mcp-readiness

Lighthouse for MCP servers. Point it at any public Model Context Protocol server and get a graded readiness report in ~2 seconds — handshake, tool quality, safety annotations, anti-ghost content, token efficiency, honest errors — plus a Claude/ChatGPT directory pre-flight.

Zero dependencies. Zero config. Zero telemetry. Runs anywhere Node 18+ runs.

npx mcp-readiness https://mcp.example.com/mcp

If this is your MCP server, the next step after the grade is to claim the public SaSame Readiness Passport:

1. Run: npx mcp-readiness https://your-server.example/mcp
2. Open: https://github.com/shigeki7777/sasame-mcp-observatory/issues/new?template=claim-passport.yml
3. Or connect the SaSame public MCP and call: claim_start(url) → claim_confirm

Claiming is free. It proves owner control; it does not create a safety endorsement, paid ranking, custody relationship, or tax document.

Put it on every pull request

- uses: shigeki7777/mcp-readiness@v1
  with:
    endpoint: ${{ vars.MCP_ENDPOINT }}
    min-grade: B

The Action writes the complete result into the GitHub Step Summary, emits annotations for failed criteria, saves mcp-readiness-report.json, and fails when the measured grade drops below the configured threshold. It needs no token and sends no telemetry to SaSame. For a server started by the workflow, pass its localhost Streamable HTTP URL instead. A complete workflow is in examples/readiness.yml.

A real run — a strong server that's one fix from a clean directory pre-flight (one criterion to address, not a verdict on your work):

  MCP Readiness    B    9/10 criteria  ·  11 tools  ·  134ms
  https://mcp.example.com/mcp

  PASS  C1 Protocol handshake conformance
  PASS  C2 Tool listability
  PASS  C3 Tool object validity
  PASS  C4 Description sufficiency / selectability
  FAIL  C5 Safety annotation presence
        0/11 tools carry a valid safety-hint annotation
  PASS  C6 Liveness & latency
  PASS  C7 Returns real content (anti-ghost)
  PASS  C8 Machine-discoverable identity
  PASS  C9 Token efficiency
  PASS  C10 Honest error behavior

  Top fix  C5 Safety annotation presence — 0/11 tools carry a valid safety-hint annotation
  Directory pre-flight  1 mechanical blocker(s) for Claude/ChatGPT listing

Why

Agents discover your MCP server through its tools/list. If a tool has no description, no readOnlyHint, returns nothing on a safe call, or your server bloats every context with a 120 KB tool list, the agent can't find, trust, or call it — and the Claude Connectors / ChatGPT Apps directories will reject it for mechanical reasons before a human ever reviews it. mcp-readiness checks the things that actually decide whether your server gets used, and tells you the one fix that moves the needle.

Install / run

npx mcp-readiness <url>                 # one-off, no install
npx mcp-readiness http://localhost:3000/mcp   # audit your server while you build it
npm i -g mcp-readiness && mcp-readiness <url>     # or install globally

Use it in CI — it exits non-zero when a server drops below a B:

- run: npx mcp-readiness "$MCP_URL"     # exit 0 = A/B, 1 = C/D, 2 = connection/usage error

npx mcp-readiness <url> --json          # machine-readable full report

After the grade: claim the Passport

mcp-readiness is the local, reproducible check. The hosted SaSame MCP Observatory adds the public record: an owner-controlled Readiness Passport, signed certificates, badge snippets, and grade-over-time history.

• If the endpoint is yours: claim it free with claim_start(url) → claim_confirm on https://live-vps.sasame.online/public-mcp.
• If you prefer GitHub: open the claim template at https://github.com/shigeki7777/sasame-mcp-observatory/issues/new?template=claim-passport.yml.
• If you are checking a peer: use the grade as a mechanical pre-flight only; it is not a malware scan, endorsement, or quality verdict.

Activation: discovered is not the same as called

A good grade means agents can call your server — not that they do. Crawlers and directories may DISCOVER a server (fetch its tools/list) without any agent ever CALLING its tools.

• Free — activation baseline. The hosted Observatory publishes what it has actually observed: discovery events vs. real tool calls. Find your server at https://live-vps.sasame.online/observatory/check/, or connect the SaSame public MCP (https://live-vps.sasame.online/public-mcp) and call start_here() for the guided baseline. Measurement only — the numbers can be zero, and a baseline is not an endorsement or a promise of traffic.
• Paid — activation repair ($99, one-time). SaSame repairs the mechanical reasons agents skip a server and delivers before/after external-call evidence from the same baseline. If no baseline can be produced for your server, you get a refund. https://buy.stripe.com/14A9ATbezeuicyBdED1ZS1p
• Boundary: measurement, not endorsement. No adoption guarantees — the evidence shows what changed in observed external calls, not a promised outcome.

Gold Rush v1 handoff (optional)

Beyond the local grade, mcp-readiness can drive SaSame's Gold Rush Agent Package over the public MCP — one guided journey that records what happened to an MCP: a package record, a visibility baseline, a runtime-health snapshot, a Visibility Report, and a replayable receipt. Directories list MCPs. Gold Rush records what happened to them.

npx mcp-readiness gold-rush start  https://mcp.example.com/mcp    # create/identify a package -> package_id
npx mcp-readiness gold-rush run    <package-id>                   # advance one deterministic safe step
npx mcp-readiness gold-rush status <package-id>                   # read append-only package state
npx mcp-readiness gold-rush report <package-id>                   # produce the Visibility Report

• Add --json for machine output, --goal <preset> on start (e.g. quick_claim, visibility_check), or --endpoint <url> to target another SaSame public MCP.
• No API key. The public surface is free and needs no token; this CLI sends no credentials.
• Boundaries (non-negotiable): measurement record, not endorsement · claim status, not identity/KYC verification · runtime health, not a security verdict · receipt, not a fiscal invoice or payment guarantee.
• No payment: these commands never trigger live settlement, DNS changes, wallet publication, external account creation, legal, or KYC actions.
• Methodology (what is / is not measured): https://live-vps.sasame.online/observatory/methodology.html

The existing npx mcp-readiness <url> audit works exactly as before — Gold Rush mode is purely additive.

The 10 criteria

Each is bound to the MCP spec or a direct measurement — not taste. Grade: A ≥10 · B ≥8 · C ≥5 · D below. (A server that never returns verifiable content is capped at B — honesty cap.)

| | Criterion | Bound to | |---|---|---| | C1 | Protocol handshake conformance | initialize returns protocolVersion + capabilities | | C2 | Tool listability | tools/list returns result.tools[] | | C3 | Tool object validity | valid name + non-empty description + typed inputSchema | | C4 | Description sufficiency | every desc ≥12 chars, median ≥20, ≥60% distinct | | C5 | Safety annotation presence | a boolean hint (readOnlyHint/destructiveHint/…) on ≥50% of tools | | C6 | Liveness & latency | 2xx initialize < 5000 ms | | C7 | Returns real content (anti-ghost) | a read-only tool returns substantive, non-echo content; priced/x402 → UNVERIFIED | | C8 | Machine-discoverable identity | serverInfo name + version | | C9 | Token efficiency | tools/list payload < 40 KB | | C10 | Honest error behavior | unknown method → structured JSON-RPC error, not a hang |

It also runs an advisory directory pre-flight mapping to documented mechanical reject reasons for the Claude Connectors and ChatGPT Apps directories (missing titles/annotations, promotional or generic tool names, missing privacy-policy signal). About to submit? The directory pre-flight guide lists what each directory checks — and what's out of scope (privacy-policy content, identity verification, OAuth), so you handle those yourself.

Safety

mcp-readiness only calls tools that declare readOnlyHint: true (or, if none do, it probes the first tool with empty arguments only — it never fabricates arguments for a tool whose safety is undeclared, so it won't trigger a write). It never pays an x402 invoice; a priced tool is reported as delivery UNVERIFIED, not failed.

How the C7 / "ghost" check stays honest

A read-only tool that rejects synthetic arguments (input validation) is not a ghost — it's doing its job. mcp-readiness samples up to three read-only tools and only reports "no real content" when a tool returns empty on a genuine empty-args call. A validation error or a trivial echo of synthetic input is reported as UNVERIFIED, never as a defect.

Grade-over-time

mcp-readiness measures your server right now — something you can reproduce yourself. The SaSame MCP Observatory (free, no key) is the hosted companion that has crawled and re-measured thousands of public MCP servers over time, so it can tell you how a server's grade moved across days (improving / degrading), with ed25519-signed, offline-verifiable certificates. This CLI runs the same criteria the Observatory uses.

License & what's open vs. what's the service

The CLI is MIT — use it, fork it, sell it, wire it into your build. Copying the code is encouraged; that's the point. The 10 criteria and the grading logic are open by design.

What forking the code doesn't give you is the hosted SaSame MCP Observatory: the continuous re-measurement of thousands of public MCP servers over time, the longitudinal grade-over-time history (improving / degrading), and the ed25519-signed certificates — anyone can verify a certificate offline, but only SaSame issues them. This CLI grades a server right now (something you can reproduce yourself); the Observatory is the service that remembers how it moved.

MIT © SaSame SRL.