Project Tools

This directory contains project-local development tools and MCP servers.

GDB MCP Server

Location: mcp-server-gdb/

This is a high-quality GDB/MI protocol MCP server. It allows AI agents (Grok Build, Claude, Cursor, etc.) to drive real GDB sessions using the proper Machine Interface protocol instead of fragile CLI scraping.

Current Status (2026-05-15)

The server is production-usable in both modes:

• Full migration to rmcp 0.1.5 is complete.
• All tools use modern #[tool] + Parameters<T> with rich, documented JSON schemas.
• Real async stop/breakpoint notifications work for MCP clients.
• The original ratatui TUI is fully functional and can run alongside the MCP server.
• Zero compiler warnings. Two integration tests exist.
• The original "two GDBManager worlds" design is strictly preserved (TUI has its private manager; agents use the global one).

Why This Project Exists

• Reference implementation and testbed for ptrace-based debugger work (cdebug)
• Reliable remote GDB control for agents using the real GDB/MI protocol
• Visual TUI lets developers watch exactly what the AI is doing during debugging sessions

Running

From the project root:

./gdb-mcp                 # TUI + SSE server on port 9090 (best for observation)
./gdb-mcp --stdio         # Clean stdio MCP server (primary mode for agents)
./gdb-mcp --port 1234     # Custom SSE port

Usage with MCP Clients

Claude Desktop / Cursor / Windsurf (stdio mode — recommended):

{
  "mcpServers": {
    "gdb": {
      "command": "./gdb-mcp",
      "args": ["--stdio"],
      "cwd": "/absolute/path/to/your/project"
    }
  }
}

TUI + Remote Access:

Run ./gdb-mcp (no arguments) to get both the beautiful ratatui TUI and an SSE server on port 9090. You can then connect other clients to http://127.0.0.1:9090/sse.

Key Features

• Proper GDB/MI protocol (not CLI scraping)
• Rich, self-documenting tool schemas for agents
• Real async stopped / breakpoint notifications
• Multi-session support
• Full original ratatui TUI (registers, stack, assembly, hexdump, memory, breakpoints, etc.)
• Clean separation between TUI-driven sessions and agent-driven sessions
• Zero warnings, solid integration tests

Important Notes

• The TUI (./gdb-mcp) and the MCP server can (and often should) run at the same time on different sessions. This is by design.
• The TUI uses its own private GDBManager. Agents use the global one exposed via the MCP tools.
• Pressing q in the TUI cleanly shuts down both the interface and the SSE server.

Development

cd mcp-server-gdb
cargo build --release
cargo test
cargo check          # Must be clean (0 warnings policy)

Upstream

This is a vendored and heavily evolved fork of https://github.com/pansila/mcp_server_gdb (MIT).

See mcp-server-gdb/MCP.md for the detailed migration history and current priorities.

Note: Only the build artifacts (target/) in mcp-server-gdb/ are gitignored. The full source is tracked for reproducibility and history.