mcpField
J
JSON Contracts

JSON Contracts

ローカル
github.com開発ツール125 週間前に更新

JSON Contracts について

JSON Contractsは、自然言語の依頼をJSONに変換するエージェント向けのローカルMCP契約レジストリ兼バリデーターです。スキーマ、ルール、例、検証手順を提供し、モデルの選択と実行はエージェントが担います。サーバー自身はJSONを生成せず、LLMプロバイダーも呼び出しません。

主な機能

  1. 01Git管理のJSON契約を読み込み
  2. 02スキーマ、ルール、例を提供
  3. 03生成JSONをスキーマで検証
  4. 04無効なJSON向けの修正ガイダンス
  5. 05作成と編集の操作に対応
  6. 06契約をMCPリソースとして公開

活用シーン

  1. 01サポート依頼を検証済みチケットに変換
  2. 02スキーマ準拠のAPIフィルターを作成
  3. 03アプリ向けに生成したJSONを検証
  4. 04契約の変更をGitで管理

MCP 対応

ローカルのstdio MCPサーバーとして、契約の一覧、読み取り、生成ガイダンス、編集、検証、修正のツールと契約リソースを提供します。LLMプロバイダーを呼び出さず、JSONも生成しません。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定
{
"mcpServers": {
"json-contracts-json-contracts": {
"command": "npx",
"args": [
"-y",
"json-contracts"
],
"env": {
"JSON_CONTRACTS_DIR": "<JSON_CONTRACTS_DIR>"
}
}
}
}
起動コマンドnpx -y json-contracts
設定が必要な環境変数
JSON_CONTRACTS_DIRFolder containing JSON contract files. Defaults to ./json-contracts.

ローカルサーバーにはマシン上の実行環境(Node.js 18 以上など)が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ
npmjson-contracts0.1.2

ツール

8

掲載時のツール一覧 · 3 週間前に更新

このツールにパラメーターはありません。

詳細

JSON Contracts MCP サーバー

JSON Contracts は、自然言語から JSON へのワークフロー向けのローカル MCP コントラクトサーバーです。エージェントに、Git で管理される JSON コントラクト、ルール、例、および JSON Schema 検証ツールを提供することで、あらゆるモデルが自然言語のリクエストをスキーマに準拠した JSON に確実に変換できるようにします。

MCP サーバーは LLM プロバイダーを呼び出しません。 MCP サーバーに API キーは必要ありません。 MCP サーバーは BAML、LangChain、Markdown、DSL を使用しません。 MCP サーバーは MCP サンプリングを使用しません。 MCP サーバー自体が JSON を生成することはありません。

オプションの Studio は、ライブデモとローカルでのコントラクトテスト用の別パッケージ/リポジトリです。MCP stdio サーバー自体が LLM プロバイダーを呼び出すことはありません。

ユーザーは自然言語を入力します。 エージェントがモデルを選択します。 エージェントが自然言語から 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 設定をエージェントホストに追加します。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": []
}

エージェント/アプリへの導入

アプリで既に使用しているモデルと併せて、json-contracts をローカルのコントラクト/検証ツールとして使用します。

1. MCP サーバーを追加する

エージェントホストが MCP に対応している場合は、上記のサーバー設定を追加し、JSON_CONTRACTS_DIR がアプリ所有のコントラクトフォルダーを指すようにします。

アプリに独自のエージェントランタイムがある場合は、同じ 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 はコンテキストを変更せずに渡します。コントラクトは、ルール/例を通じてその使用方法を決定します。最終的な JSON は、引き続きスキーマに一致する必要があります。

4. エージェントにこのツールポリシーを設定する

エージェントのシステム/開発者指示として、次の内容を使用します:

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 サーバーがモデルを呼び出すことも、出力を変更することもありません。モデルの選択、プロバイダーキー、コンテキスト、ビジネス上のデフォルト値は、引き続きアプリ/エージェントが管理します。

コントラクトファイル

各コントラクトは、json-contracts/ にある 1 つの .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 を省略するか、draft-07 または 2020-12 を明示的に設定してください。
  • description は任意ですが、設定を推奨します。
  • rules は任意で、省略した場合は [] がデフォルトです。
  • examples は任意で、省略した場合は [] がデフォルトです。例の output 値は schema に対して検証に合格する必要があります。
  • operations は任意で、省略した場合は create と edit の操作が有効になります。操作のメタデータはトップレベルに置き、JSON Schema の中には含めないでください。
  • name は任意ですが、正しい名前はファイル名を基準とします。
  • version フィールドは拒否されます。バージョン管理には Git を使用してください。
  • コントラクトファイルはプレーンな JSON です。

同梱のコントラクト例

デフォルトの json-contracts/ フォルダーには、チームが同じ AI のグルーコードを繰り返し作成しがちな、さまざまなアプリカテゴリの例が含まれています。

コントラクト業界/アプリのパターン自然言語から変換される内容
support-ticketSaaS サポートトリアージ対応のサポートチケット。
create-filter内部ツール/API ビルダーAPI フィルターオブジェクト。
chart-generationBI/分析ツールダッシュボードのチャート生成仕様。
patient-intake医療機関の受付トリアージおよび予約振り分け用オブジェクト。
ecommerce-returnEC サポート返品、返金、交換、保証のリクエスト。
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": {}
}

エージェント/モデルはこのコントラクトを使って 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": {}
}

エージェント/モデルはこの編集用コントラクトを使って、更新後の JSON オブジェクト全体を返します。MCP サーバーはまず currentJson を選択したコントラクトに照らして検証します。その後、エージェントは編集したオブジェクトを 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 を解釈、正規化したり、別のスキーマに照らして検証したりしません。モデルがコントラクトのルールおよび出力スキーマと併せて利用できるように、コントラクトのペイロード内でオブジェクトを変更せずに返します。

重要な動作:

  • 外部変数は input に隠しテキストとして追加せず、context に入れてください。
  • 最終的な 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": []
}

エージェント/モデルは、この修復コントラクトを使って修正済みの 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

これらのプロンプトは、エージェント/モデル向けにコントラクトテキストを表示するだけです。モデルを呼び出したり、MCP サーバー内で JSON を生成したりすることはありません。

正しいフロー

ユーザー:

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

エージェントが呼び出します:

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

MCP はスキーマ、ルール、例、指示、および入力を返します。

エージェント/モデルが生成します:

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

エージェントが呼び出します:

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

無効な場合、エージェントは get_repair_contract を呼び出し、自身のモデルを使って修復してから、再度 validate_json を呼び出します。

編集フロー

既存の JSON を編集する場合、エージェントは現在の 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
}

その後、エージェントは編集済みの最終オブジェクトを validate_json で検証します。

コントラクトの検証とリント用 CLI

MCP ホストを起動せずに、CI または pre-commit チェックで CLI を使います。

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

最小限のアプリ統合例

小さな Node MCP クライアントが examples/node-client に含まれています。アプリ側のループを示しています。

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 を参照してください。

ドキュメントサイトとコンテンツ戦略

docs/ フォルダーは、GitHub Pages の設定で /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_TRANSPORTstdioトランスポートです。v1 では stdio を実装しています。
PORT3000将来の HTTP トランスポート用に予約されています。
API_AUTH_TOKEN未設定将来の HTTP Bearer 認証用に予約されています。
DEBUGfalsestderr へのデバッグログ出力を有効にします。
WATCH_CONTRACTStrueローカルのコントラクトを監視し、変更時に再読み込みします。
ALLOW_INVALID_CONTRACTSfalsetrue の場合、無効なコントラクトを警告とともにスキップします。

Studio 専用の LLM プロバイダー変数については、別の json-contracts-studio リポジトリで説明しています。MCP stdio サーバーではこれらの変数を使用しません。

stdio モードでは、ログは stderr のみに書き込まれます。サーバーが stdout にログを書き込むことはありません。

セキュリティに関する注意事項

json-contracts の MCP サーバーは、次のことを行いません。

  • LLM プロバイダーを呼び出しません
  • プロバイダーの API キーを使用しません
  • MCP サンプリングを実行しません
  • コントラクトファイル内の内容を実行しません
  • eval を使用しません
  • コントラクトファイル内のコードをインポートまたは実行しません
  • DEBUG=true の場合を除き、ユーザー入力全体をログに記録しません
  • Zod を使用して MCP ツールの入力を検証します
  • コントラクトファイル、スキーマ、サンプルのサイズ制限を適用します
  • 安全でないコントラクト名とリソース URI を拒否します
  • パストラバーサルを防止します

オプションの独立した Studio は、ローカル UI または .env ファイルにキーを設定した場合にのみ LLM プロバイダーを呼び出すことができます。これらのプロバイダー呼び出しは 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 サポートはオプションです。デフォルトのコントラクトとともに stdio サーバーをパッケージ化するための Dockerfile のサンプルが含まれています。

コメント

MCP は初めてですか?

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。