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

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