Technical Answer Validator

技術回答バリデーター

AI エージェント向けの、小型で決定論的な回答レビュー ツールです。MCP stdio および REST API として利用できます。呼び出し元はそれぞれ、1 回の評価に使用する概念、許容される同義語、数値要件、回答テキストを指定します。質問バンクや回答コーパスは含まれていません。

これは学習を支援するツールであり、公式認定試験の採点ツールではありません。キーワードマッチングでは、意味的に正しい言い換えを見逃したり、表面的に一致する誤解を招く回答を受け入れたりすることがあります。ユーザーは、指定された採点基準とすべての結果を確認してください。

ローカルで実行する

Python 3.10 以降が必要です。REST サーバーは標準ライブラリを使用します。MCP アダプターは公式 Python SDK 2.2.0 を使用します。

$env:TAV_API_KEY = "replace-with-a-long-random-secret-at-least-24-characters"
python -m tav_api

サービスはデフォルトで 127.0.0.1:8080 で待ち受けます。変更するには、TAV_HOST と TAV_PORT を設定してください。ローカルの単一キー モードでは、24 文字以上の TAV_API_KEY が設定されていない場合、起動を拒否します。デプロイする場合は、python scripts/create_api_key.py CLIENT_ID を使って呼び出し元ごとに個別のキーを作成し、各クライアント ID と生成された SHA-256 ダイジェストを対応付けた JSON オブジェクトとして TAV_API_KEYS を設定してください。一度だけ表示される生のキーは、そのクライアントと共有して保管してください。このリポジトリには保存またはコミットしないでください。TAV_API_KEYS が設定されている場合は、TAV_API_KEY より優先されます。

AI エージェント向け MCP

コミット済みのロックファイルを使って、仮想環境に固定バージョンの MCP SDK 2.2.0 をインストールしてください。

uv sync --locked
.\.venv\Scripts\Activate.ps1

stdio MCP サーバーは、evaluate_answer(rubric, answer) という 1 つのツールを公開します。環境内の Python と mcp_server.py の絶対パスを指定して、MCP ホストを設定してください。Claude Desktop の設定例（パスを置き換えてください）：

{
  "mcpServers": {
    "technical-answer-validator": {
      "command": "C:\\path\\to\\technical-answer-validator\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\technical-answer-validator\\mcp_server.py"]
    }
  }
}

PyPI に公開した後は、uvx --from technical-answer-validator tav-mcp を使って実行してください。ローカル開発では、.venv の Python と mcp_server.py を使用してください。Codex CLI または別の MCP ホストでは、そのコマンドとスクリプトのパスを使って、stdio サーバーの設定を行ってください。ホストを再起動し、ツール一覧の表示と evaluate_answer の呼び出しを依頼してください。stdio トランスポートはユーザーのエージェントホスト上でローカルに動作するため、インターネットのエンドポイントや API キーは不要です。

Codex の TOML テンプレートは codex-mcp-config.example.toml、Claude Desktop の JSON テンプレートは claude-mcp-config.example.json です。2 つのプレースホルダーパスを絶対パスに置き換えてください。ホストの設定にこのブロックを統合してください。他の MCP サーバーやグローバル設定を上書きしないでください。

ローカル MCP 使用回数

MCP サーバーは、ツール呼び出し、評価の成功、無効なリクエスト、内部エラーのローカルな日別集計数を保持します。ルーブリックや回答のテキストは保存せず、ネットワーク経由で何かを送信することもありません。集計数は ~/.technical-answer-validator/usage.sqlite3（Windows：ユーザーのホームディレクトリ）に90日間保持されます。tav-mcp-stats を実行すると、JSON レポートが出力されます。集計を無効にするには、MCP サーバーの環境変数に TAV_ANALYTICS=off を設定します。別のローカルデータベースパスを選択するには、TAV_ANALYTICS_DB を設定します。ユーザーが自発的にレポートを共有しない限り、これらの集計数はユーザーのコンピューター上に保持されます。

メンテナーと匿名の使用回数を自発的に共有するには、この通知を確認したうえで、MCP サーバーの環境変数でリモートテレメトリーを有効にしてください。

TAV_TELEMETRY=on
TAV_TELEMETRY_URL=https://technical-answer-validator-telemetry.chl1591204.workers.dev/v1/event

リモートテレメトリーはデフォルトでオフです。有効にすると、各ツール呼び出しで、ランダムな永続インストール ID、パッケージのバージョン、結果（success、invalid_request、または error）のみが、設定された Cloudflare Worker に送信されます。ID はランダムで、ユーザー、デバイス、アカウントの識別子から生成されるものではありません。個人ではなく、個別のインストール数を推定するために使用します。回答、ルーブリック、ツールの出力、IP アドレス、ホスト名、リクエストの内容は、イベントペイロードに含まれません。リクエストを配信するため、Cloudflare は送信元の IP などのネットワーク接続メタデータを必然的に受け取りますが、当社の Worker はそれをログに記録したり保存したりしません。Analytics Engine はイベントデータを3か月間保持します。無効にするには TAV_TELEMETRY=off を設定し、必要に応じて ~/.technical-answer-validator/telemetry-id を削除してランダム ID をリセットしてください。テレメトリーに失敗しても、評価が中断されることはありません。

コレクターは上記の URL にデプロイされており、イベントは /v1/event でのみ受け付けます。集計使用状況を読み取るには、Worker を所有するアカウントの Account Analytics Read に制限した Cloudflare API トークンを作成し、このリポジトリから python scripts/query_telemetry.py を実行してください。スクリプトはトークンを表示も保存もせずに入力するよう求めます。レポートでは、呼び出しの合計数を UTC の日付、パッケージのバージョン、結果ごとに集計し、個別のインストール数を推定します。個人を特定するものではありません。トークンをソース管理、MCP 設定、コマンドラインに含めないでください。

PyPI 0.1.1 には、このオプトイン方式のテレメトリーコードは含まれていません。0.1.2 でパッケージユーザーが利用できるようになります。データ収集は、そのバージョンをインストールし、ユーザーが上記の両方の環境変数を明示的に有効にした後にのみ開始されます。ローカルのみで動作する tav-mcp-stats コマンドは、引き続き独立して利用できます。

リクエスト

POST /v1/evaluate

{
  "rubric": {
    "required_concepts": ["isolation", "lockout tag"],
    "accepted_synonyms": {"isolation": ["energy isolation"]},
    "numeric_requirements": [],
    "required_count": 2
  },
  "answer": "Apply energy isolation and attach a lockout tag."
}

accepted_synonyms のキーは、概念と完全に一致する必要があります。numeric_requirements は省略可能な配列で、[{"value":"10","unit":"kN","tolerance":"0"}] のように指定します。回答内の数値は、明示的な要件が指定されている場合にのみチェックされます。概念スコアは、一致した概念数 / required_count（デフォルトでは概念数）で、上限は1.0です。数値の不一致がある場合、スコアは50%減点されます。判定のしきい値は、correct >= 0.8、partial >= 0.4、それ以外は wrong です。

レスポンスとエラー

リクエストが成功すると、api_version、status、score、verdict、一致した概念／不足している概念、数値チェックの詳細、および review_required: true が返されます。

エラーは JSON { "error": { "code": "...", "message": "..." } } を使用します。ステータスには、400（無効なリクエスト）、401（キーがない、または無効）、404、405、413（本文が64 KiBを超過）、429（クライアント ID ごとに毎分60リクエスト超過）が含まれます。レート制限は、認証済みクライアント ID ごとに毎分60リクエストで、メモリ上に保持され、プロセスの再起動時にリセットされます。日別のリクエスト数／成功数／クライアントエラー数／レート制限数のカウンターは、回答テキストを含めずに SQLite に保存され、90日後に期限切れになります。GET /v1/usage は、呼び出し元の現在の UTC 日のカウントのみを返します。必要に応じて使用状況データのボリュームを保持、バックアップしてください。含まれるのはクライアント ID と集計情報のみです。

プライバシーとデプロイの制限

stdio MCP オプションはローカルで実行され、ユーザーが上記の説明に従ってリモートテレメトリを明示的に有効にしない限り、利用情報を中央サービスに送信しません。ローカルで集計した呼び出し回数は、別途無効にできます。REST API では、API クライアントごとにサーバー側の集計が行われます。

サーバーは、リクエスト本文や回答をログに記録しません。REST のレート制限のため、クライアント ID とリクエストのタイムスタンプをキーにした日次カウントをプロセスメモリに保存します。stdio MCP オプションはエージェントホスト内でローカルに実行され、この HTTP サーバーにはリクエストを送信しません。REST API はコンテナ化され、永続ボリュームに利用カウンターを保存します。公開サービスを開始する前に、リバースプロキシで TLS を終端し、プロキシレベルでレート制限と同時実行数制限を設定し、シークレットマネージャーからデプロイし、ホストを監視して、データ保持ポリシーと連絡先を公開してください。アプリケーションレベルのクライアントごとのレート制限は再起動時にリセットされるため、エッジ制御の代わりにはなりません。

検証

python -m unittest discover -s tests -v

OpenAPI コントラクトは openapi.yaml にあり、MCP Registry の公式ドラフト記述子は server.json にあります。公開手順については PUBLISHING.md を参照してください。.env.example を .env にコピーして秘密鍵を追加した後、Docker Compose でローカル実行します。Compose はサービスをループバックインターフェースでのみ公開するため、HTTPS リバースプロキシを別途設定してください。compose.yaml は名前付きボリュームに集計済みの利用情報を永続化し、読み取り専用のルートファイルシステム、Linux ケイパビリティの削除、およびリソース制限を適用します。

これらのテストで確認するのは API と採点の動作であり、専門試験における正確性を保証するものではありません。