Connecting servers

mcporter Overview

GitHub Edit page

mcporter Overview

mcporter is a CLI and TypeScript runtime for the Model Context Protocol (MCP). It wraps the upstream TypeScript SDK with:

  • Runtime orchestration – createRuntime loads servers from config JSON, editor imports, or ad-hoc flags and handles OAuth retries, transport promotion, and cleanup.
  • CLI surfaces – mcporter list, mcporter call, mcporter generate-cli, mcporter emit-ts, and mcporter inspect-cli expose the runtime features to humans and scripts.
  • Tooling helpers – createServerProxy maps MCP tools to camelCase methods for Node/Bun scripts and returns CallResult helpers (.text(), .markdown(), .json()).

#Primary Commands

  • npx mcporter list [server|--http-url|--stdio]

    • Lists tool metadata, renders TypeScript-style signatures, and surfaces copy/pasteable examples (including ad-hoc HTTP selectors).

  • npx mcporter call server.tool key=value …

    • Invokes a tool via either flag syntax or the function-call expression form; add --output json to capture structured responses.

  • npx mcporter resource server [uri]

    • Lists MCP resources for a server, or reads a specific resource URI and renders text/markdown/JSON/raw output.

  • npx mcporter generate-cli --server name [--bundle|--compile]

    • Emits a standalone CLI for a single MCP server. Bundling defaults to Rolldown unless the runtime resolves to Bun; compiled binaries require Bun.

  • npx mcporter emit-ts <server> --mode types|client

    • Produces .d.ts files or typed client factories that mirror the CLI schema output.

  • npx mcporter inspect-cli dist/server.js

    • Reads embedded metadata so you can regenerate a CLI without guesswork.

#Runtime Helpers

Use createServerProxy(runtime, name) inside scripts when you want ergonomic camelCase calls instead of kebab-case tool names. The proxy:

  1. Validates arguments against the MCP schema.
  2. Automatically merges default values.
  3. Returns a CallResult helper so you can render .text(), .markdown(), or .json() without manual parsing.

If tool discovery fails, unambiguous named argument objects still reach the tool. Use an explicit { args: { ... }, timeoutMs: 1000 } envelope when argument names overlap with runtime options.

The .json() helper retains JSON null entries alongside other parsed content and gives an explicit structured JSON null precedence over fallback text.

When you need raw access (custom transports, streaming), use the bare Client from @modelcontextprotocol/client or inspect runtime.connect(name) for lower-level control. Headless callers that must rely on cached tokens without launching OAuth can pass disableOAuth: true to connect, callTool, listTools, resource helpers, and callOnce; this suppresses interactive OAuth while keeping eligible connections pooled.

#Debug + Support Docs

  • Ad-hoc MCP Servers (docs/adhoc.md) – explains the --http-url / --stdio flags.
  • Tool Calling Cheatsheet (docs/tool-calling.md) – shows the two argument styles and when to use each.
  • Hang Diagnostics (docs/hang-debug.md + docs/tmux.md) – run long-lived commands inside tmux and dump active handles if shutdown stalls.

Read these docs (via pnpm run docs:list) whenever your task touches the corresponding area. They contain the up-to-date project guidance.