mcp-shipcheck

Why

"Done" used to mean the code works. That's not enough. A product is code + safety + error handling + docs + identity + shipping hygiene. Shipcheck defines the bar.

What's in here

CLI usage

npx @mcptoolshop/shipcheck init       # Copy templates into current repo
npx @mcptoolshop/shipcheck audit      # Check SHIP_GATE.md progress
npx @mcptoolshop/shipcheck dogfood    # Check dogfood freshness (Gate F)
npx @mcptoolshop/shipcheck help       # Show help
npx @mcptoolshop/shipcheck --version  # Show version

Set SHIPCHECK_JSON=1 to get structured JSON error output instead of coloured text.

Quick start

1. Read ADOPTION.md

2. Run npx @mcptoolshop/shipcheck init in your repo root

3. Check off applicable items in SHIP_GATE.md, mark non-applicable with SKIP:

4. Run npx @mcptoolshop/shipcheck audit — exits 0 when all hard gates pass

5. Ship when audit passes

How it works

Hard gates (A-D) block release:

• A. Security Baseline — SECURITY.md, threat model, no secrets, no telemetry, default safety posture

• B. Error Handling — structured error shape (code/message/hint/retryable), safe output, graceful degradation

• C. Operator Docs — README, CHANGELOG, LICENSE, tool documentation

• D. Shipping Hygiene — verify script, version alignment, dependency scanning, lockfile

Soft gate (E) doesn't block but defines "whole":

• E. Identity — logo, translations, landing page, repo metadata

Gate F — Dogfood Freshness (optional, requires dogfood-labs):

• Checks for a fresh, verified, passing dogfood record

• Supports enforcement modes: required, warn-only, exempt

• Configurable freshness window (default: 30 days)

The gate says what must be true, not how to implement it. Applicability tags ([all], [npm], [mcp], [cli], [desktop], [vsix], [container]) prevent checkbox shame on repos where items don't apply.

Error contract at a glance

Tier 1 — Shape (mandatory everywhere):

{
  "code": "INPUT_TEXT_EMPTY",
  "message": "Text must not be empty",
  "hint": "Provide at least one character of text",
  "retryable": false
}

Tier 2 — Base type + exit codes (CLI/MCP/desktop):

Error codes use namespaced prefixes: IO_, CONFIG_, PERM_, DEP_, RUNTIME_, PARTIAL_, INPUT_, STATE_. Codes are stable once released.

Trust model

Data touched: reads package.json, pyproject.toml, and SHIP_GATE.md in the current working directory. Writes template files (SHIP_GATE.md, SECURITY.md, CHANGELOG.md, SCORECARD.md) to the current directory only. No network requests. All operations are local file reads and writes. No secrets handling. Does not read, store, or transmit credentials. No telemetry collected or sent.

Reference implementation

mcp-voice-soundboard was the first repo to pass Ship Gate — scoring 46/50 after remediation.

Scorecard

License

MIT