{
  "markdown": "# JSON Contracts MCP Server\n\nJSON 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.\n\nThe MCP server does not call an LLM provider.\nThe MCP server does not need API keys.\nThe MCP server does not use BAML, LangChain, Markdown, or a DSL.\nThe MCP server does not use MCP sampling.\nThe MCP server does not generate JSON by itself.\n\nThe optional Studio is a separate package/repo for live demos and local contract testing. The MCP stdio server itself does not call LLM providers.\n\nYour user provides natural language.\nYour agent chooses the model.\nYour agent performs the natural-language-to-JSON conversion.\n`json-contracts` provides the contract and validates the result.\n\n## Correct mental model\n\nNot this:\n\n```text\njson-contracts = generator\n```\n\nThis:\n\n```text\njson-contracts = schema contract registry + validator\n```\n\nLike TypeScript:\n\n```text\ndeveloper writes code\nTypeScript validates it\n```\n\nWith `json-contracts`:\n\n```text\nagent writes JSON\njson-contracts validates it\n```\n\n## Architecture\n\n```text\nUser\n  ↓\nAgent using whatever model the user picked\n  ↓\njson-contracts MCP server\n  - lists available JSON contracts\n  - returns schemas, rules, examples, and instructions\n  - validates agent-produced JSON\n  - returns repair contracts when validation fails\n  ↓\nAgent generates or repairs JSON itself\n  ↓\nApp consumes valid JSON\n```\n\nThe MCP server never performs natural-language-to-JSON conversion itself. It only provides contracts, validation, and repair guidance.\n\n## Install\n\nInstall globally:\n\n```bash\nnpm install -g json-contracts\njson-contracts --help\n```\n\nOr run without installing:\n\n```bash\nnpx -y json-contracts@latest\n```\n\nThe npm package is `json-contracts`; the installed CLI binary is still `json-contracts`.\n\n## 30-second setup\n\nCreate a starter contract folder and validate it:\n\n```bash\nmkdir my-json-contracts\ncd my-json-contracts\nnpx -y json-contracts@latest init\nnpx -y json-contracts@latest validate\n```\n\nThen add the MCP config below to your agent host. Point `JSON_CONTRACTS_DIR` at the `json-contracts` folder that `init` created.\n\nValidate contracts in CI without starting MCP:\n\n```bash\nnpx -y json-contracts@latest validate --contracts ./json-contracts\nnpx -y json-contracts@latest lint --strict --contracts ./json-contracts\n```\n\nBy default, the server starts as a local stdio MCP server and loads contracts from:\n\n```text\n./json-contracts\n```\n\n## MCP config\n\n```json\n{\n  \"mcpServers\": {\n    \"json-contracts\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"json-contracts@latest\"],\n      \"env\": {\n        \"JSON_CONTRACTS_DIR\": \"./json-contracts\"\n      }\n    }\n  }\n}\n```\n\nAdding a new behavior only requires adding a new `.json` file to the contracts folder. No MCP config change is required.\n\n### MCP host config snippets\n\nMost MCP hosts use the same stdio shape. Adapt paths for your machine and point `JSON_CONTRACTS_DIR` at your app-owned contracts folder.\n\n#### Claude Desktop\n\n```json\n{\n  \"mcpServers\": {\n    \"json-contracts\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"json-contracts@latest\"],\n      \"env\": {\n        \"JSON_CONTRACTS_DIR\": \"/absolute/path/to/json-contracts\"\n      }\n    }\n  }\n}\n```\n\n#### Cursor / Windsurf / VS Code MCP-compatible hosts\n\n```json\n{\n  \"mcpServers\": {\n    \"json-contracts\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"json-contracts@latest\"],\n      \"env\": {\n        \"JSON_CONTRACTS_DIR\": \"./json-contracts\"\n      }\n    }\n  }\n}\n```\n\n#### Continue or generic stdio MCP clients\n\n```json\n{\n  \"name\": \"json-contracts\",\n  \"command\": \"npx\",\n  \"args\": [\"-y\", \"json-contracts@latest\"],\n  \"env\": {\n    \"JSON_CONTRACTS_DIR\": \"./json-contracts\"\n  }\n}\n```\n\nIf `npx` startup is too slow or your host requires explicit executables, install globally and use:\n\n```json\n{\n  \"command\": \"json-contracts\",\n  \"args\": []\n}\n```\n\n## Adopt in your agent/app\n\nUse `json-contracts` as a local contract/validation tool beside the model your app already uses.\n\n### 1. Add the MCP server\n\nIf your agent host supports MCP, add the server config above and point `JSON_CONTRACTS_DIR` at the contracts folder your app owns.\n\nIf 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.\n\n### 2. Write one contract per JSON behavior\n\nCreate files such as:\n\n```text\njson-contracts/support-ticket.json\njson-contracts/real-estate-lead.json\njson-contracts/chart-generation.json\n```\n\nEach file contains:\n\n- `schema` for the final JSON shape\n- `rules` for app-specific mapping behavior\n- `examples` for model guidance\n- optional `operations` for create/edit behavior\n\n### 3. Pass app/system variables as `context`\n\nDo not hide runtime variables in the user prompt. Pass them as `context`:\n\n```json\n{\n  \"contract\": \"real-estate-lead\",\n  \"input\": \"I'm pre-approved for a 4 bedroom house in Durham NC up to 900k.\",\n  \"context\": {\n    \"current_datetime\": \"2026-05-03T00:00:00Z\",\n    \"email\": \"JohnnyAppleseed@gmail.com\",\n    \"source\": \"website-lead-form\"\n  }\n}\n```\n\n`json-contracts` passes context through unchanged. Contracts decide how to use it through rules/examples. The final JSON still must match the schema.\n\n### 4. Give your agent this tool policy\n\nUse this as the system/developer instruction for your agent:\n\n```text\nWhen converting natural language into app JSON, use json-contracts.\n\nCreate flow:\n1. Call get_json_contract with contract, input, and context.\n2. Generate JSON using the returned schema, rules, examples, input, and context.\n3. Call validate_json.\n4. If invalid, call get_repair_contract, repair the JSON, and validate again.\n5. Return only validated JSON to the app.\n\nEdit flow:\n1. Call get_edit_contract with contract, currentJson, input, and context.\n2. Return the complete updated object, not a patch.\n3. Call validate_json.\n4. Repair and validate again if needed.\n\nNever 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.\n```\n\n### 5. Runtime loop in your app\n\nAt request time, your app should do:\n\n```text\nuser input + app context\n  -> get_json_contract or get_edit_contract\n  -> your chosen model generates JSON\n  -> validate_json\n  -> if invalid: get_repair_contract -> model repairs -> validate_json\n  -> app consumes valid JSON\n```\n\nThe 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.\n\n## Contract files\n\nEach contract is one `.json` file in `json-contracts/`.\n\nThe contract name is derived from the filename:\n\n```text\njson-contracts/support-ticket.json -> support-ticket\n```\n\nThere is no manifest file and no manually maintained resources file. Git handles versioning.\n\n### Contract shape\n\n```json\n{\n  \"description\": \"Convert natural language into a support ticket object.\",\n  \"rules\": [\n    \"If the user says urgent, severity must be critical.\",\n    \"Summary must be under 80 characters.\",\n    \"Category must be authentication, billing, bug, feature_request, or other.\"\n  ],\n  \"operations\": {\n    \"create\": {\n      \"enabled\": true\n    },\n    \"edit\": {\n      \"enabled\": true,\n      \"return\": \"full_object\",\n      \"rules\": [\n        \"Start from currentJson.\",\n        \"Apply only the user's requested change.\",\n        \"Preserve all unspecified fields exactly.\",\n        \"Return the complete updated JSON object.\"\n      ]\n    }\n  },\n  \"schema\": {\n    \"type\": \"object\",\n    \"additionalProperties\": false,\n    \"properties\": {\n      \"summary\": {\n        \"type\": \"string\",\n        \"maxLength\": 80\n      },\n      \"severity\": {\n        \"type\": \"string\",\n        \"enum\": [\"low\", \"medium\", \"high\", \"critical\"]\n      },\n      \"category\": {\n        \"type\": \"string\",\n        \"enum\": [\"authentication\", \"billing\", \"bug\", \"feature_request\", \"other\"]\n      }\n    },\n    \"required\": [\"summary\", \"severity\", \"category\"]\n  },\n  \"examples\": [\n    {\n      \"input\": \"Urgent, users cannot log in after SSO update.\",\n      \"output\": {\n        \"summary\": \"Users cannot log in after SSO update\",\n        \"severity\": \"critical\",\n        \"category\": \"authentication\"\n      }\n    }\n  ]\n}\n```\n\nRules:\n\n- `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.\n- `description` is optional but recommended.\n- `rules` is optional and defaults to `[]`.\n- `examples` is optional and defaults to `[]`. Example `output` values must validate against `schema`.\n- `operations` is optional and defaults to enabled `create` and `edit` operations. Operation metadata belongs at the top level, not inside the JSON Schema.\n- `name` is optional, but the filename is the source of truth.\n- A `version` field is rejected; use Git for versioning.\n- Contract files are plain JSON.\n\n## Included example contracts\n\nThe default `json-contracts/` folder includes examples from different app categories where teams commonly rebuild the same AI glue code:\n\n| Contract | Industry/app pattern | Converts natural language into |\n| --- | --- | --- |\n| `support-ticket` | SaaS support | Triage-ready support tickets. |\n| `create-filter` | Internal tools/API builders | API filter objects. |\n| `chart-generation` | BI/analytics tools | Dashboard chart generation specs. |\n| `patient-intake` | Healthcare intake | Triage and appointment-routing objects. |\n| `ecommerce-return` | Ecommerce support | Return, refund, exchange, and warranty requests. |\n| `real-estate-lead` | Real estate CRM | Buyer, renter, seller, and lease lead profiles. |\n| `legal-client-intake` | Legal tech intake | Matter routing and conflict-check data. |\n| `expense-report` | Finance/expense apps | Reimbursement and expense line items. |\n\nEach 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.\n\n## MCP resources\n\nEvery loaded contract is exposed dynamically as:\n\n```text\njson-contract://{contractName}\n```\n\nExamples:\n\n```text\njson-contract://support-ticket\njson-contract://create-filter\njson-contract://chart-generation\n```\n\n`resources/list` returns all loaded contracts. `resources/read` returns the normalized full contract JSON.\n\n## Stable MCP tools\n\n### `list_contracts`\n\nInput:\n\n```json\n{}\n```\n\nOutput:\n\n```json\n{\n  \"contracts\": [\n    {\n      \"name\": \"support-ticket\",\n      \"description\": \"Convert natural language into a support ticket object.\",\n      \"contractHash\": \"sha256:...\",\n      \"schemaHash\": \"sha256:...\"\n    }\n  ]\n}\n```\n\n### `read_contract`\n\nInput:\n\n```json\n{\n  \"contract\": \"support-ticket\"\n}\n```\n\nReturns the selected contract's description, rules, operations, schema, examples, `contractHash`, and `schemaHash`.\n\nHashes 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.\n\n### `get_json_contract`\n\nInput:\n\n```json\n{\n  \"contract\": \"support-ticket\",\n  \"input\": \"Urgent, users cannot log in after SSO update.\",\n  \"context\": {}\n}\n```\n\nOutput:\n\n```json\n{\n  \"contract\": \"support-ticket\",\n  \"contractHash\": \"sha256:...\",\n  \"schemaHash\": \"sha256:...\",\n  \"operation\": \"create\",\n  \"instructions\": [\n    \"Convert the input into JSON.\",\n    \"Return JSON only.\",\n    \"Do not return markdown.\",\n    \"Do not include commentary.\",\n    \"Do not include extra keys.\",\n    \"Match the schema exactly.\",\n    \"Use enum values exactly.\",\n    \"Follow all rules.\",\n    \"Use examples as guidance.\"\n  ],\n  \"description\": \"Convert natural language into a support ticket object.\",\n  \"rules\": [\n    \"If the user says urgent, severity must be critical.\",\n    \"Summary must be under 80 characters.\",\n    \"Category must be authentication, billing, bug, feature_request, or other.\"\n  ],\n  \"operationRules\": [],\n  \"schema\": {},\n  \"examples\": [],\n  \"operationExamples\": [],\n  \"input\": \"Urgent, users cannot log in after SSO update.\",\n  \"context\": {}\n}\n```\n\nThe agent/model uses this contract to produce JSON. The MCP server does not produce it.\n\n### `get_edit_contract`\n\nInput:\n\n```json\n{\n  \"contract\": \"create-filter\",\n  \"currentJson\": {\n    \"status\": \"open\",\n    \"limit\": 50\n  },\n  \"input\": \"we want the last 20 closed tickets\",\n  \"context\": {}\n}\n```\n\nOutput:\n\n```json\n{\n  \"contract\": \"create-filter\",\n  \"contractHash\": \"sha256:...\",\n  \"schemaHash\": \"sha256:...\",\n  \"operation\": \"edit\",\n  \"instructions\": [\n    \"Start from currentJson.\",\n    \"Apply only the user's requested change.\",\n    \"Preserve all unspecified fields exactly.\",\n    \"Return the complete updated JSON object, not a patch.\",\n    \"Return JSON only.\"\n  ],\n  \"description\": \"Convert natural language into a structured API filter object.\",\n  \"rules\": [\n    \"Only include fields that are explicitly requested or clearly implied.\"\n  ],\n  \"operationRules\": [\n    \"Preserve all unspecified fields exactly.\"\n  ],\n  \"schema\": {},\n  \"examples\": [],\n  \"operationExamples\": [],\n  \"currentJson\": {\n    \"status\": \"open\",\n    \"limit\": 50\n  },\n  \"input\": \"we want the last 20 closed tickets\",\n  \"context\": {}\n}\n```\n\nThe agent/model uses this edit contract to return the complete updated JSON object. The MCP server first validates `currentJson` against the selected contract, and the agent should validate the edited object with `validate_json` afterward.\n\n#### Context and system variables\n\n`context` is an intentional pass-through object for app/system variables that should help the model interpret the user's input.\n\nExamples:\n\n```json\n{\n  \"contract\": \"real-estate-lead\",\n  \"input\": \"I'm pre-approved for a 4 bedroom house in Durham NC up to 900k. We need a pool and a large backyard for dogs. We are looking to move this summer.\",\n  \"context\": {\n    \"current_datetime\": \"2026-05-03T00:00:00Z\",\n    \"email\": \"JohnnyAppleseed@gmail.com\"\n  }\n}\n```\n\n`json-contracts` does not interpret, normalize, or validate `context` against a separate schema. It returns the object unchanged in the contract payload so the model can use it with the contract rules and output schema.\n\nImportant behavior:\n\n- Put external variables in `context`, not by appending hidden text to `input`.\n- The final JSON must still match the contract schema.\n- Context fields should not appear in the final JSON unless the contract schema allows them.\n- Contracts can define how to use context through `rules`, examples, and schema shape.\n- Relative values such as \"this summer\" or \"last week\" should be resolved by the model using whatever date/time/location context the app provides.\n\n### `validate_json`\n\nInput:\n\n```json\n{\n  \"contract\": \"support-ticket\",\n  \"json\": {\n    \"summary\": \"Users cannot log in after SSO update\",\n    \"severity\": \"critical\",\n    \"category\": \"authentication\"\n  }\n}\n```\n\nSuccess:\n\n```json\n{\n  \"valid\": true,\n  \"contract\": \"support-ticket\",\n  \"json\": {\n    \"summary\": \"Users cannot log in after SSO update\",\n    \"severity\": \"critical\",\n    \"category\": \"authentication\"\n  },\n  \"errors\": []\n}\n```\n\nFailure:\n\n```json\n{\n  \"valid\": false,\n  \"contract\": \"support-ticket\",\n  \"errors\": [\n    {\n      \"path\": \"/severity\",\n      \"message\": \"must be equal to one of the allowed values\",\n      \"keyword\": \"enum\"\n    }\n  ]\n}\n```\n\n`valid` is never `true` unless Ajv validates the JSON against the contract schema.\n\n### `get_repair_contract`\n\nInput:\n\n```json\n{\n  \"contract\": \"support-ticket\",\n  \"invalidJson\": {\n    \"summary\": \"Users cannot log in\",\n    \"severity\": \"urgent\"\n  },\n  \"validationErrors\": []\n}\n```\n\nOutput:\n\n```json\n{\n  \"contract\": \"support-ticket\",\n  \"contractHash\": \"sha256:...\",\n  \"schemaHash\": \"sha256:...\",\n  \"instructions\": [\n    \"Repair the JSON so it validates against the schema.\",\n    \"Return JSON only.\",\n    \"Do not return markdown.\",\n    \"Do not include commentary.\",\n    \"Do not include extra keys.\",\n    \"Preserve valid fields where possible.\"\n  ],\n  \"schema\": {},\n  \"rules\": [],\n  \"examples\": [],\n  \"invalidJson\": {},\n  \"validationErrors\": []\n}\n```\n\nThe agent/model uses this repair contract to produce corrected JSON. The MCP server does not repair by calling a model. When validation errors are available, `instructions` also includes deterministic field-specific repair hints such as adding missing required fields, removing extra fields, or choosing allowed enum values.\n\n### `status`\n\nInput:\n\n```json\n{}\n```\n\nOutput:\n\n```json\n{\n  \"server\": \"json-contracts\",\n  \"version\": \"0.1.0\",\n  \"contractsDir\": \"/absolute/path/to/json-contracts\",\n  \"loaded\": 3,\n  \"contracts\": [\n    {\n      \"name\": \"support-ticket\",\n      \"description\": \"Convert natural language into a support ticket object.\",\n      \"contractHash\": \"sha256:...\",\n      \"schemaHash\": \"sha256:...\"\n    }\n  ],\n  \"watchContracts\": true,\n  \"allowInvalidContracts\": false\n}\n```\n\nUse this to debug host configuration, loaded contracts, and the exact contract/schema hashes in use.\n\n### `reload_contracts`\n\nInput:\n\n```json\n{}\n```\n\nOutput:\n\n```json\n{\n  \"loaded\": 3,\n  \"contracts\": [\"support-ticket\", \"create-filter\", \"chart-generation\"]\n}\n```\n\n## Optional MCP prompts\n\nThe server also exposes reusable prompt helpers for MCP hosts that support prompts:\n\n- `json_contract_prompt`\n- `edit_contract_prompt`\n- `repair_contract_prompt`\n\nThese prompts only render contract text for the agent/model. They do not call a model and they do not generate JSON inside the MCP server.\n\n## Correct flow\n\nUser:\n\n```text\nCreate a support ticket: urgent, users cannot log in after SSO update.\n```\n\nAgent calls:\n\n```json\n{\n  \"tool\": \"get_json_contract\",\n  \"arguments\": {\n    \"contract\": \"support-ticket\",\n    \"input\": \"Urgent, users cannot log in after SSO update.\"\n  }\n}\n```\n\nMCP returns schema, rules, examples, instructions, and input.\n\nAgent/model produces:\n\n```json\n{\n  \"summary\": \"Users cannot log in after SSO update\",\n  \"severity\": \"critical\",\n  \"category\": \"authentication\"\n}\n```\n\nAgent calls:\n\n```json\n{\n  \"tool\": \"validate_json\",\n  \"arguments\": {\n    \"contract\": \"support-ticket\",\n    \"json\": {\n      \"summary\": \"Users cannot log in after SSO update\",\n      \"severity\": \"critical\",\n      \"category\": \"authentication\"\n    }\n  }\n}\n```\n\nMCP returns:\n\n```json\n{\n  \"valid\": true,\n  \"contract\": \"support-ticket\",\n  \"json\": {\n    \"summary\": \"Users cannot log in after SSO update\",\n    \"severity\": \"critical\",\n    \"category\": \"authentication\"\n  },\n  \"errors\": []\n}\n```\n\nIf invalid, the agent calls `get_repair_contract`, uses its own model to repair, and calls `validate_json` again.\n\n### Edit flow\n\nFor existing JSON, the agent calls `get_edit_contract` with the current JSON plus a natural-language change request:\n\n```json\n{\n  \"tool\": \"get_edit_contract\",\n  \"arguments\": {\n    \"contract\": \"create-filter\",\n    \"currentJson\": {\n      \"status\": \"open\",\n      \"limit\": 50\n    },\n    \"input\": \"we want the last 20 closed tickets\"\n  }\n}\n```\n\nThe model returns the complete edited object:\n\n```json\n{\n  \"status\": \"closed\",\n  \"limit\": 20\n}\n```\n\nThen the agent validates that final edited object with `validate_json`.\n\n## Contract validation and linting CLI\n\nUse the CLI in CI or pre-commit checks without starting an MCP host:\n\n```bash\njson-contracts validate --contracts ./json-contracts\n```\n\n`validate` loads every `.json` contract, checks the contract shape, validates the JSON Schema, and validates example outputs against the schema. It exits nonzero if any contract is invalid.\n\nFor advisory checks:\n\n```bash\njson-contracts lint --contracts ./json-contracts\njson-contracts lint --strict --contracts ./json-contracts\n```\n\n`lint` includes the same validation checks, then prints generic schema-quality warnings such as empty schemas, missing examples, object schemas without `additionalProperties:false`, or broad `additionalProperties:true`. `--strict` exits nonzero when warnings are found.\n\nBoth commands support machine-readable output:\n\n```bash\njson-contracts validate --json --contracts ./json-contracts\njson-contracts lint --json --strict --contracts ./json-contracts\n```\n\n## Minimal app integration example\n\nA tiny Node MCP client is included at [`examples/node-client`](examples/node-client). It shows the app-side loop:\n\n```text\nget_json_contract -> your model -> validate_json -> optional get_repair_contract -> your model -> validate_json\n```\n\nIt intentionally does not call an LLM provider. Replace its placeholder `getModelJson()` with your own model call.\n\n## Studio\n\nThe local web Studio is intentionally **not bundled with this MCP package**. It lives in a separate repo/package so the MCP server stays small, local, and focused.\n\nUse the Studio when you want a browser UI for testing contracts, provider-backed demos, manual repair loops, or drafting new contract files.\n\nFor a quick demo with starter contracts:\n\n```bash\nmkdir my-json-contracts\ncd my-json-contracts\nnpx -y json-contracts@latest init\nnpx -y json-contracts-studio@latest\n```\n\nRepository:\n\n```text\nhttps://github.com/json-contracts/json-contracts-studio\n```\n\n## Pi local integration\n\nThis repo also includes a project-local Pi extension at `.pi/extensions/json-contracts-mcp.ts`. It starts the local MCP stdio server and exposes the server tools to Pi as `jc_*` tools for manual testing.\n\nFrom this repo on Windows PowerShell:\n\n```powershell\nnpm run build\npi\n```\n\nThen try:\n\n```text\n/jc-status\n```\n\nSee [`docs/pi-integration.md`](docs/pi-integration.md) for the full setup and test prompts.\n\n## Documentation site and content strategy\n\nThe `docs/` folder can be published directly with GitHub Pages from the `/docs` branch folder setting.\n\n- [`docs/index.md`](docs/index.md) is the docs landing page.\n- [`docs/github-pages.md`](docs/github-pages.md) explains how to enable GitHub Pages.\n- [`docs/content-marketing-plan.md`](docs/content-marketing-plan.md) contains the short-form video/content plan for positioning `json-contracts` around structured output, MCP validation, and production-safe JSON flows.\n\n## Git-controlled behavior\n\nThe `json-contracts/` folder is the product surface.\n\n- Add behavior by adding a new `.json` file.\n- Edit behavior by editing an existing `.json` file.\n- Review behavior through Git pull requests.\n- Roll back behavior through Git.\n\nNo provider keys, SDKs, sampling, or MCP config changes are required when contracts change.\n\n## Environment variables\n\n| Variable | Default | Description |\n| --- | --- | --- |\n| `JSON_CONTRACTS_DIR` | `./json-contracts` | Folder containing contract `.json` files. |\n| `MCP_TRANSPORT` | `stdio` | Transport. v1 implements stdio. |\n| `PORT` | `3000` | Reserved for future HTTP transport. |\n| `API_AUTH_TOKEN` | unset | Reserved for future HTTP Bearer auth. |\n| `DEBUG` | `false` | Enables debug logging to stderr. |\n| `WATCH_CONTRACTS` | `true` | Watches local contracts and reloads on changes. |\n| `ALLOW_INVALID_CONTRACTS` | `false` | If true, invalid contracts are skipped with warnings. |\n\nStudio-only LLM provider variables are documented in the separate [`json-contracts-studio`](https://github.com/json-contracts/json-contracts-studio) repo. The MCP stdio server does not use them.\n\nIn stdio mode, logs are written to stderr only. The server never writes logs to stdout.\n\n## Security notes\n\nThe MCP server in `json-contracts`:\n\n- never calls an LLM provider\n- never uses provider API keys\n- never performs MCP sampling\n- never executes anything from contract files\n- never uses `eval`\n- never imports or executes code from contract files\n- never logs full user input unless `DEBUG=true`\n- validates MCP tool inputs with Zod\n- enforces contract file, schema, and examples limits\n- rejects unsafe contract names and resource URIs\n- prevents path traversal\n\nThe optional separate Studio can call LLM providers only when you configure a key in its local UI or `.env` file; those provider calls are not part of the MCP stdio server.\n\n## Licensing and trademarks\n\nProject owner: **Harry Giunta**.\n\nLicensing model:\n\n- Runtime code, docs, examples, tests, and project infrastructure are licensed under **Apache-2.0**. See [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE).\n- Official starter contracts in [`json-contracts/`](json-contracts/) are licensed under **Apache-2.0 OR MIT**, at your option. See [`json-contracts/LICENSE.md`](json-contracts/LICENSE.md).\n- Third-party or marketplace contract packs may use creator-selected licenses. They should include their own license file or license metadata and must not imply official status unless approved.\n\nThe project name **json-contracts** is subject to the trademark policy in [`TRADEMARKS.md`](TRADEMARKS.md). Copyright licenses do not grant trademark rights.\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md) for contribution licensing and project guidelines.\n\n## Development\n\n```bash\nnpm install\nnpm test\nnpm run build\nnpm run dev\n```\n\nRun the published package as an MCP stdio server:\n\n```bash\nnpx -y json-contracts@latest\n```\n\nOr from this repository:\n\n```bash\nnpm run dev\n```\n\n## Docker\n\nDocker support is optional. A sample Dockerfile is included for packaging the stdio server with its default contracts.\n",
  "bytes": 25176,
  "sha": "ef59eab5acc46ef3f021e36e3a710a8a561ef2f8f5c77551a6324f85d730f304",
  "repo_slug": "json-contracts/json-contracts",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_json_contracts_json_contracts_ba275aa7/readme"
}