MCPorter 🧳 - 从 TypeScript 调用 MCP 或作为 CLI 使用

用于模型上下文协议的 TypeScript 运行时、CLI 和代码生成工具包。

MCPorter 帮助您充分利用 Anthropic 的 使用 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 接口或可以直接使用的客户端封装，使代理或测试能够以强类型的方式调用 MCP 服务器，而无需手动编写底层逻辑。
• 友好且可组合的 API。 createServerProxy() 将工具暴露为符合人体工学的驼峰命名法方法，自动应用 JSON Schema 默认值，验证必填参数，并返回包含 .text()、.markdown()、.json()、.images() 和 .content() 辅助方法的 CallResult 对象。
• OAuth 和 stdio 的便捷性。 内置的 OAuth 缓存、日志尾随和 stdio 包装器，让您可以通过同一接口处理 HTTP、SSE 和 stdio 传输。
• 临时连接。 您可以将 CLI 指向 任意 MCP 端点（HTTP 或 stdio），无需修改配置；如果需要，稍后再将其持久化保存。对于需要浏览器登录的托管 MCP（如 Supabase、Vercel 等），CLI 会自动检测——只需运行 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:'Looks good!'

# 函数调用风格（与 `mcporter list` 中的签名一致）
npx mcporter call 'linear.create_comment(issueId: "ENG-123", body: "Looks good!")'

# 以 `--` 开头的字面位置参数
npx mcporter call server.tool -- --raw-value

列出你的 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 错误次数）以及单服务器运行时的完整工具 Schema 负载。
• 添加 --verbose 可以显示注册该服务器名称的所有配置来源（优先显示主要来源），无论是在文本输出还是 JSON 列表中。

现在你可以将 mcporter list 指向临时服务器：直接提供一个 URL，或者使用新的 --http-url/--stdio 标志（加上 --env、--cwd、--name 或 --persist）来描述任意 MCP 端点。在你保存该定义之前，每次使用 mcporter call 时仍需重复相同的 URL 或 stdio 标志——只有通过 --persist 或 mcporter config add 将其合并到配置中，打印出来的 slug 才能被重复使用（使用 --scope home|project 来选择写入目标）。随后可以运行 mcporter auth https://…（或使用相同的标志集）来完成 OAuth 流程，而无需编辑配置文件。完整详情请参阅 docs/adhoc.md。

单服务器的列表现在看起来就像一个 TypeScript 头文件，你可以直接将签名复制粘贴到 mcporter call 中：

linear - 托管于 Linear 的 MCP；提供问题搜索、创建及工作流工具。
  23 个工具 · 1654ms · 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、函数、路由中间件、定时任务、OG 图像生成、沙盒、数据缓存
   * - AI：Vercel AI SDK、AI Gateway、MCP、v0
   * - 性能与交付：边缘网络、缓存、CDN、图像优化、头部信息、重定向与重写
   * - 定价：套餐、支出管理、计费
   * - 安全：审计日志、防火墙、机器人管理、BotID、OIDC、RBAC、安全计算、双因素认证
   * - 存储：博客、边缘配置
   *
   * @param topic 文档搜索的重点主题（例如“路由”、“数据获取”）。
   * @param tokens? 结果中包含的最大 token 数量。默认为 2500。
   */
  function search_vercel_documentation(topic: string, tokens?: number);

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

必填参数始终显示；可选参数则默认隐藏，除非满足以下条件之一：(a) 可选参数仅有一两个，且必填字段少于四个；或者 (b) 你使用了 --all-parameters 标志。每当 MCPorter 隐藏参数时，它都会打印一条提示：“可选参数已隐藏；使用 --all-parameters 查看所有字段。”这样你就知道如何展开完整的参数列表。返回值类型会根据工具 Schema 中的 title 自动推断，如果无法确定，则直接省略返回值类型，而不是进行猜测。

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

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

Linear：搜索文档（需要设置 LINEAR_API_KEY）

LINEAR_API_KEY=sk_linear_example npx mcporter call linear.search_documentation query="automations"

Chrome 开发者工具：截取当前标签页快照

npx mcporter call chrome-devtools.take_snapshot
npx mcporter call 'linear.create_comment(issueId: "LNR-123", body: "Hello world")'
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  # 引号内的标准输入命令 + 单一工具推断

工具调用理解类似 JavaScript 的调用语法，会自动纠正拼写接近的工具名称，并提供更丰富的内联使用提示。有关语法，请参阅 docs/call-syntax.md，关于自动纠正规则，请参阅 docs/call-heuristic.md。

有用的标志：

• --config <path> -- 自定义配置文件（默认为 ./config/mcporter.json）。
• --root <path> -- 标准输入命令的工作目录。
• --log-level <debug|info|warn|error> -- 调整日志详细程度（优先级高于 MCPORTER_LOG_LEVEL）。
• --oauth-timeout <ms> -- 缩短或延长 OAuth 浏览器等待时间；等同于 MCPORTER_OAUTH_TIMEOUT_MS 或 MCPORTER_OAUTH_TIMEOUT。
• --tail-log -- 流式输出工具响应中引用的任何日志文件的最后 20 行。
• --output <format> 或 --raw -- 控制格式化输出（默认为自动检测并美化输出）。
• --save-images <dir>（在 mcporter call 中）-- 将 MCP 图像内容块保存到指定目录下的文件中（需手动启用；标准输出格式保持不变）。
• --raw-strings（在 mcporter call 中）-- 将看起来像数字的参数值（对于 key=value、key:value 和尾随位置参数）保留为字符串。
• --no-coerce（在 mcporter call 中）-- 将所有 key=value 和位置参数保留为原始字符串（禁用布尔值/空值/数字/JSON 的强制转换）。
• --（在 mcporter call 中）-- 停止标志解析，使剩余的标记作为字面量位置参数，即使它们以 -- 开头。
• --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 服务器。标准输入传输现在会自动继承当前的 Shell 环境；只有当需要与 --cwd、--name 或 --persist <config.json> 一起注入/覆盖变量时，才添加 --env KEY=value。这些标志现在也适用于 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 运行本地标准输入 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 等有状态的标准输入服务器会在您首次调用它们时自动启动一个基于登录的守护进程，从而使 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 重定向到文件，并添加 --log-servers chrome-devtools 以仅获取特定 MCP 的调用轨迹。每个服务器的配置也可以设置 "logging": { "daemon": { "enabled": true } }，以强制对该条目进行详细日志记录。

更友好的工具调用

• 函数调用语法。 不再需要纠结于 --flag value，你可以直接以 mcporter call 'linear.create_issue(title: "Bug", team: "ENG")' 的方式调用工具。解析器支持嵌套对象/数组，在依赖 Schema 顺序时可省略标签（例如 mcporter 'context7.resolve-library-id("react")'），并清晰地展示 Schema 验证错误。详细内容请参阅 docs/call-syntax.md。
• 短横线形式的标志仍有效。 倾向于使用 CLI 风格的参数吗？可以继续使用 mcporter linear.create_issue title=value team=value、title=value、title:value，甚至 title: value——CLI 现在会将这三种形式统一处理。
• 未知的长标志会快速报错。 mcporter call server.tool --source import 现在会报错，而不会将 --source 默默转换为位置参数。请改用 source=import、--args '{"source":"import"}'，或在以 -- 开头的字面量位置参数前插入 --。
• 速查表。 请参阅 docs/tool-calling.md，其中对比了所有支持的调用方式（自动推断的动词、标志、函数调用以及自定义 URL）。
• 自动更正。 如果你拼错了工具名称，MCPorter 会检查服务器的工具目录，在编辑距离很小的情况下重试，否则会提示“您是不是想说……？”该启发式方法及其调整方式记录在 docs/call-heuristic.md 中。
• 单服务器输出更丰富。 mcporter list <server> 现在会打印 TypeScript 风格的签名、内联注释、返回值结构提示以及与新调用语法一致的命令示例。可选参数默认隐藏——如需完整 JSON Schema，可添加 --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/文本，因为 CLI 默认会美化输出
await runtime.close(); // 关闭传输连接和 OAuth 会话

当你需要连接池、重复调用，或高级选项如显式超时和日志流式传输时，就使用 createRuntime()。运行时会复用传输连接，刷新 OAuth 令牌，只有在调用 runtime.close() 时才会彻底关闭所有资源。

在代码中组合工具

运行时 API 专为代理和脚本设计，而不仅仅是供终端用户使用。

import { createRuntime, createServerProxy } from "mcporter";

const runtime = await createRuntime();
const chrome = createServerProxy(runtime, "chrome-devtools");
const linear = createServerProxy(runtime, "linear");

const snapshot = await chrome.takeSnapshot();
console.log(snapshot.text());

const docs = await linear.searchDocumentation({
	query: "automations",
	page: 0,
});
console.log(docs.json());

代理和结果辅助函数内置友好的人机交互设计：

• 属性名从驼峰式映射到短横线分隔的工具名称（takeSnapshot -> take_snapshot）。
• 位置参数会自动映射到 Schema 必填字段，而选项对象则遵循 JSON Schema 默认值。
• 结果会被封装在 CallResult 中，因此你可以选择 .text()、.markdown()、.json()、.images()、.content()，或者在需要完整包裹时访问 .raw。
• 当你需要对参数、元数据或流式传输选项进行显式控制时，可以直接调用 runtime.callTool()。

随时运行 mcporter list <server>，即可获取 TypeScript 风格的签名、可选参数提示以及与 CLI 函数调用语法匹配的示例调用。

生成独立 CLI

将任何服务器定义转换为可共享的 CLI 工具：

npx mcporter generate-cli \
  --command https://mcp.context7.com/mcp

# 输出：
#   context7.ts        （嵌入 Schema 的 TypeScript 模板）
#   context7.js        （根据运行时环境通过 Rolldown 或 Bun 打包的 CLI）

可以通过这个小技巧将 chrome-devtools MCP 转换为 CLI：

npx mcporter generate-cli --command "npx -y chrome-devtools-mcp@latest"

提示：当内联命令是第一个位置参数时，可以省略 --command（例如 npx mcporter generate-cli "npx -y chrome-devtools-mcp@latest"）。

• --name 可覆盖推断出的 CLI 名称。
• 如果希望在生成的帮助输出中显示自定义摘要，可添加 --description "..."（否则，mcporter 会在生成过程中向 MCP 服务器请求其描述或标题）。
• 生成的 CLI 继承了与 mcporter 相同的彩色帮助布局：不带参数调用二进制文件会显示嵌入的工具列表及快速入门指南，而每个 --help 页面在标准输出为 TTY 时都会使用粗体标题和浅色描述。
• 添加 --bundle [path] 可同时输出打包文件（目标 Node.js 时使用 Rolldown，运行时确定为 Bun 时则自动使用 Bun；可通过 --bundler rolldown|bun 强制指定）。
• --output <path> 可将模板输出到特定路径。
• --runtime bun|node 可选择生成代码的运行时环境（--compile 需要 Bun 运行时）。
• 添加 --compile 可生成经过 Bun 编译的二进制文件；若不指定 --bundle，MCPorter 会清理中间打包文件。
• 使用 --include-tools a,b,c 或 --exclude-tools a,b,c 可为部分工具生成 CLI（二者互斥）。
• 使用 --from <artifact>（可选 --dry-run）可根据现有 CLI 的嵌入元数据重新生成。
• 如果服务器已存在于你的配置或导入中，建议使用位置简写形式：npx mcporter generate-cli linear --bundle dist/linear.js。
• --server/--command 接受 HTTP URL、可选的 .tool 后缀，甚至无协议的主机名（shadcn.io/api/mcp.getComponents）。

每个工件都嵌入了再生元数据（生成器版本、解析后的服务器定义、调用参数）。使用以下命令：

npx mcporter inspect-cli dist/context7.js     # 人类可读的摘要
npx mcporter generate-cli --from dist/context7.js  # 使用最新 mcporter 重新生成

生成类型化客户端

当您需要强类型的工具支持，但又不想打包完整的 CLI 时，可以使用 mcporter emit-ts。它复用了与 mcporter list 相同的签名和文档块，因此生成的类型定义文件会始终与 CLI 的输出保持同步。

# 仅类型接口（Promise 签名）
npx mcporter emit-ts linear --out types/linear-tools.d.ts

# 客户端封装（在 .d.ts 文件旁边创建一个可重用的代理工厂）
npx mcporter emit-ts linear --mode client --out clients/linear.ts

• --mode types（默认）会生成一个 .d.ts 接口文件，您可以将其导入到任何地方。
• --mode client 会同时生成 .d.ts 文件和一个 .ts 辅助文件，该文件为您封装了 createRuntime 和 createServerProxy。
• 如果希望所有可选字段都明确列出，请添加 --include-optional 标志（这与 mcporter list --all-parameters 的行为一致）。
• 在脚本中使用 emit-ts 时，添加 --json 标志可以输出结构化的摘要信息（包括模式和输出路径），而不是纯文本日志。
• <server> 参数也支持 HTTP URL 和带有 .tool 后缀或缺少协议的 URL，其行为与主 CLI 一致。

完整标志参考以及生成文件的内联快照，请参阅 docs/emit-ts.md。

配置参考

如果您不想手动编辑 JSON 文件，可以使用 mcporter config list|get|add|remove|import 来管理此文件；完整操作指南请参阅 docs/config.md。配置文件以 JSONC 格式解析，因此在 mcporter.json 和 mcporter.jsonc 中都支持行内 // 和 /* ... */ 注释，以及尾随逗号。

使用 mcporter config 管理配置

通过您的包管理器（pnpm、npm、npx 等）运行 mcporter config … 命令，即可获得项目 MCP 的交互式视图：

• config list 默认仅显示本地条目，并在 TTY 终端上打印其他所有配置文件（Cursor、Claude、Windsurf、VS Code 等）的摘要信息，包括计数和示例名称。添加 --source import 可直接查看导入的条目，或使用 --json 进行脚本化。
• config get/remove/logout 复用了 mcporter list/call 中的模糊匹配逻辑，因此像 sshadcn 这样的拼写错误会自动更正为 shadcn（并显示一条浅色提示），而模糊名称则会提示“您是否想输入……？”。
• config import <kind> --copy 会将编辑器管理的条目导入到 config/mcporter.json 中，使您可以在本地对其进行自定义或移除，而无需修改上游文件。
• 每个子命令都支持 --config <path> 和 --root <dir> 选项，方便您切换多个项目配置或工作区特定的覆盖设置。

config/mcporter.json 的结构与 Cursor/Claude 的配置相同：

{
	"mcpServers": {
		"context7": {
			"description": "Context7 文档 MCP",
			"baseUrl": "https://mcp.context7.com/mcp",
			"headers": {
				"Authorization": "$env:CONTEXT7_API_KEY"
			}
		},
		"chrome-devtools": {
			"command": "npx",
			"args": ["-y", "chrome-devtools-mcp@latest"],
			"env": { "npm_config_loglevel": "error" }
		}
	},
	"imports": ["cursor", "claude-code", "claude-desktop", "codex", "windsurf", "opencode", "vscode"]
}

MCPorter 为您处理以下内容：

• 对标头和环境变量条目进行 ${VAR}、${VAR:-fallback} 和 $env:VAR 替换。
• 自动缓存 OAuth 令牌至 ~/.mcporter/<server>/ 目录下，除非您覆盖了 tokenCacheDir 设置。
• 标准输入输出命令会继承定义它们的文件所在的目录（无论是导入的还是本地配置）。
• 导入优先级按数组顺序排列；省略 imports 则使用默认值 ["cursor", "claude-code", "claude-desktop", "codex", "windsurf", "opencode", "vscode"]。

当您需要并排管理多个配置文件时，可以通过 CLI 或运行时调用提供 configPath 或 rootDir 参数。

配置解析顺序及系统级配置

MCPorter 每次运行只会读取一份主配置文件。查找顺序如下：

1. 您通过 --config 传递的路径（或程序化的 configPath）。
2. MCPORTER_CONFIG 环境变量（在您的 shell 中设置后，将在全局生效）。
3. 当前项目的 <root>/config/mcporter.json 文件。
4. 如果项目文件缺失，则使用 ~/.mcporter/mcporter.json 或 ~/.mcporter/mcporter.jsonc。

所有 mcporter config … 命令的更改都会写回到按照上述顺序选定的配置文件中。要显式管理系统级配置，只需将 CLI 指向该文件即可：

mcporter config --config ~/.mcporter/mcporter.json add global-server https://api.example.com/mcp

在您的 shell 配置文件中设置 MCPORTER_CONFIG=~/.mcporter/mcporter.json，即可使该文件成为全局默认配置（这对于 npx mcporter … 命令非常方便）。

测试与 CI

命令	用途
pnpm check	Biome 格式化检查，同时进行 Oxlint/tsgolint 代码质量检查。
pnpm build	TypeScript 编译（输出到 dist/ 目录）。
pnpm test	Vitest 单元测试和集成测试套件（包含可流式传输的 HTTP 测试数据）。

CI 通过 GitHub Actions 运行相同的三个步骤。

相关资源

• CodexBar 🟦🟩 让 Codex 的令牌窗口始终显示在 macOS 菜单栏中。https://codexbar.app。
• Trimmy ✂️ “粘贴一次，运行一次。” 将多行 Shell 片段简化为可直接粘贴并运行的形式。https://trimmy.app。
• Oracle 🧿 多模型运行的提示词打包工具及 CLI（GPT-5.1、Claude、Gemini 等）。https://github.com/steipete/oracle。
• MCP 规范 ✨ https://github.com/modelcontextprotocol/specification。

快速调试挂起的服务器

使用 tmux 保持长时间运行的 CLI 会话可见，以便您调查滞留的 MCP 传输问题：

tmux new-session -- pnpm mcporter:list

让其在后台运行，然后检查当前窗格的内容（tmux capture-pane -pt <session>）、跟踪标准输出日志，或在命令退出后终止会话。结合 MCPORTER_DEBUG_HANG=1 标志，可以获得详细的句柄诊断信息。更多详细信息请参阅 docs/tmux.md 和 docs/hang-debug.md。

许可证

MIT 许可证 — 请参阅 LICENSE。

延伸阅读：docs/tool-calling.md、docs/call-syntax.md、docs/adhoc.md、docs/emit-ts.md、docs/tmux.md。

MCPorter 快速上手指南

MCPorter 是一个用于 Model Context Protocol (MCP) 的 TypeScript 运行时、CLI 工具和代码生成套件。它能帮助你零配置发现系统中已配置的 MCP 服务器，直接调用工具，或使用 TypeScript 编写自动化脚本。

环境准备

• 操作系统: macOS, Linux, 或 Windows
• 运行环境: 需要安装 Node.js (建议 v18 或更高版本)
• 前置依赖: 无需额外安装，支持通过 npx 直接运行。若需长期开发，可全局安装。

安装步骤

你可以选择直接使用 npx 运行（推荐尝试），或者全局安装以便频繁使用。

方式一：直接使用 (无需安装)

npx mcporter list

方式二：全局安装

npm install -g mcporter

提示: 国内开发者若遇到 npm 下载缓慢，可临时切换至淘宝镜像源：

npm config set registry https://registry.npmmirror.com

基本使用

MCPorter 会自动发现你在 Cursor、Claude Code、VS Code 等工具中已配置的 MCP 服务器。

1. 查看可用的 MCP 服务器

列出所有已发现的服务及其提供的工具列表：

npx mcporter list

查看特定服务器的详细工具签名（类似 TypeScript 定义）：

npx mcporter list linear

2. 调用 MCP 工具

MCPorter 支持多种调用语法，以下是最常用的几种方式：

使用冒号分隔参数 (Shell 友好):

npx mcporter call linear.create_comment issueId:ENG-123 body:'Looks good!'

使用函数调用风格 (匹配 list 输出的签名):

npx mcporter call 'linear.create_comment(issueId: "ENG-123", body: "Looks good!")'

调用无需认证的公共服务 (例如获取 React 文档):

npx mcporter call context7.resolve-library-id libraryName=react

调用需要环境变量认证的服务:

LINEAR_API_KEY=sk_linear_example npx mcporter call linear.search_documentation query="automations"

3. 处理 OAuth 认证

对于需要浏览器登录的服务（如 Vercel），先运行 auth 命令完成授权：

npx mcporter auth vercel

授权完成后，即可像普通工具一样直接调用。

4. 生成 TypeScript 类型定义

为当前配置的服务生成 .d.ts 文件，以便在代码中获得完整的类型提示：

mcporter emit-ts