mcporter

MCPorter is a TypeScript runtime and command-line tool for discovering and calling Model Context Protocol (MCP) servers. It gives developers and coding agents the same MCP tools whether they’re working from a terminal, a script, or a generated standalone CLI — connecting to stdio, Streamable HTTP, and legacy SSE servers, and negotiating the current MCP protocol revision or an older one per server.

Beyond ad-hoc calls, it imports MCP server configs already set up in Cursor, Claude Code, Codex, Windsurf, OpenCode, and VS Code, and can generate a focused CLI or a typed TypeScript client for one specific server. A keep-alive daemon pools long-lived connections, OAuth authentication and interactive elicitation are handled for you, and MCP sessions can be recorded and replayed for reproducible testing.

What You Get

• CLI commands (list, call, resource) to discover and invoke MCP tools without writing code
• A TypeScript runtime (createRuntime, callOnce) for scripting MCP calls with connection reuse
• generate-cli and emit-ts to produce a focused CLI or typed client for one specific server
• Config import from Cursor, Claude Code, Codex, Windsurf, OpenCode, and VS Code
• OAuth authentication support with a credential vault and interactive elicitation handling
• A keep-alive daemon for pooling long-lived server connections
• Session record and replay for reproducible MCP testing

Common Use Cases

• Coding agents that need to call the same MCP tools from a terminal, a script, and a generated standalone CLI
• Developers inspecting a public or private MCP server’s available tools before wiring it into an application
• Teams generating a typed TypeScript client or focused CLI for one MCP server to hand to another team
• CI pipelines recording and replaying MCP sessions to test tool-calling logic without live network access

Under The Hood

Architecture MCPorter separates concerns across src/config (server-definition loading and normalization from JSONC files and imported client configs), src/runtime.ts plus src/runtime/ (connection lifecycle, a RuntimeConnectionCache that tracks per-server generations and retirement promises so stale connections are torn down safely under concurrent reconnects, and protocol-era negotiation between current and legacy MCP revisions), src/daemon/ (a keep-alive process that pools long-lived server connections behind a broker transport with authority validation), and src/cli/ (command parsing, help/version output, and routing layered on top of the runtime rather than duplicating it). server-proxy.ts maps MCP tool names to camelCase properties via a Proxy, giving the TypeScript API and the CLI a shared calling convention, so the CLI, the embeddable runtime, and the daemon all funnel through the same connection-cache and OAuth code paths.

Tech Stack The project is TypeScript running on Node 24+, built with tsc for the published package and an alternate bun build script for a compiled binary. The CLI is built on commander, request/response validation uses zod, config parsing accepts JSONC via jsonc-parser and TOML via @iarna/toml, and MCP protocol handling is delegated to the @modelcontextprotocol/client and @modelcontextprotocol/server packages alongside the official @modelcontextprotocol/sdk. Bundling for distributable CLIs uses rolldown. Tests run under vitest, linting under oxlint (type-aware, zero-warning), and formatting under oxfmt, with pnpm as the package manager and workspace tool.

Code Quality The repository ships an extensive test suite (over 200 test files under tests/) covering call-argument parsing, OAuth flows, Chrome DevTools relay authentication, config imports, and CLI behavior, using vitest with explicit describe/it.each cases. CI runs the full check-lint-test-build sequence across Ubuntu, macOS, and Windows on every push and pull request. Type safety is strict throughout — public APIs are exported as explicit TypeScript interfaces (RuntimeOptions, CallOptions, ServerProxyOptions) — and oxlint —type-aware —deny-warnings is enforced in the same pnpm check script used in CI and prepublishOnly, alongside oxfmt —check for formatting consistency.

API Design MCPorter’s developer experience centers on making one MCP server’s tools feel like a native TypeScript API: createServerProxy() turns arbitrary tool names into camelCase methods with predictable call signatures, while emit-ts and generate-cli let a team turn that same server into either fully-typed client code or a narrow standalone CLI without hand-writing either. Ad-hoc connections (—http-url, —stdio) mean no local configuration is required to try a public server, and elicitation handlers distinguish interactive terminal use, which can prompt for OAuth or form input, from headless and daemon use, which declines with an actionable hint instead of hanging. The record/replay feature and the Chrome DevTools relay’s credential-free loopback handoff are specific, non-generic choices that most comparable MCP tooling doesn’t offer.