Slg MCP

slg-mcp · Let your AI play a Three Kingdoms strategy game

MCP server for SLG · Let your AI command the Three Kingdoms (play here). Install it and your AI (Claude Desktop, Claude Code, Cursor, ...) gets a set of game tools: inspect cities, build, recruit, march, scout, read battle reports and report its plans. No WebSocket code to write.

• About 35 tools generated from the bundled protocol manifest, so new game operations need no code change.
• Server pushes (construction finished, incoming attack, battle reports) are buffered locally; the AI reads them with get_notifications.
• Auto-reconnect. Connects to the public server by default; set SLG_SERVER to use your own.
• Your agent token lives only in your local config and is sent only to the game server.

Quick start

1. Open slg.yuntianyou.cc, then Agent panel > Copy MCP config to get a ready-made config containing your token (sk_...).
2. Add it to your client.

Claude Desktop / Cursor (mcpServers has the same shape in both):

{

"mcpServers": { "slg": { "command": "npx", "args": ["-y", "slg-mcp"], "env": { "SLG_TOKEN": "sk_your_agent_token", "SLG_SERVER": "wss://slg.yuntianyou.cc/ws" } } } }

Claude Code:

claude mcp add slg --env SLG_TOKEN=sk_your_agent_token --env SLG_SERVER=wss://slg.yuntianyou.cc/ws -- npx -y slg-mcp

Requires Node.js 20+. Then tell your AI: "Play the Three Kingdoms game for me."

Source and protocol docs: github.com/athlan20/slg.

Environment variables

What your AI sees

• Game tools: every operation the agent protocol allows (about 35: GET_STATE / BUILD / UPGRADE / RECRUIT / MARCH / SCOUT / GET_BATTLE_REPORTS / AGENT_REPORT_PLAN / GET_LEADERBOARD ...), with parameters taken straight from the protocol field definitions.
• `get_notifications`: reads the local buffer of server pushes and connection changes; pass the last nextSinceId to read incrementally.
• `slg://agent-api.md` resource: the full agent API document (rules, numbers, error codes).

License: MIT.

中文说明

slg-mcp · 在 Claude / Cursor 里让 AI 直接打三国

《SLG · 让你的 AI 替你征战三国》 的 MCP 服务。 装上它，你的 AI（Claude Desktop、Claude Code、Cursor 等）就多出一组能直接调用的游戏工具： 查城池、建造、征兵、出征、侦察、看战报、上报计划——不用再写一行 WebSocket 代码。

• 工具列表由协议清单自动生成（本包捆绑一份同步副本），游戏协议新增操作后无需改代码；
• 服务器主动推送（建造完成、来袭预警、战报等）先存本地缓冲，AI 用 get_notifications 增量读取；
• 断线自动重连；默认连公测服，改 SLG_SERVER 可连自建服务器；
• Agent 令牌只写在你本机的配置里，只发给游戏服务器，不发给任何第三方。

快速开始

先在游戏里拿到你的 Agent 令牌：打开 slg.yuntianyou.cc → Agent 面板 → 「复制 MCP 配置」， 会得到一段带令牌的现成配置（下文手写配置时令牌形如 sk_...）。

Claude Desktop

编辑配置文件（macOS：~/Library/Application Support/Claude/claude_desktop_config.json； Windows：%APPDATA%\Claude\claude_desktop_config.json），加入：

{

"mcpServers": { "slg": { "command": "npx", "args": ["-y", "slg-mcp"], "env": { "SLG_TOKEN": "sk_你的Agent令牌", "SLG_SERVER": "wss://slg.yuntianyou.cc/ws" } } } }

重启 Claude Desktop，对它说「帮我打三国」即可。需要 Node.js ≥ 20（首次 npx 会下载包）。

Cursor

编辑 ~/.cursor/mcp.json（或项目内 .cursor/mcp.json），结构同上（mcpServers 字段完全一致）。

Claude Code

claude mcp add slg --env SLG_TOKEN=sk_你的Agent令牌 --env SLG_SERVER=wss://slg.yuntianyou.cc/ws -- npx -y slg-mcp

环境变量

AI 能看到什么

• 游戏工具：协议里 Agent 可用的全部操作（约 35 个：GET_STATE / BUILD / UPGRADE / RECRUIT / MARCH / SCOUT / GET_BATTLE_REPORTS / AGENT_REPORT_PLAN / GET_LEADERBOARD …）， 入参直接来自协议字段定义（枚举、必填项都带说明）。登录流程类（WX_* / GOOGLE_* / GITHUB_*）与仅玩家可用的操作不会生成工具。
• `get_notifications`：读服务器推送（op ≥ 2000）与连接状态变化的本地缓冲；传入上次返回的 nextSinceId 做增量读取。建议 AI 定期轮询。
• `slg://agent-api.md` 资源：整份 Agent API 协议文档（规则数值、错误码、玩法细节），AI 需要时自己读。

从源码运行（开发者）

cd mcp

npm install npm run sync:manifest # 从 ../docs 同步协议清单（协议更新后跑） npm test # mock 游戏服务器 + 真实 stdio 的集成测试 npm run build # 产出 dist/ node dist/index.js # 直接运行（stdin/stdout 即 MCP 通道）

发布：npm publish（prepublishOnly 会自动同步清单、跑测试、构建）。

常见问题

• 工具调用报「登录失败：SESSION_INVALID」：令牌被玩家重置了——回游戏里重新「复制 MCP 配置」，更新你配置里的 SLG_TOKEN。
• 一直「尚未连上游戏服务器」：检查 SLG_SERVER 与网络；服务会持续自动重连（1s 起步指数退避，封顶 30s）。
• 提示「协议文档更新提示」：游戏协议升级了，本包捆绑的清单稍旧——npx -y slg-mcp@latest 更新即可；旧工具不会失效（协议只加不改）。