@uwa4d/openapi-mcp 0.1.0

package/README.md

@@ -0,0 +1,189 @@
+# @uwa4d/openapi-mcp
+
+UWA 开放平台 MCP Server。把 UWA Open API 暴露为 MCP 工具，让 Cursor、Claude、Trae 等 AI 助手直接查询 GOT Online 性能报告数据。
+
+装好之后，可以直接用自然语言提问，例如：
+
+- 「列出我最近 10 份 GOT Online 报告」
+- 「分析 xxx 报告的卡顿帧，找出耗时最高的几个函数」
+- 「对比这两份报告的内存占用差异」
+
+## 准备
+
+1. **Node.js 18 或更高版本**（`node -v` 确认）。`npx` 随 Node 一起安装，不需要单独装本包。
+2. **AppId / AppSecret**：向 UWA 申请。
+
+## 接入
+
+在 AI 客户端的 MCP 配置里加上：
+
+```json
+{
+  "mcpServers": {
+    "uwa-openapi": {
+      "command": "npx",
+      "args": ["-y", "@uwa4d/openapi-mcp", "mcp"],
+      "env": {
+        "UWA_MCP_APP_ID": "<your_app_id>",
+        "UWA_MCP_APP_SECRET": "<your_app_secret>"
+      }
+    }
+  }
+}
+```
+
+配置文件位置：
+
+| 客户端 | 路径 |
+| --- | --- |
+| Cursor | `~/.cursor/mcp.json`（全局）或项目下 `.cursor/mcp.json` |
+| Claude Desktop | `claude_desktop_config.json` |
+| Trae | 设置面板中的 MCP 配置 |
+
+改完重启客户端即可。
+
+凭证也可以走命令行参数，适配不支持 `env` 字段的客户端：
+
+```json
+{
+  "mcpServers": {
+    "uwa-openapi": {
+      "command": "npx",
+      "args": ["-y", "@uwa4d/openapi-mcp", "mcp", "-a", "<app_id>", "-s", "<app_secret>"]
+    }
+  }
+}
+```
+
+> 配置文件里含有凭证，注意不要提交到公开代码仓库。
+
+### 先验证一下
+
+配置前可以在终端确认凭证和网络是否通：
+
+```bash
+npx -y @uwa4d/openapi-mcp check -a <app_id> -s <app_secret>
+```
+
+它会用你的凭证真实调用一次接口。输出「凭证有效，接口连通」就说明没问题，失败时会给出具体原因和排查方向。
+
+## 命令行参数
+
+三个子命令：`mcp` 启动服务（默认）、`check` 验证凭证、`list-tools` 查看工具清单。
+
+以下参数用于 `mcp`：
+
+| 参数 | 简写 | 说明 | 环境变量 |
+|------|------|------|----------|
+| `--app-id` | `-a` | AppId | `UWA_MCP_APP_ID` |
+| `--app-secret` | `-s` | AppSecret | `UWA_MCP_APP_SECRET` |
+| `--base-url` | `-b` | 接口地址，默认 `https://secure-api.uwa4d.com` | `UWA_MCP_API_BASE_URL` |
+| `--sandbox` | | 切到测试环境 `https://sandbox-api.uwa4d.com` | |
+| `--tool` | `-t` | 加载哪些工具，逗号分隔，默认 `preset.default` | `UWA_MCP_TOOL` |
+| `--engine` | `-e` | 只加载适用于 `unity` / `unreal` 的工具，默认 `all` | `UWA_MCP_ENGINE` |
+| `--tool-name-case` | `-c` | 工具命名风格 `snake` / `camel`，默认 `snake` | |
+| `--tool-name-prefix` | | 工具名前缀，便于与其他 MCP 区分 | `UWA_MCP_TOOL_NAME_PREFIX` |
+| `--max-rows` | | 预签名数据的条目数上限，`0` 表示不限（默认返回全部） | |
+| `--max-chars` | | 单次返回的字符数上限，防止超大数据撑爆上下文，`0` 表示不限 | |
+| `--timeout` | | 单次请求超时毫秒数，默认 60000 | |
+
+## 工具过滤
+
+全部接口一次性注册会让模型难以选择，默认只加载 `preset.default`。用 `--tool` 按需调整：
+
+```bash
+# 默认高频工具集
+-t preset.default
+
+# 全部只读接口
+-t preset.readonly
+
+# 全部工具
+-t all
+
+# 按模块加载：common / gotonline / overview / gpu / mono / lua / localtest
+-t overview,gpu
+
+# 组合：默认集 + 所有预签名类接口 + 单个指定工具
+-t preset.default,presign,gotonline_overview_stack_id_map
+
+# 只做 Unity 项目，砍掉 UE 专用工具
+-t preset.default -e unity
+```
+
+查看全部工具和可用过滤键：
+
+```bash
+npx -y @uwa4d/openapi-mcp list-tools
+npx -y @uwa4d/openapi-mcp list-tools -t overview -e unity
+```
+
+## 大数据接口的返回方式
+
+堆栈树、资源列表、卡顿帧等接口不直接返回数据，而是返回一个有效期 600 秒的预签名下载地址。
+
+**这类工具会自动下载、解压并返回全部数据**，不需要你手动下载。返回里带有完整性标记：
+
+- `_complete: "已返回全部数据"` — 数据完整
+- `_totalItems` — 主数据列表的条目总数
+- `_returnedChars` — 实际返回的字符数
+
+只在明确只要前 N 条时才传 `maxRows`。另有一道字符数兜底闸门（`--max-chars`，默认 50 万字符），正常报告不会触发；一旦触发会在 `_truncated` 里说清楚，此时可以用 `download: false` 取回 `dataPresignUrl` 自行下载完整文件。
+
+## 曲线接口的双横轴
+
+曲线类接口（如 `gotonline_overview_indicator_curve_dashboard`）的返回里有**两套横轴**：部分曲线自带 `y_axis.{指标名}.x_axis`，其余用外层共享 `x_axis`。两者点数不同，混用会把数据对错帧。
+
+工具会在保留原始结构的前提下追加 `_axisBinding`，逐条说明该用哪根横轴：
+
+```json
+{
+  "y_axis": { "...": "原始数据原样保留" },
+  "x_axis": { "...": "原始数据原样保留" },
+  "_axisBinding": {
+    "fps": {
+      "points": 14,
+      "xAxisSource": "y_axis.fps.x_axis（该曲线专属）",
+      "xAxisPoints": 14,
+      "xRange": [0, 390],
+      "step": 30
+    },
+    "Application_TargetFramerate_Count": {
+      "points": 407,
+      "xAxisSource": "x_axis（外层共享）",
+      "xAxisPoints": 407,
+      "xRange": [1, 407],
+      "step": 1
+    }
+  }
+}
+```
+
+数据点数与横轴点数不一致时会额外给出 `warning`。
+
+## 版本
+
+`npx -y @uwa4d/openapi-mcp` 会自动拉取最新稳定版。可以按需要锁定版本，写在包名后面：
+
+| 写法 | 行为 | 适用 |
+| --- | --- | --- |
+| `@uwa4d/openapi-mcp` | 跟随最新稳定版，自动升级 | 默认，大多数用户 |
+| `@uwa4d/openapi-mcp@0.1.0` | 锁死某个版本 | 生产流水线，要求完全可复现 |
+| `@uwa4d/openapi-mcp@beta` | 跟随测试版 | 配合 UWA 验证新接口 |
+
+测试版只发布在 `beta` 标签下，默认写法不会拉到测试版。
+
+## 常见问题
+
+**启动后客户端里看不到工具**
+检查 Node 版本是否 ≥ 18，以及配置文件 JSON 格式是否正确（多一个逗号就会整个失效）。改完配置需要重启客户端。
+
+**提示凭证错误**
+用 `check` 命令在终端单独验证一次，排除是客户端配置传参的问题。注意测试环境和生产环境的凭证不通用。
+
+**返回「数据服务错误」**
+部分接口区分报告生成时间和引擎类型，例如 Unity 2026-07-09 之前的报告用 `get_overview_statistic_v1`，之后的用 `get_overview_statistic_v2`。工具描述里注明了适用范围。
+
+## 许可
+
+Copyright © UWA. 保留所有权利。

package/dist/auth.d.ts

@@ -0,0 +1,16 @@
+export interface Credentials {
+    appId: string;
+    appSecret: string;
+}
+/**
+ * UWA 开放平台签名。
+ *
+ * sign = SHA256(appSecret 字节 ‖ (appId + "/n" + timestamp) 字节)
+ *
+ * 注意两个容易踩的点：
+ *   - "/n" 是字面的斜杠加字母 n，不是换行符
+ *   - appSecret 是作为哈希前缀喂进去的，不是标准 HMAC
+ */
+export declare function sign(creds: Credentials, timestampSec: number): string;
+/** 服务端允许的时间偏差是 20 分钟，这里每次请求都重新生成，不做缓存。 */
+export declare function authHeaders(creds: Credentials, apiVersion: string): Record<string, string>;

package/dist/auth.js

@@ -0,0 +1,27 @@
+import { createHash } from 'node:crypto';
+/**
+ * UWA 开放平台签名。
+ *
+ * sign = SHA256(appSecret 字节 ‖ (appId + "/n" + timestamp) 字节)
+ *
+ * 注意两个容易踩的点：
+ *   - "/n" 是字面的斜杠加字母 n，不是换行符
+ *   - appSecret 是作为哈希前缀喂进去的，不是标准 HMAC
+ */
+export function sign(creds, timestampSec) {
+    return createHash('sha256')
+        .update(creds.appSecret, 'utf8')
+        .update(`${creds.appId}/n${timestampSec}`, 'utf8')
+        .digest('hex');
+}
+/** 服务端允许的时间偏差是 20 分钟，这里每次请求都重新生成，不做缓存。 */
+export function authHeaders(creds, apiVersion) {
+    const ts = Math.floor(Date.now() / 1000);
+    return {
+        'x-uwa-api-minor-version': apiVersion,
+        'x-uwa-open-api-app-id': creds.appId,
+        'x-uwa-open-api-sign': sign(creds, ts),
+        'x-uwa-open-api-timestamp': String(ts),
+        'x-uwa-open-api-sign-version': 'v1',
+    };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+import { Command, Option } from 'commander';
+import { UwaClient } from './client.js';
+import { loadSpec } from './spec.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';
+const DEFAULT_BASE_URL = 'https://secure-api.uwa4d.com';
+const SANDBOX_BASE_URL = 'https://sandbox-api.uwa4d.com';
+function splitList(value) {
+    return value
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+/** 凭证不落配置文件时可以只给环境变量，命令行参数优先级更高。 */
+function resolveCredentials(opts) {
+    const appId = opts.appId ?? process.env['UWA_MCP_APP_ID'];
+    const appSecret = opts.appSecret ?? process.env['UWA_MCP_APP_SECRET'];
+    if (!appId || !appSecret) {
+        console.error('缺少凭证。请通过 -a/--app-id 与 -s/--app-secret 传入，\n' +
+            '或设置环境变量 UWA_MCP_APP_ID / UWA_MCP_APP_SECRET。');
+        process.exit(1);
+    }
+    return { appId, appSecret };
+}
+const program = new Command();
+program
+    .name('uwa-openapi-mcp')
+    .description('UWA 开放平台 MCP Server，把 UWA Open API 暴露为 MCP 工具')
+    .version(PACKAGE_VERSION);
+program
+    .command('mcp', { isDefault: true })
+    .description('启动 MCP Server')
+    .option('-a, --app-id <id>', 'UWA 开放平台 AppId（环境变量 UWA_MCP_APP_ID）')
+    .option('-s, --app-secret <secret>', 'UWA 开放平台 AppSecret（环境变量 UWA_MCP_APP_SECRET）')
+    .option('-b, --base-url <url>', `接口地址（环境变量 UWA_MCP_API_BASE_URL）`, process.env['UWA_MCP_API_BASE_URL'] ?? DEFAULT_BASE_URL)
+    .option('--sandbox', `使用测试环境 ${SANDBOX_BASE_URL}`, false)
+    .option('-t, --tool <list>', '加载的工具，逗号分隔，可用 preset.default / preset.readonly / all / 模块名 / 工具名', splitList)
+    .addOption(new Option('-e, --engine <engine>', '只加载适用于该引擎的工具')
+    .choices(['unity', 'unreal', 'all'])
+    .default(process.env['UWA_MCP_ENGINE'] ?? 'all'))
+    .addOption(new Option('-c, --tool-name-case <case>', '工具命名风格').choices(['snake', 'camel']).default('snake'))
+    .option('--tool-name-prefix <prefix>', '工具名前缀，便于与其他 MCP 区分', process.env['UWA_MCP_TOOL_NAME_PREFIX'] ?? '')
+    .option('--max-rows <n>', '预签名数据的条目数上限，0 表示不限（默认返回全部）', (v) => Number.parseInt(v, 10), DEFAULT_MAX_ROWS)
+    .option('--max-chars <n>', '单次返回的字符数兜底上限，防止异常大的数据撑爆上下文，0 表示不限', (v) => Number.parseInt(v, 10), DEFAULT_MAX_CHARS)
+    .option('--timeout <ms>', '单次请求超时（毫秒）', (v) => Number.parseInt(v, 10), 60_000)
+    .option('--spec <path>', '自定义 spec 文件路径，默认用内置的')
+    .action(async (opts) => {
+    const { appId, appSecret } = resolveCredentials(opts);
+    await startStdio({
+        appId,
+        appSecret,
+        baseUrl: opts.sandbox ? SANDBOX_BASE_URL : opts.baseUrl,
+        tools: opts.tool ?? splitList(process.env['UWA_MCP_TOOL'] ?? 'preset.default'),
+        engine: opts.engine,
+        nameCase: opts.toolNameCase,
+        namePrefix: opts.toolNamePrefix,
+        maxRows: opts.maxRows,
+        maxChars: opts.maxChars,
+        timeoutMs: opts.timeout,
+        specPath: opts.spec,
+    });
+});
+program
+    .command('list-tools')
+    .description('列出可用工具及其过滤键，用于挑选 --tool 的取值')
+    .option('-t, --tool <list>', '按过滤键预览选中结果', splitList)
+    .addOption(new Option('-e, --engine <engine>', '按引擎过滤').choices(['unity', 'unreal', 'all']).default('all'))
+    .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 byModule = new Map();
+    for (const op of spec.operations) {
+        const key = op.modules.join(',');
+        if (!byModule.has(key))
+            byModule.set(key, []);
+        byModule.get(key).push(op);
+    }
+    for (const [module, ops] of [...byModule].sort()) {
+        console.log(`\n## ${module}`);
+        for (const op of ops) {
+            const mark = selected.has(op.id) ? '*' : ' ';
+            const engines = op.engines.map((e) => (e === 'unity' ? 'U3D' : 'UE')).join('+');
+            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(', ')}`);
+});
+program
+    .command('check')
+    .description('验证凭证与网络连通性，用于接入前自查')
+    .option('-a, --app-id <id>', 'UWA 开放平台 AppId（环境变量 UWA_MCP_APP_ID）')
+    .option('-s, --app-secret <secret>', 'UWA 开放平台 AppSecret（环境变量 UWA_MCP_APP_SECRET）')
+    .option('-b, --base-url <url>', '接口地址', process.env['UWA_MCP_API_BASE_URL'] ?? DEFAULT_BASE_URL)
+    .option('--sandbox', `使用测试环境 ${SANDBOX_BASE_URL}`, false)
+    .option('--timeout <ms>', '单次请求超时（毫秒）', (v) => Number.parseInt(v, 10), 30_000)
+    .action(async (opts) => {
+    const { appId, appSecret } = resolveCredentials(opts);
+    const baseUrl = opts.sandbox ? SANDBOX_BASE_URL : opts.baseUrl;
+    console.log(`接口地址：${baseUrl}`);
+    console.log(`AppId：${appId}`);
+    const client = new UwaClient({
+        baseUrl,
+        credentials: { appId, appSecret },
+        timeoutMs: opts.timeout,
+    });
+    try {
+        // 挑一个最轻的只读接口做真实调用，凭证、签名、网络三者一次性验完
+        const data = await client.call('GET', '/openapi/v1/data/report/record/batch', 'v1.0.1', {
+            days: 7,
+            pageNo: 1,
+            pageSize: 10,
+        });
+        const total = data?.total;
+        console.log('\n凭证有效，接口连通。');
+        if (typeof total === 'number')
+            console.log(`最近 7 天有 ${total} 份报告。`);
+        console.log('\n可以按 README 配置 MCP 客户端了。');
+    }
+    catch (err) {
+        console.error(`\n调用失败：${err instanceof Error ? err.message : String(err)}`);
+        console.error('\n排查方向：\n' +
+            '  - 凭证是否填错或已停用\n' +
+            '  - 是否该用测试环境（加 --sandbox）\n' +
+            '  - 本机到接口地址的网络是否通（代理、防火墙）');
+        process.exit(1);
+    }
+});
+program.parseAsync(process.argv).catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});

package/dist/client.d.ts

@@ -0,0 +1,28 @@
+import { type Credentials } from './auth.js';
+import type { HttpMethod } from './spec.js';
+export interface ClientOptions {
+    baseUrl: string;
+    credentials: Credentials;
+    timeoutMs: number;
+}
+export declare class UwaApiError extends Error {
+    readonly code: number;
+    readonly rawMessage: string;
+    constructor(code: number, rawMessage: string, message: string);
+}
+export declare class UwaClient {
+    private readonly opts;
+    constructor(opts: ClientOptions);
+    call(method: HttpMethod, path: string, apiVersion: string, query: Record<string, unknown>, body?: Record<string, unknown>): Promise<unknown>;
+    /**
+     * 下载预签名地址指向的数据。
+     *
+     * 这些文件动辄几十 MB 且多为 gzip，必须在这里解压、解析、截断，
+     * 直接把原始内容交给模型会撑爆上下文。
+     */
+    downloadPresign(presignUrl: string): Promise<{
+        kind: 'json' | 'text';
+        json?: unknown;
+        text?: string;
+    }>;
+}

package/dist/client.js

@@ -0,0 +1,103 @@
+import { gunzipSync } from 'node:zlib';
+import { authHeaders } from './auth.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;
+    constructor(code, rawMessage, message) {
+        super(message);
+        this.code = code;
+        this.rawMessage = rawMessage;
+        this.name = 'UwaApiError';
+    }
+}
+export class UwaClient {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async call(method, path, apiVersion, query, body) {
+        const url = new URL(path, this.opts.baseUrl);
+        for (const [k, v] of Object.entries(query)) {
+            if (v === undefined || v === null || v === '')
+                continue;
+            // 文档约定：多值参数一律用英文逗号分隔，不用重复 key
+            url.searchParams.set(k, Array.isArray(v) ? v.join(',') : String(v));
+        }
+        const headers = authHeaders(this.opts.credentials, apiVersion);
+        if (body)
+            headers['Content-Type'] = 'application/json';
+        const res = await fetch(url, {
+            method,
+            headers,
+            body: body ? JSON.stringify(body) : undefined,
+            signal: AbortSignal.timeout(this.opts.timeoutMs),
+        });
+        const text = await res.text();
+        if (!res.ok && !text) {
+            throw new UwaApiError(res.status, 'HTTP_ERROR', `HTTP ${res.status} ${res.statusText}`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            // idmap 等接口返回 octet-stream，非 JSON 时原样交回
+            return text;
+        }
+        // idmap 一类接口直接返回业务数据，没有 {status, data} 信封，
+        // 只有识别出信封结构时才拆包，否则原样返回，避免拆出 undefined。
+        if (!isEnvelope(parsed))
+            return parsed;
+        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}` : ''}`);
+        }
+        return parsed.data ?? {};
+    }
+    /**
+     * 下载预签名地址指向的数据。
+     *
+     * 这些文件动辄几十 MB 且多为 gzip，必须在这里解压、解析、截断，
+     * 直接把原始内容交给模型会撑爆上下文。
+     */
+    async downloadPresign(presignUrl) {
+        const res = await fetch(presignUrl, { signal: AbortSignal.timeout(this.opts.timeoutMs) });
+        if (!res.ok)
+            throw new Error(`下载预签名数据失败：HTTP ${res.status} ${res.statusText}`);
+        let buf = Buffer.from(await res.arrayBuffer());
+        // fetch 只在响应头声明 Content-Encoding 时自动解压；
+        // OSS 上不少文件是内容本身就是 gzip，靠 magic bytes 兜底
+        if (buf.length > 2 && buf[0] === 0x1f && buf[1] === 0x8b)
+            buf = gunzipSync(buf);
+        const text = buf.toString('utf8');
+        const head = text.trimStart()[0];
+        if (head === '{' || head === '[') {
+            try {
+                return { kind: 'json', json: JSON.parse(text) };
+            }
+            catch {
+                /* 落到文本分支 */
+            }
+        }
+        return { kind: 'text', text };
+    }
+}

package/dist/presets.d.ts

@@ -0,0 +1,20 @@
+import type { Engine, Operation } from './spec.js';
+/**
+ * 默认加载的高频工具。
+ *
+ * 全量 55 个接口一次性注册会让 tools/list 过长、模型选择困难，
+ * 所以默认只给覆盖 80% 场景的这一组，其余通过 --tool 按需加载。
+ */
+export declare const PRESET_DEFAULT: readonly string[];
+/**
+ * 每个接口对应的一组过滤键，用户在 --tool 里写任意一个即可命中。
+ * 键包含：工具 id、所属模块、preset 名、以及 presign 这一横切分类。
+ */
+export declare function filterKeys(op: Operation): string[];
+export interface SelectOptions {
+    /** --tool 的取值，未指定时用 preset.default */
+    tools?: string[];
+    /** --engine 过滤，'all' 表示不过滤 */
+    engine?: Engine | 'all';
+}
+export declare function selectOperations(all: Operation[], opts: SelectOptions): Operation[];

package/dist/presets.js

@@ -0,0 +1,51 @@
+/**
+ * 默认加载的高频工具。
+ *
+ * 全量 55 个接口一次性注册会让 tools/list 过长、模型选择困难，
+ * 所以默认只给覆盖 80% 场景的这一组，其余通过 --tool 按需加载。
+ */
+export const PRESET_DEFAULT = [
+    'list_report_records',
+    'get_report_detail',
+    'get_report_url',
+    'list_scenes',
+    'gotonline_meta_custom',
+    'get_overview_statistic_v1',
+    'get_overview_statistic_v2',
+    'get_ue_overview_statistic_v2',
+    'get_scene_statistic_v1',
+    'get_scene_statistic_v2',
+    'get_gpu_statistic',
+    'get_mono_statistic',
+    'get_localtest_statistic',
+    'get_localtest_failed_assets',
+    'list_optimization_tasks',
+    'gotonline_overview_indicator_statistic_dashboard',
+    'gotonline_overview_indicator_curve_dashboard',
+    'gotonline_overview_memory_manage_data_report',
+    'gotonline_overview_method_group_statistic',
+    'gotonline_overview_stack_stutter_full_presign',
+];
+/**
+ * 每个接口对应的一组过滤键，用户在 --tool 里写任意一个即可命中。
+ * 键包含：工具 id、所属模块、preset 名、以及 presign 这一横切分类。
+ */
+export function filterKeys(op) {
+    const keys = new Set([op.id, 'preset.all', 'all', ...op.modules]);
+    if (op.returnsPresignUrl)
+        keys.add('presign');
+    if (op.method === 'GET')
+        keys.add('preset.readonly');
+    if (PRESET_DEFAULT.includes(op.id))
+        keys.add('preset.default');
+    return [...keys];
+}
+export function selectOperations(all, opts) {
+    const wanted = new Set((opts.tools?.length ? opts.tools : ['preset.default']).map((t) => t.trim()).filter(Boolean));
+    const engine = opts.engine ?? 'all';
+    return all.filter((op) => {
+        if (engine !== 'all' && !op.engines.includes(engine))
+            return false;
+        return filterKeys(op).some((k) => wanted.has(k));
+    });
+}

package/dist/server.d.ts

@@ -0,0 +1,25 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type Engine } from './spec.js';
+import { type NameCase } from './tools.js';
+export interface ServerOptions {
+    appId: string;
+    appSecret: string;
+    baseUrl: string;
+    tools: string[];
+    engine: Engine | 'all';
+    nameCase: NameCase;
+    namePrefix: string;
+    /** 0 表示不按条数截断（默认） */
+    maxRows: number;
+    /** 0 表示不按字符数截断 */
+    maxChars: number;
+    timeoutMs: number;
+    specPath?: string;
+}
+export declare const PACKAGE_VERSION = "0.1.0";
+export declare function createServer(opts: ServerOptions): {
+    server: McpServer;
+    toolCount: number;
+    total: number;
+};
+export declare function startStdio(opts: ServerOptions): Promise<void>;

package/dist/server.js

@@ -0,0 +1,27 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { UwaClient } from './client.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';
+export function createServer(opts) {
+    const spec = loadSpec(opts.specPath);
+    const operations = selectOperations(spec.operations, { tools: opts.tools, engine: opts.engine });
+    const client = new UwaClient({
+        baseUrl: opts.baseUrl,
+        credentials: { appId: opts.appId, appSecret: opts.appSecret },
+        timeoutMs: opts.timeoutMs,
+    });
+    const server = new McpServer({ name: 'uwa-openapi-mcp', version: PACKAGE_VERSION });
+    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 };
+}
+export async function startStdio(opts) {
+    const { server, toolCount, total } = createServer(opts);
+    // stdout 是 MCP 协议通道，任何日志都必须走 stderr
+    console.error(`[uwa-openapi-mcp] 已加载 ${toolCount}/${total} 个工具，接口地址 ${opts.baseUrl}`);
+    await server.connect(new StdioServerTransport());
+}