# Predictive Debugger

> An MCP server that finds likely runtime failures in JavaScript and TypeScript. It ranks files by structural risk, maps dependencies, and asks an independent model where the code will break, using the coding-agent CLI you already sign in to.

## Agent resources

- [Complete documentation](https://predictivedebugger.dev/llms-full.txt): Every documentation page in one file.
- [Source code](https://github.com/SpeedosDK/predictive-debugger): Server source, tools, and tests.
- [Package](https://www.npmjs.com/package/predictive-debugger): Published releases on npm.

## Product facts

- Package: predictive-debugger on npm
- Version: 0.8.1
- License: MIT
- Runtime: Node.js 22 or later
- Languages: JavaScript and TypeScript, including JSX, TSX and decorators
- Agents: Claude Code, Codex, and GitHub Copilot CLI
- Tools: scan_project, analyze_file, map_dependencies, predict_failures, analyze_logs, list_providers
- Cost: The MCP server is free. Predictions use your own CLI sign-in and its allowance.
- Scope: Predictive Debugger ranks risk and predicts likely runtime failures. It does not run your code, and it does not replace tests or review.

## Tools

- `scan_project` (Local): Rank source files by risk density. Start with the code that deserves a closer read.
- `analyze_file` (Local): Inspect complexity, async boundaries, and the signals behind a file’s risk score.
- `map_dependencies` (Local): Trace imports, reverse imports, and connected tests back to their source lines.
- `predict_failures` (Model call): Ask an independent model for likely runtime failures, with a line number and a reason.
- `analyze_logs` (Local): Surface unusual log entries, ranked by severity and unusual wording. Requires Python 3.
- `list_providers` (Local): See which supported CLIs are installed and check their sign-in status.

## Documentation

- [Documentation overview](https://predictivedebugger.dev/docs): Setup, tool reference, and VS Code preview for the Predictive Debugger MCP server.
- [Quickstart](https://predictivedebugger.dev/docs/quickstart): Install the MCP server, confirm your agent can see it, and run your first risk scan in about five minutes.
- [Review code your agent just wrote](https://predictivedebugger.dev/docs/guides/review-new-code): Check a change from outside the context that produced it, using a fresh prediction for one file or a scoped sub-agent for several.
- [Find the riskiest file before a release](https://predictivedebugger.dev/docs/guides/find-risk): Rank a directory by risk density, read the signals behind the ranking, and understand what the numbers do and do not claim.
- [Trace what a change breaks](https://predictivedebugger.dev/docs/guides/trace-impact): Find a file's imports, reverse imports, and connected tests with source-line evidence, so a local edit gets a review as wide as its reach.
- [Advanced setup](https://predictivedebugger.dev/docs/setup): Provider login, registration scope, Codex and Copilot configuration, updates, and building Predictive Debugger from source.
- [Tool reference](https://predictivedebugger.dev/docs/tools): Parameters, outputs, and limits for all six Predictive Debugger MCP tools, and how the prediction score is calculated.
- [VS Code preview](https://predictivedebugger.dev/docs/vscode): Run the experimental Predictive Debugger VS Code extension from source and configure its settings.

## Install

Claude Code: `claude mcp add --scope project predictive-debugger -- npx -y predictive-debugger@latest`
Codex: `codex mcp add predictive-debugger -- npx -y predictive-debugger@latest`
GitHub Copilot: `copilot mcp add predictive-debugger -- npx -y predictive-debugger@latest`

On native Windows, replace `npx` with `cmd /d /c npx`.