mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-05 01:50:27 +08:00
874b70726d
- Moved 6 empty test files (*.test.ts) to archive/ - Moved 5 Python test scripts (*.py) to archive/ - Moved 5 outdated/temporary documents to archive/ - Cleaned up root directory for better organization
311 lines
9.2 KiB
Markdown
311 lines
9.2 KiB
Markdown
# CodexLens MCP Integration - Implementation Summary
|
||
|
||
> Implementation Date: 2026-01-19
|
||
> Project: CCW Dashboard + CodexLens MCP
|
||
|
||
## 实现概览
|
||
|
||
成功完成 codex-lens LSP 功能分析及其 MCP 端点设计，并在 CCW view 中实现工具选择功能。
|
||
|
||
---
|
||
|
||
## ✅ 已完成任务
|
||
|
||
### 1. **Gemini 分析 - CodexLens LSP 功能** ✓
|
||
|
||
**输出文件**：`D:\Claude_dms3\codex-lens\docs\MCP_ENDPOINT_DESIGN.md`
|
||
|
||
**分析结果**：
|
||
- **4 个核心 MCP 工具**已规划：
|
||
1. `code.symbol.search` - 符号搜索（对应 `workspace/symbol` 和 `textDocument/completion`）
|
||
2. `code.symbol.findDefinition` - 查找定义（对应 `textDocument/definition`）
|
||
3. `code.symbol.findReferences` - 查找引用（对应 `textDocument/references`）
|
||
4. `code.symbol.getHoverInfo` - 悬停信息（对应 `textDocument/hover`）
|
||
|
||
**技术细节**：
|
||
- 后端实现基于 `GlobalSymbolIndex` 和 `ChainSearchEngine`
|
||
- 完整的 MCP schema 定义（参数、返回值、使用场景）
|
||
- 命名规范：`code.symbol.<operation>`
|
||
|
||
---
|
||
|
||
### 2. **实现 Multi-Select 字段类型** ✓
|
||
|
||
**修改文件**：`ccw/src/templates/dashboard-js/components/mcp-manager.js`
|
||
|
||
**核心实现**：
|
||
|
||
#### 字段渲染（line 1506-1529）
|
||
```javascript
|
||
${field.type === 'multi-select' ? `
|
||
<div id="wizard-field-${field.key}" class="space-y-2 p-2 bg-muted/30 border border-border rounded-lg max-h-48 overflow-y-auto">
|
||
${(field.options || []).map(opt => {
|
||
const isChecked = (field.default || []).includes(opt.value);
|
||
return `
|
||
<label class="flex items-center gap-2 p-2 rounded-md hover:bg-accent cursor-pointer transition-colors">
|
||
<input type="checkbox"
|
||
class="wizard-multi-select-${field.key} rounded border-border text-primary focus:ring-primary"
|
||
value="${escapeHtml(opt.value)}"
|
||
${isChecked ? 'checked' : ''}>
|
||
<span class="text-sm text-foreground">${escapeHtml(opt.label)}</span>
|
||
${opt.desc ? `<span class="text-xs text-muted-foreground ml-auto">${escapeHtml(opt.desc)}</span>` : ''}
|
||
</label>
|
||
`;
|
||
}).join('')}
|
||
</div>
|
||
` : `
|
||
<input type="${field.type || 'text'}" ...>
|
||
`}
|
||
```
|
||
|
||
#### 值收集（line 1637-1661）
|
||
```javascript
|
||
if (field.type === 'multi-select') {
|
||
const checkboxes = document.querySelectorAll(`.wizard-multi-select-${field.key}:checked`);
|
||
const selectedValues = Array.from(checkboxes).map(cb => cb.value);
|
||
|
||
if (field.required && selectedValues.length === 0) {
|
||
showRefreshToast(`${t(field.labelKey)} - ${t('mcp.wizard.selectAtLeastOne')}`, 'error');
|
||
hasError = true;
|
||
break;
|
||
}
|
||
|
||
values[field.key] = selectedValues;
|
||
}
|
||
```
|
||
|
||
**特性**：
|
||
- ✅ 复选框列表 UI
|
||
- ✅ 默认值预选
|
||
- ✅ 必填验证
|
||
- ✅ 悬停高亮效果
|
||
- ✅ 滚动容器（max-height: 48）
|
||
|
||
---
|
||
|
||
### 3. **添加 CodexLens 到推荐 MCP 列表** ✓
|
||
|
||
**修改位置**：`ccw/src/templates/dashboard-js/components/mcp-manager.js` (line 1430-1457)
|
||
|
||
**MCP 定义**：
|
||
```javascript
|
||
{
|
||
id: 'codex-lens-tools',
|
||
nameKey: 'mcp.codexLens.name',
|
||
descKey: 'mcp.codexLens.desc',
|
||
icon: 'code-2',
|
||
category: 'code-intelligence',
|
||
fields: [
|
||
{
|
||
key: 'tools',
|
||
labelKey: 'mcp.codexLens.field.tools',
|
||
type: 'multi-select', // 使用新的 multi-select 类型
|
||
options: [
|
||
{ value: 'symbol.search', label: 'Symbol Search', desc: 'Workspace symbol search' },
|
||
{ value: 'symbol.findDefinition', label: 'Find Definition', desc: 'Go to definition' },
|
||
{ value: 'symbol.findReferences', label: 'Find References', desc: 'Find all references' },
|
||
{ value: 'symbol.getHoverInfo', label: 'Hover Information', desc: 'Rich symbol info' }
|
||
],
|
||
default: ['symbol.search', 'symbol.findDefinition', 'symbol.findReferences'],
|
||
required: true,
|
||
descKey: 'mcp.codexLens.field.tools.desc'
|
||
}
|
||
],
|
||
buildConfig: (values) => {
|
||
const tools = values.tools || [];
|
||
const env = { CODEXLENS_ENABLED_TOOLS: tools.join(',') };
|
||
return buildCrossPlatformMcpConfig('npx', ['-y', 'codex-lens-mcp'], { env });
|
||
}
|
||
}
|
||
```
|
||
|
||
**配置生成**：
|
||
```javascript
|
||
// 示例输出
|
||
{
|
||
command: "cmd", // Windows 自动包装
|
||
args: ["/c", "npx", "-y", "codex-lens-mcp"],
|
||
env: {
|
||
CODEXLENS_ENABLED_TOOLS: "symbol.search,symbol.findDefinition,symbol.findReferences"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4. **添加 i18n 翻译支持** ✓
|
||
|
||
**修改文件**：`ccw/src/templates/dashboard-js/i18n.js`
|
||
|
||
#### 英文翻译（line 959-963）
|
||
```javascript
|
||
'mcp.codexLens.name': 'CodexLens Tools',
|
||
'mcp.codexLens.desc': 'Code intelligence tools for symbol search, navigation, and reference finding',
|
||
'mcp.codexLens.field.tools': 'Enabled Tools',
|
||
'mcp.codexLens.field.tools.desc': 'Select the code intelligence tools to enable for this MCP server',
|
||
'mcp.wizard.selectAtLeastOne': 'Please select at least one option',
|
||
```
|
||
|
||
#### 中文翻译（line 3286-3290）
|
||
```javascript
|
||
'mcp.codexLens.name': 'CodexLens 工具',
|
||
'mcp.codexLens.desc': '代码智能工具，提供符号搜索、代码导航和引用查找功能',
|
||
'mcp.codexLens.field.tools': '启用的工具',
|
||
'mcp.codexLens.field.tools.desc': '选择要启用的代码智能工具',
|
||
'mcp.wizard.selectAtLeastOne': '请至少选择一个选项',
|
||
```
|
||
|
||
---
|
||
|
||
## 📋 使用流程
|
||
|
||
### 用户操作步骤
|
||
|
||
1. **打开 CCW Dashboard**
|
||
```bash
|
||
ccw view
|
||
```
|
||
|
||
2. **导航到 MCP Manager**
|
||
- 点击侧边栏 "MCP Servers" → "Manage"
|
||
|
||
3. **安装 CodexLens MCP**
|
||
- 滚动到 "Recommended MCP" 部分
|
||
- 找到 "CodexLens Tools" 卡片
|
||
- 点击 "Install" 按钮
|
||
|
||
4. **配置工具**
|
||
- 在弹出的安装向导中，看到 **4 个工具选项**（带复选框）
|
||
- 默认已选中 3 个：
|
||
- ☑ Symbol Search
|
||
- ☑ Find Definition
|
||
- ☑ Find References
|
||
- ☐ Hover Information
|
||
- 可以勾选/取消勾选任意工具
|
||
|
||
5. **选择安装目标**
|
||
- **Project**：项目级（`.mcp.json`）
|
||
- **Global**：全局级（`~/.claude.json`）默认选中
|
||
- **Codex**：Codex 全局（`~/.codex/config.toml`）
|
||
|
||
6. **确认安装**
|
||
- 点击 "Install" 按钮
|
||
- 等待安装完成提示
|
||
|
||
### 生成的配置示例
|
||
|
||
**Claude 配置（`.claude.json` 或 `.mcp.json`）**：
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"codex-lens-tools": {
|
||
"command": "cmd",
|
||
"args": ["/c", "npx", "-y", "codex-lens-mcp"],
|
||
"env": {
|
||
"CODEXLENS_ENABLED_TOOLS": "symbol.search,symbol.findDefinition,symbol.findReferences"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**Codex 配置（`~/.codex/config.toml`）**：
|
||
```toml
|
||
[mcp_servers.codex-lens-tools]
|
||
command = "npx"
|
||
args = ["-y", "codex-lens-mcp"]
|
||
env = { CODEXLENS_ENABLED_TOOLS = "symbol.search,symbol.findDefinition,symbol.findReferences" }
|
||
enabled = true
|
||
```
|
||
|
||
---
|
||
|
||
## 🎯 技术亮点
|
||
|
||
### 1. **跨平台兼容性**
|
||
- 使用 `buildCrossPlatformMcpConfig` 自动处理 Windows `cmd /c` 包装
|
||
- 支持 Claude、Codex 两种配置格式
|
||
|
||
### 2. **动态工具控制**
|
||
- 通过环境变量 `CODEXLENS_ENABLED_TOOLS` 控制启用的工具
|
||
- 前端 UI 实时更新配置
|
||
|
||
### 3. **可扩展字段类型**
|
||
- 新增 `multi-select` 字段类型
|
||
- 保持向后兼容（`text`, `password` 等）
|
||
|
||
### 4. **国际化支持**
|
||
- 完整的中英文翻译
|
||
- UI 文本动态切换
|
||
|
||
---
|
||
|
||
## 📁 修改文件清单
|
||
|
||
| 文件路径 | 修改内容 | 行数 |
|
||
|---------|---------|------|
|
||
| `codex-lens/docs/MCP_ENDPOINT_DESIGN.md` | **新增** - MCP 端点设计文档 | 262 |
|
||
| `ccw/src/templates/dashboard-js/components/mcp-manager.js` | 字段渲染 multi-select 支持 | 1506-1529 |
|
||
| `ccw/src/templates/dashboard-js/components/mcp-manager.js` | 值收集 multi-select 处理 | 1637-1661 |
|
||
| `ccw/src/templates/dashboard-js/components/mcp-manager.js` | 添加 codex-lens-tools MCP 定义 | 1430-1457 |
|
||
| `ccw/src/templates/dashboard-js/i18n.js` | 添加英文翻译（5 个键） | 959-963 |
|
||
| `ccw/src/templates/dashboard-js/i18n.js` | 添加中文翻译（5 个键） | 3286-3290 |
|
||
|
||
---
|
||
|
||
## 🚀 后续工作
|
||
|
||
### 待实现功能（CodexLens MCP Server）
|
||
|
||
1. **实现 MCP Server**
|
||
- 创建 `codex-lens-mcp` npm 包
|
||
- 实现 4 个 MCP 工具的 handler
|
||
- 环境变量解析：`CODEXLENS_ENABLED_TOOLS`
|
||
|
||
2. **测试**
|
||
- 单元测试：MCP 工具实现
|
||
- 集成测试：与 CCW Dashboard 集成
|
||
- E2E 测试：完整安装流程
|
||
|
||
3. **文档**
|
||
- 用户手册：如何使用 CodexLens MCP
|
||
- API 文档：MCP 工具详细说明
|
||
- 故障排除指南
|
||
|
||
### 可选增强
|
||
|
||
- **实时索引进度**：显示代码索引状态
|
||
- **更多工具**：`code.symbol.getDocumentSymbols`
|
||
- **过滤器**：按文件类型/语言过滤符号
|
||
- **性能监控**：工具调用延迟统计
|
||
|
||
---
|
||
|
||
## 📊 性能指标
|
||
|
||
| 指标 | 值 |
|
||
|------|-----|
|
||
| Gemini 分析时间 | 67.6s |
|
||
| 新增代码行数 | ~150 lines |
|
||
| 支持的工具数 | 4 tools |
|
||
| i18n 翻译键 | 10 keys (5 en + 5 zh) |
|
||
| 修改文件数 | 3 files |
|
||
|
||
---
|
||
|
||
## 🎉 总结
|
||
|
||
成功完成 codex-lens LSP 到 MCP 的完整设计和 CCW Dashboard 集成：
|
||
|
||
1. ✅ **完整的 MCP 端点设计**（4 个工具，详细 schema）
|
||
2. ✅ **可复用的 multi-select 字段类型**
|
||
3. ✅ **CodexLens MCP 集成到推荐列表**
|
||
4. ✅ **完整的中英文国际化支持**
|
||
|
||
用户现在可以在 CCW Dashboard 中一键安装 CodexLens MCP 服务，并通过可视化界面选择启用的代码智能工具。
|
||
|
||
---
|
||
|
||
Generated: 2026-01-19
|
||
Status: ✅ Ready for Testing
|