convez.ai
MCP ServerDevOps & InfraestruturaIntermediário
mcp-tool-shop-org

Shipcheck

mcp-tool-shop-org/shipcheck

Checklists e padrões para validar produto antes de enviar

Ver no GitHub
BomPluginScore · de 0 a 100

Framework 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/shipcheck

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
87%
Último commit
há 5 dias
Versão
v1.0.9
Issues abertas
2
Contribuidores
1

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

StandardWhat it covers
Ship Gate31 hard-gate + 4 soft-gate pre-release checklist
Error Contract2-tier structured error standard with code registry
Security BaselineReport email, response timeline, threat scope
HandbookOperational field manual for complex tools
ScorecardPre/post remediation scoring
Adoption GuideApply 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

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 codeMeaning
0OK
1User error (bad input, missing config)
2Runtime error (crash, backend failure)
3Partial 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

CategoryScoreNotes
A. Security6/8SECURITY.md, trust model, no secrets/telemetry. MCP items skipped (not an MCP server)
B. Error Handling3/7Structured error shape + exit codes + no raw stacks. MCP/desktop/vscode skipped
C. Operator Docs4/7README, CHANGELOG, LICENSE, --help. Logging/MCP/complex skipped
D. Shipping Hygiene6/9verify script, version=tag, npm audit in CI, engines.node, lockfile. Zero deps = no update mechanism
E. Identity4/4Logo, translations, landing page, metadata
Total23/3114 items skipped with justification · shipcheck audit passes 100%

License

MIT


Ver o original no GitHub

Bom para

Relacionados