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

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'));
+}