Llamator MCP Server

🚀 LLAMATORのMCPサーバー

LLMのレッドチーミングワークフローを自動化するMCPサーバーです。

🚀 クイックスタート

このリポジトリは、自動化されたLLMレッドチーミングのためのLLAMATORを中心とした本番向けサービスラッパーを提供します。2つの統合インターフェースを公開しています。

• HTTP API (FastAPI)：ジョブの送信、ジョブ状態の取得、およびアーティファクトのアクセスに使用します。
• MCPサーバー (Streamable HTTP transport)：エージェント/ツールの統合に使用し、LLAMATORの実行をツールとして呼び出せるようにします。

実行は非同期で、ARQ + Redisを介して調整されます。アーティファクトはMinIOにアップロードされ、署名付きURLを介して取得されます（JSONとして返され、APIはリダイレクトしません）。

✨ 主な機能

• Redisに永続的な状態を保存する非同期テスト実行。
• シークレットを削除したリクエストの永続化：
  • APIキーは平文で保存されません。
  • 保存されるペイロードには、ブールマーカー（例：api_key_present）のみが含まれます。
• アーティファクトのライフサイクル管理：
  • ワーカーはLLAMATOR_MCP_ARTIFACTS_ROOT/<job_id>/...の下にジョブローカルのアーティファクトを作成します。
  • アーティファクトはartifacts.zipという名前のアーカイブとしてMinIOにアップロードされます。
  • HTTP APIは、ジョブプレフィックスの下にある利用可能なオブジェクトをリストし、署名付きのダウンロードリンクを解決できます。
• X-API-Keyを介したHTTPおよびMCPインターフェースのオプションのAPIキー保護。
• APIキー認証をサポートするOpenAPIスキーマ（Swagger UI）。
• /metricsで公開されるPrometheusメトリクス。

📦 インストール

必要条件

• Docker
• Docker Compose

フルスタックの起動

docker compose up --build

デフォルトのサービスエンドポイント

• HTTP API: http://localhost:8000
• MinIO S3エンドポイント: http://localhost:9000
• MinIOコンソール: http://localhost:9001

ヘルスチェック

curl -sS http://localhost:8000/v1/health

📚 ドキュメント

設定

すべての設定はLLAMATOR_MCP_で始まる環境変数を介して提供されます。完全なリファレンスはDOCUMENTATION.mdにあります。

典型的なローカルセットアップ

cp .env.example .env

主要な設定カテゴリ

• Redis：ジョブキューと状態保存のための接続DSN。
• MinIO：アーティファクトのためのS3互換ストレージ。
• 攻撃/判定モデル：LLAMATOR実行のためのOpenAI互換エンドポイント。
• APIセキュリティ：オプションのX-API-Key保護。
• ジョブ実行：タイムアウト、TTL、およびリトライ動作。

💻 使用例

実行の作成

curl -sS -X POST "http://localhost:8000/v1/tests/runs" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <optional>" \
  -d '{
    "tested_model": {
      "kind": "openai",
      "base_url": "http://host.docker.internal:1234/v1",
      "model": "llm",
      "api_key": "lm-studio"
    },
    "run_config": { "enable_reports": false },
    "plan": { "preset_name": "owasp:llm10", "num_threads": 1 }
  }'

レスポンスには以下が含まれます。

• job_id (uuid4の16進数、32文字)
• status (queued | running | succeeded | failed)
• created_at (UTCタイムスタンプ)

ジョブ状態の取得

curl -sS "http://localhost:8000/v1/tests/runs/<job_id>" \
  -H "X-API-Key: <optional>"

レスポンスには以下が含まれます。

• status：現在のジョブ状態
• result：集計されたメトリクス（成功した場合）
• error：エラー詳細（失敗した場合）
• error_notice：ユーザー向けのコンパクトなエラーメッセージ（失敗した場合）

アーティファクト

ジョブに利用可能なオブジェクトをリストする：

curl -sS "http://localhost:8000/v1/tests/runs/<job_id>/artifacts" \
  -H "X-API-Key: <optional>"

特定のオブジェクトの署名付きダウンロードURLを解決する：

curl -sS "http://localhost:8000/v1/tests/runs/<job_id>/artifacts/<path>" \
  -H "X-API-Key: <optional>"

ダウンロードエンドポイントはdownload_urlを含むJSONペイロードを返し、リダイレクトを発行しません。

MCPインターフェース

MCPサーバーはFastAPIアプリケーションにマウントされ（デフォルトのマウントパス：/mcp）、Streamable HTTPトランスポートを使用します。

公開されているツール：

• create_llamator_run：ジョブを送信し、完了を待ち、集計されたメトリクスと（利用可能な場合）artifacts.zipの署名付きURLを返します。
• get_llamator_run：完了したジョブの集計されたメトリクスとオプションのアーティファクトアーカイブURLを返します。

両方のツールは一貫したレスポンススキーマを返します：

{
  "job_id": "string",
  "aggregated": {
    "attack_name": {
      "metric": 0
    }
  },
  "artifacts_download_url": "string or null",
  "error_notice": "string or null"
}

プロトコルの注意事項、ヘッダー、および例はDOCUMENTATION.mdに記載されています。

🔧 技術詳細

セキュリティモデル

• LLAMATOR_MCP_API_KEYが空の場合、認証は無効になります。
• 設定されている場合、保護されたHTTPルートとMCPアプリはX-API-Key: <value>を要求します。

ローカル開発

依存関係のインストール

poetry install

APIサーバーの実行

uvicorn llamator_mcp_server.main:app --host 0.0.0.0 --port 8000

ワーカーの実行

arq llamator_mcp_server.worker_settings.WorkerSettings

チュートリアル

ステップバイステップの例が含まれたJupyterノートブックはnotebooks/llamator_mcp_server_tutorial.ipynbにあります。以下をデモンストレートしています。

• curlを使用したHTTP APIの使用
• MCP JSON-RPCプロトコルの相互作用
• ジョブの完了をポーリングする
• アーティファクトの取得

テスト

統合テストはllamator-mcp-server/testsにあり、tests/.env.testに依存しています。

pytest -q

📄 ライセンス

このプロジェクトはCreative Commons Attribution-ShareAlike 4.0 Internationalライセンスの条項の下でライセンスされています。詳細についてはLICENSEファイルを参照してください。