validate

machinegrade validate

AI が生成した成果物を、使用する前にコントラクトに照らして検証します。

• json_schema — artifact を JSON Schema に照らして検証します（すべてのエラーを収集します）。
• openapi_response — OpenAPI 仕様内の指定された path + method + status に対応するレスポンススキーマに照らして、レスポンスボディを検証します。
• sql — 指定された方言における SQL 文字列の構文エラーを確認します。

各チェックはエラーではなく判定結果を返します：{valid, errors, latency_ms}。 成果物が有効かどうかにかかわらず、HTTP 200 を返します。不正なキー、未対応のタイプ、不正な形式の本文、上限超過など、本当に不正なリクエストのみ型付き HTTP エラーになります。

https://api.machinegrade.dev で公開中です — 無料プラン、セルフサービスのキー、30 秒でお試しいただけます（最初の例をご覧ください）。Hono 上に構築されており、同じコードベースを Cloudflare Workers（本番環境）と通常の Node（ローカル開発環境）で実行できます。また、ご自身でホストする場合に備えて MIT ライセンスを採用しています。

理由

JSON、API レスポンス、SQL を生成するエージェントには、結果を使う前に高速かつ低コストで、機械的に判定可能な合否チェックが必要です。これは、LLM を判定者として使う完全な呼び出しよりも低コストで、決定論的です。

ローカルで実行する

npm install
npm run dev
# machinegrade validate listening on http://localhost:8787

実行可能な例 3 件

1. curl

# Get an API key (live service — works as-is)
curl -s -X POST https://api.machinegrade.dev/keys \
  -H 'content-type: application/json' \
  -d '{"email": "[email protected]"}'
# => {"key":"sk_..."}

# Validate a JSON artifact against a JSON Schema
curl -s -X POST https://api.machinegrade.dev/v1/validate \
  -H 'content-type: application/json' \
  -H 'X-Api-Key: sk_...' \
  -d '{
    "type": "json_schema",
    "artifact": {"name": "Ada", "age": 30},
    "contract": {
      "schema": {
        "type": "object",
        "required": ["name", "age"],
        "properties": {"name": {"type": "string"}, "age": {"type": "number"}}
      }
    }
  }'
# => {"valid":true,"errors":[],"latency_ms":1}

2. Python（requests）

import requests

base = "http://localhost:8787"

key = requests.post(f"{base}/keys", json={"email": "[email protected]"}).json()["key"]

resp = requests.post(
    f"{base}/v1/validate",
    headers={"X-Api-Key": key},
    json={
        "type": "sql",
        "artifact": "SELECT id, name FROM users WHERE id = 1",
        "contract": {"dialect": "mysql"},
    },
)
print(resp.status_code, resp.headers.get("X-Calls-Remaining"), resp.json())

3. MCP 設定スニペット

mcp/server.ts は単一のツール validate を公開し、POST /v1/validate に転送します。MCP 対応クライアントを接続してください。

{
  "mcpServers": {
    "machinegrade-validate": {
      "command": "npx",
      "args": ["tsx", "mcp/server.ts"],
      "cwd": "/path/to/validate",
      "env": {
        "SANDBOX_URL": "http://localhost:8787",
        "SANDBOX_API_KEY": "sk_..."
      }
    }
  }
}

リモート接続

本番サービスでは、ローカルプロセスも npm のインストールも不要な MCP エンドポイントを、ストリーム可能な HTTP で直接公開しています。

POST https://api.machinegrade.dev/mcp

上記の stdio アダプターと同じ、単一の validate ツールです。 initialize と tools/list はキーなしで動作します（検出は匿名で可能です）。tools/call には X-Api-Key が必要です（REST API と同様に POST /keys から発行できます。無料プランと上限は共通です）。

Claude Code の場合：

claude mcp add --transport http validate https://api.machinegrade.dev/mcp --header "X-Api-Key: sk_..."

npm 経由の stdio アダプター（@machinegrade/validate、上記参照）は、ローカル／オフラインでの使用や HTTP トランスポートに対応していないクライアント向けに引き続き利用できます。

Claude Desktop：ワンクリックでインストール

最新の .mcpb バンドルを Releases からダウンロードし、ダブルクリックしてください。Claude Desktop はインストール時に API キーを尋ね、設定ファイルではなく OS のキーチェーン（macOS Keychain、Windows Credential Manager）に保存します。claude_desktop_config.json には何も書き込まれません。

まず無料のキーを発行してください（月 500 回）：

curl -s -X POST https://api.machinegrade.dev/keys \
  -H 'content-type: application/json' \
  -d '{"email": "[email protected]"}'

このバンドルは、ホストされた API を利用する軽量な stdio クライアントです：約 34 KB で、依存関係はバンドルされていません。セルフホストする場合は、拡張機能の API base URL 設定を独自のデプロイ先に指定すると、ツールはそちらに接続します。

API

完全なコントラクトについては public/openapi.yaml を、サービスの起動後に機械可読な概要（タイプ、上限、料金、エラーコード）を確認するには /v1/manifest をご覧ください。 /llms.txt は LLM エージェント向けの簡単な案内です。

エンドポイント	入力	出力
POST /keys	{email}	{key}
POST /v1/validate	ヘッダー X-Api-Key、本文 {type, artifact, contract?}	判定結果、ヘッダー X-Calls-Remaining
GET /v1/manifest	—	機能マニフェスト
GET /stats	ヘッダー X-Admin-Token	ファネル：keys_issued、active_callers、repeat_callers_7d、limit_hits、paid_requests
POST /v1/paid-request	ヘッダー X-Api-Key	有料アクセスへの関心を記録
GET /openapi.yaml、GET /llms.txt	—	静的ドキュメント
POST /mcp	MCP ストリーム可能 HTTP、tools/call にはヘッダー X-Api-Key	上記の「リモート接続」を参照

料金

• 無料プラン： 1 キーあたり月 500 回、レート制限は 1 分あたり 60 回です。
• 有料プラン： 無料枠を超えた分は 1 回あたり EUR 0.002 です — 近日開始予定。 POST /v1/paid-request から有料アクセスをリクエストしてください（X-Api-Key が必要です）。提供開始時にお知らせします。

エラー

すべてのエラーは型付き JSON — {code, message, hint, docs_url} です。自由形式の文字列ではありません。

コード	HTTP ステータス	発生条件
INVALID_KEY	401	X-Api-Key がない、または不明
LIMIT_EXCEEDED	402	無料プランの月間上限（500 回）を超過
UNSUPPORTED_TYPE	400	type が json_schema、openapi_response、sql のいずれでもない
MALFORMED_INPUT	400	リクエストボディがドキュメントに記載された形式と一致しない
RATE_LIMITED	429	1 つのキーで 1 分間に 60 回を超えるリクエスト

判定結果（{valid, errors, latency_ms}）はエラーではありません。無効なアーティファクトは通常想定される結果であり、HTTP 200 を返します。

アーティファクトの送信

artifact は JSON でエンコードされた文字列ではなく、JSON 値である必要があります。

{"type": "json_schema", "artifact": {"name": "Ada"}, "contract": {"schema": {"type": "object"}}}   // correct
{"type": "json_schema", "artifact": "{\"name\": \"Ada\"}", "contract": {"schema": {"type": "object"}}}  // wrong

type: "sql" の場合、アーティファクトは文字列、つまり SQL ステートメントそのものです。

MCP の呼び出し元が値を文字列化することはよくあり（ツールスキーマで artifact の型が宣言されるまでは Claude Desktop 経由でも同様でした）、サービスは限定的な範囲で誤った形式を許容します。artifact が文字列で、型が json_schema または openapi_response であり、コントラクトのトップレベルスキーマで宣言された型に string が含まれない場合、その文字列は検証前に JSON としてデコードされ、判定結果には "decoded_from_string": true が含まれます。このフィールドは追加されますが、{valid, errors, latency_ms} は変更されません。

文字列アーティファクトが正当なケースは多いため、それ以外の場合は意図的にデコードしません。

送信内容	コントラクトスキーマ	結果
"42"	{"type": "number"}	42 にデコードされ、valid: true、decoded_from_string: true
"42"	{"type": "string"}	そのまま、valid: true
"{\"a\":1}"	{"type": "string"}	そのまま、valid: true
"{\"a\":1}"	{"required": ["a"]}	そのまま — トップレベルに type がなく、意図が不明

ストレージ

src/storage.ts では、Storage インターフェースと 2 つの実装を定義しています。

• MemoryStorage — インメモリで完全に動作する実装です。npm run dev とテストスイートで使用します。
• D1Storage — schema.sql（keys、events テーブル）をバックエンドとする、実際の Cloudflare D1 バインディングです。本番環境で使用します。src/index.ts の Workers エントリーポイントが、最初のリクエスト時に DB バインディングから構築します。

新しい D1 データベースに schema.sql を適用するには、次のコマンドを実行します。

wrangler d1 execute machinegrade-validate-db --file=schema.sql          # local
wrangler d1 execute machinegrade-validate-db --file=schema.sql --remote # production

テスト

npm test          # vitest run, in-process via app.request(), MemoryStorage
npm run typecheck # tsc --noEmit

テストでは、キーの発行、各バリデーターの正常系と失敗ケース、型付きの 401/400/402/429 エラー、使用量計測の上限（テストで両方を注入できるため、実際のリクエストを何百回も繰り返す必要はありません）、および /stats のファネル集計をカバーします。

デプロイ

このサービスは Cloudflare Workers（Hono + D1 + Workers Static Assets）上で動作します。新しい Cloudflare アカウントでセルフホストするには、次の手順を実行します。

wrangler d1 create machinegrade-validate-db   # copy the returned database_id into wrangler.toml
wrangler d1 execute machinegrade-validate-db --file=schema.sql --remote
wrangler secret put ADMIN_TOKEN
wrangler deploy

次に、Cloudflare ダッシュボードまたは wrangler を使って、カスタムドメイン（例：api.machinegrade.dev）を Worker にバインドします。CLOUDFLARE_API_TOKEN と CLOUDFLARE_ACCOUNT_ID のリポジトリシークレットを設定し、.github/workflows/ci.yml の deploy ジョブのコメントを解除すると、main へのプッシュ時に CI からデプロイできます。

Workers への移植について、知っておくべき点が 2 つあります。

• GET /openapi.yaml と GET /llms.txt は ASSETS バインディング（wrangler.toml の [assets]。public/ を参照）によって配信されます。Cloudflare が Worker を呼び出さずに直接配信します。src/index.ts のルートは、ASSETS バインディングが存在しないローカルの Node 開発環境とテスト用のフォールバックです。
• json_schema および openapi_response バリデーターは ajv ではなく @cfworker/json-schema を使用します。Workers ランタイムでは new Function(...) によるスキーマのコンパイルが許可されていません。また、このスキーマは呼び出し元からリクエストごとに動的に渡されるため、ビルド時に事前コンパイルすることもできません。

ステータス

率直に言って、まだ初期段階です。このサービスは稼働中で、無料枠は実際に利用されており、有料プランが成り立つかどうかを測定しています。次のことは信頼していただけます。

• API の契約（/v1/validate のリクエスト／レスポンス形式、型付きエラーコード、判定の意味）は安定しています。互換性を損なう変更は、必ずバージョン付きのパス（/v2/...）で行い、予告なく変更することはありません。
• 無料枠（月 500 回）は継続します。
• 万が一サービスを終了する場合、告知から 90 日間はキーを引き続きご利用いただけます。また、バリデーターはこのリポジトリでオープンソースとして公開されているため、同じ動作をセルフホストできます。

現時点で最も参考になるのは、皆さまからのフィードバックや連携事例です。課題を作成するか、無料枠を超える利用が必要な場合は POST /v1/paid-request をご利用ください。