Fantasy Tabletop Helper

Fantasy Tabletop Helper — MCP 服务

将 Claude Desktop、Cursor、Codex 或任何支持 MCP 的客户端连接到你的桌上角色扮演战役，并用日常语言询问关于你自己世界的问题。

“Westruun 中哪些 NPC 信奉某种宗教？其中哪些是我的队伍已经见过的？”

此仓库包含连接文档和客户端配置示例。服务本身托管在 fantasytabletophelper.com 中运行，因此无需安装、克隆或保持运行。

• 端点： https://www.fantasytabletophelper.com/api/mcp — 请保留 www.，见下文
• 传输方式： 无状态 Streamable HTTP，仅支持 POST
• 访问权限： Hero 计划 + PAT（ftth_mcp_…）。可读取，并可进行受控写入（你创作的提案／笔记／事件）。不是 OAuth——这是另一个独立问题。
• 源码： 闭源。该应用是商业产品；此仓库是客户端部分。

---

仅限你本人（读取 + 受控写入）

服务会以你的身份查询数据库，而非以管理员身份查询。答案由行级安全机制决定，因此它只能显示你登录网站时能够看到的内容。

允许写入，但范围有限：你创作的笔记和事件、你提交的摘要，以及供 DM 审核的提案。AI 工具通过此连接执行的任何操作，在 DM 于应用中审核之前，都不会成为战役正史。

	谁可以看到
队伍笔记	战役成员
仅 DM 可见的笔记	该战役的 DM，或笔记作者
私密笔记	仅作者
Codex 条目	该战役的成员；非正史条目仅 DM 可见

如果你是玩家，将 AI 客户端连接到你的战役不会泄露 DM 的秘密。此限制由数据库强制执行，而非由应用代码实现。

工具

工具	返回内容
list_campaigns	你的战役及你在每个战役中的角色
get_campaign	单个战役的详细信息
list_sessions	各场游戏，按最近游玩时间从新到旧排列
search_codex	NPC、地点、物品、背景设定、宗教、文化、团体
get_subject	单个 Codex 条目的完整内容及其关系
get_session_notes	单场游戏的笔记
get_session_recap	游戏摘要——如果你是 DM，还会包含 DM 备战提示
append_session_note	添加笔记（需指定可见范围）
submit_session_recap	保存你撰写的摘要
propose_subject	提交 Codex 条目提案，供 DM 审核
propose_relationship	提交两个现有条目之间的关联提案
list_session_events	你有权读取的掷骰和战斗事件
append_session_event	添加一个类型化事件（掷骰／命中／治疗……）
get_session_transcript	最新的就绪转录稿——仅限 DM，绝不提供音频

派系和公会以 kind: "group" 的形式存储——没有单独的 faction 类型。

---

设置

1. 创建令牌

在网站上，前往 Account → AI Tool Access（/account/mcp），将令牌命名为你要连接的工具名称，然后点击 Create token。

令牌只会显示一次，开头为 ftth_mcp_。请立即复制。 系统只会存储哈希值，因此之后无法再次查看。如果令牌丢失，请撤销并重新创建。

2. 配置客户端

可直接编辑的文件位于 examples/ 中。以 Claude Desktop 为例：

{
  "mcpServers": {
    "ftthelper": {
      "url": "https://www.fantasytabletophelper.com/api/mcp",
      "headers": { "Authorization": "Bearer ftth_mcp_YOUR_TOKEN_HERE" }
    }
  }
}

重启客户端。工具列表中应该会出现 ftthelper。

请保留 www.

这不是装饰。裸域名会重定向到 www，而 HTTP 客户端在重定向改变来源时会丢弃 Authorization 标头——这是合理的，因为客户端无法确定新主机是否值得托付你的凭据。若将客户端指向 https://fantasytabletophelper.com/api/mcp，令牌就会在传输过程中被剥离，因此服务收到的是匿名请求，并会针对完全有效的令牌返回 401 Invalid or missing MCP token。

3. 向它提问

“列出我的战役，然后找出 Westruun 战役中的所有宗教。”

---

撤销令牌

在 Account → AI Tool Access 中，点击令牌旁边的 Revoke。这会在该客户端下次请求时生效。撤销你曾粘贴到已不受你控制的位置的任何令牌。

故障排查

症状	原因
404	路径错误，或者此部署已关闭服务器。
刚创建的令牌出现 401	几乎总是 URL 的问题：用了不带 www. 的裸域名，导致令牌被剥除。怀疑令牌有问题之前，请先检查这一点。
401	令牌错误、已撤销或已过期。请创建新令牌。
503	我们无法为你的帐户打开会话。通常是暂时性的；请重试。
403	你的套餐不是 Hero。
429	软性速率限制（每个令牌约 60 次请求/分钟）。请等待 Retry-After。
GET 请求出现 405	这是预期行为。该服务器仅支持 POST；你的客户端应使用 POST。
已连接，但每次工具调用都返回错误	服务器端配置问题。请联系支持团队——服务器会记录这些错误。
工具返回空列表	通常确实如此：你还没有任何活动，或者搜索没有匹配结果。

最后两行值得区分。空列表是一种答复；错误则表示故障。

许可

文档和示例配置：MIT。托管服务有其自己的 条款。