mcp-schema-lint

Validate an MCP server's registry manifest (server.json) and tools/list surface against the Official MCP Registry schema — before you publish.

Deterministic, zero-dependency, MIT, reads-only. The config/manifest-integrity DETECT side for MCP servers, in the same family as:

• mcp-benchmark-hygiene (audits grading config-leakage),
• harness-audit / cov-shield / env-precedence-check (agent-eval / CLI-config integrity).

mcp-schema-lint checks the server's own schema so it passes registry + client conformance — the natural companion to mcp-server builder work.

Why

The Official MCP Registry returns 422 for a description over 100 chars, requires a mcp-name: ownership line in the README for PyPI validation, and rejects manifests whose required fields drift from ServerDetail. These silent failures cost a publish cycle. mcp-schema-lint catches them in one command.

What it checks

Manifest (server.json) — against the official 2025-12-11 ServerDetail schema

signal	check
M1	required top-level fields present + typed: name, description, version
M2	description ≤ 100 chars (registry 422s over 100)
M3	repository.url is http(s)
M3b	packages[].transport.type is a known MCP transport (stdio, sse, http, streamable-http)
M4	version is semver-ish (no spaces / path chars)
M5	README has the mcp-name: <qualified-name> ownership line (PyPI/registry requirement)

Surface (tools/list)

signal	check
T1	tool names unique + non-empty (no duplicate-name tools)
T2	each tool has an inputSchema
T3	inputSchema.properties[].type is JSON-schema-legal

Usage

mcp-schema-lint server.json                 # lint one manifest
mcp-schema-lint --dir ./repos               # find + lint all server.json under a tree
mcp-schema-lint --tools-list ./tools.json   # validate a tools/list response

Exit: 0 = clean, 1 = error(s) found, 2 = usage / not found. Reads only.

Install

uv tool install git+https://github.com/sudo-ai-git/mcp-schema-lint
# or in place:
python3 mcp_schema_lint.py path/to/server.json

Verified

• 9-test suite (required-fields, desc-length>100, bad scheme, bad version, missing ownership line, duplicate tool names, illegal JSON type).
• Real-world clean on all 4 manifests I actually published to the Official Registry (mcp-skill-sec, mcp-verify-claim, mcp-benchmark-hygiene, mcp-secret-scrub).
• Schema sourced from the authoritative https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json (ServerDetail): top-level required is name/description/version only — transport/url nest under packages[]/repository.

Status

v0.1.0. MIT. Part of the same agent-trust family.