diff --git a/servers/ts-mcp-debugger/readme.md b/servers/ts-mcp-debugger/readme.md new file mode 100644 index 000000000..2a4fa652f --- /dev/null +++ b/servers/ts-mcp-debugger/readme.md @@ -0,0 +1,165 @@ +# TypeScript MCP Debugger + +Enterprise-grade debugging for Node.js and TypeScript applications with 25+ specialized tools. + +## Documentation + +For complete documentation, visit: +- **Main Documentation**: https://github.com/digital-defiance/ai-capabilities-suite/tree/main/packages/mcp-debugger-server#readme +- **Tool Reference**: https://github.com/digital-defiance/ai-capabilities-suite/blob/main/packages/mcp-debugger-server/TOOL-REFERENCE.md +- **AI Agent Integration**: https://github.com/digital-defiance/ai-capabilities-suite/blob/main/packages/mcp-debugger-server/AI-AGENT-INTEGRATION.md +- **VS Code Integration**: https://github.com/digital-defiance/ai-capabilities-suite/blob/main/packages/mcp-debugger-server/VSCODE-INTEGRATION.md + +## Features + +### Core Debugging +- **Breakpoint Management**: Set, remove, toggle, and list breakpoints with conditions, hit counts, and logpoints +- **Execution Control**: Continue, step over/into/out, and pause execution +- **Variable Inspection**: Inspect local/global variables, evaluate expressions, watch variables +- **Call Stack Navigation**: View and navigate stack frames with context switching + +### Advanced Features +- **Hang Detection**: Detect infinite loops and hanging processes +- **TypeScript Support**: Full source map support for TypeScript debugging +- **Performance Profiling**: CPU profiling, memory profiling, heap snapshots +- **Test Framework Integration**: Debug Jest, Mocha, and Vitest tests + +### Enterprise Features +- **Observability**: Structured logging, metrics, health checks, Prometheus export +- **Security**: Authentication, rate limiting, data masking, audit logging +- **Production Ready**: Circuit breakers, retry logic, graceful shutdown, resource limits + +## Quick Start + +### Using Docker Desktop MCP Toolkit + +1. Enable the server in Docker Desktop's MCP Toolkit +2. Configure environment variables (optional): + - `NODE_ENV`: production (default) or development + - `LOG_LEVEL`: info (default), debug, warn, or error +3. Start using the debugging tools in your AI agent + +### Using Docker CLI + +```bash +docker run -d \ + --name mcp-debugger \ + -e NODE_ENV=production \ + -e LOG_LEVEL=info \ + digidefiance/mcp-debugger-server:latest +``` + +### Using Docker Compose + +```yaml +version: '3.8' +services: + mcp-debugger: + image: digidefiance/mcp-debugger-server:latest + environment: + - NODE_ENV=production + - LOG_LEVEL=info + restart: unless-stopped +``` + +## Available Tools + +The server provides 25 debugging tools: + +### Session Management +- `debugger_start` - Start a new debug session +- `debugger_stop_session` - Stop a debug session + +### Breakpoints +- `debugger_set_breakpoint` - Set a breakpoint with optional condition +- `debugger_remove_breakpoint` - Remove a breakpoint +- `debugger_toggle_breakpoint` - Toggle breakpoint enabled/disabled +- `debugger_list_breakpoints` - List all breakpoints + +### Execution Control +- `debugger_continue` - Resume execution +- `debugger_step_over` - Step over current line +- `debugger_step_into` - Step into function call +- `debugger_step_out` - Step out of current function +- `debugger_pause` - Pause execution + +### Variable Inspection +- `debugger_inspect` - Evaluate an expression +- `debugger_get_local_variables` - Get local variables +- `debugger_get_global_variables` - Get global variables +- `debugger_inspect_object` - Inspect object properties +- `debugger_add_watch` - Add a watch expression +- `debugger_remove_watch` - Remove a watch expression +- `debugger_get_watches` - Get all watched expressions + +### Call Stack +- `debugger_get_stack` - Get current call stack +- `debugger_switch_stack_frame` - Switch to a different stack frame + +### Advanced Features +- `debugger_detect_hang` - Detect hanging processes and infinite loops +- `debugger_start_cpu_profile` - Start CPU profiling +- `debugger_stop_cpu_profile` - Stop CPU profiling and get results +- `debugger_take_heap_snapshot` - Take a heap snapshot +- `debugger_get_performance_metrics` - Get performance metrics + +## Use Cases + +### Debugging Failing Tests +``` +1. Start debug session with test command +2. Set breakpoints in test code +3. Step through execution to find the issue +4. Inspect variables to understand state +5. Fix the bug and verify +``` + +### Performance Analysis +``` +1. Start debug session with your application +2. Start CPU profiling +3. Run performance-critical code +4. Stop profiling and analyze results +5. Identify bottlenecks and optimize +``` + +### Detecting Infinite Loops +``` +1. Use debugger_detect_hang with your code +2. Configure timeout and sample interval +3. Get hang location and call stack +4. Fix the infinite loop +``` + +### TypeScript Debugging +``` +1. Start debug session with TypeScript code +2. Set breakpoints in .ts files (not .js) +3. Source maps automatically map locations +4. Inspect variables with TypeScript names +5. Debug with original source code +``` + +## System Requirements + +- **Node.js**: >= 18.0.0 +- **Docker**: Latest version recommended +- **Memory**: Minimum 512MB, recommended 1GB+ +- **CPU**: x64 or arm64 architecture + +## Support + +- **GitHub Issues**: https://github.com/digital-defiance/ai-capabilities-suite/issues +- **Email**: info@digitaldefiance.org +- **Documentation**: https://github.com/digital-defiance/ai-capabilities-suite/tree/main/packages/mcp-debugger-server + +## License + +MIT License - See [LICENSE](https://github.com/digital-defiance/ai-capabilities-suite/blob/main/LICENSE) for details. + +## Author + +**Digital Defiance** +- Website: https://digitaldefiance.org +- GitHub: https://github.com/digital-defiance +- Email: info@digitaldefiance.org diff --git a/servers/ts-mcp-debugger/server.yaml b/servers/ts-mcp-debugger/server.yaml new file mode 100644 index 000000000..1b21870b1 --- /dev/null +++ b/servers/ts-mcp-debugger/server.yaml @@ -0,0 +1,39 @@ +name: ts-mcp-debugger +image: mcp/mcp-debugger-server +type: server +meta: + category: debugging + tags: + - debugging + - development-tools + - typescript + - nodejs + - profiling + - testing +about: + title: ACS TypeScript Debugger + description: Enterprise-grade debugging for Node.js/TypeScript with 25+ tools including breakpoints, profiling, hang detection, and source map support + icon: https://raw.githubusercontent.com/Digital-Defiance/vscode-mcp-debugger/main/images/icon.png +source: + project: https://github.com/digital-defiance/mcp-debugger-server + commit: ec0f06a99c9ec14acf164153a3868042bc2eddb7 +config: + description: Configure the MCP Debugger Server for your debugging needs + env: + - name: NODE_ENV + example: production + value: "{{ts-mcp-debugger.node_env}}" + - name: LOG_LEVEL + example: info + value: "{{ts-mcp-debugger.log_level}}" + parameters: + type: object + properties: + node_env: + type: string + default: production + description: Node.js environment (production, development) + log_level: + type: string + default: info + description: Logging level (debug, info, warn, error) diff --git a/servers/ts-mcp-debugger/tools.json b/servers/ts-mcp-debugger/tools.json new file mode 100644 index 000000000..a3f3e887b --- /dev/null +++ b/servers/ts-mcp-debugger/tools.json @@ -0,0 +1,362 @@ +[ + { + "name": "debugger_start", + "description": "Start a new debug session with a Node.js process", + "arguments": [ + { + "name": "command", + "type": "string", + "desc": "Command to execute (e.g., 'node', 'npm')" + }, + { + "name": "args", + "type": "array", + "desc": "Command arguments" + }, + { + "name": "cwd", + "type": "string", + "desc": "Working directory for the process" + }, + { + "name": "timeout", + "type": "number", + "desc": "Maximum execution time in milliseconds" + } + ] + }, + { + "name": "debugger_stop_session", + "description": "Stop a debug session and cleanup all resources", + "arguments": [ + { + "name": "sessionId", + "type": "string", + "desc": "ID of the debug session to stop" + } + ] + }, + { + "name": "debugger_set_breakpoint", + "description": "Set a breakpoint at a specific file and line number with optional condition", + "arguments": [ + { + "name": "sessionId", + "type": "string", + "desc": "ID of the debug session" + }, + { + "name": "file", + "type": "string", + "desc": "File path where to set the breakpoint" + }, + { + "name": "line", + "type": "number", + "desc": "Line number for the breakpoint" + }, + { + "name": "condition", + "type": "string", + "desc": "Optional condition expression" + } + ] + }, + { + "name": "debugger_remove_breakpoint", + "description": "Remove a breakpoint from the session", + "arguments": [ + { + "name": "sessionId", + "type": "string", + "desc": "ID of the debug session" + }, + { + "name": "breakpointId", + "type": "string", + "desc": "ID of the breakpoint to remove" + } + ] + }, + { + "name": "debugger_toggle_breakpoint", + "description": "Toggle a breakpoint between enabled and disabled states", + "arguments": [ + { + "name": "sessionId", + "type": "string", + "desc": "ID of the debug session" + }, + { + "name": "breakpointId", + "type": "string", + "desc": "ID of the breakpoint to toggle" + } + ] + }, + { + "name": "debugger_list_breakpoints", + "description": "Get all breakpoints for a debug session", + "arguments": [ + { + "name": "sessionId", + "type": "string", + "desc": "ID of the debug session" + } + ] + }, + { + "name": "debugger_continue", + "description": "Resume execution until the next breakpoint or program termination", + "arguments": [ + { + "name": "sessionId", + "type": "string", + "desc": "ID of the debug session" + } + ] + }, + { + "name": "debugger_step_over", + "description": "Execute the current line and pause at the next line in the same scope", + "arguments": [ + { + "name": "sessionId", + "type": "string", + "desc": "ID of the debug session" + } + ] + }, + { + "name": "debugger_step_into", + "description": "Execute the current line and pause at the first line inside any called function", + "arguments": [ + { + "name": "sessionId", + "type": "string", + "desc": "ID of the debug session" + } + ] + }, + { + "name": "debugger_step_out", + "description": "Execute until the current function returns and pause at the calling location", + "arguments": [ + { + "name": "sessionId", + "type": "string", + "desc": "ID of the debug session" + } + ] + }, + { + "name": "debugger_pause", + "description": "Pause a running debug session", + "arguments": [ + { + "name": "sessionId", + "type": "string", + "desc": "ID of the debug session" + } + ] + }, + { + "name": "debugger_inspect", + "description": "Evaluate a JavaScript expression in the current execution context", + "arguments": [ + { + "name": "sessionId", + "type": "string", + "desc": "ID of the debug session" + }, + { + "name": "expression", + "type": "string", + "desc": "JavaScript expression to evaluate" + } + ] + }, + { + "name": "debugger_get_local_variables", + "description": "Get all local variables in the current scope", + "arguments": [ + { + "name": "sessionId", + "type": "string", + "desc": "ID of the debug session" + } + ] + }, + { + "name": "debugger_get_global_variables", + "description": "Get global variables accessible from the current scope", + "arguments": [ + { + "name": "sessionId", + "type": "string", + "desc": "ID of the debug session" + } + ] + }, + { + "name": "debugger_inspect_object", + "description": "Inspect an object's properties with nested resolution", + "arguments": [ + { + "name": "sessionId", + "type": "string", + "desc": "ID of the debug session" + }, + { + "name": "objectId", + "type": "string", + "desc": "Object reference ID to inspect" + }, + { + "name": "depth", + "type": "number", + "desc": "Maximum depth for nested object inspection" + } + ] + }, + { + "name": "debugger_add_watch", + "description": "Add an expression to the watch list", + "arguments": [ + { + "name": "sessionId", + "type": "string", + "desc": "ID of the debug session" + }, + { + "name": "expression", + "type": "string", + "desc": "Expression to watch" + } + ] + }, + { + "name": "debugger_remove_watch", + "description": "Remove an expression from the watch list", + "arguments": [ + { + "name": "sessionId", + "type": "string", + "desc": "ID of the debug session" + }, + { + "name": "watchId", + "type": "string", + "desc": "ID of the watch to remove" + } + ] + }, + { + "name": "debugger_get_watches", + "description": "Get all watched expressions with their current values", + "arguments": [ + { + "name": "sessionId", + "type": "string", + "desc": "ID of the debug session" + } + ] + }, + { + "name": "debugger_get_stack", + "description": "Get the current call stack with function names and file locations", + "arguments": [ + { + "name": "sessionId", + "type": "string", + "desc": "ID of the debug session" + } + ] + }, + { + "name": "debugger_switch_stack_frame", + "description": "Switch the execution context to a specific stack frame", + "arguments": [ + { + "name": "sessionId", + "type": "string", + "desc": "ID of the debug session" + }, + { + "name": "frameIndex", + "type": "number", + "desc": "Index of the stack frame to switch to" + } + ] + }, + { + "name": "debugger_detect_hang", + "description": "Detect if a process hangs or enters an infinite loop", + "arguments": [ + { + "name": "command", + "type": "string", + "desc": "Command to execute" + }, + { + "name": "args", + "type": "array", + "desc": "Command arguments" + }, + { + "name": "timeout", + "type": "number", + "desc": "Maximum execution time in milliseconds" + }, + { + "name": "sampleInterval", + "type": "number", + "desc": "Interval for sampling execution location in milliseconds" + } + ] + }, + { + "name": "debugger_start_cpu_profile", + "description": "Start CPU profiling for performance analysis", + "arguments": [ + { + "name": "sessionId", + "type": "string", + "desc": "ID of the debug session" + } + ] + }, + { + "name": "debugger_stop_cpu_profile", + "description": "Stop CPU profiling and get profile data", + "arguments": [ + { + "name": "sessionId", + "type": "string", + "desc": "ID of the debug session" + } + ] + }, + { + "name": "debugger_take_heap_snapshot", + "description": "Take a heap snapshot for memory analysis", + "arguments": [ + { + "name": "sessionId", + "type": "string", + "desc": "ID of the debug session" + } + ] + }, + { + "name": "debugger_get_performance_metrics", + "description": "Get performance metrics for the debug session", + "arguments": [ + { + "name": "sessionId", + "type": "string", + "desc": "ID of the debug session" + } + ] + } +]