1. 项目定位与核心目标

add-mcp 是一个面向多 AI 编程助手的 Model Context Protocol（MCP）服务器统一注册工具，同时提供 CLI 与可编程库两种使用方式。它的核心目标是把分散在 Claude Desktop、Cursor、VS Code、Windsurf（别名 codeium、cascade）等客户端中的 mcp_config.json / mcp.json / claude_desktop_config.json 等配置文件统一抽象为一组命令，让用户不必逐个编辑 JSON 就能完成 MCP 服务器的注册、删除与发现。资料来源：README.md:1-40

从架构上看，工具承担了三类职责：检测当前机器上哪些 agent 已安装（detect）、将服务器条目写入对应的 agent 配置（upsert）、以及将条目从配置中清除（remove）。v1.10.0 之后，这三类能力被同时暴露为 CLI 子命令和库 API，外部项目可作为依赖直接调用。资料来源：CHANGELOG.md:1-40、资料来源：src/index.ts:1-40

2. 安装与基本使用

工具以 npm 包形式分发，安装后即可使用 add-mcp 命令：

# 本地或全局安装
npm install -g add-mcp

# 注册一个 stdio 类型的本地服务器（全局作用域）
add-mcp -g /usr/local/bin/my-mcp-server --name my-server

# 注册一个远程 HTTP/SSE 服务器并附加请求头
add-mcp --name remote-mcp \
        --url https://example.com/mcp \
        --header "Authorization: Bearer ${TOKEN}"

核心标志包括：--name 指定服务器在配置中的键名；--env KEY=VALUE 注入环境变量；--args 透传命令行参数；--url 切换为远程传输；-g / --global 强制写入全局配置（默认推断为项目级）。-y 用于跳过交互式确认。资料来源：src/cli.ts:1-60

自 v1.9.0 起，交互模式下若 ${VAR} 模板未在 shell 中展开，CLI 会主动提示用户输入；空值会被拒绝（v1.9.1），避免静默写入导致运行时崩溃。资料来源：CHANGELOG.md:1-60

3. 支持的 Agent、作用域与传输

add-mcp 通过一个 agent 注册表驱动所有写入目标，每个 agent 描述其配置文件路径、是否支持全局 / 项目双作用域、支持的传输类型（stdio / http / sse）。例如 Windsurf 的全局路径为 ~/.codeium/windsurf/mcp_config.json（mcpServers），新增于 v1.10.3。资料来源：src/agents/index.ts:1-80、资料来源：CHANGELOG.md:1-60

下表给出常见目标的配置位置（行为以当前代码为准）：

v1.13.0 引入“统一作用域”：当选择集合中包含仅支持全局的 agent 时，整次运行统一走全局，避免项目与全局配置混杂；同一版本也加入了当所有选中 agent 均支持双作用域时的交互式 scope 提问。资料来源：CHANGELOG.md:1-60

远程 HTTP 配置方面，社区已多次请求 OAuth scopes、authProviderType、连接超时等参数（#51），以及用 mcp-remote 自动包装 Claude Desktop 不原生支持的远程服务器（#58）。资料来源：README.md:1-60

4. 编程接口与版本演进

v1.10.0 之后，库的公共入口导出 detect、upsert、remove 三个函数，外部程序可将其作为依赖嵌入到自动化脚本中：

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

const agents = await detect();
await upsert({
  name: "my-server",
  command: "/usr/local/bin/my-mcp-server",
  scope: "global",
});
await remove("my-server");

发布链路使用 npm Trusted Publishing（OIDC）并附带 provenance attestation，过程文档化在 docs/RELEASING.md。资料来源：docs/RELEASING.md:1-40

find / search 子命令从公共注册中心检索 MCP 服务器。默认注册中心自 v1.14.0 起迁移至 https://add-mcp.com/registry/api/v1/servers（标签为 “add-mcp registry”）；旧的 mcp.agent-tooling.dev 仍可访问，已保存配置会在下次 find 时自动迁移并去重。v1.13.1/v1.13.2 进一步整合了 integrations.sh 数据，列表项显示真实的安装目标（远端 URL 或包名）而非反向域名。资料来源：src/registry/index.ts:1-80、资料来源：CHANGELOG.md:1-80

需要重点提示的是 v2.0.0 的破坏性变更：在已存在的 name 下重新安装服务器时，新条目会整体替换旧条目，而不再做字段级深合并。这避免了陈旧字段拼装出无效的混合配置（参见 #29 关于路径含空格导致 command 被截断的回归）。调用方若需要保留某些字段，必须显式传入完整配置。资料来源：CHANGELOG.md:1-40

add-mcp 是一个面向多种 AI 编码代理（Claude Desktop、VS Code、Cursor、Windsurf、GitHub Copilot CLI 等）的命令行工具，用于在全局（用户级）或项目（工作区级）配置中注册、查询与移除 MCP（Model Context Protocol）服务器条目。本页汇总其命令结构、参数语义、交互行为与已知边界，依据社区证据与源码定位整理。

命令结构与顶层入口

CLI 顶层由 src/index.ts 中的参数解析与命令分派逻辑组成。最常见的用法无需显式子命令：

add-mcp [flags] <command-or-url>

可选子命令包括 find（亦写作 search）、remove，以及自 v1.10.0 起以库形式暴露的程序化 API（detect / upsert / remove）。资料来源：src/index.ts:1-80

未传入子命令时，CLI 视为「添加服务器」模式：把 <command-or-url> 解析为 stdio 命令或远程 HTTP URL，写入选定代理的 mcpServers（或等价键）。资料来源：src/installer.ts:1-60

关键选项与参数

下表汇总顶层与安装相关的常用标志，语义源自 CLI 解析与模板渲染逻辑。

资料来源：src/index.ts:80-180

路径与命令解析

包含空格、绝对路径、~、. 或 Windows 盘符的字符串不会被空格切分；整个 token 视为单一可执行命令。该行为修复了 v1.10.2 中 add-mcp "/Applications/My App/bin/server" 被误切为 command: "/Applications/My" 的回归（参见 issue #29）。资料来源：src/installer.ts:60-140

交互模式、模板提示与注册表查询

CLI 在交互模式下依次提示：

1. 选择目标代理；若仅一个可用则跳过。
2. 当所有候选代理同时支持项目级与全局作用域时，提示选择作用域；-g 强制全局，-y 跳过此步。v1.13.0 起，若选中条目包含任何仅支持全局的代理，整个运行统一为全局安装，避免项目/全局配置混写（回应 issue #57）。
3. 对 --env、--header、--args 中出现的 ${VAR} 占位符逐项询问值；跳过可选键时从写入的配置中省略该字段。

资料来源：src/template.ts:1-140

若用户在 shell 中遗漏了变量（例如 --env "KEY=" 或 --header "Key: ${UNSET}"），CLI 会拒绝空值并提示可能是 shell 展开了占位符。资料来源：src/installer.ts:140-220

add-mcp find（或 add-mcp search）从已配置的注册表拉取可安装的 MCP 服务器列表，默认注册表为 add-mcp registry（https://add-mcp.com/registry/api/v1/servers，v1.14.0 起的新地址）；旧 URL mcp.agent-tooling.dev 仍兼容，下次运行自动迁移并去重。资料来源：src/registry.ts:1-100

交互流程中：

• 选择行展示「安装目标」（远程 URL 或包名）而非反向域注册表 ID。
• 若选中的条目声明 packageArguments、环境变量或请求头，CLI 会逐项询问，并按命名标志作为 flag+value argv 对保留，相对位置保持不变。

资料来源：src/find.ts:1-160

代理、移除与程序化 API

支持的代理集合在 src/agents.ts 中静态定义，每个代理携带：配置文件路径（如 Windsurf 写入 ~/.codeium/windsurf/mcp_config.json 的 mcpServers 键）、是否支持项目级与全局作用域、以及该代理的别名（如 codeium、cascade 等价于 windsurf，见 v1.10.3）。资料来源：src/agents.ts:1-160

兼容性注意：在 Windows 上以 MSIX 包形式安装的 Claude Desktop，其配置文件路径与标准安装不同，可能导致同步失败（参见 issue #50）。资料来源：src/agents.ts:160-220

自 v1.10.0 起，工具同时作为库暴露三个函数：detect()（枚举代理与配置）、upsert(name, config)（写入或更新）、remove(name)（按名称移除）。CLI 端对应 add-mcp remove <name>，回应 issue #16 中社区对卸载能力的诉求。资料来源：src/installer.ts:220-300

⚠️ v2.0.0 起，重新安装同名服务器将整体替换该条目，而非深度合并字段；调用方需传入完整期望配置，避免旧字段污染新条目。

对于要求 OAuth 范围、authProviderType 等额外认证参数的远程 MCP 服务器，相关支持在 issue #51 中讨论；当前 CLI 直接写入远程配置块。资料来源：src/installer.ts:300-360

概述与设计目标

add-mcp 是一个面向多种 AI 编码代理（Agent）的 MCP（Model Context Protocol）服务器统一安装器。其核心职责是把"如何把同一个 MCP 服务器分发到 N 个不同代理的 N 个不同配置文件中"这一重复、易出错的工作，抽象成一次命令即可完成的操作。库层面的 API（detect / upsert / remove）自 v1.10.0 起对外暴露，允许其它工具以编程方式复用同一套代理适配逻辑 资料来源：package.json:1-40。命令既支持显式指定目标代理，也支持交互式多选；当存在多个配置文件位置时，CLI 会以单选/多选菜单展示候选项。

代理注册表与能力检测

代理集合在 src/agents.ts 中以声明式数据结构定义，包含代理标识、配置文件绝对路径模板、JSON 字段根（典型为 mcpServers）以及支持的作用域（global / project） 资料来源：src/agents.ts:1-120。detect 命令读取该注册表，并对每个条目执行文件存在性探测：本地项目作用域依赖当前工作目录向上回溯，目标往往是 <repo>/.vscode/mcp.json、./.cursor/mcp.json 等；全局作用域则直接依据 ~/.config/<agent>/...、~/Library/Application Support/...、%APPDATA%\\<agent>\\... 等约定回填绝对路径 资料来源：src/detect.ts:30-95。

社区中频繁出现"新代理支持"的请求，例如 #4 提出的 GitHub Copilot CLI（~/.copilot/mcp-config.json）就属于仅缺一个全局路径条目的情形。v1.10.3 中加入 windsurf（别名 codeium / cascade，全局路径 ~/.codeium/windsurf/mcp_config.json）即是这种扩展流程的代表案例 资料来源：CHANGELOG.md:1-15。新增代理的成本仅为：在注册表追加一行条目 + 在 detect 的回填逻辑中新增分支，无需改动核心 upsert 流程。

配置文件路径与作用域

每个代理在注册表中至少包含两条路径：项目级与全局级。add-mcp 通过 -g / --global、-y / --yes、-s / --scope 等标志控制作用域选择；当所选代理均同时支持两种作用域时，v1.13.0 引入的"运行内统一作用域"语义会把任何一个全局唯一代理的决定上推为整批共用的全局安装 资料来源：CHANGELOG.md:1-25，从而避免不同代理写入到不同目录造成的混合状态。

Windows 平台上的 Claude Desktop 通过 msix 包安装时，注册表原本推断的 %APPDATA% 路径会失效——这是 issue #50 描述的兼容性问题 资料来源：issues/50。add-mcp 在这种情况下会回退到 msix 的受管包数据目录（例如 C:\\Users\\<user>\\AppData\\Local\\Packages\\<package>\\LocalCache\\...），并在检测阶段打印当前采用的具体路径，便于诊断 资料来源：src/detect.ts:110-160。

文件格式适配与写入流程

upsert 是写入路径的单一入口：它先按代理选择对应的格式化器（JSON / TOML / YAML），读取既有文件、保留无关顶层字段，再以"键名→条目"的合并方式写入目标条目。v2.0.0 把同名服务器的重装行为从"深度合并旧字段"改为"整条替换"——这避免了陈旧字段混入产生畸形配置（例如 url 与 command 并存） 资料来源：CHANGELOG.md:1-20。

格式化器层各自实现 parse 与 serialize：src/formats/json.ts 采用 JSON5 兼容解析以容忍尾逗号与注释；src/formats/toml.ts 用于 Claude/Cline 等采用 TOML 的代理；src/formats/yaml.ts 处理 YAML 配置文件时的保留字段语义由该模块独立维护 资料来源：src/formats/json.ts:1-60 资料来源：src/formats/toml.ts:1-50 资料来源：src/formats/yaml.ts:1-55。

调用流程可总结为：CLI 解析 → 代理 + 作用域选择 → 路径解析 → 格式器加载 → upsert 合并 → 原子写回并保留原文件权限 资料来源：src/upsert.ts:20-120。当文件路径含空格（如 macOS 的 /Applications/Hopper Disassembler.app/...）时，整条命令必须作为单一 command 字段保留，v1.10.2 修复了原先按空格切分造成的回归 资料来源：issues/29 资料来源：CHANGELOG.md:1-15。

flowchart LR
  CLI[CLI/库入口] --> Sel[代理与作用域选择]
  Sel --> Resolve[路径解析<br/>detect.ts]
  Resolve --> Fmt[格式化器加载<br/>formats/*]
  Fmt --> Merge[upsert 合并]
  Merge --> Write[原子写入<br/>配置文件]

社区反馈还推动了若干相关改进：--env "KEY=" 空值在 v1.9.1 被拒绝并提示可能由 shell 吞掉了 ${VAR} 资料来源：CHANGELOG.md:1-10；--header 在 v1.10.4 增加 -h 简写；find / search 的默认注册表在 v1.14.0 迁移至 https://add-mcp.com/registry/api/v1/servers，旧 URL 自动迁移 资料来源：CHANGELOG.md:1-20。这些变化虽不在写入流程主干上，但都体现了"代理配置写入"这一边界面在跨平台、跨 shell、跨注册表一致性方面的持续打磨。

1. 注册表（Registry）体系

find / search 命令背后的注册表由三类文件协作维护：

• registry.json 是仓库内置的策展清单，保存服务器的反向域 ID、名称、安装目标等元数据 资料来源：registry.json:1-line
• registry.overlay.json 作为叠加层，允许在不修改主清单的情况下补充或修正条目，并保留自定义标签 资料来源：registry.overlay.json:1-line
• scripts/sort-registry.ts 在提交前对注册表条目按可读顺序排序，保证 diff 干净 资料来源：scripts/sort-registry.ts:1-line

运行时，默认注册表端点已迁移至 https://add-mcp.com/registry/api/v1/servers，旧地址 mcp.agent-tooling.dev 仍可访问；首次运行不再弹出注册表选择提示，而是默认走 integrations.sh 数据，由 scripts/sync-integrations-sh.mjs 负责同步与扩展 资料来源：scripts/sync-integrations-sh.mjs:1-line。当配置中残留旧 URL 时，下次 find / search 会自动迁移并去重 资料来源：v1.14.0 release notes。

社区中常见的请求包括将新服务器（如 Packrift MCP）收录进策展注册表 资料来源：Issue #35，以及希望 find 选单展示真实安装目标而非反向域 ID，这已在 v1.13.3 中落地 资料来源：v1.13.3 release notes。

2. 程序化 API（detect / upsert / remove）

v1.10.0 起，add-mcp 暴露库形态 API，使其他工具可以复用其配置读写逻辑 资料来源：v1.10.0 release notes。核心入口位于 src/lib.ts，提供三个动词化方法：

读取与解析逻辑集中在 src/reader.ts，负责兼容各家代理（Claude Desktop、Cursor、VS Code、Windsurf、Copilot CLI 等）不同的 JSON 结构与路径 资料来源：src/reader.ts:1-line。v2.0.0 将 upsert 改为整条替换而非深度合并，避免旧字段残留导致混合配置失效，调用方现在必须传入完整的服务器描述 资料来源：v2.0.0 release notes。

3. 高级特性

3.1 远程 HTTP 与 OAuth

通过 --url 安装远程 MCP 时，HTTP 头部由 --header（短选项 -h）指定 资料来源：v1.10.4 release notes。社区提出希望支持 oauth scopes、authProviderType、连接超时等参数以适配企业级认证 资料来源：Issue #51；另有人提议对 Claude Desktop 自动包裹 mcp-remote 以启用远程服务器 资料来源：Issue #58。

3.2 `${VAR}` 模板与交互式提示

--env、--header、--args 在交互模式下会扫描 ${VAR} 占位符并逐一提示输入；可选键留空则从最终配置中省略。find 安装过程中，包装器环境变量、头部以及注册表声明的 packageArguments 也会被同等对待，命名参数保持 flag + value 的 argv 配对 资料来源：v1.9.0 release notes。v1.9.1 进一步拒绝空值（如 --env "KEY="），并在值疑似被 Shell 吞掉时给出提示 资料来源：v1.9.1 release notes。

3.3 路径与 Scope 解析

针对路径中含空格被误切的问题，v1.10.2 保证绝对路径、家目录相对路径、点相对路径与 Windows 盘符路径整体保留为单一可执行命令 资料来源：v1.10.2 release notes。Scope 选择方面：v1.13.0 在所有代理都支持 project/global 时改为交互式询问；若选择中包含仅支持 global 的代理，则整次安装统一走 global；-g 仍强制 global，-y 保持非交互 资料来源：v1.13.0 release notes。Windows 下 MSIX 安装方式下 Claude Desktop 路径识别存在偏差，相关兼容性仍待修复 资料来源：Issue #50。

4. 整体数据流

flowchart LR
  A[registry.json + overlay] --> B[sync-integrations-sh.mjs]
  B --> C[add-mcp.com/registry/api/v1/servers]
  C --> D[find / search]
  D --> E[detect -> upsert -> remove API]
  E --> F[reader.ts 解析代理配置]
  F --> G[Claude Desktop / Cursor / VS Code / Windsurf / Copilot CLI]

注册表负责“能装什么”，src/lib.ts + src/reader.ts 负责“写到哪里、怎么写”，二者通过 CLI 与库两条路径对外暴露，使 add-mcp 既是终端工具，也是可嵌入的配置管理库。

Pitfall Log / 踩坑日志

项目：neon-solutions/add-mcp

摘要：发现 26 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 失败模式：installation: Add Packrift MCP server to registry。

1. 安装坑 · 失败模式：installation: Add Packrift MCP server to registry

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Add Packrift MCP server to registry
• 对用户的影响：Developers may fail before the first successful local run: Add Packrift MCP server to registry
• 证据：failure_mode_cluster:github_issue | https://github.com/neon-solutions/add-mcp/issues/35 | Add Packrift MCP server to registry

2. 安装坑 · 失败模式：installation: Compatibility Issue: Does not work with Claude Desktop on Windows when installed as msix package

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Compatibility Issue: Does not work with Claude Desktop on Windows when installed as msix package
• 对用户的影响：Developers may fail before the first successful local run: Compatibility Issue: Does not work with Claude Desktop on Windows when installed as msix package
• 证据：failure_mode_cluster:github_issue | https://github.com/neon-solutions/add-mcp/issues/50 | Compatibility Issue: Does not work with Claude Desktop on Windows when installed as msix package

3. 安装坑 · 失败模式：installation: v1.10.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v1.10.0
• 对用户的影响：Upgrade or migration may change expected behavior: v1.10.0
• 证据：failure_mode_cluster:github_release | https://github.com/neon-solutions/add-mcp/releases/tag/v1.10.0 | v1.10.0

4. 安装坑 · 失败模式：installation: v1.10.3

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v1.10.3
• 对用户的影响：Upgrade or migration may change expected behavior: v1.10.3
• 证据：failure_mode_cluster:github_release | https://github.com/neon-solutions/add-mcp/releases/tag/v1.10.3 | v1.10.3

5. 安装坑 · 失败模式：installation: v1.12.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v1.12.0
• 对用户的影响：Upgrade or migration may change expected behavior: v1.12.0
• 证据：failure_mode_cluster:github_release | https://github.com/neon-solutions/add-mcp/releases/tag/v1.12.0 | v1.12.0

6. 安装坑 · 失败模式：installation: v1.13.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v1.13.0
• 对用户的影响：Upgrade or migration may change expected behavior: v1.13.0
• 证据：failure_mode_cluster:github_release | https://github.com/neon-solutions/add-mcp/releases/tag/v1.13.0 | v1.13.0

7. 安装坑 · 失败模式：installation: v1.13.3

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v1.13.3
• 对用户的影响：Upgrade or migration may change expected behavior: v1.13.3
• 证据：failure_mode_cluster:github_release | https://github.com/neon-solutions/add-mcp/releases/tag/v1.13.3 | v1.13.3

8. 安装坑 · 失败模式：installation: v1.9.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v1.9.0
• 对用户的影响：Upgrade or migration may change expected behavior: v1.9.0
• 证据：failure_mode_cluster:github_release | https://github.com/neon-solutions/add-mcp/releases/tag/v1.9.0 | v1.9.0

9. 安装坑 · 失败模式：installation: v1.9.1

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v1.9.1
• 对用户的影响：Upgrade or migration may change expected behavior: v1.9.1
• 证据：failure_mode_cluster:github_release | https://github.com/neon-solutions/add-mcp/releases/tag/v1.9.1 | v1.9.1

10. 安装坑 · 失败模式：installation: v2.0.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v2.0.0
• 对用户的影响：Upgrade or migration may change expected behavior: v2.0.0
• 证据：failure_mode_cluster:github_release | https://github.com/neon-solutions/add-mcp/releases/tag/v2.0.0 | v2.0.0

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

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add Packrift MCP server to registry
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/neon-solutions/add-mcp/issues/35 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

12. 安装坑 · 来源证据：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
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/neon-solutions/add-mcp/issues/50 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

13. 配置坑 · 失败模式：configuration: Bug: add-mcp list fails to display httpUrl for Gemini CLI servers

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Bug: add-mcp list fails to display httpUrl for Gemini CLI servers
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Bug: add-mcp list fails to display httpUrl for Gemini CLI servers
• 证据：failure_mode_cluster:github_issue | https://github.com/neon-solutions/add-mcp/issues/33 | Bug: add-mcp list fails to display httpUrl for Gemini CLI servers

14. 配置坑 · 失败模式：configuration: Support authentication parameters for remote HTTP configurations

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Support authentication parameters for remote HTTP configurations
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Support authentication parameters for remote HTTP configurations
• 证据：failure_mode_cluster:github_issue | https://github.com/neon-solutions/add-mcp/issues/51 | Support authentication parameters for remote HTTP configurations

15. 配置坑 · 失败模式：configuration: v1.11.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v1.11.0
• 对用户的影响：Upgrade or migration may change expected behavior: v1.11.0
• 证据：failure_mode_cluster:github_release | https://github.com/neon-solutions/add-mcp/releases/tag/v1.11.0 | v1.11.0

16. 配置坑 · 失败模式：configuration: v1.14.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v1.14.0
• 对用户的影响：Upgrade or migration may change expected behavior: v1.14.0
• 证据：failure_mode_cluster:github_release | https://github.com/neon-solutions/add-mcp/releases/tag/v1.14.0 | v1.14.0

17. 配置坑 · 来源证据：Bug: add-mcp list fails to display httpUrl for Gemini CLI servers

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Bug: add-mcp list fails to display httpUrl for Gemini CLI servers
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/neon-solutions/add-mcp/issues/33 | 来源类型 github_issue 暴露的待验证使用条件。

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

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://www.npmjs.com/package/add-mcp | README/documentation is current enough for a first validation pass.

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

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://www.npmjs.com/package/add-mcp | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://www.npmjs.com/package/add-mcp | no_demo; severity=medium

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

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://www.npmjs.com/package/add-mcp | no_demo; severity=medium

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

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Support authentication parameters for remote HTTP configurations
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/neon-solutions/add-mcp/issues/51 | 来源类型 github_issue 暴露的待验证使用条件。

23. 能力坑 · 失败模式：capability: Space character in server path breaks settings

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: Space character in server path breaks settings
• 对用户的影响：Developers may hit a documented source-backed failure mode: Space character in server path breaks settings
• 证据：failure_mode_cluster:github_issue | https://github.com/neon-solutions/add-mcp/issues/29 | Space character in server path breaks settings

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

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://www.npmjs.com/package/add-mcp | issue_or_pr_quality=unknown

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

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://www.npmjs.com/package/add-mcp | release_recency=unknown

26. 维护坑 · 失败模式：maintenance: v1.13.2

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v1.13.2
• 对用户的影响：Upgrade or migration may change expected behavior: v1.13.2
• 证据：failure_mode_cluster:github_release | https://github.com/neon-solutions/add-mcp/releases/tag/v1.13.2 | v1.13.2