Metadata-Version: 2.4
Name: shipcheck-mcp
Version: 0.23.0
Summary: MCP verification server for AI coding agents — proves a feature works across UI, API, and database. Run with: uvx shipcheck-mcp
Author: ShipCheck contributors
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,mcp,playwright,testing,verification
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Requires-Dist: mcp<2.0.0,>=1.0.0
Requires-Dist: pydantic>=2.7.0
Provides-Extra: database
Requires-Dist: psycopg2-binary>=2.9; extra == 'database'
Requires-Dist: sqlalchemy>=2.0; extra == 'database'
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Provides-Extra: github-app
Requires-Dist: pyjwt[crypto]>=2.8.0; extra == 'github-app'
Provides-Extra: playwright
Requires-Dist: playwright>=1.45.0; extra == 'playwright'
Description-Content-Type: text/markdown

<p align="center">
  <img src="docs/images/hero.png" alt="ShipCheck — MCP verification server" width="820">
</p>

<h1 align="center">ShipCheck</h1>
<p align="center"><b>It doesn't write tests. It proves the feature works.</b></p>

<p align="center">
  <a href="#"><img alt="license" src="https://img.shields.io/badge/license-MIT-blue"></a>
  <a href="#"><img alt="tests" src="https://img.shields.io/badge/tests-172%20passing-brightgreen"></a>
  <a href="#"><img alt="mcp tools" src="https://img.shields.io/badge/MCP%20tools-27-2e5aa8"></a>
</p>

---

## In a nutshell

AI coding agents (Claude Code, Cursor, OpenCode…) can write code and write tests, but nothing checks the agent's own work the way a QA engineer would: actually run the app, click through the real flow, hit the real API, and look at the real database.

ShipCheck is that QA engineer, exposed as an MCP server. Point it at any repository and describe a feature — it **discovers** how the app actually works (no hardcoded assumptions about routes, tables, or auth patterns), **plans** what to check, and **verifies** it across the UI, the API, and the database, handing back evidence instead of a guess.

```
ANY SOFTWARE
     │
     ▼
 INSPECT · DISCOVER          detect stack, build a SystemGraph of routes/tables/actors
     │
     ▼
    PLAN                     generate a verification plan from the graph — no hardcoded URLs
     │
     ▼
   VERIFY                    Playwright (UI) + HTTP (API) + read-only SQL (database)
     │
     ▼
   EVIDENCE                  pass/fail per layer, diagnosis on failure, a written report
```

## Install

Published on PyPI as `shipcheck-mcp` (the import name is still `shipcheck`, the MCP server and CLI are the same package — `mcp` is a base dependency, not an extra, so the plain command below is enough to run the MCP server):

```bash
pip install shipcheck-mcp                              # MCP server + CLI, no extras needed
pip install 'shipcheck-mcp[playwright,database]'        # + browser-driven UI checks + SQL verification
playwright install chromium                             # only if you installed the playwright extra
```

From a clone of this repo instead: `pip install -e '.[playwright,database]'`.

## Use it from an agent

Zero local install — an MCP client can run it directly via `uvx`:

```bash
claude mcp add shipcheck -- uvx shipcheck-mcp
```

Want UI/database checks too:

```bash
claude mcp add shipcheck -- uvx --from 'shipcheck-mcp[playwright,database]' shipcheck-mcp
```

Then just ask:

> "Use ShipCheck to verify that users can register and log in."

The agent calls ShipCheck's tools directly — `discover`, `verify_feature`, `bughunt`, `verify_change` — the same way it calls a file-read or shell tool.

## Use it from the terminal

```bash
shipcheck inspect .                                          # detect the stack, no config file needed
shipcheck plan "users can register and log in"                # see the plan, dry-run, nothing executed
shipcheck verify "users can register and log in" \
  --execute --base-url http://localhost:8000                  # run it for real
shipcheck loop "users can register and log in" \
  --execute --base-url http://localhost:8000 --depth advanced # verify, diagnose failures, retest
```

## What it verifies

| Layer | Adapter | What it proves |
|---|---|---|
| UI | Playwright | The user-visible workflow reaches the expected final state |
| API | HTTP client | Endpoints return the expected status and payloads |
| Database | SQL / Supabase REST | Persistent state matches the completed workflow |
| System | Runtime observer | Reloads, concurrency, cross-actor causal effects |

Beyond the happy path: autonomous bug hunting (composes every operation workflow from the graph and finds what's broken, no feature description needed), bug filing to GitHub issues, discovery-driven test generation (negative/boundary/auth/state/regression), behavioral invariants (idempotency, state conservation, auth boundaries), git-diff-scoped verification (`verify_change` — only re-checks what a diff actually affects), and CI reporting (markdown/HTML/JUnit + GitHub PR comments).

## 27 MCP tools

Full reference: [website/pages/docs/tools.mdx](website/pages/docs/tools.mdx) (run `cd website && npm install && npm run dev` to browse it, or read `AGENTS.md`). Grouped by what they do: discovery (`inspect_project`, `discover`, `explore`, `capabilities`), planning & verification (`generate_test_plan`, `verify_feature`, `run_verification_loop_tool`, `analyze_diff`, `verify_change`), autonomous (`bughunt`, `report_bugs`, `multi_actor_verify`), API & data (`api_request`, `api_discover`, `api_set_token`, `db_query`, `db_discover`, `db_assert`), record & report (`save_scenario`, `load_scenario`, `list_scenarios`, `generate_report`, `github_pr_report`), memory (`project_memory`, `show_memory_graph`, `record_memory_change`, `observe`).

## Design goal

ShipCheck doesn't compete with Playwright MCP or browser-use as a low-level browser controller. Those answer *how do I interact with a page?* ShipCheck answers *what should be verified, which users need to participate, what state should change, and what evidence proves the feature works?*

It doesn't know your application. It discovers it, learns how it behaves, and proves whether the behavior you asked for actually works — the same way on a FastAPI JSON API, a Next.js SPA, or a classic server-rendered Flask app, without a line of product-specific code in ShipCheck itself.

## Docs

- [Getting Started](docs/README.md) · [Architecture](docs/ARCHITECTURE.md) · [Deployment](docs/DEPLOYMENT.md) · [Roadmap](docs/ROADMAP.md)
- Docs site: `cd website && npm install && npm run dev`

## License

MIT
