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

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