Debugging MCP Server
# Debugging MCP Server
A Model Context Protocol (MCP) server for structured debugging assistance. This server exposes tools, resources, and prompts that help an LLM host automatically diagnose errors, search the codebase, and correlate failures.
## Features
This server provides a strict, safe, and context-rich environment for an LLM to investigate coding issues.
### 🛠️ Tools (Actions)
- `initialize_session`: Auto-detects the framework, log paths, test runners, and tech stack.
- `search_codebase`: Fast search using `ripgrep` (fallback to fs walk).
- `run_tests`: Executes the workspace's test suite (requires explicit `confirm=true` flag for safety).
- `get_recent_commits`: Wraps `git` for contextual history.
- **Debugger Integration (DAP & V8 CDP)**:
- `connect_dap`: Connects to a running debugger. Automatically detects and switches between DAP (TCP) and V8 Inspector (WebSocket) protocols!
- `inspect_runtime_state`: Retrieves live threads, call stack, scopes, and variables.
- `step_debugger`: Controls execution flow (`continue`, `next`, `stepIn`, `stepOut`) while preserving safe execution synchronization.
- `evaluate_expression`: Evaluates expressions safely (restricted to `hover` and `watch` contexts).
- `disconnect_dap`: Cleanly disconnects from the remote session.
### 📁 Resources (Context)
- `workspace://structure`: A dynamic map of the repository structure.
- `workspace://logs`: Tail common workspace log files.
### 💬 Prompts (Workflows)
- `debug-error`: Orchestrates the LLM to use the tools to find root causes of an error.
- `explain-stacktrace`: Analyzes a provided stack trace using codebase search.
- `correlate-failure`: Links recent commits to a current failure state.
## Installation & Build
```bash
# Install dependencies
npm install
# Build the TypeScript code
npm run build
```
## Usage
You can run the server directly via stdio:
```bash
npm start
```
### Using the MCP Inspector
To test the server locally, use the official MCP Inspector:
```bash
npm run inspect
```
## Security & Architecture
This server is built with safety in mind. All command execution (like `run_tests`) is gated by a **Policy Layer** (`src/server/policy.ts`) that guarantees:
1. No destructive shell commands can be run.
2. File access is strictly locked to the workspace root.
3. DAP code evaluation is restricted from executing arbitrary mutations (no Repl context).
4. Safety flags (like `confirm: true`) are required for active agents.
For deeper technical details and usage examples, refer to the [GUIDE.md](GUIDE.md).
TDQS
Scored across 9 tools
The tools have clear purposes but some overlap exists. For example, 'initialize_session' and 'connect_dap' both establish debugging context, and 'evaluate_expression' and 'inspect_runtime_state' both retrieve debuggee state information. The descriptions help differentiate them, but an agent might occasionally misselect between related tools.
Most tools follow a consistent verb_noun pattern (e.g., 'connect_dap', 'evaluate_expression', 'run_tests'), with clear and descriptive names. However, 'get_recent_commits' and 'search_codebase' slightly deviate by using 'get' and 'search' instead of more action-oriented verbs, but overall the naming is highly readable and predictable.
With 9 tools, the count is well-scoped for a debugging server. Each tool serves a distinct role in the debugging workflow, from setup and connection to runtime inspection and code analysis, without feeling excessive or insufficient for the domain.
The toolset covers core debugging operations effectively, including session initialization, DAP connection, runtime inspection, expression evaluation, and test execution. Minor gaps exist, such as no explicit tool for setting breakpoints or managing breakpoint lists, but agents can work around this using existing tools like 'step_debugger' and 'search_codebase'.