使用说明
调试MCP服务器
一个MCP（模型上下文协议）服务器，连接web浏览器和Claude代码，实现无缝调试工作流程。
概述
此服务器从浏览器小部件（控制台日志、错误堆栈、屏幕截图）接收调试数据，并通过MCP协议将其暴露给Claude Code。它还促进了Claude Code和浏览器用户之间的互动问答。
特性
- 调试数据摄入：用于从浏览器接收调试报告的HTTP端点
- MCP工具：通过MCP协议将调试数据暴露给Claude Code
- 互动问答：基于WebSocket的双向通信，用于澄清问题
- 文件存储：用于报告和屏幕截图的有序文件系统存储
- 仅限本地主机：仅保护本地服务器以供开发使用
快速开始
安装
# Global installation
npm install -g @yourco/debug-mcp-server
# Or use npx
npx @yourco/debug-mcp-server
运行服务器
# Start the server
debug-mcp-server
# Or with custom port
DEBUG_MCP_PORT=4000 debug-mcp-server
配置
创建 ~/.debug-mcp/config.json:
{
"port": 3000,
"storagePath": "~/.debug-mcp",
"retentionDays": 7
}
或者使用环境变量：
DEBUG_MCP_PORT-HTTP服务器端口（默认值：3000）DEBUG_MCP_STORAGE_PATH-存储目录（默认：~/.debug-mcp)DEBUG_MCP_RETENTION_DAYS-报告保留期（默认值：7）
MCP集成
将Claude代码连接到服务器
添加到您的Claude Code MCP配置中：
{
"mcpServers": {
"debug-reports": {
"command": "node",
"args": ["/path/to/debug-mcp-server/dist/index.js"]
}
}
}
可用的MCP工具
submit_debug_report-从浏览器接收调试数据list_debug_reports-列出所有已存储的调试报告get_debug_report-按ID检索特定调试报告ask_user_questions-将问题发送到浏览器并等待答案clear_old_reports-清理旧的调试数据
可用MCP资源
debug://reports/latest-获取最新调试报告debug://reports/{id}-按ID获取特定报告debug://screenshots/{id}-访问屏幕截图文件
API终点
POST/api/debug
从浏览器小部件接收调试数据。
请求正文：
{
"logs": [
{ "level": "error", "message": "Error message", "timestamp": 1234567890 }
],
"error": {
"message": "TypeError: Cannot read property...",
"stack": "Error stack trace..."
},
"screenshot": "data:image/png;base64,...",
"comment": "User description of the issue",
"url": "https://example.com/page",
"timestamp": 1234567890
}
答复：
{
"success": true,
"data": {
"reportId": "abc123",
"timestamp": 1234567890
}
}
POST/api/问题/答案
从浏览器接收克劳德问题的答案。
请求正文：
{
"sessionId": "session-123",
"answers": [
{ "questionId": "q1", "answer": "User's answer" }
]
}
发展
设置
# Clone the repository
git clone https://github.com/yourco/debug-mcp-server.git
cd debug-mcp-server
# Install dependencies
npm install
# Run in development mode
npm run dev
项目结构
debug-mcp-server/
├── src/
│ ├── index.ts # Entry point
│ ├── mcp/ # MCP server implementation
│ ├── http/ # HTTP/WebSocket servers
│ ├── storage/ # File storage layer
│ ├── types/ # TypeScript types
│ └── config/ # Configuration
├── specs/ # SpecKit specifications
├── tests/ # Jest tests
└── logs/ # Session logs
测试
# Run unit tests
npm test
# Run with coverage
npm run test:coverage
# Run linter
npm run lint
建筑
# Build for production
npm run build
# Output: dist/index.js
建筑
┌─────────────────────┐
│ Browser Widget │
│ (HTTP/WebSocket) │
└──────────┬──────────┘
│
↓
┌─────────────────────────────────────┐
│ Debug MCP Server │
│ ┌─────────────────────────────┐ │
│ │ HTTP Server (Express) │ │
│ │ - POST /api/debug │ │
│ │ - POST /api/questions │ │
│ └─────────────────────────────┘ │
│ ┌─────────────────────────────┐ │
│ │ WebSocket Server │ │
│ │ - Push questions to browser│ │
│ └─────────────────────────────┘ │
│ ┌─────────────────────────────┐ │
│ │ MCP Server │ │
│ │ - Tools & Resources │ │
│ └─────────────────────────────┘ │
│ ┌─────────────────────────────┐ │
│ │ File Storage │ │
│ │ - ~/.debug-mcp/ │ │
│ └─────────────────────────────┘ │
└──────────┬──────────────────────────┘
│
↓
┌─────────────────────┐
│ Claude Code │
│ (VS Code) │
└─────────────────────┘
存储结构
~/.debug-mcp/
├── reports/
│ ├── 2025-11-26/
│ │ ├── report-abc123.json
│ │ └── report-def456.json
│ └── 2025-11-27/
│ └── report-ghi789.json
├── screenshots/
│ ├── screenshot-abc123.png
│ └── screenshot-def456.png
└── config.json
故障排除
服务器无法启动
检查端口是否已在使用中：
lsof -i :3000
使用其他端口：
DEBUG_MCP_PORT=4000 debug-mcp-server
Claude Code无法连接
- 验证服务器是否正在运行：
curl http://localhost:3000/api/health - 检查克劳德代码设置中的MCP配置
- 配置更改后重新启动VS代码
浏览器小部件无法发送数据
- 验证服务器是否在localhost:3000上运行
- 检查浏览器控制台是否存在CORS错误
- 确保浏览器可以通过网络访问本地主机
贡献
看 CLAUDE.md 开发指南和项目构成。
许可证
麻省理工学院
支持
对于问题和功能请求，请在GitHub上打开问题。
