Predictive Debugger

[Predictive Debugger]

Predictive Debugger

Website and docs: predictivedebugger.dev

[npm version] [CI] [License: MIT] [GitHub stars]

MCP server for finding likely runtime failures in JavaScript and TypeScript. Seven tools help your coding agent check types, rank risky files, trace dependencies, inspect logs and get an independent model review with a line number and reason.

Uses the Claude Code, Codex or GitHub Copilot CLI you already have installed. Prediction calls use that CLI's model access and usage allowance. No separate API key is needed. Your provider's terms apply to those calls; check them before use, especially on a Claude subscription. See Provider terms.

Setup

Requires Node.js 22 or later. For model predictions, install and sign in to at least one supported CLI. Python 3 is optional for log analysis.

1. Add the MCP server

Choose your agent below. npx downloads and runs the package automatically.

claude mcp add --scope project predictive-debugger -- npx -y predictive-debugger@latest

claude mcp add --scope project predictive-debugger -- cmd /d /c npx -y predictive-debugger@latest

codex mcp add predictive-debugger -- npx -y predictive-debugger@latest

codex mcp add predictive-debugger -- cmd /d /c npx -y predictive-debugger@latest

{  "mcpServers": {    "predictive-debugger": {      "command": "npx",      "args": ["-y", "predictive-debugger@latest"],      "tools": ["*"]    }  }}

2. Check the connection

Restart your agent and check /mcp for predictive-debugger and its seven tools. To check that the package downloads and print its version:

npx -y predictive-debugger@latest --version

Running without --version starts a stdio server that waits for your agent's messages. See setup help for local builds and troubleshooting.

3. Ask your agent about the code

Use Predictive Debugger to find the riskiest files in src/.Show the imports and tests connected to src/services/orders.ts.Check src/services/orders.ts for likely runtime failures.Find unusual entries in logs/app.log.

Tools

Start with scan_project and check_types, then read the files they highlight. Use map_dependencies to find related files and predict_failures when you want a second opinion. Pass several paths as files so small files share bounded model calls and avoid repeating the CLI context for every file.

See the tool reference for parameters, result fields and limits.

Privacy and limits

• Static analysis, dependency maps and log analysis run locally. predict_failures sends source and bounded dependency context to your CLI's model provider. Set calleeContext: false to omit dependency context.
• Credentials stay with the CLI. MCP tools can read paths the server process can access; project-scoped setup does not restrict file access. See the security model.
• JavaScript and TypeScript are supported, including JSX, TSX and decorators. Vue and Svelte single-file components are not supported. Files above 4 MB are rejected; large predictions may cover only selected declarations.
• Risk scores and predictions can be wrong. The benchmarks use development cases and do not establish accuracy on arbitrary repositories.
• Manually verified on Windows. CI covers Windows, macOS and Linux on Node 22 and 24; real CLI installations on macOS and Linux have not been manually verified.

VS Code preview

An unfinished extension can show findings in the Problems panel. It requires a local build and is not available on the Marketplace or as a prebuilt VSIX. See trying the extension.

Documentation

• predictivedebugger.dev: website, quickstart and guides.
• Advanced setup: provider login, project scope, updates and local builds.
• Tool reference: parameters, prediction results, dependency context and scoring.
• VS Code preview: development host, commands and settings.
• Benchmarks and method.
• Development and contributing. Bug reports are welcome; code contributions are not open yet.
• Security policy. Report vulnerabilities privately.

License

MIT.