Skip to main content
Glama
Debugging MCP Server

Debugging MCP Server

by luischang07

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.

Related MCP server: SentinelMCP

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.

Available Tools

9 tools
connect_dapConnect to Debug AdapterA

Establishes a TCP connection to a running Debug Adapter Protocol (DAP) server. This must be called before inspect_runtime_state or evaluate_expression. The debug adapter must already be listening on the specified host and port (e.g., a Node.js app started with --inspect-brk, or a VS Code debug adapter in server mode).

Inputs: port (required), host, adapter_id, protocol, +1 more.

disconnect_dapDisconnect from Debug AdapterA

Cleanly disconnects from the current DAP session. The debuggee continues running — this does NOT terminate it. Idempotent: safe to call even if not connected.

Inputs: no named parameters.

evaluate_expressionEvaluate ExpressionA

Evaluates an expression in the context of the debuggee's current state. Requires an active DAP connection and typically works best when the debuggee is stopped. The context parameter restricts what kind of evaluation is performed: "hover" (default, safe, no side effects) or "watch".

Inputs: expression (required), frame_id, context.

get_recent_commitsGet Recent CommitsA

Retrieves recent git commits for the workspace. Useful for correlating code changes with failures. Returns commit hash, author, date, and message.

Inputs: count, file, since, show_diff.

initialize_sessionInitialize Debug SessionA

Auto-detects the workspace's technology stack, package manager, test runner, log paths, and entry points. Call this first to establish context before debugging.

Inputs: workspace_path.

inspect_runtime_stateInspect Runtime StateA

Retrieves the live debugging snapshot from a connected DAP session: threads, call stack, scopes, and local variables with their current values. Requires an active DAP connection (call connect_dap first). Most useful when the debuggee is stopped at a breakpoint.

Inputs: thread_id, frame_index, max_variables, variable_depth.

run_testsRun TestsA

Executes the workspace's test suite. Auto-detects the appropriate test runner. The confirm flag MUST be set to true to actually execute — this is a safety measure.

Inputs: confirm (required), command, timeout_ms.

search_codebaseSearch CodebaseA

Fast text search across the workspace files. Uses ripgrep when available, falls back to a recursive file walk. Returns matching file paths, line numbers, and line content.

Inputs: query (required), case_sensitive, max_results, path.

step_debuggerStep DebuggerA

Controls execution flow of the debuggee. Use this to resume, step over, step into, or step out. Requires an established debugging connection which is currently paused. This command will mutate the state of the debuggee and wait up to 3 seconds for it to pause again.

Inputs: action (required), thread_id.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 9 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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'.

    Related MCP Connectors

    Related MCP Servers