@uwa4d/openapi-mcp 0.2.0-beta.0 → 0.2.0-beta.2

package/dist/server.js

@@ -1,10 +1,11 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { UwaClient } from './client.js';
+import { registerCompositeTools, COMPOSITE_TOOLS, selectCompositeTools } from './composite/index.js';
 import { selectOperations } from './presets.js';
 import { loadSpec } from './spec.js';
 import { makeHandler, toolConfig, toolName } from './tools.js';
-export const PACKAGE_VERSION = '0.1.0';
+export const PACKAGE_VERSION = '0.2.0';
 export function createServer(opts) {
     const spec = loadSpec(opts.specPath);
     const operations = selectOperations(spec.operations, { tools: opts.tools, engine: opts.engine });
@@ -17,11 +18,21 @@ export function createServer(opts) {
     for (const op of operations) {
         server.registerTool(toolName(op.id, opts.nameCase, opts.namePrefix), toolConfig(op), makeHandler(op, client, opts.maxRows, opts.maxChars));
     }
-    return { server, toolCount: operations.length, total: spec.operations.length };
+    const compositeCount = registerCompositeTools(server, client, {
+        tools: opts.tools,
+        engine: opts.engine,
+        nameCase: opts.nameCase,
+        namePrefix: opts.namePrefix,
+        maxChars: opts.maxChars,
+    });
+    const toolCount = operations.length + compositeCount;
+    const total = spec.operations.length + COMPOSITE_TOOLS.length;
+    return { server, toolCount, total, atomicCount: operations.length, compositeCount };
 }
 export async function startStdio(opts) {
-    const { server, toolCount, total } = createServer(opts);
+    const { server, toolCount, total, atomicCount, compositeCount } = createServer(opts);
     // stdout 是 MCP 协议通道，任何日志都必须走 stderr
-    console.error(`[uwa-openapi-mcp] 已加载 ${toolCount}/${total} 个工具，接口地址 ${opts.baseUrl}`);
+    console.error(`[uwa-openapi-mcp] 已加载 ${toolCount}/${total} 个工具（原子 ${atomicCount} + 复合 ${compositeCount}），接口地址 ${opts.baseUrl}`);
     await server.connect(new StdioServerTransport());
 }
+export { selectCompositeTools, COMPOSITE_TOOLS };

package/dist/tools.d.ts

@@ -28,6 +28,14 @@ export interface ToolResult {
  * 帧号范围和步长，并在点数对不上时给出警告，从结构上消除歧义。
  */
 export declare function annotateCurveAxes(data: unknown): unknown;
+/**
+ * 报告列表接口一次返回、按项目组分组。但上游会把同一份报告挂到每个项目组下
+ * （沙箱实测多组两两交集 100%），直接按组统计会成倍放大。
+ *
+ * 这里就地合并：按 link 里的 project= 判定真实归属，每份报告只保留在正确的组里。
+ * 不额外打接口。上游修好后检测不到重复，本函数原样返回。
+ */
+export declare function annotateProjectGroups(data: unknown): unknown;
 export declare function makeHandler(op: Operation, client: UwaClient, defaultMaxRows: number, maxChars: number): (args: Record<string, unknown>) => Promise<ToolResult>;
 export declare function toolConfig(op: Operation): {
     title: string;

package/dist/tools.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { UwaApiError } from './client.js';
+import { versionGuideFor } from './version-guide.js';
 const ENGINE_LABEL = { unity: 'Unity', unreal: 'UE' };
 /**
  * 预签名数据默认完整返回，不按条数截断——实测各接口解压后在 10 KB ~ 500 KB 之间，
@@ -36,6 +37,10 @@ function zodFor(param) {
  */
 function describe(op) {
     const lines = [op.summary || op.name];
+    // v1/v2 选用规则放在最前，避免模型淹没在长 notes 里选错接口
+    const guide = versionGuideFor(op.id);
+    if (guide)
+        lines.push(guide);
     const engines = op.engines.map((e) => ENGINE_LABEL[e]).join(' / ');
     lines.push(`适用引擎：${engines}｜模块：${op.modules.join(',')}｜${op.method} ${op.path}`);
     const sdk = op.variants.find((v) => v.sdkRequirement)?.sdkRequirement;
@@ -145,13 +150,58 @@ function summarize(payload, maxRows, maxChars) {
         rowTruncated = maxRows > 0 && lines.length > maxRows;
         body = rowTruncated ? lines.slice(0, maxRows).join('\n') : (payload.text ?? '');
     }
-    let text = typeof body === 'string' ? body : JSON.stringify(body, null, 2);
-    let charTruncated = false;
-    if (maxChars > 0 && text.length > maxChars) {
-        charTruncated = true;
-        text = text.slice(0, maxChars);
+    const fitted = fitToChars(body, maxChars);
+    return { rowTruncated, total, ...fitted };
+}
+const serialize = (v) => (typeof v === 'string' ? v : JSON.stringify(v, null, 2));
+/**
+ * 把返回内容压到字符上限以内。
+ *
+ * 直接按字符裁剪 JSON 会切出非法结构，模型没法解析。因此优先按条目缩减
+ * 主数据数组——二分找出能放下的最大条数，保留完整的 JSON 结构，
+ * 并在元信息里说明丢了多少。只有在没有数组可缩减时才退化为字符串截断。
+ */
+function fitToChars(body, maxChars) {
+    const full = serialize(body);
+    if (maxChars <= 0 || full.length <= maxChars) {
+        return { charTruncated: false, chars: full.length, body: full };
     }
-    return { rowTruncated, charTruncated, total, chars: text.length, body: text };
+    const rebuild = (n) => {
+        if (Array.isArray(body))
+            return serialize(body.slice(0, n));
+        if (body && typeof body === 'object') {
+            const obj = body;
+            const key = mainArrayKey(obj);
+            if (!key)
+                return null;
+            return serialize({ ...obj, [key]: obj[key].slice(0, n) });
+        }
+        return null;
+    };
+    const count = Array.isArray(body)
+        ? body.length
+        : body && typeof body === 'object'
+            ? (() => {
+                const key = mainArrayKey(body);
+                return key ? body[key].length : 0;
+            })()
+            : 0;
+    if (count > 0 && rebuild(0) !== null) {
+        // 二分出能放进上限的最大条数
+        let lo = 0;
+        let hi = count;
+        while (lo < hi) {
+            const mid = Math.ceil((lo + hi) / 2);
+            const text = rebuild(mid);
+            if (text.length <= maxChars)
+                lo = mid;
+            else
+                hi = mid - 1;
+        }
+        const text = rebuild(lo);
+        return { charTruncated: true, kept: lo, chars: text.length, body: text };
+    }
+    return { charTruncated: true, chars: maxChars, body: full.slice(0, maxChars) };
 }
 function isObj(v) {
     return typeof v === 'object' && v !== null && !Array.isArray(v);
@@ -196,6 +246,93 @@ export function annotateCurveAxes(data) {
         _axisHint: '每条曲线按 _axisBinding[曲线名].xAxisSource 指定的横轴取值，不要统一使用外层 x_axis',
     };
 }
+const RECORD_ARRAY_KEYS = /^gotOnline.*Records$/;
+/**
+ * 报告列表接口一次返回、按项目组分组。但上游会把同一份报告挂到每个项目组下
+ * （沙箱实测多组两两交集 100%），直接按组统计会成倍放大。
+ *
+ * 这里就地合并：按 link 里的 project= 判定真实归属，每份报告只保留在正确的组里。
+ * 不额外打接口。上游修好后检测不到重复，本函数原样返回。
+ */
+export function annotateProjectGroups(data) {
+    if (!isObj(data) || !Array.isArray(data['content']))
+        return data;
+    const groups = data['content'].filter(isObj);
+    if (groups.length < 2)
+        return data;
+    // dataKey → 出现过的项目组；以及「该报告在哪个数组字段里、原文是什么」
+    const groupsOf = new Map();
+    const firstSeen = new Map();
+    for (const g of groups) {
+        const gid = String(g['projectGroupId'] ?? '');
+        if (!gid)
+            continue;
+        for (const [k, v] of Object.entries(g)) {
+            if (!RECORD_ARRAY_KEYS.test(k) || !Array.isArray(v))
+                continue;
+            for (const r of v) {
+                if (!isObj(r))
+                    continue;
+                const key = typeof r['dataKey'] === 'string' ? r['dataKey'] : null;
+                if (!key)
+                    continue;
+                if (!groupsOf.has(key))
+                    groupsOf.set(key, new Set());
+                groupsOf.get(key).add(gid);
+                if (!firstSeen.has(key)) {
+                    const fromLink = /[?&]project=(\d+)/.exec(String(r['link'] ?? ''))?.[1];
+                    firstSeen.set(key, { arrayKey: k, record: r, realGid: fromLink ?? gid });
+                }
+            }
+        }
+    }
+    const duplicated = [...groupsOf.values()].some((gs) => gs.size > 1);
+    if (!duplicated)
+        return data;
+    // 已知项目组壳子（保留名称、engine 等元信息），报告重新按真实归属灌入
+    const shells = new Map();
+    for (const g of groups) {
+        const gid = String(g['projectGroupId'] ?? '');
+        if (!gid || shells.has(gid))
+            continue;
+        const shell = { ...g };
+        for (const k of Object.keys(shell)) {
+            if (RECORD_ARRAY_KEYS.test(k))
+                shell[k] = [];
+        }
+        shells.set(gid, shell);
+    }
+    let placed = 0;
+    let orphaned = 0;
+    for (const { arrayKey, record, realGid } of firstSeen.values()) {
+        let shell = shells.get(realGid);
+        if (!shell) {
+            // link 指向的组不在本页 content 里——仍给出一份壳，避免报告丢失
+            shell = {
+                projectGroupId: Number.isFinite(Number(realGid)) ? Number(realGid) : realGid,
+                projectGroupName: `(id=${realGid})`,
+                engine: null,
+            };
+            shells.set(realGid, shell);
+            orphaned++;
+        }
+        if (!Array.isArray(shell[arrayKey]))
+            shell[arrayKey] = [];
+        shell[arrayKey].push(record);
+        placed++;
+    }
+    // 丢掉合并后一个报告都没有的空组（它们原先只有别人的副本）
+    const content = [...shells.values()].filter((g) => Object.entries(g).some(([k, v]) => RECORD_ARRAY_KEYS.test(k) && Array.isArray(v) && v.length > 0));
+    return {
+        ...data,
+        content,
+        _deduplicated: true,
+        _uniqueReportCount: placed,
+        _dedupeNote: `上游把同一份报告重复挂在多个项目组下，已按 link 中 project= 合并归位，去重后 ${placed} 份` +
+            (orphaned ? `（其中 ${orphaned} 份所属项目组不在本页，已单独列出）` : '') +
+            '。可直接按项目组统计。',
+    };
+}
 /** MCP 的 content.text 必须是字符串，undefined 会让客户端校验失败。 */
 function asText(value) {
     if (typeof value === 'string')
@@ -221,20 +358,41 @@ export function makeHandler(op, client, defaultMaxRows, maxChars) {
                     if (args[p.name] !== undefined)
                         body[p.name] = args[p.name];
             }
-            const data = annotateCurveAxes(await client.call(op.method, op.path, apiVersion, query, body));
+            const raw = await client.call(op.method, op.path, apiVersion, query, body);
+            const data = annotateProjectGroups(annotateCurveAxes(raw));
             const presignUrl = op.returnsPresignUrl && data && typeof data === 'object'
                 ? data['dataPresignUrl']
                 : undefined;
             if (!presignUrl || !wantDownload) {
-                return { content: [{ type: 'text', text: asText(data) }] };
+                // 非预签名接口同样可能很大（如报告列表 50 条约 56K 字符、
+                // 统计接口批量查十几份报告可达 20 万字符），这里必须同样设闸门，
+                // 否则会直接撑爆模型上下文。
+                const fitted = fitToChars(data, maxChars);
+                if (!fitted.charTruncated) {
+                    return { content: [{ type: 'text', text: asText(fitted.body) }] };
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: asText({
+                                _truncated: `返回内容超过 ${maxChars} 字符上限，已缩减为 ${fitted.kept ?? 0} 条。` +
+                                    `请缩小查询范围后重试${op.query.some((p) => p.name === 'pageSize') ? '（如调小 pageSize 分页获取）' : '（如减少批量查询的条目数）'}，` +
+                                    `或在启动参数里调大 --max-chars。`,
+                                _returnedChars: fitted.chars,
+                            }),
+                        },
+                        { type: 'text', text: asText(fitted.body) },
+                    ],
+                };
             }
             const payload = await client.downloadPresign(presignUrl);
-            const { rowTruncated, charTruncated, total, chars, body: content } = summarize(payload, maxRows, maxChars);
+            const { rowTruncated, charTruncated, total, kept, chars, body: content } = summarize(payload, maxRows, maxChars);
             const notes = [];
             if (rowTruncated)
                 notes.push(`按 maxRows=${maxRows} 截断，去掉 maxRows 参数可取全量`);
             if (charTruncated) {
-                notes.push(`内容超过 ${maxChars} 字符上限已截断，尾部数据缺失。` +
+                notes.push(`内容超过 ${maxChars} 字符上限，已缩减为 ${kept ?? 0} 条。` +
                     `如需完整数据，用 download=false 拿 dataPresignUrl 自行下载，或启动时调大 --max-chars`);
             }
             const meta = {

package/dist/version-guide.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 版本成对工具的选用规则。
+ *
+ * 集中手写、挂到 describe() 首段，避免散落在 notes 里被模型漏读。
+ * 不塞进 docs/ 生成链路——刷新官方文档镜像不会冲掉这里。
+ */
+/** 写入工具 description 的「选用规则」块，key 为 operation id。 */
+export declare const VERSION_GUIDE: Record<string, string>;
+export declare function versionGuideFor(opId: string): string | undefined;

package/dist/version-guide.js

@@ -0,0 +1,87 @@
+/**
+ * 版本成对工具的选用规则。
+ *
+ * 集中手写、挂到 describe() 首段，避免散落在 notes 里被模型漏读。
+ * 不塞进 docs/ 生成链路——刷新官方文档镜像不会冲掉这里。
+ */
+/** 写入工具 description 的「选用规则」块，key 为 operation id。 */
+export const VERSION_GUIDE = {
+    get_overview_statistic_v1: [
+        '【选用规则——务必先看】',
+        '- Unity：仅适用于解析日 < 2026-07-09 的 Overview 报告。新报告请改用 get_overview_statistic_v2。',
+        '- UE：仅适用于提交日 ≤ 2026-03-25 的 Overview 报告。新报告请改用 get_ue_overview_statistic_v2。',
+        '- 不确定日期时：先调 get_report_detail 看 createDate / engine / sdkVersion；或直接用复合工具 report_diagnosis / top_functions（内部自动路由）。',
+    ].join('\n'),
+    get_overview_statistic_v2: [
+        '【选用规则——务必先看】',
+        '- 仅 Unity。解析日 ≥ 2026-07-09 且 SDK ≥ 2.5.1 的 Overview 报告。',
+        '- 更早的 Unity 报告请用 get_overview_statistic_v1。UE 报告请用 get_ue_overview_statistic_v2（或旧报告用 get_overview_statistic_v1）。',
+        '- 不确定时用复合工具 report_diagnosis / top_functions，无需自己选版本。',
+    ].join('\n'),
+    get_ue_overview_statistic_v2: [
+        '【选用规则——务必先看】',
+        '- 仅 UE。提交日 > 2026-03-25 的 Overview 报告。',
+        '- 更早的 UE 报告请用 get_overview_statistic_v1。Unity 报告请用 get_overview_statistic_v1 或 get_overview_statistic_v2。',
+        '- 单次批量最多 30 份（文档写 50，实测上限 30）。不确定时用复合工具自动路由。',
+    ].join('\n'),
+    get_scene_statistic_v1: [
+        '【选用规则——务必先看】',
+        '- 仅 Unity。解析日 < 2026-07-09 的 Overview 报告场景统计。',
+        '- 新报告请改用 get_scene_statistic_v2。',
+    ].join('\n'),
+    get_scene_statistic_v2: [
+        '【选用规则——务必先看】',
+        '- 仅 Unity。解析日 ≥ 2026-07-09 且 SDK ≥ 2.5.1 的 Overview 报告场景统计。',
+        '- 更早的报告请用 get_scene_statistic_v1。',
+    ].join('\n'),
+    gotonline_overview_custom_dashboard: [
+        '【选用规则——务必先看】',
+        '- 自定义面板统计 1.0（抽帧曲线）。不支持 GPU 类面板。',
+        '- 需要 GPU 指标或更多统计值类型时，改用 gotonline_overview_indicator_statistic_dashboard（2.0，需 SDK ≥ 2.5.1）。',
+        '- 逐帧曲线用 gotonline_overview_indicator_curve_dashboard（2.0，最多 3 个面板）。',
+    ].join('\n'),
+    gotonline_overview_indicator_statistic_dashboard: [
+        '【选用规则——务必先看】',
+        '- 自定义面板统计 2.0。需 SDK ≥ 2.5.1，支持 GPU 指标，最多 15 个面板。',
+        '- 旧接口（抽帧、无 GPU）见 gotonline_overview_custom_dashboard。',
+        '- 只要逐帧曲线不要统计值时用 gotonline_overview_indicator_curve_dashboard。',
+    ].join('\n'),
+    gotonline_overview_indicator_curve_dashboard: [
+        '【选用规则——务必先看】',
+        '- 自定义面板帧数据 2.0。需 SDK ≥ 2.5.1，最多 3 个面板；不支持内存类面板。',
+        '- 要统计值（含场景维度）用 gotonline_overview_indicator_statistic_dashboard。',
+    ].join('\n'),
+    gotonline_overview_memory_usage_snapshot: [
+        '【选用规则——务必先看】',
+        '- 资源快照帧号 1.0。仅适用于解析日 < 2026-07-09 的报告。',
+        '- 新报告请用 gotonline_overview_dump_frames（快照帧 2.0）。',
+    ].join('\n'),
+    gotonline_overview_dump_frames: [
+        '【选用规则——务必先看】',
+        '- 快照帧 2.0。仅适用于解析日 ≥ 2026-07-09 且 SDK ≥ 2.5.1 的报告。',
+        '- 更早的报告请用 gotonline_overview_memory_usage_snapshot。',
+    ].join('\n'),
+    gotonline_overview_log_export: [
+        '【选用规则——务必先看】',
+        '- 运行日志 1.0。Unity：解析日 < 2026-07-09；UE：提交日 ≤ 2026-03-25。',
+        '- 新报告请用 gotonline_lg_runtime_log_entries_presign（运行日志 2.0）。',
+    ].join('\n'),
+    gotonline_lg_runtime_log_entries_presign: [
+        '【选用规则——务必先看】',
+        '- 运行日志 2.0（预签名）。解析日 ≥ 2026-07-09 且 SDK ≥ 2.5.1。',
+        '- 更早的报告请用 gotonline_overview_log_export。',
+    ].join('\n'),
+    gotonline_overview_group_export: [
+        '【选用规则——务必先看】',
+        '- UE 自定义函数组统计 1.0。仅适用于提交日 ≤ 2026-03-25 的 UE 报告。',
+        '- 新 UE 报告请用 gotonline_overview_method_group_statistic（需 Header api 版本 v1.0.2）。',
+    ].join('\n'),
+    gotonline_overview_method_group_statistic: [
+        '【选用规则——务必先看】',
+        '- 自定义函数组统计（Unity SDK ≥ 2.5.1；UE 提交日 > 2026-03-25，且 api 版本须 v1.0.2）。',
+        '- UE 旧报告请用 gotonline_overview_group_export。',
+    ].join('\n'),
+};
+export function versionGuideFor(opId) {
+    return VERSION_GUIDE[opId];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uwa4d/openapi-mcp",
-  "version": "0.2.0-beta.0",
+  "version": "0.2.0-beta.2",
   "description": "UWA 开放平台 MCP Server，将 UWA Open API 暴露为 MCP 工具供 AI 助手调用",
   "type": "module",
   "bin": {

package/spec/overrides.json

@@ -0,0 +1,26 @@
+{
+  "$comment": [
+    "官方文档与接口实际行为不符时的修正层。",
+    "生成 spec 时套用（见 scripts/parse-docs.ts），因此刷新 docs/ 下的文档不会冲掉这里的修正。",
+    "每条都必须写明 verifiedAt 与 evidence——没有实测依据不要往这里加，",
+    "否则下一个人无法判断该修正是否已经过时。",
+    "上游修好文档后应删除对应条目，而不是留着。"
+  ],
+  "operations": {
+    "get_ue_overview_statistic_v2": {
+      "reason": "文档称单次最多 50 份，实测上限为 30 份",
+      "verifiedAt": "2026-08-04",
+      "evidence": "30 个长 dataKey（参数串 1140 字符）成功；31 个短 dataKey（参数串 1094 字符，更短）失败并返回 20001，排除 URL 长度因素。49 个 key 逐个单查均正常，故确为批量条数限制。",
+      "replaceInText": [
+        {
+          "from": "最多 50 个",
+          "to": "最多 30 个（文档写 50，实测上限 30）"
+        },
+        {
+          "from": "单次请求最多查询 50 份报告",
+          "to": "单次请求最多查询 30 份报告（文档写 50，实测上限 30，超出会返回 20001）"
+        }
+      ]
+    }
+  }
+}

package/spec/uwa-openapi.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-08-04T07:36:54.873Z",
+  "generatedAt": "2026-08-04T09:11:08.206Z",
   "sourceDoc": "uwa-openapi-20260730.md",
   "operationCount": 55,
   "operations": [
@@ -928,14 +928,14 @@
           "type": "string",
           "required": false,
           "example": "1002,1003",
-          "description": "报告 recordId 列表，逗号分隔，最多 50 个。与 dataKeys 二选一，两者均填时取交集"
+          "description": "报告 recordId 列表，逗号分隔，最多 30 个（文档写 50，实测上限 30）。与 dataKeys 二选一，两者均填时取交集"
         },
         {
           "name": "dataKeys",
           "type": "string",
           "required": false,
           "example": "testDataKey1,testDataKey2",
-          "description": "报告 dataKey 列表，逗号分隔，最多 50 个。与 recordIds 二选一，两者均填时取交集"
+          "description": "报告 dataKey 列表，逗号分隔，最多 30 个（文档写 50，实测上限 30）。与 recordIds 二选一，两者均填时取交集"
         }
       ],
       "body": [],
@@ -956,7 +956,7 @@
           ],
           "notes": [
             "本接口仅支持 2026-03-25 之后提交的 UE Overview 报告；更早版本的报告应使用获取报告统计数据 1.0",
-            "单次请求最多查询 50 份报告，recordIds 与 dataKeys 至少填一个",
+            "单次请求最多查询 30 份报告（文档写 50，实测上限 30，超出会返回 20001），recordIds 与 dataKeys 至少填一个",
             "LLM 字段为 UE 专属低层内存分析数据，当报告未开启 LLM 采集时该字段可能为空数组 []"
           ],
           "returnRules": [],
@@ -966,14 +966,14 @@
               "type": "string",
               "required": false,
               "example": "1002,1003",
-              "description": "报告 recordId 列表，逗号分隔，最多 50 个。与 dataKeys 二选一，两者均填时取交集"
+              "description": "报告 recordId 列表，逗号分隔，最多 30 个（文档写 50，实测上限 30）。与 dataKeys 二选一，两者均填时取交集"
             },
             {
               "name": "dataKeys",
               "type": "string",
               "required": false,
               "example": "testDataKey1,testDataKey2",
-              "description": "报告 dataKey 列表，逗号分隔，最多 50 个。与 recordIds 二选一，两者均填时取交集"
+              "description": "报告 dataKey 列表，逗号分隔，最多 30 个（文档写 50，实测上限 30）。与 recordIds 二选一，两者均填时取交集"
             }
           ],
           "body": [],