mcporter (Steipete)

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

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

MCPorter帮助您深入了解Anthropic中强调的“代码执行”工作流程 使用MCP执行代码 指导：发现系统上已经配置的MCP服务器，直接调用它们，用TypeScript编写更丰富的自动化，并在需要共享工具时创建单用途CLI。所有这些都是开箱即用的——没有样板，没有模式。

关键能力

• 零配置发现。 createRuntime() 合并您的家庭配置(~/.mcporter/mcporter.json[c]，或 $XDG_CONFIG_HOME/mcporter/mcporter.json[c] 设置时），然后 config/mcporter.json，加上Cursor/Claude/Copyx/Windsurf/OpenCode/VS代码导入，扩展 ${ENV} 占位符和池连接，以便您可以在多个调用之间重用传输。
• 一个命令CLI生成。 mcporter generate-cli 将任何MCP服务器定义转换为可运行的CLI，具有可选的绑定/编译和元数据，便于重新生成。
• 键入工具客户端。 mcporter emit-ts 发射 .d.ts 接口或准备运行的客户端包装器，这样代理/测试就可以调用具有强TypeScript类型的MCP服务器，而无需手写管道。
• 友好的可组合API。 createServerProxy() 将工具公开为符合人体工程学的camelCase方法，自动应用JSON模式默认值，验证所需参数，并返回 CallResult 随着 .text(), .markdown(), .json(), .images()，以及 .content() 助手。
• OAuth和stdio人体工程学。 内置的OAuth缓存、日志跟踪和stdio包装器允许您从同一接口使用HTTP、SSE和stdio传输。
• 临时连接。 将CLI指向 _任何_ MCP端点（HTTP或stdio），无需接触配置，然后如果需要，可以稍后持久化。需要浏览器登录的托管MCP（Supabase、Vercel等）会被自动检测到——只需运行 mcporter auth CLI动态地将定义提升到OAuth。看 docs/adhoc.md.

0.11.0的新增功能

• 桥接模式。 mcporter serve 将守护进程管理的保持活动服务器暴露为一个具有可读性的MCP桥 server__tool 名字。
• 无头OAuth。 --no-browser、vault种子设定、缓存令牌刷新，以及 auth: "refreshable_bearer" 涵盖非交互式部署。
• HTTP兼容性。 httpFetch: "node-http1" 保留拒绝Node内置的提供程序 fetch 工作。
• 更安全的写作。 Config、OAuth vault、JSON输出和缓存元数据写入都是序列化/原子化的，因此并行代理不会相互踩踏。
• 释放信心。 0.11.0 已在npm和Homebrew上发布，实时/已发布的安装烟雾是绿色的。

快速开始

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

调用语法选项

# Colon-delimited flags (shell-friendly)
npx mcporter call linear.create_comment issueId:ENG-123 body:'Looks good!'

# Function-call style (matches signatures from `mcporter list`)
npx mcporter call 'linear.create_comment(issueId: "ENG-123", body: "Looks good!")'

# Literal positional values that start with `--`
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 + tool suffix auto-resolves
npx mcporter list --stdio "bun run ./local-server.ts" --env TOKEN=xyz

• 添加 --json 生成一个机器可读的摘要，其中包含每台服务器的状态（auth/offline/http/错误计数），对于单台服务器运行，还包含完整的工具模式有效负载。
• 添加 --verbose 以文本和JSON列表输出的形式显示注册服务器名称的每个配置源（主服务器优先）。

您现在可以指向 mcporter list 在ad-hoc服务器上：直接提供URL或使用新的 --http-url/--stdio 标志（加号 --env, --cwd, --name，或 --persist)以描述任何MCP端点。在坚持该定义之前，您仍然需要重复相同的URL/stdio标志 mcporter call--打印的slug只有在您通过以下方式将其合并到配置中后才能重复使用 --persist 或 mcporter config add （使用 --scope home|project 选择写入目标）。跟进 mcporter auth https://… （或相同的标志集）在不编辑配置的情况下完成OAuth。详细信息请访问 docs/adhoc.md.

单服务器列表现在读起来像TypeScript头文件，因此您可以将签名直接复制/粘贴到 mcporter call:

linear - Hosted Linear MCP; exposes issue search, create, and workflow tooling.
  23 tools · 1654ms · HTTP https://mcp.linear.app/mcp

  /**
   * Create a comment on a specific Linear issue
   * @param issueId The issue ID
   * @param body The content of the comment as Markdown
   * @param parentId? A parent comment ID to reply to
   */
  function create_comment(issueId: string, body: string, parentId?: string);
  // optional (3): notifySubscribers, labelIds, mentionIds

  /**
   * List documents in the user's Linear workspace
   * @param query? An optional search query
   * @param projectId? Filter by project ID
   */
  function list_documents(query?: string, projectId?: string);
  // optional (11): limit, before, after, orderBy, initiativeId, ...

以下是你跑步时Vercel的样子 npx mcporter list vercel:

vercel - Vercel MCP (requires OAuth).

  /**
   * Search the Vercel documentation.
   * Use this tool to answer any questions about Vercel’s platform, features, and best practices,
   * including:
   * - Core Concepts: Projects, Deployments, Git Integration, Preview Deployments, Environments
   * - Frontend & Frameworks: Next.js, SvelteKit, Nuxt, Astro, Remix, frameworks configuration and
   *   optimization
   * - APIs: REST API, Vercel SDK, Build Output API
   * - Compute: Fluid Compute, Functions, Routing Middleware, Cron Jobs, OG Image Generation, Sandbox,
   *   Data Cache
   * - AI: Vercel AI SDK, AI Gateway, MCP, v0
   * - Performance & Delivery: Edge Network, Caching, CDN, Image Optimization, Headers, Redirects,
   *   Rewrites
   * - Pricing: Plans, Spend Management, Billing
   * - Security: Audit Logs, Firewall, Bot Management, BotID, OIDC, RBAC, Secure Compute, 2FA
   * - Storage: Blog, Edge Config
   *
   * @param topic Topic to focus the documentation search on (e.g., 'routing', 'data-fetching').
   * @param tokens? Maximum number of tokens to include in the result. Default is 2500.
   */
  function search_vercel_documentation(topic: string, tokens?: number);

  /**
   * Deploy the current project to Vercel
   */
  function deploy_to_vercel();

所需参数始终显示；可选参数保持隐藏状态，除非（a）只有一两个可选参数，且必填字段少于四个，或者（b）您传递了 --all-parameters。每当MCPorter隐藏参数时，它都会打印 Optional parameters hidden; run with --all-parameters to view all fields. 所以你知道如何显示完整的签名。返回类型是从工具模式中推断出来的 title，转而完全省略后缀，而不是猜测。

Context7:获取文档（无需身份验证）

npx mcporter call context7.resolve-library-id query="React hooks docs" libraryName=react
npx mcporter call context7.query-docs libraryId=/reactjs/react.dev query="useEffect cleanup"

线性：搜索文档（需要 LINEAR_API_KEY)

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

Chrome DevTools：快照当前选项卡

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   # protocol optional; defaults to https
npx mcporter call linear.listIssues --tool listIssues   # auto-corrects to list_issues
npx mcporter linear.list_issues                         # shorthand: infers `call`
VERCEL_ACCESS_TOKEN=sk_vercel_example npx mcporter call "npx -y vercel-domains-mcp" domain=answeroverflow.com  # quoted stdio cmd + single-tool inference

工具调用可以理解类似JavaScript的调用语法，自动纠正差点错过的工具名称，并发出更丰富的内联使用提示。看 docs/call-syntax.md 语法和 docs/call-heuristic.md 用于自动校正规则。

有用的标志：

• `--config

--自定义配置文件（默认为 ./config/mcporter.json`).

• `--root

` --stdio命令的工作目录。

• --log-level --调整冗长（尊重 MCPORTER_LOG_LEVEL).
• --oauth-timeout --缩短/延长OAuth浏览器等待时间；与...相同 MCPORTER_OAUTH_TIMEOUT_MS / MCPORTER_OAUTH_TIMEOUT.
• --tail-log --流式传输工具响应引用的任何日志文件的最后20行。
• --output 或 --raw --控制格式化输出（默认为打印精美的自动检测）。
• --save-images （on mcporter call)--将MCP图像内容块保存到给定目录中的文件中（opt-in；stdout输出形状保持不变）。
• --raw-strings （on mcporter call)--保持参数值的数值外观（for key=value, key:value，以及尾随位置值）作为字符串。
• --no-coerce （on mcporter call)--保留所有 key=value 将位置值作为原始字符串（禁用bool/null/number/JSON强制转换）。
• -- （on mcporter call)--停止标志解析，使剩余的标记保持文字位置值，即使它们以开头 --.
• --json （on mcporter list)--发出JSON摘要/计数而不是文本。多服务器运行每个服务器的状态、计数和连接问题报告；单服务器运行包含完整的工具元数据。
• --output json/raw （on mcporter call)--当连接失败时，MCPorter会打印通常的彩色提示，并发出结构化的提示 { server, tool, issue } 信封，这样脚本就可以以编程方式处理auth/offline/http错误。
• --json （on mcporter auth)--每当OAuth/传输设置失败时，发出相同的结构化连接信封，而不是抛出错误。随着 --no-browser，它发出包含auth-start的JSON authorizationUrl 和 redirectUrl.
• --no-browser / --browser none （on mcporter auth 或 mcporter config login)--禁止浏览器启动，并打印无头工作流的OAuth授权URL； MCPORTER_OAUTH_NO_BROWSER=1 / true / yes 实现相同的行为。
• --json （on mcporter emit-ts)--打印一个JSON摘要，描述发出的文件（模式+输出路径），而不是文本日志——在脚本中生成工件时很方便。
• --all-parameters --列出服务器时显示每个模式字段（默认输出显示至少五个参数以及其余参数的摘要）。
• --http-url / --stdio "command …" --描述一个内联的ad-hoc MCP服务器。STDIO传输现在自动继承您当前的shell环境；添加 --env KEY=value 仅当您需要同时注入/覆盖变量时 --cwd, --name，或 --persist 。这些标志现在可以与 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浏览器握手有单独的5分钟宽限期；通过 --oauth-timeout （或出口 MCPORTER_OAUTH_TIMEOUT_MS)当您在诊断顽固的身份验证流时需要CLI更快地退出时。

尝试不编辑配置的MCP

# Point at an HTTPS MCP server directly
npx mcporter list --http-url https://mcp.linear.app/mcp --name linear

# Run a local stdio MCP server via Bun
npx mcporter call --stdio "bun run ./local-server.ts" --name local-tools

• 添加 --persist config/mcporter.local.json 以保存推断的定义以供将来运行。
• 使用 --allow-http 如果你真的需要达到明文端点。
• 看 docs/adhoc.md 深入了解（env覆盖、cwd、OAuth）。

使用守护程序使MCP服务器保持温暖

• chrome-devtools, mobile-mcp，和其他有状态的stdio服务器在您第一次调用它们时会自动启动一个每次登录的守护进程，以便Chrome选项卡和设备会话在代理之间保持活动状态。
• 使用 mcporter daemon status 检查守护进程是否正在运行（以及连接了哪些服务器）。
• 随时停止 mcporter daemon stop，预热 mcporter daemon start，或通过反弹 mcporter daemon restart 在调整了configs/env之后。
• 所有其他服务器都是短暂的；添加 "lifecycle": "keep-alive" 到服务器条目（或设置 MCPORTER_KEEPALIVE=name)当您希望守护进程管理它时。您还可以设置 "lifecycle": "ephemeral" （或 MCPORTER_DISABLE_KEEPALIVE=name)选择退出。
• 该守护进程仅管理来自您的配置/导入的命名服务器。通过调用临时STDIO/HTTP目标 --stdio …, --http-url …，或者内联函数调用语法今天仍保留在每个进程中；坚持他们 config/mcporter.json （或使用 --persist)如果你需要他们参与共享守护进程。
• mcporter serve --stdio 将每个守护进程管理的保活服务器暴露为一个MCP stdio桥，供Claude Code或Codex等客户端使用。注册一次，然后调用命名空间工具，如 chrome-devtools__list_pages；添加 --servers a,b 限制桥梁或 `--http

在本地主机上提供Streamable HTTP服务 /mcp`.

• 故障排除？跑 mcporter daemon start --log （或 --log-file /tmp/daemon.log)将stdout/stderr放入一个文件中，并添加 --log-servers chrome-devtools 当您只需要特定MCP的呼叫跟踪时。还可以设置每台服务器的配置 "logging": { "daemon": { "enabled": true } } 强制对该条目进行详细记录。

Friendlier工具调用

• 函数调用语法。 而不是杂耍 --flag value，您可以将工具称为 mcporter call 'linear.create_issue(title: "Bug", team: "ENG")'解析器支持嵌套对象/数组，当你想依赖模式顺序时，可以省略标签（例如。 mcporter 'context7.resolve-library-id("React hooks docs", "react")')，并清楚地显示模式验证错误。深入潜水 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 用于快速比较每种支持的调用样式（自动推断的动词、标志、函数调用和ad-hoc URL）。
• 自动更正。 如果键入工具名称，MCPorter会检查服务器的工具目录，在编辑距离很小时重试，否则会打印 Did you mean …? 提示。启发式（以及如何调整它）在 docs/call-heuristic.md.
• 更丰富的单服务器输出。 mcporter list 现在打印TypeScript风格的签名、内联注释、返回形状提示和反映新调用语法的命令示例。默认情况下，可选参数保持隐藏状态--add --all-parameters 或 --schema 每当您需要完整的JSON模式时。更喜欢更严格的扫描？ mcporter list --brief （或 --signatures)仅保留紧凑的签名和可选摘要。

安装

立即跑步 npx

npx mcporter list

添加到您的项目

pnpm add mcporter

使用npm全局安装

npm install -g mcporter

自制（甜菊汁/自来水）

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

tap与npm一起发布。如果您在安装较旧的水龙头时遇到问题，请运行 brew update 在重新安装之前。

一次代码调用

import { callOnce } from 'mcporter';

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

console.log(result); // raw MCP envelope

callOnce 自动发现所选服务器（包括Cursor/Claude/Copyro/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: { query: 'React hooks docs', libraryName: 'react' },
});

console.log(result); // prints JSON/text automatically because the CLI pretty-prints by default
await runtime.close(); // shuts down transports and OAuth sessions

伸手去够 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());

代理和结果助手中融入了友好的人体工程学：

• 属性名称从camelCase映射到kebab case工具名称(takeSnapshot -> take_snapshot).
• 位置参数会自动映射到模式所需的字段上，选项对象会尊重JSON模式默认值。
• 结果被包裹在 CallResult，所以你可以选择 .text(), .markdown(), .json(), .images(), .content()，或访问 .raw 当你需要完整的信封时。

下降到 runtime.callTool() 每当您需要对参数、元数据或流选项进行显式控制时。

呼叫 mcporter list 任何时候你需要TypeScript风格的签名、可选参数提示和与CLI函数调用语法匹配的示例调用。添加 --brief 或 --signatures 当你只想要紧凑的签名时。

生成独立CLI

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

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

# Outputs:
#   context7.ts        (TypeScript template with embedded schemas)
#   context7.js        (bundled CLI via Rolldown or Bun, depending on runtime)

通过这个奇怪的技巧将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 当stdout是TTY时，页面使用粗体标题+灰色描述。
• 添加 --bundle [path] 在模板旁边发出一个bundle（当以Node为目标时为Rolldown，当运行时解析为Bun时为Bun；用覆盖 --bundler rolldown|bun).
• `--output

` 将模板写入特定位置。

• --runtime bun|node 为生成的代码选择运行时（Bun是必需的 --compile).
• 添加 --compile 发出Bun编译的二进制文件；当您忽略时，MCPorter会清理中间包 --bundle.
• 使用 --include-tools a,b,c 或 --exclude-tools a,b,c 为工具子集生成CLI（互斥）。
• 使用 --from （可选 --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     # human-readable summary
npx mcporter generate-cli --from dist/context7.js  # replay with latest mcporter

代理通常应该为每个MCP服务器或工作流获得一项小技能，而不是 一种通用的“全麦波特”技能。看 docs/agent-skills.md 用于模式和可复制模板。

生成类型化客户端

使用 mcporter emit-ts 当您想要强类型的工具而不需要提供完整的CLI时。它重用与以下相同的签名/doc块 mcporter list，因此生成的标头与CLI显示的内容保持同步。

# Types-only interface (Promise signatures)
npx mcporter emit-ts linear --out types/linear-tools.d.ts

# Client wrapper (creates a reusable proxy factory alongside the .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).
• 添加 --json 在编写脚本时发出结构化摘要（模式加输出路径）而不是纯文本日志 emit-ts.
• 这 ` 参数还可以理解HTTP URL和选择器 .tool` 后缀或缺少协议——镜像主CLI。

看 docs/emit-ts.md 用于获取完整标志引用以及已发出文件的内联快照。

配置参考

使用管理此文件 mcporter config list|get|add|remove|import 当你宁愿避免手工编辑JSON时；看见 docs/config.md 完整的演练。 配置文件被解析为JSONC，因此内联 // 和 /* ... */ 两者都支持注释和尾随逗号 mcporter.json 和 mcporter.jsonc.

通过以下方式管理配置 mcporter config

跑 mcporter config … 当你想要一个项目MCP的交互式视图时，可以通过你的包管理器（pnpm、npm、npx等）：

• config list 显示 仅本地条目 默认情况下，在TTY上，打印其他每个配置文件（Cursor、Claude、Windsurf、VS Code等）的摘要，包括计数和示例名称。添加 --source import 直接检查这些进口条目，或 --json 用于脚本编写。
• config get/remove/logout 重用模糊匹配逻辑 mcporter list/call，所以拼写错误像 sshadcn 自动更正为 shadcn （带着一个模糊的提示）和模棱两可的名字浮出水面：“你是说……吗？”暗示。
• config import --copy 将编辑器管理的条目拉入 config/mcporter.json，允许您在本地自定义或删除它们，而无需接触上游文件。
• 每一个子司令部都荣誉 `--config

/ --root `，使处理多个项目配置或特定于工作区的覆盖变得容易。

config/mcporter.json 镜像Cursor/Claude的形状：

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

MCPorter为您处理的内容：

• ${VAR}, ${VAR:-fallback}，以及 $env:VAR 配置字符串的插值。秘密轴承 headers, env，并且承载令牌占位符保持惰性并在运行时解析。
• 共享保管库中的自动OAuth令牌缓存(~/.mcporter/credentials.json，或 $XDG_DATA_HOME/mcporter/credentials.json 设置时），除非您覆盖 tokenCacheDir.
• Stdio命令继承了定义它们的文件的目录（导入或本地配置）。
• 导入优先级与数组顺序匹配；省略 imports 使用默认值 ["cursor", "claude-code", "claude-desktop", "codex", "windsurf", "opencode", "vscode"].
• chrome-devtools-mcp --autoConnect 收到一个小的兼容性补丁，而上游自动连接可以挂在繁忙的Chrome配置文件上；集 MCPORTER_DISABLE_CHROME_DEVTOOLS_COMPAT=1 选择退出。

OAuth保护的服务器

如果HTTP MCP需要浏览器登录（OAuth），请使用 --auth oauth （或设置 "auth": "oauth" JSON格式），然后运行 mcporter auth 一次：

npx mcporter config add notion https://mcp.notion.com/mcp --auth oauth
npx mcporter auth notion

在无头主机上，使用 npx mcporter auth notion --no-browser 打印授权URL，而不是启动平台浏览器。将打印的URL视为敏感的操作输出。如果你在另一台机器上打开它，请确保打印的 redirectUrl 回调端口可以通过仅环回隧道或配置的 oauthRedirectUrl.

不支持动态客户端注册的提供商可以使用预先注册的应用程序：

{
  "mcpServers": {
    "hubspot": {
      "baseUrl": "https://mcp.hubspot.com/mcp",
      "auth": "oauth",
      "oauthClientId": "your-client-id",
      "oauthClientSecretEnv": "HUBSPOT_CLIENT_SECRET",
      "oauthTokenEndpointAuthMethod": "client_secret_post",
      "oauthRedirectUrl": "http://127.0.0.1:3434/callback",
    },
  },
}

将客户端机密保存在环境变量或私有机器本地配置中， 并准确登记 oauthRedirectUrl 与供应商。

可刷新的承载令牌（非交互式OAuth）

对于需要在没有浏览器提示的情况下自动刷新的具有预种子OAuth令牌的服务器，请使用 auth: "refreshable_bearer"HTTP服务器接收 Authorization: Bearer 标题；STDIO服务器需要 refresh.accessTokenEnv 将令牌作为环境变量注入：

{
  "mcpServers": {
    "example": {
      "command": "uvx",
      "args": ["example-mcp-server"],
      "auth": "refreshable_bearer",
      "refresh": {
        "tokenEndpoint": "https://api.example.com/oauth/token",
        "clientIdEnv": "EXAMPLE_CLIENT_ID",
        "clientSecretEnv": "EXAMPLE_CLIENT_SECRET",
        "clientAuthMethod": "client_secret_basic",
        "refreshSkewSeconds": 300,
        "accessTokenEnv": "EXAMPLE_ACCESS_TOKEN",
      },
    },
  },
}

mcporter使用保管库中的刷新令牌在令牌过期之前（默认提前5分钟）刷新令牌。对于启动后无法重新加载凭据的保持活动状态的stdio服务器，请使用 "lifecycle": "ephemeral" 或者在令牌过期之前重新启动守护进程。

已经拥有OAuth令牌的无头部署可以在没有OAuth令牌的情况下为vault种子 复制mcporter的内部保险库密钥：

npx mcporter vault set hubspot --tokens-file ./tokens.json
npx mcporter vault set hubspot --stdin /config/mcporter.json` 在当前项目中。
1. `$XDG_CONFIG_HOME/mcporter/mcporter.json[c]` 当 `XDG_CONFIG_HOME` 已设置，否则 `~/.mcporter/mcporter.json[c]`，如果项目文件丢失。

全部 `mcporter config …` 突变会写回按该顺序选择的任何文件。要明确管理系统范围的配置，请将CLI指向它：

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

集 `MCPORTER_CONFIG=~/.mcporter/mcporter.json` 在shell配置文件中，当您希望该文件在任何地方都是默认文件时（方便 `npx mcporter …` 跑步）。

当显式设置XDG Base Directory环境变量时，mcporter会为其自己的文件尊重这些变量： `XDG_CONFIG_HOME` 对于家庭配置， `XDG_DATA_HOME` 对于OAuth保险库， `XDG_CACHE_HOME` 对于模式缓存，以及 `XDG_STATE_HOME` 用于守护进程/运行时状态。如果匹配的XDG var未设置或相对，mcporter将保留遗留值 `~/.mcporter` 路径。现有的显式覆盖仍然获胜。

### 工具筛选

服务器定义可以通过以下任一方式隐藏或阻止精确的工具名称 `allowedTools` 或 `blockedTools`:

{ "mcpServers": { "slack-readonly": { "baseUrl": "https://example.com/slack/mcp", "allowedTools": ["channels_list", "conversations_history"], }, "filesystem-safe": { "command": "npx -y @modelcontextprotocol/server-filesystem ~/Downloads", "blockedTools": ["write_file", "delete_file", "move_file"], }, }, }

`allowedTools` 是一个满列表：只有列出的工具才会出现在 `mcporter list` 并且可以被调用。一个空数组会阻塞每个工具。 `blockedTools` 是一个阻止列表：列出的工具被隐藏并被拒绝 `mcporter call`。仅使用精确的工具名称，并为每台服务器选择一种模式。

## 测试和CI

|命令|目的|
| ------------ | ----------------------------------------------------------------------- |
| `pnpm check` |Oxfmt格式化加Oxlint/tsgolint门。                             |
| `pnpm build` |TypeScript编译（发射 `dist/`).                                 |
| `pnpm test` |Vitest单元和集成套件（包括可流式传输的HTTP设备）。 |

CI通过GitHub Actions运行相同的三人组。

## 相关

- CodexBar🟦🟩 在macOS菜单栏中保持Codex令牌窗口可见。 .
- 特里米✂️ “粘贴一次，运行一次。”平铺多行shell代码段，使其粘贴并运行。 .
- 甲骨文🧿 提示打包器/CLI进行多模型运行（GPT-5.1、Claude、Gemini）。 .
- MCP规范✨ 

## 快速调试挂起的服务器

使用 `tmux` 在调查挥之不去的MCP传输时，保持长时间运行的CLI会话可见：

tmux new-session -- pnpm mcporter:list

让它在后台运行，然后检查窗格(`tmux capture-pane -pt `)，尾随stdio日志，或在命令退出后终止会话。搭配这个 `MCPORTER_DEBUG_HANG=1` 当您需要详细的句柄诊断时。更多细节： [docs/tmux.md](docs/tmux.md) 和 [docs/hang-debug.md](docs/hang-debug.md).

## 许可证

麻省理工学院——见 [许可证](LICENSE).

进一步阅读： [docs/tool-calling.md](docs/tool-calling.md), [docs/call-syntax.md](docs/call-syntax.md), [docs/adhoc.md](docs/adhoc.md), [docs/emit-ts.md](docs/emit-ts.md), [docs/tmux.md](docs/tmux.md).