MCP ACS Debugger Server

How to use

You will run the MCP ACS Debugger Server as a local, stdio-based service that your MCP clients connect to. Start a debug session by launching the server through the supported command, then request actions such as starting a process, setting breakpoints, continuing execution, inspecting variables, and stepping through code. Your MCP client can manage multiple sessions in parallel, isolate their state, and perform advanced operations like hang detection and profiling. Use this flow to have an AI agent drive debugging tasks end-to-end: start the target process, place breakpoints, run until pausing, inspect state, and iterate until issues are resolved.

How to install

Prerequisites you need before installation are a modern Node.js runtime and npm, plus a runtime environment suitable for your platform.

# Install the MCP Debugger Server globally
npm install -g @ai-capabilities-suite/mcp-debugger-server

# Verify installation (shows version information)
ts-mcp-server --version

Configuration and how to run

Configure your MCP client to connect to the debugger using the standard stdio integration. The server is started as a local process that the MCP client talks to via JSON-RPC over stdio. In common configurations you specify the command to start the debugger server and any arguments or environment variables your environment needs.

{
  "mcpServers": {
    "debugger": {
      "type": "stdio",
      "name": "debugger",
      "command": "ts-mcp-server",
      "args": []
    }
  }
}

Environment variables to customize behavior

The server supports optional environment variables to control logging, timeouts, authentication, rate limiting, and auditing. You can enable debug logging, set operation timeouts, require authentication tokens, and tailor auditing behavior.

# Enable verbose debug logging
DEBUG=mcp:*

# Set a custom timeout in milliseconds for debugger actions
MCP_DEBUGGER_TIMEOUT=60000

# Require an authentication token for requests
MCP_DEBUGGER_AUTH_TOKEN=your-secret-token

# Configure rate limiting (max requests per minute)
MCP_DEBUGGER_RATE_LIMIT=100

# Enable audit logging for debugging operations
MCP_DEBUGGER_AUDIT_LOG=true

Internal tooling and integration notes

The server integrates with Node.js Inspector Protocol to drive the target processes, and it exposes a suite of debugging tools that you can exercise through your MCP client. Use the provided tooling to start sessions, set and manage breakpoints, inspect variables, and profile performance.

# Example: run the debugger to verify it launches correctly (non-impactful check)
ts-mcp-server --version

Troubleshooting quick tips

If you encounter issues during setup or debugging, verify the following common points: Node.js version compatibility (>= 18), that the MCP server process starts without errors, and that your MCP client connects to the correct stdio channel. For debugging many sessions, monitor resource usage and consider limiting concurrent sessions if you observe increased memory consumption.

Common usage scenarios

Use cases include starting a Node.js process under debug, setting breakpoints in TypeScript via source maps, continuing to breakpoints, evaluating expressions, inspecting stacks, and performing memory or CPU profiling to identify issues. The server supports multiple sessions, so you can debug different targets or test suites in parallel with isolation.

Notes

Keep your tooling up to date to benefit from improved source map handling, better error messages, and enhanced performance. If you are integrating with CI/CD, consider using hang detection and automated test debugging to catch issues early in the pipeline.

Security and production considerations

This server includes enterprise-grade features like authentication, rate limiting, audit logging, and circuit breakers to support production usage. Treat debugging in production with care, apply appropriate access controls, and use audit logs to monitor who executes which debugging actions.

Notes on multi-language and extensions

TypeScript debugging benefits from source maps, and you can attach to JavaScript/TypeScript code while leveraging source maps to map breakpoints to original TypeScript sources.

debugger_start

Start a new debug session for a Node.js process with optional arguments, working directory, and timeout.

debugger_stop_session

Terminate a running debug session and release associated resources.

debugger_set_breakpoint

Create a breakpoint at a given file and line with an optional condition.

debugger_remove_breakpoint

Remove a breakpoint by its identifier from a session.

debugger_toggle_breakpoint

Enable or disable a breakpoint without removing it.

debugger_list_breakpoints

Retrieve all breakpoints currently set for a session.

debugger_continue

Resume execution until the next breakpoint or end of program.

debugger_step_over

Execute the current line and pause at the next line in the same scope.

debugger_step_into

Enter the next function call and pause at the first line inside.

debugger_step_out

Run to the end of the current function and pause at the caller.

debugger_pause

Pause a running debug session.

debugger_inspect

Evaluate an expression in the current execution context.

debugger_get_local_variables

Get all local variables in the current scope.

debugger_get_global_variables

Get global variables accessible from the current scope.

debugger_inspect_object

Inspect an object's properties with nested resolution.

debugger_add_watch

Add an expression to the watch list.

debugger_remove_watch

Remove a watch expression by its ID.

debugger_get_watches

Get all watched expressions with their current values.

debugger_get_stack

Get the current call stack with function names and locations.

debugger_switch_stack_frame

Switch the active frame to a specific stack frame index.

debugger_detect_hang

Run a command and detect potential hangs with a timeout and sample interval.