MCPorter 🧳

TypeScript 运行时、CLI 和代码生成工具集，用于模型上下文协议 (Model Context Protocol)。

MCPorter 帮助您充分利用 Anthropic 的 Code Execution with MCP 指导中提到的“代码执行”工作流程：发现系统上已经配置的 MCP 服务器，直接调用它们，在 TypeScript 中组合更丰富的自动化，并在需要共享工具时创建单用途 CLI。所有这些都开箱即用——无需样板代码，无需探索模式。

主要功能

• 零配置发现。 createRuntime() 首先合并您的家目录配置 (~/.mcporter/mcporter.json[c])，然后是 config/mcporter.json，加上 Cursor/Claude/Codex/Windsurf/OpenCode/VS Code 导入，扩展 ${ENV} 占位符，并汇集连接以便在多次调用中复用传输。
• 一键 CLI 生成。 mcporter generate-cli 将任何 MCP 服务器定义转换为可运行的 CLI，带有可选捆绑/编译和元数据以方便重新生成。
• 类型化工具客户端。 mcporter emit-ts 发射 .d.ts 接口或可运行的客户端包装器，使得代理/测试可以使用强类型的 TypeScript 调用 MCP 服务器而无需手动编写管道。
• 友好的组合式 API。 createServerProxy() 将工具暴露为符合人体工程学的驼峰命名法方法，自动应用 JSON 模式的默认值，验证必需参数，并返回一个带有 .text()、.markdown()、.json() 和 .content() 辅助函数的 CallResult。
• OAuth 和标准 I/O 工程学。 内置的 OAuth 缓存、日志尾随和标准 I/O 包装器让您能够从同一接口处理 HTTP、SSE 和标准 I/O 传输。
• 临时连接。 您可以指向 CLI 的任意 MCP 端点（HTTP 或标准 I/O），无需修改配置，之后如果需要可以保存它。预期浏览器登录的托管 MCP（如 Supabase、Vercel 等）会自动检测——只需运行 mcporter auth <url>，CLI 会在运行时将定义提升为 OAuth。详情参见 docs/adhoc.md。

快速入门

MCPorter 自动发现您已经在 Cursor、Claude Code/Desktop、Codex 或本地覆盖中配置的 MCP 服务器。您可以立即使用 npx 来尝试它——无需安装。需要完整的命令参考（标志、模式、返回类型）？请查看 docs/cli-reference.md。

调用语法选项

# 用冒号分隔的标志（适合 shell）
npx mcporter call linear.create_comment issueId:ENG-123 body:'看起来不错！'

# 函数调用风格（匹配来自 `mcporter list` 的签名）
npx mcporter call 'linear.create_comment(issueId: "ENG-123", body: "看起来不错！")'

列出您的 MCP 服务器

npx mcporter list
npx mcporter list context7 --schema
npx mcporter list https://mcp.linear.app/mcp --all-parameters
npx mcporter list shadcn.io/api/mcp.getComponents           # URL + 工具后缀自动解析
npx mcporter list --stdio "bun run ./local-server.ts" --env TOKEN=xyz

• 添加 --json 以输出机器可读的摘要，包括每个服务器的状态（认证/离线/HTTP/错误计数），以及单个服务器运行时的完整工具模式负载。
• 添加 --verbose 以显示注册服务器名称的所有配置来源（主要来源优先），并在文本和 JSON 列表输出中显示。

现在您可以将 mcporter list 指向临时服务器：直接提供 URL 或使用新的 --http-url/--stdio 标志（加上 --env、--cwd、--name 或 --persist）来描述任何 MCP 端点。直到您持久化该定义之前，您仍然需要重复相同的 URL/标准 I/O 标志给 mcporter call——只有当您通过 --persist 或 mcporter config add（使用 --scope home|project 选择写目标）将其合并到配置中时，打印的 slug 才能被复用。随后运行 mcporter auth https://…（或相同的标志集）完成 OAuth 而无需编辑配置。完整细节参见 docs/adhoc.md。

单个服务器列表现在像 TypeScript 头文件一样读取，因此您可以直接复制粘贴签名到 mcporter call：

linear - 托管的 Linear MCP；公开问题搜索、创建和工作流工具。
  23 个工具 · 1654 毫秒 · HTTP https://mcp.linear.app/mcp

  /**
   * 在特定的 Linear 问题上创建评论
   * @param issueId 问题 ID
   * @param body 评论内容作为 Markdown
   * @param parentId? 回复的父评论 ID
   */
  function create_comment(issueId: string, body: string, parentId?: string);
  // 可选 (3): notifySubscribers, labelIds, mentionIds

  /**
   * 列出用户 Linear 工作区中的文档
   * @param query? 可选的搜索查询
   * @param projectId? 按项目 ID 过滤
   */
  function list_documents(query?: string, projectId?: string);
  // 可选 (11): limit, before, after, orderBy, initiativeId, ...

这是您运行 npx mcporter list vercel 时 Vercel 的样子：

vercel - Vercel MCP（需要 OAuth）。

  /**
   * 搜索 Vercel 文档。
   * 使用此工具回答有关 Vercel 平台、功能和最佳实践的问题，
   * 包括：
   * - 核心概念：项目、部署、Git 集成、预览部署、环境
   * - 前端与框架：Next.js、SvelteKit、Nuxt、Astro、Remix、框架配置和优化
   * - API：REST API、Vercel SDK、构建输出 API
   * - 计算：Fluid Compute、函数、路由中间件、Cron 作业、OG 图片生成、沙盒、数据缓存
   * - AI：Vercel AI SDK、AI 网关、MCP、v0
   * - 性能与交付：边缘网络、缓存、CDN、图片优化、标头、重定向、重写
   * - 定价：计划、支出管理、账单
   * - 安全：审计日志、防火墙、机器人管理、BotID、OIDC、RBAC、安全计算、双因素认证
   * - 存储：博客、边缘配置
   *
   * @param topic 聚焦文档搜索的主题（例如，“路由”，“数据获取”）。
   * @param tokens? 结果中包含的最大标记数，默认为 2500。
   */
  function search_vercel_documentation(topic: string, tokens?: number);

  /**
   * 将当前项目部署到 Vercel
   */
  function deploy_to_vercel();

所需参数始终显示；除非有仅一两个可选参数且少于四个必需字段，或者您传递了 --all-parameters，否则可选参数将隐藏。每当 MCPorter 隐藏参数时，它都会打印 隐藏了可选参数；使用 --all-parameters 查看所有字段。，这样您就知道如何揭示完整签名。返回类型根据工具模式的 title 推断，如果无法推断则完全省略后缀。

Context7：获取文档（无需认证）

npx mcporter call context7.resolve-library-id libraryName=react
npx mcporter call context7.get-library-docs context7CompatibleLibraryID=/websites/react topic=hooks

Linear：搜索文档（需要 LINEAR_API_KEY）

LINEAR_API_KEY=sk_linear_example npx mcporter call linear.search_documentation query="自动化"

Chrome DevTools：快照当前标签页

npx mcporter call chrome-devtools.take_snapshot
npx mcporter call 'linear.create_comment(issueId: "LNR-123", body: "你好世界")'
npx mcporter call https://mcp.linear.app/mcp.list_issues assignee=me
npx mcporter call shadcn.io/api/mcp.getComponent component=vortex   # 协议可选；默认为 https
npx mcporter call linear.listIssues --tool listIssues   # 自动纠正为 list_issues
npx mcporter linear.list_issues                         # 简写：推断 `call`
VERCEL_ACCESS_TOKEN=sk_vercel_example npx mcporter call "npx -y vercel-domains-mcp" domain=answeroverflow.com  # 引用标准 I/O 命令 + 单工具推断

工具调用理解类似 JavaScript 的调用语法，自动纠正接近的工具名称，并发出更丰富的内联使用提示。参见 docs/call-syntax.md 了解语法和 docs/call-heuristic.md 了解自动纠正规则。

有用的标志：

• --config <path> -- 自定义配置文件（默认为 ./config/mcporter.json）。
• --root <path> -- 标准 I/O 命令的工作目录。
• --log-level <debug|info|warn|error> -- 调整详细程度（尊重 MCPORTER_LOG_LEVEL）。
• --oauth-timeout <ms> -- 缩短/延长 OAuth 浏览器等待时间；同 MCPORTER_OAUTH_TIMEOUT_MS / MCPORTER_OAUTH_TIMEOUT。
• --tail-log -- 流式输出工具响应中引用的任何日志文件的最后一行。
• --output <format> 或 --raw -- 控制格式化输出（默认为自动检测的漂亮打印）。
• --json（在 mcporter list 上）-- 输出 JSON 摘要/计数而不是文本。多服务器运行报告每个服务器的状态、计数和连接问题；单服务器运行包括完整的工具元数据。
• --output json/raw（在 mcporter call 上）-- 当连接失败时，MCPorter 打印通常的颜色化提示并同时发出结构化的 { server, tool, issue } 封装，以便脚本可以程序化地处理认证/离线/HTTP 错误。
• --json（在 mcporter auth 上）-- 每当 OAuth/传输设置失败时，发出相同的结构化连接封装，而不是抛出错误。
• --json（在 mcporter emit-ts 上）-- 打印描述生成文件的 JSON 摘要（模式 + 输出路径）而不是文本日志——在脚本内部生成工件时非常有用。
• --all-parameters -- 列出服务器时显示每个模式字段（默认输出至少显示五个参数及其余部分的摘要）。
• --http-url <https://…> / --stdio "command …" -- 行内描述临时 MCP 服务器。STDIO 传输现在自动继承您当前的 shell 环境；仅在需要注入/覆盖变量时添加 --env KEY=value，以及 --cwd、--name 或 --persist <config.json>。这些标志现在也适用于 mcporter auth，所以 mcporter auth https://mcp.example.com/mcp 直接生效。
• 对于受 OAuth 保护的服务器，如 vercel，只需运行一次 npx mcporter auth vercel 完成登录。

提示：您可以完全跳过动词——mcporter firecrawl 自动运行 mcporter list firecrawl，带点的令牌如 mcporter linear.list_issues 分派到调用命令（包括拼写修正）。

超时默认为 30 秒；如果您预计启动缓慢，请使用 MCPORTER_LIST_TIMEOUT 或 MCPORTER_CALL_TIMEOUT 覆盖。OAuth 浏览器握手单独获得 60 秒宽限期；当您需要 CLI 更快地退出以诊断顽固的认证流程时，传递 --oauth-timeout <ms>（或导出 MCPORTER_OAUTH_TIMEOUT_MS）。

不编辑配置即可尝试 MCP

# 直接指向 HTTPS MCP 服务器
npx mcporter list --http-url https://mcp.linear.app/mcp --name linear

# 通过 Bun 运行本地标准 I/O MCP 服务器
npx mcporter call --stdio "bun run ./local-server.ts" --name local-tools

• 添加 --persist config/mcporter.local.json 以保存推断的定义供未来运行使用。
• 如果您确实需要访问明文端点，请使用 --allow-http。
• 详情参见 docs/adhoc.md（环境覆盖、当前工作目录、OAuth）。

使用守护进程保持 MCP 服务器活跃

• chrome-devtools、mobile-mcp 和其他有状态的标准 I/O 服务器首次调用时会自动启动每个登录的守护进程，以便 Chrome 标签页和设备会话在代理之间保持活跃。
• 使用 mcporter daemon status 检查守护进程是否正在运行（以及哪些服务器已连接）。
• 任何时候都可以通过 mcporter daemon stop 停止它，通过 mcporter daemon start 预热，或在调整配置/环境后通过 mcporter daemon restart 重启。
• 其他所有服务器都是临时的；当您希望守护进程管理它时，在服务器条目中添加 "lifecycle": "keep-alive"（或设置 MCPORTER_KEEPALIVE=name）。您也可以设置 "lifecycle": "ephemeral"（或 MCPORTER_DISABLE_KEEPALIVE=name）以选择退出。
• 守护进程仅管理来自您的配置/导入的命名服务器。通过 --stdio …、--http-url … 或行内函数调用语法调用的临时 STDIO/HTTP 目标今天仍然是进程内的；如果需要它们参与共享守护进程，请将它们持久化到 config/mcporter.json（或使用 --persist）。
• 故障排除？运行 mcporter daemon start --log（或 --log-file /tmp/daemon.log）将 stdout/stderr tee 到文件中，并在仅需特定 MCP 的调用跟踪时添加 --log-servers chrome-devtools。每个服务器配置还可以设置 "logging": { "daemon": { "enabled": true } } 以强制详细记录该条目。

更友好的工具调用

• 函数调用语法。 您可以调用工具为 mcporter call 'linear.create_issue(title: "Bug", team: "ENG")'，而不是处理 --flag value。解析器支持嵌套对象/数组，允许您在依赖模式顺序时省略标签（例如 mcporter 'context7.resolve-library-id("react")'），并清晰地呈现模式验证错误。深入参见 docs/call-syntax.md。
• 标志简写仍有效。 偏好 CLI 样式的参数？坚持使用 mcporter linear.create_issue title=value team=value、title=value、title:value 或甚至 title: value——CLI 现在规范化所有三种形式。
• 快捷指南。 参见 docs/tool-calling.md 了解每种支持的调用风格（自动推断动词、标志、函数调用和临时 URL）的快速比较。
• 自动纠正。 如果您拼错了工具名称，MCPorter 会检查服务器的工具目录，当编辑距离很小时重试，并在其他情况下打印 您是指……？ 提示。启发式算法（以及如何调整它）捕获在 docs/call-heuristic.md。
• 更丰富的单服务器输出。 mcporter list <server> 现在打印 TypeScript 样式的签名、内联注释、返回形状提示和反映新调用语法的命令示例。默认情况下，可选参数保持隐藏——每次需要完整 JSON 模式时添加 --all-parameters 或 --schema。

安装

使用 npx 立即运行

npx mcporter list

添加到您的项目

pnpm add mcporter

Homebrew (steipete/tap)

brew tap steipete/tap
brew install steipete/tap/mcporter

该 tap 与 MCPorter 0.3.2 一起发布。如果您遇到旧版 tap 安装的问题，请在重新安装前运行 brew update。

从代码中一次性调用

import { callOnce } from "mcporter";

const result = await callOnce({
	server: "firecrawl",
	toolName: "crawl",
	args: { url: "https://anthropic.com" },
});

console.log(result); // 原始 MCP 封装

callOnce 自动发现所选服务器（包括 Cursor/Claude/Codex/Windsurf/OpenCode/VS Code 导入），处理 OAuth 提示，并在完成后关闭传输。它非常适合手动运行或将 MCPorter 直接集成到代理工具钩子中。

使用运行时组合自动化

import { createRuntime } from "mcporter";

const runtime = await createRuntime();

const tools = await runtime.listTools("context7");
const result = await runtime.callTool("context7", "resolve-library-id", {
	args: { libraryName: "react" },
});

console.log(result); // 默认情况下自动打印 JSON/text，因为 CLI 默认漂亮打印
await runtime.close(); // 关闭传输和 OAuth 会话

当您需要连接池、重复调用或高级选项（如显式超时和日志流）时，请使用 createRuntime()。运行时复用传输，刷新 OAuth 令牌