# https://github.com/neon-solutions/add-mcp 项目说明书 生成时间：2026-06-06 07:53:43 UTC ## 目录 - [Overview and Supported Agents](#page-overview) - [CLI Commands Reference](#page-commands) - [Architecture, Source Structure, and Programmatic API](#page-architecture) - [Registries, Configuration, and Troubleshooting](#page-registries-config) ## Overview and Supported Agents ### 相关页面 相关主题：[CLI Commands Reference](#page-commands), [Architecture, Source Structure, and Programmatic API](#page-architecture)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/neon-solutions/add-mcp/blob/main/README.md) - [package.json](https://github.com/neon-solutions/add-mcp/blob/main/package.json) - [src/find.ts](https://github.com/neon-solutions/add-mcp/blob/main/src/find.ts) - [src/agents.ts](https://github.com/neon-solutions/add-mcp/blob/main/src/agents.ts) - [src/lib.ts](https://github.com/neon-solutions/add-mcp/blob/main/src/lib.ts) - [CLAUDE.md](https://github.com/neon-solutions/add-mcp/blob/main/CLAUDE.md) - [AGENTS.md](https://github.com/neon-solutions/add-mcp/blob/main/AGENTS.md) - [registry.json](https://github.com/neon-solutions/add-mcp/blob/main/registry.json)
# 概述与支持的代理 (Overview and Supported Agents) ## 项目目的与定位 `add-mcp` 是一个使用 Node.js（要求 `node >= 18`，见 [package.json:73-75](https://github.com/neon-solutions/add-mcp/blob/main/package.json#L73-L75)）编写的命令行工具，核心使命是「**通过一条命令，将 MCP（Model Context Protocol）服务器安装到多种主流 AI 编码代理的配置文件中**」。其官方定位为 "Add MCP servers to your favorite coding agents with a single command."（[package.json:3](https://github.com/neon-solutions/add-mcp/blob/main/package.json#L3)）。 该工具同时提供编程式 API（`detect` / `upsert` / `remove`），自 v1.10.0 起可通过 `import` 方式作为库被调用（见 [CHANGELOG 引用：v1.10.0](https://github.com/neon-solutions/add-mcp/releases/tag/v1.10.0)）。开发说明位于 [CLAUDE.md](https://github.com/neon-solutions/add-mcp/blob/main/CLAUDE.md) 与 [AGENTS.md](https://github.com/neon-solutions/add-mcp/blob/main/AGENTS.md)，并以 `bun` 作为包管理器与脚本执行器。 ## 支持的代理清单 下表汇总了 `add-mcp` 当前支持的代理、CLI 标识符以及本地与全局配置文件路径（整理自 [README.md](https://github.com/neon-solutions/add-mcp/blob/main/README.md) 与 [package.json:32-47](https://github.com/neon-solutions/add-mcp/blob/main/package.json#L32-L47) 中的 `keywords` 字段）： | 代理 (Agent) | CLI 标识 | 项目级配置 | 全局配置 | |---|---|---|---| | Claude Code | `claude-code` | `.mcp.json` | `~/.claude.json` | | Claude Desktop | `claude-desktop` | - | `~/Library/Application Support/Claude/claude_desktop_config.json` | | Codex | `codex` | `.codex/config.toml` | `~/.codex/config.toml` | | Cursor | `cursor` | `.cursor/mcp.json` | `~/.cursor/mcp.json` | | Gemini CLI | `gemini-cli` | `.gemini/settings.json` | `~/.gemini/settings.json` | | Goose | `goose` | `.goose/config.yaml` | `~/.config/goose/config.yaml` | | GitHub Copilot CLI | `github-copilot-cli` | `.vscode/mcp.json` | `~/.copilot/mcp-config.json` | | MCPorter | `mcporter` | `config/mcporter.json` | `~/.mcporter/mcporter.json`（或 `mcporter.jsonc`） | | OpenCode | `opencode` | `opencode.json` | `~/.config/opencode/opencode.json` | | VS Code | `vscode` | `.vscode/mcp.json` | `~/Library/Application Support/Code/User/mcp.json` | | Windsurf | `windsurf` | - | `~/.codeium/windsurf/mcp_config.json` | | Zed | `zed` | `.zed/settings.json` | `~/Library/Application Support/Zed/...` | Windsurf 支持自 v1.10.3 加入，并提供 `codeium` 与 `cascade` 别名（见 [CHANGELOG：v1.10.3](https://github.com/neon-solutions/add-mcp/releases/tag/v1.10.3)）；GitHub Copilot CLI 支持源自社区请求 [#4](https://github.com/neon-solutions/add-mcp/issues/4)，其全局路径遵循 Copilot CLI 规范（`~/.copilot/mcp-config.json`）。 ## 核心能力与命令模式 CLI 主入口为 `src/index.ts`（编译后位于 `dist/index.js`，见 [package.json:55-57](https://github.com/neon-solutions/add-mcp/blob/main/package.json#L55-L57)），其下组织三大能力： 1. **直接安装命令** — 接受命令名、参数、环境变量、HTTP/SSE header 等，将一条 MCP 服务器记录写入所选代理的配置文件；库 API 名为 `upsert`（[src/lib.ts](https://github.com/neon-solutions/add-mcp/blob/main/src/lib.ts)）。 2. **交互式发现 (`find`)** — 从一个或多个 MCP 注册表（如仓库内置的 [registry.json](https://github.com/neon-solutions/add-mcp/blob/main/registry.json)）中搜索服务器、提示缺失的 `${VAR}` 模板值、并把搜索结果落盘到目标代理。该流程的类型定义集中在 [src/find.ts:1-58](https://github.com/neon-solutions/add-mcp/blob/main/src/find.ts#L1-L58)，包括 `FindCommandOptions`、`FindInstallPlan`、`PromptField` 等。 3. **删除命令 (`remove`)** — 移除已弃用的 MCP 服务器记录，对应社区需求 [#16](https://github.com/neon-solutions/add-mcp/issues/16)。 路径处理在 v1.10.2 进行了关键回归修复：带空格的绝对路径、home-relative（`~/...`）、dot-relative（`./...`）以及 Windows 盘符路径会被完整保留为单一可执行命令，避免被空格拆分为 `command` + `args`（见 [CHANGELOG：v1.10.2](https://github.com/neon-solutions/add-mcp/releases/tag/v1.10.2)）。v1.9.1 起 `--env "KEY="`（空值）会被显式拒绝，并在 `${VAR}` 似乎被 shell 吞掉时给出提示（见 [CHANGELOG：v1.9.1](https://github.com/neon-solutions/add-mcp/releases/tag/v1.9.1)）。 ## 社区反馈与已知边界 - **远程认证能力待增强**：[#51](https://github.com/neon-solutions/add-mcp/issues/51) 提出需为 `streamable-http` 远程配置增加 OAuth scopes、`authProviderType` 与连接超时等认证参数。 - **Windows MSIX 安装兼容性问题**：[#50](https://github.com/neon-solutions/add-mcp/issues/50) 反馈在 Windows 上以 MSIX 形式安装 Claude Desktop 后，工具写入/同步路径不正确。 - **LM Studio 支持请求**：[#24](https://github.com/neon-solutions/add-mcp/issues/24) 提议增加 LM Studio 适配（macOS 路径建议为 `~/.lmstudio/mcp.json`），目前尚未在 `package.json` 的 `keywords` 中列出。 - **环境变量配置指南**：[#15](https://github.com/neon-solutions/add-mcp/issues/15) 询问如何为 MCP 服务器设置环境变量，建议优先使用 v1.9.0 引入的交互式 `${VAR}` 提示能力（[CHANGELOG：v1.9.0](https://github.com/neon-solutions/add-mcp/releases/tag/v1.9.0)）。 ## See Also - [Registry and `find` Workflow](./registry-and-find-workflow.md) - [CLI Command Reference](./cli-command-reference.md) - [Library API (`detect` / `upsert` / `remove`)](./library-api.md) - [Releasing & npm Provenance](./releasing.md) --- ## CLI Commands Reference ### 相关页面 相关主题：[Overview and Supported Agents](#page-overview), [Registries, Configuration, and Troubleshooting](#page-registries-config), [Architecture, Source Structure, and Programmatic API](#page-architecture)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/neon-solutions/add-mcp/blob/main/README.md) - [CHANGELOG.md](https://github.com/neon-solutions/add-mcp/blob/main/CHANGELOG.md) - [package.json](https://github.com/neon-solutions/add-mcp/blob/main/package.json) - [src/index.ts](https://github.com/neon-solutions/add-mcp/blob/main/src/index.ts) - [src/lib.ts](https://github.com/neon-solutions/add-mcp/blob/main/src/lib.ts) - [src/types.ts](https://github.com/neon-solutions/add-mcp/blob/main/src/types.ts) - [src/installer.ts](https://github.com/neon-solutions/add-mcp/blob/main/src/installer.ts) - [registry.json](https://github.com/neon-solutions/add-mcp/blob/main/registry.json)
# CLI Commands Reference `add-mcp` 是一个面向多种 AI 编码代理的 Model Context Protocol（MCP）服务器安装工具，通过单一命令行将服务器写入对应代理的配置文件。本文汇总当前版本（v1.10.4）的全部命令行入口、参数语义及行为变更。 ## 1. 命令体系总览 `add-mcp` 通过 Commander.js 注册顶层命令，并在 `package.json` 中以 `bin.add-mcp` 暴露可执行入口 [package.json](https://github.com/neon-solutions/add-mcp/blob/main/package.json)。三条核心子命令及语义如下： | 命令 | 用途 | 主要行为 | | --- | --- | --- | | `add-mcp ` | 默认安装命令 | 解析 source（远程 URL / 包名 / 命令），写入目标代理的 mcp 配置 | | `add-mcp list` | 列出已安装的服务器 | 扫描项目与全局目录，输出当前 agent 的 mcp 列表 | | `add-mcp find` | 从注册表搜索 | 调用 `findRegistries` 中的注册表，提示用户选择安装 | 顶层标志（适用于安装命令）包括 `-g/--global`、`-a/--agent`、`--name`、`--env`、`-h/--header` 等，详见 README 表格 [README.md](https://github.com/neon-solutions/add-mcp/blob/main/README.md)。 ## 2. 默认安装命令 默认命令根据 `source` 字符串推断类型：URL 视作远程，npm/oci 包名视作 `package`，其余被视作本地命令 [src/types.ts:SourceType](https://github.com/neon-solutions/add-mcp/blob/main/src/types.ts)。 ```bash # 本地 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](https://github.com/neon-solutions/add-mcp/blob/main/CHANGELOG.md)。社区问题 #29「Space character in server path breaks settings」中报告的 `/Applications/Hopper Disassembler.app/...` 场景已被该版本覆盖 [issue #29](https://github.com/neon-solutions/add-mcp/issues/29)。 - `--env "KEY="`（空值）会被拒绝并提示可能的 shell 变量被吞，源自 v1.9.1 [CHANGELOG.md:1.9.1](https://github.com/neon-solutions/add-mcp/blob/main/CHANGELOG.md)。 - 交互模式下，`${VAR}` 占位符在 `--env`/`--header`/`--args` 中会逐一提示；可选 key 跳过则不会写入配置 [CHANGELOG.md:1.9.0](https://github.com/neon-solutions/add-mcp/blob/main/CHANGELOG.md)。 - v1.10.4 新增 `-h` 作为 `--header` 的简写 [CHANGELOG.md:1.10.4](https://github.com/neon-solutions/add-mcp/blob/main/CHANGELOG.md)。 - v1.10.0 起同时暴露 `detect` / `upsert` / `remove` 程序化 API，可作为库使用 [src/lib.ts](https://github.com/neon-solutions/add-mcp/blob/main/src/lib.ts) [CHANGELOG.md:1.10.0](https://github.com/neon-solutions/add-mcp/blob/main/CHANGELOG.md)。 ## 3. `list` 子命令 `list` 用于查看已写入配置的 MCP 服务器： ```bash npx add-mcp list # 扫描所有检测到的代理 npx add-mcp list -g # 列出全局配置 npx add-mcp list -a cursor # 指定代理（即使未检测到也会显示） ``` 底层通过读取各 agent 的 `localConfigKey` / `configKey`（点号路径）来定位服务器项 [src/types.ts:AgentConfig](https://github.com/neon-solutions/add-mcp/blob/main/src/types.ts)。每个 agent 的本地与全局配置路径在 README 的表格中给出，例如 `claude-code` 本地为 `.mcp.json`、全局为 `~/.claude.json` [README.md](https://github.com/neon-solutions/add-mcp/blob/main/README.md)。 ## 4. `find` 子命令与自定义注册表 `find` 调用 `findRegistries`（来自 `~/.config/add-mcp/config.json`）拼接查询参数，HTTP 端点需返回符合官方 schema 的 JSON： ```mermaid 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](https://github.com/neon-solutions/add-mcp/blob/main/README.md)。`registry.json` 则维护了官方策划的服务器集合，每个条目使用 `https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json` 校验 [registry.json](https://github.com/neon-solutions/add-mcp/blob/main/registry.json)。 ## 5. 常见失败模式与变通 - **代理安装路径异常**：Claude Desktop 通过 msix 安装到 Windows 时配置目录与预期不同，issue #50 仍在跟踪 [issue #50](https://github.com/neon-solutions/add-mcp/issues/50)。遇到此类情况可改用 `-a` 显式指定 agent，或将 CLI 作为库直接调用。 - **远程 HTTP 认证**：issue #51 提出对 OAuth scopes、`authProviderType` 等认证参数的需求 [issue #51](https://github.com/neon-solutions/add-mcp/issues/51)；当前版本仅支持 `--header` 透传认证头，更复杂的 OAuth 流需依赖宿主代理自身。 - **环境变量配置**：issue #15 中用户询问 `--env` 用法 [issue #15](https://github.com/neon-solutions/add-mcp/issues/15)；推荐使用 `${VAR}` 占位 + 交互模式以避免在 shell 历史中泄露密钥。 - **移除已废弃服务器**：issue #16 请求 `remove` 能力 [issue #16](https://github.com/neon-solutions/add-mcp/issues/16)，已在 v1.10.0 通过程序化 API 暴露，可直接调用 `remove` 函数 [src/lib.ts](https://github.com/neon-solutions/add-mcp/blob/main/src/lib.ts)。 ## See Also - [README.md](https://github.com/neon-solutions/add-mcp/blob/main/README.md) — 完整使用说明与代理配置路径表 - [CHANGELOG.md](https://github.com/neon-solutions/add-mcp/blob/main/CHANGELOG.md) — 版本变更日志 - [src/types.ts](https://github.com/neon-solutions/add-mcp/blob/main/src/types.ts) — AgentConfig / McpServerConfig 类型 - [src/lib.ts](https://github.com/neon-solutions/add-mcp/blob/main/src/lib.ts) — `detect` / `upsert` / `remove` 程序化 API - [docs/RELEASING.md](https://github.com/neon-solutions/add-mcp/blob/main/docs/RELEASING.md) — 发布流程与 npm Trusted Publishing 配置 --- ## Architecture, Source Structure, and Programmatic API ### 相关页面 相关主题：[Overview and Supported Agents](#page-overview), [CLI Commands Reference](#page-commands), [Registries, Configuration, and Troubleshooting](#page-registries-config)
相关源码文件 以下源码文件用于生成本页说明： - [package.json](https://github.com/neon-solutions/add-mcp/blob/main/package.json) - [README.md](https://github.com/neon-solutions/add-mcp/blob/main/README.md) - [CLAUDE.md](https://github.com/neon-solutions/add-mcp/blob/main/CLAUDE.md) - [AGENTS.md](https://github.com/neon-solutions/add-mcp/blob/main/AGENTS.md) - [src/formats/json.ts](https://github.com/neon-solutions/add-mcp/blob/main/src/formats/json.ts) - [registry.json](https://github.com/neon-solutions/add-mcp/blob/main/registry.json)
# 架构、源码结构与编程式 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](https://github.com/fallow-rs/fallow)` 以建议模式运行（不强制失败）。资料来源：[CLAUDE.md:Dev environment]()。 ## 2. 源码结构与构建产物 源码入口与构建产物在 `package.json` 中显式声明，便于既作 CLI 运行又作库导入： | 字段 | 值 | 作用 | | --- | --- | --- | | `main` | `./dist/lib.js` | 库的运行时入口 | | `types` | `./dist/lib.d.ts` | 库的 TypeScript 类型入口 | | `bin` | `add-mcp: dist/index.js` | 可执行 CLI 入口 | | `exports["."]` | `types + import` | `import "add-mcp"` 解析路径 | | `engines.node` | `>=18` | 最低 Node 版本 | 资料来源：[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` 暴露，使用者无需关心内部目录布局： ```js 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`）。 ```mermaid 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](https://github.com/neon-solutions/add-mcp) - 发布流程：[docs/RELEASING.md](https://github.com/neon-solutions/add-mcp/blob/main/docs/RELEASING.md) - 相关议题：#16（移除 MCP）、#29（路径中的空格）、#35（注册表收录申请）、#50（Claude Desktop on Windows MSIX 兼容性） --- ## Registries, Configuration, and Troubleshooting ### 相关页面 相关主题：[CLI Commands Reference](#page-commands), [Architecture, Source Structure, and Programmatic API](#page-architecture), [Overview and Supported Agents](#page-overview)
相关源码文件 以下源码文件用于生成本页说明： - [registry.json](https://github.com/neon-solutions/add-mcp/blob/main/registry.json) - [package.json](https://github.com/neon-solutions/add-mcp/blob/main/package.json) - [CLAUDE.md](https://github.com/neon-solutions/add-mcp/blob/main/CLAUDE.md) - [AGENTS.md](https://github.com/neon-solutions/add-mcp/blob/main/AGENTS.md) - [README.md](https://github.com/neon-solutions/add-mcp/blob/main/README.md) - [CHANGELOG.md](https://github.com/neon-solutions/add-mcp/blob/main/CHANGELOG.md)
# Registries, Configuration, and Troubleshooting 本文聚焦 `add-mcp` 的三大运维主题：注册表（registry）、智能体（agent）配置与故障排查。它们相互配合，让用户既能基于精选注册表一键安装 MCP 服务器，也能把同一份服务器规范分发到不同 AI 编码助手的本地或全局配置中。 ## 注册表（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 ` 或基于注册表安装时，CLI 会从这份本地注册表匹配条目并提示选择，再结合 `packageArguments`、`environmentVariables` 与 `headers` 模板生成最终的服务器配置；`${VAR}` 占位符会在交互模式下被提示输入。资料来源：[CHANGELOG.md]() ## 智能体配置（Agent Configuration） `add-mcp` 的核心抽象是“智能体适配器”映射表，统一不同 AI 编码助手的配置文件位置、格式与键名。下表汇总了截至 v1.10.4 已支持的智能体、本地与全局配置路径： | 智能体 | 关键字 | 本地路径 | 全局路径 | | --- | --- | --- | --- | | Claude Code | `claude-code` | `.mcp.json` | `~/.claude.json` | | Claude Desktop | `claude-desktop` | — | `~/Library/Application Support/Claude/claude_desktop_config.json` | | Codex | `codex` | `.codex/config.toml` | `~/.codex/config.toml` | | Cursor | `cursor` | `.cursor/mcp.json` | `~/.cursor/mcp.json` | | Gemini CLI | `gemini-cli` | `.gemini/settings.json` | `~/.gemini/settings.json` | | Goose | `goose` | `.goose/config.yaml` | `~/.config/goose/config.yaml` | | GitHub Copilot CLI | `github-copilot-cli` | `.vscode/mcp.json` | `~/.copilot/mcp-config.json` | | MCPorter | `mcporter` | `config/mcporter.json` | `~/.mcporter/mcporter.json`（或 `.jsonc`） | | OpenCode | `opencode` | `opencode.json` | `~/.config/opencode/opencode.json` | | VS Code | `vscode` | `.vscode/mcp.json` | `~/Library/Application Support/Code/User/mcp.json` | | Windsurf | `windsurf`（别名 `codeium`、`cascade`） | — | `~/.codeium/windsurf/mcp_config.json` | | Zed | `zed` | `.zed/settings.json` | `~/Library/Application Support/Zed/settings.json` | 资料来源：[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](https://github.com/neon-solutions/add-mcp/releases/tag/v1.10.2) / [Issue #29](https://github.com/neon-solutions/add-mcp/issues/29) 2. **空环境变量值**。`--env "KEY="` 在 v1.9.1 之前会原样写入导致服务器启动失败；现在会拒绝写入并提示可能由 shell 提前展开了 `${VAR}`。`--header` 的空值同样会给出 shell 展开提示。资料来源：[v1.9.1](https://github.com/neon-solutions/add-mcp/releases/tag/v1.9.1) 3. **Windows MSIX 安装路径不正确**。Claude Desktop 通过 MSIX 安装时，`add-mcp` 写入的路径与实际安装位置不一致；用户需确认安装方式或自定义目标。资料来源：[Issue #50](https://github.com/neon-solutions/add-mcp/issues/50) 4. **远程 HTTP 缺少鉴权参数**。当前尚不支持 OAuth scopes、`authProviderType` 等远程鉴权参数；如需为远程 MCP 服务器设置凭据，请临时改用本地 `stdio` 形式或手动编辑配置文件。资料来源：[Issue #51](https://github.com/neon-solutions/add-mcp/issues/51) 5. **需要移除已安装的 MCP**。社区已在 #16 中提出 `remove` 子命令需求，自 v1.10.0 起可使用程序化 API 中的 `remove` 函数，CLI 包装命令的演进请关注后续 release。资料来源：[v1.10.0](https://github.com/neon-solutions/add-mcp/releases/tag/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]() --- --- ## Doramagic 踩坑日志 项目：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