Debugging 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

# Install dependencies
npm install

# Build the TypeScript code
npm run build

Usage

You can run the server directly via stdio:

npm start

Using the MCP Inspector

To test the server locally, use the official MCP Inspector:

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.