What is cpp-debug-mcp CLAUDE.md?

A project guide for Claude Code working on a C++ debugging server. It describes the repository structure, development setup, testing commands, and components that connect the GNU Debugger and clangd, a C++ code-analysis tool.

It is for developing and testing a Python server that exposes C++ debugging and code-analysis tools.

It gives the coding agent the project-specific context needed to navigate the codebase and use its setup and test commands correctly.

cpp-debug-mcp CLAUDE.md — Instructions file by William-An

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods

npx agentmods add instructions/william-an/cpp-debug-mcp/claude-md

Clone the repo

git clone --depth 1 https://github.com/William-An/cpp-debug-mcp

Per session 786 This file is loaded in full into every session.

When invoked 786 The same file — it is already loaded in full.

Security scan A 0 findings. Scan, not verified.

Origin original No closer match found in the catalogue.

Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

Model	Per session	Once invoked
Fable 5	$0.00786	$0.00786
Opus 5	$0.00393	$0.00393
Sonnet 5	$0.00157	$0.00157
Haiku 4.5	$0.00079	$0.00079

Measured yesterday against content hash 971bb2df0ffb, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

cpp-debug-mcp CLAUDE.md scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured yesterday.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

CLAUDE.md · 78 lines

How it starts

The opening of the file, as written. The whole thing — 78 lines — stays where its author put it; the contents beside it link to each section on GitHub.

CLAUDE.md — cpp-debug-mcp

Project Overview

MCP server plugin for Claude Code that integrates GDB (via GDB/MI) and clangd (via LSP) for C++ debugging. Published on PyPI as cpp-debug-mcp.

Repository Layout

src/cpp_debug_mcp/
  server.py          — FastMCP server entry point, lifespan, tool registration
  __main__.py         — python -m entry point
  gdb/
    controller.py     — Async GDB/MI wrapper (pygdbmi + run_in_executor)
    session.py        — Session lifecycle, tmux console management
  lsp/
    client.py         — Async JSON-RPC client for clangd over STDIO
    protocol.py       — LSP message helpers & response parsers
    session.py        — clangd session manager
  analysis/
    correlator.py     — Cross-references GDB runtime + LSP static info
  tools/
    fmt.py            — Human-readable output formatting
    gdb_tools.py      — 16 GDB MCP tools
    lsp_tools.py      — 8 LSP MCP tools
    combined_tools.py — 3 combined GDB+LSP tools
tests/               — pytest tests (fixtures in tests/fixtures/)

Development Setup

uv venv .venv
source .venv/bin/activate
uv pip install -e ".[dev]"
pytest tests/ -v

Testing

27 tests currently pass; 10 are skipped when clangd is not installed
Tests require gdb to be installed (system package)
Test fixtures: tests/fixtures/sample.cpp (valid program), tests/fixtures/segfault.cpp (null deref)
Fixtures are compiled automatically by tests via the Makefile

Release & Publish Flow

Bump version in both pyproject.toml and setup.cfg (they must stay in sync)
Commit and push to master
Create a GitHub release: gh release create v<VERSION> --title "v<VERSION>" --notes "..."
The .github/workflows/publish.yml workflow runs tests on Python 3.10/3.12/3.13, then publishes to PyPI via trusted publisher (OIDC — no API tokens needed)
PyPI indexing takes ~30 seconds; verify with pip index versions cpp-debug-mcp

MCP Registration

Global (all projects):

claude mcp add --scope user cpp-debug -- uvx cpp-debug-mcp

Read the full file on GitHub · 78 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

yesterday First seen · 78 lines · 786 tokens per session scan A 971bb2df0ffb

Subscribe to this mod's changes

cpp-debug-mcp CLAUDE.md is an instructions file published in the GitHub repository William-An/cpp-debug-mcp (1 stars, last pushed 5mo ago), licensed MIT. It adds 786 tokens to every session, about $0.0039 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.

Debugging Languages Testing

codex AGENTS.md

AGENTS.md instructions for openai/codex, covering rust/codex-rs, the codex-core crate, code review rules, crate api surface and model visible context.

openai/codex · 5,182 tokens

buildNext

Working notes and architecture documentation for the new esbuild-based build system in build/next. Use when making changes to the new build pipeline (transpile/bundle commands, NLS plugin, source-map handling, resource copying, or self-hosting watch tasks).

microsoft/vscode · 6,785 tokens

cpp-debug-mcp CLAUDE.md