网硕互联帮助中心【免费下载链接】mcporter
Call MCPs via TypeScript, masquerading as simple TypeScript API. Or package them as cli.
项目地址：
https://gitcode.com/gh_mirrors/mc/mcporter
点击查看 免费下载
本文介绍 mcporter 官方推荐的 Agent Skill Pattern（Agent 技能模式）：与其给 Agent 配一个什么都教的通用 mcporter 技能，不如为每个 MCP 服务器或工作流编写一个小而专的技能。读完本文，你将掌握四步实战流程——添加服务器、探查工具面、编写 skill、生成专用 CLI，并学会用 allowedTools/blockedTools 精确收窄 Agent 可见与可调用的工具范围。
核心原则：小技能优于大而全的通用技能
mcporter 在 docs/agent-skills.md 中给出的第一原则非常明确：优先为每个 MCP 服务器或工作流编写一个独立的技能，而不是编写一个通用的 mcporter 技能。
一个聚焦的技能价值在于：
- 保持 Agent 提示词（prompt）小而精：技能文件只需要描述与当前任务相关的少数工具，不会把无关内容塞进上下文；
- 直接点名有用的工具：技能正文可以明确写出要调用哪个 server.tool、传什么参数，Agent 不需要自行猜测；
- 避免加载无关服务器的 schema：如果 Agent 当前任务是查文档，就不必把线性项目管理、浏览器调试等其他服务器的工具 schema 全部载入。
这正是 mcporter 从设计上想规避的"大 schema 上下文问题"——通用技能被迫教 Agent 如何发现、选择并调用每一个已配置的服务器，等于把大型 schema 重新搬回提示词里。而按服务器拆分的技能，让技能作者能针对该服务器描述"安全且有用"的工作流，Agent 只需要照做。
推荐流程：四步把一个 MCP 服务器接入 Agent
原文档给出的推荐流程分为四步，下面结合仓库源码逐一对每一步做展开说明。
第 1 步：添加或导入 MCP 服务器
npx mcporter config add docs https://mcp.context7.com/mcp –scope home
这条命令把名为 docs 的服务器写入 home 级配置。从 src/cli/config/add.ts 的 resolveWriteTarget 实现可以看到：
- –scope home 写入 ~/.mcporter/mcporter.json（或设置 XDG_CONFIG_HOME 时的 $XDG_CONFIG_HOME/mcporter/mcporter.json）；
- –scope project 写入当前仓库的 config/mcporter.json；
- –persist <path> 优先级最高，可强制写入自定义文件。
把服务器放到 home 级配置意味着它跨项目可用，这符合 Agent 场景下"全局工具随时待命"的需求。若使用 –scope project 或省略 scope（默认 project），则服务器只对当前仓库可见，适合与团队共享。
config add 还支持完整的目标与传输选项：–transport http|sse|stdio、–url、–command/–stdio、–env KEY=value、–header KEY=value、–description、OAuth 相关参数等，详见 配置指南 与 add.ts 的参数解析逻辑。
第 2 步：探查工具面
添加完成后，用两条命令了解该服务器到底暴露了哪些工具：
npx mcporter list docs –brief
npx mcporter list docs –schema
- –brief（别名 –signatures）只打印紧凑的 TypeScript 风格签名与可选参数摘要，不包含冗长的文档块；
- –schema 输出原始 JSON Schema，便于精确掌握每个工具的参数结构；
- 此外还有 –all-parameters 可展开被隐藏的可选参数。
从 src/cli/list-flags.ts 可以看到，–brief 与 –json、–schema、–verbose、–all-parameters 互斥，使用时会直接报错，避免输出格式冲突。列表输出的签名样式与参数说明规则详见 Call 语法参考 的 "Reading the CLI Signatures" 一节：必需参数不带 ?，可选参数带 ? 并继承枚举字面量，超过两个可选参数时默认折叠为 // optional (8): … 摘要。
这一步的核心价值在于：技能作者需要基于真实的工具签名来编写技能，而不是凭空猜测参数名——签名里看到 resolve-library-id(query: string, libraryName: string)，技能里就照着写。
第 3 步：编写只调用相关工具的技能
探查完毕后，编写一个聚焦的技能文件。原文档给出了可直接套用的模板：
—
name: docs-mcp
description: Fetch package and framework docs through the configured docs MCP server.
—
# Docs MCP
Use `npx mcporter call docs.resolve-library-id query=<task> libraryName=<name>`
to resolve a package, then call `npx mcporter call docs.query-docs …` with
the resolved ID and docs query.
技能正文通过 mcporter call 调用工具。call 支持多种参数风格（详见 Tool Calling Cheatsheet 与 Call 语法参考），技能作者可以选择对 Agent 最友好的一种：
| key=value 键值对 | mcporter call docs.resolve-library-id query="React hooks docs" libraryName=react |
| 函数调用式（贴近 list 打印的签名） | mcporter call 'docs.resolve-library-id(query: "React hooks docs", libraryName: "react")' |
| 无标签位置参数 | mcporter call 'docs.resolve-library-id("React hooks docs", "react")' |
| JSON 载荷 | mcporter call docs.resolve-library-id –args '{"query":"…","libraryName":"react"}' |
所有风格走同一条校验管线（schema 驱动的类型强制、必填检查、枚举提示），因此无论 Agent 习惯哪种写法，行为都一致。注意字符串含空格或逗号时，整个表达式要用单引号包裹，避免 shell 拆词。
技能文件的具体存放位置与加载机制取决于 Agent 运行时（Claude Code 的 skills 目录、OpenCode 的 rules 等），mcporter 只负责提供 CLI 与配置支撑；技能正文里把"该服务器上哪些工作流是安全有用的"写清楚，正是技能作者的核心职责。
第 4 步：重复或可共享的工作流，生成专用 CLI
如果某个工作流会被反复使用或需要分享给团队，就不要让 Agent 每次都拼写原始的 mcporter call 语法，而是生成一个专用 CLI：
npx mcporter generate-cli docs –bundle dist/docs-mcp.js
generate-cli 会把该服务器的工具 schema 转成子命令，schema 字段变成位置参数或 flags，生成一个独立可分发、可执行、自描述的命令行工具。常用选项（详见 CLI Generator 文档）：
- –name <name>：显式指定 CLI 名（省略时从命令 URL 推断，如 https://mcp.context7.com/mcp 推断为 context7）；
- –bundle <path>：打包为单个 JS 文件（默认输出 <server>.ts，加 –minify 可压缩）；
- –compile [path]：进一步用 bun build –compile 生成原生可执行文件（需 Bun）；
- –runtime node|bun：选择生成运行时（省略时优先 Bun，其次 Node）；
- –include-tools a,b / –exclude-tools a,b：收窄 CLI 暴露的工具子集（详见下文）；
- –timeout <ms>：默认工具调用超时为 30 秒，可覆盖。
生成出的 CLI 嵌入了解析后的服务器定义快照，运行时不依赖外部 –config/–server 覆盖；工具参数校验、布尔值、枚举、默认值均在调用前完成，错误会先于网络请求暴露。
用 allowedTools / blockedTools 收窄 Agent 的工具面
当服务器暴露了不应该展示给 Agent的工具（如管理类、调试类、高危写操作）时，在 config/mcporter.json（或 home 级配置）中使用工具过滤：
{
"mcpServers": {
"docs": {
"url": "https://mcp.context7.com/mcp",
"allowedTools": ["resolve-library-id", "query-docs"]
}
}
}
或使用黑名单形式：
{
"mcpServers": {
"docs": {
"url": "https://mcp.context7.com/mcp",
"blockedTools": ["admin-reset", "debug_tool"]
}
}
}
两条规则的关键语义（见 src/tool-filters.ts 与 配置指南 的 Schema Reference 表格）：
- allowedTools（别名 allowed_tools）是精确名称白名单：只有列出的工具会出现在 mcporter list 中且可被调用；空数组表示阻断所有工具；
- blockedTools（别名 blocked_tools）是精确名称黑名单：列出的工具从 list 中隐藏，并被 call 拒绝；
- 两者不能同时出现。配置层在 src/config-schema.ts 用 superRefine 直接拒绝"同时指定两者"的配置；程序化定义在 createRuntime 时同样会被 validateToolFilters 拦截。
过滤的实际生效位置在运行时层（src/runtime.ts）：
- listTools 返回前调用 filterTools，白名单/黑名单直接裁剪工具列表——Agent 的 schema 探查根本看不到被过滤的工具；
- callTool 在发起连接之前就调用 isToolAllowed 校验，被过滤的工具抛出 Tool 'X' is not accessible on server 'Y' (blocked by configuration)，且不会建立任何网络连接。
这在安全上很有意义：阻断发生在连接建立之前，被禁用的工具连"触发服务器端副作用"的机会都没有。测试 tests/tool-filters.test.ts 完整覆盖了这些行为：allowlist 裁剪 listTools 结果、空 allowlist 返回空列表、blocklist 在连接前拒绝 callTool（断言 connect 与 callTool 均未被调用）、camelCase/snake_case 字段规范化、互斥校验。
补充边界：generate-cli 的工具收窄 ≠ 动态授权
generate-cli 的 –include-tools / –exclude-tools 与配置层的 allowedTools/blockedTools 用途类似但层次不同：
- allowedTools/blockedTools 作用于运行期的 list 与 call，是 Agent 与脚本每次访问服务器时的强制过滤；
- –include-tools/–exclude-tools 作用于生成期，静态裁剪生成 CLI 暴露的子命令（–include-tools 传空或与 –exclude-tools 同时使用会在生成时直接报错，见 src/cli/generate/tool-selection.ts 与集成测试 tests/cli-generate-cli.integration.test.ts）。
需要特别注意的是：静态工具清单不是动态授权。生成出的 CLI 可以脱离原始配置它的 MCP 客户端独立运行，因此不会自动继承该客户端的审批提示、工具调用策略或审计轨迹。对需要逐调用策略管控的部署，应将生成命令包裹在外部策略网关之后——网关负责规范化操作、评估当前策略、请求审批、执行或拦截调用，并持久化脱敏后的决策与结果记录（CLI Generator 文档 给出了完整的包装器伪代码）。直接执行生成物会绕过这层策略边界。
落地建议
- 一个服务器一个技能：技能名直接采用服务器名（如 docs-mcp），描述里写明用途，正文只教与该服务器相关的工具与参数；
- 先 list –brief 后写技能：以真实签名为准，避免写出不存在的参数名；
- 用 allowedTools 收窄暴露面：凡是 Agent 不该碰的管理/调试/高危工具，一律在配置中过滤掉；
- 工作流成熟后升级为 CLI：需要反复执行或跨环境分享时，用 generate-cli –bundle 生成独立产物，Agent 只需要调用一个命令而非记忆一整套 mcporter call 语法；
- 敏感与安全：配置文件支持 ${VAR} 环境变量占位符，不要把密钥直接写进 config/mcporter.json；需要动态策略时在生成 CLI 外加包装网关。
赞
【免费下载链接】mcporter
Call MCPs via TypeScript, masquerading as simple TypeScript API. Or package them as cli.
项目地址：
https://gitcode.com/gh_mirrors/mc/mcporter
点击查看 免费下载
相关推荐
Cogito v2预览版：109B MoE开启AI混合推理新纪元
Socket.IO Client C++：现代C++11实时通信客户端完全指南
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
评论前必须登录！
注册