slg-mcp 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,83 @@
-# Temporary Holding Version
+# slg-mcp · 在 Claude / Cursor 里让 AI 直接打三国
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[《SLG · 让你的 AI 替你征战三国》](https://slg.yuntianyou.cc) 的 [MCP](https://modelcontextprotocol.io) 服务。
+装上它，你的 AI（Claude Desktop、Claude Code、Cursor 等）就多出一组能直接调用的游戏工具：
+查城池、建造、征兵、出征、侦察、看战报、上报计划——**不用再写一行 WebSocket 代码**。
+
+- 工具列表由[协议清单](../docs/agent-api.json)自动生成（本包捆绑一份同步副本），游戏协议新增操作后无需改代码；
+- 服务器主动推送（建造完成、来袭预警、战报等）先存本地缓冲，AI 用 `get_notifications` 增量读取；
+- 断线自动重连；默认连公测服，改 `SLG_SERVER` 可连自建服务器；
+- Agent 令牌只写在你本机的配置里，只发给游戏服务器，不发给任何第三方。
+
+## 快速开始
+
+先在游戏里拿到你的 Agent 令牌：打开 [slg.yuntianyou.cc](https://slg.yuntianyou.cc) → **Agent 面板 → 「复制 MCP 配置」**，
+会得到一段带令牌的现成配置（下文手写配置时令牌形如 `sk_...`）。
+
+### Claude Desktop
+
+编辑配置文件（macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`；
+Windows：`%APPDATA%\Claude\claude_desktop_config.json`），加入：
+
+```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
+
+```bash
+claude mcp add slg --env SLG_TOKEN=sk_你的Agent令牌 --env SLG_SERVER=wss://slg.yuntianyou.cc/ws -- npx -y slg-mcp
+```
+
+## 环境变量
+
+| 变量 | 必填 | 说明 |
+| --- | --- | --- |
+| `SLG_TOKEN` | 是 | 玩家的永久 Agent 令牌（游戏内「复制给 AI」/「复制 MCP 配置」里自带，`sk_` 开头）。只存在你本机。 |
+| `SLG_SERVER` | 否 | 游戏 WebSocket 地址，默认 `wss://slg.yuntianyou.cc/ws`（公测服）；自建服务器改成自己的地址。 |
+| `SLG_AGENT_MODEL` | 否 | 登录时自报驱动模型名（如 `claude-opus-5-5`），进游戏内「模型榜」分组；不填归「未声明」。 |
+| `SLG_REQUEST_TIMEOUT_MS` | 否 | 单个工具调用等待上限，默认 30000。 |
+| `SLG_READY_TIMEOUT_MS` | 否 | 等待连接（含登录）就绪的上限，默认 20000。 |
+
+## 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 需要时自己读。
+
+## 从源码运行（开发者）
+
+```bash
+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` 更新即可；旧工具不会失效（协议只加不改）。

package/dist/config.js

@@ -0,0 +1,32 @@
+// 环境变量配置（AISLG-131）：Agent 令牌只存在玩家本机的 MCP 配置里，
+// 只发给 SLG_SERVER 指向的游戏服务器，不发给任何第三方。
+export const DEFAULT_SERVER = 'wss://slg.yuntianyou.cc/ws';
+const MIN_TIMEOUT_MS = 1_000;
+const MAX_TIMEOUT_MS = 300_000;
+function readTimeout(env, key, fallbackMs) {
+    const raw = Number(env[key]);
+    if (!Number.isFinite(raw)) {
+        return fallbackMs;
+    }
+    return Math.min(Math.max(Math.floor(raw), MIN_TIMEOUT_MS), MAX_TIMEOUT_MS);
+}
+/** 解析环境变量；token 缺失时返回 error（进程以清晰报错退出，而不是半启动） */
+export function readConfig(env) {
+    const token = typeof env.SLG_TOKEN === 'string' ? env.SLG_TOKEN.trim() : '';
+    if (token === '') {
+        return {
+            error: '缺少环境变量 SLG_TOKEN：请填入游戏内「Agent 面板 → 复制给 AI / 复制 MCP 配置」里的 Agent 令牌（sk_ 开头）。详见 https://github.com/athlan20/slg 的 mcp/README.md。',
+        };
+    }
+    const server = typeof env.SLG_SERVER === 'string' && env.SLG_SERVER.trim() !== '' ? env.SLG_SERVER.trim() : DEFAULT_SERVER;
+    const agentModel = typeof env.SLG_AGENT_MODEL === 'string' && env.SLG_AGENT_MODEL.trim() !== '' ? env.SLG_AGENT_MODEL.trim() : null;
+    return {
+        config: {
+            token,
+            server,
+            agentModel,
+            requestTimeoutMs: readTimeout(env, 'SLG_REQUEST_TIMEOUT_MS', 30_000),
+            readyTimeoutMs: readTimeout(env, 'SLG_READY_TIMEOUT_MS', 20_000),
+        },
+    };
+}

package/dist/connection.js

@@ -0,0 +1,260 @@
+// 游戏服务器连接（AISLG-131）：标准 WebSocket + JSON 帧（与 backend/api 一致，
+// 见 docs/agent-api.md「帧结构」）。职责：
+// - 启动即连接并 LOGIN {token, asAgent: true, docVersion}（v50 起可带 agentModel 自报）；
+// - 工具调用经 request() 走 seq 配对，超时按配置；
+// - 推送帧（op ≥ 2000 / push=true）进有上限的环形缓冲，get_notifications 增量读取；
+// - 断线自动重连（指数退避封顶 30s），重连成功后重新登录并写一条合成通知，
+//   让 AI 能感知「连接曾断过、期间可能有错过」。
+import WebSocket from 'ws';
+/** 通知环形缓冲的默认容量（旧通知被新通知挤掉） */
+export const NOTIFY_BUFFER_LIMIT = 500;
+const LOGIN_OP = 1;
+const RECONNECT_BASE_MS = 1_000;
+const RECONNECT_MAX_MS = 30_000;
+export class SlgConnection {
+    config;
+    manifest;
+    socket = null;
+    seq = 0;
+    pending = new Map();
+    notifications = [];
+    notificationSeq = 0;
+    reconnectAttempt = 0;
+    reconnectTimer = null;
+    stopped = false;
+    state = 'disconnected';
+    /** 最近一次登录失败（token 失效等）；成功后清空 */
+    loginError = null;
+    /** LOGIN 响应里的文档更新提示（协议 v32）；工具结果里透传给 AI */
+    docNotice = null;
+    constructor(config, manifest, notifyLimit = NOTIFY_BUFFER_LIMIT) {
+        this.config = config;
+        this.manifest = manifest;
+        this.notifyLimit = notifyLimit;
+    }
+    notifyLimit;
+    start() {
+        this.stopped = false;
+        void this.connect();
+    }
+    async stop() {
+        this.stopped = true;
+        if (this.reconnectTimer !== null) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        for (const [, pending] of this.pending) {
+            clearTimeout(pending.timer);
+            pending.resolve({ ok: false, error: { code: 'MCP_SHUTDOWN', message: 'MCP 服务已停止' } });
+        }
+        this.pending.clear();
+        const socket = this.socket;
+        this.socket = null;
+        if (socket && socket.readyState === WebSocket.OPEN) {
+            await new Promise((resolve) => {
+                socket.once('close', () => resolve());
+                socket.close(1000, 'shutdown');
+            });
+        }
+    }
+    getState() {
+        return this.state;
+    }
+    isReady() {
+        return this.state === 'connected';
+    }
+    /** 自最近一次读取以来的通知快照（id > sinceId），并带下一个游标 */
+    notificationsSince(sinceId, limit) {
+        const entries = this.notifications.filter((entry) => entry.id > sinceId).slice(0, limit);
+        const nextSinceId = entries.length > 0 ? entries.at(-1).id : sinceId;
+        return { entries, nextSinceId };
+    }
+    /** 压一条合成通知（连接建立 / 断开重连），让 AI 感知连接事件 */
+    pushSynthetic(state) {
+        this.buffer({
+            eventId: null,
+            op: -1,
+            name: 'connection',
+            data: { state, at: new Date().toISOString(), server: this.config.server },
+        });
+    }
+    buffer(entry) {
+        this.notificationSeq += 1;
+        this.notifications.push({ ...entry, id: this.notificationSeq });
+        if (this.notifications.length > this.notifyLimit) {
+            this.notifications.splice(0, this.notifications.length - this.notifyLimit);
+        }
+    }
+    /**
+     * 调用一个游戏协议：未就绪时等待（连接 / 登录进行中），超时或失败按错误返回。
+     * 不抛异常——调用方（MCP 工具）把错误原样转成工具结果。
+     */
+    async request(op, data) {
+        const waitError = await this.waitReady();
+        if (waitError !== null) {
+            return { ok: false, error: waitError };
+        }
+        const socket = this.socket;
+        if (!socket || socket.readyState !== WebSocket.OPEN) {
+            return { ok: false, error: { code: 'MCP_NOT_CONNECTED', message: `与游戏服务器的连接不可用（${this.state}），正在自动重连，请稍后重试` } };
+        }
+        this.seq += 1;
+        const seq = this.seq;
+        const frame = JSON.stringify({ op, seq, data });
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(seq);
+                resolve({
+                    ok: false,
+                    error: { code: 'MCP_TIMEOUT', message: `请求超时（> ${this.config.requestTimeoutMs}ms）：连接可能已中断，自动重连后请重试` },
+                });
+            }, this.config.requestTimeoutMs);
+            this.pending.set(seq, { resolve, timer });
+            socket.send(frame);
+        });
+    }
+    /** 等到 connected（含登录完成）；返回 null 表示就绪，否则为错误 */
+    async waitReady() {
+        if (this.isReady()) {
+            return null;
+        }
+        const deadline = Date.now() + this.config.readyTimeoutMs;
+        while (Date.now() < deadline && !this.stopped) {
+            if (this.loginError !== null) {
+                return { ...this.loginError, message: `登录失败：${this.loginError.message}（请检查 MCP 配置里的 SLG_TOKEN / SLG_SERVER）` };
+            }
+            if (this.isReady()) {
+                return null;
+            }
+            await new Promise((resolve) => setTimeout(resolve, 200));
+        }
+        return {
+            code: 'MCP_NOT_READY',
+            message: `尚未连上游戏服务器（${this.state}）：它会持续自动重连，请稍后重试；长时间不行请检查 SLG_SERVER（当前 ${this.config.server}）与网络`,
+        };
+    }
+    async connect() {
+        if (this.stopped) {
+            return;
+        }
+        this.state = 'connecting';
+        await new Promise((resolve) => {
+            const socket = new WebSocket(this.config.server);
+            this.socket = socket;
+            const failTimer = setTimeout(() => {
+                socket.terminate();
+                resolve();
+            }, this.config.readyTimeoutMs);
+            socket.once('open', () => {
+                clearTimeout(failTimer);
+                void this.login(socket).finally(() => resolve());
+            });
+            socket.once('error', () => {
+                clearTimeout(failTimer);
+                resolve();
+            });
+            socket.on('message', (raw) => this.handleMessage(raw.toString()));
+            socket.once('close', () => this.handleClose(socket));
+        });
+        if (!this.isReady()) {
+            this.scheduleReconnect();
+        }
+    }
+    async login(socket) {
+        const data = {
+            token: this.config.token,
+            asAgent: true,
+            docVersion: this.manifest.version,
+        };
+        if (this.config.agentModel !== null) {
+            data.agentModel = this.config.agentModel;
+        }
+        const response = await this.rawRequest(socket, LOGIN_OP, data);
+        if (response.ok) {
+            this.loginError = null;
+            this.docNotice = typeof response.data.docNotice === 'string' ? response.data.docNotice : null;
+            this.state = 'connected';
+            this.reconnectAttempt = 0;
+            this.pushSynthetic(this.notificationSeq > 0 ? 'reconnected' : 'connected');
+        }
+        else {
+            this.loginError = response.error;
+            this.state = 'disconnected';
+            socket.close(4001, 'login failed');
+        }
+    }
+    /** 不经 waitReady 的裸请求（登录用；连接刚打开必然可用） */
+    rawRequest(socket, op, data) {
+        this.seq += 1;
+        const seq = this.seq;
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(seq);
+                resolve({ ok: false, error: { code: 'MCP_TIMEOUT', message: '登录请求超时' } });
+            }, this.config.requestTimeoutMs);
+            this.pending.set(seq, { resolve, timer });
+            socket.send(JSON.stringify({ op, seq, data }));
+        });
+    }
+    handleMessage(raw) {
+        let frame;
+        try {
+            frame = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        if (frame.push === true || typeof frame.op === 'number' && frame.op >= 2000) {
+            const opNames = this.manifest.ops.find((candidate) => candidate.op === frame.op);
+            this.buffer({
+                eventId: typeof frame.eventId === 'number' ? frame.eventId : null,
+                op: typeof frame.op === 'number' ? frame.op : -1,
+                name: opNames?.name ?? `op_${String(frame.op)}`,
+                data: (frame.data ?? {}),
+            });
+            return;
+        }
+        if (typeof frame.seq === 'number') {
+            const pending = this.pending.get(frame.seq);
+            if (!pending) {
+                return;
+            }
+            this.pending.delete(frame.seq);
+            clearTimeout(pending.timer);
+            if (frame.ok === true) {
+                pending.resolve({ ok: true, data: (frame.data ?? {}) });
+                return;
+            }
+            const error = frame.error;
+            pending.resolve({ ok: false, error: { code: error?.code ?? 'UNKNOWN', message: error?.message ?? '未知错误' } });
+        }
+    }
+    handleClose(socket) {
+        if (this.socket !== socket) {
+            return;
+        }
+        const wasReady = this.state === 'connected';
+        this.socket = null;
+        this.state = 'disconnected';
+        for (const [, pending] of this.pending) {
+            clearTimeout(pending.timer);
+            pending.resolve({ ok: false, error: { code: 'MCP_DISCONNECTED', message: '连接已断开，正在自动重连，请重试' } });
+        }
+        this.pending.clear();
+        if (wasReady && !this.stopped) {
+            this.pushSynthetic('disconnected');
+        }
+        this.scheduleReconnect();
+    }
+    scheduleReconnect() {
+        if (this.stopped || this.reconnectTimer !== null) {
+            return;
+        }
+        const delay = Math.min(RECONNECT_BASE_MS * 2 ** this.reconnectAttempt, RECONNECT_MAX_MS);
+        this.reconnectAttempt += 1;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            void this.connect();
+        }, delay);
+    }
+}

package/dist/index.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+// slg-mcp 入口（AISLG-131）：stdio 传输的 MCP Server。stdout 是 JSON-RPC 通道，
+// 一切日志走 stderr。启动即连游戏服务器并自动重连；SLG_TOKEN 缺失时以清晰
+// 报错退出（AI 工具的 MCP 面板会把 stderr 展示给玩家）。
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { readConfig } from './config.js';
+import { SlgConnection } from './connection.js';
+import { createMcpServer } from './server.js';
+import { loadManifest, loadManifestMarkdown } from './manifest.js';
+async function main() {
+    const parsed = readConfig(process.env);
+    if ('error' in parsed) {
+        console.error(`[slg-mcp] ${parsed.error}`);
+        process.exit(1);
+    }
+    const config = parsed.config;
+    const manifest = loadManifest();
+    const connection = new SlgConnection(config, manifest);
+    connection.start();
+    const server = createMcpServer(config, manifest, connection, loadManifestMarkdown());
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`[slg-mcp] 已启动：${manifest.ops.length} 个协议操作，工具由清单生成（文档版本 v${manifest.version}）；服务器 ${config.server}`);
+    const shutdown = () => {
+        void connection.stop().finally(() => process.exit(0));
+    };
+    process.once('SIGINT', shutdown);
+    process.once('SIGTERM', shutdown);
+}
+main().catch((err) => {
+    console.error('[slg-mcp] 启动失败:', err instanceof Error ? err.message : err);
+    process.exit(1);
+});

package/dist/manifest.js

@@ -0,0 +1,75 @@
+// 协议清单（docs/agent-api.json 的同步副本，见 scripts/sync-manifest.mjs）：
+// MCP 工具在启动时由清单生成——一个 op 对应一个 tool，协议新增操作后重新
+// sync:manifest 即出现，不用手写。排除规则（与后端的角色限制对齐，见
+// backend/api/src/handlers*.ts 的 conn.role !== 'player' 拦截）：
+// - preAuth（登录前）的 op：WX_* / GOOGLE_LOGIN / GITHUB_AUTH_START / OAUTH_REDEEM——
+//   仅供网页与微信小游戏；
+// - LOGIN / LOGOUT：由本服务自己的连接管理，暴露成工具只会破坏连接；
+// - 仅玩家连接可调：RESET_ACCOUNT / GOOGLE_BIND / GET_AGENT_TOKEN / RESET_AGENT_TOKEN
+//   （Agent 连接一律 AGENT_FORBIDDEN）。
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** 仅玩家连接可调、不生成工具的 op 名（preAuth 之外的补充名单） */
+const PLAYER_ONLY_OPS = new Set(['RESET_ACCOUNT', 'GOOGLE_BIND', 'GET_AGENT_TOKEN', 'RESET_AGENT_TOKEN']);
+/** 由本服务自行管理、不作为工具暴露的 op 名 */
+const SELF_MANAGED_OPS = new Set(['LOGIN', 'LOGOUT']);
+/** manifest/ 目录：src 与 dist 到它的相对层级一致，运行时定位无需打包器支持 */
+function manifestDir() {
+    return join(dirname(fileURLToPath(import.meta.url)), '..', 'manifest');
+}
+export function loadManifest() {
+    const raw = JSON.parse(readFileSync(join(manifestDir(), 'agent-api.json'), 'utf8'));
+    return raw;
+}
+export function loadManifestMarkdown() {
+    return readFileSync(join(manifestDir(), 'agent-api.md'), 'utf8');
+}
+/** 生成 MCP 工具用的 op 清单（保留原有顺序，剔除排除项） */
+export function toolOps(manifest) {
+    return manifest.ops.filter((op) => op.kind === 'request' && !op.preAuth && !SELF_MANAGED_OPS.has(op.name) && !PLAYER_ONLY_OPS.has(op.name));
+}
+/** 字段名必须是合法标识符：清单里的「（规则）」等纯文档行不是真实参数，跳过 */
+const IDENTIFIER_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** 单引号字面量联合（"'a' | 'b'"）→ 枚举；其余按基础类型映射，复杂类型宽松放行 */
+function parseKind(typeText) {
+    if (typeText === 'boolean') {
+        return { kind: 'boolean', options: [] };
+    }
+    if (typeText === 'number') {
+        return { kind: 'number', options: [] };
+    }
+    const options = [...typeText.matchAll(/'([^']+)'/g)].map((match) => match[1]);
+    if (options.length > 0 && /^[\s'|-]+$/.test(typeText.replace(/'[^']*'/g, ''))) {
+        return { kind: 'enum', options };
+    }
+    // 纯 string / 'string | null' 等含 string 字样的都按 string 收
+    if (typeText.split('|').every((part) => part.trim() === 'string' || part.trim() === 'null')) {
+        return { kind: 'string', options: [] };
+    }
+    return { kind: 'any', options: [] };
+}
+/** op 的请求字段 → 工具入参定义；desc 以「必填」开头视为必填（清单约定） */
+export function toolParams(op) {
+    const fields = op.requestFields ?? [];
+    const params = [];
+    for (const field of fields) {
+        if (!IDENTIFIER_NAME.test(field.name)) {
+            continue;
+        }
+        const { kind, options } = parseKind(field.type);
+        params.push({
+            name: field.name,
+            desc: field.desc,
+            required: field.desc.startsWith('必填'),
+            kind,
+            options,
+            typeText: field.type,
+        });
+    }
+    return params;
+}
+/** 错误码 → 描述映射（工具失败时附给人话解释） */
+export function errorCodeMap(manifest) {
+    return new Map(Object.entries(manifest.errorCodes ?? {}));
+}

package/dist/server.js

@@ -0,0 +1,96 @@
+// MCP 服务装配（AISLG-131）：工具全部由协议清单生成（manifest.ts 的排除与入参规则），
+// 另加两个固定件——get_notifications 工具（读推送环形缓冲）与 agent-api 资源（整份协议
+// 文档，AI 需要规则细节时自己读）。游戏侧返回错误时附错误码表里的人话解释；
+// LOGIN 带 docNotice 时在工具结果开头提示 AI 更新文档。
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { errorCodeMap, loadManifestMarkdown, toolOps, toolParams, } from './manifest.js';
+export const AGENT_API_RESOURCE_URI = 'slg://agent-api.md';
+const NOTIFICATIONS_TOOL = 'get_notifications';
+const NOTIFICATION_PAGE_LIMIT = 50;
+function zodForParam(param) {
+    const base = param.kind === 'enum'
+        ? z.enum(param.options)
+        : param.kind === 'number'
+            ? z.number()
+            : param.kind === 'boolean'
+                ? z.boolean()
+                : param.kind === 'string'
+                    ? z.string()
+                    : z.any();
+    const withDesc = base.describe(param.kind === 'any' ? `${param.desc}（类型：${param.typeText}，结构按协议文档构造）` : param.desc);
+    return param.required ? withDesc : withDesc.optional();
+}
+function toolDescription(manifest, opName, summary, agentNote) {
+    const lines = [summary];
+    if (agentNote) {
+        lines.push(`\n使用建议：${agentNote}`);
+    }
+    lines.push(`\n（协议 op ${opName}，文档版本 v${manifest.version}；完整规则可读资源 ${AGENT_API_RESOURCE_URI}）`);
+    return lines.join('\n');
+}
+function respondText(text, isError = false) {
+    return { text, isError };
+}
+/** 组装工具结果：docNotice 前置提示 */
+function formatOutcome(connection, outcome) {
+    const prefix = connection.docNotice !== null ? `[协议文档更新提示] ${connection.docNotice}\n\n` : '';
+    if (!outcome.isError) {
+        return respondText(prefix + outcome.text);
+    }
+    return respondText(prefix + outcome.text, true);
+}
+export function createMcpServer(config, manifest, connection, manifestMarkdown = loadManifestMarkdown()) {
+    const server = new McpServer({ name: 'slg-mcp', version: getVersion() });
+    const errorLookup = errorCodeMap(manifest);
+    for (const op of toolOps(manifest)) {
+        const shape = {};
+        for (const param of toolParams(op)) {
+            shape[param.name] = zodForParam(param);
+        }
+        const description = toolDescription(manifest, op.name, op.summary, op.agentNote);
+        server.registerTool(op.name, { title: op.title, description, inputSchema: shape }, async (args) => {
+            const response = await connection.request(op.op, (args ?? {}));
+            const outcome = response.ok
+                ? respondText(JSON.stringify(response.data, null, 2))
+                : respondText(describeError(errorLookup, response.error), true);
+            const decorated = formatOutcome(connection, outcome);
+            return { content: [{ type: 'text', text: decorated.text }], isError: decorated.isError };
+        });
+    }
+    server.registerTool(NOTIFICATIONS_TOOL, {
+        title: '读取新消息（服务器推送）',
+        description: '读取游戏服务器主动推送的消息（op ≥ 2000：建造完成、来袭预警、战报、资源与地块变化等）与连接状态变化。推送先存在本地缓冲，用本工具增量读取：传入上次返回的 nextSinceId（首次不传 = 从头读），只返回更新的部分。定时轮询本工具即可跟上游戏内发生的事情。',
+        inputSchema: {
+            sinceId: z.number().int().min(0).describe('上一次调用返回的 nextSinceId；不传表示从头读取缓冲内的全部消息').optional(),
+            limit: z.number().int().min(1).max(200).describe('本次最多返回条数，默认 50').optional(),
+        },
+    }, async (args) => {
+        const sinceId = typeof args.sinceId === 'number' ? args.sinceId : 0;
+        const limit = typeof args.limit === 'number' ? args.limit : NOTIFICATION_PAGE_LIMIT;
+        const { entries, nextSinceId } = connection.notificationsSince(sinceId, limit);
+        const payload = {
+            notifications: entries,
+            nextSinceId,
+            hasMore: entries.length === limit && connection.notificationsSince(nextSinceId, 1).entries.length > 0,
+            connection: { state: connection.getState(), server: config.server },
+        };
+        const decorated = formatOutcome(connection, respondText(JSON.stringify(payload, null, 2)));
+        return { content: [{ type: 'text', text: decorated.text }], isError: decorated.isError };
+    });
+    server.registerResource('agent-api', AGENT_API_RESOURCE_URI, { mimeType: 'text/markdown', description: `《SLG》Agent API 完整协议文档（v${manifest.version}）：全部操作、字段、错误码与游戏规则数值。` }, async (uri) => ({
+        contents: [{ uri: uri.href, text: manifestMarkdown, mimeType: 'text/markdown' }],
+    }));
+    return server;
+}
+function describeError(errorLookup, error) {
+    const known = errorLookup.get(error.code);
+    const parts = [`游戏服务器返回错误 ${error.code}：${error.message}`];
+    if (known) {
+        parts.push(`（${known.desc}${known.action ? `；${known.action}` : ''}）`);
+    }
+    return parts.join('');
+}
+function getVersion() {
+    return process.env.npm_package_version ?? '0.1.0';
+}