@uwa4d/openapi-mcp 0.1.0

package/dist/spec.d.ts

@@ -0,0 +1,51 @@
+export type Engine = 'unity' | 'unreal';
+export type HttpMethod = 'GET' | 'POST';
+export interface Param {
+    name: string;
+    type: string;
+    required: boolean;
+    example?: string;
+    description: string;
+}
+export interface Variant {
+    title: string;
+    docEngines: Engine[];
+    supportedEngines: Engine[];
+    module: string;
+    description: string;
+    apiVersions: string[];
+    sdkRequirement?: string;
+    prerequisite?: string;
+    notes: string[];
+    /** 返回结构里的语义规则（如「x_axis 优先级规则」），误读会直接导致数据解释错误。 */
+    returnRules: string[];
+    query: Param[];
+    body: Param[];
+    docLine: number;
+}
+export interface Operation {
+    id: string;
+    name: string;
+    method: HttpMethod;
+    path: string;
+    summary: string;
+    engines: Engine[];
+    modules: string[];
+    apiVersions: string[];
+    defaultApiVersion: string;
+    query: Param[];
+    body: Param[];
+    returnsPresignUrl: boolean;
+    variants: Variant[];
+}
+export interface ApiSpec {
+    generatedAt: string;
+    sourceDoc: string;
+    operationCount: number;
+    operations: Operation[];
+}
+/**
+ * spec 在包根的 spec/ 目录下，运行时读取而非编译期 import，
+ * 这样 dist 保持纯代码，更新文档只需替换 json。
+ */
+export declare function loadSpec(specPath?: string): ApiSpec;

package/dist/spec.js

@@ -0,0 +1,12 @@
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * spec 在包根的 spec/ 目录下，运行时读取而非编译期 import，
+ * 这样 dist 保持纯代码，更新文档只需替换 json。
+ */
+export function loadSpec(specPath) {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const target = specPath ?? resolve(here, '..', 'spec', 'uwa-openapi.json');
+    return JSON.parse(readFileSync(target, 'utf8'));
+}

package/dist/tools.d.ts

@@ -0,0 +1,36 @@
+import { type ZodTypeAny } from 'zod';
+import type { Operation } from './spec.js';
+import type { UwaClient } from './client.js';
+export type NameCase = 'snake' | 'camel';
+/**
+ * 预签名数据默认完整返回，不按条数截断——实测各接口解压后在 10 KB ~ 500 KB 之间，
+ * 使用者绝大多数时候要的就是全量。
+ *
+ * 只保留一道按字符数的兜底闸门，防止个别异常大的报告一次性撑爆模型上下文。
+ * 阈值取 50 万字符（约 16 万 token），高于目前观测到的最大值，正常报告不会触发。
+ */
+export declare const DEFAULT_MAX_ROWS = 0;
+export declare const DEFAULT_MAX_CHARS = 500000;
+export declare function toolName(id: string, nameCase: NameCase, prefix: string): string;
+export declare function buildInputSchema(op: Operation): Record<string, ZodTypeAny>;
+export interface ToolResult {
+    content: {
+        type: 'text';
+        text: string;
+    }[];
+    isError?: boolean;
+}
+/**
+ * 曲线类接口的返回里有两套横轴：部分曲线自带 y_axis.{指标}.x_axis（步长 30 帧），
+ * 其余用外层共享 x_axis（逐帧）。两者点数不同，混用会把数据对错帧。
+ *
+ * 光在工具描述里写规则不够可靠，这里直接为每条曲线标注它实际该用哪根横轴、
+ * 帧号范围和步长，并在点数对不上时给出警告，从结构上消除歧义。
+ */
+export declare function annotateCurveAxes(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;
+    description: string;
+    inputSchema: Record<string, ZodTypeAny>;
+};

package/dist/tools.js

@@ -0,0 +1,272 @@
+import { z } from 'zod';
+import { UwaApiError } from './client.js';
+const ENGINE_LABEL = { unity: 'Unity', unreal: 'UE' };
+/**
+ * 预签名数据默认完整返回，不按条数截断——实测各接口解压后在 10 KB ~ 500 KB 之间，
+ * 使用者绝大多数时候要的就是全量。
+ *
+ * 只保留一道按字符数的兜底闸门，防止个别异常大的报告一次性撑爆模型上下文。
+ * 阈值取 50 万字符（约 16 万 token），高于目前观测到的最大值，正常报告不会触发。
+ */
+export const DEFAULT_MAX_ROWS = 0; // 0 表示不限条数
+export const DEFAULT_MAX_CHARS = 500_000; // 0 表示不限字符
+export function toolName(id, nameCase, prefix) {
+    const base = nameCase === 'camel' ? id.replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase()) : id;
+    return prefix ? `${prefix}${base}` : base;
+}
+function zodFor(param) {
+    switch (param.type) {
+        case 'number':
+            return z.number();
+        case 'boolean':
+            return z.boolean();
+        case 'string[]':
+            return z.array(z.string());
+        case 'number[]':
+            return z.array(z.number());
+        case 'object[]':
+            return z.array(z.record(z.unknown()));
+        default:
+            return z.string();
+    }
+}
+/**
+ * 工具描述是模型选对接口的唯一依据，所以把引擎适用范围、版本差异、
+ * 前置依赖和文档里的坑都带上；这些信息全部来自官方文档，不做推测。
+ */
+function describe(op) {
+    const lines = [op.summary || op.name];
+    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;
+    if (sdk)
+        lines.push(`SDK 要求：${sdk}`);
+    // 同一接口 Unity / UE 说明不同时分别标注，避免模型张冠李戴
+    const byEngine = new Map();
+    for (const v of op.variants) {
+        if (!v.description)
+            continue;
+        const label = v.docEngines.map((e) => ENGINE_LABEL[e]).join('/');
+        if (!byEngine.has(v.description))
+            byEngine.set(v.description, []);
+        byEngine.get(v.description).push(label);
+    }
+    if (byEngine.size === 1) {
+        lines.push([...byEngine.keys()][0]);
+    }
+    else {
+        for (const [desc, labels] of byEngine)
+            lines.push(`[${labels.join('/')}] ${desc}`);
+    }
+    const prereq = [...new Set(op.variants.map((v) => v.prerequisite).filter(Boolean))];
+    if (prereq.length)
+        lines.push(`前置依赖：${prereq.join('；')}`);
+    // 返回结构的语义规则必须完整给出：漏掉不会报错，但会让模型把数据读错
+    const rules = [...new Set(op.variants.flatMap((v) => v.returnRules))];
+    if (rules.length)
+        lines.push(`解读返回值时务必遵守：\n${rules.map((r) => `- ${r}`).join('\n')}`);
+    // 不做截断。文档里的注意事项常把最关键的约束放在最后一条
+    const notes = [...new Set(op.variants.flatMap((v) => v.notes))];
+    if (notes.length)
+        lines.push(`注意：\n${notes.map((n) => `- ${n}`).join('\n')}`);
+    if (op.returnsPresignUrl) {
+        lines.push('本接口返回预签名下载地址。工具已自动下载、解压并返回全部数据，无需再手动下载；' +
+            '只在明确只要前 N 条时才传 maxRows。若返回中出现 _truncated 字段，说明数据被截断，' +
+            '可用 download=false 取回 dataPresignUrl（有效期 600 秒）自行下载完整文件。');
+    }
+    return lines.join('\n');
+}
+export function buildInputSchema(op) {
+    const shape = {};
+    for (const p of [...op.query, ...op.body]) {
+        const base = zodFor(p).describe(p.example ? `${p.description}（示例：${p.example}）` : p.description);
+        shape[p.name] = p.required ? base : base.optional();
+    }
+    if (op.apiVersions.length > 1) {
+        shape['apiVersion'] = z
+            .enum(op.apiVersions)
+            .optional()
+            .describe(`接口版本，默认 ${op.defaultApiVersion}。不同版本的返回字段有差异，详见文档`);
+    }
+    if (op.returnsPresignUrl) {
+        shape['download'] = z
+            .boolean()
+            .optional()
+            .describe('是否自动下载并解析预签名数据，默认 true。设为 false 时只返回 dataPresignUrl');
+        shape['maxRows'] = z
+            .number()
+            .optional()
+            .describe('可选的条目数上限。默认返回全部数据，只有在明确只需要前 N 条时才传这个参数');
+    }
+    return shape;
+}
+/** 找出对象里最长的那个数组字段，它通常就是主数据列表。 */
+function mainArrayKey(obj) {
+    let best;
+    let bestLen = 0;
+    for (const [k, v] of Object.entries(obj)) {
+        if (Array.isArray(v) && v.length > bestLen) {
+            best = k;
+            bestLen = v.length;
+        }
+    }
+    return best;
+}
+/**
+ * 默认原样返回下载到的全部数据。
+ * maxRows > 0 时才按条数裁剪；无论如何都受 maxChars 兜底约束。
+ */
+function summarize(payload, maxRows, maxChars) {
+    let body;
+    let total;
+    let rowTruncated = false;
+    if (payload.kind === 'json') {
+        const data = payload.json;
+        if (Array.isArray(data)) {
+            total = data.length;
+            rowTruncated = maxRows > 0 && data.length > maxRows;
+            body = rowTruncated ? data.slice(0, maxRows) : data;
+        }
+        else if (data && typeof data === 'object') {
+            const obj = data;
+            const key = mainArrayKey(obj);
+            const arr = key ? obj[key] : undefined;
+            total = arr?.length;
+            rowTruncated = maxRows > 0 && arr !== undefined && arr.length > maxRows;
+            body = rowTruncated && key ? { ...obj, [key]: arr.slice(0, maxRows) } : data;
+        }
+        else {
+            body = data;
+        }
+    }
+    else {
+        const lines = (payload.text ?? '').split('\n');
+        total = lines.length;
+        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);
+    }
+    return { rowTruncated, charTruncated, total, chars: text.length, body: text };
+}
+function isObj(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/**
+ * 曲线类接口的返回里有两套横轴：部分曲线自带 y_axis.{指标}.x_axis（步长 30 帧），
+ * 其余用外层共享 x_axis（逐帧）。两者点数不同，混用会把数据对错帧。
+ *
+ * 光在工具描述里写规则不够可靠，这里直接为每条曲线标注它实际该用哪根横轴、
+ * 帧号范围和步长，并在点数对不上时给出警告，从结构上消除歧义。
+ */
+export function annotateCurveAxes(data) {
+    if (!isObj(data) || !isObj(data['y_axis']))
+        return data;
+    const yAxis = data['y_axis'];
+    const shared = isObj(data['x_axis']) && Array.isArray(data['x_axis']['data']) ? data['x_axis']['data'] : null;
+    const binding = {};
+    for (const [name, curve] of Object.entries(yAxis)) {
+        if (!isObj(curve))
+            continue;
+        const points = Array.isArray(curve['data']) ? curve['data'].length : 0;
+        const ownAxis = isObj(curve['x_axis']) && Array.isArray(curve['x_axis']['data']) ? curve['x_axis']['data'] : null;
+        const axis = ownAxis ?? shared;
+        const first = axis?.[0];
+        const last = axis?.[axis.length - 1];
+        binding[name] = {
+            points,
+            xAxisSource: ownAxis ? `y_axis.${name}.x_axis（该曲线专属）` : 'x_axis（外层共享）',
+            xAxisPoints: axis?.length ?? null,
+            xRange: axis?.length ? [first, last] : null,
+            step: axis && axis.length > 1 ? Number(axis[1]) - Number(axis[0]) : null,
+            ...(axis && axis.length !== points
+                ? { warning: `曲线 ${points} 个数据点与横轴 ${axis.length} 个点长度不一致，请勿按下标直接对齐` }
+                : {}),
+        };
+    }
+    if (Object.keys(binding).length === 0)
+        return data;
+    return {
+        ...data,
+        _axisBinding: binding,
+        _axisHint: '每条曲线按 _axisBinding[曲线名].xAxisSource 指定的横轴取值，不要统一使用外层 x_axis',
+    };
+}
+/** MCP 的 content.text 必须是字符串，undefined 会让客户端校验失败。 */
+function asText(value) {
+    if (typeof value === 'string')
+        return value;
+    if (value === undefined || value === null)
+        return '(接口无返回内容)';
+    return JSON.stringify(value, null, 2);
+}
+export function makeHandler(op, client, defaultMaxRows, maxChars) {
+    return async (args) => {
+        try {
+            const apiVersion = args['apiVersion'] ?? op.defaultApiVersion;
+            const wantDownload = args['download'] ?? true;
+            const maxRows = args['maxRows'] ?? defaultMaxRows;
+            const query = {};
+            for (const p of op.query)
+                if (args[p.name] !== undefined)
+                    query[p.name] = args[p.name];
+            let body;
+            if (op.body.length) {
+                body = {};
+                for (const p of op.body)
+                    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 presignUrl = op.returnsPresignUrl && data && typeof data === 'object'
+                ? data['dataPresignUrl']
+                : undefined;
+            if (!presignUrl || !wantDownload) {
+                return { content: [{ type: 'text', text: asText(data) }] };
+            }
+            const payload = await client.downloadPresign(presignUrl);
+            const { rowTruncated, charTruncated, total, chars, body: content } = summarize(payload, maxRows, maxChars);
+            const notes = [];
+            if (rowTruncated)
+                notes.push(`按 maxRows=${maxRows} 截断，去掉 maxRows 参数可取全量`);
+            if (charTruncated) {
+                notes.push(`内容超过 ${maxChars} 字符上限已截断，尾部数据缺失。` +
+                    `如需完整数据，用 download=false 拿 dataPresignUrl 自行下载，或启动时调大 --max-chars`);
+            }
+            const meta = {
+                ...data,
+                _downloaded: true,
+                _format: payload.kind,
+                ...(total !== undefined ? { _totalItems: total } : {}),
+                _returnedChars: chars,
+                ...(notes.length ? { _truncated: notes.join('；') } : { _complete: '已返回全部数据' }),
+            };
+            delete meta['dataPresignUrl'];
+            return {
+                content: [
+                    { type: 'text', text: asText(meta) },
+                    { type: 'text', text: asText(content) },
+                ],
+            };
+        }
+        catch (err) {
+            const msg = err instanceof UwaApiError
+                ? err.message
+                : err instanceof Error
+                    ? `调用 ${op.method} ${op.path} 失败：${err.message}`
+                    : String(err);
+            return { content: [{ type: 'text', text: msg }], isError: true };
+        }
+    };
+}
+export function toolConfig(op) {
+    return {
+        title: op.name,
+        description: describe(op),
+        inputSchema: buildInputSchema(op),
+    };
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@uwa4d/openapi-mcp",
+  "version": "0.1.0",
+  "description": "UWA 开放平台 MCP Server，将 UWA Open API 暴露为 MCP 工具供 AI 助手调用",
+  "type": "module",
+  "bin": {
+    "uwa-openapi-mcp": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "spec",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "gen": "tsx scripts/parse-docs.ts",
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/cli.ts",
+    "smoke": "tsx scripts/smoke-test.ts",
+    "prepublishOnly": "npm run build && node scripts/check-publish-tag.mjs",
+    "release": "node scripts/release.mjs",
+    "release:dry": "node scripts/release.mjs --dry-run",
+    "version:beta": "node scripts/bump.mjs beta",
+    "version:release": "node scripts/bump.mjs release"
+  },
+  "keywords": [
+    "uwa",
+    "mcp",
+    "model-context-protocol",
+    "openapi",
+    "game-performance"
+  ],
+  "license": "UNLICENSED",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "commander": "^12.1.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0"
+  }
+}