mcpsmgr 0.1.0

package/openspec/config.yaml

@@ -0,0 +1,20 @@
+schema: spec-driven
+
+# Project context (optional)
+# This is shown to AI when creating artifacts.
+# Add your tech stack, conventions, style guides, domain knowledge, etc.
+# Example:
+#   context: |
+#     Tech stack: TypeScript, React, Node.js
+#     We use conventional commits
+#     Domain: e-commerce platform
+
+# Per-artifact rules (optional)
+# Add custom rules for specific artifacts.
+# Example:
+#   rules:
+#     proposal:
+#       - Keep proposals under 500 words
+#       - Always include a "Non-goals" section
+#     tasks:
+#       - Break tasks into chunks of max 2 hours

package/openspec/specs/agent-adapters/spec.md

@@ -0,0 +1,148 @@
+## Purpose
+
+为 5 个编程 agent 提供配置适配器, 处理各自不同的配置文件格式和路径.
+
+## Requirements
+
+### Requirement: Adapter output format
+
+All adapters SHALL output MCP server configs WITHOUT the `env`/`environment` field. The adapter SHALL:
+
+1. Substitute `${VAR_NAME}` references in args with actual values from the env block
+2. For remaining env vars (not referenced in args), use the `env` command as a wrapper with `KEY=value` args
+3. Never include `env` or `environment` field in the output
+
+When reading configs back (`fromAgentFormat`), the adapter SHALL handle both the new format (command = "env" with KEY=value args) and the legacy format (separate env/environment field) for backward compatibility.
+
+#### Scenario: Args contain ${VAR} references
+- **WHEN** a stdio config has args containing `${JINA_API_KEY}` and env `{ "JINA_API_KEY": "xxx" }`
+- **THEN** the adapter substitutes `${JINA_API_KEY}` with `xxx` directly in the args, removes the env field, and does NOT use env command wrapper (since no remaining env vars)
+
+#### Scenario: Env vars not referenced in args
+- **WHEN** a stdio config has env vars `{ "BRAVE_API_KEY": "xxx" }` with no `${BRAVE_API_KEY}` in args
+- **THEN** the adapter uses `env` command wrapper: `command: "env"`, args: `["BRAVE_API_KEY=xxx", "npx", ...]`
+
+#### Scenario: Mixed - some referenced, some not
+- **WHEN** a stdio config has `${API_KEY}` in args AND a separate `DEBUG` env var
+- **THEN** `${API_KEY}` is substituted in args, `DEBUG` is passed via env command wrapper
+
+#### Scenario: Write stdio config without env vars
+- **WHEN** a stdio config has empty env vars
+- **THEN** the adapter outputs config with the original command and args, and NO `env`/`environment` field
+
+#### Scenario: Read new format config
+- **WHEN** the adapter reads a config with `command: "env"` and args containing KEY=value entries
+- **THEN** it extracts env vars from the KEY=value args and reconstructs the original command, args, and env
+
+#### Scenario: Read legacy format config (backward compatibility)
+- **WHEN** the adapter reads a config with a separate `env`/`environment` field
+- **THEN** it parses the env vars from that field as before
+
+### Requirement: Claude Code Adapter
+
+系统 SHALL 提供 Claude Code 的配置适配器, 操作 `.mcp.json` 文件.
+
+#### Scenario: 读取已有配置
+
+- **WHEN** 项目根目录存在 `.mcp.json`
+- **THEN** adapter 解析文件, 提取 `mcpServers` 下所有 MCP 服务条目
+
+#### Scenario: 写入新服务
+
+- **WHEN** 向 Claude Code 添加一个 MCP 服务
+- **THEN** adapter 读取 `.mcp.json` (不存在则创建), 在 `mcpServers` 下添加服务条目, 使用 env command wrapper 格式 (stdio 有 env vars 时) 或 HTTP 格式 `{ "type": "http", "url": "...", "headers": {...} }`, 保留文件中已有的其他服务条目
+
+#### Scenario: 同名冲突
+
+- **WHEN** `.mcp.json` 中已存在同名服务
+- **THEN** adapter 报告冲突, 不修改文件
+
+### Requirement: Codex CLI Adapter
+
+系统 SHALL 提供 Codex CLI 的配置适配器, 操作 `.codex/config.toml` 文件.
+
+#### Scenario: 读取已有配置
+
+- **WHEN** 项目中存在 `.codex/config.toml`
+- **THEN** adapter 解析 TOML 文件, 提取 `[mcp_servers.*]` 下所有 MCP 服务条目
+
+#### Scenario: 写入新服务
+
+- **WHEN** 向 Codex CLI 添加一个 MCP 服务
+- **THEN** adapter 读取 `.codex/config.toml` (不存在则创建 `.codex/` 目录和文件), 在 `[mcp_servers.<name>]` section 下添加服务配置, 使用 env command wrapper 格式 (有 env vars 时 command = "env"), MUST 保留文件中已有的非 MCP section 和注释
+
+#### Scenario: 同名冲突
+
+- **WHEN** `.codex/config.toml` 中 `[mcp_servers]` 下已存在同名服务
+- **THEN** adapter 报告冲突, 不修改文件
+
+### Requirement: Gemini CLI Adapter
+
+系统 SHALL 提供 Gemini CLI 的配置适配器, 操作 `.gemini/settings.json` 文件.
+
+#### Scenario: 读取已有配置
+
+- **WHEN** 项目中存在 `.gemini/settings.json`
+- **THEN** adapter 解析文件, 提取 `mcpServers` 下所有 MCP 服务条目
+
+#### Scenario: 写入新服务
+
+- **WHEN** 向 Gemini CLI 添加一个 MCP 服务
+- **THEN** adapter 读取 `.gemini/settings.json` (不存在则创建 `.gemini/` 目录和文件), 在 `mcpServers` 下添加服务条目, 使用 env command wrapper 格式, 保留文件中已有的其他字段 (如 `mcp`, `theme` 等非 mcpServers 字段)
+
+#### Scenario: 同名冲突
+
+- **WHEN** `.gemini/settings.json` 中 `mcpServers` 下已存在同名服务
+- **THEN** adapter 报告冲突, 不修改文件
+
+### Requirement: OpenCode Adapter
+
+系统 SHALL 提供 OpenCode 的配置适配器, 操作 `opencode.json` 文件.
+
+#### Scenario: 读取已有配置
+
+- **WHEN** 项目根目录存在 `opencode.json`
+- **THEN** adapter 解析文件, 提取 `mcp` 下所有 MCP 服务条目
+
+#### Scenario: 写入新服务 (stdio)
+
+- **WHEN** 向 OpenCode 添加一个 stdio 类型的 MCP 服务
+- **THEN** adapter 在 `mcp` 下添加服务条目, 格式为 `{ "type": "local", "command": ["env", "KEY=val", "<cmd>", ...] }` (有 env vars 时) 或 `{ "type": "local", "command": ["<cmd>", "<arg1>", ...] }` (无 env vars 时), 不使用 `environment` 字段
+
+#### Scenario: 写入新服务 (http)
+
+- **WHEN** 向 OpenCode 添加一个 http 类型的 MCP 服务
+- **THEN** adapter 在 `mcp` 下添加服务条目, 格式为 `{ "type": "remote", "url": "...", "headers": {...} }`
+
+#### Scenario: 同名冲突
+
+- **WHEN** `opencode.json` 中 `mcp` 下已存在同名服务
+- **THEN** adapter 报告冲突, 不修改文件
+
+### Requirement: Antigravity Adapter
+
+系统 SHALL 提供 Antigravity 的配置适配器, 操作 `~/.gemini/antigravity/mcp_config.json` (全局文件).
+
+#### Scenario: 读取已有配置
+
+- **WHEN** `~/.gemini/antigravity/mcp_config.json` 存在
+- **THEN** adapter 解析文件, 提取 `mcpServers` 下所有 MCP 服务条目
+
+#### Scenario: 写入新服务
+
+- **WHEN** 向 Antigravity 添加一个 MCP 服务
+- **THEN** adapter 读取 `~/.gemini/antigravity/mcp_config.json` (不存在则创建目录和文件), 在 `mcpServers` 下添加服务条目, 使用 env command wrapper 格式 或 HTTP 格式 `{ "serverUrl": "...", "headers": {...} }`, 注意 HTTP 时 url key MUST 为 `serverUrl`
+
+#### Scenario: 同名冲突
+
+- **WHEN** 配置文件中 `mcpServers` 下已存在同名服务
+- **THEN** adapter 报告冲突, 不修改文件
+
+### Requirement: Agent 自动检测
+
+系统 SHALL 在项目目录中自动检测哪些 agent 的配置文件已存在.
+
+#### Scenario: 检测项目中的 agent
+
+- **WHEN** 系统需要确定项目使用了哪些 agent
+- **THEN** 系统检查以下文件是否存在: `.mcp.json` (Claude Code), `.codex/` 目录 (Codex CLI), `.gemini/settings.json` (Gemini CLI), `opencode.json` (OpenCode); Antigravity 始终作为可选项列出 (因为仅全局配置)

package/openspec/specs/central-storage/spec.md

@@ -0,0 +1,42 @@
+## Purpose
+
+管理 `~/.mcps-manager/` 中央仓库的初始化, 配置文件和服务定义文件的存储.
+
+## Requirements
+
+### Requirement: Setup 初始化中央仓库
+
+系统 SHALL 提供 `mcpsmgr setup` 命令, 创建 `~/.mcps-manager/` 目录结构并交互式收集配置信息.
+
+#### Scenario: 首次 setup
+
+- **WHEN** 用户执行 `mcpsmgr setup` 且 `~/.mcps-manager/` 不存在
+- **THEN** 系统创建 `~/.mcps-manager/` 目录 (权限 700) 和 `servers/` 子目录, 交互式要求用户输入 GLM5 API Key, 选择 GLM5 端点 (Coding 或通用), 并将配置保存到 `~/.mcps-manager/config.json` (权限 600). Web Reader API Key 默认复用 GLM5 API Key (同属智谱平台)
+
+#### Scenario: 重复 setup
+
+- **WHEN** 用户执行 `mcpsmgr setup` 且 `~/.mcps-manager/` 已存在
+- **THEN** 系统提示配置已存在, 询问是否覆盖
+
+### Requirement: config.json 结构
+
+系统 SHALL 将全局配置保存在 `~/.mcps-manager/config.json` 中.
+
+#### Scenario: 配置文件内容
+
+- **WHEN** setup 完成后
+- **THEN** config.json 包含 `glm.apiKey` (GLM5 API key), `glm.endpoint` (完整端点 URL), `webReader.apiKey` (Web Reader API key), `webReader.url` (Web Reader MCP 端点 URL)
+
+### Requirement: 服务定义文件存储
+
+系统 SHALL 将每个 MCP 服务定义保存为 `~/.mcps-manager/servers/{name}.json`, 文件权限 600.
+
+#### Scenario: 服务定义文件结构
+
+- **WHEN** 一个 MCP 服务被添加到中央仓库
+- **THEN** 服务定义文件包含 `name` (服务名), `source` (来源 URL), `default` (基础配置, 含 transport/command/args/env 等), `overrides` (per-agent 配置覆盖, 可为空对象)
+
+#### Scenario: 文件权限
+
+- **WHEN** 服务定义文件被创建
+- **THEN** 文件权限 MUST 设置为 600 (仅所有者可读写)

package/openspec/specs/glm-integration/spec.md

@@ -0,0 +1,70 @@
+## Purpose
+
+集成 GLM5 大模型和智谱 Web Reader MCP, 实现 MCP 服务文档的自动分析和配置提取.
+
+## Requirements
+
+### Requirement: GLM5 API 调用
+
+系统 SHALL 调用 GLM5 Chat Completion API 分析 MCP 服务文档.
+
+#### Scenario: 调用 GLM5 分析文档
+
+- **WHEN** 用户通过 `mcpsmgr server add <url>` 添加服务
+- **THEN** 系统构造请求: model 为 `glm-5`, system prompt 指示分析 MCP 文档并提取 5 个 agent 的配置, tools 中包含 webReader 函数定义, user message 包含用户提供的 URL, 发送到 config.json 中配置的 GLM5 端点
+
+#### Scenario: GLM5 端点认证
+
+- **WHEN** 调用 GLM5 API
+- **THEN** 系统使用 `Authorization: Bearer <glm.apiKey>` 认证, Content-Type 为 `application/json`
+
+### Requirement: Web Reader 工具集成
+
+系统 SHALL 将智谱 Web Reader MCP 作为 GLM5 的 function calling tool 提供.
+
+#### Scenario: 定义 webReader 工具
+
+- **WHEN** 构造 GLM5 请求
+- **THEN** tools 数组中包含 webReader 函数定义, 参数为 `url` (string, required), tool_choice 设为 `auto`
+
+#### Scenario: 处理 GLM5 的工具调用
+
+- **WHEN** GLM5 返回 `tool_calls` 要求调用 webReader
+- **THEN** 系统提取 URL 参数, 向 Web Reader MCP 端点发送请求 (使用 `webReader.apiKey` 认证), 获取网页内容, 将结果作为 `role: "tool"` 消息回传给 GLM5 继续对话
+
+#### Scenario: Web Reader 调用失败
+
+- **WHEN** Web Reader MCP 返回错误或超时
+- **THEN** 系统将错误信息回传给 GLM5, 由 GLM5 决定是否重试或基于已有信息返回结果
+
+### Requirement: GitHub README 优先获取
+
+系统 SHALL 对 GitHub `owner/repo` 格式优先获取 README.
+
+#### Scenario: GitHub 简写解析
+
+- **WHEN** 用户输入格式为 `owner/repo` (不含 `/` 以外的特殊字符, 不以 `http` 开头, 不以 `@` 开头)
+- **THEN** 系统先尝试给 GLM5 的 user message 中提供 `https://github.com/{owner}/{repo}` 作为文档 URL, 并指示 GLM5 优先读取该仓库的 README
+
+### Requirement: 分析结果结构化输出
+
+GLM5 MUST 返回结构化 JSON 格式的分析结果.
+
+#### Scenario: 标准分析结果
+
+- **WHEN** GLM5 完成文档分析
+- **THEN** 返回 JSON 包含: `name` (服务名, 从文档中提取), `default` (基础配置, 含 transport/command/args/env 等), `overrides` (per-agent 配置覆盖, key 为 agent id), `requiredEnvVars` (需要用户提供值的环境变量名列表)
+
+#### Scenario: 分析结果展示
+
+- **WHEN** GLM5 返回分析结果
+- **THEN** 系统展示: 服务名, 来源 URL, 基础配置详情, 各 agent 的专属配置差异表 (含 transport 和差异说明), 让用户充分了解后选择是否信任
+
+### Requirement: 多轮对话处理
+
+系统 SHALL 支持 GLM5 function calling 的多轮对话.
+
+#### Scenario: 多次工具调用
+
+- **WHEN** GLM5 在一次对话中多次请求调用 webReader (如先读 README 再读其他页面)
+- **THEN** 系统依次执行每次工具调用, 将结果回传, 直到 GLM5 返回最终分析结果 (不含 tool_calls)

package/openspec/specs/project-operations/spec.md

@@ -0,0 +1,138 @@
+## Purpose
+
+提供项目级的 MCP 服务管理操作, 包括初始化, 添加, 移除, 同步和状态查看.
+
+## Requirements
+
+### Requirement: 项目初始化
+
+系统 SHALL 支持 `mcpsmgr init` 命令, 在当前项目中交互式选择 agent 和 MCP 服务.
+
+#### Scenario: 交互式初始化
+
+- **WHEN** 用户在项目目录执行 `mcpsmgr init`
+- **THEN** 系统自动检测已存在的 agent 配置文件并预选 (其中 `isGlobal` 为 `true` 的 agent SHALL 默认不选中), 展示所有支持的 agent 供用户勾选, 从中央仓库列出所有已保存的 MCP 服务供用户勾选, 展示即将执行的操作预览, 确认后将选中的服务写入选中的 agent 配置文件
+
+#### Scenario: 服务器选择默认状态基于目标目录检测
+
+- **WHEN** 用户完成 agent 选择后进入服务器选择步骤
+- **THEN** 系统 SHALL 读取所有已选中 agent 的现有配置, 收集已存在的 MCP 服务名称. 对于已存在于任一已选中 agent 配置中的服务, SHALL 标记为 `(detected)` 并默认选中. 对于不存在于任何已选中 agent 配置中的服务, SHALL 默认不选中.
+
+#### Scenario: 配置读取失败降级
+
+- **WHEN** 读取某个已选中 agent 的现有配置时发生错误 (如文件损坏)
+- **THEN** 系统 SHALL 跳过该 agent 的服务检测, 继续处理其他 agent, 不阻断初始化流程
+
+#### Scenario: 中央仓库为空
+
+- **WHEN** 用户执行 `mcpsmgr init` 但 `~/.mcps-manager/servers/` 下没有任何服务
+- **THEN** 系统提示中央仓库为空, 建议先使用 `mcpsmgr server add` 添加服务
+
+### Requirement: 项目添加服务
+
+系统 SHALL 支持 `mcpsmgr add <server-name>` 命令, 将中央仓库中的服务添加到当前项目的 agent 配置中.
+
+#### Scenario: 添加到已检测的 agent
+
+- **WHEN** 用户执行 `mcpsmgr add context7`
+- **THEN** 系统自动检测项目中已存在的 agent 配置文件, 展示列表供用户勾选 (其中 `isGlobal` 为 `true` 的 agent SHALL 默认不选中), 将服务写入勾选的 agent 配置文件
+
+#### Scenario: 服务不存在于中央仓库
+
+- **WHEN** 用户执行 `mcpsmgr add nonexistent`
+- **THEN** 系统报错, 提示服务不存在于中央仓库
+
+#### Scenario: 部分 agent 同名冲突
+
+- **WHEN** 添加时某些 agent 配置文件中已存在同名服务
+- **THEN** 系统对冲突的 agent 报告跳过, 对无冲突的 agent 正常写入
+
+### Requirement: 项目移除服务
+
+系统 SHALL 支持 `mcpsmgr remove <server-name>` 命令, 从当前项目的 agent 配置中移除单个 MCP 服务配置.
+
+#### Scenario: 从多个 agent 移除
+
+- **WHEN** 用户执行 `mcpsmgr remove brave-search`
+- **THEN** 系统列出包含该服务的所有 agent 配置, 供用户勾选要移除的 (其中 `isGlobal` 为 `true` 的 agent SHALL 默认不选中), 从勾选的 agent 配置文件中删除该服务条目, 保留文件中的其他内容. 未勾选的 agent SHALL NOT 被删除任何 MCP 配置
+
+#### Scenario: 无 agent 包含该服务
+
+- **WHEN** 用户执行 `mcpsmgr remove nonexistent` 但没有任何 agent 配置包含该服务
+- **THEN** 系统提示未在任何 agent 配置中找到该服务
+
+#### Scenario: 取消选中 agent 不删除 MCP
+
+- **WHEN** 用户在 remove 交互中取消选中某个 agent
+- **THEN** 系统 SHALL NOT 删除该 agent 中的任何 MCP 配置, 仅跳过该 agent
+
+### Requirement: 同步中央仓库变更
+
+系统 SHALL 支持 `mcpsmgr sync` 命令, 将中央仓库的服务配置同步到当前项目的 agent 配置文件.
+
+#### Scenario: 同步更新
+
+- **WHEN** 用户修改了中央仓库中的服务配置 (如更新了 API key) 后执行 `mcpsmgr sync`
+- **THEN** 系统读取各 agent 配置文件中已有的 MCP 服务, 与中央仓库比对, 展示变更预览, 用户确认后更新 agent 配置文件中对应服务的配置
+
+#### Scenario: 同名冲突处理
+
+- **WHEN** sync 过程中发现某个 agent 配置中的服务名与中央仓库同名但非 mcpsmgr 管理 (用户手动添加的)
+- **THEN** 系统报告冲突, 跳过该服务在该 agent 的同步
+
+### Requirement: 列出项目 MCP 状态
+
+系统 SHALL 支持 `mcpsmgr list` 命令, 展示当前项目各 agent 的 MCP 服务状态矩阵.
+
+#### Scenario: 状态矩阵展示
+
+- **WHEN** 用户在项目目录执行 `mcpsmgr list`
+- **THEN** 系统扫描所有 agent 的实际配置文件, 解析出已配置的 MCP 服务, 以表格形式展示 (行: 服务名, 列: agent 名, 值: 是否存在及 transport 类型)
+
+#### Scenario: 无 agent 配置文件
+
+- **WHEN** 项目中没有任何 agent 配置文件
+- **THEN** 系统提示未检测到任何 agent 配置, 建议执行 `mcpsmgr init`
+
+### Requirement: 交互中断优雅退出
+
+所有项目级交互式命令 (init, add, remove, sync) SHALL 在用户按 Ctrl-C 中断 prompt 时正常退出, 不输出错误信息, 退出码为 0.
+
+#### Scenario: init 命令中按 Ctrl-C
+
+- **WHEN** 用户在 `mcpsmgr init` 的任意 prompt 步骤中按 Ctrl-C
+- **THEN** 系统 SHALL 静默退出, 不输出错误堆栈, 不修改任何配置文件, 进程退出码为 0
+
+#### Scenario: add 命令中按 Ctrl-C
+
+- **WHEN** 用户在 `mcpsmgr add <server>` 的 agent 选择 prompt 中按 Ctrl-C
+- **THEN** 系统 SHALL 静默退出, 不输出错误堆栈, 不修改任何配置文件, 进程退出码为 0
+
+#### Scenario: remove 命令中按 Ctrl-C
+
+- **WHEN** 用户在 `mcpsmgr remove <server>` 的 agent 选择 prompt 中按 Ctrl-C
+- **THEN** 系统 SHALL 静默退出, 不输出错误堆栈, 不修改任何配置文件, 进程退出码为 0
+
+#### Scenario: sync 命令中按 Ctrl-C
+
+- **WHEN** 用户在 `mcpsmgr sync` 的确认 prompt 中按 Ctrl-C
+- **THEN** 系统 SHALL 静默退出, 不输出错误堆栈, 不修改任何配置文件, 进程退出码为 0
+
+#### Scenario: setup 命令中按 Ctrl-C
+
+- **WHEN** 用户在 `mcpsmgr setup` 的任意 prompt 步骤中按 Ctrl-C
+- **THEN** 系统 SHALL 静默退出, 不输出错误堆栈, 不修改任何配置文件, 进程退出码为 0
+
+### Requirement: init 命令中取消勾选已检测服务触发删除
+
+系统 SHALL 在 `mcpsmgr init` 中, 当用户取消勾选已检测到的 MCP 服务时, 将其视为删除意图, 在操作计划中展示并在确认后执行删除.
+
+#### Scenario: 取消勾选已检测服务
+
+- **WHEN** 用户在 `mcpsmgr init` 的服务选择步骤中, 取消勾选一个已被检测到 (标记为 `(detected)`) 的服务
+- **THEN** 系统 SHALL 在操作计划中以 `- <server-name>` 格式展示该服务将被删除, 并在用户确认后, 从对应 agent 配置中移除该服务
+
+#### Scenario: 仅从包含该服务的 agent 中删除
+
+- **WHEN** 用户取消勾选一个已检测服务, 且多个已选 agent 中只有部分包含该服务
+- **THEN** 系统 SHALL 仅从实际包含该服务的 agent 配置中执行删除, 不影响不包含该服务的 agent

package/openspec/specs/server-management/spec.md

@@ -0,0 +1,93 @@
+## Purpose
+
+管理中央仓库中 MCP 服务定义的添加, 移除和列出, 包括通过 GLM5 分析文档自动生成配置.
+
+## Requirements
+
+### Requirement: 通过 URL 添加 MCP 服务
+
+系统 SHALL 支持 `mcpsmgr server add <url-or-repo>` 命令, 通过 URL 或 GitHub `owner/repo` 简写添加 MCP 服务到中央仓库.
+
+#### Scenario: 使用 GitHub 简写添加
+
+- **WHEN** 用户执行 `mcpsmgr server add anthropics/mcp-brave-search`
+- **THEN** 系统将 `anthropics/mcp-brave-search` 扩展为 `https://github.com/anthropics/mcp-brave-search`, 优先获取 README.md 内容, 调用 GLM5 分析文档, 提取服务名和配置, 展示分析结果供用户确认
+
+#### Scenario: 使用完整 URL 添加
+
+- **WHEN** 用户执行 `mcpsmgr server add https://docs.bigmodel.cn/cn/coding-plan/mcp/search-mcp-server`
+- **THEN** 系统直接将 URL 传递给 GLM5 分析, 提取服务名和配置
+
+#### Scenario: 不支持的输入格式
+
+- **WHEN** 用户执行 `mcpsmgr server add @scope/package` 或 `mcpsmgr server add bare-name`
+- **THEN** 系统报错, 提示需要提供 URL 或 `owner/repo` 格式
+
+### Requirement: 同名服务检测
+
+系统 SHALL 在添加服务时检测中央仓库中是否已存在同名服务.
+
+#### Scenario: 中央仓库同名冲突
+
+- **WHEN** 用户添加的服务名与 `~/.mcps-manager/servers/` 中已有服务同名
+- **THEN** 系统报错, 提示服务已存在并建议先执行 `mcpsmgr server remove <name>`
+
+### Requirement: GLM5 分析结果确认
+
+系统 SHALL 展示 GLM5 的分析结果, 让用户选择是否信任.
+
+#### Scenario: 用户信任分析结果
+
+- **WHEN** GLM5 返回分析结果且用户选择信任
+- **THEN** 系统使用分析结果中的配置, 交互式要求用户输入 requiredEnvVars 中的值 (每次按键以 `*` 显示, 支持粘贴), 提示信息中 SHALL 包含安全说明 "stored locally, never sent to servers", 输入的值不会传递给 GLM5 或其他 LLM, 直接按已生成的配置保存到中央仓库
+
+#### Scenario: 用户不信任分析结果
+
+- **WHEN** GLM5 返回分析结果且用户选择不信任
+- **THEN** 系统回退到手动配置模式, 要求用户逐项输入 transport, command, args, env 等信息
+
+### Requirement: 无文档 URL 回退
+
+系统 SHALL 支持不提供文档 URL 时的手动配置.
+
+#### Scenario: 文档 URL 留空
+
+- **WHEN** 用户在添加流程中文档 URL 留空
+- **THEN** 系统进入手动配置模式, 不调用 GLM5, 不生成 overrides, 仅保存 default 配置
+
+### Requirement: 移除 MCP 服务
+
+系统 SHALL 支持 `mcpsmgr server remove <name>` 命令, 从中央仓库删除服务定义.
+
+#### Scenario: 成功移除
+
+- **WHEN** 用户执行 `mcpsmgr server remove brave-search` 且服务存在
+- **THEN** 系统删除 `~/.mcps-manager/servers/brave-search.json`
+
+#### Scenario: 服务不存在
+
+- **WHEN** 用户执行 `mcpsmgr server remove nonexistent`
+- **THEN** 系统报错, 提示服务不存在
+
+### Requirement: 列出中央仓库服务
+
+系统 SHALL 支持 `mcpsmgr server list` 命令, 列出中央仓库中所有已保存的服务.
+
+#### Scenario: 列出所有服务
+
+- **WHEN** 用户执行 `mcpsmgr server list`
+- **THEN** 系统读取 `~/.mcps-manager/servers/` 下所有 JSON 文件, 展示服务名, 来源, transport 类型, 是否有 overrides
+
+### Requirement: server-add 交互中断优雅退出
+
+`mcpsmgr server add` 命令 SHALL 在用户按 Ctrl-C 中断任意 prompt 时正常退出, 不输出错误信息, 退出码为 0.
+
+#### Scenario: 自动模式中按 Ctrl-C
+
+- **WHEN** 用户在 `mcpsmgr server add <url>` 的 GLM 分析确认或环境变量输入 prompt 中按 Ctrl-C
+- **THEN** 系统 SHALL 静默退出, 不输出错误堆栈, 不保存任何服务配置, 进程退出码为 0
+
+#### Scenario: 手动模式中按 Ctrl-C
+
+- **WHEN** 用户在手动配置模式的任意 prompt 中按 Ctrl-C
+- **THEN** 系统 SHALL 静默退出, 不输出错误堆栈, 不保存任何服务配置, 进程退出码为 0

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "mcpsmgr",
+  "version": "0.1.0",
+  "description": "Unified MCP server manager for multiple coding agents",
+  "type": "module",
+  "bin": {
+    "mcpsmgr": "./dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "cli",
+    "agent"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@inquirer/prompts": "^8.3.0",
+    "commander": "^14.0.3",
+    "smol-toml": "^1.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.4.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}