JSON Contracts

What JSON Contracts does

The JSON Contracts MCP server acts as a local registry and validator for structured output workflows. Each contract is stored as a separate .json file in a contracts folder, with the filename defining the contract name. A contract can contain a JSON Schema, descriptive rules, examples, and optional create or edit operation settings.

The server gives an agent the information needed to convert a natural-language request into application data, then checks the result against the declared schema. It does not perform the conversion itself, call an LLM provider, select a model, or mutate the generated output. The agent or application remains responsible for generation, repair, provider credentials, and business defaults.

This makes JSON Contracts useful for support tickets, leads, charts, or other behaviors where an application needs predictable JSON rather than free-form model text. Contracts can be versioned with Git because each behavior is represented by a file and no separate manifest is required.

How it works

A typical create flow starts with get_json_contract, passing the contract name, natural-language input, and optional runtime context. The response supplies the schema, rules, examples, input, and context for the agent to use when producing JSON. The agent then calls validate_json with its result.

If validation fails, the agent calls get_repair_contract, uses the returned guidance to correct the object, and validates it again. Edit workflows use get_edit_contract with the current JSON, requested change, and context. Contracts can require a complete updated object and preserve unspecified fields rather than returning a patch.

Context is passed through unchanged. Runtime values such as timestamps, email addresses, or source identifiers should be supplied as context instead of being hidden in the user prompt. Contract rules determine whether those values belong in the final output, which must still satisfy the schema.

Setup and configuration

Install the CLI globally with npm install -g json-contracts, or run it without a global installation using npx -y json-contracts@latest. The starter setup creates a contracts folder with json-contracts init; json-contracts validate checks the contract files.

By default, the MCP process starts as a local stdio server and reads contracts from ./json-contracts. Set JSON_CONTRACTS_DIR when the application uses another location. A typical host configuration runs npx -y json-contracts@latest and passes that environment variable. Installing globally allows the host to invoke the json-contracts executable directly.

Contract files can also be checked without starting MCP. Use validate --contracts <path> for validation and lint --strict --contracts <path> for strict linting. Adding a new behavior means adding another .json file; the MCP host configuration does not need to change.

Tools and capabilities

The JSON Contracts MCP server supports these documented operations:

• List available JSON contracts.
• Retrieve a contract with its schema, rules, examples, instructions, input, and context.
• Retrieve edit instructions using current JSON and a requested change.
• Validate agent-produced JSON against a contract schema.
• Return repair guidance for invalid JSON.

Schemas use JSON Schema, with the default validator targeting 2020-12 unless a contract explicitly selects draft-07 or 2020-12. Example outputs are expected to validate against their contract schema. Create and edit operations are enabled by default unless contract metadata changes that behavior.

Limitations and notes

The server does not generate JSON, call an LLM provider, require API keys, use MCP sampling, or depend on BAML, LangChain, Markdown, or a separate DSL. The optional Studio is a separate package and is not part of the MCP stdio server.

The agent must follow the intended sequence: obtain the contract, generate JSON, validate it, and repair invalid results when necessary. The server does not enforce that orchestration policy on its own. Contract authors must also ensure that rules, examples, operation metadata, and schemas agree; invalid example outputs or schemas will be caught during contract validation or linting.