Local Dev Doctor MCP

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

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:

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

To work from source:

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:

{
  "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 for the threat model and disclosure process, and the architecture guide for the trust boundaries.

Streamable HTTP

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

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

Development

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 before opening a change.

License

MIT