# Debug MCP v2.0 - Optimization Summary
## 🎉 优化完成！
Debug MCP 已成功优化至 v2.0，架构更加简洁合理。
## 主要改进
### 1. ❌ 移除了代码自动注入/删除功能
**之前的问题：**
- AI 无法精确控制调试代码的位置
- 可能破坏代码结构
- 不够灵活，无法根据上下文定制
**现在的方案：**
- AI 根据分析结果自己编写调试代码
- 使用 `get_debug_template` 获取代码模板
- AI 自己决定在哪里插入、如何定制
### 2. 📁 日志文件改为工程相对路径
**之前的问题：**
- 所有日志都存在 MCP 服务器目录
- 多个项目调试时会混乱
**现在的方案：**
```javascript
// 日志路径：{projectPath}/.debug/debug.log
// 例如：D:/my-project/.debug/debug.log
// 在请求体中指定 projectPath
POST /api/log
{
"projectPath": "/path/to/project",
"message": "Debug message",
"level": "info"
}
```
### 3. 🔌 端口优化
**之前：**
- 默认端口 3000（太常用，容易冲突）
**现在：**
- 默认端口 **37373**（不常用）
- 环境变量：`DEBUG_PORT` 或 `MCP_DEBUG_PORT`
- 支持自定义端口
### 4. 📋 MCP 工具简化
#### 新增工具
- **get_server_info** - 获取服务器配置和使用说明
- **get_debug_template** - 生成调试代码模板（不再自动注入）
- **clear_debug_logs** - 清空指定工程的日志
#### 保留工具
- **analyze_bug** - 分析 bug（增强，返回调试建议）
- **read_debug_logs** - 读取日志（支持 projectPath）
- **list_debug_blocks** - 列出调试标记（辅助手动清理）
#### 删除工具
- ~~add_debug_logs~~ - AI 自己写代码
- ~~remove_debug_logs~~ - AI 自己删除
- ~~detect_environment~~ - AI 自己判断
- ~~create_test_steps~~ - 不再需要
## 新的工作流程
### 典型调试流程
```
用户: "登录按钮点击没反应"
1. AI 调用 analyze_bug
→ 返回: 可能原因、调试建议、推荐环境
2. AI 调用 get_debug_template
→ 返回: 浏览器环境的调试代码模板
3. AI 将模板代码复制到用户文件的合适位置
→ AI 根据上下文定制日志内容
4. 用户运行应用
→ 代码发送日志到 http://localhost:37373/api/log
→ 日志存储在 {projectPath}/.debug/debug.log
5. AI 调用 read_debug_logs
→ 读取并分析日志
6. 根据日志分析，AI 添加更多针对性调试代码
7. 重复步骤 4-6，直到问题解决
8. AI 调用 list_debug_blocks
→ 查找所有 // debug-start ... // debug-end 标记
9. AI 手动删除所有调试代码
→ 更精确、更安全
```
## API 变更
### HTTP 端点
| 端点 | 方法 | 描述 |
|------|------|------|
| /api/info | GET | 服务器信息和使用说明 |
| /api/log | POST | 接收调试日志（支持 projectPath） |
| /api/log | GET | 读取日志（支持 projectPath 查询参数） |
| /api/log | DELETE | 清空日志（支持 projectPath 查询参数） |
| /api/stats | GET | 日志统计（支持 projectPath 查询参数） |
| /health | GET | 健康检查 |
### 请求示例
#### 发送日志
```bash
curl -X POST http://localhost:37373/api/log \
-H "Content-Type: application/json" \
-d '{
"projectPath": "/path/to/project",
"timestamp": "2025-01-03T10:30:00Z",
"level": "info",
"message": "Button clicked",
"data": { "userId": 123 }
}'
```
#### 读取日志
```bash
curl "http://localhost:37373/api/log?projectPath=/path/to/project&last=100"
```
## MCP 工具使用示例
### 1. 获取服务器信息
```javascript
const info = await mcp.call('get_server_info');
// 返回: { port: 37373, endpoints: {...}, supportedEnvironments: [...] }
```
### 2. 分析 Bug
```javascript
const analysis = await mcp.call('analyze_bug', {
bugDescription: 'Login button not responding',
files: ['src/components/Login.js']
});
// 返回: { possibleCauses: [...], suggestedFixes: [...] }
```
### 3. 获取调试模板
```javascript
const template = await mcp.call('get_debug_template', {
environment: 'browser',
logMessage: 'Login button clicked',
variables: ['username', 'formData'],
projectPath: '/path/to/project'
});
// 返回: { code: 'fetch(...)', language: 'javascript', description: '...' }
```
AI 将返回的 `code` 复制到用户文件中。
### 4. 读取日志
```javascript
const logs = await mcp.call('read_debug_logs', {
projectPath: '/path/to/project',
lastLines: 100
});
// 返回: { logs: [...], totalLogs: 50, ... }
```
### 5. 列出调试标记
```javascript
const blocks = await mcp.call('list_debug_blocks', {
projectPath: '/path/to/project'
});
// 返回: { files: [{ filePath, blockCount }, ...] }
```
### 6. 清空日志
```javascript
await mcp.call('clear_debug_logs', {
projectPath: '/path/to/project'
});
```
## 配置变更
### 环境变量 (.env)
```env
# 默认端口 37373（不再使用 3000）
DEBUG_PORT=37373
# 或使用 MCP_DEBUG_PORT
MCP_DEBUG_PORT=37373
# 日志文件相对路径
LOG_FILE=.debug/debug.log
```
### Claude Desktop 配置
```json
{
"mcpServers": {
"debug-mcp": {
"command": "node",
"args": ["D:\\work\\debug-mcp\\dist\\index.js"],
"env": {
"DEBUG_PORT": "37373"
}
}
}
}
```
## 优势对比
| 方面 | v1.0 | v2.0 |
|------|------|------|
| **代码注入** | 自动注入 | AI 手动插入 ✅ 更灵活 |
| **代码删除** | 自动删除 | AI 手动删除 ✅ 更安全 |
| **日志位置** | MCP 目录 | 项目目录 ✅ 更合理 |
| **端口冲突** | 容易冲突 (3000) | 极少冲突 (37373) ✅ |
| **环境检测** | 自动检测 | AI 判断 ✅ 更准确 |
| **复杂度** | 高（适配器系统） | 低（模板生成）✅ |
| **AI 控制** | 受限 | 完全控制 ✅ |
## 迁移指南
### 对于用户
1. **更新配置**：端口改为 37373
2. **日志路径**：日志现在在您的项目目录 `.debug/debug.log`
3. **调试流程**：AI 会给您代码模板让您插入，而不是自动修改
### 对于 AI
1. **移除调用**：不再使用 `add_debug_logs` 和 `remove_debug_logs`
2. **使用模板**：调用 `get_debug_template` 获取代码
3. **手动编辑**：将模板代码复制到用户文件
4. **指定路径**：所有涉及日志的操作都需要 `projectPath` 参数
## 文件变更
### 新增文件
- `src/tools/template.ts` - 模板生成器
### 修改文件
- `src/http/server.ts` - 支持 projectPath，端口 37373
- `src/http/log-handler.ts` - 支持 projectPath
- `src/mcp/tools.ts` - 完全重写，使用 if 语句替代 switch
- `.env` - 端口改为 37373
### 删除功能
- `src/tools/injector.ts` - 不再需要（代码注入）
- `src/tools/cleanup.ts` - 不再需要（自动删除）
- `src/adapters/detector.ts` - 不再需要（环境检测）
- `src/adapters/index.ts` - 简化（只保留模板生成）
## 测试验证
```bash
# 构建成功
npm run build
# ✅ 0 errors
# 启动服务器
npm start
# ✅ HTTP API server listening on port 37373
# ✅ Server info: http://localhost:37373/api/info
# 测试端点
curl http://localhost:37373/health
# ✅ {"status":"ok",...}
```
## 总结
v2.0 是一个更加**简洁、灵活、合理**的版本：
- ✅ **AI 有完全控制权** - 代码由 AI 编写和修改
- ✅ **日志组织清晰** - 每个项目的日志独立存储
- ✅ **端口不冲突** - 使用不常用的 37373 端口
- ✅ **架构更简单** - 移除了复杂的适配器和注入系统
- ✅ **使用更直观** - 模板 + 手动插入的方式更容易理解
**升级建议**：立即升级到 v2.0，体验更好的调试工作流！
