mcpready

A readiness scorecard for MCP servers. Point it at a Model Context Protocol server and get a graded report where every finding cites the exact spec clause it checks (MUST / SHOULD), with a one-line fix.

npx mcpready scan node ./my-server.js

Not a security scanner and not a debugger: mcpready judges whether your server is correct and pleasant for an agent to use, and tells you precisely why, with a link to the rule in the spec.

What makes a finding trustworthy

Each rule carries its provenance. A failing check looks like this:

FAIL  base-ping-empty-result   ping result is not an empty object
  Top fix  Respond to ping with a success result of {} (an empty object).
  MUST: The receiver MUST respond promptly with an empty response.
  https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/ping

Rules that are not spec-mandated are labelled HEURISTIC so you always know whether a finding is a conformance failure or a quality suggestion.

Version aware

The MCP spec is a moving target (the discovery, session, and error-handling rules all changed between 2025-06-18 and 2025-11-25). mcpready reads the protocolVersion your server negotiates and applies the rule set for that revision, so it does not flag a server for a requirement that did not exist yet.

Usage

Scan a server (stdio command or Streamable HTTP URL):

mcpready scan node ./my-server.js         # stdio server you launch
mcpready scan https://mcp.example.com/mcp # remote Streamable HTTP server
mcpready scan <target> --json             # machine-readable report (stable schema)
mcpready scan <target> --min-grade B      # exit non-zero if the grade is below B (CI gate)
mcpready scan <target> --fail-on error    # exit non-zero on any failed error/warn check
mcpready scan <target> --timeout 5000

Other commands:

mcpready validate server.json             # validate against the official registry schema
mcpready card <target>                    # draft an (experimental) Server Card from the server
mcpready diff old.json new.json           # compare two scan --json reports (drift / rug-pull)
mcpready preflight <target> --target claude|openai   # connector-directory submission readiness

Exit codes: 0 pass, 1 grade below --min-grade / failing --fail-on severity (or diff found changes / preflight NOT READY), 2 usage/connection error.

Directory pre-flight

mcpready preflight checks the machine-verifiable submission requirements for the Claude connector directory and the OpenAI Apps directory (HTTPS transport, tool title + readOnly/destructive/openWorld hints, OAuth flow and S256 PKCE, widget MIME/CSP, metadata limits, privacy policy) and prints a READY / NOT READY checklist plus the non-machine-checkable items for human review.

mcpready preflight https://mcp.example.com/mcp --target claude \
  --server-json server.json --manifest manifest.json --privacy-url https://example.com/privacy

GitHub Action

Gate a PR on your server's grade and get a job-summary report + inline annotations:

- uses: codixus/mcpready/packages/action@v1
  with:
    target: https://mcp.example.com/mcp
    min-grade: B      # optional
    fail-on: error    # optional

See packages/action for all inputs.

What it checks

• Conformance - lifecycle/handshake, version negotiation, JSON-RPC error codes, ping, capability consistency.
• Transport - stdio stream discipline and framing; Streamable HTTP Origin validation, session-id semantics, content-type and protocol-version contracts.
• Tool quality - valid input schemas, name format/uniqueness, description quality, safety-annotation consistency.
• Context cost - the token weight of tools/list and outlier descriptions.
• Directory pre-flight - Claude / OpenAI connector-directory submission rules.
• Every check is either tied to a spec clause or labelled HEURISTIC.

Programmatic use

The rule engine ships separately as mcpready-core:

import { probeHttp, buildReport } from "mcpready-core";
const report = buildReport(await probeHttp("https://mcp.example.com/mcp"));
console.log(report.score.grade);

Status

stdio and Streamable HTTP scanning both work, with the conformance, transport, tool-quality and context-cost rule sets, validate / card / diff, full Claude/OpenAI directory pre-flight, and a GitHub Action. A hosted web checker is on the roadmap. The rules track the 2025-11-25 spec.

Develop

bun install
bun run typecheck
bun test
bun run lint

License

MIT