# MCP Preflight

**Review MCP config before you run it.**

Turn a configuration or tool-catalog JSON snapshot into a static review report.
The checker never starts or contacts the configured servers. The Python CLI has
no third-party runtime dependencies and needs no account or API key.

[![CI](https://github.com/newlifesolution/mcp-preflight/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/newlifesolution/mcp-preflight/actions/workflows/ci.yml)

**Alpha, [MIT licensed](LICENSE).** No PyPI distribution; use a reviewed GitHub release or authorized checkout.
CLI and optional MCP stdio adapter are the focus. A bounded Windows socket-close
fix addresses the reproduced local HTTP timeout; see [scope and tests](docs/HTTP.md).
A clean report is not proof of safety.

## Try the difference

From an authorized checkout, with Python 3.12+:

```sh
python scripts/mcp_preflight.py --input examples/preflight-before.json --fail-on review
python scripts/mcp_preflight.py --input examples/preflight-after.json --fail-on review
```

Run the commands separately: the first intentionally exits **1**; the second exits **0**.
No pip install, server startup or network access is needed for this demo.

![Synthetic example: an unpinned package selector triggers a finding; an exact version removes that finding. Runtime remains unverified.](docs/assets/preflight-demo.svg)

The only input change is `example-mcp@latest` → `example-mcp@1.2.3`.
Both are synthetic strings, not package recommendations. The checker does not
look up whether that package or version exists. Both inputs explicitly provide
an empty catalog; this demo checks version syntax, not tool safety.

## Use it in your workflow

| You have… | Preflight gives you… |
| --- | --- |
| An MCP config someone wants to enable | Static indicators to review before connection |
| A captured `tools/list` response | Catalog/schema and annotation review items |
| A CI check | JSON or SARIF plus a configurable failure threshold |
| Codex with the optional adapter | `preflight_review_json` over stdio |

```sh
python scripts/mcp_preflight.py --input your-config.json --output report.json --fail-on high
python scripts/mcp_preflight.py --input your-config.json --format sarif --output report.sarif
```

Reports omit supplied credential values, URLs, commands and free-form names and
descriptions. Keep the original input private and inspect any report before sharing.
SARIF export works; GitHub code-scanning ingestion is not yet verified.

**Next:** [input examples](docs/INPUTS.md) · [CLI reference](docs/CLI.md) ·
[Codex setup](docs/CODEX.md) · [complete usage](docs/REFERENCE.md)

## Where it fits

Preflight is a small static review step. For agent-wide discovery, broader
security analysis or live protocol debugging, compare
[Snyk Agent Scan](https://github.com/snyk/agent-scan),
[Cisco MCP Scanner](https://github.com/cisco-ai-defense/mcp-scanner),
[SecureAI-Scan](https://github.com/akanthed/SecureAI-Scan) and
[MCP Inspector](https://github.com/modelcontextprotocol/inspector).
Some also offer offline scanning: that is not an exclusive feature here.
See the [dated comparison and tradeoffs](docs/COMPARISON.md).

Preflight does not inspect server source code, fetch catalogs, enforce runtime
policies or certify prompt-injection resistance. Detection accuracy and
competitive superiority have not been benchmarked.

## Evidence you can inspect

[Remote CI on 2026-10-06](https://github.com/newlifesolution/mcp-preflight/actions/runs/37464486446):
13 successful jobs covering one artifact build, four Windows/Linux × Python
3.12/3.13 core jobs, and eight MCP jobs with minimum/normal SDK resolution.
The workflow checks installed CLI/HTTP and MCP behavior outside the checkout.
This is evidence for that commit, not a guarantee for future changes.

[Validation and open limits](docs/VALIDATION.md) · [HTTP behavior](docs/HTTP.md) ·
[Contributing](CONTRIBUTING.md) · [Security reporting](SECURITY.md)

## Help improve the alpha

Authorized reviewers: [report a reproducible false positive or missing check](https://github.com/newlifesolution/mcp-preflight/issues/new/choose).
Use a minimal synthetic example and include the rule ID and expected behavior.
Never attach live credentials or original private configurations.

Licensed under [MIT](LICENSE). Public availability, customer adoption and a support SLA are not asserted.