nodejs-debug-mcp/README.md

Model Context Protocol server exposing a debug-script tool for Node.js inspector sessions.

# nodejs-debug-mcp

MCP server that gives coding agents the ability to debug Node.js scripts without modifying source code.

## Why install this

Your coding agent (Claude, Cursor, etc.) can inspect runtime values without modifying your code. Instead of asking the agent to add `console.log` statements, it can call `debug-script` to see what's happening at any line during execution.

Particularly useful for debugging unit tests and helping agents write tests by understanding what values are actually present at runtime.

## How it works

The agent specifies:
- A Node.js command to run
- A breakpoint location (file and line)
- An expression to evaluate

The tool runs the script, pauses at that line each time it executes, evaluates the expression, and returns all values when the script finishes.

## Parameters

- **command:** Node.js command with `--inspect-brk` flag (enables debugging and pauses execution at start)
- **breakpoint:** `{ file: string, line: number }`
- **expression:** JavaScript expression to evaluate
- **timeout:** Maximum execution time in milliseconds
- **includeStack:** (optional) Include call stack frames in the result

## Setup

### Claude Code

```bash
claude mcp add --scope user --transport stdio nodejs-debug-mcp -- npx -y nodejs-debug-mcp
```

### Codex CLI

```bash
codex mcp add nodejs-debug-mcp -- npx -y nodejs-debug-mcp
```

### Cursor

Add to your MCP settings config file:
```json
{
  "mcpServers": {
    "nodejs-debug-mcp": {
      "command": "npx",
      "args": ["-y", "nodejs-debug-mcp"]
    }
  }
}
```

## Development

```bash
npx tsc                        # Build
node --test test/e2e.test.js  # Test
```

See `SPECIFICATION.md` for implementation details.

## Release

To publish a new version to npm:

```bash
# Patch version (0.1.2 → 0.1.3)
npm version patch && git push --follow-tags

# Minor version (0.1.2 → 0.2.0)
npm version minor && git push --follow-tags

# Major version (0.1.2 → 1.0.0)
npm version major && git push --follow-tags
```

This automatically:
- Updates package.json version
- Creates a git commit and tag
- Pushes to GitHub
- Triggers the publish workflow

## License

MIT