mcpsmgr 0.1.0

package/openspec/changes/archive/2026-03-12-graceful-exit-on-interrupt/proposal.md

@@ -0,0 +1,25 @@
+## Why
+
+用户在 `init`, `setup`, `add`, `remove`, `server-add`, `sync` 等交互式命令中按 Ctrl-C 或 q 退出时, 程序会抛出未捕获的 `AbortError` 异常并显示错误堆栈, 体验不好.  应该静默退出, 不输出任何错误信息.
+
+## What Changes
+
+- 所有使用 `@inquirer/prompts` 的交互式命令统一捕获用户中断 (`AbortError`)
+- 捕获后静默退出, 进程退出码为 0 (正常退出)
+- 不改变任何已有的业务逻辑
+
+## Capabilities
+
+### New Capabilities
+
+(无)
+
+### Modified Capabilities
+
+- `project-operations`: init, add, remove, sync 命令需要支持用户中断时的优雅退出
+- `server-management`: server-add 命令需要支持用户中断时的优雅退出
+
+## Impact
+
+- 影响文件: `src/commands/init.ts`, `src/commands/setup.ts`, `src/commands/add.ts`, `src/commands/remove.ts`, `src/commands/server-add.ts`, `src/commands/sync.ts`
+- 不影响 API, 依赖或外部系统

package/openspec/changes/archive/2026-03-12-graceful-exit-on-interrupt/specs/project-operations/spec.md

@@ -0,0 +1,30 @@
+## ADDED Requirements
+
+### 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

package/openspec/changes/archive/2026-03-12-graceful-exit-on-interrupt/specs/server-management/spec.md

@@ -0,0 +1,15 @@
+## ADDED Requirements
+
+### 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/openspec/changes/archive/2026-03-12-graceful-exit-on-interrupt/tasks.md

@@ -0,0 +1,17 @@
+## 1. 工具函数
+
+- [x] 1.1 在 `src/utils/` 下创建 `prompt.ts`, 实现 `isUserCancellation(error): boolean` 函数, 通过检测 `ExitPromptError` (从 `@inquirer/prompts` 导入) 判断是否为用户主动取消
+
+## 2. 命令改造
+
+- [x] 2.1 在 `src/commands/init.ts` 的 action handler 中添加 try-catch, 捕获 ExitPromptError 后静默 return
+- [x] 2.2 在 `src/commands/setup.ts` 的 action handler 中添加 try-catch, 捕获 ExitPromptError 后静默 return
+- [x] 2.3 在 `src/commands/add.ts` 的 action handler 中添加 try-catch, 捕获 ExitPromptError 后静默 return
+- [x] 2.4 在 `src/commands/remove.ts` 的 action handler 中添加 try-catch, 捕获 ExitPromptError 后静默 return
+- [x] 2.5 在 `src/commands/server-add.ts` 的 action handler 中添加 try-catch, 捕获 ExitPromptError 后静默 return
+- [x] 2.6 在 `src/commands/sync.ts` 的 action handler 中添加 try-catch, 捕获 ExitPromptError 后静默 return
+
+## 3. 验证
+
+- [x] 3.1 构建项目确认无编译错误
+- [x] 3.2 手动测试: 在各命令的 prompt 中按 Ctrl-C, 确认静默退出且退出码为 0

package/openspec/changes/archive/2026-03-12-mcps-manager-cli/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-11

package/openspec/changes/archive/2026-03-12-mcps-manager-cli/design.md

@@ -0,0 +1,104 @@
+## Context
+
+多个编程 agent (Claude Code, Codex CLI, Gemini CLI, OpenCode, Antigravity) 各自使用不同的 MCP 配置格式和文件位置.  开发者在项目中使用多个 agent 时, 需要手动维护多份配置, 格式各异 (JSON/TOML), schema 各异 (key 名, transport type 值, command 格式等).  当前没有统一管理工具.
+
+参考项目 skills-manager 和 rules-manager 的两层存储 + 项目部署模式, 构建 mcpsmgr CLI.
+
+### 各 Agent 配置差异摘要
+
+| Agent | 文件 | 格式 | 顶层 key | env key | command 格式 | 作用域 |
+|-------|------|------|----------|---------|-------------|--------|
+| Claude Code | .mcp.json | JSON | mcpServers | env | string + args | 项目 |
+| Codex CLI | .codex/config.toml | TOML | mcp_servers | env | string + args | 项目 |
+| Gemini CLI | .gemini/settings.json | JSON | mcpServers | env | string + args | 项目 |
+| OpenCode | opencode.json | JSON | mcp | environment | array (含 cmd) | 项目 |
+| Antigravity | ~/.gemini/antigravity/mcp_config.json | JSON | mcpServers | env | string + args | 全局 |
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- 提供统一 CLI 管理 5 个 agent 的 MCP 配置
+- 中央仓库 (`~/.mcps-manager/`) 存储服务定义, 含 API key
+- 合并写入各 agent 配置文件, 不影响无关内容
+- 通过 GLM5 + Web Reader 自动分析 MCP 文档, 生成 per-agent 配置
+- 无状态追踪, 直接读取各 agent 实际配置文件
+- 支持 URL 和 GitHub `owner/repo` 简写添加服务
+
+**Non-Goals:**
+
+- 不做 profiles (预设服务组合), 后续按需添加
+- 不内置 registry 模板, 所有服务通过用户手动或 GLM5 分析添加
+- 不支持 `@scope/package` npm 包格式作为添加输入
+- 不管理 agent 本身的安装或其他非 MCP 配置
+
+## Decisions
+
+### D1: Adapter 模式处理各 agent 配置差异
+
+每个 agent 实现一个 Adapter, 包含 read / write / toAgentFormat / fromAgentFormat 方法.  Adapter 负责:
+- 解析目标配置文件 (JSON 或 TOML)
+- 仅修改 MCP 相关部分, 保留其他内容
+- 将通用服务定义转换为 agent 特定的 schema
+
+**备选方案**: 统一模板 + 变量替换.  放弃原因: 各 agent 的 schema 差异过大 (key 名, 值格式, transport type 都不同), 模板无法覆盖.
+
+### D2: 中央仓库直接存储 API key (明文)
+
+服务定义文件中直接保存 key 明文.  因为工具完全本地运行, 无网络传输风险.  通过文件权限 (目录 700, 文件 600) 保护.
+
+**备选方案**: 环境变量引用 / keychain 集成.  放弃原因: 增加复杂度, 本地工具无传输隐私问题.
+
+### D3: 合并写入而非 symlink
+
+配置文件多为混合文件 (MCP 只是其中一部分), symlink 会覆盖其他配置.  采用 read-modify-write: 读取目标文件 → 解析 → 修改 MCP 部分 → 序列化回写.
+
+**备选方案**: 仅管理专用文件 (如 .mcp.json).  放弃原因: 实用性太窄, 大部分 agent 的 MCP 配置嵌在混合文件中.
+
+### D4: 通用服务定义格式
+
+```json
+{
+  "name": "brave-search",
+  "source": "https://github.com/anthropics/mcp-brave-search",
+  "default": {
+    "transport": "stdio",
+    "command": "npx",
+    "args": ["-y", "@anthropic/mcp-brave-search"],
+    "env": { "BRAVE_API_KEY": "sk-xxx" }
+  },
+  "overrides": {
+    "claude-code": {
+      "transport": "http",
+      "url": "https://example.com/mcp",
+      "headers": { "Authorization": "Bearer sk-xxx" }
+    }
+  }
+}
+```
+
+有 override 用 override, 没有用 default 经 adapter 格式转换.
+
+### D5: GLM5 Agent 分析文档
+
+添加服务时, 用户提供 URL 或 GitHub owner/repo.  mcpsmgr 调用 GLM5, 将 webReader 作为 function calling tool 提供.  GLM5 自主决定是否调用 webReader 获取文档内容, 分析后返回结构化配置.
+
+GitHub owner/repo 优先拼接 README URL: `https://github.com/{owner}/{repo}/blob/main/README.md`.  README 不存在则给仓库首页, 由 GLM5 自行探索.
+
+### D6: 无状态文件, 读取追踪
+
+不维护项目状态文件.  `list` 命令直接扫描各 agent 的实际配置文件, 解析出已配置的 MCP 服务.  这样:
+- 用户手动修改配置后, 状态自动保持最新
+- 不存在状态与实际不一致的问题
+
+### D7: 同名冲突报错不修改
+
+中央仓库添加同名服务 → 报错, 提示先 remove.  项目部署时目标文件已有同名服务 → 报告冲突, 不修改该 agent 的配置文件.
+
+## Risks / Trade-offs
+
+- [TOML 序列化保真度] 读取 .codex/config.toml 后重新序列化可能丢失注释和格式 → 使用保留注释的 TOML 库 (如 @iarna/toml 或 smol-toml), 优先保留原始格式
+- [GLM5 分析准确性] LLM 可能误判配置 → 展示详细分析结果让用户选择是否信任, 不信任则回退手动模式
+- [配置文件并发修改] 用户在 mcpsmgr 操作同时手动编辑配置文件 → 概率极低, 不特别处理
+- [Web Reader 调用配额] 智谱 Web Reader MCP 有月度调用限制 (Lite 100 次) → 仅在 server add 时调用, 频率很低
+- [Antigravity 未来支持项目级配置] Google 可能后续添加项目级支持 → Adapter 抽象层便于扩展, 届时新增配置路径即可

package/openspec/changes/archive/2026-03-12-mcps-manager-cli/proposal.md

@@ -0,0 +1,34 @@
+## Why
+
+多个编程 agent (Claude Code, Codex CLI, Gemini CLI, OpenCode, Antigravity) 都支持 MCP, 但配置格式各不相同.  给项目添加一个 MCP 服务需要手动修改多个配置文件, 格式转换容易出错, 维护成本高.  需要一个统一的命令行工具来集中管理 MCP 服务定义, 并自动部署到各 agent 的配置文件中.
+
+## What Changes
+
+- 新建 CLI 工具 `mcpsmgr`, 发布为 npm 包
+- 中央仓库 `~/.mcps-manager/` 存储 MCP 服务定义 (含 API key 等敏感信息)
+- 支持通过 URL 或 GitHub `owner/repo` 简写添加 MCP 服务
+- 集成 GLM5 + 智谱 Web Reader MCP 自动分析文档, 生成 per-agent 配置
+- 合并写入各 agent 配置文件, 不影响无关内容
+- 无状态追踪, 直接读取各 agent 实际配置文件
+- 支持 5 个 agent: Claude Code, Codex CLI, Gemini CLI, OpenCode, Antigravity
+- Antigravity 仅支持全局配置, 其余支持项目级配置
+
+## Capabilities
+
+### New Capabilities
+
+- `central-storage`: 中央仓库管理, 包括 setup 初始化, config.json 配置 (GLM5 key, Web Reader key, 端点选择), 服务定义文件的 CRUD
+- `server-management`: MCP 服务的添加 (URL/GitHub 简写), 移除, 列出; 通过 GLM5 分析文档自动生成 default + per-agent overrides 配置
+- `agent-adapters`: 各 agent 的配置适配器, 包括配置文件的读取, 合并写入, 格式转换 (JSON/TOML), 同名冲突检测
+- `project-operations`: 项目级操作, 包括 init (交互式选择 agent 和服务), add/remove (项目中添加或移除服务), sync (同步中央仓库变更到项目), list (跨 agent 状态矩阵)
+- `glm-integration`: GLM5 API 调用, Web Reader MCP 工具集成, 文档分析 prompt 管理, function calling 多轮对话处理
+
+### Modified Capabilities
+
+## Impact
+
+- 新建 TypeScript 项目, 使用 tsup 打包, vitest 测试
+- 依赖: TOML 解析库 (处理 Codex CLI 配置), HTTP 客户端 (调用 GLM5 和 Web Reader), 交互式 CLI 库 (inquirer 或类似)
+- 需要用户提供智谱平台的 API key (GLM5 + Web Reader)
+- 文件系统操作: 读写 `~/.mcps-manager/` 和各 agent 项目级配置文件
+- 文件权限: `~/.mcps-manager/` 目录 700, 服务定义文件 600

package/openspec/changes/archive/2026-03-12-mcps-manager-cli/specs/agent-adapters/spec.md

@@ -0,0 +1,110 @@
+## ADDED Requirements
+
+### 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` 下添加服务条目, 格式为 `{ "type": "<transport>", "command": "<cmd>", "args": [...], "env": {...} }` 或 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 下添加服务配置, 格式为 `command = "...", args = [...], 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` 下添加服务条目, 格式为 `{ "command": "...", "args": [...], "env": {...} }`, 保留文件中已有的其他字段 (如 `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": ["<cmd>", "<arg1>", ...], "environment": {...} }`, 注意 `command` MUST 为数组 (包含命令和参数), `env` key MUST 转换为 `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` 下添加服务条目, 格式为 `{ "command": "...", "args": [...], "env": {...} }` 或 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/changes/archive/2026-03-12-mcps-manager-cli/specs/central-storage/spec.md

@@ -0,0 +1,38 @@
+## ADDED 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/changes/archive/2026-03-12-mcps-manager-cli/specs/glm-integration/spec.md

@@ -0,0 +1,66 @@
+## ADDED 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/changes/archive/2026-03-12-mcps-manager-cli/specs/project-operations/spec.md

@@ -0,0 +1,76 @@
+## ADDED Requirements
+
+### Requirement: 项目初始化
+
+系统 SHALL 支持 `mcpsmgr init` 命令, 在当前项目中交互式选择 agent 和 MCP 服务.
+
+#### Scenario: 交互式初始化
+
+- **WHEN** 用户在项目目录执行 `mcpsmgr init`
+- **THEN** 系统自动检测已存在的 agent 配置文件并预选, 展示所有支持的 agent 供用户勾选, 从中央仓库列出所有已保存的 MCP 服务供用户勾选, 展示即将执行的操作预览, 确认后将选中的服务写入选中的 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 配置文件, 展示列表供用户勾选, 将服务写入勾选的 agent 配置文件
+
+#### Scenario: 服务不存在于中央仓库
+
+- **WHEN** 用户执行 `mcpsmgr add nonexistent`
+- **THEN** 系统报错, 提示服务不存在于中央仓库
+
+#### Scenario: 部分 agent 同名冲突
+
+- **WHEN** 添加时某些 agent 配置文件中已存在同名服务
+- **THEN** 系统对冲突的 agent 报告跳过, 对无冲突的 agent 正常写入
+
+### Requirement: 项目移除服务
+
+系统 SHALL 支持 `mcpsmgr remove <server-name>` 命令, 从当前项目的 agent 配置中移除服务.
+
+#### Scenario: 从多个 agent 移除
+
+- **WHEN** 用户执行 `mcpsmgr remove brave-search`
+- **THEN** 系统列出包含该服务的所有 agent 配置, 供用户勾选要移除的, 从勾选的 agent 配置文件中删除该服务条目, 保留文件中的其他内容
+
+#### Scenario: 无 agent 包含该服务
+
+- **WHEN** 用户执行 `mcpsmgr remove nonexistent` 但没有任何 agent 配置包含该服务
+- **THEN** 系统提示未在任何 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`

package/openspec/changes/archive/2026-03-12-mcps-manager-cli/specs/server-management/spec.md

@@ -0,0 +1,75 @@
+## ADDED 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 中的值 (隐藏输入), 保存到中央仓库
+
+#### 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

package/openspec/changes/archive/2026-03-12-mcps-manager-cli/tasks.md

@@ -0,0 +1,60 @@
+## 1. 项目初始化
+
+- [x] 1.1 初始化 npm 项目, 配置 package.json (name: mcpsmgr, bin 入口), tsconfig.json, tsup 打包配置, vitest 测试配置
+- [x] 1.2 搭建 src/ 目录结构: commands/, adapters/, services/, utils/, types.ts, index.ts (CLI 入口)
+- [x] 1.3 安装依赖: TOML 解析库, HTTP 客户端, 交互式 CLI 库 (inquirer/prompts), CLI 框架 (commander)
+
+## 2. 类型定义与通用服务定义格式
+
+- [x] 2.1 定义 ServerDefinition 类型 (name, source, default, overrides)
+- [x] 2.2 定义 DefaultConfig 类型 (transport, command, args, env, url, headers)
+- [x] 2.3 定义 AgentAdapter 接口 (read, write, remove, has, toAgentFormat, fromAgentFormat)
+- [x] 2.4 定义 GlobalConfig 类型 (glm.apiKey, glm.endpoint, webReader.apiKey, webReader.url)
+
+## 3. 中央仓库管理 (central-storage)
+
+- [x] 3.1 实现 setup 命令: 创建 ~/.mcps-manager/ 和 servers/ 目录, 设置权限 700
+- [x] 3.2 实现 setup 交互流程: 收集 GLM5 API Key, 端点选择, 保存 config.json (权限 600). Web Reader API Key 复用 GLM5 API Key
+- [x] 3.3 实现 config.json 读写工具函数
+- [x] 3.4 实现服务定义文件的读写工具函数 (含权限 600 设置)
+
+## 4. Agent Adapters
+
+- [x] 4.1 实现 Claude Code Adapter: 读写 .mcp.json, mcpServers 格式转换
+- [x] 4.2 实现 Codex CLI Adapter: 读写 .codex/config.toml, mcp_servers TOML 格式转换, 保留非 MCP section 和注释
+- [x] 4.3 实现 Gemini CLI Adapter: 读写 .gemini/settings.json, mcpServers 格式转换, 保留非 MCP 字段
+- [x] 4.4 实现 OpenCode Adapter: 读写 opencode.json, mcp 格式转换 (command 数组, environment key, type local/remote)
+- [x] 4.5 实现 Antigravity Adapter: 读写 ~/.gemini/antigravity/mcp_config.json (全局), mcpServers 格式转换 (HTTP 时用 serverUrl)
+- [x] 4.6 实现 Agent 自动检测: 扫描项目目录判断哪些 agent 配置文件已存在
+- [x] 4.7 编写各 adapter 的单元测试
+
+## 5. GLM5 集成 (glm-integration)
+
+- [x] 5.1 实现 GLM5 API 客户端: Chat Completion 请求封装, Bearer 认证
+- [x] 5.2 实现 webReader function calling 工具定义
+- [x] 5.3 实现 Web Reader MCP 调用: 向 Web Reader 端点发送请求, 获取网页内容
+- [x] 5.4 实现多轮对话处理: 循环处理 tool_calls, 回传结果, 直到获得最终分析
+- [x] 5.5 实现分析结果解析: 从 GLM5 响应中提取结构化 JSON (name, default, overrides, requiredEnvVars)
+- [x] 5.6 实现 GitHub owner/repo 解析: 判断输入格式, 拼接 GitHub URL, 构造 user message 指示优先读 README
+- [x] 5.7 编写 system prompt: 指示 GLM5 分析 MCP 文档, 提取 5 个 agent 的配置差异
+
+## 6. 服务管理命令 (server-management)
+
+- [x] 6.1 实现 server add 命令: 解析输入 (URL / owner/repo / 不合法格式), 调用 GLM5 分析, 展示结果, 用户确认, 收集 env 变量值, 保存到中央仓库
+- [x] 6.2 实现 server add 手动模式回退: 无 URL 或用户不信任 GLM5 时的交互式配置
+- [x] 6.3 实现 server remove 命令: 从中央仓库删除服务定义文件
+- [x] 6.4 实现 server list 命令: 列出中央仓库所有服务
+
+## 7. 项目操作命令 (project-operations)
+
+- [x] 7.1 实现 init 命令: 交互式选择 agent (含自动检测预选) + 选择中央仓库中的服务 + 确认 + 批量写入
+- [x] 7.2 实现 add 命令: 从中央仓库取服务定义, 检测项目 agent, 用户勾选, 写入配置 (含同名冲突跳过)
+- [x] 7.3 实现 remove 命令: 扫描各 agent 配置中包含该服务的, 用户勾选, 删除条目
+- [x] 7.4 实现 sync 命令: 比对中央仓库与项目 agent 配置, 展示变更预览, 确认后更新
+- [x] 7.5 实现 list 命令: 扫描各 agent 配置, 生成跨 agent 状态矩阵表格
+
+## 8. CLI 入口与集成
+
+- [x] 8.1 使用 commander 注册所有命令和子命令 (setup, server add/remove/list, init, add, remove, sync, list)
+- [x] 8.2 添加 setup 前置检查: 非 setup 命令执行前检测 ~/.mcps-manager/config.json 是否存在
+- [x] 8.3 端到端测试: 完整流程测试 (setup → server add → init → add → list → sync → remove)