Registry / llm-agents / mcporter

mcporter

JSON →
library0.9.0jsnpmunverified

MCPorter is a TypeScript runtime and CLI tool designed to facilitate interaction with Model Context Protocol (MCP) servers. It provides capabilities for zero-configuration discovery of MCP servers across various environments (local files, editors like Cursor/Claude/VS Code), one-command CLI generation for any server definition, and the creation of strongly typed tool clients. The library offers a composable API for programmatic access, handling aspects like OAuth caching, log tailing, and different transport mechanisms (HTTP, SSE, stdio). Currently at version `0.9.0`, MCPorter maintains a rapid release cadence, indicated by frequent minor and patch updates, continuously enhancing its functionality for 'code execution' workflows as envisioned by the Model Context Protocol. Its key differentiators include automated config merging, ergonomic API wrappers that apply JSON-schema defaults and validation, and robust support for ad-hoc and OAuth-backed connections.

npm install mcporter
INSTALL
IMPORT
SIG · MCPORTER
M
mcporter
llm-agentsjavascriptv0.9.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

createRuntime
import { createRuntime } from 'mcporter'
const createRuntime = require('mcporter')
MCPorter is primarily an ESM module. Use ES module `import` syntax. CJS `require` is not supported for top-level entry points.
createServerProxy
import { createServerProxy } from 'mcporter'
import createServerProxy from 'mcporter'
This is a named export, not a default export. Ensure you destructure it from the module.
CallResult
import type { CallResult } from 'mcporter'
import { CallResult } from 'mcporter'
While `CallResult` can be imported as a value, it's primarily a type. Using `import type` is recommended for clarity and tree-shaking.
McpServer
import type { McpServer } from 'mcporter'
This type represents a discovered MCP server instance. Use `import type`.

This quickstart demonstrates how to programmatically discover MCP servers and tools, and invoke a tool using the `createRuntime` and `createServerProxy` APIs. It lists all configured servers and then attempts to call a hypothetical `linear.createComment` tool, handling potential configuration issues.

import { createRuntime, createServerProxy } from 'mcporter'; async function main() { // Initialize the MCPorter runtime. It automatically discovers servers // from ~/.mcporter/mcporter.json, config/mcporter.json, and editor imports. const runtime = await createRuntime(); // List all discovered servers and their tools. console.log('Discovered MCP servers and tools:'); const servers = await runtime.listServers(); for (const server of servers) { console.log(`- ${server.id}: ${server.description || 'No description'}`); const tools = await server.listTools(); if (tools.length > 0) { console.log(' Tools:'); for (const tool of tools) { console.log(` - ${tool.name}: ${tool.description || 'No description'}`); } } else { console.log(' No tools found.'); } } // Example: Interact with a specific server and tool. // This assumes a server named 'linear' and a tool 'create_comment' exists for demonstration. // Adjust server ID and tool name based on your MCPorter configuration (e.g., ~/.mcporter/mcporter.json). try { const linearServer = await runtime.getServer('linear'); if (linearServer) { const linearProxy = createServerProxy(linearServer); // Call the tool with strongly typed arguments. const result = await linearProxy.createComment({ issueId: 'ENG-123', body: 'Looks good from MCPorter programmatic API!', }); console.log('\nResult from linear.createComment:'); console.log(await result.markdown()); } else { console.log('\nServer "linear" not found in configuration. Skipping tool call example.'); } } catch (error) { console.error('\nError calling tool:', error); console.log('Ensure you have a "linear" server configured (e.g., via ~/.mcporter/mcporter.json)'); console.log('and that the "create_comment" tool exists and is accessible.'); } } main().catch(console.error);
mcporter --version
Debug
Known issues
breakingMCPorter `v0.8.0` introduced changes to how static `Authorization` headers are handled once OAuth is active. Imported editor configurations can no longer override fresh OAuth tokens, which might break workflows relying on statically defined headers overriding dynamic tokens.
fix
Review configurations where static `Authorization` headers are present. For OAuth-backed servers, ensure token management is handled through MCPorter's OAuth flows or explicitly clear cached tokens if issues arise.
affects: >=0.8.0
gotchaMCPorter `v0.9.0` added per-server exact-name tool filtering via `allowedTools` and `blockedTools` in configuration. If tools unexpectedly disappear or calls fail, verify these new filtering options in your `mcporter.json` files.
fix
Check your `mcporter.json` configurations for `allowedTools` or `blockedTools` arrays under server definitions. Adjust them to ensure desired tools are not unintentionally filtered out.
affects: >=0.9.0
breakingOAuth credentials were centralized to `~/.mcporter/credentials.json` in `v0.7.0`. Older credential caches might become invalid or require migration.
fix
If experiencing OAuth issues after upgrading, use `mcporter auth --reset` to clear corrupted caches and re-authenticate. MCPorter should attempt auto-migration, but manual reset can resolve stubborn issues.
affects: >=0.7.0
gotchaThe CLI supports multiple call syntaxes, including colon-delimited flags (`issueId:ENG-123`) and function-call style (`linear.create_comment(issueId: "ENG-123")`). Inconsistent usage or special characters in arguments can lead to parsing errors.
fix
For complex arguments or those containing spaces/special characters, prefer the function-call style with proper quoting, or use `--args '{"key":"value"}'` for JSON payloads. Refer to `mcporter call --help` or `docs/call-syntax.md` for details.
affects: >=0.6.0
gotchaAd-hoc server connections via CLI flags like `--http-url` or `--stdio` are ephemeral by default. If you intend to reuse them, they must be explicitly persisted.
fix
To persist an ad-hoc server definition, add `--persist <path/to/config.json>` to your `mcporter list` or `mcporter config add` command. For OAuth with ad-hoc servers, use `mcporter auth <url>` or `mcporter config login <url>`.
affects: >=0.6.5
deprecatedLegacy ad-hoc flags `--sse` and `--insecure` have been aliased to `--http-url` and `--allow-http` respectively in `v0.6.5`. While still functional, prefer the newer, more descriptive flags.
fix
Update scripts and documentation to use `--http-url` instead of `--sse` and `--allow-http` instead of `--insecure` for future compatibility.
affects: >=0.6.5
Errors
Common errors & fixes
Error: Server "my-server-name" not found in configuration.
The specified MCP server ID does not exist in any discovered configuration file (e.g., `~/.mcporter/mcporter.json`, `config/mcporter.json`, or editor imports).
fix
Verify the server ID is correct. Run `npx mcporter list` to see available servers. If the server is external or ad-hoc, ensure it's properly added using `mcporter config add` or specified via ad-hoc CLI flags.
Error: Auth required for server "my-oauth-server".
The MCP server requires OAuth authentication, but no valid token is present or it has expired.
fix
Run `npx mcporter auth my-oauth-server` to initiate the OAuth flow in your browser. If issues persist, try `npx mcporter auth my-oauth-server --reset` to clear existing credentials.
Error: Cannot find module 'mcporter' from ... (or similar CJS `require` error)
MCPorter is primarily distributed as an ES Module, and direct `require()` calls in a CommonJS environment might fail, especially in newer Node.js versions or without proper transpilation.
fix
Ensure your project is configured for ES Modules (e.g., `"type": "module"` in `package.json`) and use `import { ... } from 'mcporter';` syntax. If you must use CommonJS, consider dynamic `import('mcporter')` or a build step to transpile.
Command failed: mcporter call linear.create_comment issueId:ENG-123 body:'Looks good!' Error: Invalid argument value for 'body': ...
CLI argument parsing can be sensitive to syntax, especially with complex values, quotes, or when switching between flag-based and function-call styles.
fix
Review the specific error message for argument type/format mismatch. Ensure proper quoting for string values, especially those with spaces. Consider using the function-call syntax with explicit string literals or `--args` for JSON objects. Run `mcporter list <server> --schema` for expected argument types.
Upgrade
Version history
0.9.0latest on npm
Audit
Dependencies
noderequiredRequired Node.js runtime environment.
Agent activity
27 hits · last 30 days
node
26
OpenAI (training)
1
Resources
mcporter — npm install mcporter · libregistry