Metadata-Version: 2.4
Name: mcp-config-doctor
Version: 0.1.0
Summary: Read-only static diagnostics for local stdio MCP configuration
Author: MCP Config Doctor
License: Proprietary beta
Project-URL: Homepage, https://github.com/haozhn/mcp-config-doctor
Project-URL: Source, https://github.com/haozhn/mcp-config-doctor
Project-URL: Issues, https://github.com/haozhn/mcp-config-doctor/issues
Keywords: mcp,model-context-protocol,diagnostics,claude,codex,vscode
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# MCP Config Doctor 0.1

MCP Config Doctor is a local, read-only static scanner for one named MCP server.
It checks known configuration surfaces for Claude Desktop, Claude Code, Codex,
and VS Code, then prints deterministic findings and manual next steps.

Version 0.1.0 is a deliberately narrow public beta. It performs static checks
only, makes no runtime-success promise, and does not include checkout or license
enforcement. USD 19 remains a pricing hypothesis rather than a current charge.

## Install and run locally

Python 3.11 or newer is the supported runtime. The package has no runtime
dependencies and does not require network access.

```bash
python3 -m venv .venv
.venv/bin/pip install .
mcp-doctor scan --server filesystem
```

Narrow the scan or emit machine-readable output:

```bash
mcp-doctor scan --server filesystem --client codex --format json
```

The command prints the paths it checked, but replaces the home and project roots
with `~` and `<project>`. It never prints environment values or argument values.

## What v0 checks

- known user and project/workspace configuration locations;
- duplicate, shadowed, absent, and ambiguous-scope definitions;
- local stdio command resolution in the current process environment;
- configured `cwd`, path-like arguments, and named environment references;
- wrapper/no-TTY and container/localhost risk patterns;
- malformed, duplicate-key, unreadable, oversized, and unsupported configs;
- text and JSON reports using the same versioned finding catalog.

The full path matrix is in [docs/config-matrix.md](docs/config-matrix.md), and
the stable code contract is in [docs/findings.md](docs/findings.md).

## Exit codes

- `0`: reliable static scan with no actionable `FAIL`; warnings may remain.
- `1`: reliable scan found at least one actionable `FAIL`.
- `2`: invalid input, parsing, permission, unsupported transport/shape, or
  ambiguous precedence prevented a reliable conclusion.

## Safety and privacy boundary

The installed `mcp-doctor` command only reads bounded supported config files and
uses filesystem metadata plus the current process environment for static checks.
It contains no network, subprocess-launch, file-write, installer, elevation, or
auto-fix path. It does not start an MCP server, invoke JSON-RPC, call a tool, or
claim that a GUI client inherits the shell's environment.

Environment values are inspected only for empty/present status and placeholder
resolution. They are never retained in the report. Command arguments are not
rendered. No telemetry is collected by the CLI; funnel measurement belongs to
external repository, package, checkout, and support surfaces rather than this
command. The external event names and data boundary are recorded in
[`metrics/event-contract.json`](metrics/event-contract.json).

See [SECURITY.md](SECURITY.md) for the exact threat and disclosure boundary.

## Known limitations

- Static checks cannot prove client or server runtime behavior.
- Claude Desktop's Linux path is a compatibility convention tested by v0, not a
  claim that Anthropic ships Claude Desktop on every Linux environment.
- VS Code manages user profiles; v0 checks the default stable profile path and
  the current workspace, not every named, portable, Insiders, or remote profile.
- VS Code's official MCP docs distinguish user/workspace scopes without defining
  deterministic duplicate-name precedence. v0 therefore returns exit `2` when
  the same server appears in both.
- Codex project configuration is subject to project trust.
- Python 3.9/3.10 source execution can parse Codex only when a compatible
  `tomli` module is already present; packaged support starts at Python 3.11.
- Remote HTTP/SSE, OAuth, client-specific runtime bugs, and third-party server
  correctness are explicit non-goals.

## Verify

From this product directory:

```bash
python3 -m pip install --no-deps -e .
python3 -m unittest discover -s tests -v
python3 scripts/dry_run.py
```

Uninstalling the package removes the product. The CLI creates no state, edits no
configuration, and has no hosted user data to migrate or delete.
