JSON Contracts

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 JSON_CONTRACTS_DIR 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 JSON_CONTRACTS_DIR 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": [] }

Adopt in your agent/app

Use json-contracts as a local contract/validation tool beside the model your app already uses.

1. Add the MCP server

If your agent host supports MCP, add the server config above and point JSON_CONTRACTS_DIR at the contracts folder your app owns.

If your app has its own agent runtime, connect to the same MCP stdio server and call the tools directly. The important part is the flow, not the host.

2. Write one contract per JSON behavior

Create files such as:

json-contracts/support-ticket.json

json-contracts/real-estate-lead.json json-contracts/chart-generation.json

Each file contains:

• schema for the final JSON shape
• rules for app-specific mapping behavior
• examples for model guidance
• optional operations for create/edit behavior

3. Pass app/system variables as context

Do not hide runtime variables in the user prompt. Pass them as context:

{

"contract": "real-estate-lead", "input": "I'm pre-approved for a 4 bedroom house in Durham NC up to 900k.", "context": { "current_datetime": "2026-05-03T00:00:00Z", "email": "JohnnyAppleseed@gmail.com", "source": "website-lead-form" } }

json-contracts passes context through unchanged. Contracts decide how to use it through rules/examples. The final JSON still must match the schema.

4. Give your agent this tool policy

Use this as the system/developer instruction for your agent:

When converting natural language into app JSON, use json-contracts.

Create flow:

1. Call get_json_contract with contract, input, and context.
2. Generate JSON using the returned schema, rules, examples, input, and context.
3. Call validate_json.
4. If invalid, call get_repair_contract, repair the JSON, and validate again.
5. Return only validated JSON to the app.

Edit flow:

1. Call get_edit_contract with contract, currentJson, input, and context.
2. Return the complete updated object, not a patch.
3. Call validate_json.
4. Repair and validate again if needed.

Never skip validation. Never add fields that are not allowed by the schema. Do not copy context fields into output unless the schema allows them and the contract rules say to use them.

5. Runtime loop in your app

At request time, your app should do:

user input + app context

-> get_json_contract or get_edit_contract -> your chosen model generates JSON -> validate_json -> if invalid: get_repair_contract -> model repairs -> validate_json -> app consumes valid JSON

The MCP server does not call the model and does not mutate output. Your app/agent remains in control of model choice, provider keys, context, and business defaults.

Contract files

Each contract is one .json file in json-contracts/.

The contract name is derived from the filename:

json-contracts/support-ticket.json -> support-ticket

There is no manifest file and no manually maintained resources file. Git handles versioning.

Contract shape

{

"description": "Convert natural language into a support ticket object.", "rules": [ "If the user says urgent, severity must be critical.", "Summary must be under 80 characters.", "Category must be authentication, billing, bug, feature_request, or other." ], "operations": { "create": { "enabled": true }, "edit": { "enabled": true, "return": "full_object", "rules": [ "Start from currentJson.", "Apply only the user's requested change.", "Preserve all unspecified fields exactly.", "Return the complete updated JSON object." ] } }, "schema": { "type": "object", "additionalProperties": false, "properties": { "summary": { "type": "string", "maxLength": 80 }, "severity": { "type": "string", "enum": ["low", "medium", "high", "critical"] }, "category": { "type": "string", "enum": ["authentication", "billing", "bug", "feature_request", "other"] } }, "required": ["summary", "severity", "category"] }, "examples": [ { "input": "Urgent, users cannot log in after SSO update.", "output": { "summary": "Users cannot log in after SSO update", "severity": "critical", "category": "authentication" } } ] }

Rules:

• schema is required and must be valid JSON Schema. Omit $schema for the default 2020-12 validator, or set $schema to draft-07 or 2020-12 explicitly.
• description is optional but recommended.
• rules is optional and defaults to [].
• examples is optional and defaults to []. Example output values must validate against schema.
• operations is optional and defaults to enabled create and edit operations. Operation metadata belongs at the top level, not inside the JSON Schema.
• name is optional, but the filename is the source of truth.
• A version field is rejected; use Git for versioning.
• Contract files are plain JSON.

Included example contracts

The default json-contracts/ folder includes examples from different app categories where teams commonly rebuild the same AI glue code:

Each one uses the same MCP tools: read the contract, let the model create or edit JSON, validate it, and repair if needed. New apps should not need a new bespoke prompt framework just to get reliable JSON.

MCP resources

Every loaded contract is exposed dynamically as:

json-contract://{contractName}

Examples:

json-contract://support-ticket

json-contract://create-filter json-contract://chart-generation

resources/list returns all loaded contracts. resources/read returns the normalized full contract JSON.

Stable MCP tools

list_contracts

Input:

{}

Output:

{

"contracts": [ { "name": "support-ticket", "description": "Convert natural language into a support ticket object.", "contractHash": "sha256:...", "schemaHash": "sha256:..." } ] }

read_contract

Input:

{

"contract": "support-ticket" }

Returns the selected contract's description, rules, operations, schema, examples, contractHash, and schemaHash.

Hashes are deterministic SHA-256 values over the normalized contract/schema payload. They are for logging, cache keys, and audit trails; contract files still use Git for versioning.

get_json_contract

Input:

{

"contract": "support-ticket", "input": "Urgent, users cannot log in after SSO update.", "context": {} }

Output:

{

"contract": "support-ticket", "contractHash": "sha256:...", "schemaHash": "sha256:...", "operation": "create", "instructions": [ "Convert the input into JSON.", "Return JSON only.", "Do not return markdown.", "Do not include commentary.", "Do not include extra keys.", "Match the schema exactly.", "Use enum values exactly.", "Follow all rules.", "Use examples as guidance." ], "description": "Convert natural language into a support ticket object.", "rules": [ "If the user says urgent, severity must be critical.", "Summary must be under 80 characters.", "Category must