schema-mcp

Official registry Developer tools

JSON Schema toolkit: version diff with breaking-change classification, draft-07/2020-12 validation

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

NPM package @nopilot/schema-mcp
Claude Code
claude mcp add schema-mcp -- npx -y @nopilot/schema-mcp@1.0.1
JSON configuration (Claude Desktop, Cursor, VS Code)
{
    "mcpServers": {
        "schema-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@nopilot/schema-mcp@1.0.1"
            ]
        }
    }
}

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. schema-diff-tools
  2. The local-first difference
  3. Tools (MCP)
  4. Install & run
  5. Engine usage (npm)
  6. Development
  7. Dependencies & licenses
  8. Publishing

schema-diff-tools

Deterministic JSON Schema tools for agents and humans: path-level diff + breaking-change classification + instance validation, as an npm engine (@nopilot/schema-diff-engine) plus a local-first MCP server (@nopilot/schema-mcp).

Why not just "ask the model"? LLMs are famously unreliable at "is this schema change backwards-compatible?" — they miss nested required additions and misjudge type narrowing. This engine answers deterministically: same input → byte-identical output, every time.

The local-first difference

The npm side proves the demand (json-schema-diff: ~270k weekly downloads); the MCP side is nearly empty — the closest existing server sees ~36 weekly visitors and validates single schemas only. Most hosted API-diff services upload your schemas to their gateway. Proprietary API contracts should not take that trip.

schema-mcp runs entirely on your machine:

hosted schema-diff servicesschema-mcp
Where your schemas gouploaded to their APInever leave the process
Works offlinenoyes
Breaking-change classificationvariesdeterministic, path-level
$ref handlingoften server-side fetchsame-document only, zero network
Source availablemostly closedMIT, full tests

Three hard guarantees (enforced by design and tests):

  1. Deterministic action tools, not AI wrappers — no LLM calls anywhere; identical input produces identical output.
  2. Pure local computation — zero network requests (external $refs are reported not_supported, never fetched), zero external data sources; the whole test suite runs offline.
  3. Runs locally, no hosted gateway — stdio or localhost HTTP, bind 127.0.0.1 by default.

Tools (MCP)

schema_diff

Two schema versions in → classified change list out. Each entry: path (JSON-pointer style), kind, severity (breaking / non_breaking / not_supported), description, old/new values.

Breaking: required addition, type narrowing or disjoint type change, enum value removal, minimum/maximum/minLength/minItems tightening, pattern change (conservatively breaking — regex re-acceptance is undecidable), format change/addition, required-property deletion, additionalProperties restriction, const change.

Non-breaking: optional property addition, type widening, constraint removal/loosening, enum addition, required removal.

not_supported is explicit, never silent: if/then/else/not/unevaluated* subtrees (severity depends on evaluation order), anyOf/oneOf/allOf variant-count changes (index-wise diff is meaningless), $id changes, external/dangling refs. Each carries a reason.

Same-document $ref / #definitions / $defs are inlined before diffing (cycles broken), so changes inside a $ref target are attributed to the referencing paths too.

schema_validate

Validate an instance document against a schema (draft-07 or 2020-12, auto-detected from $schema). Same-document $ref and standard formats (email, date-time, uri, …) supported. Sorted issues with instancePath/schemaPath/keyword.

Install & run

npm install -g @nopilot/schema-mcp
schema-mcp                          # stdio (default)
schema-mcp --transport http --port 9430   # stateless Streamable HTTP on 127.0.0.1

MCP client config (stdio):

{
  "mcpServers": {
    "schema": { "command": "schema-mcp" }
  }
}

Engine usage (npm)

import { diffSchemas, validateInstance } from '@nopilot/schema-diff-engine';

const r = diffSchemas(oldSchema, newSchema);
// → { changes: [{ path: '/properties/age/minimum', kind: 'minimum_tightened',
//     severity: 'breaking', description, old: 0, new: 18 }],
//     hasBreaking: true, breakingCount, nonBreakingCount, notSupportedCount,
//     dialect: { from, to } }

validateInstance(schema, { id: 'abc' });  // → { valid, issues: [...] }

Inputs may be objects, JSON strings, or local file paths (MCP layer).

Development

npm install
npm test              # build + typecheck + 36 vitest tests + determinism harness
npm run determinism   # byte-equality spot checks only
npm run publish:dry   # npm publish --dry-run for both packages

Dependencies & licenses

Runtime dependencies (mature, permissive, maintained; no GPL/AGPL anywhere in the tree):

packageversionlicenserole
ajv^8.20.0MITJSON Schema validation engine (draft-07 + 2020-12 builds)
ajv-formats^3.0.1MITstandard format vocabulary for ajv
@modelcontextprotocol/sdk^1.32.2MITofficial MCP TypeScript SDK (server only)
zod^4.6.7MITtool input schema
express^5.2.1MITHTTP transport host

All transitive runtime dependencies are MIT/Apache-2.0/ISC. (Diff/classification logic is dependency-free — first-party code only; ajv powers schema_validate.)

License of this project: MIT (see LICENSE).

Publishing

This repo ships to zero registries by itself. See PUBLISH.md for the manual npm publish + MCP registry submission steps.

Frequently asked questions

What is schema-mcp?

JSON Schema toolkit: version diff with breaking-change classification, draft-07/2020-12 validation

How do I install schema-mcp?

It runs on your machine. In Claude Code: claude mcp add schema-mcp -- npx -y @nopilot/schema-mcp@1.0.1. For other clients, paste the JSON configuration from this page into their MCP settings.

Does schema-mcp need an API key?

Its registry entry lists no required key or secret. Some features may still need an account with the service it connects to.

Is schema-mcp open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains schema-mcp?

It is published by latbert. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.