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

package/dist/cli.js

@@ -2,9 +2,11 @@
 import { Command, Option } from 'commander';
 import { UwaClient } from './client.js';
 import { loadSpec } from './spec.js';
+import { compositeFilterKeys, selectCompositeTools, COMPOSITE_TOOLS } from './composite/index.js';
 import { filterKeys, selectOperations } from './presets.js';
 import { DEFAULT_MAX_CHARS, DEFAULT_MAX_ROWS, toolName } from './tools.js';
 import { PACKAGE_VERSION, startStdio } from './server.js';
+import { checkForUpdate, formatUpdateNotice, resolveUpdateChannel } from './version-check.js';
 const DEFAULT_BASE_URL = 'https://secure-api.uwa4d.com';
 const SANDBOX_BASE_URL = 'https://sandbox-api.uwa4d.com';
 function splitList(value) {
@@ -70,10 +72,10 @@ program
     .option('--spec <path>', '自定义 spec 文件路径')
     .action((opts) => {
     const spec = loadSpec(opts.spec);
-    const selected = new Set(selectOperations(spec.operations, {
-        tools: opts.tool ?? ['all'],
-        engine: opts.engine,
-    }).map((o) => o.id));
+    const toolFilter = opts.tool ?? ['all'];
+    const engine = opts.engine;
+    const selected = new Set(selectOperations(spec.operations, { tools: toolFilter, engine }).map((o) => o.id));
+    const selectedComposite = new Set(selectCompositeTools({ tools: toolFilter, engine }).map((t) => t.id));
     const byModule = new Map();
     for (const op of spec.operations) {
         const key = op.modules.join(',');
@@ -89,8 +91,19 @@ program
             console.log(`${mark} ${toolName(op.id, 'snake', '').padEnd(52)} ${op.method.padEnd(4)} ${engines.padEnd(7)} ${op.name}`);
         }
     }
-    console.log(`\n共 ${spec.operations.length} 个工具，当前条件选中 ${selected.size} 个（* 标记）`);
-    console.log(`可用过滤键：${[...new Set(spec.operations.flatMap(filterKeys))].sort().join(', ')}`);
+    console.log('\n## composite（手写复合工具）');
+    for (const t of COMPOSITE_TOOLS) {
+        const mark = selectedComposite.has(t.id) ? '*' : ' ';
+        const engines = t.engines.map((e) => (e === 'unity' ? 'U3D' : 'UE')).join('+');
+        console.log(`${mark} ${toolName(t.id, 'snake', '').padEnd(52)} CMP  ${engines.padEnd(7)} ${t.title}`);
+    }
+    const total = spec.operations.length + COMPOSITE_TOOLS.length;
+    const selectedCount = selected.size + selectedComposite.size;
+    console.log(`\n共 ${total} 个工具（原子 ${spec.operations.length} + 复合 ${COMPOSITE_TOOLS.length}），当前条件选中 ${selectedCount} 个（* 标记）`);
+    const keys = [
+        ...new Set([...spec.operations.flatMap(filterKeys), ...compositeFilterKeys()]),
+    ].sort();
+    console.log(`可用过滤键：${keys.join(', ')}`);
 });
 program
     .command('check')
@@ -121,6 +134,16 @@ program
         console.log('\n凭证有效，接口连通。');
         if (typeof total === 'number')
             console.log(`最近 7 天有 ${total} 份报告。`);
+        console.log(`\nMCP 包版本：${PACKAGE_VERSION}（${resolveUpdateChannel(PACKAGE_VERSION)} 通道）`);
+        if (process.env['UWA_MCP_SKIP_UPDATE_CHECK'] !== '1') {
+            const update = await checkForUpdate(PACKAGE_VERSION);
+            if (update) {
+                console.log(formatUpdateNotice(update));
+            }
+            else {
+                console.log('已是最新同通道版本（或暂时无法连接 npm registry）。');
+            }
+        }
         console.log('\n可以按 README 配置 MCP 客户端了。');
     }
     catch (err) {

package/dist/client.js

@@ -1,22 +1,12 @@
 import { gunzipSync } from 'node:zlib';
 import { authHeaders } from './auth.js';
+import { resolveErrorHint } from './error-hints.js';
 function isEnvelope(v) {
     if (!v || typeof v !== 'object' || Array.isArray(v))
         return false;
     const o = v;
     return o['status'] === 'success' || o['status'] === 'failed';
 }
-/** 常见错误码的排查提示，直接给到模型，省掉一轮试错。 */
-const ERROR_HINTS = {
-    20001: '业务参数不合法，核对参数名、取值范围和必填项（注意批量接口的参数名多为复数，如 dataKeys）',
-    23508: '数据服务错误，常见原因是报告不适用该接口版本（如新报告调用了 1.0 接口，或旧报告调用了 2.0 接口），改用对应版本重试',
-    24050: '该账号未开通 Open API 权限，请联系 UWA 工作人员开通',
-    24052: '请求参数有误，请对照接口文档检查',
-    24054: 'AppId 不存在，检查 appId 是否正确、是否用错了环境（sandbox / 线上凭证不通用）',
-    24056: '签名错误，检查 appSecret 是否正确',
-    24057: '时间戳过期，本机时间与服务端偏差不能超过 20 分钟',
-    30001: '服务端错误，常见原因是用错了引擎对应的接口（如对 UE 报告调用了 Unity 专用接口）',
-};
 export class UwaApiError extends Error {
     code;
     rawMessage;
@@ -68,8 +58,9 @@ export class UwaClient {
         if (parsed.status === 'failed' || parsed.error) {
             const code = parsed.error?.code ?? -1;
             const raw = parsed.error?.data?.rawMessage ?? '';
-            const hint = ERROR_HINTS[code];
-            throw new UwaApiError(code, raw, `[${code}] ${parsed.error?.message ?? '请求失败'}${raw ? ` (${raw})` : ''}${hint ? `\n排查建议：${hint}` : ''}`);
+            const apiMessage = parsed.error?.message ?? '请求失败';
+            const hint = resolveErrorHint(code, raw, apiMessage);
+            throw new UwaApiError(code, raw, `[${code}] ${apiMessage}${raw ? ` (${raw})` : ''}${hint ? `\n排查建议：${hint}` : ''}`);
         }
         return parsed.data ?? {};
     }

package/dist/composite/helpers.d.ts

@@ -0,0 +1,19 @@
+import type { ToolResult } from '../tools.js';
+export declare function isObj(v: unknown): v is Record<string, unknown>;
+export declare function asText(value: unknown): string;
+/** 把任意结果压进字符闸门，超限时保留元信息 + 提示。 */
+export declare function jsonToolResult(data: unknown, maxChars: number): ToolResult;
+export declare function errorResult(err: unknown): ToolResult;
+/** 从 createDate 字符串取出 YYYY-MM-DD，无法解析则返回空。 */
+export declare function dayOf(dateStr: string | undefined | null): string | null;
+export declare function dayGte(day: string, cutoff: string): boolean;
+export declare function dayGt(day: string, cutoff: string): boolean;
+export declare function dayLt(day: string, cutoff: string): boolean;
+export declare function dayLte(day: string, cutoff: string): boolean;
+/** 宽松比较 SDK 版本号（按点分数字）。缺省或无法解析视为不满足。 */
+export declare function sdkAtLeast(sdk: string | undefined | null, min: string): boolean;
+export declare function requireReportKey(args: Record<string, unknown>): {
+    dataKey?: string;
+    recordId?: string;
+};
+export declare function topNOf(args: Record<string, unknown>, fallback?: number): number;

package/dist/composite/helpers.js

@@ -0,0 +1,90 @@
+export function isObj(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+export function asText(value) {
+    if (typeof value === 'string')
+        return value;
+    if (value === undefined || value === null)
+        return '(无返回内容)';
+    return JSON.stringify(value, null, 2);
+}
+/** 把任意结果压进字符闸门，超限时保留元信息 + 提示。 */
+export function jsonToolResult(data, maxChars) {
+    const text = asText(data);
+    if (maxChars <= 0 || text.length <= maxChars) {
+        return { content: [{ type: 'text', text }] };
+    }
+    return {
+        content: [
+            {
+                type: 'text',
+                text: asText({
+                    _truncated: `返回超过 ${maxChars} 字符上限已截断。请缩小 topN / 查询范围，或启动时调大 --max-chars。`,
+                    _returnedChars: maxChars,
+                }),
+            },
+            { type: 'text', text: text.slice(0, maxChars) },
+        ],
+    };
+}
+export function errorResult(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: [{ type: 'text', text: msg }], isError: true };
+}
+/** 从 createDate 字符串取出 YYYY-MM-DD，无法解析则返回空。 */
+export function dayOf(dateStr) {
+    if (!dateStr)
+        return null;
+    const m = /(\d{4}-\d{2}-\d{2})/.exec(String(dateStr));
+    return m?.[1] ?? null;
+}
+export function dayGte(day, cutoff) {
+    return day >= cutoff;
+}
+export function dayGt(day, cutoff) {
+    return day > cutoff;
+}
+export function dayLt(day, cutoff) {
+    return day < cutoff;
+}
+export function dayLte(day, cutoff) {
+    return day <= cutoff;
+}
+/** 宽松比较 SDK 版本号（按点分数字）。缺省或无法解析视为不满足。 */
+export function sdkAtLeast(sdk, min) {
+    if (!sdk)
+        return false;
+    const parse = (s) => s
+        .replace(/^v/i, '')
+        .split(/[^0-9]+/)
+        .filter(Boolean)
+        .map((n) => Number.parseInt(n, 10));
+    const a = parse(sdk);
+    const b = parse(min);
+    if (!a.length || a.some((n) => Number.isNaN(n)))
+        return false;
+    for (let i = 0; i < Math.max(a.length, b.length); i++) {
+        const x = a[i] ?? 0;
+        const y = b[i] ?? 0;
+        if (x > y)
+            return true;
+        if (x < y)
+            return false;
+    }
+    return true;
+}
+export function requireReportKey(args) {
+    const dataKey = typeof args['dataKey'] === 'string' && args['dataKey'] ? args['dataKey'] : undefined;
+    const recordId = args['recordId'] !== undefined && args['recordId'] !== null && args['recordId'] !== ''
+        ? String(args['recordId'])
+        : undefined;
+    if (!dataKey && !recordId)
+        throw new Error('必须提供 dataKey 或 recordId');
+    return { dataKey, recordId };
+}
+export function topNOf(args, fallback = 20) {
+    const n = typeof args['topN'] === 'number' ? args['topN'] : fallback;
+    if (!Number.isFinite(n) || n < 1)
+        return fallback;
+    return Math.min(Math.floor(n), 200);
+}

package/dist/composite/index.d.ts

@@ -0,0 +1,25 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { Engine } from '../spec.js';
+import { type NameCase } from '../tools.js';
+import type { UwaClient } from '../client.js';
+import type { CompositeTool } from './types.js';
+/** 全部手写复合工具（不进 uwa-openapi.json）。 */
+export declare const COMPOSITE_TOOLS: readonly CompositeTool[];
+export declare const COMPOSITE_DEFAULT_IDS: readonly string[];
+export interface SelectCompositeOptions {
+    tools?: string[];
+    engine?: Engine | 'all';
+}
+/**
+ * 与原子工具同一套 --tool / --engine 过滤语义。
+ * 未指定 --tool 时视为 preset.default（复合工具若声明了该键则选中）。
+ */
+export declare function selectCompositeTools(opts: SelectCompositeOptions): CompositeTool[];
+export declare function registerCompositeTools(server: McpServer, client: UwaClient, opts: {
+    tools: string[];
+    engine: Engine | 'all';
+    nameCase: NameCase;
+    namePrefix: string;
+    maxChars: number;
+}): number;
+export declare function compositeFilterKeys(): string[];

package/dist/composite/index.js

@@ -0,0 +1,46 @@
+import { toolName } from '../tools.js';
+import { topResourcesTool } from './top-resources.js';
+import { topFunctionsTool } from './top-functions.js';
+import { reportDiagnosisTool } from './report-diagnosis.js';
+/** 全部手写复合工具（不进 uwa-openapi.json）。 */
+export const COMPOSITE_TOOLS = [
+    topResourcesTool,
+    topFunctionsTool,
+    reportDiagnosisTool,
+];
+export const COMPOSITE_DEFAULT_IDS = COMPOSITE_TOOLS.map((t) => t.id);
+/**
+ * 与原子工具同一套 --tool / --engine 过滤语义。
+ * 未指定 --tool 时视为 preset.default（复合工具若声明了该键则选中）。
+ */
+export function selectCompositeTools(opts) {
+    const wanted = new Set((opts.tools?.length ? opts.tools : ['preset.default']).map((t) => t.trim()).filter(Boolean));
+    const engine = opts.engine ?? 'all';
+    return COMPOSITE_TOOLS.filter((t) => {
+        if (engine !== 'all' && !t.engines.includes(engine))
+            return false;
+        const keys = new Set([t.id, 'preset.all', 'all', 'composite', ...t.filterKeys]);
+        return [...keys].some((k) => wanted.has(k));
+    });
+}
+export function registerCompositeTools(server, client, opts) {
+    const selected = selectCompositeTools({ tools: opts.tools, engine: opts.engine });
+    const ctx = {
+        client,
+        maxChars: opts.maxChars,
+        nameCase: opts.nameCase,
+        namePrefix: opts.namePrefix,
+        engine: opts.engine,
+    };
+    for (const tool of selected) {
+        server.registerTool(toolName(tool.id, opts.nameCase, opts.namePrefix), {
+            title: tool.title,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+        }, (async (args) => tool.handler(args ?? {}, ctx)));
+    }
+    return selected.length;
+}
+export function compositeFilterKeys() {
+    return [...new Set(COMPOSITE_TOOLS.flatMap((t) => [t.id, 'composite', ...t.filterKeys]))].sort();
+}

package/dist/composite/name-pattern.d.ts

@@ -0,0 +1,8 @@
+/** 按函数名过滤（子串或 /regex/flags），供 top_functions 本地过滤 idmap 结果。 */
+export declare function matchesNamePattern(name: string, pattern?: unknown): boolean;
+export declare function filterRowsByNamePattern<T extends {
+    name: string;
+}>(rows: T[], pattern: unknown): {
+    rows: T[];
+    matchedTotal: number;
+};

package/dist/composite/name-pattern.js

@@ -0,0 +1,25 @@
+/** 按函数名过滤（子串或 /regex/flags），供 top_functions 本地过滤 idmap 结果。 */
+export function matchesNamePattern(name, pattern) {
+    if (pattern == null || (typeof pattern === 'string' && !pattern.trim()))
+        return true;
+    const p = String(pattern).trim();
+    if (p.length >= 2 && p.startsWith('/') && p.lastIndexOf('/') > 0) {
+        const last = p.lastIndexOf('/');
+        const body = p.slice(1, last);
+        const flags = p.slice(last + 1);
+        try {
+            return new RegExp(body, flags).test(name);
+        }
+        catch {
+            return name.toLowerCase().includes(p.toLowerCase());
+        }
+    }
+    return name.toLowerCase().includes(p.toLowerCase());
+}
+export function filterRowsByNamePattern(rows, pattern) {
+    if (pattern == null || (typeof pattern === 'string' && !pattern.trim())) {
+        return { rows, matchedTotal: rows.length };
+    }
+    const matched = rows.filter((r) => matchesNamePattern(r.name, pattern));
+    return { rows: matched, matchedTotal: matched.length };
+}

package/dist/composite/overview-view.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Overview 统计 v1 / v2 / UE 2.0 返回结构差异很大：
+ * - Unity v1：对象形 brief { fps_mean: [49] } + asset_stats
+ * - UE 2.0：数组形 brief [{ label, value }] + Resource 段
+ * - Unity v2（POST）：categories[] + basicInfo{}
+ * 这里统一抽成复合工具能用的扁平视图。
+ */
+export interface OverviewView {
+    /** 简报指标 key → 单值 */
+    brief: Record<string, unknown>;
+    /** 报告基本信息 label/key → 单值 */
+    summary: Record<string, unknown>;
+    /** 函数/卡顿相关条目 */
+    functions: {
+        name: string;
+        value: number;
+        unit?: string;
+        source: string;
+        label?: string;
+    }[];
+    /** 内存/资源相关条目（类型级） */
+    memory: {
+        name: string;
+        assetType: string;
+        memoryBytes: number;
+        _source: string;
+    }[];
+    /** 是否开启资源采集；无法判定时为 null */
+    hasResource: boolean | null;
+    shape: 'v1' | 'v2' | 'ue-v2' | 'unknown';
+}
+/** 把 unwrap 后的报告或原始 data 统一成 OverviewView。 */
+export declare function viewOverview(data: unknown): OverviewView;