{"id":17453,"library":"mcporter","title":"MCPorter","description":"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.","status":"active","version":"0.9.0","language":"javascript","source_language":"en","source_url":"https://github.com/steipete/mcporter","tags":["javascript","cli","mcp","model-context-protocol","sweetistics","typescript"],"install":[{"cmd":"npm install mcporter","lang":"bash","label":"npm"},{"cmd":"yarn add mcporter","lang":"bash","label":"yarn"},{"cmd":"pnpm add mcporter","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required Node.js runtime environment.","package":"node","optional":false}],"imports":[{"note":"MCPorter is primarily an ESM module. Use ES module `import` syntax. CJS `require` is not supported for top-level entry points.","wrong":"const createRuntime = require('mcporter')","symbol":"createRuntime","correct":"import { createRuntime } from 'mcporter'"},{"note":"This is a named export, not a default export. Ensure you destructure it from the module.","wrong":"import createServerProxy from 'mcporter'","symbol":"createServerProxy","correct":"import { createServerProxy } from 'mcporter'"},{"note":"While `CallResult` can be imported as a value, it's primarily a type. Using `import type` is recommended for clarity and tree-shaking.","wrong":"import { CallResult } from 'mcporter'","symbol":"CallResult","correct":"import type { CallResult } from 'mcporter'"},{"note":"This type represents a discovered MCP server instance. Use `import type`.","symbol":"McpServer","correct":"import type { McpServer } from 'mcporter'"}],"quickstart":{"code":"import { createRuntime, createServerProxy } from 'mcporter';\n\nasync function main() {\n  // Initialize the MCPorter runtime. It automatically discovers servers\n  // from ~/.mcporter/mcporter.json, config/mcporter.json, and editor imports.\n  const runtime = await createRuntime();\n\n  // List all discovered servers and their tools.\n  console.log('Discovered MCP servers and tools:');\n  const servers = await runtime.listServers();\n  for (const server of servers) {\n    console.log(`- ${server.id}: ${server.description || 'No description'}`);\n    const tools = await server.listTools();\n    if (tools.length > 0) {\n      console.log('  Tools:');\n      for (const tool of tools) {\n        console.log(`    - ${tool.name}: ${tool.description || 'No description'}`);\n      }\n    } else {\n      console.log('  No tools found.');\n    }\n  }\n\n  // Example: Interact with a specific server and tool.\n  // This assumes a server named 'linear' and a tool 'create_comment' exists for demonstration.\n  // Adjust server ID and tool name based on your MCPorter configuration (e.g., ~/.mcporter/mcporter.json).\n  try {\n    const linearServer = await runtime.getServer('linear');\n    if (linearServer) {\n      const linearProxy = createServerProxy(linearServer);\n      // Call the tool with strongly typed arguments.\n      const result = await linearProxy.createComment({\n        issueId: 'ENG-123',\n        body: 'Looks good from MCPorter programmatic API!',\n      });\n      console.log('\\nResult from linear.createComment:');\n      console.log(await result.markdown());\n    } else {\n      console.log('\\nServer \"linear\" not found in configuration. Skipping tool call example.');\n    }\n  } catch (error) {\n    console.error('\\nError calling tool:', error);\n    console.log('Ensure you have a \"linear\" server configured (e.g., via ~/.mcporter/mcporter.json)');\n    console.log('and that the \"create_comment\" tool exists and is accessible.');\n  }\n}\n\nmain().catch(console.error);","lang":"typescript","description":"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."},"warnings":[{"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.","message":"MCPorter `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.","severity":"breaking","affected_versions":">=0.8.0"},{"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.","message":"MCPorter `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.","severity":"gotcha","affected_versions":">=0.9.0"},{"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.","message":"OAuth credentials were centralized to `~/.mcporter/credentials.json` in `v0.7.0`. Older credential caches might become invalid or require migration.","severity":"breaking","affected_versions":">=0.7.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=0.6.0"},{"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>`.","message":"Ad-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.","severity":"gotcha","affected_versions":">=0.6.5"},{"fix":"Update scripts and documentation to use `--http-url` instead of `--sse` and `--allow-http` instead of `--insecure` for future compatibility.","message":"Legacy 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.","severity":"deprecated","affected_versions":">=0.6.5"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"The specified MCP server ID does not exist in any discovered configuration file (e.g., `~/.mcporter/mcporter.json`, `config/mcporter.json`, or editor imports).","error":"Error: Server \"my-server-name\" not found in configuration."},{"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.","cause":"The MCP server requires OAuth authentication, but no valid token is present or it has expired.","error":"Error: Auth required for server \"my-oauth-server\"."},{"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.","cause":"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.","error":"Error: Cannot find module 'mcporter' from ... (or similar CJS `require` error)"},{"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.","cause":"CLI argument parsing can be sensitive to syntax, especially with complex values, quotes, or when switching between flag-based and function-call styles.","error":"Command failed: mcporter call linear.create_comment issueId:ENG-123 body:'Looks good!'\nError: Invalid argument value for 'body': ..."}],"ecosystem":"npm","meta_description":null}