Dependency-free validator for MCP (Model Context Protocol) server manifests
(server.json) against the official MCP Registry schema
(2025-12-11). Catches broken manifests before you publish them to a
registry or hand them to a client.
Transparency notice: this project is built, tested, and maintained by an autonomous AI agent (Hermes, by Nous Research) operating in the Autonomous Income Research Lab. A human owner reviews and authorizes external actions.
The MCP registry/discovery niche is growing fast (measured: 879 GitHub repos,
repo growth 1.217/90d, HN attention growth 1.167/30d as of 2026-08-17 —
evidence in the lab's experiments/2026-08-17-second-niche-scan.md). Publishers
hand-write server.json; small mistakes (bad namespace, stdio transport with a
URL, missing remote URL) break discovery or installs. This linter encodes the
official schema rules plus convention checks, with zero dependencies.
python3 mcp_registry_lint.py path/to/server.json
python3 mcp_registry_lint.py path/to/server.json --json # machine-readable findings
python3 mcp_registry_lint.py path/to/server.json --evidence # portable evidence recordExit codes: 0 = no errors, 1 = validation errors, 2 = unreadable/malformed file.
--evidence packages a lint result as a portable evidence record for
maintainers and publishers — the difference between "the linter says so" and a
verifiable artifact:
- Per violation class, not per payload — findings are grouped into stable
class identifiers (
repository-incomplete,package-version-range, …). - Schema-version pinning — the record states both the schema the tool
validated against and the
$schemathe subject declares. - Minimal reproduction per class — the smallest manifest that still
triggers the class, re-linted by the tool itself;
reproductionVerifiedplus disclosedreproductionResidualClassesprovide false-positive accounting. - Machine-readable and diff-able — deterministic JSON (sorted keys, no timestamps), subject identified by sha256 of the exact bytes linted.
Record schema: evidenceRecordVersion: 1.0. Dogfooded against live registry
violators (2026-08-21): two production manifests shipping "repository": {}
produce verified 215-byte reproductions that correctly pin each subject's
declared schema version.
This repository is itself a composite GitHub Action — no installation needed:
- uses: actions/checkout@v4
- uses: baobabcat/[email protected]
with:
manifest: server.json # default; path relative to the repo rootThe step fails the job on validation errors (warnings are advisory) and writes
a job summary with the lint output. Requires only python3, present on all
GitHub-hosted runners. Dogfooded by this repo's own self-lint workflow,
which asserts the action both passes examples/valid-server.json and fails
examples/broken-server.json.
Example output:
[ERROR ] $.packages[0].transport.url: streamable-http transport requires a url
[WARNING] $.version: version 'latest' is not semver-shaped (e.g. 1.0.2)
1 errors, 1 warnings
Errors:
- required top-level fields:
name,description,version namematches<namespace>/<server>(^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+$, 3–200 chars)description1–100 chars,title≤100 chars,version≤255 charswebsiteUrl/repository.urlare http(s) URIs;repositoryrequiresurlandsource;repository.subfoldermust be a clean relative path- packages require
registryType,identifier,transport - package
versionmust be specific:latestand ranges (^1.2.3,~1.2.3,>=1.2.3,1.x,1.*) are rejected fileSha256required formcpbpackages; must be 64 lowercase hex charstransport.type∈ {stdio, streamable-http, sse}; stdio must not declare a URL; http/sse transports require an http(s) URL- URL template resolution: transport URL
{variables}must be resolvable — in package context from the package's argumentvalueHints, argument names, or environment variable names; in remote context from the transport's ownvariablesobject (unresolvable refs stay literal and break the endpoint) - arguments:
type∈ {named, positional}; named args requirename; positional args requirevalueorvalueHint;isRepeatedmust be boolean - remotes:
type∈ {streamable-http, sse}, http(s)urlrequired - env var / header entries require
name;isRequired/isSecretmust be booleans variablesmap entries must be Input objects- icons require an HTTPS
src
Warnings:
- missing
$schema; unknown top-level fields (custom metadata belongs in_meta) - non-semver
version; package version ≠ manifest version - unknown
registryType(outside npm/pypi/oci/nuget/mcpb) - env var names not in UPPER_SNAKE_CASE convention; named-arg names without leading dashes
- Input
valuereferencing{variables}with novariablesmap, or refs missing from it;variablesdefined but never referenced (dead config) runtimeHintmissing whenruntimeArgumentsare present- icon
mimeTypeoutside the schema enum;sizesentries not WxH/any - manifest declares neither
packagesnorremotes
Dogfooded on 100 live manifests from the official registry
(registry.modelcontextprotocol.io):
- v0.1 (2026-08-17): 0 false-positive errors, 1 legitimate warning
(an env var named
X-API-Key— a header-style name used as an environment variable). Raw data:experiments/dogfood-registry-lint/. - v0.2 (2026-08-18): 0 false positives; 2 manifests flagged with genuine
schema violations the registry API had accepted —
ai.agentrapay/[email protected]andai.alpic.test/[email protected]both ship"repository": {}, missing the schema-requiredurlandsource(verified against raw API payloads). The sameX-API-Keywarning recurred.
python3 test_mcp_registry_lint.py73 tests (stdlib unittest): valid manifests, every error/warning rule,
evidence-record mode (structure, per-class grouping, reproduction
verification, determinism), and CLI behavior including exit codes and
--json mode. No network needed.
- v0.1 (2026-08-17): schema 2025-12-11 core rules + convention checks, human and JSON output. 31/31 tests pass.
- v0.2 (2026-08-18):
{curly_braces}template-resolution checks for transport URLs and Input values, argument shape rules, mcpbfileSha256, version-range rejection, repository/icon checks, header templating. 64/64 tests pass. - v0.3 (2026-08-20): GitHub Action wrapper (
action.yml, composite — the repo itself is the action), job-summary output, self-dogfoodingself-lintCI workflow,examples/fixtures. 64/64 tests pass. - v0.4 (2026-08-21):
--evidencemode — portable, per-class evidence records with verified minimal reproductions and schema-version pinning (see above). 73/73 tests pass. - Next: official-registry publishing ruleset (namespace ownership hints).