@leadfund/lead-mcp 0.0.0-stage → 202610.2.0

package/src/config.js

@@ -0,0 +1,297 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/**
+ * 运行配置
+ *
+ * <p>配置来源优先级：命令行参数 &gt; 环境变量 &gt; 用户配置文件 &gt; 内置默认值。</p>
+ *
+ * <p><b>服务地址不在包里</b>：包内只保留 local 默认地址，
+ * sit / prd 等环境地址由使用方在自己的配置文件
+ * {@code ~/.lead-mcp/config.json} 或 {@code --base-url} 里指定。</p>
+ */
+
+/**
+ * @typedef {Object} LeadMcpConfig
+ * @property {string} env 环境标识，会随请求透传给后端用于审计
+ * @property {string[]} baseUrls dmmp-system（系统 id 275）服务地址列表，多个时按顺序故障转移
+ * @property {number} timeoutMs 单次请求超时（毫秒）
+ * @property {string|undefined} token 访问令牌，可选
+ * @property {string|undefined} operator 操作人标识（工号），用于服务端限流与审计
+ * @property {string|undefined} operatorOs 操作人操作系统账号
+ * @property {"stdio"|"sse"|"http"} transport 传输方式
+ * @property {number} httpPort HTTP 监听端口
+ * @property {string} httpHost HTTP 监听地址
+ * @property {string} httpPath HTTP 端点路径
+ * @property {string|undefined} authToken HTTP 访问令牌（Bearer），HTTP 模式下必填
+ */
+
+/**
+ * 内置环境
+ *
+ * <p>只保留本地开发地址。内网地址一律由使用方配置，避免随包公开。</p>
+ */
+export const BUILTIN_ENVIRONMENTS = {
+  local: {
+    label: "本地开发",
+    baseUrls: ["http://localhost:8081"],
+  },
+};
+
+export const DEFAULT_ENV = "local";
+export const DEFAULT_TIMEOUT_MS = 10000;
+export const DEFAULT_HTTP_PORT = 3100;
+export const DEFAULT_HTTP_HOST = "127.0.0.1";
+
+/**
+ * 传输方式
+ */
+export const TRANSPORTS = ["stdio", "sse", "http"];
+
+export const USAGE = `lead-mcp —— 利得零售系统 MCP Server
+
+用法：
+  lead-mcp [选项]
+
+服务地址（dmmp-system 275）
+  --env <环境>         目标环境名，从用户配置文件的 environments 里取
+                       也可用环境变量 LEAD_MCP_ENV
+  --base-url <url>     直接指定服务地址，逗号分隔多个时按顺序故障转移
+                       优先级高于 --env，也可用环境变量 LEAD_MCP_BASE_URL
+                       例：--base-url http://10.1.1.197:8081
+                           --base-url http://a:8081,http://b:8081
+
+传输方式
+  --transport <方式>   stdio（默认，本地 MCP Client）/ sse / http
+                       也可用环境变量 LEAD_MCP_TRANSPORT
+  --http-port <端口>   HTTP 监听端口，默认 ${DEFAULT_HTTP_PORT}
+  --http-host <地址>   HTTP 监听地址，默认 ${DEFAULT_HTTP_HOST}
+                       需要对外暴露时传 0.0.0.0
+  --http-path <路径>   HTTP 端点路径，默认 sse 用 /sse、http 用 /mcp
+  --auth-token <token> HTTP 访问令牌，HTTP 模式下必填（Bearer 认证）
+                       也可用环境变量 LEAD_MCP_AUTH_TOKEN
+
+通用
+  --timeout <ms>       单次请求超时毫秒数，默认 ${DEFAULT_TIMEOUT_MS}
+  --token <token>      dmmp-system 访问令牌，可选
+  --operator <工号>    操作人标识，用于服务端限流与审计；不配置则用操作系统账号
+  -h, --help           查看帮助
+
+用户配置文件（默认 ~/.lead-mcp/config.json，可用 LEAD_MCP_CONFIG 指定）：
+  {
+    "defaultEnvironment": "sit",
+    "environments": {
+      "sit": ["http://10.1.1.197:8081"],
+      "prd": ["http://10.32.30.208:8081", "http://10.32.30.209:8081"]
+    }
+  }
+`;
+
+/**
+ * 配置文件路径
+ *
+ * @returns {string} 路径
+ */
+export function resolveConfigFile() {
+  return (
+    process.env.LEAD_MCP_CONFIG ??
+    path.join(os.homedir(), ".lead-mcp", "config.json")
+  );
+}
+
+/**
+ * 读取用户配置文件
+ *
+ * @returns {{defaultEnvironment?: string, environments?: Record<string, string[]>}} 配置
+ * @throws {Error} 配置文件存在但格式非法
+ */
+export function loadUserConfig() {
+  const file = resolveConfigFile();
+  try {
+    const raw = fs.readFileSync(file, "utf8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object") {
+      throw new Error("格式必须是 JSON 对象");
+    }
+    return parsed;
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return {};
+    }
+    throw new Error(`读取配置文件失败 ${file}：${error.message}`);
+  }
+}
+
+/**
+ * 解析操作人的操作系统账号
+ *
+ * @returns {string|undefined}
+ */
+export function resolveOperatorOs() {
+  try {
+    const info = os.userInfo();
+    if (info && info.username) {
+      return info.username;
+    }
+  } catch {
+    // 容器环境下可能拿不到，忽略
+  }
+  return process.env.USER || process.env.USERNAME || undefined;
+}
+
+/**
+ * 解析 --key value 形式的参数
+ *
+ * @param {string[]} argv
+ * @returns {Map<string, string>}
+ */
+export function parseArgs(argv) {
+  const result = new Map();
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (!arg.startsWith("--")) {
+      continue;
+    }
+    const key = arg.slice(2);
+    const next = argv[i + 1];
+    if (next === undefined || next.startsWith("--")) {
+      result.set(key, "true");
+      continue;
+    }
+    result.set(key, next);
+    i += 1;
+  }
+  return result;
+}
+
+/**
+ * 解析服务地址列表
+ *
+ * @param {string} value 逗号分隔的地址
+ * @returns {string[]} 地址列表
+ */
+export function splitBaseUrls(value) {
+  return String(value)
+    .split(",")
+    .map((item) => item.trim().replace(/\/+$/, ""))
+    .filter((item) => item.length > 0);
+}
+
+/**
+ * 解析传输方式
+ *
+ * @param {string} name 传输方式
+ * @returns {"stdio"|"sse"|"http"} 传输方式
+ * @throws {Error} 非法
+ */
+export function normalizeTransport(name) {
+  const transport = String(name).trim().toLowerCase();
+  if (!TRANSPORTS.includes(transport)) {
+    throw new Error(`未知传输方式 "${name}"，可选值：${TRANSPORTS.join(" / ")}`);
+  }
+  return transport;
+}
+
+/**
+ * 加载配置
+ *
+ * @param {string[]} [argv]
+ * @returns {LeadMcpConfig}
+ * @throws {Error} 配置非法
+ */
+export function loadConfig(argv = process.argv.slice(2)) {
+  const args = parseArgs(argv);
+  const userConfig = loadUserConfig();
+
+  const rawEnv = args.get("env") ?? process.env.LEAD_MCP_ENV;
+  const rawBaseUrl = args.get("base-url") ?? process.env.LEAD_MCP_BASE_URL;
+  const hasBaseUrl = Boolean(rawBaseUrl) && rawBaseUrl !== "true";
+
+  // 解析服务地址：显式地址 > 用户配置的环境 > 内置 local
+  let env;
+  let baseUrls;
+  if (hasBaseUrl) {
+    env = rawEnv && rawEnv !== "true" ? String(rawEnv).trim() : "custom";
+    baseUrls = splitBaseUrls(rawBaseUrl);
+  } else {
+    const envName =
+      (rawEnv && rawEnv !== "true" ? rawEnv : undefined) ??
+      userConfig.defaultEnvironment ??
+      DEFAULT_ENV;
+    const configured = userConfig.environments?.[envName];
+    const builtin = BUILTIN_ENVIRONMENTS[envName];
+    if (!configured && !builtin) {
+      throw new Error(
+        `未知环境 "${envName}"。请在 ${resolveConfigFile()} 的 environments 里配置，` +
+          `或直接用 --base-url 指定地址`,
+      );
+    }
+    env = envName;
+    baseUrls = configured ?? builtin.baseUrls;
+  }
+  if (!Array.isArray(baseUrls) || baseUrls.length === 0) {
+    throw new Error(`环境 "${env}" 没有配置服务地址`);
+  }
+
+  // 传输方式
+  const rawTransport = args.get("transport") ?? process.env.LEAD_MCP_TRANSPORT;
+  const transport = normalizeTransport(
+    rawTransport && rawTransport !== "true" ? rawTransport : "stdio",
+  );
+
+  const portRaw = args.get("http-port") ?? process.env.LEAD_MCP_HTTP_PORT;
+  const httpPort = portRaw ? Number.parseInt(portRaw, 10) : DEFAULT_HTTP_PORT;
+  const hostRaw = args.get("http-host") ?? process.env.LEAD_MCP_HTTP_HOST;
+  const httpHost = hostRaw && hostRaw !== "true" ? hostRaw : DEFAULT_HTTP_HOST;
+  const pathRaw = args.get("http-path");
+  const httpPath =
+    pathRaw && pathRaw !== "true"
+      ? pathRaw
+      : transport === "sse"
+        ? "/sse"
+        : transport === "http"
+          ? "/mcp"
+          : "/mcp";
+
+  const authRaw = args.get("auth-token") ?? process.env.LEAD_MCP_AUTH_TOKEN;
+  const authToken = authRaw && authRaw !== "true" ? authRaw : undefined;
+
+  // HTTP 模式会被暴露到公网（典型是走 ng 隧道），没有令牌等于不设防
+  if (transport !== "stdio" && !authToken) {
+    throw new Error(
+      "HTTP 模式必须配置访问令牌：请用 --auth-token 或环境变量 LEAD_MCP_AUTH_TOKEN",
+    );
+  }
+
+  const timeoutRaw = args.get("timeout") ?? process.env.LEAD_MCP_TIMEOUT_MS;
+  const timeoutMs = timeoutRaw ? Number.parseInt(timeoutRaw, 10) : DEFAULT_TIMEOUT_MS;
+  const token = args.get("token") ?? process.env.LEAD_MCP_TOKEN;
+  const operatorRaw = args.get("operator") ?? process.env.LEAD_MCP_OPERATOR;
+  const operator = operatorRaw && operatorRaw !== "true" ? operatorRaw.trim() : undefined;
+
+  return {
+    env,
+    baseUrls,
+    timeoutMs: Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : DEFAULT_TIMEOUT_MS,
+    token: token && token !== "true" ? token : undefined,
+    // 未显式配置工号时退化为操作系统账号，保证服务端审计至少有「谁」
+    operator: operator ?? resolveOperatorOs(),
+    operatorOs: resolveOperatorOs(),
+    transport,
+    httpPort: Number.isFinite(httpPort) && httpPort > 0 ? httpPort : DEFAULT_HTTP_PORT,
+    httpHost,
+    httpPath,
+    authToken,
+  };
+}
+
+/**
+ * 是否请求帮助
+ *
+ * @param {string[]} [argv]
+ * @returns {boolean}
+ */
+export function isHelpRequested(argv = process.argv.slice(2)) {
+  return argv.includes("--help") || argv.includes("-h");
+}

package/src/http.js

@@ -0,0 +1,224 @@
+import crypto from "node:crypto";
+import http from "node:http";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createServer } from "./server.js";
+import { logger } from "./logger.js";
+
+/**
+ * HTTP(S) 传输
+ *
+ * <p>为云端 MCP 服务（如阿里云百炼）提供入口。百炼支持两种协议：</p>
+ * <ul>
+ *     <li>{@code sse}  —— {@code GET /sse} 建流，{@code POST /messages?sessionId=} 回传消息</li>
+ *     <li>{@code http} —— Streamable HTTP，{@code POST /mcp} 一站式</li>
+ * </ul>
+ *
+ * <p><b>鉴权</b>：所有业务端点校验 {@code Authorization: Bearer <token>}，
+ * 令牌由 {@code --auth-token} 配置，HTTP 模式下必填。</p>
+ */
+
+/**
+ * 定长安全比较
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean} 是否相等
+ */
+function timingSafeEqual(a, b) {
+  const bufA = Buffer.from(a ?? "", "utf8");
+  const bufB = Buffer.from(b ?? "", "utf8");
+  if (bufA.length !== bufB.length) {
+    return false;
+  }
+  return crypto.timingSafeEqual(bufA, bufB);
+}
+
+/**
+ * 校验 Authorization 头
+ *
+ * @param {http.IncomingMessage} req 请求
+ * @param {import("./config.js").LeadMcpConfig} config 配置
+ * @returns {boolean} 是否通过
+ */
+function checkAuth(req, config) {
+  if (!config.authToken) {
+    return true;
+  }
+  const header = req.headers.authorization ?? "";
+  return timingSafeEqual(header, `Bearer ${config.authToken}`);
+}
+
+/**
+ * 读取并解析 JSON 请求体
+ *
+ * @param {http.IncomingMessage} req 请求
+ * @returns {Promise<unknown>} 解析后的 body
+ */
+async function readJsonBody(req) {
+  const chunks = [];
+  for await (const chunk of req) {
+    chunks.push(chunk);
+  }
+  if (chunks.length === 0) {
+    return undefined;
+  }
+  const raw = Buffer.concat(chunks).toString("utf8");
+  if (!raw.trim()) {
+    return undefined;
+  }
+  return JSON.parse(raw);
+}
+
+/**
+ * 启动 HTTP 服务
+ *
+ * @param {import("./config.js").LeadMcpConfig} config 配置
+ * @returns {Promise<http.Server>} HTTP Server
+ */
+export async function startHttpServer(config) {
+  /** @type {Map<string, {transport: any, server: any}>} */
+  const sessions = new Map();
+
+  const server = http.createServer(async (req, res) => {
+    const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+
+    // 健康检查不鉴权，方便探活
+    if (req.method === "GET" && url.pathname === "/health") {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(
+        JSON.stringify({
+          ok: true,
+          transport: config.transport,
+          env: config.env,
+          sessions: sessions.size,
+        }),
+      );
+      return;
+    }
+
+    if (!checkAuth(req, config)) {
+      logger.warn("鉴权失败，已拒绝", { path: url.pathname, ip: req.socket.remoteAddress });
+      res.writeHead(401, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "unauthorized" }));
+      return;
+    }
+
+    try {
+      if (config.transport === "sse") {
+        await handleSse(url, req, res, config, sessions);
+      } else {
+        await handleStreamableHttp(url, req, res, config, sessions);
+      }
+    } catch (error) {
+      logger.error("HTTP 请求处理失败", error);
+      if (!res.headersSent) {
+        res.writeHead(500, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "internal error" }));
+      }
+    }
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(config.httpPort, config.httpHost, resolve);
+  });
+
+  const displayHost =
+    config.httpHost === "0.0.0.0" || config.httpHost === "::" ? "127.0.0.1" : config.httpHost;
+  logger.info(
+    `HTTP 服务已启动，传输=${config.transport}，端点=http://${displayHost}:${config.httpPort}${config.httpPath}` +
+      `，后端环境=${config.env}，地址=${config.baseUrls.join(", ")}`,
+  );
+  if (config.httpHost === "0.0.0.0") {
+    logger.info("已监听所有网卡，可用 ng/隧道工具暴露到公网");
+  }
+
+  return server;
+}
+
+/**
+ * SSE 传输：GET 建流，POST /messages 回传
+ *
+ * @param {URL} url
+ * @param {http.IncomingMessage} req
+ * @param {http.ServerResponse} res
+ * @param {import("./config.js").LeadMcpConfig} config
+ * @param {Map<string, any>} sessions
+ */
+async function handleSse(url, req, res, config, sessions) {
+  if (req.method === "GET" && url.pathname === config.httpPath) {
+    const transport = new SSEServerTransport("/messages", res);
+    const mcpServer = createServer(config);
+    sessions.set(transport.sessionId, { transport, server: mcpServer });
+    res.on("close", () => {
+      sessions.delete(transport.sessionId);
+      logger.info("SSE 连接关闭", { sessionId: transport.sessionId });
+    });
+    await mcpServer.connect(transport);
+    logger.info("SSE 连接建立", { sessionId: transport.sessionId });
+    return;
+  }
+
+  if (req.method === "POST" && url.pathname === "/messages") {
+    const sessionId = url.searchParams.get("sessionId") ?? "";
+    const entry = sessions.get(sessionId);
+    if (!entry) {
+      res.writeHead(404, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "session not found" }));
+      return;
+    }
+    const body = await readJsonBody(req);
+    await entry.transport.handlePostMessage(req, res, body);
+    return;
+  }
+
+  res.writeHead(404, { "Content-Type": "application/json" });
+  res.end(JSON.stringify({ error: "not found" }));
+}
+
+/**
+ * Streamable HTTP 传输
+ *
+ * @param {URL} url
+ * @param {http.IncomingMessage} req
+ * @param {http.ServerResponse} res
+ * @param {import("./config.js").LeadMcpConfig} config
+ * @param {Map<string, any>} sessions
+ */
+async function handleStreamableHttp(url, req, res, config, sessions) {
+  if (url.pathname !== config.httpPath) {
+    res.writeHead(404, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: "not found" }));
+    return;
+  }
+
+  const sessionId = req.headers["mcp-session-id"];
+  let entry = sessionId ? sessions.get(sessionId) : undefined;
+
+  if (!entry) {
+    if (req.method !== "POST") {
+      // 没有会话的 GET/DELETE 直接拒绝
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "missing mcp-session-id" }));
+      return;
+    }
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: () => crypto.randomUUID(),
+      onsessioninitialized: (id) => {
+        sessions.set(id, { transport, server: mcpServer });
+        logger.info("HTTP 会话建立", { sessionId: id });
+      },
+      onsessionclosed: (id) => {
+        sessions.delete(id);
+        logger.info("HTTP 会话关闭", { sessionId: id });
+      },
+    });
+    const mcpServer = createServer(config);
+    await mcpServer.connect(transport);
+    entry = { transport, server: mcpServer };
+  }
+
+  const body = req.method === "POST" ? await readJsonBody(req) : undefined;
+  await entry.transport.handleRequest(req, res, body);
+}

package/src/logger.js

@@ -0,0 +1,64 @@
+/**
+ * 日志工具
+ *
+ * <p><b>重要</b>：stdio 传输下 stdout 是 JSON-RPC 协议通道，
+ * 任何往 stdout 写的日志都会破坏协议。所有日志必须走 stderr。</p>
+ */
+
+/**
+ * @param {string} message
+ * @param {unknown[]} args
+ * @returns {string}
+ */
+function format(message, args) {
+  if (!args || args.length === 0) {
+    return message;
+  }
+  const details = args.map((arg) => {
+    if (arg instanceof Error) {
+      return `${arg.name}: ${arg.message}`;
+    }
+    if (typeof arg === "object" && arg !== null) {
+      try {
+        return JSON.stringify(arg);
+      } catch {
+        return String(arg);
+      }
+    }
+    return String(arg);
+  });
+  return `${message} ${details.join(" ")}`;
+}
+
+/**
+ * @param {string} level
+ * @param {string} message
+ * @param {unknown[]} args
+ */
+function write(level, message, args) {
+  process.stderr.write(`[lead-mcp] ${level} ${format(message, args)}\n`);
+}
+
+export const logger = {
+  /**
+   * @param {string} message
+   * @param {...unknown} args
+   */
+  info(message, ...args) {
+    write("INFO", message, args);
+  },
+  /**
+   * @param {string} message
+   * @param {...unknown} args
+   */
+  warn(message, ...args) {
+    write("WARN", message, args);
+  },
+  /**
+   * @param {string} message
+   * @param {...unknown} args
+   */
+  error(message, ...args) {
+    write("ERROR", message, args);
+  },
+};