Archivist AI

Archivist AI MCP 服务

Archivist AI 的官方 Model Context Protocol（MCP）服务——这是一个面向游戏主持人和玩家的 TTRPG 战役记忆平台。

注册表元数据位于 server.json 中。通过 .github/workflows/publish-mcp.yml 自动根据版本标签发布到 官方 MCP 注册表（git tag v3.0.1 && git push origin v3.0.1）。

将 Claude、ChatGPT、Cursor、Notion 和 Windsurf 等 AI 助手直接连接到你的战役数据：角色、场次、地点、派系、物品、任务、日志、关键时刻、英雄奖项、引言、聚光时刻等。

快速入门

MCP 服务 URL： https://mcp.myarchivist.ai/mcp

Discord 工具位于同级主机：https://discord.myarchivist.ai/mcp。这是一个独立的 MCP 资源（OAuth + 你的录音机器人），不会取代此处的战役工具。

{
  "mcpServers": {
    "archivist-ai": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.myarchivist.ai/mcp",
        "--header",
        "X-API-Key:${ARCHIVIST_API_KEY}"
      ],
      "env": {
        "ARCHIVIST_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "archivist-ai": {
      "type": "remote",
      "url": "https://mcp.myarchivist.ai/mcp"
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "archivist-ai": {
      "type": "remote",
      "url": "https://mcp.myarchivist.ai/mcp",
      "oauth": false,
      "headers": {
        "X-API-Key": "{env:ARCHIVIST_API_KEY}"
      }
    }
  }
}

{
  "mcpServers": {
    "archivist-ai": {
      "url": "https://mcp.myarchivist.ai/mcp"
    }
  }
}

{
  "mcpServers": {
    "archivist-ai": {
      "serverUrl": "https://mcp.myarchivist.ai/mcp"
    }
  }
}

提示词示例

• “列出我的所有战役，然后总结我的《Strahd 的诅咒》战役最近一场游戏的内容。”
• “创建一名名为 Mirelle Voss 船长的新 NPC，她是一名为 Silver Hand 派系效力的走私者，并将她关联到 Dusk 港地点。”
• “在我的战役中添加名为‘找回月长石’的任务，然后列出所有尚未完成的任务及相关角色。”

可用工具

读取工具不会产生破坏性影响，且具有幂等性。写入工具遵循标准 REST 语义——删除操作具有破坏性且幂等；PATCH 非幂等；PUT 幂等。所有返回包含文本的描述（角色、派系、地点、物品、时刻、节拍、游戏场次、日志）的读取工具都接受可选的 with_links 参数——请参阅下方的 Wiki 链接，了解为何在编辑前几乎总是应传入 with_links: true。

以下内容不会开放：删除战役、删除游戏场次、仅产品视图端点（节拍重新排序/批量编辑、战役设置、演员阵容/成员管理）、分段录音上传，以及 AI 图像生成。

OAuth 作用域与写入权限

通过 https://app.myarchivist.ai 连接的 OAuth 客户端会在授权时请求作用域。每个写入工具（创建/更新/删除 + 图像上传）还要求调用方的令牌具有 agent_write 作用域。

MCP 会在 tools/list 中遵循 API 的权限控制：不具备 agent_write 的 Agent 客户端只能看到读取工具；即使尝试调用写入工具，也会收到“找不到工具”的 JSON-RPC 错误。API 密钥凭据和非 Agent OAuth 客户端不受此筛选限制——API 是它们的权威权限控制方，所有工具都会保持可见。

在 agent_write 公布之前已连接的现有 OAuth 客户端，需要重新授权以获取包含此新作用域的令牌。

战役

场次

故事结构

精彩内容

世界构建

任务

日志

关系

图片

Wikilinks

Archivist AI 中的描述、摘要、事件内容和日志正文可以包含 [[Target Name|Optional Alias]] 标记，这些标记会解析为实际记录。所有涉及带有 wikilinks 的文本字段的写入工具都必须遵循一个简单的协议，以免破坏现有链接。

必须遵守的一条规则

写入前始终使用 with_links: true 读取。 Character、Faction、Location、Item、Moment、Beat、Session 和 Journal 的所有 Get/List 工具都接受此参数。API 默认会剥离 wikilinks，以便读取方获取干净的文本，这意味着简单的读取/修改/写入操作会删除源记录中的所有 [[…]]。传入 with_links: true 会返回保留方括号的文本，以便你在写入时保留这些标记。

每种记录的约定

重命名和重新指向

• 重命名别名：编辑方括号内的内容。[[Alice|Al]] → [[Alice|Ali]]。
• 重新指向其他目标：更改可见的目标名称。[[Alice]] → [[Alicia]]。
• 移除链接：在文本中移除别名的方括号（自动解析），或调用 delete_link（显式）。
• 对百科目标进行战役范围的重命名或重新指向：使用 bulk_link_maintenance，并传入 operation: "update"、new_alias 和/或 new_target_id。API 会通过后台 webhook 重写所有引用文本字段，并返回一个 task_id。

图片

可通过直接上传为 Character、Faction、Location、Item、Moment、Session 以及战役本身添加实体图片。MCP 服务不提供 AI 图片生成工具——图片生成仍是 Archivist AI 应用中的产品功能，也是 API 上的 REST 端点。

直接上传（两步）

对于用户已保存在磁盘或内存中的图像，请使用预签名 URL 流程：

1. 调用 init_image_upload，并提供 campaign_id、entity_type、entity_id、file_name 和 content_type（必须为 image/*）。你会收到 object_key、upload_url、public_url 和 expires_in_seconds。
2. 你的客户端（或人类协作者）在 URL 过期前，向 upload_url 发起 HTTP PUT 请求，上传原始图像字节，并使用相同的 Content-Type 标头。此步骤在 MCP 传输之外进行。
3. 使用 object_key、entity_type、entity_id 和 attach（默认为 true）调用 complete_image_upload。API 会验证上传内容、执行 NSFW 审核，并在 attach 为 true 时将实体的 image 字段设为审核后的 public_url。

无法发起任意 HTTP PUT 请求的 Agent，应在步骤 1 和步骤 3 之间将 PUT 步骤交由人工完成。

移除

delete_entity_image 可通过以下两种模式之一，移除某个 campaign 中的图像：

• 按实体移除：传入 entity_type + entity_id。API 会从记录中解除图像关联，并删除底层对象。
• 按 URL 移除：传入受管理的 image_url（例如来自之前 init_image_upload 的响应）。仅删除对象。

故障排查

• **身份验证失败或工具返回 401：**重新连接服务并再次完成 OAuth 登录，或检查 app.myarchivist.ai 中的 API 密钥是否为最新版本。
• **缺少写入工具（仅适用于 Agent OAuth 客户端）：**缺少 agent_write 作用域的 Agent OAuth 客户端不会显示写入工具。重新连接并批准写入权限。API 密钥和非 Agent OAuth 客户端始终可以看到所有工具；请参阅 OAuth 作用域和写入权限。
• **Claude Desktop 无法连接：**它需要 mcp-remote 代理和 Node.js；编辑配置后，请重启 Claude Desktop。
• **编辑后 Wikilinks 消失：**更新记录前，请使用 with_links: true 读取记录。请参阅 Wikilinks。

隐私与支持

• 隐私政策： https://www.myarchivist.ai/privacy
• 支持与安全联系邮箱： [email protected]
• 社区： Discord