Python Code Validator

Python コードバリデーター

Python が満たすべき例に照らして検証、修復、実行する MCP サーバーです。validate_python、repair_python、execute_python を https://api.statemind.ai/mcp の HTTP 経由で利用できます。無料のキーがあり、アカウントは不要です。

AI が生成した Python が、依頼どおりに動作することを証明するホステッドサービスです。意図をアサーションまたは doctest の行で指定すると、コードはネットワーク接続のない読み取り専用ファイルシステム内のコンテナーで実行され、すべての例に合格した場合にのみ修正案が返されます。QuixBugs の欠陥では、41% を修復し、77% については記述どおりに動作していないとして拒否します。修正済みプログラムに対する誤検知はなく、ruff と mypy はどの欠陥も検出しません（数値）。

意図を必要としないチェックも含まれています。構文と lint の診断、動的インポートや実行時の属性参照の背後に隠れた呼び出しも検出する AST セキュリティポリシー、bandit によるチェック、認証情報のスキャン、決定論的な修復を行い、1 つの判定とスコアを返します。同じ質問を 10 分以内に 2 回行うと、最初の回答が返され、料金はかかりません（x-msvc-repeat: 1）。

このリポジトリには、クライアント側の設定として MCP の設定、CI スクリプト、pre-commit フックが含まれています。サービス自体は https://api.statemind.ai で稼働するため、インストールもホストも不要です。

アカウントなしでキーを取得

curl -s -X POST https://api.statemind.ai/v1/keys
# {"api_key": "msvc_free_…", "tier": "free", "calls_per_day": 25, "modes": ["static"]}

UTC 日ごとに計量される静的チェックは 1 日 25 回まで、1 つのアドレスあたり取得できるキーは数個です。試用や小規模なプロジェクトでの実行には十分ですが、大量利用には向きません。各回答には利用枠の状態（x-quota-remaining、x-quota-reset）が含まれるため、クライアントは利用停止になる前に呼び出しを控えられます。

MCP

公式 MCP レジストリに ai.statemind/python-code-validator として登録されています。この名前は GitHub アカウントではなく、サービスを提供するドメインに基づいて検証されています。任意の MCP クライアントで、次のブロックを追加します。

{
  "mcpServers": {
    "python-code-validator": {
      "type": "http",
      "url": "https://api.statemind.ai/mcp",
      "headers": { "Authorization": "Bearer msvc_free_…" }
    }
  }
}

• Claude Code：claude mcp add --transport http python-code-validator https://api.statemind.ai/mcp --header "Authorization: Bearer msvc_free_…"
• Cursor：~/.cursor/mcp.json に同じブロックを追加します。
• VS Code / Copilot：.vscode/mcp.json の "servers" の下に追加します。

コマンドを起動するクライアントには、このリポジトリの stdio ブリッジを使います。HTTPS 経由で同じツールに転送します。

{
  "mcpServers": {
    "python-code-validator": {
      "command": "python3",
      "args": ["/path/to/python-code-validator/mcp_stdio.py"]
    }
  }
}

このリポジトリの Dockerfile でビルドするコンテナーとしても利用できます。

docker build -t python-code-validator .
docker run -i --rm -e VALIDATOR_API_KEY python-code-validator

Gemini CLI では、同じブリッジを拡張機能としてインストールします。利用を促す指示ファイルも含まれています。

gemini extensions install jkanselaar/python-code-validator

ツールは 3 つあり、コードに対する処理にちなんだ名前が付いています。

ツール	コードを実行するか	キー
validate_python	いいえ	無料
repair_python — fixed_code も返します	いいえ	有料
execute_python — サンドボックス内でも実行します	はい	有料

mode 引数を持つ従来の単一ツール python_code_validator も、すでに設定済みのクライアントから引き続き利用できますが、現在は一覧に表示されません。

コードが本来どう動作するはずだったかを伝える

上記のチェックはどれも、誤った答えを計算する関数を検出できません。それを検出できるのは意図だけであり、コードを依頼したエージェントだけがその意図を把握しています。そこで、意図も一緒に渡します。

{"code": "def bitcount(n): …", "mode": "execute",
 "options": {"examples": "assert bitcount(127) == 7"}}

doctest の行（>>> bitcount(127) に続けて 7）も同じように使えます。ソースにすでに記述されている >>> の例も同様です。execute_python はそれらをサンドボックスで実行します。例に合わない場合は python:example-mismatch エラーとなり、修復処理ではすべての例に合格した場合にのみ修正案が返されます。正しさを判断する隠しテスト入力がある実際のバグで構成された QuixBugs の欠陥セットでは、41% を修復し、77% については記述どおりに動作していないとして拒否します。修正済みプログラムに対する誤検知はありません。

同じ呼び出しを繰り返しても料金はかかりません。同じキーで同じ質問、つまり同じモード、同じコード、同じ例を尋ねると、すでに得た回答が x-msvc-repeat: 1 を付けて返されます。そのため、エージェントが各ステップで作業を検証しても、結果が変わるはずのない判定に料金が発生することはありません。

Claude Code プラグイン

指示は無視されることがありますが、フックは無視できません。このプラグインは、Claude Code が書き込みまたは編集した Python ファイルを、そのファイルが書かれたターン内にすべてチェックし、エラーをユーザーではなくモデルに返します。

/plugin marketplace add jkanselaar/python-code-validator
/plugin install python-code-validator@statemind

設定は不要です。初回使用時に無料キーを自動で作成し、保持します。受理されたファイルについては何も通知されません。却下されたファイルがあると、問題のある行を示してターンを停止します。また、同一のファイルを二度チェックすることはありません。このプラグイン自体の問題でセッションが終了することはありません。サービスに接続できない場合や利用枠を使い切った場合もターンは続行され、利用枠を増やす方法が表示されます。

無料枠ではなく有料キーを使うには VALIDATOR_API_KEY を設定し、独自のデプロイ先を指定するには VALIDATOR_URL を設定してください。このプラグインには、フックではできないことを補う validate-python スキルも含まれています。意図を例として示し、その例に照らしてコードを実行します。

Cursor フック

同じスクリプトを Cursor の postToolUse に接続します。判定結果は終了コードではなく、会話のコンテキストとして返されます。

mkdir -p .cursor/hooks
base=https://raw.githubusercontent.com/jkanselaar/python-code-validator/main
curl -sf $base/plugin/hooks/validate_written.py -o .cursor/hooks/validate_written.py
curl -sf $base/cursor/hooks.json -o .cursor/hooks.json

プロジェクトフックはプロジェクトのルートから実行されます。そのため、cursor/hooks.json のコマンドはルートからの相対パスになっています。代わりにすべてのプロジェクトに適用するフックにするには、スクリプトを ~/.cursor/hooks/ に置き、同じブロックを ~/.cursor/hooks.json に追加して、コマンドに python3 ./hooks/validate_written.py --cursor を指定します。

エージェントに使わせる

サーバーを設定するだけでは呼び出されません。呼び出すのは指示ファイルです。このリポジトリの AGENTS.md はそのためのテキストで、クライアントが読み込む名前を問わず、どのプロジェクトにも配置できるように書かれています。

mkdir -p .github
curl -sf https://raw.githubusercontent.com/jkanselaar/python-code-validator/main/AGENTS.md \
  | tee AGENTS.md CLAUDE.md GEMINI.md .github/copilot-instructions.md >/dev/null

Cursor では代わりにフロントマター付きのルールを読み込むため、別のファイルを使います。プロジェクトの .cursor/rules/ に .cursor/rules/python-code-validator.mdc をコピーしてください。

すでにある指示に一行追加するだけで済ませたい場合は、次の要約を使ってください。

コードを書く前に、コードがどう動くべきかを assert の例として書き、options.examples に渡してください。編集のたびに validate_python を呼び出し、関数が完成したら execute_python を一度呼び出してください。その関数の動作が変わるまでは、再度呼び出さないでください。呼び出し結果に fixed_code が含まれている場合は、それを採用してください。サービスが例に照らして実行済みです。valid: false で返されたコードを提示してはいけません。

CI

サービスがクライアントを提供するため、ワークフローでこのリポジトリをチェックアウトしたり、シークレットを用意したりする必要はありません。

- run: |
    curl -sf https://api.statemind.ai/v1/client -o validate.py
    python3 validate.py --changed-against "origin/${{ github.base_ref }}"

または、Marketplace のアクションとして利用できます。

permissions:
  contents: read
  pull-requests: write   # so the run can comment its result on the pull request
steps:
  - uses: jkanselaar/[email protected]
    with:
      api-key: ${{ secrets.VALIDATOR_API_KEY }}   # optional; free tier without it

変更された Python が検証され、問題のある行が差分に注釈として付けられます。構文エラーや安全でないパターンがある場合、ジョブは失敗します。サービスが完全に受け付けないファイル（200 kB の上限を超えるファイル）は、実行を失敗させる代わりに、警告を表示してスキップされます。

実行後、プルリクエストにはコメントが一つ残ります。後続のプッシュではコメントを繰り返し追加せず、既存のコメントを編集します。コメントには、何が受理され、何が修正され、その日の利用枠がどれだけ残っているかが記載されます。pull-requests: write がなければ何も書き込まれず、ジョブにも影響しません。comment: "false" を指定すると、コメントを無効にできます。

無料枠では、アクションはワークフローのキャッシュにキーを保存します。リポジトリごとに一日一つのキーを使うため、利用枠は実行単位ではなくリポジトリ単位で適用されます。api-key を設定すると、キャッシュは使われません。

Pre-commit

repos:
  - repo: https://github.com/jkanselaar/python-code-validator
    rev: v1.22.0
    hooks:
      - id: python-code-validator

クライアント自体

validate.py は標準ライブラリのみを使用するため、Makefile、git フック、コンテナから python validate.py file.py としても実行できます。

$ python3 validate.py service.py
::error file=service.py,line=88,title=SyntaxError::invalid syntax
FAIL service.py score=0.66

0/1 files accepted

VALIDATOR_API_KEY が設定されている場合はそれが使われ、設定されていない場合はクライアントが無料キーを作成します。VALIDATOR_KEY_FILE にパスを指定するとキーが保持され、複数回の実行で同じ利用枠を共有できます。別のデプロイ先を指定するには VALIDATOR_URL を設定してください。VALIDATOR_SOURCE には呼び出し元を指定しますが、この値は集計にのみ使われます。ワークフロー内での実行では、自動的に github-action として記録されます。

バッジ

プルリクエストのたびに Python のチェックを行うリポジトリは、そのことを示せます。

[![Python validated](https://img.shields.io/badge/python-validated-2ea44f?logo=python&logoColor=white)](https://api.statemind.ai/?src=badge)

HTTP

curl -s https://api.statemind.ai/v1/validate \
  -H "Authorization: Bearer $VALIDATOR_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"code": "def f(:\n    pass\n", "mode": "static"}'

mode は static、repair、または execute です。repair と execute には、設定済みのキーが必要です。送信されたコードはログに記録されません。

呼び出しが拒否された場合は対処方法が示されるため、尋ねる相手がいない呼び出し元でも自分で解決できます。

{"error": "payment_required",
 "remedy": {"action": "upgrade_key", "hint": "A free key covers static only. …"}}

呼び出し料金

無料キーでは、1 日あたり 25 回の静的チェックを利用できます。また、1 つのアドレスで取得できるキーは 1 日あたり数個までなので、この利用枠は継続的な利用向けではなく、試用向けです。利用枠を超えると、キーにクレジットが付与されます。静的チェックは 1 クレジット、修正は 3 クレジット、サンドボックスでの実行は 10 クレジットです。また、10 分以内に同じ呼び出しを繰り返した場合は、最初の結果が返され、料金はかかりません。

クレジットは、請求書の発行や問い合わせ先への連絡なしに、カードで購入できます。

curl -s -X POST https://api.statemind.ai/v1/keys/checkout \
  -H 'content-type: application/json' \
  -d '{"api_key": "'"$VALIDATOR_API_KEY"'", "credits": 500}'

Stripe Checkout ページが返されます。カード決済が完了すると、数秒後にはキーにクレジットが反映されます（500 クレジットは €10 です）。Gnosis ウォレットを持つエージェントは、ブラウザーを使わずに xDAI で支払うこともできます。GET /v1/pricing に両方の方法が記載されています。

例

examples/ には 3 つのファイルと、それらを送信するクライアントが含まれています。すべてのチェックに合格しても誤った数値を返す例、セキュリティポリシーによって拒否される例、サンドボックスで承認されて返される例です。

ライセンス

MIT。