argo-mcp

Argo MCP 服务

通过 Model Context Protocol 将 AI 助手连接到你的 Argo 战役。配置完成后，AI 助手便可读取和编写战役设定、查找角色详情，并直接在聊天界面中与 Argo 数据交互。

支持的客户端：Claude Code、Claude Desktop、OpenAI Codex、VS Code（1.103+）以及任何兼容 MCP 的宿主。

一键安装

点击任一按钮会将带有此配置的 vscode:mcp/install URL 交给你的编辑器：

{ "type": "http", "url": "https://mcp.argo.games/mcp" }

VS Code 会将条目保存到用户级 mcp.json 中，并在首次连接时通过针对 Argo 授权服务的动态客户端注册协商 OAuth。URL 中不包含令牌——VS Code 会将生成的访问令牌和刷新令牌保存在操作系统密钥链中。

Linux / Flatpak / Snap 注意事项： 如果点击按钮后没有打开 VS Code，则说明尚未注册 vscode: URL 处理程序。以下情况很常见：

• Flatpak / Snap 版 VS Code — 沙盒会将安装与主机隔离，因此主机浏览器无法找到协议处理程序。
• Tarball / 手动安装 — 不会运行用于执行 update-desktop-database 的 postinst 钩子。可以运行一次 xdg-mime default code.desktop x-scheme-handler/vscode，也可以使用下面的手动备用方法。

手动备用方法：将下面 VS Code（一键安装，推荐） 部分中的 JSON 复制到 VS Code 的 mcp.json 配置中。

同一个安装按钮也会显示在 Argo 安装页面 https://app.argo.games/docs/mcp/install 上。

---

前置条件

• Node.js 20 或更高版本
• 拥有至少一个战役的 Argo 账号
• 游戏主持人必须通过 OAuth2 授权流程授权 AI 助手（参见获取令牌）

---

快速开始

有三种受支持的方式可使用 Argo MCP 服务。请选择与你的客户端相符的方式。

ChatGPT（远程）

使用托管端点——不要安装 npx 软件包。将此 MCP 服务 URL 添加到 ChatGPT：

https://mcp.argo.games/mcp

ChatGPT 会在首次连接时通过动态客户端注册引导你完成 OAuth 流程。

本地 MCP 客户端（Claude Code、Claude Desktop、Codex 等）——推荐

在运行 MCP 客户端的机器上登录一次：

npx -y argo-mcp auth login

该命令会打印授权 URL，不会打开任何页面，并要求你粘贴授权页面中的访问令牌（以及可选的刷新令牌）。令牌会保存在本地：

• Windows：%APPDATA%\argo-mcp\tokens.json
• macOS：~/Library/Application Support/argo-mcp/tokens.json
• Linux：${XDG_CONFIG_HOME:-~/.config}/argo-mcp/tokens.json

然后配置 MCP 服务，无需设置环境变量：

{
  "mcpServers": {
    "argo": { "command": "npx", "args": ["-y", "argo-mcp"] }
  }
}

其他身份验证命令：

npx -y argo-mcp auth status   # show whether you are signed in
npx -y argo-mcp auth logout   # forget locally stored tokens

本地 stdio 模式不使用 OAuth 动态客户端注册。DCR 仅由托管的 HTTP 服务 https://mcp.argo.games 使用。

高级用法——环境变量

对于 CI、Docker，或偏好显式配置环境变量的用户，可以跳过 auth login，直接传入令牌。OAUTH_TOKEN 的优先级始终高于本地令牌存储。

{
  "mcpServers": {
    "argo": {
      "command": "npx",
      "args": ["-y", "argo-mcp"],
      "env": {
        "OAUTH_TOKEN": "<your-access-token>",
        "REFRESH_TOKEN": "<your-refresh-token>"
      }
    }
  }
}

---

从源代码构建（贡献者）

git clone https://github.com/Argo-RPG-Platform/MCP.git argo-mcp
cd argo-mcp
npm install
npm run build

---

获取令牌

MCP 服务使用与特定战役集绑定的 OAuth2 访问令牌向 Argo 进行身份验证。令牌通过 Argo 授权流程获取：

1. 在浏览器中打开 **https://app.argo.games/oauth2/mcp-connect**。
2. 选择要允许 AI 助手访问的战役，以及权限级别（只读或读写）。
3. 点击 Authorize。系统会将你重定向到一个页面，其中显示两个令牌：
   • Access token — 将其设为 OAUTH_TOKEN
   • Refresh token — 将其设为 REFRESH_TOKEN（推荐；访问令牌约 1 小时后过期时，可自动续期）

请像对待密码一样保护这两个令牌。你可以随时在战役的集成页面撤销它们。

---

配置

VS Code（一键安装，推荐）

使用本 README 顶部的安装按钮，或将以下内容粘贴到 .vscode/mcp.json（工作区级）或用户级 MCP 配置中：

{
  "servers": {
    "argo": {
      "type": "http",
      "url": "https://mcp.argo.games/mcp"
    }
  }
}

VS Code 会在首次连接时通过 Dynamic Client Registration 自动处理 OAuth。无需设置 OAUTH_TOKEN 或 REFRESH_TOKEN——VS Code 会将令牌存储在操作系统密钥链中。

Claude Code

使用 CLI 添加服务：

claude mcp add argo \
  --command node \
  --args /absolute/path/to/argo-mcp/dist/index.js \
  --env OAUTH_TOKEN=<your-access-token> \
  --env REFRESH_TOKEN=<your-refresh-token>

或者手动将其添加到项目的 .claude/settings.json：

{
  "mcpServers": {
    "argo": {
      "command": "node",
      "args": ["/absolute/path/to/argo-mcp/dist/index.js"],
      "env": {
        "OAUTH_TOKEN": "<your-access-token>",
        "REFRESH_TOKEN": "<your-refresh-token>"
      }
    }
  }
}

Claude Desktop

编辑 Claude Desktop 配置文件：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "argo": {
      "command": "node",
      "args": ["/absolute/path/to/argo-mcp/dist/index.js"],
      "env": {
        "OAUTH_TOKEN": "<your-access-token>",
        "REFRESH_TOKEN": "<your-refresh-token>"
      }
    }
  }
}

保存后重启 Claude Desktop。

OpenAI Codex

将服务添加到 Codex MCP 配置中：

{
  "mcpServers": {
    "argo": {
      "command": "node",
      "args": ["/absolute/path/to/argo-mcp/dist/index.js"],
      "env": {
        "OAUTH_TOKEN": "<your-access-token>",
        "REFRESH_TOKEN": "<your-refresh-token>"
      }
    }
  }
}

ChatGPT App 提交

对于托管的 ChatGPT 应用入口，本仓库会在 MCP 域上提供 OAuth 发现、动态客户端注册和域名验证端点。提交检查清单和必需的环境变量见 CHATGPT_APP_SUBMISSION.md。

使用 .env 文件（本地开发）

在 argo-mcp 目录中创建 .env 文件：

OAUTH_TOKEN=<your-access-token>
REFRESH_TOKEN=<your-refresh-token>

然后直接运行：

npm run dev       # hot-reload via tsx
# or
npm start         # compiled dist/

---

预构建 Agent 技能

连接 MCP 后，你可以安装 argo-agent-skills 插件，获取可直接使用的游戏主持人工作流，编排下方的工具——会前准备、会后回顾、NPC 生成，以及 MCP 设置引导。同一技能源还提供面向 Claude（Code + Claude.ai）和兼容 OpenAI 的客户端（Codex、ChatGPT）的配套打包版本。

Claude Code：

/plugin marketplace add Argo-RPG-Platform/argo-agent-skills
/plugin install argo-gm-pack@argo

Claude.ai / Codex / ChatGPT： 从最新版本下载对应目标的 zip 文件，并按照该仓库 README 中的上传步骤操作。

请参阅 Argo 技能文档，了解完整的技能列表、示例，以及编写自定义技能的指南。

---

可用工具

此服务提供涵盖战役、mnemons、会话、公会、好友和 Argo 社区论坛的工具。

战役

• list_campaigns（campaign.read）列出可访问的战役及其访问级别
• get_campaign（campaign.read）获取战役详情
• create_campaign（campaign.create）创建新战役
• update_campaign（campaign.write）更新战役名称或描述
• list_co_gms（campaign.read）列出助理 GM
• add_co_gm（campaign.write）添加助理 GM
• remove_co_gm（campaign.write）移除助理 GM

Mnemons

• describe_mnemon_types 列出受支持的 mnemon 类型、关系标签和内容块规则
• list_mnemons（campaign.read）列出某个战役的 mnemon 条目
• get_mnemon（campaign.read）完整获取某个 mnemon 条目
• list_mnemon_relationships（campaign.read）列出关联条目和关系边
• create_*_mnemons（campaign.write）创建 NPC、Location、Quest、Lore、Archive、Journal、SessionSummary、Player 和 Custom 类型的 mnemon 条目
• update_*_mnemons（campaign.write）更新这些 mnemon 条目的类型字段和元数据字段；Quest 工具还会写入 Quest 的目标、奖励标记、背景和 GM 备注
• set_quest_objective_state（campaign.write）根据目标 ID 将一个 Quest 目标标记为完成、失败或重新开启
• update_mnemons_content（campaign.write）编辑 mnemon 内容块
• create_mnemon_relationship（campaign.write）在条目之间创建关系
• delete_mnemon_relationship（campaign.write）根据 ID 删除关系

Sessions

• create_session（campaign.write）安排一场战役场次
• list_sessions（campaign.read）列出某个战役在指定月份的场次
• get_session（campaign.read）获取单个场次
• update_session（campaign.write）更新场次安排或文本

Guilds

• list_guilds（guild.read）列出当前用户加入的 Guild
• get_guild（guild.read）获取 Guild 详情
• list_guild_members（guild.read）列出 Guild 成员
• add_campaign_to_guild（guild.write）将战役关联到 Guild
• invite_guild_member（guild.admin）邀请 Guild 成员
• remove_guild_member（guild.admin）移除 Guild 成员
• set_guild_member_role（guild.admin）更改 Guild 成员的角色
• add_guild_calendar_event（guild.admin）添加 Guild 日历活动

Friends

• list_friends（friends.read）列出已接受的好友
• list_sent_friend_requests（friends.read）列出待处理的外发好友请求
• list_received_friend_requests（friends.read）列出待处理的收到的好友请求
• send_friend_request（friends.write）发送好友请求
• accept_friend_request（friends.write）接受好友请求
• reject_friend_request（friends.write）拒绝好友请求
• cancel_friend_request（friends.write）取消已发送的好友请求

要邀请他人加入战役或 Guild，请使用 invite_guild_member 或 send_friend_request——MCP 接口不会向你现有 Argo 环境之外的地址发送电子邮件。

Forum

• forum_list_categories（forum.read）列出论坛分类
• forum_list_topics（forum.read）列出某个分类中的主题
• forum_get_latest_topics（forum.read）列出近期论坛活动
• forum_read_topic（forum.read）阅读主题讨论串
• forum_search（forum.read）搜索论坛内容
• forum_get_user_posts（forum.read）列出当前用户的主题
• forum_get_notifications（forum.read）列出当前用户的通知
• forum_create_topic（forum.write）在 community.argo.games 上创建新主题
• forum_reply（forum.write）回复 community.argo.games 上的现有主题

许多战役范围的工具都接受 campaignId。你可以从 Argo 战役 URL 中找到战役 ID，也可以询问 GM。

---

Token 续期

访问令牌约一小时后过期。如果配置了 REFRESH_TOKEN，服务会在首次请求返回 401 时自动获取新的访问令牌，并透明地重试——无需执行任何操作。

如果未设置刷新令牌且访问令牌过期，工具会返回：

令牌已过期——请在 https://app.argo.games/oauth2/mcp-connect 重新授权

在该 URL 重新运行授权流程以获取新令牌。

---

撤销访问权限

若要断开 AI 助手与某个战役的连接，请在 Argo WebApp 的战役集成页面撤销授权。访问令牌和刷新令牌都会立即失效。

---

环境变量

变量	必填	描述
OAUTH_TOKEN	若未通过 auth login 登录，则必填	授权流程签发的 OAuth2 访问令牌
REFRESH_TOKEN	建议填写	OAuth2 刷新令牌；可启用自动续期
ARGO_API_BASE	否	覆盖 API 基础 URL（默认值：https://api.argo.games）
ARGO_MCP_TOKEN_PATH	否	覆盖 auth login 使用的本地令牌文件路径

---

隐私政策

完整政策：https://argo.games/privacy

Argo MCP 服务处理的内容：

• 收集的数据。 Argo 授权服务（oauth.argo.games）签发的 OAuth 访问令牌和刷新令牌；经由工具调用传输的战役、mnemon、guild、forum 和 friends 数据；用于速率限制和防滥用的标准 HTTP 元数据（IP、用户代理）。
• 用途。 工具调用会代表已认证用户转发至 Argo WebAPI（api.argo.games）。令牌会在 MCP 会话期间缓存在进程内，以便未在后续请求中携带 Authorization 的客户端（这是 Claude Code 的已知行为）继续正常工作。
• 存储与保留。 会话令牌缓存仅存储在内存中，并在 30 分钟无活动后清除。MCP 服务不会持久化任何用户内容（mnemons、战役、论坛帖子），而是将其转发至 WebAPI 后丢弃。日志仅保留请求元数据，不保留数据内容。
• 第三方共享。 请求只会转发至 Argo WebAPI，以及在 OAuth 流程期间转发至 Argo 授权服务。此服务不会向其他第三方提供请求数据。
• 联系。 隐私问题：[email protected]。安全问题披露：请参阅 Argo GitHub 组织中的 SECURITY 政策。

上述链接中的托管隐私政策是权威版本，涵盖包括 WebAPI 和 WebApp 在内的完整 Argo 平台。

---

许可证

MIT — 参见 LICENSE。