Setting breakpoints and inspecting variables in a Node.js application
Power your agent
คำสั่งของผู้เผยแพร่เอง ไม่ใช่เอนด์พอยต์ของ PlugMCP
Host a copy with our keys and logs.
npx -y @ai-capabilities-suite/[email protected]Claude Code ไม่มีลิงก์ติดตั้งสำหรับคำสั่งแบบโลคัล ให้คัดลอกคำสั่งด้านล่างแล้วรันในเทอร์มินัล
claude mcp add io.github.digital-defiance-mcp-debugger -- npx -y @ai-capabilities-suite/mcp-debugger-server@1.1.8รันในเทอร์มินัล
{ "mcpServers": { "io.github.digital-defiance-mcp-debugger": { "command": "npx", "args": [ "-y", "@ai-capabilities-suite/[email protected]" ] } }}claude_desktop_config.json
URL แบบรีโมตหรือคำสั่งบนเครื่องของคุณ? การติดตั้งสองแบบต่างกันอย่างไร
รันบน PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
เปิดThis package is now maintained in its own repository: https://github.com/Digital-Defiance/mcp-debugger-server
This repository is part of the AI Capabilitites Suite on GitHub.
An enterprise-grade Model Context Protocol (MCP) server that provides comprehensive debugging capabilities for Node.js and JavaScript applications via Chrome DevTools Protocol. This server enables AI agents (Kiro, Amazon Q, GitHub Copilot) to interactively debug Node.js code with 25+ specialized tools, offering everything from basic breakpoint management to advanced CPU/memory profiling and hang detection. For multi-language debugging (Python, Java, Go, etc.), use the VS Code extension which leverages Debug Adapter Protocol.
# Install globally
npm install -g @ai-capabilities-suite/mcp-debugger-server
# Verify installation
ts-mcp-server --version
# Run directly without installing
npx @ai-capabilities-suite/mcp-debugger-server
# Pull and run the Docker image
docker pull digitaldefiance/mcp-debugger-server:latest
docker run -d --name mcp-debugger digitaldefiance/mcp-debugger-server:latest
# Or use docker-compose (see DOCKER-DEPLOYMENT.md)
docker-compose up -d
# Clone the repository
git clone https://github.com/digital-defiance/ai-capabilities-suite.git
cd ai-capabilities-suite
# Install dependencies
npm install
# Build the packages
npx nx build @ai-capabilities-suite/mcp-debugger-core
npx nx build @ai-capabilities-suite/mcp-debugger-server
# Run the server
node packages/mcp-debugger-server/dist/src/cli.js
Add to .kiro/settings/mcp.json:
{
"mcpServers": {
"debugger": {
"command": "ts-mcp-server",
"args": [],
"env": {
"NODE_ENV": "production"
},
"disabled": false,
"autoApprove": [
"debugger_start",
"debugger_set_breakpoint",
"debugger_continue",
"debugger_step_over",
"debugger_inspect",
"debugger_get_stack"
]
}
}
}
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"debugger": {
"command": "ts-mcp-server",
"args": []
}
}
}
Add to .vscode/settings.json:
{
"mcp.servers": {
"debugger": {
"command": "ts-mcp-server",
"args": [],
"enabled": true
}
}
}
Optional environment variables for advanced configuration:
# Enable debug logging
DEBUG=mcp:*
# Set custom timeout (milliseconds)
MCP_DEBUGGER_TIMEOUT=60000
# Enable authentication
MCP_DEBUGGER_AUTH_TOKEN=your-secret-token
# Enable rate limiting
MCP_DEBUGGER_RATE_LIMIT=100
# Enable audit logging
MCP_DEBUGGER_AUDIT_LOG=true
The MCP ACS Debugger Server provides 25 specialized tools organized into 8 categories:
debugger_startStart a new debug session with a Node.js process.
Parameters:
command (string, required): The command to execute (e.g., "node", "npm")args (string[], optional): Command arguments (e.g., ["test.js"])cwd (string, optional): Working directory for the processtimeout (number, optional): Timeout in milliseconds (default: 30000)Example:
{
"command": "node",
"args": ["app.js"],
"cwd": "/path/to/project",
"timeout": 30000
}
Response:
{
"status": "success",
"sessionId": "session-123",
"state": "paused",
"pid": 12345
}
debugger_stop_sessionStop a debug session and cleanup all resources.
Parameters:
sessionId (string, required): The debug session IDExample:
{
"sessionId": "session-123"
}
debugger_set_breakpointSet a breakpoint at a specific file and line number.
Parameters:
sessionId (string, required): The debug session IDfile (string, required): The file path (absolute or relative)line (number, required): The line number (1-indexed)condition (string, optional): Optional condition expression (e.g., "x > 10")Example:
{
"sessionId": "session-123",
"file": "/path/to/file.js",
"line": 42,
"condition": "count > 5"
}
debugger_remove_breakpointRemove a breakpoint from the session.
Parameters:
sessionId (string, required): The debug session IDbreakpointId (string, required): The breakpoint ID to removedebugger_toggle_breakpointToggle a breakpoint between enabled and disabled states.
Parameters:
sessionId (string, required): The debug session IDbreakpointId (string, required): The breakpoint ID to toggledebugger_list_breakpointsGet all breakpoints for a debug session.
Parameters:
sessionId (string, required): The debug session IDResponse:
{
"status": "success",
"breakpoints": [
{
"id": "bp-1",
"file": "/path/to/file.js",
"line": 42,
"condition": "x > 10",
"enabled": true,
"verified": true
}
]
}
debugger_continueResume execution until the next breakpoint or program termination.
Parameters:
sessionId (string, required): The debug session IDdebugger_step_overExecute the current line and pause at the next line in the same scope.
Parameters:
sessionId (string, required): The debug session IDdebugger_step_intoExecute the current line and pause at the first line inside any called function.
Parameters:
sessionId (string, required): The debug session IDdebugger_step_outExecute until the current function returns and pause at the calling location.
Parameters:
sessionId (string, required): The debug session IDdebugger_pausePause a running debug session.
Parameters:
sessionId (string, required): The debug session IDdebugger_inspectEvaluate a JavaScript expression in the current execution context.
Parameters:
sessionId (string, required): The debug session IDexpression (string, required): The JavaScript expression to evaluateExample:
{
"sessionId": "session-123",
"expression": "user.name + ' ' + user.age"
}
debugger_get_local_variablesGet all local variables in the current scope.
Parameters:
sessionId (string, required): The debug session IDdebugger_get_global_variablesGet global variables accessible from the current scope.
Parameters:
sessionId (string, required): The debug session IDdebugger_inspect_objectInspect an object's properties with nested resolution.
Parameters:
sessionId (string, required): The debug session IDobjectId (string, required): The object ID from a previous inspectionmaxDepth (number, optional): Maximum depth to traverse (default: 2)debugger_add_watchAdd an expression to the watch list.
Parameters:
sessionId (string, required): The debug session IDexpression (string, required): The expression to watchdebugger_remove_watchRemove an expression from the watch list.
Parameters:
sessionId (string, required): The debug session IDwatchId (string, required): The watch ID (expression) to removedebugger_get_watchesGet all watched expressions with their current values.
Parameters:
sessionId (string, required): The debug session IDdebugger_get_stackGet the current call stack with function names and file locations.
Parameters:
sessionId (string, required): The debug session IDResponse:
{
"status": "success",
"stack": [
{
"function": "myFunction",
"file": "/absolute/path/to/file.js",
"line": 42,
"column": 10
}
]
}
debugger_switch_stack_frameSwitch the execution context to a specific stack frame.
Parameters:
sessionId (string, required): The debug session IDframeIndex (number, required): The frame index (0 = top frame)debugger_detect_hangDetect if a process hangs or enters an infinite loop.
Parameters:
command (string, required): The command to executeargs (string[], optional): Command argumentscwd (string, optional): Working directorytimeout (number, required): Timeout in millisecondssampleInterval (number, optional): Sample interval for loop detection (default: 100ms)Example:
{
"command": "node",
"args": ["script.js"],
"timeout": 5000,
"sampleInterval": 100
}
Response (hung):
{
"status": "success",
"hung": true,
"location": "/path/to/file.js:42",
"stack": [...],
"message": "Process hung at /path/to/file.js:42",
"duration": 5000
}
Response (completed):
{
"status": "success",
"hung": false,
"completed": true,
"exitCode": 0,
"duration": 1234
}
npm install -g @ai-capabilities-suite/mcp-debugger-server
Add to your MCP configuration file (e.g., .kiro/settings/mcp.json):
{
"mcpServers": {
"debugger": {
"command": "ts-mcp-server",
"args": []
}
}
}
Ask your AI agent to debug your code:
"Debug my Node.js script app.js and set a breakpoint at line 42"
The AI agent will use the MCP ACS Debugger Server to:
// 1. Start a debug session
{
"tool": "debugger_start",
"args": {
"command": "node",
"args": ["my-script.js"]
}
}
// Returns: { sessionId: "session-123", state: "paused" }
// 2. Set a breakpoint
{
"tool": "debugger_set_breakpoint",
"args": {
"sessionId": "session-123",
"file": "/path/to/my-script.js",
"line": 10
}
}
// 3. Continue execution
{
"tool": "debugger_continue",
"args": {
"sessionId": "session-123"
}
}
// 4. When paused at breakpoint, inspect variables
{
"tool": "debugger_get_local_variables",
"args": {
"sessionId": "session-123"
}
}
// 5. Step through code
{
"tool": "debugger_step_over",
"args": {
"sessionId": "session-123"
}
}
// 6. Stop the session
{
"tool": "debugger_stop_session",
"args": {
"sessionId": "session-123"
}
}
// 1. Start debugging a Jest test
{
"tool": "debugger_start",
"args": {
"command": "node",
"args": ["node_modules/.bin/jest", "my-test.spec.js", "--runInBand"],
"timeout": 60000
}
}
// 2. Set breakpoint in test file
{
"tool": "debugger_set_breakpoint",
"args": {
"sessionId": "session-123",
"file": "/path/to/my-test.spec.js",
"line": 25
}
}
// 3. Continue to breakpoint
{
"tool": "debugger_continue",
"args": {
"sessionId": "session-123"
}
}
// 4. Inspect test variables
{
"tool": "debugger_inspect",
"args": {
"sessionId": "session-123",
"expression": "expect.getState()"
}
}
// Use hang detection to identify infinite loops
{
"tool": "debugger_detect_hang",
"args": {
"command": "node",
"args": ["potentially-hanging-script.js"],
"timeout": 5000,
"sampleInterval": 100
}
}
// Returns hang location and stack trace if hung
// TypeScript debugging works automatically with source maps
// 1. Ensure your tsconfig.json has "sourceMap": true
// 2. Start debugging the compiled JavaScript
{
"tool": "debugger_start",
"args": {
"command": "node",
"args": ["--enable-source-maps", "dist/app.js"]
}
}
// 3. Set breakpoints using TypeScript file paths
{
"tool": "debugger_set_breakpoint",
"args": {
"sessionId": "session-123",
"file": "/path/to/src/app.ts", // TypeScript source file
"line": 42
}
}
// The debugger automatically maps to the compiled JavaScript location
// 1. Start session and set breakpoint
// ... (as in Scenario 1)
// 2. Add watched variables
{
"tool": "debugger_add_watch",
"args": {
"sessionId": "session-123",
"expression": "user.balance"
}
}
// 3. Continue execution
{
"tool": "debugger_continue",
"args": {
"sessionId": "session-123"
}
}
// 4. Check watched variables at each pause
{
"tool": "debugger_get_watches",
"args": {
"sessionId": "session-123"
}
}
// Returns: { watches: [{ watchId: "user.balance", value: 100, changed: true, oldValue: 50, newValue: 100 }] }
Setting breakpoints and inspecting variables in a Node.js application
Detecting and diagnosing an infinite loop
Debugging TypeScript code with source map support
Note: Replace placeholder images with actual screenshots or animated GIFs demonstrating the debugger in action. See images/README.md for guidelines.
Symptoms: Error when trying to use a session ID Cause: The session ID is invalid or the session has been terminated Solution:
# Start a new debug session
{
"tool": "debugger_start",
"arguments": {
"command": "node",
"args": ["your-script.js"]
}
}
Symptoms: Cannot inspect variables or evaluate expressions Cause: Trying to inspect variables when the process is running Solution:
debugger_pause to pause execution immediatelySymptoms: Execution doesn't stop at the breakpoint Cause: Invalid breakpoint location or code path not executed Solution:
Verify the file path is correct (use absolute paths):
"file": "/absolute/path/to/your/file.js" // ✅ Good
"file": "file.js" // ❌ Avoid
Check that the line number has executable code (not comments or blank lines)
Verify the breakpoint is set and verified:
{
"tool": "debugger_list_breakpoints",
"arguments": { "sessionId": "your-session-id" }
}
Symptoms: Hang detection reports a hang when the script is running normally Cause: The timeout is too short for the script's normal execution time Solution:
{
"tool": "debugger_detect_hang",
"arguments": {
"command": "node",
"args": ["script.js"],
"timeout": 60000, // Increase timeout to 60 seconds
"sampleInterval": 200 // Increase sample interval
}
}
Symptoms: Breakpoints in .ts files don't pause execution Cause: Source maps are not enabled or not found Solution:
Ensure "sourceMap": true in tsconfig.json:
{
"compilerOptions": {
"sourceMap": true
}
}
Use --enable-source-maps flag when starting Node.js:
node --enable-source-maps dist/app.js
Verify .map files exist alongside compiled JavaScript:
ls dist/*.js.map
Symptoms: Module not found errors when starting the server Cause: The packages haven't been built or dependencies not installed Solution:
# Install dependencies
npm install
# Build the packages
npx nx build @ai-capabilities-suite/mcp-debugger-core
npx nx build @ai-capabilities-suite/mcp-debugger-server
# Or if installed globally, reinstall
npm install -g @ai-capabilities-suite/mcp-debugger-server
Symptoms: "Failed to connect to inspector" or WebSocket errors Cause: The Inspector Protocol failed to start Solution:
Ensure Node.js version is 18 or higher:
node --version # Should be >= 18.0.0
Check that no other debugger is attached to the process
Verify the process starts successfully:
node --inspect-brk your-script.js
# Should output: Debugger listening on ws://...
Symptoms: Server consumes excessive memory Cause: Too many concurrent sessions or large heap snapshots Solution:
Limit concurrent sessions
Stop unused sessions:
{
"tool": "debugger_stop_session",
"arguments": { "sessionId": "session-id" }
}
Configure resource limits (see Environment Variables section)
Symptoms: Debugging operations are slow Cause: Large objects, deep inspection, or many breakpoints Solution:
Limit object inspection depth:
{
"tool": "debugger_inspect_object",
"arguments": {
"sessionId": "session-id",
"objectId": "obj-id",
"maxDepth": 2 // Limit depth
}
}
Use conditional breakpoints to reduce pauses
Remove unnecessary breakpoints
If you encounter issues not covered here:
DEBUG=mcp:*node --version)ts-mcp-server --version)Enable AI agents to autonomously debug your code:
Integrate debugging into your CI/CD pipeline:
Debug production-like environments safely:
Help developers learn debugging techniques:
Identify and fix performance issues:
The server returns structured error responses with the following codes:
npx nx test @ai-capabilities-suite/mcp-core
npx nx test @ai-capabilities-suite/mcp-server
npx nx test @ai-capabilities-suite/mcp-server --testPathPattern=e2e --testTimeout=60000
node packages/mcp-server/test-mcp-manual.js
See TESTING.md for comprehensive testing documentation.
The MCP ACS Debugger Server is built on enterprise-grade technologies:
┌─────────────────────────────────────────────────────────────┐
│ AI Agent Layer │
│ (Kiro, Amazon Q, GitHub Copilot, Claude Desktop) │
└────────────────────────┬────────────────────────────────────┘
│ MCP Protocol (stdio/JSON-RPC)
│
┌────────────────────────▼────────────────────────────────────┐
│ MCP ACS Debugger Server │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Session │ │ Breakpoint │ │ Variable │ │
│ │ Manager │ │ Manager │ │ Inspector │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Hang │ │ CPU │ │ Memory │ │
│ │ Detector │ │ Profiler │ │ Profiler │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Source │ │ Audit │ │ Metrics │ │
│ │ Map Manager │ │ Logger │ │ Collector │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└────────────────────────┬────────────────────────────────────┘
│ Inspector Protocol (CDP/WebSocket)
│
┌────────────────────────▼────────────────────────────────────┐
│ Node.js Inspector │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Debugger │ │ Runtime │ │ Profiler │ │
│ │ Domain │ │ Domain │ │ Domain │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└────────────────────────┬────────────────────────────────────┘
│
┌────────────────────────▼────────────────────────────────────┐
│ Target Node.js Process │
│ (Application, Test Runner, etc.) │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ Security Layer │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Auth │ │ Rate │ │ Data │ │
│ │ Manager │ │ Limiter │ │ Masker │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Session │ │ Audit │ │ Circuit │ │
│ │ Timeout │ │ Logger │ │ Breaker │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────┘
Performance metrics on a MacBook Pro (M1, 16GB RAM):
Typical resource consumption:
Contributions are welcome! Please follow these guidelines:
If you're a maintainer publishing updates:
This project builds upon excellent open-source technologies:
Special thanks to:
MIT License - See LICENSE file for details
Copyright (c) 2024 Digital Defiance
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Made with ❤️ by Digital Defiance
Q: What is the Model Context Protocol (MCP)? A: MCP is a protocol that enables AI agents to interact with external tools and services. The MCP ACS Debugger Server implements MCP to provide debugging capabilities to AI agents.
Q: Which AI agents are supported? A: The server works with any MCP-compatible AI agent, including:
Q: Can I use this for production debugging? A: Yes! The server includes enterprise features like authentication, rate limiting, audit logging, and circuit breakers specifically for production use. However, always test in a staging environment first.
Q: Is this free to use? A: Yes, the MCP ACS Debugger Server is open source under the MIT license and free for both personal and commercial use.
Q: What Node.js versions are supported? A: Node.js >= 18.0.0 is required. We recommend using the latest LTS version.
Q: Does this work with TypeScript? A: Yes! Full TypeScript support with source maps. Set breakpoints in .ts files and inspect variables with their original TypeScript names.
Q: Can I debug remote processes? A: The server connects to local Node.js processes via the Inspector Protocol. For remote debugging, use SSH tunneling or deploy the server on the remote machine.
Q: How many concurrent debug sessions can I run? A: The server supports 100+ concurrent sessions. Each session is isolated and doesn't interfere with others.
Q: Does this work with Docker containers? A: Yes! We provide official Docker images. See DOCKER-DEPLOYMENT.md for details.
Q: Why isn't my breakpoint hitting? A: Common causes:
Q: How do I debug a specific test? A: Start a debug session with your test runner:
{
"tool": "debugger_start",
"arguments": {
"command": "node",
"args": ["node_modules/.bin/jest", "my-test.spec.js", "--runInBand"]
}
}
Q: Can I debug asynchronous code? A: Yes! The debugger fully supports async/await, Promises, and callbacks. Set breakpoints in async functions and step through them normally.
Q: How do I detect memory leaks? A: Use the memory profiling tools:
Q: Will debugging slow down my application? A: Yes, debugging adds overhead. Expect 2-5x slowdown when actively debugging. Use conditional breakpoints and disable unnecessary breakpoints to minimize impact.
Q: How much memory does the server use? A: Base memory usage is 50-100MB, plus 10-20MB per active debug session.
Q: Can I use this in CI/CD pipelines? A: Yes! The server is designed for automation. Use hang detection and test debugging in your CI/CD pipeline to catch issues early.
Q: Is it safe to use in production? A: The server includes enterprise security features (authentication, rate limiting, audit logging), but debugging in production should be done carefully and only when necessary.
Q: How is sensitive data protected? A: The server includes automatic PII masking for common patterns (emails, SSNs, credit cards). Configure additional masking rules as needed.
Q: Can I restrict which operations are allowed? A: Yes! Use authentication and configure allowed operations per user/token. See the Security section in the documentation.
Q: How do I integrate with VS Code? A: See VSCODE-INTEGRATION.md for detailed integration instructions.
Q: Can I use this with GitHub Copilot? A: Yes! GitHub Copilot can use MCP servers. Configure the server in your Copilot settings.
Q: Does this work with Mocha/Jest/Vitest? A: Yes! The server has built-in support for all major test frameworks. Just start a debug session with your test runner command.
We welcome contributions! See CONTRIBUTING.md for guidelines.
Support the project:
Release Date: December 2025
New Features:
Bug Fixes:
Performance:
Release Date: November 2024
New Features:
Improvements:
Release Date: November 2024
New Features:
Improvements:
Release Date: October 2024
Initial Release:
Want to influence the roadmap? Share your ideas
Node.js and TypeScript debugging with 25+ tools for AI agents
{ "mcpServers": { "io.github.digital-defiance-mcp-debugger": { "command": "npx", "args": [ "-y", "@ai-capabilities-suite/[email protected]" ] } }}เครื่องมือ
ยังไม่มีรายการเครื่องมือ เซิร์ฟเวอร์แบบรีโมตจะได้รายการหลังการตรวจสอบสถานะครั้งแรก
FAQ
คัดลอกคอนฟิก stdio สำหรับ Cursor, Claude Desktop, Claude Code หรือ VS Code ได้ในหน้านี้ คอนฟิกนี้ใช้การติดตั้งของผู้เผยแพร่ ไม่ใช่พร็อกซีของ PlugMCP
ระเบียนนี้ไม่ได้ระบุตัวแปรสภาพแวดล้อมที่จำเป็น
MCP Debugger ทำงานแบบโลคัลผ่าน stdio
ตรวจสอบล่าสุดเมื่อ 2026-11-09 Node.js and TypeScript debugging with 25+ tools for AI agents