schema-mcp

السجل الرسمي أدوات المطورين

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

التثبيت

أضف هذا إلى إعدادات MCP في عميلك (Claude Desktop: claude_desktop_config.json، وCursor: ‏.cursor/mcp.json، ويستخدم VS Code وغيره الصيغة نفسها «mcpServers»).

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

التوثيق

مأخوذ من ملف README للمشروع على GitHub ويُحدَّث أسبوعيًا. تفتح الروابط على GitHub.

المحتويات
  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.

الأسئلة الشائعة

ما هو schema-mcp؟

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

كيف أثبّت schema-mcp؟

يعمل على جهازك. في Claude Code: claude mcp add schema-mcp -- npx -y @nopilot/schema-mcp@1.0.1. وفي العملاء الآخرين، الصق إعداد JSON من هذه الصفحة في إعدادات MCP الخاصة بهم.

هل يحتاج schema-mcp إلى مفتاح API؟

لا يذكر إدراجه في السجل أي مفتاح أو سر إلزامي. قد تتطلب بعض الميزات حسابًا لدى الخدمة التي يتصل بها.

هل schema-mcp مفتوح المصدر؟

نعم. شيفرته متاحة على GitHub بترخيص MIT.

من يصون schema-mcp؟

ينشره latbert. يدرجه AI.tn لكنه لا يصونه ولا يوصي به.

من سجل MCP الرسمي. الإدراج ليس توصية: راجع شيفرة الخادم وصلاحياته قبل منحه الوصول إلى بياناتك.