JSON Contracts

JSON Contracts MCP 服务

JSON Contracts 是一个本地 MCP 合约服务，用于自然语言转 JSON 工作流。它为 Agent 提供受 Git 管理的 JSON 合约、规则、示例和 JSON Schema 验证工具，让任何模型都能可靠地将自然语言请求转换为符合 Schema 的 JSON。

MCP 服务不会调用 LLM 提供商。 MCP 服务不需要 API 密钥。 MCP 服务不使用 BAML、LangChain、Markdown 或 DSL。 MCP 服务不使用 MCP 抽样。 MCP 服务本身不会生成 JSON。

可选的 Studio 是一个独立的包／代码库，用于现场演示和本地合约测试。MCP stdio 服务本身不会调用 LLM 提供商。

用户提供自然语言。 Agent 选择模型。 Agent 执行自然语言转 JSON 的转换。 json-contracts 提供合约并验证结果。

正确的理解方式

不是这样：

json-contracts = generator

而是这样：

json-contracts = schema contract registry + validator

类似 TypeScript：

developer writes code
TypeScript validates it

使用 json-contracts：

agent writes JSON
json-contracts validates it

架构

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

MCP 服务本身绝不会执行自然语言转 JSON 的转换。它只提供合约、验证和修复指导。

安装

全局安装：

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

或者不安装直接运行：

npx -y json-contracts@latest

npm 包名为 json-contracts；安装后的 CLI 二进制文件仍名为 json-contracts。

30 秒完成设置

创建初始合约文件夹并进行验证：

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

然后将下方的 MCP 配置添加到 Agent 宿主。将 JSON_CONTRACTS_DIR 指向 init 创建的 json-contracts 文件夹。

无需启动 MCP，即可在 CI 中验证合约：

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

默认情况下，服务会以本地 stdio MCP 服务的形式启动，并从以下位置加载合约：

./json-contracts

MCP 配置

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

添加新行为只需在合约文件夹中添加一个新的 .json 文件。无需更改 MCP 配置。

MCP 宿主配置示例

大多数 MCP 宿主使用相同的 stdio 配置格式。请根据你的设备调整路径，并将 JSON_CONTRACTS_DIR 指向应用自有的合约文件夹。

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 的宿主

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

Continue 或通用 stdio MCP 客户端

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

如果 npx 启动太慢，或者宿主要求指定可执行文件，请全局安装并使用：

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

在你的 Agent／应用中采用

将 json-contracts 作为本地合约／验证工具，与应用已使用的模型搭配使用。

1. 添加 MCP 服务

如果你的 Agent 宿主支持 MCP，请添加上方的服务配置，并将 JSON_CONTRACTS_DIR 指向应用自有的合约文件夹。

如果应用有自己的 Agent 运行时，请连接到同一个 MCP stdio 服务并直接调用工具。关键在于工作流，而非宿主。

2. 为每种 JSON 行为编写一个合约

创建如下文件：

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

每个文件都包含：

• 用于定义最终 JSON 结构的 schema
• 用于定义应用专属映射行为的 rules
• 用于指导模型的 examples
• 可选的、用于定义创建／编辑行为的 operations

3. 将应用／系统变量作为 context 传入

不要将运行时变量隐藏在用户提示词中。应将其作为 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": "[email protected]",
    "source": "website-lead-form"
  }
}

json-contracts 会原样传递 context。合约通过规则／示例决定如何使用它。最终 JSON 仍必须符合 Schema。

4. 为 Agent 提供以下工具策略

将以下内容用作 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. 应用中的运行时循环

收到请求时，应用应执行以下操作：

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

MCP 服务不会调用模型，也不会修改输出。应用／Agent 仍可控制模型选择、提供商密钥、context 和业务默认值。

合约文件

每个合约都是 json-contracts/ 中的一个 .json 文件。

合约名称由文件名派生：

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

没有清单文件，也无需手动维护资源文件。版本控制由 Git 处理。

契约结构

{
  "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"
      }
    }
  ]
}

规则：

• schema 是必填项，且必须是有效的 JSON Schema。对于默认的 2020-12 验证器，请省略 $schema；或者将 $schema 显式设为 draft-07 或 2020-12。
• description 是可选项，但建议填写。
• rules 是可选项，默认为 []。
• examples 是可选项，默认为 []。示例中的 output 值必须通过 schema 验证。
• operations 是可选项，默认启用 create 和 edit 操作。操作元数据应放在顶层，而非 JSON Schema 内。
• name 是可选项，但文件名才是事实来源。
• 不接受 version 字段；请使用 Git 进行版本管理。
• 契约文件为纯 JSON。

内置示例契约

默认的 json-contracts/ 文件夹包含来自不同应用类别的示例，这些类别中，团队通常会重复构建相同的 AI 粘合代码：

契约	行业/应用模式	将自然语言转换为
support-ticket	SaaS 支持	可直接用于分流的支持工单。
create-filter	内部工具/API 构建器	API 过滤器对象。
chart-generation	BI/分析工具	仪表盘图表生成规范。
patient-intake	医疗接诊	分流和预约路由对象。
ecommerce-return	电商支持	退货、退款、换货和保修请求。
real-estate-lead	房地产 CRM	买家、租客、卖家和租赁线索档案。
legal-client-intake	法律科技接待	案件路由和利益冲突检查数据。
expense-report	财务/费用应用	报销和费用明细项。

每个示例都使用相同的 MCP 工具：读取契约，让模型创建或编辑 JSON，验证结果，并在需要时修复。新应用无需仅为获得可靠的 JSON 而另建专用的提示词框架。

MCP 资源

每个已加载的契约都会动态公开为：

json-contract://{contractName}

示例：

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

resources/list 会返回所有已加载的契约。resources/read 会返回规范化后的完整契约 JSON。

稳定的 MCP 工具

list_contracts

输入：

{}

输出：

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

read_contract

输入：

{
  "contract": "support-ticket"
}

返回所选契约的描述、规则、操作、架构、示例、contractHash 和 schemaHash。

哈希是基于规范化后的契约/架构负载计算得出的确定性 SHA-256 值。它们用于日志记录、缓存键和审计跟踪；契约文件仍使用 Git 进行版本管理。

get_json_contract

输入：

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

输出：

{
  "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 be authentication, billing, bug, feature_request, or other."
  ],
  "operationRules": [],
  "schema": {},
  "examples": [],
  "operationExamples": [],
  "input": "Urgent, users cannot log in after SSO update.",
  "context": {}
}

Agent/模型使用此契约生成 JSON。MCP 服务不会生成 JSON。

get_edit_contract

输入：

{
  "contract": "create-filter",
  "currentJson": {
    "status": "open",
    "limit": 50
  },
  "input": "we want the last 20 closed tickets",
  "context": {}
}

输出：

{
  "contract": "create-filter",
  "contractHash": "sha256:...",
  "schemaHash": "sha256:...",
  "operation": "edit",
  "instructions": [
    "Start from currentJson.",
    "Apply only the user's requested change.",
    "Preserve all unspecified fields exactly.",
    "Return the complete updated JSON object, not a patch.",
    "Return JSON only."
  ],
  "description": "Convert natural language into a structured API filter object.",
  "rules": [
    "Only include fields that are explicitly requested or clearly implied."
  ],
  "operationRules": [
    "Preserve all unspecified fields exactly."
  ],
  "schema": {},
  "examples": [],
  "operationExamples": [],
  "currentJson": {
    "status": "open",
    "limit": 50
  },
  "input": "we want the last 20 closed tickets",
  "context": {}
}

Agent/模型使用此编辑契约返回完整的更新后 JSON 对象。MCP 服务会先根据所选契约验证 currentJson，随后 Agent 应使用 validate_json 验证编辑后的对象。

上下文和系统变量

context 是一个有意保留的透传对象，用于传递有助于模型理解用户输入的应用/系统变量。

示例：

{
  "contract": "real-estate-lead",
  "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.",
  "context": {
    "current_datetime": "2026-05-03T00:00:00Z",
    "email": "[email protected]"
  }
}

json-contracts 不会解读、规范化 context，也不会根据单独的架构对其进行验证。它会在契约负载中原样返回该对象，以便模型结合契约规则和输出架构使用它。

重要行为：

• 将外部变量放入 context，不要将隐藏文本追加到 input。
• 最终 JSON 仍必须符合契约架构。
• 除非契约架构允许，否则上下文字段不应出现在最终 JSON 中。
• 契约可以通过 rules、示例和架构结构定义如何使用上下文。
• “今年夏天”或“上周”这类相对时间值，应由模型根据应用提供的日期/时间/位置上下文进行解析。

validate_json

输入：

{
  "contract": "support-ticket",
  "json": {
    "summary": "Users cannot log in after SSO update",
    "severity": "critical",
    "category": "authentication"
  }
}

成功：

{
  "valid": true,
  "contract": "support-ticket",
  "json": {
    "summary": "Users cannot log in after SSO update",
    "severity": "critical",
    "category": "authentication"
  },
  "errors": []
}

失败：

{
  "valid": false,
  "contract": "support-ticket",
  "errors": [
    {
      "path": "/severity",
      "message": "must be equal to one of the allowed values",
      "keyword": "enum"
    }
  ]
}

只有 Ajv 根据契约架构验证 JSON 通过时，valid 才会是 true。

get_repair_contract

输入：

{
  "contract": "support-ticket",
  "invalidJson": {
    "summary": "Users cannot log in",
    "severity": "urgent"
  },
  "validationErrors": []
}

输出：

{
  "contract": "support-ticket",
  "contractHash": "sha256:...",
  "schemaHash": "sha256:...",
  "instructions": [
    "Repair the JSON so it validates against the schema.",
    "Return JSON only.",
    "Do not return markdown.",
    "Do not include commentary.",
    "Do not include extra keys.",
    "Preserve valid fields where possible."
  ],
  "schema": {},
  "rules": [],
  "examples": [],
  "invalidJson": {},
  "validationErrors": []
}

Agent/模型使用此修复契约生成修正后的 JSON。MCP 服务不会通过调用模型来修复数据。当存在验证错误时，instructions 还会包含确定性的字段级修复提示，例如添加缺失的必填字段、移除多余字段或选择允许的枚举值。

status

输入：

{}

输出：

{
  "server": "json-contracts",
  "version": "0.1.0",
  "contractsDir": "/absolute/path/to/json-contracts",
  "loaded": 3,
  "contracts": [
    {
      "name": "support-ticket",
      "description": "Convert natural language into a support ticket object.",
      "contractHash": "sha256:...",
      "schemaHash": "sha256:..."
    }
  ],
  "watchContracts": true,
  "allowInvalidContracts": false
}

使用此工具调试主机配置、已加载的契约，以及当前使用的准确契约/架构哈希。

reload_contracts

输入：

{}

输出：

{
  "loaded": 3,
  "contracts": ["support-ticket", "create-filter", "chart-generation"]
}

可选 MCP 提示词

对于支持提示词的 MCP 主机，服务还提供可重复使用的提示词辅助工具：

• json_contract_prompt
• edit_contract_prompt
• repair_contract_prompt

这些提示词只会为 Agent/模型呈现契约文本。它们不会调用模型，也不会在 MCP 服务内生成 JSON。

正确流程

用户：

Create a support ticket: urgent, users cannot log in after SSO update.

Agent 调用：

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

MCP 返回架构、规则、示例、说明和输入。

Agent/模型生成：

{
  "summary": "Users cannot log in after SSO update",
  "severity": "critical",
  "category": "authentication"
}

Agent 调用：

{
  "tool": "validate_json",
  "arguments": {
    "contract": "support-ticket",
    "json": {
      "summary": "Users cannot log in after SSO update",
      "severity": "critical",
      "category": "authentication"
    }
  }
}

MCP 返回：

{
  "valid": true,
  "contract": "support-ticket",
  "json": {
    "summary": "Users cannot log in after SSO update",
    "severity": "critical",
    "category": "authentication"
  },
  "errors": []
}

如果无效，Agent 会调用 get_repair_contract，使用自己的模型进行修复，然后再次调用 validate_json。

编辑流程

对于现有 JSON，Agent 会使用当前 JSON 和自然语言变更请求调用 get_edit_contract：

{
  "tool": "get_edit_contract",
  "arguments": {
    "contract": "create-filter",
    "currentJson": {
      "status": "open",
      "limit": 50
    },
    "input": "we want the last 20 closed tickets"
  }
}

模型返回完整的编辑后对象：

{
  "status": "closed",
  "limit": 20
}

然后，Agent 使用 validate_json 验证最终编辑后的对象。

契约验证和 lint 命令行工具

无需启动 MCP 主机，即可在 CI 或提交前检查中使用命令行工具：

json-contracts validate --contracts ./json-contracts

validate 会加载所有 .json 契约，检查契约结构、验证 JSON Schema，并根据架构验证示例输出。只要有任何契约无效，它就会以非零状态码退出。

如需执行提示性检查：

json-contracts lint --contracts ./json-contracts
json-contracts lint --strict --contracts ./json-contracts

lint 会执行相同的验证检查，然后打印通用的架构质量警告，例如架构为空、缺少示例、对象架构未设置 additionalProperties:false，或 additionalProperties:true 范围过宽。发现警告时，--strict 会以非零状态码退出。

两种命令都支持机器可读输出：

json-contracts validate --json --contracts ./json-contracts
json-contracts lint --json --strict --contracts ./json-contracts

最小应用集成示例

examples/node-client 中包含一个小型 Node MCP 客户端，展示了应用端的循环流程：

get_json_contract -> your model -> validate_json -> optional get_repair_contract -> your model -> validate_json

此示例刻意不调用任何 LLM 提供商。请将占位函数 getModelJson() 替换为你自己的模型调用。

Studio

本地 Web Studio 不会与此 MCP 软件包一同打包。它位于单独的仓库/软件包中，以保持 MCP 服务小巧、本地化且专注。

如果你需要通过浏览器 UI 测试契约、运行由提供商支持的演示、手动执行修复流程或起草新的契约文件，请使用 Studio。

如需使用入门契约快速演示：

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

仓库：

https://github.com/json-contracts/json-contracts-studio

Pi 本地集成

此仓库还包含项目本地的 Pi 扩展 .pi/extensions/json-contracts-mcp.ts。它会启动本地 MCP stdio 服务，并将服务工具作为 jc_* 工具提供给 Pi，以便手动测试。

在此仓库中使用 Windows PowerShell：

npm run build
pi

然后尝试：

/jc-status

完整设置说明和测试提示词请参阅 docs/pi-integration.md。

文档站点和内容策略

通过 GitHub Pages 的 /docs 分支文件夹设置，可以直接发布 docs/ 文件夹。

• docs/index.md 是文档首页。
• docs/github-pages.md 说明如何启用 GitHub Pages。
• docs/content-marketing-plan.md 包含短视频/内容计划，介绍如何围绕结构化输出、MCP 验证和适用于生产环境的安全 JSON 流程来定位 json-contracts。

由 Git 控制行为

json-contracts/ 文件夹是产品界面。

• 添加新的 .json 文件以新增行为。
• 编辑现有 .json 文件以修改行为。
• 通过 Git 拉取请求审查行为。
• 通过 Git 回滚行为。

更改合约时，无需修改提供商密钥、SDK、采样或 MCP 配置。

环境变量

变量	默认值	描述
JSON_CONTRACTS_DIR	./json-contracts	存放合约 .json 文件的文件夹。
MCP_TRANSPORT	stdio	传输方式。v1 实现了 stdio。
PORT	3000	为未来的 HTTP 传输预留。
API_AUTH_TOKEN	unset	为未来的 HTTP Bearer 身份验证预留。
DEBUG	false	启用将调试日志写入 stderr。
WATCH_CONTRACTS	true	监视本地合约，并在发生更改时重新加载。
ALLOW_INVALID_CONTRACTS	false	如果为 true，则跳过无效合约并发出警告。

仅供 Studio 使用的大模型提供商变量记录在单独的 json-contracts-studio 仓库中。MCP stdio 服务不会使用这些变量。

在 stdio 模式下，日志仅写入 stderr。服务绝不会将日志写入 stdout。

安全说明

json-contracts 中的 MCP 服务：

• 绝不调用大模型提供商
• 绝不使用提供商 API 密钥
• 绝不执行 MCP 采样
• 绝不执行合约文件中的任何内容
• 绝不使用 eval
• 绝不导入或执行合约文件中的代码
• 除非 DEBUG=true，否则绝不记录完整的用户输入
• 使用 Zod 验证 MCP 工具输入
• 限制合约文件、架构和示例的大小
• 拒绝不安全的合约名称和资源 URI
• 防止路径遍历

只有在可选的独立 Studio 本地界面或 .env 文件中配置密钥后，它才会调用大模型提供商；这些提供商调用不属于 MCP stdio 服务。

许可和商标

项目所有者：Harry Giunta。

许可模式：

• 运行时代码、文档、示例、测试和项目基础设施均采用 Apache-2.0 许可。请参阅 LICENSE 和 NOTICE。
• json-contracts/ 中的官方入门合约采用 Apache-2.0 OR MIT 许可，你可以自行选择。请参阅 json-contracts/LICENSE.md。
• 第三方或市场合约包可采用创建者选择的许可。它们应包含自己的许可文件或许可元数据，且未经批准不得暗示其为官方内容。

项目名称 json-contracts 受 TRADEMARKS.md 中的商标政策约束。著作权许可不授予商标权。

有关贡献许可和项目指南，请参阅 CONTRIBUTING.md。

开发

npm install
npm test
npm run build
npm run dev

将已发布的软件包作为 MCP stdio 服务运行：

npx -y json-contracts@latest

或者从此仓库运行：

npm run dev

Docker

Docker 支持为可选项。项目包含一个示例 Dockerfile，用于将 stdio 服务与其默认合约打包。