@ai-capabilities-suite/mcp-debugger-server/TOOL-REFERENCE.md

Enterprise-grade MCP server providing advanced debugging capabilities for Node.js and TypeScript applications. Features 25+ debugging tools including breakpoints, variable inspection, execution control, CPU/memory profiling, hang detection, source map sup

# MCP Debugger Server - Tool Reference

Complete reference documentation for all 21 MCP debugging tools with schemas, examples, and debugging scenarios.

## Table of Contents

- [Session Management](#session-management)
- [Breakpoint Management](#breakpoint-management)
- [Execution Control](#execution-control)
- [Variable Inspection](#variable-inspection)
- [Variable Watching](#variable-watching)
- [Call Stack Navigation](#call-stack-navigation)
- [Hang Detection](#hang-detection)
- [Debugging Scenarios](#debugging-scenarios)
- [Error Codes Reference](#error-codes-reference)

## Session Management

### 1. debugger_start

Start a new debug session with a Node.js process. The process will be paused at the start.

**Schema:**
```json
{
  "name": "debugger_start",
  "description": "Start a new debug session with a Node.js process. The process will be paused at the start.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "command": {
        "type": "string",
        "description": "The command to execute (e.g., 'node', 'npm')"
      },
      "args": {
        "type": "array",
        "items": { "type": "string" },
        "description": "Command arguments (e.g., ['test.js'])"
      },
      "cwd": {
        "type": "string",
        "description": "Working directory for the process"
      },
      "timeout": {
        "type": "number",
        "description": "Timeout in milliseconds (default: 30000)"
      }
    },
    "required": ["command"]
  }
}
```

**Parameters:**
- `command` (string, required): The command to execute
- `args` (string[], optional): Command arguments
- `cwd` (string, optional): Working directory
- `timeout` (number, optional): Timeout in milliseconds (default: 30000)

**Example Request:**
```json
{
  "command": "node",
  "args": ["src/app.js"],
  "cwd": "/path/to/project",
  "timeout": 30000
}
```

**Example Response (Success):**
```json
{
  "status": "success",
  "sessionId": "session-abc123",
  "state": "paused",
  "pid": 12345
}
```

**Example Response (Error):**
```json
{
  "status": "error",
  "code": "SESSION_START_FAILED",
  "message": "Failed to spawn process: ENOENT"
}
```

**Usage Notes:**
- The process starts in a paused state at the first line
- Store the returned `sessionId` for all subsequent operations
- Use absolute paths for file arguments when possible
- Set appropriate timeouts based on expected execution time
- The process will have the Inspector Protocol attached

**Requirements:** 2.1, 9.1


---

### 2. debugger_stop_session

Stop a debug session, cleanup all resources, and kill the process if still running.

**Schema:**
```json
{
  "name": "debugger_stop_session",
  "description": "Stop a debug session, cleanup all resources, and kill the process if still running.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "sessionId": {
        "type": "string",
        "description": "The debug session ID"
      }
    },
    "required": ["sessionId"]
  }
}
```

**Parameters:**
- `sessionId` (string, required): The debug session ID

**Example Request:**
```json
{
  "sessionId": "session-abc123"
}
```

**Example Response (Success):**
```json
{
  "status": "success",
  "sessionId": "session-abc123",
  "stopped": true
}
```

**Usage Notes:**
- Always call this when done debugging to prevent resource leaks
- Safe to call even if the process has already terminated
- Removes all breakpoints and disconnects the inspector
- Kills the process if it's still running

**Requirements:** 8.2, 9.1

---

## Breakpoint Management


### 3. debugger_set_breakpoint

Set a breakpoint at a specific file and line number with optional condition.

**Parameters:** `sessionId` (required), `file` (required), `line` (required), `condition` (optional)

**Example:** `{"sessionId": "session-123", "file": "/path/to/file.js", "line": 42, "condition": "x > 10"}`

**Response:** Returns breakpoint ID, file, line, condition, enabled status, and verification status

**Requirements:** 1.1, 1.2, 9.1

### 4. debugger_remove_breakpoint

Remove a breakpoint from the session.

**Parameters:** `sessionId` (required), `breakpointId` (required)

**Requirements:** 1.4, 9.1

### 5. debugger_toggle_breakpoint

Toggle a breakpoint between enabled and disabled states.

**Parameters:** `sessionId` (required), `breakpointId` (required)

**Requirements:** 1.5, 9.1

### 6. debugger_list_breakpoints

Get all breakpoints for a debug session with their properties.

**Parameters:** `sessionId` (required)

**Response:** Array of breakpoints with id, file, line, condition, enabled, and verified status

**Requirements:** 1.3, 9.1

---

## Execution Control

### 7. debugger_continue

Resume execution until the next breakpoint or program termination.

**Parameters:** `sessionId` (required)

**Requirements:** 2.2, 9.1

### 8. debugger_step_over

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

**Parameters:** `sessionId` (required)

**Response:** Returns new state and location

**Requirements:** 2.3, 9.1

### 9. debugger_step_into

Execute the current line and pause at the first line inside any called function.

**Parameters:** `sessionId` (required)

**Requirements:** 2.4, 9.1

### 10. debugger_step_out

Execute until the current function returns and pause at the calling location.

**Parameters:** `sessionId` (required)

**Requirements:** 2.5, 9.1

### 11. debugger_pause

Pause a running debug session and return the current execution location.

**Parameters:** `sessionId` (required)

**Requirements:** 2.6, 9.1

---

## Variable Inspection

### 12. debugger_inspect

Evaluate a JavaScript expression in the current execution context.

**Parameters:** `sessionId` (required), `expression` (required)

**Example:** `{"sessionId": "session-123", "expression": "user.name + ' ' + user.age"}`

**Response:** Returns value, type, and objectId (if object)

**Requirements:** 3.4, 9.1, 9.3

### 13. debugger_get_local_variables

Get all local variables in the current scope with names, values, and types.

**Parameters:** `sessionId` (required)

**Requirements:** 3.1, 9.1, 9.3

### 14. debugger_get_global_variables

Get global variables accessible from the current scope.

**Parameters:** `sessionId` (required)

**Requirements:** 3.2, 9.1, 9.3

### 15. debugger_inspect_object

Inspect an object's properties with nested resolution up to specified depth.

**Parameters:** `sessionId` (required), `objectId` (required), `maxDepth` (optional, default: 2)

**Requirements:** 3.3, 9.1, 9.3

---

## Variable Watching

### 16. debugger_add_watch

Add an expression to the watch list for automatic evaluation on each pause.

**Parameters:** `sessionId` (required), `expression` (required)

**Requirements:** 3.5, 9.1

### 17. debugger_remove_watch

Remove an expression from the watch list.

**Parameters:** `sessionId` (required), `watchId` (required)

**Requirements:** 3.5, 9.1

### 18. debugger_get_watches

Get all watched expressions with current values and change detection.

**Parameters:** `sessionId` (required)

**Response:** Array of watches with watchId, expression, value, changed flag, oldValue, newValue

**Requirements:** 3.5, 9.1

---

## Call Stack Navigation

### 19. debugger_get_stack

Get the current call stack with function names, file locations (absolute paths), and line numbers.

**Parameters:** `sessionId` (required)

**Response:** Array of stack frames with function, file, line, column

**Requirements:** 4.1, 9.1, 9.4

### 20. debugger_switch_stack_frame

Switch the execution context to a specific stack frame by index (0 = top frame).

**Parameters:** `sessionId` (required), `frameIndex` (required)

**Requirements:** 4.2, 9.1

---

## Hang Detection

### 21. debugger_detect_hang

Detect if a process hangs or enters an infinite loop.

**Parameters:** `command` (required), `args` (optional), `cwd` (optional), `timeout` (required), `sampleInterval` (optional, default: 100)

**Example:** `{"command": "node", "args": ["script.js"], "timeout": 5000, "sampleInterval": 100}`

**Response (Hung):** `{"hung": true, "location": "/path/file.js:42", "stack": [...], "message": "...", "duration": 5000}`

**Response (Completed):** `{"hung": false, "completed": true, "exitCode": 0, "duration": 1234}`

**Requirements:** 5.1, 5.2, 5.3, 5.4, 9.1


---

## Debugging Scenarios

### Scenario 1: Basic Script Debugging

**Goal:** Debug a simple Node.js script

**Steps:**
1. `debugger_start` - Start the session
2. `debugger_set_breakpoint` - Set breakpoint at line of interest
3. `debugger_continue` - Run to breakpoint
4. `debugger_get_local_variables` - Inspect variables
5. `debugger_step_over` - Step through code
6. `debugger_stop_session` - Cleanup

### Scenario 2: Conditional Breakpoint

**Goal:** Pause only when a specific condition is true

**Steps:**
1. `debugger_start` - Start the session
2. `debugger_set_breakpoint` with condition: `{"condition": "count > 100"}`
3. `debugger_continue` - Run until condition is met
4. `debugger_inspect` - Evaluate expressions
5. `debugger_stop_session` - Cleanup

### Scenario 3: Infinite Loop Detection

**Goal:** Find where code is stuck in an infinite loop

**Steps:**
1. `debugger_detect_hang` with timeout and sample interval
2. Review the returned location and stack trace
3. Fix the loop condition

### Scenario 4: Test Debugging

**Goal:** Debug a failing Jest test

**Steps:**
1. `debugger_start` with Jest command: `{"command": "node", "args": ["node_modules/.bin/jest", "test.js", "--runInBand"]}`
2. `debugger_set_breakpoint` in test file
3. `debugger_continue` to breakpoint
4. `debugger_get_local_variables` - Check test state
5. `debugger_inspect` - Evaluate test assertions
6. `debugger_stop_session` - Cleanup

### Scenario 5: Variable Tracking

**Goal:** Track how a variable changes during execution

**Steps:**
1. `debugger_start` - Start the session
2. `debugger_add_watch` - Add variable to watch list
3. `debugger_set_breakpoint` at multiple locations
4. `debugger_continue` - Run to first breakpoint
5. `debugger_get_watches` - Check variable value
6. Repeat steps 4-5 for each breakpoint
7. `debugger_stop_session` - Cleanup

### Scenario 6: Call Stack Analysis

**Goal:** Understand the execution path leading to a point

**Steps:**
1. `debugger_start` - Start the session
2. `debugger_set_breakpoint` at the point of interest
3. `debugger_continue` - Run to breakpoint
4. `debugger_get_stack` - View the call stack
5. `debugger_switch_stack_frame` - Navigate to different frames
6. `debugger_get_local_variables` - Inspect variables in each frame
7. `debugger_stop_session` - Cleanup

### Scenario 7: TypeScript Debugging

**Goal:** Debug TypeScript code with source maps

**Steps:**
1. Ensure tsconfig.json has `"sourceMap": true`
2. `debugger_start` with `--enable-source-maps` flag
3. `debugger_set_breakpoint` using TypeScript file path
4. `debugger_continue` - Breakpoint automatically maps to compiled JS
5. `debugger_get_local_variables` - Variable names preserved from TS
6. `debugger_stop_session` - Cleanup

### Scenario 8: Object Inspection

**Goal:** Deeply inspect a complex object

**Steps:**
1. `debugger_start` - Start the session
2. `debugger_set_breakpoint` where object exists
3. `debugger_continue` - Run to breakpoint
4. `debugger_inspect` - Evaluate object expression, get objectId
5. `debugger_inspect_object` - Inspect with maxDepth
6. `debugger_stop_session` - Cleanup

---

## Error Codes Reference

### Session Errors

- **SESSION_NOT_FOUND**: Session ID doesn't exist or was terminated
- **SESSION_START_FAILED**: Failed to start the process or attach inspector

### Breakpoint Errors

- **BREAKPOINT_SET_FAILED**: Invalid file path, line number, or condition
- **BREAKPOINT_NOT_FOUND**: Breakpoint ID doesn't exist
- **REMOVE_BREAKPOINT_FAILED**: Failed to remove breakpoint
- **TOGGLE_BREAKPOINT_FAILED**: Failed to toggle breakpoint state
- **LIST_BREAKPOINTS_FAILED**: Failed to list breakpoints

### Execution Errors

- **CONTINUE_FAILED**: Session not paused or process terminated
- **STEP_OVER_FAILED**: Session not paused or at end of execution
- **STEP_INTO_FAILED**: Session not paused or no function to step into
- **STEP_OUT_FAILED**: Session not paused or already at top level
- **PAUSE_FAILED**: Session already paused or process terminated

### Inspection Errors

- **INSPECT_FAILED**: Invalid expression or session not paused
- **GET_STACK_FAILED**: Session not paused or no call frames
- **NOT_PAUSED**: Operation requires paused state
- **GET_LOCAL_VARIABLES_FAILED**: Session not paused or no local scope
- **GET_GLOBAL_VARIABLES_FAILED**: Session not paused or no global scope
- **INSPECT_OBJECT_FAILED**: Invalid object ID or object no longer exists

### Watch Errors

- **ADD_WATCH_FAILED**: Invalid expression
- **REMOVE_WATCH_FAILED**: Internal error
- **WATCH_NOT_FOUND**: Watch ID doesn't exist
- **GET_WATCHES_FAILED**: Internal error

### Frame Errors

- **SWITCH_FRAME_FAILED**: Invalid frame index or session not paused

### Hang Detection Errors

- **HANG_DETECTION_FAILED**: Failed to start process or attach inspector

### Cleanup Errors

- **STOP_SESSION_FAILED**: Session already stopped or internal error

---

## Quick Reference Table

| Tool | Purpose | Requires Paused | Returns Location |
|------|---------|----------------|------------------|
| debugger_start | Start session | No | No |
| debugger_stop_session | Stop session | No | No |
| debugger_set_breakpoint | Set breakpoint | No | No |
| debugger_remove_breakpoint | Remove breakpoint | No | No |
| debugger_toggle_breakpoint | Toggle breakpoint | No | No |
| debugger_list_breakpoints | List breakpoints | No | No |
| debugger_continue | Resume execution | Yes | No |
| debugger_step_over | Step over line | Yes | Yes |
| debugger_step_into | Step into function | Yes | Yes |
| debugger_step_out | Step out of function | Yes | Yes |
| debugger_pause | Pause execution | No | Yes |
| debugger_inspect | Evaluate expression | Yes | No |
| debugger_get_local_variables | Get local vars | Yes | No |
| debugger_get_global_variables | Get global vars | Yes | No |
| debugger_inspect_object | Inspect object | Yes | No |
| debugger_add_watch | Add watch | No | No |
| debugger_remove_watch | Remove watch | No | No |
| debugger_get_watches | Get watches | No | No |
| debugger_get_stack | Get call stack | Yes | No |
| debugger_switch_stack_frame | Switch frame | Yes | No |
| debugger_detect_hang | Detect hang | No | Yes (if hung) |

---

## Best Practices

1. **Always cleanup sessions** - Call `debugger_stop_session` when done
2. **Use absolute paths** - For file arguments and breakpoints
3. **Check verification** - Verify breakpoints are set correctly
4. **Handle errors** - Check response status and handle errors gracefully
5. **Set appropriate timeouts** - Based on expected execution time
6. **Use conditional breakpoints** - To reduce noise and focus on specific cases
7. **Track variable changes** - Use watches for important variables
8. **Navigate stack frames** - To understand execution context
9. **Enable source maps** - For TypeScript debugging
10. **Test hang detection** - Before running potentially problematic code

---

## See Also

- [README.md](./README.md) - User documentation and usage examples
- [API.md](./API.md) - Detailed API documentation with JSDoc
- [AI-AGENT-INTEGRATION.md](./AI-AGENT-INTEGRATION.md) - AI agent integration guide
- [VSCODE-INTEGRATION.md](./VSCODE-INTEGRATION.md) - VS Code extension guide
- [TESTING.md](./TESTING.md) - Testing documentation