MCP Debug

MCP调试服务器

概述

MCP调试服务器在调试适配器协议（DAP）和模型上下文协议（MCP）之间提供了一个桥梁，通过标准化的接口对Go应用程序进行编程调试。该系统将Delve调试器功能与基于角色的架构集成在一起，该架构源于闪电网络的并发模式。

该项目提供了两个主要界面：一个供人类操作员使用的交互式终端用户界面，以及一个用于与人工智能系统和其他自动化工具集成的无头MCP服务器。这两个接口共享相同的底层调试引擎，该引擎构建在具有适当生命周期管理的面向服务的架构上。

安装

构建交互式TUI控制台：

go build -o tui-console ./cmd/tui
./tui-console

构建无头MCP服务器：

go build -o dlv-mcp-server ./cmd/dlv-mcp-server
./dlv-mcp-server

Claude代码集成

要将此调试器与Claude Code一起使用，请将MCP服务器安装到Go-bin目录中：

go install ./cmd/dlv-mcp-server

然后将其添加到Claude代码中（假设GOPATH/bin在您的PATH中）：

claude mcp add go-debugger dlv-mcp-server

如果GOPATH/bin不在您的PATH中，请使用完整路径：

claude mcp add go-debugger $(go env GOPATH)/bin/dlv-mcp-server

一旦添加，Claude将可以访问MCP服务器提供的所有15个调试工具。您可以通过要求Claude列出可用的MCP工具或启动调试会话来验证连接。

Gemini CLI集成

要将此调试器与Gemini CLI一起使用，请先将MCP服务器安装到Go-bin目录中：

go install ./cmd/dlv-mcp-server

然后，将其作为MCP服务器添加到Gemini CLI中（假设 GOPATH/bin 在你的 PATH):

gemini mcp add go-debugger dlv-mcp-server

如果 GOPATH/bin 不在你的 PATH，使用完整路径：

gemini mcp add go-debugger $(go env GOPATH)/bin/dlv-mcp-server

一旦添加，Gemini将可以访问MCP服务器提供的所有15个调试工具。您可以通过要求Gemini列出可用工具来验证连接(gemini tool list)或者通过启动调试会话。

手动MCP服务器配置

对于不包括以下内容的较旧版本的Gemini CLI gemini mcp add 命令，您可以通过编辑来手动配置MCP服务器 settings.json 文件。此文件通常位于 ~/.gemini/settings.json.

你需要添加一个 mcpServers 反对此文件。此对象包含每个服务器的键值对，其中键是服务器的唯一名称，值是定义如何启动和与之交互的对象。

以下是一个如何在中配置MCP服务器的示例 settings.json:

{
  "mcpServers": {
    "go-debugger": {
      "command": "dlv-mcp-server",
      "env": [],
      "trust": true
    }
  }
}

配置选项

• command：启动MCP服务器的命令。
• args：传递给命令的字符串参数数组。
• cwd：启动服务器的工作目录。
• env：为服务器进程设置的环境变量。
• timeout：向服务器发出请求的超时时间（毫秒）。
• trust：一个布尔值，用于绕过该服务器的工具调用确认。

注： 建议使用 gemini mcp add 在较新版本的Gemini CLI上使用命令，以避免手动配置错误。

建筑

该系统被组织成具有明确关注点分离的重点包。在根水平上， daemon.go 提供管理所有组件生命周期的MCPDebugService。此服务初始化参与者系统，创建MCP服务器，并确保在关闭时进行适当的清理。

graph TB
    subgraph "User Interfaces"
        TUI["TUI Console
Bubble Tea Framework"]
        MCP_CLIENT["MCP Clients
AI/LLM Systems"]
    end
    
    subgraph "Service Layer"
        DAEMON["MCPDebugService
daemon.go"]
    end
    
    subgraph "Protocol Layer"
        MCP_SERVER["MCP Server
15 Debug Tools
JSON-RPC 2.0"]
        TUI_PKG["TUI Package
Dashboard, Sessions
Commands, Logs"]
    end
    
    subgraph "Core Engine"
        ACTOR["Actor System
LND Router Pattern
Message Passing"]
        DEBUGGER["Debugger Package
DAP Protocol
Session Management"]
    end
    
    subgraph "Debug Backend"
        DELVE["Delve Debugger
Go Runtime Integration"]
    end
    
    TUI --> TUI_PKG
    MCP_CLIENT --> MCP_SERVER
    TUI_PKG --> DAEMON
    MCP_SERVER --> DAEMON
    DAEMON --> ACTOR
    ACTOR --> DEBUGGER
    DEBUGGER --> DELVE
    
    style TUI fill:#2196F3,stroke:#1565C0,stroke-width:2px,color:#fff
    style MCP_CLIENT fill:#2196F3,stroke:#1565C0,stroke-width:2px,color:#fff
    style DAEMON fill:#FF9800,stroke:#E65100,stroke-width:2px,color:#fff
    style MCP_SERVER fill:#9C27B0,stroke:#6A1B9A,stroke-width:2px,color:#fff
    style TUI_PKG fill:#9C27B0,stroke:#6A1B9A,stroke-width:2px,color:#fff
    style ACTOR fill:#4CAF50,stroke:#2E7D32,stroke-width:2px,color:#fff
    style DEBUGGER fill:#4CAF50,stroke:#2E7D32,stroke-width:2px,color:#fff
    style DELVE fill:#F44336,stroke:#C62828,stroke-width:2px,color:#fff

调试器包包含核心DAP协议实现和Delve集成。它使用基于角色的消息传递系统，其中调试命令通过类型化消息接口异步处理。每个调试会话都作为独立的参与者运行，允许具有隔离状态的多个并发调试会话。

MCP包将调试功能作为十五个可通过JSON-RPC 2.0访问的标准化工具公开。这些工具涵盖会话管理、程序控制、断点管理、执行控制和检查功能。所有工具参数都使用具有全面验证的强类型结构。

TUI包使用Bubble Tea框架实现了一个交互式终端界面。它提供了五个不同的视图：显示实时指标的仪表板、用于管理活动调试会话的会话表、用于监控连接的客户端视图、用于执行MCP工具的命令界面和用于系统输出的日志查看器。TUI通过MCP服务器使用的相同执行器系统连接到调试引擎，确保接口之间的一致性。

封装结构

该项目遵循分层包结构，其中每个包都有一个明确定义的责任。根包提供服务层和生命周期管理。调试器包处理所有DAP协议问题和Delve集成。MCP包将调试操作转换为MCP工具。TUI软件包提供交互式监控。

支持包包括用于生产二进制文件的cmd、用于开发实用程序的内部/测试、演示程序的示例以及用于全面记录实施过程的agent_planning。

演员系统

该项目使用闪电网络的actor系统进行并发消息处理。这比传统的基于互斥的并发性提供了几个关键优势。参与者按顺序处理消息，消除参与者边界内的竞争条件。路由器模式实现了跨多个调试器实例的负载平衡。类型安全消息接口确保了参与者间通信的编译时正确性。

演员之间的沟通遵循两种模式。Tell模式为通知和状态更新提供了即发即弃消息。Ask模式实现了与future的请求-响应通信，用于异步操作上的同步式编程。

MCP工具

MCP服务器通过十五个工具公开调试功能：

会话管理工具包括 create_debug_session 用于初始化新会话，以及 initialize_session 用于配置DAP客户端功能。

程序控制工具提供 launch_program 在启用调试的情况下启动Go程序， attach_to_process 用于调试已运行的进程，以及 configuration_done 以表示准备就绪。

断点管理通过以下方式处理 set_breakpoints 它接受文件路径和行号。

执行控制工具包括 continue_execution, step_next, step_in, step_out，以及 pause_execution 用于对程序流进行细粒度控制。

检查工具提供 get_threads 对于线程信息， get_stack_frames 对于呼叫栈， get_variables 用于范围检查，以及 evaluate_expression 用于运行时评估。

终端用户界面

TUI通过选项卡式界面提供全面的监控和控制功能。导航使用标准键盘快捷键，其中Tab用于切换视图，箭头键用于选择，Enter用于执行命令，q或Ctrl+C用于退出。

仪表板视图显示服务器状态、活动会话、连接的客户端、总请求数、错误计数和正常运行时间。这些指标在服务器处理请求时实时更新。

会话视图显示了所有调试会话的可排序表，其中包含会话ID、客户端信息、程序路径、当前状态和断点计数列。可以选择会话进行详细检查。

命令视图为执行MCP工具提供了一个交互式提示。命令以JSON对象的形式输入，指定工具名称和参数。保留先前执行的命令的历史记录，以供参考和重新执行。

日志视图在可滚动视口中显示系统输出，并自动跟踪新条目。日志条目按级别分类，并加盖时间戳，以便于调试和审计。

用法

对于交互式调试，启动TUI控制台并使用命令选项卡创建调试会话。例如，输入 {"tool": "create_debug_session", "args": {"session_id": "debug1"}} 初始化新会话。然后，会话将出现在会话选项卡中，可以在其中监视其状态。

对于程序化访问，请运行MCP服务器并通过MCP协议进行连接。服务器通过标准I/O接受JSON-RPC 2.0请求。请求遵循MCP规范，工具调用封装在标准协议信封中。

日志记录

MCP调试服务器维护详细的日志，用于调试和故障排除。日志会自动写入 ~/.dlv-mcp-server 主文件夹中的目录。

日志文件结构

• 位置: ~/.dlv-mcp-server/
• 格式: debug_YYYY-MM-DD_HH-MM-SS.log （为每个服务器会话打上时间戳）
• 最新日志：符号链接 latest.log 始终指向当前会话的日志文件

日志内容

日志文件包括：

• 服务器启动和初始化消息
• DAP协议请求和响应
• 会话生命周期事件（创建、初始化、终止）
• 调试操作（断点、步进、求值）
• 操作失败时的错误消息和堆栈跟踪

查看日志

要实时查看当前会话的日志：

tail -f ~/.dlv-mcp-server/latest.log

要搜索特定操作或错误，请执行以下操作：

grep -i error ~/.dlv-mcp-server/latest.log
grep "evaluate" ~/.dlv-mcp-server/latest.log

日志保留

日志文件不会自动清理。要管理磁盘空间，请定期删除旧日志文件：

# Remove logs older than 7 days
find ~/.dlv-mcp-server -name "debug_*.log" -mtime +7 -delete

发展

该项目遵循Lightning Network的代码风格和提交约定开发指南。代码使用80个字符的行限制，并使用制表符进行缩进。函数用godoc兼容的注释记录。提交的前缀是受影响的包名称。

测试使用带有断言证明的标准Go测试框架。每个包都包括全面的单元测试。集成测试验证了从MCP请求到DAP协议再到Delve后端的完整调试工作流程。

依赖项

该项目依赖于几个关键的外部库。闪电网络的actor系统提供了并发框架。谷歌的go-dap实现了调试适配器协议。Charm的泡泡茶为终端界面提供动力。Mark3Labs的mcp-go处理mcp协议问题。

文档

agent_planning目录中提供了全面的文档。这包括架构决策、实现说明和开发历史。关键文档涵盖了参与者系统模式、TUI设计和实现、包重构过程和过程附件功能。

许可证

这个项目是开源软件。有关条款和条件，请参阅许可文件。