@uwa4d/openapi-mcp 0.2.0-beta.11 → 0.2.0-beta.13

package/dist/cli.js

@@ -6,7 +6,7 @@ import { compositeFilterKeys, selectCompositeTools, COMPOSITE_TOOLS } from './co
 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';
+import { checkForUpdate, describeReleaseChannel, formatUpdateNotice } 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) {
@@ -134,14 +134,14 @@ program
         console.log('\n凭证有效，接口连通。');
         if (typeof total === 'number')
             console.log(`最近 7 天有 ${total} 份报告。`);
-        console.log(`\nMCP 包版本：${PACKAGE_VERSION}（${resolveUpdateChannel(PACKAGE_VERSION)} 通道）`);
+        console.log(`\nMCP 包版本：${PACKAGE_VERSION}（${describeReleaseChannel(PACKAGE_VERSION).releaseLabel}）`);
         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('已是最新同 release 线版本（或暂时无法连接 npm registry）。');
             }
         }
         console.log('\n可以按 README 配置 MCP 客户端了。');

package/dist/composite/index.js

@@ -2,8 +2,10 @@ import { toolName } from '../tools.js';
 import { topResourcesTool } from './top-resources.js';
 import { topFunctionsTool } from './top-functions.js';
 import { reportDiagnosisTool } from './report-diagnosis.js';
+import { mcpVersionTool } from './mcp-version.js';
 /** 全部手写复合工具（不进 uwa-openapi.json）。 */
 export const COMPOSITE_TOOLS = [
+    mcpVersionTool,
     topResourcesTool,
     topFunctionsTool,
     reportDiagnosisTool,

package/dist/composite/mcp-version.d.ts

@@ -0,0 +1,2 @@
+import type { CompositeTool } from './types.js';
+export declare const mcpVersionTool: CompositeTool;

package/dist/composite/mcp-version.js

@@ -0,0 +1,46 @@
+import { PACKAGE_VERSION } from '../package-version.js';
+import { buildMcpVersionInfo, describeReleaseChannel } from '../version-check.js';
+import { errorResult, jsonToolResult } from './helpers.js';
+const release = describeReleaseChannel(PACKAGE_VERSION);
+const STABLE_DESCRIPTION = [
+    '查询当前 UWA OpenAPI MCP 正式版版本，并与 npm 最新稳定版对比（仅正式版↔正式版，不与内部测试版交叉）。',
+    '适用：Unity / UE｜复合工具｜无需 dataKey',
+    '若 updateAvailable=true，请用 userNotice 主动转告客户重启 MCP 升级。',
+    '用户问「MCP 什么版本」「有没有新版本」时优先调用本工具，不要臆测版本号。',
+].join('\n');
+const INTERNAL_DESCRIPTION = [
+    '查询当前 UWA OpenAPI MCP 内部测试版版本，并与 npm @beta 最新测试版对比（仅测试↔测试，不与正式版交叉）。',
+    '适用：Unity / UE｜复合工具｜无需 dataKey｜仅 UWA 内部 sandbox 联调',
+    '若 updateAvailable=true，请用 userNotice 主动转告测试人员重启 MCP 升级。',
+    '用户问「MCP 什么版本」「有没有新版本」时优先调用本工具，不要臆测版本号。',
+].join('\n');
+export const mcpVersionTool = {
+    id: 'uwa_mcp_version',
+    title: release.releaseLine === 'stable' ? 'MCP 正式版与升级提示' : 'MCP 内部测试版与升级提示',
+    engines: ['unity', 'unreal'],
+    filterKeys: ['uwa_mcp_version', 'composite', 'preset.default', 'common'],
+    description: release.releaseLine === 'stable' ? STABLE_DESCRIPTION : INTERNAL_DESCRIPTION,
+    inputSchema: {},
+    async handler(_args, ctx) {
+        try {
+            if (process.env['UWA_MCP_SKIP_UPDATE_CHECK'] === '1') {
+                return jsonToolResult({
+                    package: '@uwa4d/openapi-mcp',
+                    currentVersion: PACKAGE_VERSION,
+                    releaseLine: release.releaseLine,
+                    releaseLabel: release.releaseLabel,
+                    updateCheckSkipped: true,
+                    userNotice: `当前 MCP ${release.releaseLabel} ${PACKAGE_VERSION}（已设置 UWA_MCP_SKIP_UPDATE_CHECK，未核对 npm 最新版）。`,
+                }, ctx.maxChars);
+            }
+            const info = await buildMcpVersionInfo(PACKAGE_VERSION);
+            return jsonToolResult({
+                ...info,
+                suggestTellUser: info.updateAvailable,
+            }, ctx.maxChars);
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    },
+};

package/dist/package-version.d.ts

@@ -0,0 +1,2 @@
+/** 与 package.json 同步，避免 MCP 握手版本和 npm 包不一致。 */
+export declare const PACKAGE_VERSION: string;

package/dist/package-version.js

@@ -0,0 +1,15 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+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();

package/dist/presets.js

@@ -31,6 +31,7 @@ export const PRESET_DEFAULT = [
     'gotonline_overview_stack_stutter_scene_tree_presign',
     'gotonline_overview_stack_tree_frame_presign',
     // 复合工具（手写，见 src/composite/）
+    'uwa_mcp_version',
     'top_resources',
     'top_functions',
     'report_diagnosis',

package/dist/server-instructions.js

@@ -12,6 +12,7 @@ export const SERVER_INSTRUCTIONS = [
     '5. 非法面板名要纠正（fps_mean→fps_avg；android_pss_max→android_memory_pss@max）；数值带单位。PSS 优先读 pss_peak_kb/mb/frame。',
     '6. 接口失败时说明原因：运行日志 80108 — Unity 无 LG file_meta 表示未解析、无可用日志；UE 无 meta 只能说「暂不支持获取当前报告的运行日志」（方案切换过），勿断定报告本身无日志。其它失败勿把瞬时错误说成「一定没有数据」。',
     '7. 接口限流 31004（API_RATE_LIMIT）：UWA 服务端保护，预期行为，不是 Bug。稍等重试或减少并行/批量（如 top_resources 缩小 assetTypes）。若返回含 _partialErrors 且 _rateLimitHint，部分类型限流时已有 Top 仍可用，需说明可能不完整，勿当成报告无资源。',
+    '8. MCP 版本：用户问版本或升级时调用 uwa_mcp_version（正式版只对比正式版最新稳定版，内部测试版只对比测试版，互不交叉）。若 instructions 含「MCP 正式版/内部测试版有新版本」，必须用 userNotice 主动转告并说明重启 MCP 升级。',
     '',
     '体检优先调用 report_diagnosis；细节再按 _apisUsed 深挖。对比多份报告时说明场景/时长/目标帧是否可比（见 comparability_note）。',
 ].join('\n');

package/dist/server.d.ts

@@ -16,9 +16,10 @@ export interface ServerOptions {
     maxChars: number;
     timeoutMs: number;
     specPath?: string;
+    /** 覆盖默认 server instructions（用于启动时注入版本升级提醒）。 */
+    instructions?: string;
 }
-/** 与 package.json 同步，避免 MCP 握手版本和 npm 包不一致。 */
-export declare const PACKAGE_VERSION: string;
+export { PACKAGE_VERSION } from './package-version.js';
 export declare function createServer(opts: ServerOptions): {
     server: McpServer;
     toolCount: number;

package/dist/server.js

@@ -1,6 +1,3 @@
-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';
@@ -9,19 +6,9 @@ import { selectOperations } from './presets.js';
 import { loadSpec } from './spec.js';
 import { makeHandler, toolConfig, toolName } from './tools.js';
 import { SERVER_INSTRUCTIONS } from './server-instructions.js';
-import { scheduleUpdateNotice } from './version-check.js';
-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();
+import { PACKAGE_VERSION } from './package-version.js';
+import { buildMcpVersionInfo, buildUpdateInstructionAppendix, scheduleUpdateNotice, } from './version-check.js';
+export { PACKAGE_VERSION } from './package-version.js';
 export function createServer(opts) {
     const spec = loadSpec(opts.specPath);
     const operations = selectOperations(spec.operations, { tools: opts.tools, engine: opts.engine });
@@ -30,7 +17,7 @@ export function createServer(opts) {
         credentials: { appId: opts.appId, appSecret: opts.appSecret },
         timeoutMs: opts.timeoutMs,
     });
-    const server = new McpServer({ name: 'uwa-openapi-mcp', version: PACKAGE_VERSION }, { instructions: SERVER_INSTRUCTIONS });
+    const server = new McpServer({ name: 'uwa-openapi-mcp', version: PACKAGE_VERSION }, { instructions: opts.instructions ?? SERVER_INSTRUCTIONS });
     for (const op of operations) {
         server.registerTool(toolName(op.id, opts.nameCase, opts.namePrefix), toolConfig(op), makeHandler(op, client, opts.maxRows, opts.maxChars));
     }
@@ -46,7 +33,22 @@ export function createServer(opts) {
     return { server, toolCount, total, atomicCount: operations.length, compositeCount };
 }
 export async function startStdio(opts) {
-    const { server, toolCount, total, atomicCount, compositeCount } = createServer(opts);
+    let instructions = SERVER_INSTRUCTIONS;
+    if (process.env['UWA_MCP_SKIP_UPDATE_CHECK'] !== '1') {
+        try {
+            const info = await buildMcpVersionInfo(PACKAGE_VERSION);
+            const appendix = buildUpdateInstructionAppendix(info);
+            if (appendix)
+                instructions = `${SERVER_INSTRUCTIONS}\n\n${appendix}`;
+        }
+        catch {
+            /* 版本检查失败不阻塞启动 */
+        }
+    }
+    const { server, toolCount, total, atomicCount, compositeCount } = createServer({
+        ...opts,
+        instructions,
+    });
     // stdout 是 MCP 协议通道，任何日志都必须走 stderr
     console.error(`[uwa-openapi-mcp] v${PACKAGE_VERSION} 已加载 ${toolCount}/${total} 个工具（原子 ${atomicCount} + 复合 ${compositeCount}），接口地址 ${opts.baseUrl}`);
     scheduleUpdateNotice(PACKAGE_VERSION);

package/dist/version-check.d.ts

@@ -3,12 +3,39 @@ export declare const PACKAGE_NAME = "@uwa4d/openapi-mcp";
 export interface UpdateCheckResult {
     current: string;
     latest: string;
-    channel: 'beta' | 'latest';
+    /** npm dist-tag，仅作逻辑区分 */
+    registryTag: 'beta' | 'latest';
 }
-/** 当前运行版本应跟哪个 dist-tag 比对新版。 */
+/** uwa_mcp_version 工具与启动 instructions 用的结构化版本信息。 */
+export interface McpVersionInfo {
+    package: string;
+    currentVersion: string;
+    /** stable=正式版（客户） / internal=内部测试版；与 npm dist-tag 一一对应，互不交叉比对 */
+    releaseLine: 'stable' | 'internal';
+    /** 对用户/模型可见的通道名，正式版不说 beta */
+    releaseLabel: string;
+    latestOnChannel: string | null;
+    registryReachable: boolean;
+    updateAvailable: boolean;
+    userNotice: string;
+    upgradeHint: string;
+}
+export interface ReleaseChannelPresentation {
+    registryTag: 'beta' | 'latest';
+    releaseLine: 'stable' | 'internal';
+    releaseLabel: string;
+    packageInstallRef: string;
+}
+/** 当前运行版本应跟哪个 npm dist-tag 比对新版（正式↔latest，测试↔beta，不交叉）。 */
 export declare function resolveUpdateChannel(version: string): 'beta' | 'latest';
+/** 正式版与内部测试版的分发呈现（客户侧不出现 beta 字样）。 */
+export declare function describeReleaseChannel(version: string): ReleaseChannelPresentation;
 /** 查询 registry 是否有比 current 更新的同通道版本；失败时返回 null。 */
 export declare function checkForUpdate(current: string): Promise<UpdateCheckResult | null>;
+/** 拉取完整版本信息（工具返回 + 启动 instructions）。 */
+export declare function buildMcpVersionInfo(current: string): Promise<McpVersionInfo>;
+/** 有新版本时追加到 server instructions，让模型在对话里主动提醒用户。 */
+export declare function buildUpdateInstructionAppendix(info: McpVersionInfo): string | null;
 export declare function formatUpdateNotice(result: UpdateCheckResult): string;
 /** 启动时异步检查；仅写 stderr，不阻塞 MCP 握手。 */
 export declare function scheduleUpdateNotice(current: string): void;

package/dist/version-check.js

@@ -2,10 +2,28 @@
 export const PACKAGE_NAME = '@uwa4d/openapi-mcp';
 const REGISTRY_URL = 'https://registry.npmjs.org/@uwa4d%2Fopenapi-mcp';
 const CHECK_TIMEOUT_MS = 8_000;
-/** 当前运行版本应跟哪个 dist-tag 比对新版。 */
+/** 当前运行版本应跟哪个 npm dist-tag 比对新版（正式↔latest，测试↔beta，不交叉）。 */
 export function resolveUpdateChannel(version) {
     return version.includes('-') ? 'beta' : 'latest';
 }
+/** 正式版与内部测试版的分发呈现（客户侧不出现 beta 字样）。 */
+export function describeReleaseChannel(version) {
+    const registryTag = resolveUpdateChannel(version);
+    if (registryTag === 'beta') {
+        return {
+            registryTag: 'beta',
+            releaseLine: 'internal',
+            releaseLabel: '内部测试版',
+            packageInstallRef: `${PACKAGE_NAME}@beta`,
+        };
+    }
+    return {
+        registryTag: 'latest',
+        releaseLine: 'stable',
+        releaseLabel: '正式版',
+        packageInstallRef: PACKAGE_NAME,
+    };
+}
 /** 简易 semver 比较：a > b 返回 1，相等 0，a < b 返回 -1。 */
 function compareVersions(a, b) {
     if (a === b)
@@ -71,17 +89,66 @@ async function fetchDistTagVersion(channel) {
 }
 /** 查询 registry 是否有比 current 更新的同通道版本；失败时返回 null。 */
 export async function checkForUpdate(current) {
-    const channel = resolveUpdateChannel(current);
-    const latest = await fetchDistTagVersion(channel);
-    if (!latest || compareVersions(latest, current) <= 0)
+    const info = await buildMcpVersionInfo(current);
+    if (!info.updateAvailable || !info.latestOnChannel)
+        return null;
+    return { current: info.currentVersion, latest: info.latestOnChannel, registryTag: describeReleaseChannel(current).registryTag };
+}
+function buildUpgradeHint(presentation) {
+    return (`若 MCP 配置未锁定具体版本号，请在您使用的 AI 客户端中重启 MCP 服务以升级（重载 MCP 配置或重启客户端均可）；` +
+        `终端核对：npx --yes --prefer-online ${presentation.packageInstallRef} --version`);
+}
+/** 拉取完整版本信息（工具返回 + 启动 instructions）。 */
+export async function buildMcpVersionInfo(current) {
+    const presentation = describeReleaseChannel(current);
+    const latestOnChannel = await fetchDistTagVersion(presentation.registryTag);
+    const registryReachable = latestOnChannel !== null;
+    const updateAvailable = registryReachable && latestOnChannel !== null && compareVersions(latestOnChannel, current) > 0;
+    const upgradeHint = buildUpgradeHint(presentation);
+    if (updateAvailable && latestOnChannel) {
+        return {
+            package: PACKAGE_NAME,
+            currentVersion: current,
+            releaseLine: presentation.releaseLine,
+            releaseLabel: presentation.releaseLabel,
+            latestOnChannel,
+            registryReachable,
+            updateAvailable: true,
+            userNotice: `UWA OpenAPI MCP（${presentation.releaseLabel}）有新版本：当前 ${current}，${presentation.releaseLabel}最新 ${latestOnChannel}。` +
+                upgradeHint,
+            upgradeHint,
+        };
+    }
+    const latestLabel = latestOnChannel ?? '(暂时无法连接 npm 核对最新版)';
+    return {
+        package: PACKAGE_NAME,
+        currentVersion: current,
+        releaseLine: presentation.releaseLine,
+        releaseLabel: presentation.releaseLabel,
+        latestOnChannel,
+        registryReachable,
+        updateAvailable: false,
+        userNotice: registryReachable
+            ? `UWA OpenAPI MCP（${presentation.releaseLabel}）已是最新：当前 ${current}，${presentation.releaseLabel}最新 ${latestLabel}。`
+            : `UWA OpenAPI MCP（${presentation.releaseLabel}）当前版本 ${current}；暂时无法连接 npm 核对最新版。`,
+        upgradeHint,
+    };
+}
+/** 有新版本时追加到 server instructions，让模型在对话里主动提醒用户。 */
+export function buildUpdateInstructionAppendix(info) {
+    if (!info.updateAvailable || !info.latestOnChannel)
         return null;
-    return { current, latest, channel };
+    const headline = info.releaseLine === 'stable'
+        ? '【MCP 正式版有新版本 — 请主动告知用户】'
+        : '【MCP 内部测试版有新版本 — 请主动告知内部测试人员】';
+    return (`${headline}当前运行 ${info.currentVersion}，${info.releaseLabel}最新 ${info.latestOnChannel}。` +
+        `请用自然语言转告用户重启 MCP 升级（勿只写 stderr 日志）。详情可调工具 uwa_mcp_version。` +
+        ` ${info.upgradeHint}`);
 }
 export function formatUpdateNotice(result) {
-    const pkgRef = result.channel === 'beta' ? `${PACKAGE_NAME}@beta` : PACKAGE_NAME;
-    return (`[uwa-openapi-mcp] 有新版本 ${result.latest}（当前 ${result.current}，通道 ${result.channel}）。` +
-        `若 MCP 配置未锁定具体版本号，请在您使用的 AI 客户端中重启 MCP 服务以升级（重载 MCP 配置或重启客户端均可）；` +
-        `也可在终端核对：npx --yes --prefer-online ${pkgRef} --version`);
+    const presentation = describeReleaseChannel(result.current);
+    return (`[uwa-openapi-mcp] ${presentation.releaseLabel}有新版本 ${result.latest}（当前 ${result.current}）。` +
+        buildUpgradeHint(presentation));
 }
 /** 启动时异步检查；仅写 stderr，不阻塞 MCP 握手。 */
 export function scheduleUpdateNotice(current) {

package/package.json

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