概述与支持的代理 (Overview and Supported Agents)

项目目的与定位

add-mcp 是一个使用 Node.js（要求 node >= 18，见 package.json:73-75）编写的命令行工具，核心使命是「通过一条命令，将 MCP（Model Context Protocol）服务器安装到多种主流 AI 编码代理的配置文件中」。其官方定位为 "Add MCP servers to your favorite coding agents with a single command."（package.json:3）。

该工具同时提供编程式 API（detect / upsert / remove），自 v1.10.0 起可通过 import 方式作为库被调用（见 CHANGELOG 引用：v1.10.0）。开发说明位于 CLAUDE.md 与 AGENTS.md，并以 bun 作为包管理器与脚本执行器。

支持的代理清单

下表汇总了 add-mcp 当前支持的代理、CLI 标识符以及本地与全局配置文件路径（整理自 README.md 与 package.json:32-47 中的 keywords 字段）：

Windsurf 支持自 v1.10.3 加入，并提供 codeium 与 cascade 别名（见 CHANGELOG：v1.10.3）；GitHub Copilot CLI 支持源自社区请求 #4，其全局路径遵循 Copilot CLI 规范（~/.copilot/mcp-config.json）。

核心能力与命令模式

CLI 主入口为 src/index.ts（编译后位于 dist/index.js，见 package.json:55-57），其下组织三大能力：

1. 直接安装命令 — 接受命令名、参数、环境变量、HTTP/SSE header 等，将一条 MCP 服务器记录写入所选代理的配置文件；库 API 名为 upsert（src/lib.ts）。
2. 交互式发现 (find) — 从一个或多个 MCP 注册表（如仓库内置的 registry.json）中搜索服务器、提示缺失的 ${VAR} 模板值、并把搜索结果落盘到目标代理。该流程的类型定义集中在 src/find.ts:1-58，包括 FindCommandOptions、FindInstallPlan、PromptField 等。
3. 删除命令 (remove) — 移除已弃用的 MCP 服务器记录，对应社区需求 #16。

路径处理在 v1.10.2 进行了关键回归修复：带空格的绝对路径、home-relative（~/...）、dot-relative（./...）以及 Windows 盘符路径会被完整保留为单一可执行命令，避免被空格拆分为 command + args（见 CHANGELOG：v1.10.2）。v1.9.1 起 --env "KEY="（空值）会被显式拒绝，并在 ${VAR} 似乎被 shell 吞掉时给出提示（见 CHANGELOG：v1.9.1）。

社区反馈与已知边界

• 远程认证能力待增强：#51 提出需为 streamable-http 远程配置增加 OAuth scopes、authProviderType 与连接超时等认证参数。
• Windows MSIX 安装兼容性问题：#50 反馈在 Windows 上以 MSIX 形式安装 Claude Desktop 后，工具写入/同步路径不正确。
• LM Studio 支持请求：#24 提议增加 LM Studio 适配（macOS 路径建议为 ~/.lmstudio/mcp.json），目前尚未在 package.json 的 keywords 中列出。
• 环境变量配置指南：#15 询问如何为 MCP 服务器设置环境变量，建议优先使用 v1.9.0 引入的交互式 ${VAR} 提示能力（CHANGELOG：v1.9.0）。

See Also

• Registry and find Workflow
• CLI Command Reference
• Library API (detect / upsert / remove)
• Releasing & npm Provenance

1. 命令体系总览

add-mcp 通过 Commander.js 注册顶层命令，并在 package.json 中以 bin.add-mcp 暴露可执行入口 package.json。三条核心子命令及语义如下：

顶层标志（适用于安装命令）包括 -g/--global、-a/--agent、--name、--env、-h/--header 等，详见 README 表格 README.md。

2. 默认安装命令

默认命令根据 source 字符串推断类型：URL 视作远程，npm/oci 包名视作 package，其余被视作本地命令 src/types.ts:SourceType。

# 本地 stdio 命令
npx add-mcp /usr/local/bin/my-mcp --name my-server

# 远程 HTTP/SSE 服务器
npx add-mcp https://mcp.example.com/sse --name example

# 安装并提示输入 ${VAR} 占位
npx add-mcp @scope/pkg --env "API_KEY=${API_KEY}"

行为要点：

• 路径中包含空格或绝对路径（如 macOS .app 内的可执行文件）必须使用引号包裹，CLI 在 v1.10.2 已修复对绝对路径、相对路径、Windows 盘符的拆分逻辑 CHANGELOG.md:1.10.2。社区问题 #29「Space character in server path breaks settings」中报告的 /Applications/Hopper Disassembler.app/... 场景已被该版本覆盖 issue #29。
• --env "KEY="（空值）会被拒绝并提示可能的 shell 变量被吞，源自 v1.9.1 CHANGELOG.md:1.9.1。
• 交互模式下，${VAR} 占位符在 --env/--header/--args 中会逐一提示；可选 key 跳过则不会写入配置 CHANGELOG.md:1.9.0。
• v1.10.4 新增 -h 作为 --header 的简写 CHANGELOG.md:1.10.4。
• v1.10.0 起同时暴露 detect / upsert / remove 程序化 API，可作为库使用 src/lib.ts CHANGELOG.md:1.10.0。

3. `list` 子命令

list 用于查看已写入配置的 MCP 服务器：

npx add-mcp list          # 扫描所有检测到的代理
npx add-mcp list -g       # 列出全局配置
npx add-mcp list -a cursor # 指定代理（即使未检测到也会显示）

底层通过读取各 agent 的 localConfigKey / configKey（点号路径）来定位服务器项 src/types.ts:AgentConfig。每个 agent 的本地与全局配置路径在 README 的表格中给出，例如 claude-code 本地为 .mcp.json、全局为 ~/.claude.json README.md。

4. `find` 子命令与自定义注册表

find 调用 findRegistries（来自 ~/.config/add-mcp/config.json）拼接查询参数，HTTP 端点需返回符合官方 schema 的 JSON：

flowchart LR
  A[find 命令] --> B[读取 config.json]
  B --> C[遍历 findRegistries]
  C --> D[GET url?search=&version=latest&limit=100]
  D --> E[解析 servers 数组]
  E --> F[clack prompts 选择]
  F --> G[复用安装流程写入 agent 配置]

来源与请求格式在 README「Adding a Custom Registry」一节有完整示例 README.md。registry.json 则维护了官方策划的服务器集合，每个条目使用 https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json 校验 registry.json。

5. 常见失败模式与变通

• 代理安装路径异常：Claude Desktop 通过 msix 安装到 Windows 时配置目录与预期不同，issue #50 仍在跟踪 issue #50。遇到此类情况可改用 -a 显式指定 agent，或将 CLI 作为库直接调用。
• 远程 HTTP 认证：issue #51 提出对 OAuth scopes、authProviderType 等认证参数的需求 issue #51；当前版本仅支持 --header 透传认证头，更复杂的 OAuth 流需依赖宿主代理自身。
• 环境变量配置：issue #15 中用户询问 --env 用法 issue #15；推荐使用 ${VAR} 占位 + 交互模式以避免在 shell 历史中泄露密钥。
• 移除已废弃服务器：issue #16 请求 remove 能力 issue #16，已在 v1.10.0 通过程序化 API 暴露，可直接调用 remove 函数 src/lib.ts。

See Also

• README.md — 完整使用说明与代理配置路径表
• CHANGELOG.md — 版本变更日志
• src/types.ts — AgentConfig / McpServerConfig 类型
• src/lib.ts — detect / upsert / remove 程序化 API
• docs/RELEASING.md — 发布流程与 npm Trusted Publishing 配置

架构、源码结构与编程式 API

1. 项目定位与边界

add-mcp 是一款命令行工具（CLI），用单条命令将 MCP（Model Context Protocol）服务器安装到多个主流编码代理中。package.json 的描述为 "Add MCP servers to your favorite coding agents with a single command."，并以 Apache-2.0 协议发布。资料来源：package.json:2-5。

README 中明确支持的代理包括 claude-code、claude-desktop、codex、cursor、gemini-cli、goose、github-copilot-cli、mcporter、opencode、vscode、windsurf、zed 等。同一份项目元数据（package.json 的 keywords 数组）也列出这些代理名称作为搜索关键词，表明代理清单在 CLI 与打包元数据之间保持一致。资料来源：package.json:keywords、README.md:Agent table。

仓库使用 bun 作为包管理器，并通过 bun run test 与 bun run typecheck 跑测试与类型检查；CI 中 Fallow 以建议模式运行（不强制失败）。资料来源：CLAUDE.md:Dev environment。

2. 源码结构与构建产物

源码入口与构建产物在 package.json 中显式声明，便于既作 CLI 运行又作库导入：

资料来源：package.json:main,types,exports,bin,engines。

构建脚本 tsup src/index.ts src/lib.ts --format esm --dts --clean 表明源码入口为 src/index.ts（CLI）与 src/lib.ts（库），打包为单一 ESM 格式并生成 .d.ts 类型声明。资料来源：package.json:scripts.build。

运行时依赖按职责划分：@clack/prompts 处理交互提示，@iarna/toml 解析 TOML 配置，chalk 输出着色，commander 解析 CLI 参数，js-yaml 解析 YAML，jsonc-parser 解析带注释的 JSON。资料来源：package.json:dependencies。

3. 编程式 API（Programmatic API）

自 v1.10.0 起，add-mcp 公开编程式 API detect / upsert / remove，供其他工具作为库引用（社区公告原文："expose a programmatic API (detect / upsert / remove) for use as a library in addition to the CLI"）。该 API 通过 ESM 入口 dist/lib.js 与类型声明 dist/lib.d.ts 暴露，使用者无需关心内部目录布局：

import { detect, upsert, remove } from "add-mcp";

exports["."] 字段将 "." 映射到 ./dist/lib.d.ts（types）与 ./dist/lib.js（import），保证 Node 与 TypeScript 用户开箱即用。资料来源：package.json:exports。

社区中"add remove mcp ability"（#16）议题反映了 remove API 的实际用户需求：当初次安装的 MCP 服务被弃用时，CLI 与库用户都需要一条稳定的卸载路径。配合 upsert 与 detect，三者构成"查找—安装—移除"的完整生命周期。资料来源：package.json:bin（命令行入口同样调用相同核心）。

4. JSON 配置格式层

src/formats/json.ts 处理带 JSONC 注释的代理配置文件，典型如 Claude Desktop、Cursor、VS Code 等使用 JSON 家族格式的代理。关键行为如下：

• 读取时使用 jsonc.parse 容忍注释与尾逗号，函数签名为 readJsonConfig(filePath): ConfigFile。资料来源：src/formats/json.ts:readJsonConfig。
• 写入时优先保留原始缩进（detectIndent）并以 jsonc.modify / applyEdits 做原地编辑，失败回退到 JSON.stringify，函数签名为 writeJsonConfig(filePath, config, configKey)。资料来源：src/formats/json.ts:writeJsonConfig。
• 删除时通过 removeJsonConfigKey 对 configKey（支持点号嵌套路径，如 mcpServers.foo）进行结构化移除，避免误删相邻键。资料来源：src/formats/json.ts:removeJsonConfigKey。
• 目录不存在时自动 mkdirSync(dir, { recursive: true })，适配首次安装场景。资料来源：src/formats/json.ts:writeJsonConfig。

configKey 的点号路径设计是 JSON 格式层的关键抽象：它允许上层逻辑以"代理无关"的方式描述"我要修改嵌套对象中的某个键"，而具体嵌套层级由各代理在其配置中自行约定（例如 Claude Desktop 使用 mcpServers 顶层键，VS Code 在工程根的 .vscode/mcp.json 中同样使用 servers）。

flowchart LR
  A[用户命令 / 库调用] --> B[upsert / detect / remove]
  B --> C{目标代理格式}
  C -->|JSON / JSONC| D[formats/json.ts]
  C -->|TOML| E[formats/toml.ts]
  C -->|YAML| F[formats/yaml.ts]
  D --> G[代理配置文件]
  E --> G
  F --> G

v1.10.2 修复了"Space character in server path breaks settings"（#29）——带空格的可执行路径会被错误切分为 command + args。修复后，包含绝对路径、home 相对路径、点相对路径、Windows 盘符路径的命令被原样保留为单一可执行命令；这一修复同时影响到 JSON / TOML / YAML 各类格式层的"目标命令"处理。资料来源：v1.10.2 release notes。

registry.json 是内置的可发现服务器目录，遵循 https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json 模式描述 npm/OCI 包与 streamable-http 远程端点。资料来源：registry.json:server.$schema。社区曾通过 #35 申请将 io.github.packrift/packrift-mcp 加入此注册表。

5. 发布与可信供应链

add-mcp 通过 GitHub Actions 发布到 npm，启用 npm Trusted Publishing（OIDC）与 provenance attestation；维护者在本地不支持 npm publish，必须走流水线。CHANGELOG.md 仅记录面向用户的变更；开发者须知由 CLAUDE.md 与 AGENTS.md 维护，二者内容目前一致。资料来源：CLAUDE.md:Releasing、AGENTS.md:Releasing。

See Also

• 项目主仓库：neon-solutions/add-mcp
• 发布流程：docs/RELEASING.md
• 相关议题：#16（移除 MCP）、#29（路径中的空格）、#35（注册表收录申请）、#50（Claude Desktop on Windows MSIX 兼容性）

注册表（Registry）结构与维护

add-mcp 在仓库根目录维护一份精选注册表 registry.json，其条目遵循官方 MCP 服务器描述规范 $schema: https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json（个别早期条目仍引用 2025-09-29 版本）。每个服务器声明 name、title、description、版本号、可选的 websiteUrl 与图标，并提供 packages（包形式：npm、oci 等）与 remotes（远程 streamable-http / sse）两类传输方式。资料来源：registry.json

注册表通过 npm 脚本进行整理与校验：npm run registry:sort 用于统一条目顺序以便审阅，npm run registry:verify 负责检查 schema 一致性。资料来源：package.json

当用户执行 add-mcp find <query> 或基于注册表安装时，CLI 会从这份本地注册表匹配条目并提示选择，再结合 packageArguments、environmentVariables 与 headers 模板生成最终的服务器配置；${VAR} 占位符会在交互模式下被提示输入。资料来源：CHANGELOG.md

智能体配置（Agent Configuration）

add-mcp 的核心抽象是“智能体适配器”映射表，统一不同 AI 编码助手的配置文件位置、格式与键名。下表汇总了截至 v1.10.4 已支持的智能体、本地与全局配置路径：

资料来源：README.md（Windsurf 自 v1.10.3 起支持）

CLI 通过 -g/--global 与 --name 等标志将同一份服务器规范写入对应智能体的本地或全局文件；配置文件支持 JSON、JSONC、YAML 与 TOML 四种格式，写入前会保留注释、缩进与原始顺序。

常见故障排查

以下是社区反馈与发布说明中整理出的高频问题速查表：

1. 路径中包含空格导致命令被拆分。v1.10.0 之前 add-mcp "/Applications/My App/bin/server" 会被误切为 command: "/Applications/My"，其余部分变成参数；v1.10.2 起改为识别绝对路径、~ 相对、. 相对与 Windows 盘符路径，将其整体作为单一可执行命令保留。资料来源：v1.10.2 / Issue #29
2. 空环境变量值。--env "KEY=" 在 v1.9.1 之前会原样写入导致服务器启动失败；现在会拒绝写入并提示可能由 shell 提前展开了 ${VAR}。--header 的空值同样会给出 shell 展开提示。资料来源：v1.9.1
3. Windows MSIX 安装路径不正确。Claude Desktop 通过 MSIX 安装时，add-mcp 写入的路径与实际安装位置不一致；用户需确认安装方式或自定义目标。资料来源：Issue #50
4. 远程 HTTP 缺少鉴权参数。当前尚不支持 OAuth scopes、authProviderType 等远程鉴权参数；如需为远程 MCP 服务器设置凭据，请临时改用本地 stdio 形式或手动编辑配置文件。资料来源：Issue #51
5. 需要移除已安装的 MCP。社区已在 #16 中提出 remove 子命令需求，自 v1.10.0 起可使用程序化 API 中的 remove 函数，CLI 包装命令的演进请关注后续 release。资料来源：v1.10.0
6. 环境变量模板未替换。${VAR} 占位符会在交互式安装时被提示输入；非交互模式下需提前在 shell 中导出变量，避免被静默丢弃。

程序化 API 与发布流程

add-mcp 既是命令行也是 npm 库：package.json 的 exports 指向 ./dist/lib.js 与类型声明 ./dist/lib.d.ts，对外暴露 detect / upsert / remove 三个核心函数，便于在测试、CI 或自定义安装器中复用同一套配置写入逻辑。资料来源：package.json

发布方面，仓库使用 npm Trusted Publishing（OIDC）加来源证明（provenance attestation），由锁定的 GitHub Actions 流水线执行 npm stage publish，并要求维护者通过 WebAuthn 二次确认；本地 npm publish 不受支持。所有变更需先让 bun run test 通过，再交由流水线产出。资料来源：CLAUDE.md / AGENTS.md

Pitfall Log / 踩坑日志

项目：neon-solutions/add-mcp

摘要：发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Add Packrift MCP server to registry。

1. 安装坑 · 来源证据：Add Packrift MCP server to registry

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add Packrift MCP server to registry
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_a249cc57446f4702b71205d7038f7364 | https://github.com/neon-solutions/add-mcp/issues/35 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：Compatibility Issue: Does not work with Claude Desktop on Windows when installed as msix package

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Compatibility Issue: Does not work with Claude Desktop on Windows when installed as msix package
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_482e954ed77d4d81aef0eef2d4e3a3e3 | https://github.com/neon-solutions/add-mcp/issues/50 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

3. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | npm_package:add-mcp | https://www.npmjs.com/package/add-mcp | README/documentation is current enough for a first validation pass.

4. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | npm_package:add-mcp | https://www.npmjs.com/package/add-mcp | last_activity_observed missing

5. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | npm_package:add-mcp | https://www.npmjs.com/package/add-mcp | no_demo; severity=medium

6. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | npm_package:add-mcp | https://www.npmjs.com/package/add-mcp | no_demo; severity=medium

7. 安全/权限坑 · 来源证据：Support authentication parameters for remote HTTP configurations

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Support authentication parameters for remote HTTP configurations
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_09d1044faf824f248317ee044ca27240 | https://github.com/neon-solutions/add-mcp/issues/51 | 来源类型 github_issue 暴露的待验证使用条件。

8. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | npm_package:add-mcp | https://www.npmjs.com/package/add-mcp | issue_or_pr_quality=unknown

9. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | npm_package:add-mcp | https://www.npmjs.com/package/add-mcp | release_recency=unknown