使用说明

MCP调试器服务器

一个全面的模型上下文协议（MCP）服务器，为LLM应用程序提供调试、测试、linting和代码分析功能。该服务器使AI助手能够通过标准化协议与代码库交互，支持多种编程语言和运行时。

特性

资源

工作区文件：从工作区读取文件和文件切片
Git集成：访问git状态、差异和存储库信息
调试会话：实时调试会话状态和线程信息
堆栈跟踪：当前调用堆栈帧和局部变量
测试报告：测试执行结果和故障分析
Lint报告：代码质量和风格分析结果
日志：具有过滤和搜索功能的结构化日志记录

工具

调试会话管理：打开/关闭多个运行时的调试会话
断点控制：设置、清除、启用/禁用断点
执行控制：进入/结束/退出，继续，暂停执行
表达式求值：在调试上下文中计算表达式
观察表情：在执行过程中监视变量值
文件修补程序：应用带有安全确认的补丁
测试：运行测试套件并分析结果
掉毛：执行代码质量检查
命令执行：运行白名单系统命令
Git操作：在人工确认的情况下提交更改

支持的运行库

Node.js：完全支持Chrome DevTools协议（CDP）
python：通过debugpy调试适配器协议
去：深入调试器集成
Java：JDWP（Java调试线协议）
C: .通过Visual Studio协议进行NET调试
C/C++：GDB/LLDB集成
PHP程序：Xdebug支持
红宝石：Ruby调试器集成
锈：本机调试支持

安装

地方发展设置

# Clone the repository
git clone https://github.com/dennisonbertram/mcp-debugger.git
cd mcp-debugger

# Install dependencies
npm install

# Build the server
npm run build

# Or run directly with ts-node (development)
npm run dev

云代码IDE集成

先决条件

谷歌云代码安装在VS Code/IntelliJ中的扩展
已安装Node.js 18+
在项目中初始化Git存储库

云代码快速入门

全局安装MCP调试器服务器：

npm install -g https://github.com/dennisonbertram/mcp-debugger.git

添加到您的云代码MCP配置中：

{
  "mcp": {
    "servers": {
      "debugger": {
        "command": "mcp-debugger-server",
        "args": [],
        "env": {
          "WORKSPACE_DIR": "${workspaceFolder}"
        }
      }
    }
  }
}

备选方案：在项目中本地运行：

# Add to package.json scripts
{
  "scripts": {
    "mcp-debugger": "node dist/index.js"
  }
}

云代码配置文件

创建或更新您的 .vscode/settings.json:

{
  "cloudcode.mcp.enabled": true,
  "cloudcode.mcp.servers": {
    "debugger": {
      "command": "node",
      "args": ["${workspaceFolder}/node_modules/@dennisonbertram/mcp-debugger/dist/index.js"],
      "env": {
        "WORKSPACE_DIR": "${workspaceFolder}",
        "LOG_LEVEL": "info"
      }
    }
  }
}

IntelliJ云代码配置

对于带有云代码的IntelliJ IDEA：

首选设置 → 工具 → 云代码 → 主控程序
添加新的MCP服务器：
- 名字：MCP调试器
- 命令: node
- 参数: ${project.dir}/node_modules/@dennisonbertram/mcp-debugger/dist/index.js
- 环境变量:
  - WORKSPACE_DIR=${project.dir}
  - LOG_LEVEL=info

MCP云平台部署

对于使用MCP cloud平台的云托管部署：

# Deploy to MCP-Cloud (requires API key)
curl -X POST https://api.mcp-cloud.ai/v1/servers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-debugger-server",
    "template": "custom",
    "env": {
      "WORKSPACE_DIR": "/app",
      "LOG_LEVEL": "info"
    }
  }'

Docker部署

FROM node:18-alpine

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

COPY dist/ ./dist/
EXPOSE 3000

CMD ["node", "dist/index.js"]

# Build and run
docker build -t mcp-debugger .
docker run -p 3000:3000 -e WORKSPACE_DIR=/app mcp-debugger

MCP云集成

MCP调试器服务器可以通过MCP云平台进行部署和管理，以供企业级使用：

身份验证设置

# Set API key for MCP-Cloud
export MCP_API_KEY="mcp_sk_your_api_key_here"

Python客户端集成

import requests

def debug_with_mcp(prompt, session_id=None):
    url = "https://your-server.mcp-cloud.ai/v1/chat/completions"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {os.environ['MCP_API_KEY']}"
    }

    data = {
        "model": "claude-3-5-sonnet",
        "messages": [{"role": "user", "content": prompt}],
        "context_id": session_id  # For maintaining debug context
    }

    response = requests.post(url, headers=headers, json=data)
    return response.json()

JavaScript/Node.js客户端

async function debugWithMCP(prompt, sessionId = null) {
  const response = await fetch('https://your-server.mcp-cloud.ai/v1/chat/completions', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.MCP_API_KEY}`
    },
    body: JSON.stringify({
      model: 'claude-3-5-sonnet',
      messages: [{ role: 'user', content: prompt }],
      context_id: sessionId
    })
  });

  return response.json();
}

SSE实时流媒体

// Enable streaming for real-time debug output
const eventSource = new EventSource(
  'https://your-server.mcp-cloud.ai/api/servers/debug-session/events',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MCP_API_KEY}`
    }
  }
);

eventSource.addEventListener('debug:output', (event) => {
  const data = JSON.parse(event.data);
  console.log('Debug output:', data.message);
});

eventSource.addEventListener('breakpoint:hit', (event) => {
  const data = JSON.parse(event.data);
  console.log('Breakpoint hit at line:', data.line);
});

工作流集成（n8n、Zapier等）

n8n集成示例

// In an n8n Function node
const axios = require('axios');

async function debugCode(codeSnippet) {
  const response = await axios.post(
    'https://your-server.mcp-cloud.ai/v1/chat/completions',
    {
      model: "claude-3-5-sonnet",
      messages: [
        {
          role: "system",
          content: "You are a debugging assistant. Analyze the following code for issues."
        },
        {
          role: "user",
          content: codeSnippet
        }
      ],
      stream: true  // Enable streaming for real-time responses
    },
    {
      headers: {
        'Authorization': `Bearer ${$credentials.mcpApi.apiKey}`,
        'Content-Type': 'application/json'
      }
    }
  );

  return response.data;
}

配置

环境变量

# Workspace directory (defaults to current directory)
WORKSPACE_DIR=/path/to/your/project

# Enable/disable dangerous features
ALLOW_FILE_PATCHES=true
ALLOW_COMMAND_EXECUTION=false

# Limits and timeouts
MAX_EXECUTION_TIME_MS=30000
MAX_OUTPUT_BYTES=1048576

# Logging
LOG_LEVEL=info

安全功能

路径横向保护：所有文件操作都被沙盒化到工作区
命令白名单：只能执行批准的命令
补丁确认：文件补丁需要明确确认
输出限制：防止大输出占用过多内存
超时保护：所有操作都有可配置的超时

用法

启动服务器

# Production build
npm start

# Development with auto-reload
npm run dev

# With custom workspace
WORKSPACE_DIR=/my/project npm start

MCP客户端集成

克劳德桌面（单行设置）

快速设置命令：

# Add to Claude Desktop config (one line)
echo '{"mcpServers":{"debugger":{"command":"node","args":["/path/to/mcp-debugger/dist/index.js"],"env":{"WORKSPACE_DIR":"'"$PWD"'"}}}}' >> ~/Library/Application\ Support/Claude/claude_desktop_config.json

或者手动编辑配置文件：

# macOS/Linux
code ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Windows
code %APPDATA%\Claude\claude_desktop_config.json

添加此配置：

{
  "mcpServers": {
    "debugger": {
      "command": "node",
      "args": ["/path/to/mcp-debugger/dist/index.js"],
      "env": {
        "WORKSPACE_DIR": "/path/to/your/project"
      }
    }
  }
}

程序化客户端集成

服务器使用MCP协议通过stdio进行通信。将其连接到任何兼容MCP的客户端：

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

// Create MCP client
const client = new Client({
  name: "my-debug-client",
  version: "1.0.0"
});

// Connect to the debugger server
const transport = new StdioClientTransport({
  command: "node",
  args: ["dist/index.js"]
});

await client.connect(transport);
await client.initialize();

可用客户端库

Python MCP客户端

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    # Connect to MCP Debugger Server
    server_params = StdioServerParameters(
        command="node",
        args=["/path/to/mcp-debugger/dist/index.js"],
        env={"WORKSPACE_DIR": "/your/project"}
    )

    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # Use debugging tools
            result = await session.call_tool("open_debug_session", {
                "kind": "node",
                "entry": "app.js"
            })

            print("Debug session opened:", result)

asyncio.run(main())

Java MCP客户端

import io.modelcontextprotocol.client.McpClient;
import io.modelcontextprotocol.client.transport.StdioClientTransport;

public class DebugClient {
    public static void main(String[] args) {
        // Create MCP client
        McpClient client = McpClient.builder()
            .name("Debug Client")
            .version("1.0.0")
            .build();

        // Connect via stdio
        StdioClientTransport transport = new StdioClientTransport(
            "node",
            List.of("/path/to/mcp-debugger/dist/index.js")
        );

        client.connect(transport);

        // Use debugging capabilities
        ToolResult result = client.callTool("open_debug_session",
            Map.of("kind", "node", "entry", "app.js"));

        System.out.println("Debug session: " + result);
    }
}

cURL用于测试

# Test server health
curl -X POST http://localhost:3000/health

# Test MCP protocol (if using HTTP transport)
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-06-18"},"id":1}'

工作流示例

打开调试会话

const result = await client.callTool({
  name: "open_debug_session",
  arguments: {
    kind: "node",
    entry: "src/index.js",
    args: ["--port", "3000"]
  }
});
const sessionId = result.content[0].text.session_id;

设置断点

await client.callTool({
  name: "set_breakpoint",
  arguments: {
    session_id: sessionId,
    file: "src/server.js",
    line: 42,
    condition: "user.id > 0"
  }
});

检查状态

// Get stack trace
const stack = await client.callTool({
  name: "stack_trace",
  arguments: { session_id: sessionId }
});

// Evaluate expressions
const result = await client.callTool({
  name: "evaluate_expression",
  arguments: {
    session_id: sessionId,
    expression: "user.profile",
    frame_id: "frame_0"
  }
});

应用修复程序

// Apply a patch (will require confirmation)
await client.callTool({
  name: "apply_patch",
  arguments: {
    file: "src/buggy.js",
    start: 41,
    end: 43,
    replacement: "if (user && user.id > 0) {",
    require_confirmation: true
  }
});

运行测试

const testResult = await client.callTool({
  name: "run_tests",
  arguments: {
    runner: "npm",
    args: ["test", "--", "--grep", "user"]
  }
});

api参考

资源

`workspace://file`

从工作区读取文件和文件切片。

参数：

path：文件的相对路径
start：起始行号（可选）
end：结束行号（可选）

例子：

workspace://file?path=src/index.js&start=1&end=50

`debug://session/{sessionId}/state`

获取调试会话状态信息。

`debug://session/{sessionId}/locals`

获取当前帧的局部变量。

`logs://app`

通过筛选访问应用程序日志。

参数：

level：日志级过滤器（调试、信息、警告、错误）
since：开始时间的ISO日期字符串
contains：日志消息中的文本搜索
limit：要返回的最大条目数

工具

调试会话管理

open_debug_session：启动新的调试会话
close_debug_session：终止调试会话
list_debug_sessions：列出所有活动会话

断点控制

set_breakpoint：在文件位置设置断点
clear_breakpoint：删除断点
list_breakpoints：列出会话中的所有断点
toggle_breakpoint：启用/禁用断点

执行控制

continue_execution：从当前断点继续
step_into：进入函数调用
step_over：跳过函数调用
step_out：退出当前功能
pause_execution：暂停运行执行

表达式求值

evaluate_expression：计算JavaScript/Python/等表达式
watch_expression：设置手表表情
list_watch_expressions：列出活动手表表情
clear_watch_expression：删除手表表情

测试和梳理

run_tests：执行测试套件
run_lint：执行代码质量检查

文件操作

apply_patch：将补丁应用于文件（确认后）
run_command：执行白名单系统命令
git_commit：提交更改（确认）

建筑

服务器采用模块化架构构建：

MCPDebuggerServer
├── Resources/
│   ├── WorkspaceResources    # File/Git operations
│   ├── DebugResources        # Debug session state
│   ├── TestResources         # Test/lint reports
│   └── LogResources          # Logging infrastructure
├── Tools/
│   ├── DebugSessionTools     # Session management
│   ├── BreakpointTools       # Breakpoint operations
│   ├── ExecutionTools        # Step/continue operations
│   ├── EvaluationTool        # Expression evaluation
│   ├── TestTools            # Testing operations
│   ├── LintTools            # Linting operations
│   ├── PatchTools           # File patching
│   ├── CommandTools         # Command execution
│   └── GitTools             # Git operations
└── Utils/
    ├── Logger               # Structured logging
    └── Config               # Configuration management

每个组件都是可扩展的，可以很容易地增强以支持额外的运行时、工具和资源。

扩展服务器

添加新运行库

实施 DebuggerAdapter 接口：

class MyRuntimeAdapter implements DebuggerAdapter {
  // Implement required methods
  async launch(entry: string, args?: string[], env?: Record<string, string>): Promise<void> {
    // Start your runtime's debugger
  }

  async setBreakpoint(bp: Breakpoint): Promise<Breakpoint> {
    // Set breakpoint in your runtime
  }

  // ... other required methods
}

在中注册适配器 DebugSessionTools:

if (args.kind === 'myruntime') {
  adapter = new MyRuntimeAdapter(cwd);
}

添加新工具

创建一个扩展基本模式的新工具类：

export class MyCustomTool {
  registerTools(server: McpServer): void {
    server.registerTool("my_custom_tool", {
      // Tool definition
    }, this.handleMyCustomTool.bind(this));
  }

  private async handleMyCustomTool(args: any): Promise<MCPToolResult> {
    // Tool implementation
  }
}

在中注册该工具 MCPDebuggerServer:

this.myCustomTool = new MyCustomTool(config);
this.myCustomTool.registerTools(this.server);

贡献

分叉存储库
创建要素分支
添加新功能的测试
确保所有测试通过
提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

支持的集成

IDE和编辑器

VS代码：完整的云代码集成
智能 IDEA：云代码插件支持
克劳德桌面：原生MCP支持
光标：MCP协议支持
帆板运动：MCP集成
泽德：MCP支持

云平台

MCP云：企业部署平台
谷歌云代码：直接集成IDE
码头工人：容器化部署
Kubernetes：精心策划的部署

工作流程自动化

n8n：可视化工作流集成
扎皮尔：基于API的集成
Make.com：工作流自动化
GitHub操作：CI/CD集成

程式语言

Types/JavaScript：本地支持
python：调试适配器协议
去：深度整合
Java：JDWP支持
C: .NET调试
C/C++：GDB/LLDB支持
PHP程序：Xdebug集成
红宝石：Ruby调试器
锈：本机调试

支持

对于问题和疑问：

GitHub问题：报告错误和请求功能
文档： API完整参考
讨论：社区支持

更新日志

v0.1.0

支持Node.js调试的初始版本
基本工作区文件操作
Git集成
测试和棉绒执行
带有安全确认的文件修补
使用白名单执行命令
全面的日志记录和错误处理