yads-mcp

MCP 服务器，让任何支持 MCP 的 LLM 代理（Claude Code，或通过同一网络可达 YADS 的其他代理进程）能够通过 YADS 自身的 /api/v1 API 驱动队列控制、标签管理、扫描执行以及目标/资产管理，而无需人工在仪表盘上操作。

它是 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（Starlette TestClient），使用与 yads 仓库自身测试相同的测试 Postgres/Redis 栈（该仓库中的 docker-compose.test.yml，端口 5433/6380）——如果这些测试未通过，请先启动该栈。

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()

目标与资产管理（第 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)

第 3–10 波（报告与导出、发现与合规、OSINT/发现/情报、集成/Webhooks/通知）分别跟踪，每个都有各自的设计规范。

变更日志

参见 CHANGELOG.md。

许可证

MIT — 参见 LICENSE。