Skip to content

About

Dependency-free validator for MCP server manifests (server.json) against the official MCP Registry schema. Built by an autonomous AI agent.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Use this GitHub action with your project
Add this Action to an existing workflow or create a new one
View on Marketplace

Repository files navigation

mcp-registry-lint

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.

Why

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.

Usage

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 record

Exit codes: 0 = no errors, 1 = validation errors, 2 = unreadable/malformed file.

Evidence records (--evidence, v0.4.0)

--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 $schema the subject declares.
  • Minimal reproduction per class — the smallest manifest that still triggers the class, re-linted by the tool itself; reproductionVerified plus disclosed reproductionResidualClasses provide 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.

Use in CI (GitHub Action)

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 root

The 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

What it checks (schema 2025-12-11)

Errors:

  • required top-level fields: name, description, version
  • name matches <namespace>/<server> (^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+$, 3–200 chars)
  • description 1–100 chars, title ≤100 chars, version ≤255 chars
  • websiteUrl / repository.url are http(s) URIs; repository requires url and source; repository.subfolder must be a clean relative path
  • packages require registryType, identifier, transport
  • package version must be specific: latest and ranges (^1.2.3, ~1.2.3, >=1.2.3, 1.x, 1.*) are rejected
  • fileSha256 required for mcpb packages; must be 64 lowercase hex chars
  • transport.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 argument valueHints, argument names, or environment variable names; in remote context from the transport's own variables object (unresolvable refs stay literal and break the endpoint)
  • arguments: type ∈ {named, positional}; named args require name; positional args require value or valueHint; isRepeated must be boolean
  • remotes: type ∈ {streamable-http, sse}, http(s) url required
  • env var / header entries require name; isRequired/isSecret must be booleans
  • variables map 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 value referencing {variables} with no variables map, or refs missing from it; variables defined but never referenced (dead config)
  • runtimeHint missing when runtimeArguments are present
  • icon mimeType outside the schema enum; sizes entries not WxH/any
  • manifest declares neither packages nor remotes

Validation against reality

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] and ai.alpic.test/[email protected] both ship "repository": {}, missing the schema-required url and source (verified against raw API payloads). The same X-API-Key warning recurred.

Tests

python3 test_mcp_registry_lint.py

73 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.

Status / roadmap

  • 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, mcpb fileSha256, 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-dogfooding self-lint CI workflow, examples/ fixtures. 64/64 tests pass.
  • v0.4 (2026-08-21): --evidence mode — 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).

About

Dependency-free validator for MCP server manifests (server.json) against the official MCP Registry schema. Built by an autonomous AI agent.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages