Shipcheck

日本語 | 中文 | Español | Français | हिन्दी | Italiano | Português (BR)

Product standards for MCP Tool Shop.
Templates, contracts, and adoption guides that define what "done" means before anything ships.

---

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

Standard	What it covers
Ship Gate	31 hard-gate + 4 soft-gate pre-release checklist
Error Contract	2-tier structured error standard with code registry
Security Baseline	Report email, response timeline, threat scope
Handbook	Operational field manual for complex tools
Scorecard	Pre/post remediation scoring
Adoption Guide	Apply shipcheck to any repo in <30 minutes

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 front-door  # Verify the AI-native front door (Gate G)
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)

Gate G — AI-native front door (optional, requires @mcptoolshop/site-theme >=2.0.0):

• Verifies that the repo's AI-native front door (README / AGENTS.md / llms.txt) tells the truth — the machine-readable complement to the Operator Docs (C) and Identity (E) gates
• Delegates to site-theme's front-door verifier (verify({ root })), which routes documented claims to evidence channels and returns a risk-ordered scorecard
• Surfaces counts by severity (contradicted · unbacked · stale · bloat · hygiene · style) plus the gate verdict; fails (exit 1) on contradicted / unbacked / stale claims
• site-theme is an optional peer dependency (a hard dep would pull astro into this zero-dep CLI). When it isn't installed, the gate skips gracefully (exit 0) — it never crashes the audit

Executed gates — audit counts boxes; these read the artifact

shipcheck audit only tallies the checkboxes in SHIP_GATE.md — a box can be green while the fact is false. The gates below execute the check against the real artifact and exit 1 on the real defect. Each converts a specific Ship Gate line from a human attestation into a machine verification, and each ships with a RED meta-test that mutates the protected thing and proves the gate fires.

• Gate H — publish surface (shipcheck pack, D5): runs npm pack --dry-run on every publishable workspace package; fails if any tarball lacks README/LICENSE, a files[] entry doesn't resolve, or license is unset.
• Gate I — secrets (shipcheck secrets, A3): scans every publishable package's tarball surface for high-signal credentials (provider-prefixed keys, tokens, private-key blocks); matches are redacted; shipcheck-allow-secret whitelists a documented example.
• Gate J — manifest (shipcheck manifest, D2/D6/D7): every publishable package sets engines/requires-python (D6); a lockfile is committed (D7); the manifest version is not behind the newest released git tag (D2, --expect <ver> for a strict release match).
• Gate K — security-docs (shipcheck security-docs, A1/A2): SECURITY.md exists with a reporting contact (not an empty stub), and the README states a trust/threat model with a substantive body. Verifies presence + contact, not threat-model quality.
• Gate L — ci (shipcheck ci, provenance + dependency-scan config): reads .github/workflows — every npm publish workflow uses OIDC (id-token: write) and --provenance, and a recognized scanner is configured in CI (or dependabot is present). --registry <pkg>[@<ver>] also confirms the published tarball carries a provenance attestation on npm (intent and outcome).
• Gate M — deps (shipcheck deps, the dependency-security outcome): runs npm audit in every lockfile'd tree (root and subtrees — a scanner configured only for the root misses the rest), fails on vulnerabilities at/above --level (default high), and checks whether GitHub Dependabot alerts are even enabled. ci proves a scanner is configured; deps proves there are no known vulnerabilities — a repo can pass the first and fail the second.

Every gate's --json output is pure JSON (no header line), so it pipes cleanly into other tools.

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):

Exit code	Meaning
0	OK
1	User error (bad input, missing config)
2	Runtime error (crash, backend failure)
3	Partial success (some items succeeded)

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

Category	Score	Notes
A. Security	6/8	SECURITY.md, trust model, no secrets/telemetry. MCP items skipped (not an MCP server)
B. Error Handling	3/7	Structured error shape + exit codes + no raw stacks. MCP/desktop/vscode skipped
C. Operator Docs	4/7	README, CHANGELOG, LICENSE, --help. Logging/MCP/complex skipped
D. Shipping Hygiene	6/9	verify script, version=tag, npm audit in CI, engines.node, lockfile. Zero deps = no update mechanism
E. Identity	4/4	Logo, translations, landing page, metadata
Total	23/31	14 items skipped with justification · shipcheck audit passes 100%

License

MIT

---

Built by MCP Tool Shop