JSON Contracts MCP server

JSON Contracts MCP Server

JSON Contracts is a local MCP contract server for natural-language-to-JSON workflows. It gives agents Git-controlled JSON contracts, rules, examples, and JSON Schema validation tools so any model can reliably convert natural-language requests into schema-valid JSON.

The MCP server does not call an LLM provider. The MCP server does not need API keys. The MCP server does not use BAML, LangChain, Markdown, or a DSL. The MCP server does not use MCP sampling. The MCP server does not generate JSON by itself.

The optional Studio is a separate package/repo for live demos and local contract testing. The MCP stdio server itself does not call LLM providers.

Your user provides natural language. Your agent chooses the model. Your agent performs the natural-language-to-JSON conversion. json-contracts provides the contract and validates the result.

Correct mental model

Not this:

json-contracts = generator

This:

json-contracts = schema contract registry + validator

Like TypeScript:

developer writes code
TypeScript validates it

With json-contracts:

agent writes JSON
json-contracts validates it

Architecture

User
  ↓
Agent using whatever model the user picked
  ↓
json-contracts MCP server
  - lists available JSON contracts
  - returns schemas, rules, examples, and instructions
  - validates agent-produced JSON
  - returns repair contracts when validation fails
  ↓
Agent generates or repairs JSON itself
  ↓
App consumes valid JSON

The MCP server never performs natural-language-to-JSON conversion itself. It only provides contracts, validation, and repair guidance.

Install

Install globally:

npm install -g json-contracts
json-contracts --help

Or run without installing:

npx -y json-contracts@latest

The npm package is json-contracts; the installed CLI binary is still json-contracts.

30-second setup

Create a starter contract folder and validate it:

mkdir my-json-contracts
cd my-json-contracts
npx -y json-contracts@latest init
npx -y json-contracts@latest validate

Then add the MCP config below to your agent host. Point JSONCONTRACTSDIR at the json-contracts folder that init created.

Validate contracts in CI without starting MCP:

npx -y json-contracts@latest validate --contracts ./json-contracts
npx -y json-contracts@latest lint --strict --contracts ./json-contracts

By default, the server starts as a local stdio MCP server and loads contracts from:

./json-contracts

MCP config

{
  "mcpServers": {
    "json-contracts": {
      "command": "npx",
      "args": ["-y", "json-contracts@latest"],
      "env": {
        "JSON_CONTRACTS_DIR": "./json-contracts"
      }
    }
  }
}

Adding a new behavior only requires adding a new .json file to the contracts folder. No MCP config change is required.

MCP host config snippets

Most MCP hosts use the same stdio shape. Adapt paths for your machine and point JSONCONTRACTSDIR at your app-owned contracts folder.

Claude Desktop

{
  "mcpServers": {
    "json-contracts": {
      "command": "npx",
      "args": ["-y", "json-contracts@latest"],
      "env": {
        "JSON_CONTRACTS_DIR": "/absolute/path/to/json-contracts"
      }
    }
  }
}

Cursor / Windsurf / VS Code MCP-compatible hosts

{
  "mcpServers": {
    "json-contracts": {
      "command": "npx",
      "args": ["-y", "json-contracts@latest"],
      "env": {
        "JSON_CONTRACTS_DIR": "./json-contracts"
      }
    }
  }
}

Continue or generic stdio MCP clients

{
  "name": "json-contracts",
  "command": "npx",
  "args": ["-y", "json-contracts@latest"],
  "env": {
    "JSON_CONTRACTS_DIR": "./json-contracts"
  }
}

If npx startup is too slow or your host requires explicit executables, install globally and use:

{
  "command": "json-contracts",
  "args": []
}

Shortened. The full README is on GitHub.