**English** | [한국어](README.ko.md)

# Local Dev Doctor MCP

[![CI](https://github.com/efficjump/local-dev-doctor-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/efficjump/local-dev-doctor-mcp/actions/workflows/ci.yml)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3776AB)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

Local Dev Doctor turns an unfamiliar development checkout into an evidence-backed diagnosis. It
discovers how the project is meant to run, checks safe prerequisites, and executes only the exact
probe that a user approves.

It never installs packages, edits configuration, starts services automatically, or persists
environment values.

## How it works

```mermaid
flowchart LR
    A[Discover project profile] --> B[Run safe preflight]
    B --> C[Prepare exact probe]
    C --> D{Explicit approval}
    D -->|Approved| E[Run bounded probe]
    D -->|Declined| F[Stop without execution]
    E --> G[Evidence-bound analysis]
    G --> H[Build redacted runbook]
```

The profile is derived from the project itself: package-manager files, declared scripts, service
definitions, environment-variable names, executable requirements, and loopback ports. No
framework-specific command table is baked into the server.

## Highlights

- Dynamic discovery across project manifests and service definitions
- Secret-free preflight checks for executables, variable names, and loopback ports
- Exact argv plans with short-lived, one-time approval tokens
- Separate approval gates for long-running probes and possible workspace writes
- Timeouts, output caps, redaction, and process-group cleanup for executed probes
- Deterministic findings plus optional host-model hypotheses constrained to evidence IDs
- Markdown and JSON runbooks written outside the diagnosed project
- `stdio` and stateless Streamable HTTP transports

## Install

Install the command directly from the repository with
[uv](https://docs.astral.sh/uv/):

```bash
uv tool install "git+https://github.com/efficjump/local-dev-doctor-mcp.git"
```

To work from source:

```bash
git clone https://github.com/efficjump/local-dev-doctor-mcp.git
cd local-dev-doctor-mcp
uv sync --all-extras
```

## Configure an MCP client

After installation, register the command with any client that supports MCP over `stdio`:

```json
{
  "mcpServers": {
    "local-dev-doctor": {
      "command": "local-dev-doctor-mcp",
      "args": ["--transport", "stdio"],
      "env": {
        "LOCAL_DEV_DOCTOR_ALLOWED_ROOTS": "/path/to/allowed/projects"
      }
    }
  }
}
```

`LOCAL_DEV_DOCTOR_ALLOWED_ROOTS` is required. Use the platform path separator to provide more than
one allowed root.

## Diagnostic workflow

| Stage | Tools | Purpose |
| --- | --- | --- |
| Session | `start_diagnosis`, `list_diagnoses`, `get_diagnosis` | Create and inspect bounded diagnosis state |
| Discovery | `discover_profile` | Derive commands, prerequisites, services, variable names, and ports |
| Preflight | `run_preflight` | Inspect safe local state without running project commands |
| Approval | `prepare_probe` | Return the exact argv, risk flags, timeout, and one-time token |
| Execution | `execute_probe` | Run only the approved candidate under strict bounds |
| Analysis | `analyze_failures` | Produce findings whose claims cite known evidence IDs |
| Reporting | `build_runbook_report` | Write a redacted, reproducible runbook |

The server fingerprints relevant project inputs. If they change after discovery, stale plans are
rejected and the profile must be refreshed.

## Safety model

The allowed-root boundary is resolved before project access. Preflight does not read environment
values, and stored state contains variable names only. A prepared probe cannot be altered or
replayed: its token is hashed in state, expires, and is consumed by the first execution attempt.
Probe output is bounded and redacted before persistence.

See [the security policy](SECURITY.md) for the threat model and disclosure process, and
[the architecture guide](docs/architecture.md) for the trust boundaries.

## Streamable HTTP

Bind to loopback unless a trusted reverse proxy provides authentication and transport security:

```bash
local-dev-doctor-mcp --transport streamable-http --host 127.0.0.1 --port 8769
```

## Development

```bash
uv sync --all-extras
uv run ruff format --check .
uv run ruff check .
uv run mypy
uv run pytest --cov --cov-report=term-missing
uv build
```

Contributions are welcome; read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a change.

## License

[MIT](LICENSE)