@uwa4d/openapi-mcp 0.2.0-beta.9 → 0.2.1-beta.0

package/dist/cli.js

@@ -6,6 +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, 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) {
@@ -133,6 +134,16 @@ program
         console.log('\n凭证有效，接口连通。');
         if (typeof total === 'number')
             console.log(`最近 7 天有 ${total} 份报告。`);
+        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('已是最新同 release 线版本（或暂时无法连接 npm registry）。');
+            }
+        }
         console.log('\n可以按 README 配置 MCP 客户端了。');
     }
     catch (err) {

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,48 @@
+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',
+    '触发：本对话第一次使用任意 UWA MCP 工具前应先调一次；用户问版本/升级时也可调。同一对话勿重复。',
+    '若 updateAvailable=true / suggestTellUser=true，请用 userNotice 主动转告客户重启 MCP 升级；已是最新勿打扰。',
+    '不要臆测版本号。',
+].join('\n');
+const INTERNAL_DESCRIPTION = [
+    '查询当前 UWA OpenAPI MCP 内部测试版版本，并与 npm @beta 最新测试版对比（仅测试↔测试，不与正式版交叉）。',
+    '适用：Unity / UE｜复合工具｜无需 dataKey｜仅 UWA 内部 sandbox 联调',
+    '触发：本对话第一次使用任意 UWA MCP 工具前应先调一次；用户问版本/升级时也可调。同一对话勿重复。',
+    '若 updateAvailable=true / suggestTellUser=true，请用 userNotice 主动转告测试人员重启 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/composite/top-resources.js

@@ -1,3 +1,4 @@
+import { withRateLimitAnnotation } from '../error-hints.js';
 import { z } from './types.js';
 import { errorResult, isObj, jsonToolResult, requireReportKey, topNOf, } from './helpers.js';
 import { fetchOverviewStatistic, fetchReportIdentity, preferAtResourceTable, } from './route-overview.js';
@@ -193,26 +194,24 @@ export async function runTopResources(client, args) {
     apisUsed.push(...fetched.apisUsed);
     if (fetched.items.length === 0) {
         const fallbackItems = typeLevelFromOverview(view);
-        return packResult(fallbackItems, {
+        return packResult(fallbackItems, withRateLimitAnnotation({
             _sourceKind: fetched.sourceKind,
             _apisUsed: apisUsed,
-            ...(fetched.errors.length ? { _partialErrors: fetched.errors } : {}),
             _note: fallbackItems.length > 0
                 ? '逐资源列表为空，已回退为 Overview 类型级峰值。'
                 : '逐资源列表与类型级峰值均为空（报告可能未采集资源内存）。',
             _limitations: ['per_asset_empty'],
-        });
+        }, fetched.errors.length ? fetched.errors : undefined));
     }
     const note = groupBy === 'assetType'
         ? `已按类型各取 Top ${topN}（${fetched.sourceKind}，共 ${assetTypes.length} 种）。`
         : `已按内存峰值合并 ${assetTypes.length} 种资源类型（${fetched.sourceKind}），返回全局 Top ${topN}。`;
-    return packResult(fetched.items, {
+    return packResult(fetched.items, withRateLimitAnnotation({
         totalCandidates: fetched.items.length,
         _sourceKind: fetched.sourceKind,
         _apisUsed: apisUsed,
-        ...(fetched.errors.length ? { _partialErrors: fetched.errors } : {}),
         _note: note,
-    });
+    }, fetched.errors.length ? fetched.errors : undefined));
 }
 function normalizeAssetTypes(raw) {
     if (Array.isArray(raw) && raw.length)
@@ -236,6 +235,7 @@ export const topResourcesTool = {
         'Unity / UE 均优先走 AT 资源总览预签名（at/resource/overall/table/presign），按 assetType 并行下载后合并排序。',
         'groupBy=merged（默认）：跨类型合并后取全局 Top N；groupBy=assetType：每种类型各取 Top N，返回 byType。',
         'Unity 旧报告（解析日 < 2026-06-25）回退 memory/manage；拉不到逐资源时再回退 Overview 类型级峰值。',
+        '内部按 assetType 并行请求，易触发 OpenAPI 限流 31004（UWA 服务端保护，预期行为）。遇限流见 _rateLimitHint：可缩小 assetTypes、稍等重试；部分类型限流时已有 Top 仍可用。',
         '不确定报告版本时直接用本工具；需要原始全量列表时再调对应原子工具。',
     ].join('\n'),
     inputSchema: {

package/dist/error-hints.d.ts

@@ -9,5 +9,15 @@ export declare const FILE_META_REASONS: {
     readonly AT_META_TYPE_INVALID: "AT_META_TYPE_INVALID";
     readonly AT_META_PATH_MISSING: "AT_META_PATH_MISSING";
 };
+/** OpenAPI 接口限流（UWA 服务端保护，预期行为）。 */
+export declare const RATE_LIMIT_ERROR_CODE = 31004;
+/** 复合工具 _partialErrors 含限流时附加的说明（与 resolveErrorHint(31004) 语义一致）。 */
+export declare const RATE_LIMIT_HINT: string;
+/** 错误文案是否含 31004 / API_RATE_LIMIT。 */
+export declare function isRateLimitMessage(text: string): boolean;
+/** _partialErrors 中是否有限流项。 */
+export declare function hasRateLimitInPartialErrors(errors: string[]): boolean;
+/** 附带 _partialErrors；若含限流则加 _rateLimitHint。 */
+export declare function withRateLimitAnnotation(extra: Record<string, unknown>, partialErrors?: string[]): Record<string, unknown>;
 /** 组装给模型看的排查建议；优先 rawMessage 原因码 + OpenAPI message。 */
 export declare function resolveErrorHint(code: number, rawMessage: string, apiMessage: string): string | undefined;

package/dist/error-hints.js

@@ -9,6 +9,11 @@ export const FILE_META_REASONS = {
     AT_META_TYPE_INVALID: 'AT_META_TYPE_INVALID',
     AT_META_PATH_MISSING: 'AT_META_PATH_MISSING',
 };
+/** OpenAPI 接口限流（UWA 服务端保护，预期行为）。 */
+export const RATE_LIMIT_ERROR_CODE = 31004;
+/** 复合工具 _partialErrors 含限流时附加的说明（与 resolveErrorHint(31004) 语义一致）。 */
+export const RATE_LIMIT_HINT = 'OpenAPI 限流（31004）是 UWA 服务端保护，不是报告无数据或接口故障。可稍等重试、减少并发或缩小 assetTypes；' +
+    '若 _partialErrors 仅部分类型限流，已有 Top 仍可用，需说明可能不完整。';
 const ERROR_HINTS_BY_CODE = {
     20001: '业务参数不合法，核对参数名、取值范围和必填项（注意批量接口的参数名多为复数，如 dataKeys）',
     23508: '数据服务错误，常见原因是报告不适用该接口版本（如新报告调用了 1.0 接口，或旧报告调用了 2.0 接口），改用对应版本重试',
@@ -18,6 +23,8 @@ const ERROR_HINTS_BY_CODE = {
     24056: '签名错误，检查 appSecret 是否正确',
     24057: '时间戳过期，本机时间与服务端偏差不能超过 20 分钟',
     30001: '服务端错误，常见原因是用错了引擎对应的接口（如对 UE 报告调用了 Unity 专用接口）；勿把瞬时失败说成「一定没有数据」',
+    31004: 'OpenAPI 接口限流（UWA 服务端保护，预期行为）。稍等重试，或减少并行请求/缩小查询范围（如 top_resources 的 assetTypes）；' +
+        '勿当成报告无数据或接口永久故障。',
 };
 /** OpenAPI 已按引擎写好的稳定文案（优先沿用，再补 AI 纪律）。 */
 function hintForOpenApiRuntimeLogMessage(apiMessage) {
@@ -45,6 +52,24 @@ function hintForFileMetaReason(rawMessage, apiMessage) {
     }
     return null;
 }
+/** 错误文案是否含 31004 / API_RATE_LIMIT。 */
+export function isRateLimitMessage(text) {
+    return text.includes(`[${RATE_LIMIT_ERROR_CODE}]`) || text.includes('API_RATE_LIMIT') || text.includes('接口限流');
+}
+/** _partialErrors 中是否有限流项。 */
+export function hasRateLimitInPartialErrors(errors) {
+    return errors.some(isRateLimitMessage);
+}
+/** 附带 _partialErrors；若含限流则加 _rateLimitHint。 */
+export function withRateLimitAnnotation(extra, partialErrors) {
+    if (!partialErrors?.length)
+        return extra;
+    const out = { ...extra, _partialErrors: partialErrors };
+    if (hasRateLimitInPartialErrors(partialErrors)) {
+        out._rateLimitHint = RATE_LIMIT_HINT;
+    }
+    return out;
+}
 /** 组装给模型看的排查建议；优先 rawMessage 原因码 + OpenAPI message。 */
 export function resolveErrorHint(code, rawMessage, apiMessage) {
     if (code === 80108) {

package/dist/eureka.d.ts

@@ -0,0 +1,15 @@
+/** 与网关 `lb://uwa-openapi-mcp`、Eureka vipAddress 对齐。 */
+export declare const EUREKA_APP_NAME = "uwa-openapi-mcp";
+export interface EurekaOptions {
+    /** 如 http://user:pass@host:8761/eureka/ */
+    zone: string;
+    ip: string;
+    port: number;
+    hostname?: string;
+}
+export declare function resolveAdvertiseIp(explicit?: string): string;
+/**
+ * 注册到 Eureka，并维持心跳。返回的 stop 会下线实例。
+ * 注册失败会后台重试，不打断 HTTP 服务。
+ */
+export declare function startEurekaRegistration(opts: EurekaOptions): () => Promise<void>;

package/dist/eureka.js

@@ -0,0 +1,142 @@
+import { networkInterfaces } from 'node:os';
+/** 与网关 `lb://uwa-openapi-mcp`、Eureka vipAddress 对齐。 */
+export const EUREKA_APP_NAME = 'uwa-openapi-mcp';
+function normalizeZone(zone) {
+    return zone.endsWith('/') ? zone : `${zone}/`;
+}
+function firstNonInternalIpv4() {
+    for (const addrs of Object.values(networkInterfaces())) {
+        for (const addr of addrs ?? []) {
+            const family = String(addr.family);
+            if ((family === 'IPv4' || family === '4') && !addr.internal)
+                return addr.address;
+        }
+    }
+    return undefined;
+}
+export function resolveAdvertiseIp(explicit) {
+    const ip = explicit?.trim() || process.env['EUREKA_INSTANCE_IP']?.trim() || firstNonInternalIpv4();
+    if (!ip) {
+        throw new Error('无法探测注册 IP。请设置环境变量 EUREKA_INSTANCE_IP（网关要能访问到的地址，不要用 127.0.0.1）。');
+    }
+    if (ip === '127.0.0.1' || ip === '::1') {
+        throw new Error(`Eureka 不能注册 ${ip}，网关在别的进程里连不上。请设置 EUREKA_INSTANCE_IP 为测试机内网 IP。`);
+    }
+    return ip;
+}
+function instancePayload(opts, instanceId) {
+    const host = opts.hostname ?? opts.ip;
+    const base = `http://${opts.ip}:${opts.port}`;
+    const now = Date.now();
+    return {
+        instance: {
+            instanceId,
+            hostName: host,
+            app: EUREKA_APP_NAME.toUpperCase(),
+            ipAddr: opts.ip,
+            status: 'UP',
+            port: { $: opts.port, '@enabled': true },
+            securePort: { $: 443, '@enabled': false },
+            countryId: 1,
+            dataCenterInfo: {
+                '@class': 'com.netflix.appinfo.InstanceInfo$DefaultDataCenterInfo',
+                name: 'MyOwn',
+            },
+            leaseInfo: {
+                renewalIntervalInSecs: 30,
+                durationInSecs: 90,
+            },
+            homePageUrl: `${base}/`,
+            statusPageUrl: `${base}/health`,
+            healthCheckUrl: `${base}/health`,
+            vipAddress: EUREKA_APP_NAME,
+            secureVipAddress: EUREKA_APP_NAME,
+            lastUpdatedTimestamp: now,
+            lastDirtyTimestamp: now,
+        },
+    };
+}
+async function eurekaFetch(url, init) {
+    return fetch(url, {
+        ...init,
+        headers: {
+            Accept: 'application/json',
+            'Content-Type': 'application/json',
+            ...(init.headers ?? {}),
+        },
+    });
+}
+/**
+ * 注册到 Eureka，并维持心跳。返回的 stop 会下线实例。
+ * 注册失败会后台重试，不打断 HTTP 服务。
+ */
+export function startEurekaRegistration(opts) {
+    const zone = normalizeZone(opts.zone);
+    const app = EUREKA_APP_NAME.toUpperCase();
+    const instanceId = `${opts.ip}:${EUREKA_APP_NAME}:${opts.port}`;
+    const registerUrl = `${zone}apps/${app}`;
+    const instanceUrl = `${zone}apps/${app}/${encodeURIComponent(instanceId)}`;
+    const body = JSON.stringify(instancePayload(opts, instanceId));
+    let stopped = false;
+    let heartbeat;
+    let retry;
+    const log = (msg, err) => {
+        const extra = err instanceof Error ? ` ${err.message}` : err ? ` ${String(err)}` : '';
+        console.error(`[uwa-openapi-mcp] Eureka ${msg}${extra}`);
+    };
+    const sendHeartbeat = async () => {
+        if (stopped)
+            return;
+        try {
+            const res = await eurekaFetch(instanceUrl, { method: 'PUT' });
+            if (res.status === 404) {
+                log('心跳 404，重新注册');
+                await register();
+                return;
+            }
+            if (!res.ok)
+                log(`心跳失败 HTTP ${res.status}`);
+        }
+        catch (err) {
+            log('心跳异常', err);
+        }
+    };
+    const register = async () => {
+        if (stopped)
+            return;
+        try {
+            const res = await eurekaFetch(registerUrl, { method: 'POST', body });
+            if (res.ok || res.status === 204) {
+                log(`已注册 ${instanceId} → ${zone}`);
+                if (!heartbeat)
+                    heartbeat = setInterval(() => void sendHeartbeat(), 30_000);
+                return;
+            }
+            const text = await res.text().catch(() => '');
+            log(`注册失败 HTTP ${res.status} ${text.slice(0, 200)}`);
+        }
+        catch (err) {
+            log('注册异常', err);
+        }
+        if (!stopped)
+            retry = setTimeout(() => void register(), 10_000);
+    };
+    void register();
+    return async () => {
+        stopped = true;
+        if (retry)
+            clearTimeout(retry);
+        if (heartbeat)
+            clearInterval(heartbeat);
+        try {
+            const res = await eurekaFetch(instanceUrl, { method: 'DELETE' });
+            if (res.ok || res.status === 404)
+                log(`已下线 ${instanceId}`);
+            else
+                log(`下线失败 HTTP ${res.status}`);
+        }
+        catch (err) {
+            log('下线异常', err);
+        }
+    };
+}

package/dist/http.d.ts

@@ -0,0 +1,21 @@
+import { type ServerOptions } from './server.js';
+export interface HttpListenOptions extends Omit<ServerOptions, 'appId' | 'appSecret'> {
+    port: number;
+    bind: string;
+    /** MCP 路径，默认 /mcp */
+    path: string;
+    /** 请求未带凭证时的兜底（CLI / 环境变量） */
+    fallbackCredentials?: {
+        appId: string;
+        appSecret: string;
+    };
+    /**
+     * true：只回 JSON，不走 SSE。
+     * 默认 false，符合 Streamable HTTP / 飞书 HTTPStreaming。
+     */
+    jsonResponse: boolean;
+    /** 设置后向 Eureka 注册，供网关 lb://uwa-openapi-mcp 发现 */
+    eurekaZone?: string;
+    eurekaIp?: string;
+}
+export declare function startHttp(opts: HttpListenOptions): Promise<void>;

package/dist/http.js

@@ -0,0 +1,203 @@
+import { createServer as createHttpServer } from 'node:http';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { startEurekaRegistration, resolveAdvertiseIp } from './eureka.js';
+import { SERVER_INSTRUCTIONS } from './server-instructions.js';
+import { PACKAGE_VERSION, createServer } from './server.js';
+import { buildMcpVersionInfo, buildUpdateInstructionAppendix, scheduleUpdateNotice } from './version-check.js';
+function header(req, name) {
+    const raw = req.headers[name.toLowerCase()];
+    if (Array.isArray(raw))
+        return raw[0];
+    return raw;
+}
+function firstQuery(url, keys) {
+    for (const key of keys) {
+        const value = url.searchParams.get(key)?.trim();
+        if (value)
+            return value;
+    }
+    return undefined;
+}
+function credentialsFromBasic(req) {
+    const auth = header(req, 'authorization');
+    if (!auth || !auth.toLowerCase().startsWith('basic '))
+        return undefined;
+    try {
+        const decoded = Buffer.from(auth.slice(6).trim(), 'base64').toString('utf8');
+        const colon = decoded.indexOf(':');
+        if (colon <= 0)
+            return undefined;
+        const appId = decoded.slice(0, colon).trim();
+        const appSecret = decoded.slice(colon + 1).trim();
+        if (!appId || !appSecret)
+            return undefined;
+        return { appId, appSecret };
+    }
+    catch {
+        return undefined;
+    }
+}
+function resolveRequestCredentials(req, url, fallback) {
+    const appId = firstQuery(url, ['appId', 'app_id']) ??
+        header(req, 'x-uwa-open-api-app-id') ??
+        fallback?.appId;
+    const appSecret = firstQuery(url, ['appSecret', 'app_secret']) ??
+        header(req, 'x-uwa-mcp-app-secret') ??
+        header(req, 'x-uwa-open-api-app-secret') ??
+        fallback?.appSecret;
+    if (appId && appSecret)
+        return { appId, appSecret };
+    return credentialsFromBasic(req);
+}
+async function readJsonBody(req) {
+    const chunks = [];
+    for await (const chunk of req) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    if (chunks.length === 0)
+        return undefined;
+    const raw = Buffer.concat(chunks).toString('utf8').trim();
+    if (!raw)
+        return undefined;
+    return JSON.parse(raw);
+}
+function sendJson(res, status, body) {
+    if (res.headersSent)
+        return;
+    const payload = JSON.stringify(body);
+    res.writeHead(status, {
+        'Content-Type': 'application/json; charset=utf-8',
+        'Content-Length': Buffer.byteLength(payload),
+    });
+    res.end(payload);
+}
+function applyCors(res) {
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', [
+        'Content-Type',
+        'Accept',
+        'Authorization',
+        'MCP-Protocol-Version',
+        'mcp-protocol-version',
+        'MCP-Session-Id',
+        'mcp-session-id',
+        'x-uwa-open-api-app-id',
+        'x-uwa-mcp-app-secret',
+        'x-uwa-open-api-app-secret',
+    ].join(', '));
+}
+function isMcpPath(pathname, mcpPath) {
+    return pathname === mcpPath || pathname === `${mcpPath}/`;
+}
+async function handleMcp(req, res, url, opts, instructions) {
+    const creds = resolveRequestCredentials(req, url, opts.fallbackCredentials);
+    if (!creds) {
+        sendJson(res, 401, {
+            error: '缺少凭证',
+            hint: '在 URL 上带 appId、appSecret，或设置 Header x-uwa-open-api-app-id / x-uwa-mcp-app-secret',
+        });
+        return;
+    }
+    let parsedBody;
+    if (req.method === 'POST') {
+        try {
+            parsedBody = await readJsonBody(req);
+        }
+        catch {
+            sendJson(res, 400, { error: '请求体不是合法 JSON' });
+            return;
+        }
+    }
+    const { server } = createServer({
+        ...opts,
+        appId: creds.appId,
+        appSecret: creds.appSecret,
+        instructions,
+    });
+    const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: undefined,
+        enableJsonResponse: opts.jsonResponse,
+    });
+    const shutdown = () => {
+        void transport.close();
+        void server.close();
+    };
+    res.on('close', shutdown);
+    await server.connect(transport);
+    await transport.handleRequest(req, res, parsedBody);
+}
+export async function startHttp(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 preview = createServer({
+        ...opts,
+        appId: opts.fallbackCredentials?.appId ?? 'preview',
+        appSecret: opts.fallbackCredentials?.appSecret ?? 'preview',
+        instructions,
+    });
+    await preview.server.close();
+    const httpServer = createHttpServer((req, res) => {
+        void (async () => {
+            applyCors(res);
+            const host = req.headers.host ?? 'localhost';
+            const url = new URL(req.url ?? '/', `http://${host}`);
+            if (req.method === 'OPTIONS' && isMcpPath(url.pathname, opts.path)) {
+                res.writeHead(204);
+                res.end();
+                return;
+            }
+            if (req.method === 'GET' && (url.pathname === '/health' || url.pathname === '/health/')) {
+                sendJson(res, 200, { status: 'ok', name: 'uwa-openapi-mcp', version: PACKAGE_VERSION });
+                return;
+            }
+            if (!isMcpPath(url.pathname, opts.path)) {
+                sendJson(res, 404, { error: `仅提供 ${opts.path}` });
+                return;
+            }
+            await handleMcp(req, res, url, opts, instructions);
+        })().catch((err) => {
+            console.error('[uwa-openapi-mcp] HTTP 处理失败', err);
+            sendJson(res, 500, { error: err instanceof Error ? err.message : String(err) });
+        });
+    });
+    await new Promise((resolve, reject) => {
+        httpServer.once('error', reject);
+        httpServer.listen(opts.port, opts.bind, () => resolve());
+    });
+    console.error(`[uwa-openapi-mcp] v${PACKAGE_VERSION} HTTP 已启动 ${opts.bind}:${opts.port}${opts.path}，` +
+        `已加载 ${preview.toolCount}/${preview.total} 个工具（原子 ${preview.atomicCount} + 复合 ${preview.compositeCount}），` +
+        `接口地址 ${opts.baseUrl}` +
+        (opts.jsonResponse ? '，JSON 响应' : '，Streamable HTTP'));
+    scheduleUpdateNotice(PACKAGE_VERSION);
+    let stopEureka;
+    const zone = opts.eurekaZone ?? process.env['EUREKA_DEFAULT_ZONE']?.trim();
+    if (zone) {
+        const ip = resolveAdvertiseIp(opts.eurekaIp);
+        stopEureka = startEurekaRegistration({ zone, ip, port: opts.port });
+    }
+    let shuttingDown = false;
+    const shutdown = (signal) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        console.error(`[uwa-openapi-mcp] 收到 ${signal}，准备退出`);
+        void (async () => {
+            await stopEureka?.();
+            await new Promise((resolve) => httpServer.close(() => resolve()));
+            process.exit(0);
+        })();
+    };
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
+    process.on('SIGINT', () => shutdown('SIGINT'));
+}