l4d2-workshop-mirror

L4D2 Workshop Mirror MCP — 使用说明书

面向使用者的操作手册：怎么用 11 个工具、每个返回字段什么意思、遇到各种情况怎么处理。 系统设计与实现原理见 ARCHITECTURE.md，部署与运维见 DEPLOYMENT.md。

本 MCP 负责 L4D2 工坊战役地图的搜索、识别、依赖解析、下载。 所有脏活（网络请求、黑名单/去重/死图判定、Part 系列识别、依赖解析、文件校验）都在 MCP 内部完成， 你只需调用工具，不需要也不应该写 Python 脚本或调 HTTP 接口。

---

1. 快速开始（3 个最常用操作）

用户需求	你的动作
"下 X"（有 id/链接）	install_campaign(workshop_id="id 或链接")
"下 X"（只有标题）	install_campaign(title="X")
"X 有没有 / id 是多少"	resolve_map(query="X")

大图（几百 MB）用 install_campaign(..., async_mode=True) + get_download_job 轮询，避免长阻塞。

---

2. 工具速查（11 个）

下载类

install_campaign — 一站式下载（识别 → 解析依赖 → 下载 → 落盘 → 更新去重）

• 参数：workshop_id（纯数字 id 或 steam 链接）/ title（二选一）、force（默认 False，忽略去重）、auto_parts（默认 True）、strict（默认 True）、async_mode（默认 False）
• 返回必看：eligibility、preview_only、suggested_action、main（含 saved_path/size_mb/title_zh）、parts、dependencies、candidates、job_id
• 何时用：用户要下载、要给特定 id/链接/标题落地

get_download_job — 查询异步下载进度

• 参数：job_id
• 返回：status（queued/running/done/error/not_found）、elapsed_s、result（完成后是 install 完整结果）
• 何时用：install_campaign(async_mode=True) 之后轮询（隔 10-20 秒）

查询类

resolve_map — 标题解析为候选（不下载）

• 参数：query、limit（默认 5）
• 返回：items[]（workshop_id/title/title_zh/size_mb/is_campaign_score/match_ratio/in_curated_list）
• 何时用："XXX 有没有"、定位标题对应的 id；install_campaign(title=...) 内部也用它

search_campaigns — 搜索工坊战役（自动过滤 mod/黑名单/去重/死图）

• 参数：keyword、days、sort、limit（≤30）、include_ambiguous
• 返回：items[] + summary（high_confidence/ambiguous/filtered_out/dead 计数）
• 何时用：按关键词找图、"最近新图"的底层

get_map_detail — 单图详情 + 判定结果

• 参数：workshop_id、include_description（默认 False，True 时截断 500 字符）
• 返回：title/title_zh/size_mb/subscriptions、is_campaign/score/reasons/ambiguous/definitely_mod、series_info、eligibility、dead/dead_reason、in_curated_list
• 何时用："X 怎么样"、下载前查判定

check_eligibility — 下载前预检（零网络）

• 参数：workshop_id / title（至少一个）
• 返回：state（见 §3 状态字典）、days_remaining、source
• 何时用：预检一张图能不能下；批量过滤