CozyVTT MCP 是面向自托管开源虚拟桌面 CozyVTT 的 MCP（模型上下文协议）桥接工具，用于让 AI 智能体以 DM/KP 身份参与战役：在聊天中叙事、由服务器端执行权威骰子判定、移动棋子、切换地图、管理先攻顺序以及处理角色卡。它专为 Hermes Agent 构建并测试，但兼容任何支持 stdio 传输的 MCP 客户端。
用途与定位
该桥接让 AI 智能体加入 CozyVTT 战役并承担 DM/KP 职责，负责叙事、掷骰、棋子与地图操作、先攻管理和角色卡结算。桥接本身保持游戏系统无关，规则计算（技能检定、SAN 损失、伤害等）由智能体/GM 完成，桥接仅执行权威掷骰并写入结果。
主要能力
提供 41 个工具，工具返回 {ok, data?, error?} 结构，MCP 参数校验由 FastMCP 处理。工具按类别划分：
- 会话/战役：campaign_get、session_manage、session_list、session_notes_update、campaign_transfer_dm、map_list、map_switch
- 叙事：chat_send（DM/PLAYER）、chat_read
- 骰子：dice_roll（服务器端权威结果；is_secret=true 以 secret 字段投递给掷骰者与 DM，基于 v1.4.0）、events_poll（最近缓冲骰子事件，非持久历史）
- 棋子/地图：token_add、token_move、token_hp_update、token_place_creature、token_delete、map_create、map_delete、creature_search（SRD 与自定义库）
- 战斗：initiative_manage（添加/移除/掷骰/设置/重排/开始/下一/结束）、initiative_read（CoC7e 先攻按 DEX 排序，无掷骰，roll 相应受限）
- 角色：character_list、character_get、character_create、character_delete、character_validate、character_update（规则数学由智能体计算，桥接只写值）
- 文档：document_upload、document_create、document_list、campaign_document_list、document_read、document_update、document_share、document_unshare、document_delete
- 存档掷骰：saved_roll_list、saved_roll_create、saved_roll_update、saved_roll_delete（当前用户与战役私有；每用户/战役 50 个宏，服务器校验表达式；无 saved_roll_get）
- 生命骰：character_hitdice_spend（仅 DND_5E；仅派发一次消耗，不掷骰不治疗）
另有 map_create、map_delete、token_delete、character_delete 等表层工具。部分能力会依据战役的 gameSystem（DND_5E / PATHFINDER_2E / SHADOWRUN_6E / CALL_OF_CTHULHU_7E）门控；未设置 gameSystem 的灵活战役会失败关闭。campaign_get().features 报告当前战役可用门控能力。
使用方式
安装要求：CozyVTT v1.5.0 实例（主要固定基线），以及账号具备各工具所需权限的战役；依赖 uv（推荐）或 pip。MCP 使用 stdin/stdout，无网络端口或 TTY，用 -i 保持 stdin 打开。凭据在运行时提供；没有任何 COZYVTT 变量时，initialize 与 tools/list 仍可用，只有业务工具调用才初始化认证。
注册到 Hermes Agent（config.yaml）后需重启（MCP 服务器不热重载）。通用 MCP 客户端：command 为 venv python，args 为 server.py，env 如上。Docker 镜像仅安装 uv.lock 中兼容且哈希校验的运行时 wheel；上传文件需挂载进容器并传容器内路径给 document_upload；二进制下载需挂载 /app/downloads。
默认工具集为全部工具。注册时可选用逗号分隔的预设（取并集）进行过滤，被排除的工具从 tools/list 中整体移除；--list-toolsets 打印成员与默认值后成功退出且不连接 CozyVTT。客户端可追加 "--toolsets", "play" 或设置 COZYVTT_MCP_TOOLSETS。
适用场景与限制
适用于 AI 智能体在 CozyVTT 自托管虚拟桌面中充当 DM/KP 运行战役。需注意：
- 0.3.0 中三个工具被重命名（campaign_status → campaign_get、initiative_state → initiative_read、token_hp → token_hp_update），无别名，需更新客户端工具选择。
- chat_read 使用 limit/cursor 分页，offset 参数在 0.2.0 移除；先读最新页，再将 pagination.nextCursor 作为 cursor 回传，为 null 时停止。
- dice_roll、chat_send、token_hp_update、initiative_manage、character_hitdice_spend 返回 sent: true、confirmed: false 状态，需用 events_poll 读取业务广播与 system.error，不要盲目重放写入。
- events_poll 先返回最旧未读事件；保存 next_seq 供下次 since 使用。
- character_update 递归合并角色卡字段后再 PUT；未指定字段保留，数组/标量替换值，null 为显式。409 不重试。
- character_create 创建卡片后检查名单，若未确认为已分配则进行分配；分配失败时错误包含已创建的角色 ID，应改在 UI 中分配该卡而非再创建。
- 文档 scope 为 USER/CAMPAIGN/GLOBAL；类型化 txt/md 创建/更新限制 900 KiB UTF-8；文件上传用实例限制（默认 50 MiB）；PDF 内容不可编辑；取消共享只移除一个链接，不能撤销原生/全局访问；删除会移除资产及所有链接。
- 原始文档读取保留 MIME 类型与 ETag；PDF 写入项目 downloads/<document_id>.pdf；304 返回 {not_modified:true}。下载被 Git 忽略，本地副本在上游删除后仍存在。
- REST 401 会使现有 WS 认证与战役缓存失效；失去战役成员资格会取消 WS 认证而非循环重连。
- character_validate 始终包含 validation_reliable:false。initiative_read(refresh=true) 请求新状态，超时报 unknown。
- 路由缺失 404 返回“This CozyVTT instance does not provide this feature”。上传 DOCUMENT 到旧上传路由可能返回 400，不重试。
- 兼容性表描述支持的协议，不代表推断的服务器版本。记录的 DM 运行使用 CALL_OF_CTHULHU_7E 在 PREPARATION：22 个请求、一个被动 WS 连接，仅 authenticate/initiative.request_state 发出；未测试实时战役写入、多用户可见性或秘密接收者隔离。
- 日志位于 logs/cozyvtt-mcp.log（不含密码）。重复 401 有速率限制；桥接强制重新登录间隔至少 3 分钟。远程部署使用 HTTPS。
离线测试阻断 TCP 连接，包含真实 FastMCP 内存与 stdio 检查，无需战役凭据。对见证的 v1.5.0 实例的实时集成验证于 2026-10-04 使用认证只读 REST 与被动 WS 状态读取完成；未测试战役写入或多用户隔离。验证所用本地 venv 运行 Python 3.12.13；Python 3.13 尚未验证。
