yads-mcp

MCP対応のLLMエージェント（Claude Code、またはYADSと同じネットワーク上で到達可能な別のエージェントプロセス）が、ダッシュボードの人間を介さずに、YADS自身の/api/v1 APIを通じてキュー制御、タグ付け、スキャン実行、ターゲット/アセット管理を操作できるようにするMCPサーバーです。

これはYADSの既存のHTTP API（/api/v1/queue/*、/api/v1/tags*、/api/v1/targets/*）に対する薄いstdioラッパーです。独立した実行パスはなく、テナントスコープやスキャンディスパッチのコードパスを迂回しません。ここから行われるすべてのアクションは、ダッシュボードと同じテナント分離、同時スキャン制限、変更検出ロジックの対象となります。

1. APIキーの作成

YADSにログイン済みのマシン（セッションCookie）から、/developer または /api-keys/ エンドポイントを介して、このエージェントが必要とするスコープを持つキーを作成します：

• read — ステータス/リスト操作（queue_status、tags_list、scan_get_findings、 list_targets、get_target、get_target_changes、get_scan_status、 get_network_context、...）

• write — タグの変更、およびターゲットの変更（add_target、 undo_bulk_delete_targets、bulk_archive_targets、archive_dead_targets、 restore_target）

• scan_execute — スキャンのトリガー（単一または一括）

• destructive — queue_purge、tags_delete_globally、bulk_delete_targets、 bulk_blocklist_targets（呼び出し自体に confirm=True も必要）

返されたトークンは今すぐコピーしてください。二度と表示されません。

Related MCP server: agentguard

2. インストール

cd yads-mcp
python -m venv .venv
.venv/bin/pip install -e .

テスト

.venv/bin/pip install -e ".[test]"
.venv/bin/pytest tests/ -q

tests/conftest.py は、yads リポジトリのテストと同じテスト用Postgres/Redisスタック（そのリポジトリの docker-compose.test.yml、ポート5433/6380）に対して、YADSをインプロセス（Starlette TestClient）で実行します。これらのテストが通らない場合は、まずそのスタックを起動してください。

3. クライアントの設定

サーバーが必要とする環境変数：

• YADS_URL — 例：https://yads.example.com

• YADS_API_KEY — ステップ1のトークン

Claude Code

claude mcp add yads \
  --env YADS_URL=https://yads.example.com \
  --env YADS_API_KEY=<token> \
  -- /path/to/yads-mcp/.venv/bin/python -m yads_mcp.server

または .mcp.json に追加：

{
  "mcpServers": {
    "yads": {
      "command": "/path/to/yads-mcp/.venv/bin/python",
      "args": ["-m", "yads_mcp.server"],
      "env": {
        "YADS_URL": "https://yads.example.com",
        "YADS_API_KEY": "<token>"
      }
    }
  }
}

ツール

キューとスキャン制御

• queue_status()

• queue_list_rate_limited_modules()

• queue_pause() / queue_resume() — フリート全体、テナントスコープではない

• queue_cancel_task(task_id)

• queue_purge(confirm) — 破壊的、テナントスコープ、60秒の元に戻すウィンドウ

• queue_undo_purge(undo_batch)

タグ付けと整理

• tags_list()

• tags_add_to_target(target_id, tag) / tags_remove_from_target(target_id, tag)

• tags_bulk_assign(target_ids, tags, action="add"|"remove"|"replace")

• tags_bulk_add_by_ids(target_ids, tag)

• tags_delete_globally(tag_name, confirm) — 破壊的、元に戻せない

スキャン実行

• scan_trigger(target_url, profile="standard")

• scan_trigger_by_target_id(target_id, scan_types, scan_priority=None)

• scan_bulk_preview_count(only_roots=False, online_only=False, scanned_before=None)

• scan_bulk_by_criteria(scan_types, only_roots=False, online_only=False, scanned_before=None)

• scan_bulk_selected(target_ids, scan_types)

• scan_get_findings()

ターゲットとアセット管理（Wave 2）

• list_targets(tag=None, online=None, scan_status=None, domain_search=None, archived=False, last_scanned_before=None, page=1, limit=20)

• get_target(target_id)

• add_target(domain)

• bulk_delete_targets(target_ids, confirm) — 破壊的、60秒の元に戻すウィンドウ

• undo_bulk_delete_targets(undo_batch)

• bulk_archive_targets(target_ids) / archive_dead_targets() / restore_target(target_id)

• bulk_blocklist_targets(target_ids, confirm) — 破壊的、元に戻せない

• get_target_changes(target_id, limit=30)

• get_scan_status(target_id)

• get_network_context(target_id)

Wave 3〜10（レポートとエクスポート、ファインディングとコンプライアンス、OSINT/ディスカバリー/インテリジェンス、統合/ウェブフック/通知）は個別に追跡され、それぞれ独自の設計仕様があります。

変更履歴

CHANGELOG.md を参照してください。

ライセンス

MIT — LICENSE を参照してください。