@uwa4d/openapi-mcp 0.2.0-beta.1 → 0.2.0-beta.3

package/dist/composite/types.d.ts

@@ -0,0 +1,25 @@
+import { z, type ZodTypeAny } from 'zod';
+import type { Engine } from '../spec.js';
+import type { UwaClient } from '../client.js';
+import type { NameCase } from '../tools.js';
+import type { ToolResult } from '../tools.js';
+export interface CompositeContext {
+    client: UwaClient;
+    maxChars: number;
+    nameCase: NameCase;
+    namePrefix: string;
+    /** --engine 过滤，'all' 表示不过滤 */
+    engine: Engine | 'all';
+}
+export interface CompositeTool {
+    id: string;
+    title: string;
+    description: string;
+    /** 适用引擎；过滤 --engine 时用 */
+    engines: Engine[];
+    /** --tool 过滤键，除 id 外还可含 composite / preset.default 等 */
+    filterKeys: string[];
+    inputSchema: Record<string, ZodTypeAny>;
+    handler: (args: Record<string, unknown>, ctx: CompositeContext) => Promise<ToolResult>;
+}
+export { z };

package/dist/composite/types.js

@@ -0,0 +1,2 @@
+import { z } from 'zod';
+export { z };

package/dist/presets.js

@@ -25,6 +25,10 @@ export const PRESET_DEFAULT = [
     'gotonline_overview_memory_manage_data_report',
     'gotonline_overview_method_group_statistic',
     'gotonline_overview_stack_stutter_full_presign',
+    // 复合工具（手写，见 src/composite/）
+    'top_resources',
+    'top_functions',
+    'report_diagnosis',
 ];
 /**
  * 每个接口对应的一组过滤键，用户在 --tool 里写任意一个即可命中。

package/dist/server.d.ts

@@ -1,4 +1,5 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { COMPOSITE_TOOLS, selectCompositeTools } from './composite/index.js';
 import { type Engine } from './spec.js';
 import { type NameCase } from './tools.js';
 export interface ServerOptions {
@@ -16,10 +17,14 @@ export interface ServerOptions {
     timeoutMs: number;
     specPath?: string;
 }
-export declare const PACKAGE_VERSION = "0.1.0";
+/** 与 package.json 同步，避免 MCP 握手版本和 npm 包不一致。 */
+export declare const PACKAGE_VERSION: string;
 export declare function createServer(opts: ServerOptions): {
     server: McpServer;
     toolCount: number;
     total: number;
+    atomicCount: number;
+    compositeCount: number;
 };
 export declare function startStdio(opts: ServerOptions): Promise<void>;
+export { selectCompositeTools, COMPOSITE_TOOLS };

package/dist/server.js

@@ -1,10 +1,25 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 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';
+function readPackageVersion() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const pkg = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8'));
+        return pkg.version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+/** 与 package.json 同步，避免 MCP 握手版本和 npm 包不一致。 */
+export const PACKAGE_VERSION = readPackageVersion();
 export function createServer(opts) {
     const spec = loadSpec(opts.specPath);
     const operations = selectOperations(spec.operations, { tools: opts.tools, engine: opts.engine });
@@ -17,11 +32,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.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;

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,90 @@
+/**
+ * 版本成对工具的选用规则。
+ *
+ * 集中手写、挂到 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。',
+        '- 【横轴——勿混用】外层 x_axis 为逐帧共享横轴（1、2、3…）；y_axis.{指标名}.x_axis 为该曲线专属横轴（常见步长 30：0、30、60…）。',
+        '- 读取某条曲线时：若存在专属 x_axis 必须用专属，否则才用外层共享 x_axis。把共享横轴套到 FPS 等专属曲线会错位。',
+        '- 响应另含 _axisBinding / _axisHint，按其中 xAxisSource 取值即可。',
+    ].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.1",
+  "version": "0.2.0-beta.3",
   "description": "UWA 开放平台 MCP Server，将 UWA Open API 暴露为 MCP 工具供 AI 助手调用",
   "type": "module",
   "bin": {