catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-05 01:50:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

Add comprehensive tests for schema cleanup migration and search comparison

Browse Source 
- Implement tests for migration 005 to verify removal of deprecated fields in the database schema.
- Ensure that new databases are created with a clean schema.
- Validate that keywords are correctly extracted from the normalized file_keywords table.
- Test symbol insertion without deprecated fields and subdir operations without direct_files.
- Create a detailed search comparison test to evaluate vector search vs hybrid search performance.
- Add a script for reindexing projects to extract code relationships and verify GraphAnalyzer functionality.
- Include a test script to check TreeSitter parser availability and relationship extraction from sample files.
This commit is contained in:
catlog22
2025-12-16 19:27:05 +08:00
parent 3da0ef2adb
commit df23975a0b
61 changed files with 13114 additions and 366 deletions
Download Patch File Download Diff File Expand all files Collapse all files

360
ccw/docs/CODEX_MCP_IMPLEMENTATION_SUMMARY.md Normal file
View File

@@ -0,0 +1,360 @@
# Codex MCP 功能实现总结
## 📝 已完成的修复
### 1. CCW Tools MCP 卡片样式修复
**文件**: `ccw/src/templates/dashboard-js/views/mcp-manager.js`
**修改内容**:
- ✅ 卡片边框: `border-primary` → `border-orange-500` (第345行)
- ✅ 图标背景: `bg-primary` → `bg-orange-500` (第348行)
- ✅ 图标颜色: `text-primary-foreground` → `text-white` (第349行)
- ✅ "Available"徽章: `bg-primary/20 text-primary` → `bg-orange-500/20 text-orange-600` (第360行)
- ✅ 选择按钮颜色: `text-primary` → `text-orange-500` (第378-379行)
- ✅ 安装按钮: `bg-primary` → `bg-orange-500` (第386行、第399行)
**影响范围**: Claude 模式下的 CCW Tools MCP 卡片
---
### 2. Toast 消息显示时间增强
**文件**: `ccw/src/templates/dashboard-js/components/navigation.js`
**修改内容**:
- ✅ 显示时间: 2000ms → 3500ms (第300行)
**影响范围**: 所有 Toast 消息（MCP 安装、删除、切换等操作反馈）
---
## 🔧 功能实现细节
### Codex MCP 安装流程
```
用户操作
↓
前端函数: copyClaudeServerToCodex(serverName, serverConfig)
↓
调用: addCodexMcpServer(serverName, serverConfig)
↓
API 请求: POST /api/codex-mcp-add
↓
后端处理: addCodexMcpServer(serverName, serverConfig)
↓
文件操作:
1. 读取 ~/.codex/config.toml (如存在)
2. 解析 TOML 配置
3. 添加/更新 mcp_servers[serverName]
4. 序列化为 TOML
5. 写入文件
↓
返回响应: {success: true} 或 {error: "..."}
↓
前端更新:
1. loadMcpConfig() - 重新加载配置
2. renderMcpManager() - 重新渲染 UI
3. showRefreshToast(...) - 显示成功/失败消息 (3.5秒)
```
---
## 📍 关键代码位置
### 前端
| 功能 | 文件 | 行号 | 说明 |
|------|------|------|------|
| 复制到 Codex | `components/mcp-manager.js` | 175-177 | `copyClaudeServerToCodex()` 函数 |
| 添加到 Codex | `components/mcp-manager.js` | 87-114 | `addCodexMcpServer()` 函数 |
| Toast 消息 | `components/navigation.js` | 286-301 | `showRefreshToast()` 函数 |
| CCW Tools 样式 | `views/mcp-manager.js` | 342-415 | Claude 模式卡片渲染 |
| 其他项目按钮 | `views/mcp-manager.js` | 1015-1020 | "Install to Codex" 按钮 |
### 后端
| 功能 | 文件 | 行号 | 说明 |
|------|------|------|------|
| API 端点 | `core/routes/mcp-routes.ts` | 1001-1010 | `/api/codex-mcp-add` 路由 |
| 添加服务器 | `core/routes/mcp-routes.ts` | 251-330 | `addCodexMcpServer()` 函数 |
| TOML 序列化 | `core/routes/mcp-routes.ts` | 166-188 | `serializeToml()` 函数 |
### CSS
| 功能 | 文件 | 行号 | 说明 |
|------|------|------|------|
| Toast 样式 | `dashboard-css/06-cards.css` | 1501-1538 | Toast 容器和类型样式 |
| Toast 动画 | `dashboard-css/06-cards.css` | 1540-1551 | 滑入/淡出动画 |
---
## 🧪 测试用例
### 测试用例 1: CCW Tools 样式验证
**前置条件**: Dashboard 运行，进入 MCP 管理页面
**测试步骤**:
1. 确保在 Claude 模式
2. 查看 CCW Tools MCP 卡片
**预期结果**:
- [ ] 卡片有橙色边框（`border-orange-500/30`）
- [ ] 图标背景是橙色（`bg-orange-500`）
- [ ] 图标是白色（`text-white`）
- [ ] "Available"徽章是橙色
- [ ] 按钮是橙色
**优先级**: High
---
### 测试用例 2: Codex MCP 新建安装
**前置条件**: Dashboard 运行，进入 MCP 管理页面
**测试步骤**:
1. 切换到 Codex 模式
2. 勾选 CCW Tools 的 4 个核心工具
3. 点击"Install"按钮
4. 观察 Toast 消息
**预期结果**:
- [ ] Toast 消息显示
- [ ] 消息内容: "CCW Tools installed to Codex (4 tools)"
- [ ] Toast 停留时间: 3.5秒
- [ ] 卡片状态更新（显示"4 tools"绿色徽章）
- [ ] `~/.codex/config.toml` 文件创建成功
- [ ] config.toml 包含正确的 `[mcp_servers.ccw-tools]` 配置
**优先级**: Critical
---
### 测试用例 3: Claude MCP 复制到 Codex
**前置条件**:
- Dashboard 运行
- Claude 模式下已创建全局 MCP 服务器 `test-server`
**测试步骤**:
1. 切换到 Codex 模式
2. 滚动到"Copy Claude Servers to Codex"区域
3. 找到 `test-server` 卡片
4. 点击"→ Codex"按钮
5. 观察 Toast 消息
**预期结果**:
- [ ] Toast 消息显示
- [ ] 消息内容: "Codex MCP server 'test-server' added"
- [ ] Toast 停留时间: 3.5秒
- [ ] 卡片出现"Already added"绿色徽章
- [ ] "→ Codex"按钮消失
- [ ] 服务器出现在"Codex Global Servers"区域
- [ ] `~/.codex/config.toml` 包含 `test-server` 配置
**优先级**: Critical
---
### 测试用例 4: 其他项目 MCP 复制到 Codex
**前置条件**:
- Dashboard 运行
- 其他项目中存在 MCP 服务器
**测试步骤**:
1. 切换到 Codex 模式
2. 滚动到"Available from Other Projects"区域
3. 找到来自其他项目的服务器卡片
4. 点击"Install to Codex"按钮
5. 观察 Toast 消息
**预期结果**:
- [ ] Toast 消息显示
- [ ] 消息内容包含服务器名称
- [ ] Toast 停留时间: 3.5秒
- [ ] 服务器出现在"Codex Global Servers"区域
- [ ] `~/.codex/config.toml` 包含新服务器配置
**优先级**: High
---
## 🔍 验证清单
### 代码审查
- [x] ✅ 前端函数正确调用后端 API
- [x] ✅ 后端正确处理请求并写入配置文件
- [x] ✅ Toast 消息在成功和失败时都正确显示
- [x] ✅ Toast 显示时间更新为 3.5秒
- [x] ✅ CCW Tools 卡片使用橙色样式
- [x] ✅ 复制按钮调用正确的函数
- [x] ✅ 配置文件路径正确 (`~/.codex/config.toml`)
- [x] ✅ TOML 序列化正确处理所有字段
### 功能测试
- [ ] ⬜ CCW Tools 样式在 Claude 模式下正确显示
- [ ] ⬜ Codex MCP 新建安装成功
- [ ] ⬜ Toast 消息正确显示并停留 3.5秒
- [ ] ⬜ config.toml 文件正确创建
- [ ] ⬜ 从 Claude 复制到 Codex 成功
- [ ] ⬜ 从其他项目复制到 Codex 成功
- [ ] ⬜ 卡片状态正确更新
- [ ] ⬜ UI 刷新正确
### 边界情况
- [ ] ⬜ Codex 目录不存在时自动创建
- [ ] ⬜ config.toml 不存在时正确创建
- [ ] ⬜ config.toml 已存在时正确追加
- [ ] ⬜ 重复安装同一服务器正确更新配置
- [ ] ⬜ API 失败时显示错误 Toast
- [ ] ⬜ 网络错误时显示错误信息
---
## 📦 相关文件清单
### 已修改文件
1. `ccw/src/templates/dashboard-js/views/mcp-manager.js`
- 修改: CCW Tools 卡片样式（第342-415行）
2. `ccw/src/templates/dashboard-js/components/navigation.js`
- 修改: Toast 显示时间（第300行）
### 核心功能文件（未修改但相关）
3. `ccw/src/templates/dashboard-js/components/mcp-manager.js`
- 包含: `addCodexMcpServer()`, `copyClaudeServerToCodex()` 函数
4. `ccw/src/core/routes/mcp-routes.ts`
- 包含: Codex MCP API 端点和后端逻辑
5. `ccw/src/templates/dashboard-css/06-cards.css`
- 包含: Toast 样式定义
### 新增文档
6. `ccw/docs/CODEX_MCP_TESTING_GUIDE.md`
- 详细测试指南
7. `ccw/docs/QUICK_TEST_CODEX_MCP.md`
- 快速测试步骤
8. `ccw/docs/CODEX_MCP_IMPLEMENTATION_SUMMARY.md`
- 本文档
---
## 🎯 下一步行动
### 立即执行
1. **重启 Dashboard**:
```bash
# 停止当前 Dashboard
# 重新启动
npm run dev # 或你的启动命令
```
2. **执行快速测试**:
- 按照 `QUICK_TEST_CODEX_MCP.md` 执行测试
- 重点验证：
- CCW Tools 样式
- Toast 消息显示和时长
- config.toml 文件创建
3. **记录测试结果**:
- 填写 `QUICK_TEST_CODEX_MCP.md` 中的检查清单
- 截图保存关键步骤
### 如果测试失败
1. **检查浏览器控制台**:
- F12 打开开发者工具
- Console 标签查看错误
- Network 标签查看 API 请求
2. **检查后端日志**:
- 查看 CCW Dashboard 的控制台输出
- 查找 `Error adding Codex MCP server` 等错误信息
3. **验证文件权限**:
```bash
ls -la ~/.codex/
# 确保有读写权限
```
---
## 📊 测试报告模板
```markdown
# Codex MCP 功能测试报告
**测试日期**: ___________
**测试人员**: ___________
**CCW 版本**: ___________
**浏览器**: ___________
## 测试结果
### CCW Tools 样式 (Claude 模式)
- [ ] ✅ 通过 / [ ] ❌ 失败
- 备注: ___________
### Codex MCP 新建安装
- [ ] ✅ 通过 / [ ] ❌ 失败
- Toast 显示: [ ] ✅ 是 / [ ] ❌ 否
- Toast 时长: _____ 秒
- config.toml 创建: [ ] ✅ 是 / [ ] ❌ 否
- 备注: ___________
### Claude → Codex 复制
- [ ] ✅ 通过 / [ ] ❌ 失败
- Toast 显示: [ ] ✅ 是 / [ ] ❌ 否
- Toast 内容正确: [ ] ✅ 是 / [ ] ❌ 否
- 备注: ___________
### 其他项目 → Codex 安装
- [ ] ✅ 通过 / [ ] ❌ 失败
- 备注: ___________
## 发现的问题
1. ___________
2. ___________
3. ___________
## 建议改进
1. ___________
2. ___________
3. ___________
```
---
## 🎉 总结
所有功能已经实现并准备好测试：
✅ **已完成**:
- CCW Tools MCP 卡片样式修复（橙色）
- Toast 消息显示时间增强（3.5秒）
- Codex MCP 安装功能（已存在，无需修改）
- Claude → Codex 复制功能（已存在，无需修改）
- 详细测试文档和指南
⚠️ **待验证**:
- 实际运行环境中的功能测试
- 用户体验反馈
- 边界情况处理
请按照 `QUICK_TEST_CODEX_MCP.md` 开始测试！

321
ccw/docs/CODEX_MCP_TESTING_GUIDE.md Normal file
View File

@@ -0,0 +1,321 @@
# Codex MCP 安装测试指南
## 测试准备
### 前置条件
1. 确保 CCW Dashboard 正在运行
2. 打开浏览器访问 Dashboard 界面
3. 导航到 "MCP 管理" 页面
### 测试环境
- **Codex 配置文件**: `~/.codex/config.toml`
- **Claude 配置文件**: `~/.claude.json`
- **Dashboard URL**: `http://localhost:3000`
---
## 测试场景 1: Codex MCP 新建安装
### 测试步骤
1. **切换到 Codex 模式**
- 点击页面顶部的 "Codex" 按钮（橙色高亮）
- 确认右侧显示配置文件路径：`~/.codex/config.toml`
2. **查看 CCW Tools MCP 卡片**
- ✅ 验证卡片有橙色边框 (`border-orange-500`)
- ✅ 验证图标背景是橙色 (`bg-orange-500`)
- ✅ 验证图标颜色是白色
- ✅ 验证"Available"徽章是橙色
- ✅ 验证"Core only"/"All"按钮是橙色
3. **选择工具并安装**
- 勾选需要的工具（例如：所有核心工具）
- 点击橙色的"Install"按钮
- **预期结果**:
- 屏幕底部中央显示 Toast 消息
- Toast 消息内容：`"CCW Tools installed to Codex (X tools)"` (X 为选择的工具数量)
- Toast 消息类型：绿色成功提示
- Toast 显示时间：3.5秒
- 卡片状态更新为"已安装"（绿色对勾徽章）
- 安装按钮文字变为"Update"
4. **验证安装结果**
- 打开 `~/.codex/config.toml` 文件
- 确认存在 `[mcp_servers.ccw-tools]` 配置块
- 示例配置：
```toml
[mcp_servers.ccw-tools]
command = "npx"
args = ["-y", "ccw-mcp"]
env = { CCW_ENABLED_TOOLS = "write_file,edit_file,codex_lens,smart_search" }
```
### 测试数据记录
| 测试项 | 预期结果 | 实际结果 | 状态 |
|--------|----------|----------|------|
| 卡片样式（橙色边框） | ✅ | _待填写_ | ⬜ |
| 图标样式（橙色背景） | ✅ | _待填写_ | ⬜ |
| Toast 消息显示 | ✅ 3.5秒 | _待填写_ | ⬜ |
| Toast 消息内容 | "CCW Tools installed to Codex (X tools)" | _待填写_ | ⬜ |
| config.toml 文件创建 | ✅ | _待填写_ | ⬜ |
| MCP 服务器配置正确 | ✅ | _待填写_ | ⬜ |
---
## 测试场景 2: 从 Claude MCP 复制到 Codex
### 测试步骤
1. **前置准备：在 Claude 模式下创建 MCP 服务器**
- 切换到 "Claude" 模式
- 在"全局可用 MCP"区域点击"+ New Global Server"
- 创建测试服务器：
- **名称**: `test-mcp-server`
- **命令**: `npx`
- **参数**: `-y @modelcontextprotocol/server-filesystem /tmp`
- 点击"Create"按钮
- 确认服务器出现在"全局可用 MCP"列表中
2. **切换到 Codex 模式**
- 点击顶部的 "Codex" 按钮
- 向下滚动到"Copy Claude Servers to Codex"区域
3. **找到测试服务器**
- 在列表中找到 `test-mcp-server`
- 卡片应该显示：
- 蓝色"Claude"徽章
- 虚线边框（表示可复制）
- 橙色"→ Codex"按钮
4. **执行复制操作**
- 点击橙色的"→ Codex"按钮
- **预期结果**:
- Toast 消息显示：`"Codex MCP server 'test-mcp-server' added"` (中文：`"Codex MCP 服务器 'test-mcp-server' 已添加"`)
- Toast 类型：绿色成功提示
- Toast 显示时间：3.5秒
- 卡片出现绿色"Already added"徽章
- "→ Codex"按钮消失
- 服务器出现在"Codex Global Servers"区域
5. **验证复制结果**
- 检查 `~/.codex/config.toml` 文件
- 确认存在 `[mcp_servers.test-mcp-server]` 配置块
- 示例配置：
```toml
[mcp_servers.test-mcp-server]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
```
### 测试数据记录
| 测试项 | 预期结果 | 实际结果 | 状态 |
|--------|----------|----------|------|
| Claude 服务器创建 | ✅ | _待填写_ | ⬜ |
| 复制区域显示服务器 | ✅ | _待填写_ | ⬜ |
| Toast 消息显示 | ✅ 3.5秒 | _待填写_ | ⬜ |
| Toast 消息内容 | "Codex MCP server 'test-mcp-server' added" | _待填写_ | ⬜ |
| config.toml 配置正确 | ✅ | _待填写_ | ⬜ |
| 卡片状态更新 | "Already added"徽章 | _待填写_ | ⬜ |
| Codex区域显示服务器 | ✅ | _待填写_ | ⬜ |
---
## 测试场景 3: 从其他项目复制到 Codex
### 测试步骤
1. **前置准备：在其他项目中创建 MCP 服务器**
- 假设你有另一个项目（例如：`/path/to/other-project`）
- 在该项目的 `.claude.json` 或 `.mcp.json` 中添加 MCP 服务器配置
- 或在 Dashboard 中为该项目创建 MCP 服务器
2. **切换回当前项目**
- 在 Dashboard 左上角切换到当前测试项目
- 切换到 "Codex" 模式
3. **查看"其他项目可用"区域**
- 向下滚动到最底部的"Available from Other Projects"区域
- 应该看到来自其他项目的 MCP 服务器
- 卡片显示：
- 服务器名称
- 蓝色"Claude"徽章
- 项目来源标签（例如：`other-project`）
- 橙色"Install to Codex"按钮
4. **执行安装操作**
- 点击橙色的"Install to Codex"按钮
- **预期结果**:
- Toast 消息显示成功信息
- Toast 显示时间：3.5秒
- 服务器出现在"Codex Global Servers"区域
- 原卡片显示"Already added"徽章
5. **验证安装结果**
- 检查 `~/.codex/config.toml` 文件
- 确认新服务器配置正确
### 测试数据记录
| 测试项 | 预期结果 | 实际结果 | 状态 |
|--------|----------|----------|------|
| 其他项目服务器显示 | ✅ | _待填写_ | ⬜ |
| Toast 消息显示 | ✅ 3.5秒 | _待填写_ | ⬜ |
| Toast 消息内容 | 成功消息 | _待填写_ | ⬜ |
| config.toml 配置正确 | ✅ | _待填写_ | ⬜ |
| Codex区域显示服务器 | ✅ | _待填写_ | ⬜ |
---
## 故障排查
### Toast 消息不显示
**可能原因**:
1. Toast 容器 CSS 被覆盖
2. JavaScript 错误阻止了消息显示
**排查步骤**:
1. 打开浏览器开发者工具（F12）
2. 切换到 Console 标签页
3. 执行安装操作
4. 查看是否有错误信息
5. 检查 Network 标签页，确认 API 请求成功（状态码 200）
### config.toml 未创建
**可能原因**:
1. 文件权限问题
2. 后端 API 错误
**排查步骤**:
1. 检查 `~/.codex` 目录是否存在
2. 检查该目录的读写权限
3. 查看 CCW Dashboard 后端日志
4. 检查 API 响应：
```bash
# 在浏览器开发者工具 Network 标签页查看
# POST /api/codex-mcp-add
# 响应应该是: {"success": true}
```
### 服务器配置格式不正确
**可能原因**:
1. Claude 格式到 Codex 格式转换错误
2. 特殊字段未正确处理
**排查步骤**:
1. 对比 Claude 和 Codex 配置格式
2. 检查转换逻辑（`addCodexMcpServer` 函数）
3. 验证 TOML 序列化正确性
---
## 成功标准
所有测试场景通过以下标准：
✅ **UI 样式正确**
- Claude 模式：CCW Tools 卡片使用橙色样式
- Codex 模式：CCW Tools 卡片使用橙色样式
- 按钮颜色和边框符合设计规范
✅ **Toast 反馈完整**
- 安装成功时显示成功 Toast
- Toast 消息内容准确（包含服务器名称）
- Toast 显示时间为 3.5秒
- Toast 类型正确（success/error）
✅ **配置文件正确**
- `~/.codex/config.toml` 创建成功
- MCP 服务器配置格式正确
- 配置内容与源配置匹配
✅ **UI 状态同步**
- 安装后卡片状态更新
- 服务器出现在正确的区域
- 徽章显示正确
---
## 测试报告模板
### 测试信息
- **测试日期**: _____
- **测试人员**: _____
- **CCW 版本**: _____
- **浏览器**: _____
### 测试结果总结
| 测试场景 | 通过 | 失败 | 备注 |
|----------|------|------|------|
| Codex MCP 新建安装 | ⬜ | ⬜ | |
| 从 Claude MCP 复制到 Codex | ⬜ | ⬜ | |
| 从其他项目复制到 Codex | ⬜ | ⬜ | |
### 发现的问题
1. **问题描述**: _____
- **严重程度**: Critical / High / Medium / Low
- **复现步骤**: _____
- **预期结果**: _____
- **实际结果**: _____
- **截图/日志**: _____
### 改进建议
_____
---
## 附录：功能实现细节
### Toast 消息机制
**实现位置**:
- `ccw/src/templates/dashboard-js/components/navigation.js:286-301`
- 显示时间：3500ms (3.5秒)
- 淡出动画：300ms
**Toast 类型**:
- `success`: 绿色背景 (`hsl(142 76% 36%)`)
- `error`: 红色背景 (`hsl(0 72% 51%)`)
- `info`: 主色调背景
- `warning`: 橙色背景 (`hsl(38 92% 50%)`)
### Codex MCP 安装流程
1. **前端调用**: `copyClaudeServerToCodex(serverName, serverConfig)`
2. **API 端点**: `POST /api/codex-mcp-add`
3. **后端处理**: `addCodexMcpServer(serverName, serverConfig)`
4. **配置写入**: 序列化为 TOML 格式并写入 `~/.codex/config.toml`
5. **响应返回**: `{success: true}` 或 `{error: "错误消息"}`
6. **前端更新**:
- 重新加载 MCP 配置
- 重新渲染 UI
- 显示 Toast 消息
### 格式转换规则
**Claude 格式** → **Codex 格式**:
- `command` → `command` (保持不变)
- `args` → `args` (保持不变)
- `env` → `env` (保持不变)
- `cwd` → `cwd` (可选)
- `url` → `url` (HTTP 服务器)
- `enabled` → `enabled` (默认 true)
---
## 联系支持
如果遇到问题，请提供以下信息：
1. 测试场景编号
2. 浏览器开发者工具的 Console 输出
3. Network 标签页的 API 请求/响应详情
4. `~/.codex/config.toml` 文件内容（如果存在）
5. CCW Dashboard 后端日志

237
ccw/docs/GRAPH_EXPLORER_FIX.md Normal file
View File

@@ -0,0 +1,237 @@
# Graph Explorer Fix - Migration 005 Compatibility
## Issue Description
The CCW Dashboard's Graph Explorer view was broken after codex-lens migration 005, which cleaned up unused database fields.
### Root Cause
Migration 005 removed unused/redundant columns from the codex-lens database:
- `symbols.token_count` (unused, always NULL)
- `symbols.symbol_type` (redundant duplicate of `kind`)
However, `ccw/src/core/routes/graph-routes.ts` was still querying these removed columns, causing SQL errors:
```typescript
// BEFORE (broken):
SELECT
s.id,
s.name,
s.kind,
s.start_line,
s.token_count, // ❌ Column removed in migration 005
s.symbol_type, // ❌ Column removed in migration 005
f.path as file
FROM symbols s
```
This resulted in database query failures when trying to load the graph visualization.
## Fix Applied
Updated `graph-routes.ts` to match the new database schema (v5):
### 1. Updated GraphNode Interface
**Before:**
```typescript
interface GraphNode {
id: string;
name: string;
type: string;
file: string;
line: number;
docstring?: string; // ❌ Removed (no longer available)
tokenCount?: number; // ❌ Removed (no longer available)
}
```
**After:**
```typescript
interface GraphNode {
id: string;
name: string;
type: string;
file: string;
line: number;
}
```
### 2. Updated SQL Query
**Before:**
```typescript
SELECT
s.id,
s.name,
s.kind,
s.start_line,
s.token_count, // ❌ Removed
s.symbol_type, // ❌ Removed
f.path as file
FROM symbols s
```
**After:**
```typescript
SELECT
s.id,
s.name,
s.kind,
s.start_line,
f.path as file
FROM symbols s
```
### 3. Updated Row Mapping
**Before:**
```typescript
return rows.map((row: any) => ({
id: `${row.file}:${row.name}:${row.start_line}`,
name: row.name,
type: mapSymbolKind(row.kind),
file: row.file,
line: row.start_line,
docstring: row.symbol_type || undefined, // ❌ Removed
tokenCount: row.token_count || undefined, // ❌ Removed
}));
```
**After:**
```typescript
return rows.map((row: any) => ({
id: `${row.file}:${row.name}:${row.start_line}`,
name: row.name,
type: mapSymbolKind(row.kind),
file: row.file,
line: row.start_line,
}));
```
### 4. Updated API Documentation
Updated `graph-routes.md` to reflect the simplified schema without the removed fields.
## How to Use Graph Explorer
### Prerequisites
1. **CodexLens must be installed and initialized:**
```bash
pip install -e codex-lens/
```
2. **Project must be indexed:**
```bash
# Via CLI
codex init <project-path>
# Or via CCW Dashboard
# Navigate to "CodexLens" view → Click "Initialize" → Select project
```
This creates the `_index.db` database at `~/.codexlens/indexes/<normalized-path>/_index.db`
3. **Symbols and relationships must be extracted:**
- CodexLens automatically indexes symbols during `init`
- Requires TreeSitter parsers for your programming language
- Relationships are extracted via migration 003 (code_relationships table)
### Accessing Graph Explorer
1. **Start CCW Dashboard:**
```bash
ccw view
```
2. **Navigate to Graph Explorer:**
- Click the "Graph" icon in the left sidebar (git-branch icon)
- Or use keyboard shortcut if configured
3. **View Code Structure:**
- **Code Relations Tab**: Interactive graph visualization of symbols and their relationships
- **Search Process Tab**: Visualizes search pipeline steps (experimental)
### Graph Controls
**Toolbar (top-right):**
- **Fit View**: Zoom to fit all nodes in viewport
- **Center**: Center the graph
- **Reset Filters**: Clear all node/edge type filters
- **Refresh**: Reload data from database
**Sidebar Filters:**
- **Node Types**: Filter by MODULE, CLASS, FUNCTION, METHOD, VARIABLE
- **Edge Types**: Filter by CALLS, IMPORTS, INHERITS
- **Legend**: Color-coded guide for node/edge types
**Interaction:**
- **Click node**: Show details panel with symbol information
- **Drag nodes**: Rearrange graph layout
- **Scroll**: Zoom in/out
- **Pan**: Click and drag on empty space
### API Endpoints
The Graph Explorer uses these REST endpoints:
1. **GET /api/graph/nodes**
- Returns all symbols as graph nodes
- Query param: `path` (optional, defaults to current project)
2. **GET /api/graph/edges**
- Returns all code relationships as graph edges
- Query param: `path` (optional)
3. **GET /api/graph/impact**
- Returns impact analysis for a symbol
- Query params: `path`, `symbol` (required, format: `file:name:line`)
## Verification
To verify the fix works:
1. **Ensure project is indexed:**
```bash
ls ~/.codexlens/indexes/
# Should show your project path
```
2. **Check database has symbols:**
```bash
sqlite3 ~/.codexlens/indexes/<your-project>/_index.db "SELECT COUNT(*) FROM symbols"
# Should return > 0
```
3. **Check schema version:**
```bash
sqlite3 ~/.codexlens/indexes/<your-project>/_index.db "PRAGMA user_version"
# Should return: 5 (after migration 005)
```
4. **Test Graph Explorer:**
- Open CCW dashboard: `ccw view`
- Navigate to Graph view
- Should see nodes/edges displayed without errors
## Related Files
- **Implementation**: `ccw/src/core/routes/graph-routes.ts`
- **Frontend**: `ccw/src/templates/dashboard-js/views/graph-explorer.js`
- **Styles**: `ccw/src/templates/dashboard-css/14-graph-explorer.css`
- **API Docs**: `ccw/src/core/routes/graph-routes.md`
- **Migration**: `codex-lens/src/codexlens/storage/migrations/migration_005_cleanup_unused_fields.py`
## Impact
- **Breaking Change**: Graph Explorer required codex-lens database schema v5
- **Data Loss**: None (removed fields were unused or redundant)
- **Compatibility**: Graph Explorer now works correctly with migration 005+
- **Future**: All CCW features requiring codex-lens database access must respect schema version 5
## References
- Migration 005 Documentation: `codex-lens/docs/MIGRATION_005_SUMMARY.md`
- Graph Routes API: `ccw/src/core/routes/graph-routes.md`
- CodexLens Schema: `codex-lens/src/codexlens/storage/dir_index.py`

331
ccw/docs/GRAPH_EXPLORER_TROUBLESHOOTING.md Normal file
View File

@@ -0,0 +1,331 @@
# Graph Explorer 故障排查指南
## 问题 1: 数据库列名错误
### 症状
```
[Graph] Failed to query symbols: no such column: s.token_count
[Graph] Failed to query relationships: no such column: f.path
```
### 原因
Migration 004 和 005 修改了数据库 schema：
- Migration 004: `files.path` → `files.full_path`
- Migration 005: 删除 `symbols.token_count` 和 `symbols.symbol_type`
### 解决方案
✅ **已修复** - `graph-routes.ts` 已更新为使用正确的列名：
- 使用 `f.full_path` 代替 `f.path`
- 移除对 `s.token_count` 和 `s.symbol_type` 的引用
---
## 问题 2: 图谱显示为空（无节点/边）
### 症状
- 前端 Graph Explorer 视图加载成功，但图谱为空
- 控制台显示 `nodes: []` 和 `edges: []`
### 诊断步骤
#### 1. 检查数据库是否存在
```bash
# Windows (Git Bash)
ls ~/.codexlens/indexes/
# 应该看到您的项目路径，例如：
# D/Claude_dms3/
```
#### 2. 检查数据库内容
```bash
# 进入项目索引数据库
cd ~/.codexlens/indexes/D/Claude_dms3/ # 替换为您的项目路径
# 检查符号数量
sqlite3 _index.db "SELECT COUNT(*) FROM symbols;"
# 检查文件数量
sqlite3 _index.db "SELECT COUNT(*) FROM files;"
# 检查关系数量（重要！）
sqlite3 _index.db "SELECT COUNT(*) FROM code_relationships;"
```
#### 3. 判断问题类型
**情况 A：所有计数都是 0**
- 问题：项目未索引
- 解决方案：运行 `codex init <project-path>`
**情况 B：symbols > 0, files > 0, code_relationships = 0**
- 问题：**旧索引缺少关系数据**（本次遇到的情况）
- 解决方案：重新索引以提取关系
**情况 C：所有计数都 > 0**
- 问题：前端或 API 路由错误
- 解决方案：检查浏览器控制台错误
### 解决方案：重新索引提取代码关系
#### 方案 1: 使用 CodexLens CLI（推荐）
```bash
# 1. 清除旧索引（可选但推荐）
rm -rf ~/.codexlens/indexes/D/Claude_dms3/_index.db
# 2. 重新初始化项目
cd /d/Claude_dms3
codex init .
# 3. 验证关系数据已提取
sqlite3 ~/.codexlens/indexes/D/Claude_dms3/_index.db "SELECT COUNT(*) FROM code_relationships;"
# 应该返回 > 0
```
#### 方案 2: 使用 Python 脚本手动提取
创建临时脚本 `extract_relationships.py`：
```python
#!/usr/bin/env python3
"""
临时脚本：为已索引项目提取代码关系
适用于 migration 003 之前创建的索引
"""
from pathlib import Path
from codexlens.storage.dir_index import DirIndexStore
from codexlens.semantic.graph_analyzer import GraphAnalyzer
def extract_relationships_for_project(project_path: str):
"""为已索引项目提取并添加代码关系"""
project = Path(project_path).resolve()
# 打开索引数据库
store = DirIndexStore(project)
store.initialize()
print(f"Processing project: {project}")
# 获取所有已索引文件
with store._get_connection() as conn:
cursor = conn.execute("""
SELECT f.id, f.full_path, f.language, f.content
FROM files f
WHERE f.language IN ('python', 'javascript', 'typescript')
AND f.content IS NOT NULL
""")
files = cursor.fetchall()
total = len(files)
processed = 0
relationships_added = 0
for file_id, file_path, language, content in files:
processed += 1
print(f"[{processed}/{total}] Processing {file_path}...")
try:
# 创建图分析器
analyzer = GraphAnalyzer(language)
if not analyzer.is_available():
print(f" ⚠ GraphAnalyzer not available for {language}")
continue
# 获取符号
with store._get_connection() as conn:
cursor = conn.execute("""
SELECT name, kind, start_line, end_line
FROM symbols
WHERE file_id = ?
ORDER BY start_line
""", (file_id,))
symbol_rows = cursor.fetchall()
# 构造 Symbol 对象
from codexlens.entities import Symbol
symbols = [
Symbol(
name=row[0],
kind=row[1],
start_line=row[2],
end_line=row[3],
file_path=file_path
)
for row in symbol_rows
]
# 提取关系
relationships = analyzer.analyze_with_symbols(
content,
Path(file_path),
symbols
)
if relationships:
store.add_relationships(file_path, relationships)
relationships_added += len(relationships)
print(f" ✓ Added {len(relationships)} relationships")
else:
print(f" - No relationships found")
except Exception as e:
print(f" ✗ Error: {e}")
continue
store.close()
print(f"\n✅ Complete!")
print(f" Files processed: {processed}")
print(f" Relationships added: {relationships_added}")
if __name__ == "__main__":
import sys
if len(sys.argv) < 2:
print("Usage: python extract_relationships.py <project-path>")
sys.exit(1)
extract_relationships_for_project(sys.argv[1])
```
运行脚本：
```bash
cd /d/Claude_dms3/codex-lens
python extract_relationships.py D:/Claude_dms3
```
#### 验证修复
```bash
# 1. 检查关系数量
sqlite3 ~/.codexlens/indexes/D/Claude_dms3/_index.db "SELECT COUNT(*) FROM code_relationships;"
# 应该 > 0
# 2. 检查示例关系
sqlite3 ~/.codexlens/indexes/D/Claude_dms3/_index.db "
SELECT
s.name as source,
r.relationship_type,
r.target_qualified_name
FROM code_relationships r
JOIN symbols s ON r.source_symbol_id = s.id
LIMIT 5;
"
# 3. 重启 CCW Dashboard
ccw view
# 4. 打开 Graph Explorer，应该能看到节点和边
```
---
## 问题 3: Graph Explorer 不显示（404 或空白）
### 症状
- 左侧边栏的 Graph 图标不响应点击
- 或点击后显示空白页面
### 诊断
1. **检查路由是否注册**：
```bash
cd /d/Claude_dms3/ccw
rg "handleGraphRoutes" src/
```
2. **检查前端是否包含 graph-explorer 视图**：
```bash
ls src/templates/dashboard-js/views/graph-explorer.js
```
3. **检查 dashboard-generator.ts 是否包含 graph explorer**：
```bash
rg "graph-explorer" src/core/dashboard-generator.ts
```
### 解决方案
确保以下文件存在且正确：
- `src/core/routes/graph-routes.ts` - API 路由处理
- `src/templates/dashboard-js/views/graph-explorer.js` - 前端视图
- `src/templates/dashboard-css/14-graph-explorer.css` - 样式
- `src/templates/dashboard.html` - 包含 Graph 导航项（line 334）
---
## 问题 4: 关系提取失败（调试模式）
### 启用调试日志
```bash
# 设置日志级别为 DEBUG
export CODEXLENS_LOG_LEVEL=DEBUG
# 重新索引
codex init /d/Claude_dms3
# 检查日志中的关系提取信息
# 应该看到：
# DEBUG: Extracting relationships from <file>
# DEBUG: Found N relationships
```
### 常见失败原因
1. **TreeSitter 解析器缺失**：
```bash
python -c "from codexlens.semantic.graph_analyzer import GraphAnalyzer; print(GraphAnalyzer('python').is_available())"
# 应该返回: True
```
2. **文件语言未识别**：
```sql
sqlite3 _index.db "SELECT DISTINCT language FROM files;"
# 应该看到: python, javascript, typescript
```
3. **源代码无法解析**：
- 语法错误的文件会被静默跳过
- 检查 DEBUG 日志中的解析错误
---
## 快速诊断命令汇总
```bash
# 1. 检查数据库 schema 版本
sqlite3 ~/.codexlens/indexes/D/Claude_dms3/_index.db "PRAGMA user_version;"
# 应该 >= 5
# 2. 检查表结构
sqlite3 ~/.codexlens/indexes/D/Claude_dms3/_index.db "PRAGMA table_info(files);"
# 应该看到: full_path（不是 path）
sqlite3 ~/.codexlens/indexes/D/Claude_dms3/_index.db "PRAGMA table_info(symbols);"
# 不应该看到: token_count, symbol_type
# 3. 检查数据统计
sqlite3 ~/.codexlens/indexes/D/Claude_dms3/_index.db "
SELECT
(SELECT COUNT(*) FROM files) as files,
(SELECT COUNT(*) FROM symbols) as symbols,
(SELECT COUNT(*) FROM code_relationships) as relationships;
"
# 4. 测试 API 端点
curl "http://localhost:3000/api/graph/nodes" | jq '.nodes | length'
curl "http://localhost:3000/api/graph/edges" | jq '.edges | length'
```
---
## 相关文档
- [Graph Explorer 修复说明](./GRAPH_EXPLORER_FIX.md)
- [Migration 005 总结](../../codex-lens/docs/MIGRATION_005_SUMMARY.md)
- [Graph Routes API](../src/core/routes/graph-routes.md)

273
ccw/docs/QUICK_TEST_CODEX_MCP.md Normal file
View File

@@ -0,0 +1,273 @@
# Codex MCP 快速测试指南
## 🎯 快速测试步骤
### 测试 1: CCW Tools 样式检查（1分钟）
1. 打开 Dashboard → MCP 管理
2. 确保在 **Claude 模式**
3. 查看 CCW Tools MCP 卡片
4. ✅ **验证点**:
- 卡片有橙色边框（不是蓝色）
- 左上角图标是橙色背景（不是蓝色）
- "Available"徽章是橙色（不是蓝色）
- "Core only"/"All"按钮是橙色文字
**预期效果**:
```
┌─────────────────────────────────────────┐
│ 🔧 CCW Tools MCP │ ← 橙色边框
│ [橙色图标] Available (橙色徽章) │
│ │
│ [✓] Write/create files │
│ [✓] Edit/replace content │
│ ... │
│ │
│ [橙色按钮] Core only [橙色按钮] All │
│ │
│ [橙色安装按钮] Install to Workspace │
└─────────────────────────────────────────┘
```
---
### 测试 2: Codex MCP 安装 + Toast 反馈（2分钟）
#### 步骤
1. **切换到 Codex 模式**
- 点击页面顶部的 "Codex" 按钮
- 确认右侧显示 `~/.codex/config.toml`
2. **选择并安装 CCW Tools**
- 在 CCW Tools 卡片中勾选所有核心工具
- 点击橙色"Install"按钮
3. **观察 Toast 消息**
- **关键点**: 盯住屏幕底部中央
- 应该看到绿色的成功消息
- 消息内容: `"CCW Tools installed to Codex (4 tools)"` 或中文版本
- 消息停留 **3.5秒**（不是2秒）
4. **验证安装结果**
```bash
# 查看 Codex 配置文件
cat ~/.codex/config.toml
# 应该看到类似以下内容：
# [mcp_servers.ccw-tools]
# command = "npx"
# args = ["-y", "ccw-mcp"]
# env = { CCW_ENABLED_TOOLS = "write_file,edit_file,codex_lens,smart_search" }
```
#### ✅ 成功标准
| 项目 | 预期 | 通过? |
|------|------|-------|
| Toast 显示 | ✅ | ⬜ |
| Toast 内容正确 | ✅ | ⬜ |
| Toast 停留 3.5秒 | ✅ | ⬜ |
| config.toml 创建 | ✅ | ⬜ |
| 卡片状态更新 | ✅ | ⬜ |
---
### 测试 3: 从 Claude 复制到 Codex（3分钟）
#### 前置步骤：创建测试服务器
1. **切换到 Claude 模式**
2. **创建全局 MCP 服务器**:
- 点击"全局可用 MCP"区域的"+ New Global Server"
- 填写信息：
- 名称: `test-filesystem`
- 命令: `npx`
- 参数（每行一个）:
```
-y
@modelcontextprotocol/server-filesystem
/tmp
```
- 点击"Create"
3. **验证创建成功**: 服务器应该出现在"全局可用 MCP"列表中
#### 测试步骤
1. **切换到 Codex 模式**
2. **找到复制区域**: 向下滚动到"Copy Claude Servers to Codex"
3. **找到测试服务器**: 应该看到 `test-filesystem` 卡片
4. **点击复制按钮**: 橙色的"→ Codex"按钮
5. **观察反馈**:
- Toast 消息: `"Codex MCP server 'test-filesystem' added"`
- 停留时间: 3.5秒
- 卡片出现"Already added"绿色徽章
6. **验证结果**:
```bash
cat ~/.codex/config.toml
# 应该看到:
# [mcp_servers.test-filesystem]
# command = "npx"
# args = ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
```
#### ✅ 成功标准
| 项目 | 预期 | 通过? |
|------|------|-------|
| Toast 显示（包含服务器名称） | ✅ | ⬜ |
| Toast 停留 3.5秒 | ✅ | ⬜ |
| config.toml 正确添加 | ✅ | ⬜ |
| "Already added"徽章显示 | ✅ | ⬜ |
| 服务器出现在 Codex 区域 | ✅ | ⬜ |
---
## 🔍 调试清单
### Toast 消息不显示？
**检查点**:
1. 打开浏览器开发者工具 (F12)
2. 切换到 **Console** 标签
3. 执行安装操作
4. 查看是否有错误（红色文字）
**常见错误**:
```javascript
// 如果看到这个错误，说明 API 调用失败
Failed to add Codex MCP server: ...
// 如果看到这个，说明 Toast 函数未定义
showRefreshToast is not defined
```
### 配置文件未创建？
**检查步骤**:
```bash
# 1. 检查目录是否存在
ls -la ~/.codex/
# 2. 如果不存在，手动创建
mkdir -p ~/.codex
# 3. 检查权限
ls -la ~/.codex/
# 应该看到: drwxr-xr-x (可读写)
# 4. 重试安装操作
```
### 样式不对？
**可能原因**:
- 浏览器缓存了旧的 CSS
- 需要硬刷新
**解决方法**:
```
按 Ctrl + Shift + R (Windows/Linux)
或 Cmd + Shift + R (Mac)
强制刷新页面
```
---
## 📊 测试报告模板
**测试时间**: ___________
**浏览器**: Chrome / Firefox / Safari / Edge
**操作系统**: Windows / macOS / Linux
### 测试结果
| 测试项 | 通过 | 失败 | 备注 |
|--------|------|------|------|
| CCW Tools 橙色样式 | ⬜ | ⬜ | |
| Codex MCP 安装 | ⬜ | ⬜ | |
| Toast 消息显示 | ⬜ | ⬜ | |
| Toast 停留 3.5秒 | ⬜ | ⬜ | |
| Claude → Codex 复制 | ⬜ | ⬜ | |
| config.toml 正确性 | ⬜ | ⬜ | |
### 发现的问题
_请在这里描述任何问题_
### 截图
_如果有问题，请附上截图_
---
## 🎬 视频演示脚本
如果需要录制演示视频，按照以下脚本操作：
### 第1段：样式检查（15秒）
```
1. 打开 MCP 管理页面
2. 指向 CCW Tools 卡片
3. 圈出橙色边框
4. 圈出橙色图标
5. 圈出橙色按钮
```
### 第2段：Codex 安装演示（30秒）
```
1. 切换到 Codex 模式
2. 勾选核心工具
3. 点击 Install 按钮
4. 暂停并放大 Toast 消息（绿色成功消息）
5. 数秒数：1、2、3、3.5秒后消失
6. 显示 config.toml 文件内容
```
### 第3段：Claude → Codex 复制演示（45秒）
```
1. 切换到 Claude 模式
2. 创建测试服务器
3. 切换到 Codex 模式
4. 找到复制区域
5. 点击"→ Codex"按钮
6. 暂停并放大 Toast 消息（包含服务器名称）
7. 显示卡片状态变化（"Already added"徽章）
8. 显示 config.toml 更新后的内容
```
---
## ✅ 完整测试检查清单
打印此清单并在测试时勾选：
```
□ 启动 CCW Dashboard
□ 导航到 MCP 管理页面
□ 【Claude模式】CCW Tools 卡片样式正确（橙色）
□ 【Claude模式】创建全局 MCP 测试服务器
□ 【Codex模式】CCW Tools 卡片样式正确（橙色）
□ 【Codex模式】安装 CCW Tools
□ 【Codex模式】Toast 消息显示 3.5秒
□ 【Codex模式】config.toml 创建成功
□ 【Codex模式】从 Claude 复制测试服务器
□ 【Codex模式】Toast 消息包含服务器名称
□ 【Codex模式】卡片显示"Already added"
□ 【Codex模式】config.toml 包含新服务器
□ 清理测试数据（删除测试服务器）
□ 填写测试报告
```
---
## 🎉 成功！
如果所有测试通过，恭喜！功能工作正常。
如果有任何问题，请参考 `CODEX_MCP_TESTING_GUIDE.md` 的详细故障排查部分。

280
ccw/docs/mcp-manager-guide.md Normal file
View File

@@ -0,0 +1,280 @@
# MCP Manager - 使用指南
## 概述
全新的 MCP 管理器提供了统一的界面来管理 MCP 服务器，支持多种安装方式和配置管理。
## 主要特性
### 1. 统一的 MCP 编辑弹窗
- **三种模式**：
- 创建模式（Create）：创建新的 MCP 服务器
- 编辑模式（Edit）：编辑现有 MCP 服务器
- 查看模式（View）：只读查看 MCP 服务器详情
- **两种服务器类型**：
- STDIO (Command-based)：通过命令行启动的 MCP 服务器
- HTTP (URL-based)：通过 HTTP/HTTPS 访问的 MCP 服务器
### 2. 多种安装目标
支持安装到以下位置：
| 目标 | 配置文件 | 说明 |
|------|---------|------|
| **Claude** | `.mcp.json` | 项目级配置，推荐用于 Claude CLI |
| **Codex** | `~/.codex/config.toml` | Codex 全局配置 |
| **Project** | `.mcp.json` | 项目级配置（与 Claude 相同） |
| **Global** | `~/.claude.json` | 全局配置，所有项目可用 |
### 3. MCP 模板系统
- **保存模板**：从现有 MCP 服务器创建可复用模板
- **浏览模板**：按分类查看所有已保存的模板
- **一键安装**：从模板快速安装 MCP 服务器到任意目标
### 4. 统一的服务器管理
- **查看所有服务器**：
- Project（项目级）
- Global（全局级）
- Codex（Codex 全局）
- Enterprise（企业级，只读）
- **操作**：
- 启用/禁用
- 查看详情
- 编辑配置
- 删除服务器
- 保存为模板
## 使用方法
### 创建新的 MCP 服务器
1. 点击 **"Create New"** 按钮
2. 填写服务器信息：
- **名称**：唯一标识符（必填）
- **描述**：简要说明（可选）
- **分类**：从预定义分类中选择
3. 选择服务器类型：
- **STDIO**：填写 `command`、`args`、`env`、`cwd`
- **HTTP**：填写 `url`、HTTP 头
4. （可选）勾选 **"Save as Template"** 保存为模板
5. 选择安装目标（Claude/Codex/Project/Global）
6. 点击 **"Install"** 完成安装
### STDIO 服务器示例
```json
{
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"],
"env": {
"DEBUG": "true"
}
}
```
### HTTP 服务器示例
```json
{
"url": "https://api.example.com/mcp",
"http_headers": {
"Authorization": "Bearer YOUR_TOKEN",
"X-API-Key": "YOUR_KEY"
}
}
```
### 从模板安装
1. 点击 **"Templates"** 按钮
2. 浏览分类中的模板
3. 点击模板卡片上的 **"Install"** 按钮
4. 在弹窗中修改配置（如需要）
5. 选择安装目标
6. 点击 **"Install"**
### 编辑现有服务器
1. 在服务器列表中找到目标服务器
2. 点击 **编辑图标**（✏️）
3. 修改配置
4. 点击 **"Update"** 保存更改
### 管理服务器
- **启用/禁用**：点击开关图标（🔄）
- **查看详情**：点击眼睛图标（👁️）
- **保存为模板**：点击书签图标（🔖）
- **删除**：点击垃圾桶图标（🗑️）
## CLI 模式切换
支持两种 CLI 模式：
- **Claude 模式**：管理 `~/.claude.json` 和 `.mcp.json` 中的服务器
- **Codex 模式**：管理 `~/.codex/config.toml` 中的服务器
在界面顶部切换 CLI 模式以查看和管理相应的服务器。
## 统计信息
仪表板顶部显示以下统计：
- **Total Servers**：总服务器数量
- **Enabled**：已启用的服务器数量
- **Claude**：Claude 相关服务器数量（Project + Global）
- **Codex**：Codex 服务器数量
## 服务器分类
预定义分类：
- Development Tools
- Data & APIs
- Files & Storage
- AI & ML
- DevOps
- Custom
## API 支持
后端 API 已完整实现，支持：
### Claude MCP API
- `POST /api/mcp-copy-server` - 安装到项目/全局
- `POST /api/mcp-remove-server` - 从项目删除
- `POST /api/mcp-add-global-server` - 添加全局服务器
- `POST /api/mcp-remove-global-server` - 删除全局服务器
- `POST /api/mcp-toggle` - 启用/禁用服务器
### Codex MCP API
- `POST /api/codex-mcp-add` - 添加 Codex 服务器
- `POST /api/codex-mcp-remove` - 删除 Codex 服务器
- `POST /api/codex-mcp-toggle` - 启用/禁用 Codex 服务器
- `GET /api/codex-mcp-config` - 获取 Codex 配置
### 模板 API
- `GET /api/mcp-templates` - 获取所有模板
- `POST /api/mcp-templates` - 保存模板
- `DELETE /api/mcp-templates/:name` - 删除模板
- `GET /api/mcp-templates/search?q=keyword` - 搜索模板
- `GET /api/mcp-templates/categories` - 获取所有分类
## 配置文件格式
### .mcp.json (项目级)
```json
{
"mcpServers": {
"server-name": {
"command": "node",
"args": ["server.js"],
"env": {}
}
}
}
```
### .claude.json (全局级)
```json
{
"mcpServers": {
"server-name": {
"command": "node",
"args": ["server.js"]
}
}
}
```
### config.toml (Codex)
```toml
[mcp_servers.server-name]
command = "node"
args = ["server.js"]
enabled = true
```
## 故障排除
### 常见问题
1. **服务器无法启用**
- 检查命令是否正确
- 确认依赖是否已安装
- 查看环境变量是否正确
2. **无法保存到 Codex**
- 确认 `~/.codex` 目录存在
- 检查文件权限
3. **模板无法加载**
- 刷新页面重试
- 检查浏览器控制台错误信息
### 调试技巧
- 打开浏览器开发者工具查看网络请求
- 检查控制台日志
- 查看配置文件是否正确生成
## 兼容性
- **支持的配置格式**：
- `.mcp.json` (JSON)
- `.claude.json` (JSON)
- `config.toml` (TOML for Codex)
- **浏览器支持**：
- Chrome/Edge (推荐)
- Firefox
- Safari
## 最佳实践
1. **使用 .mcp.json 优先**：
- 便于版本控制
- 项目独立配置
- Claude 和 Codex 都能识别
2. **分类管理模板**：
- 为模板选择合适的分类
- 添加清晰的描述
- 避免重复的模板名称
3. **环境变量安全**：
- 敏感信息使用环境变量
- 不要在配置文件中硬编码 token
- 使用 `.env` 文件管理密钥
4. **服务器命名规范**：
- 使用小写字母和连字符
- 避免特殊字符
- 名称具有描述性
## 更新日志
### v2.0 (当前版本)
- ✅ 全新的统一编辑弹窗
- ✅ 支持多种安装目标（Claude/Codex/Project/Global）
- ✅ 完整的模板系统
- ✅ STDIO 和 HTTP 服务器类型支持
- ✅ 统一的服务器列表视图
- ✅ 实时统计信息
- ✅ 国际化支持（英文/中文）
- ✅ 响应式设计
### 从旧版本迁移
旧版本的 MCP 配置会自动识别，无需手动迁移。新版本完全兼容旧配置文件。
## 支持
如有问题或建议，请联系开发团队或提交 issue。