Shipcheck
mcp-tool-shop-org/shipcheck
Checklists e padrões para validar produto antes de enviar
Ver no GitHubFramework de padrões de produto para o MCP Tool Shop que define e valida critérios de qualidade antes do lançamento. Fornece checklists, contratos de erro estruturados, linhas de base de segurança e guias de adoção para garantir que código, documentação, tratamento de erros e higiene de envio atendam a um padrão mínimo.
Instalação
npx convez-ai mcp-tool-shop-org/shipcheck1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Validar readiness de ferramentas MCP antes do lançamento
- Implementar padrões de tratamento de erro estruturado
- Auditar conformidade com segurança e documentação
- Integrar verificações de qualidade em pipelines CI/CD
Veredito

Shipcheck é essencial para equipes que mantêm múltiplas ferramentas MCP e precisam de garantias sobre qualidade e segurança antes de enviar. A abordagem de gates hard/soft (bloqueadores vs. ideais) é pragmática e permite adoção gradual.
README
A tradução para o português deste README ainda está na fila.
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
- Read ADOPTION.md
- Run
npx @mcptoolshop/shipcheck initin your repo root - Check off applicable items in
SHIP_GATE.md, mark non-applicable withSKIP: - Run
npx @mcptoolshop/shipcheck audit— exits 0 when all hard gates pass - 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-doorverifier (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
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% |