@leadfund/lead-mcp 0.0.0-stage → 202610.2.0

package/src/server.js

@@ -0,0 +1,190 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { LeadApiError, queryAccount } from "./client.js";
+import { logger } from "./logger.js";
+
+/**
+ * MCP Server
+ *
+ * <p>本 Server 只提供<b>只读</b>工具，不做任何写操作。
+ * 工具的真实实现全部在 dmmp-system 侧，本层仅做协议适配与结果转述。</p>
+ */
+
+export const SERVER_NAME = "lead-mcp";
+export const SERVER_VERSION = "202610.1.0";
+
+/**
+ * 查询客户账户信息 工具名
+ */
+export const TOOL_QUERY_ACCOUNT = "dmmp_query_account";
+
+export const TOOL_DESCRIPTION = [
+  "根据手机号或身份证号查询客户账户信息，返回会员 id、姓名、手机号、证件类型、证件号码、证件有效期（均为脱敏值）。",
+  "手机号、身份证号、会员号三者至少提供一项；网点号可选。",
+  "网点号用于限定客户所属网点：指定网点号后结果唯一，要么查到唯一账户、要么查不到；查不到说明该客户不在这个网点下。",
+  "一个手机号或证件号可能对应多个会员。若返回多个候选会员号，必须请用户确认要查询哪一个，再带上 memberId 重新查询，不要自行挑一个。",
+  "若返回「未查询到该客户信息」，直接回答未查询到，禁止推测或补充任何未返回的内容。",
+].join("");
+
+const queryAccountInputSchema = {
+  mobile: z
+    .string()
+    .regex(/^1[3-9]\d{9}$/, "手机号格式不正确")
+    .optional()
+    .describe("完整手机号，11 位且以 1 开头。与 idNo / memberId 至少提供一项。"),
+  idNo: z
+    .string()
+    .regex(/^(\d{17}[\dXx]|\d{15})$/, "证件号码格式不正确")
+    .optional()
+    .describe("完整身份证号，15 位或 18 位。与 mobile / memberId 至少提供一项。"),
+  ownerNet: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("网点号，可选。传入后仅返回该网点下的客户，结果唯一。"),
+  memberId: z
+    .string()
+    .min(1)
+    .optional()
+    .describe(
+      "会员号，可选。命中多个会员时，先让用户确认要哪一个，再带上该会员号重新查询。",
+    ),
+};
+
+export const NOT_FOUND_TEXT = "未查询到该客户信息。";
+
+/**
+ * 指定网点但查不到时的提示
+ *
+ * @param {string} ownerNet 网点号
+ * @returns {string}
+ */
+export function formatNotFoundWithNet(ownerNet) {
+  return `未查询到该客户信息。该手机号/证件号在网点 ${ownerNet} 下没有账户，可能该客户不属于该网点。`;
+}
+
+/**
+ * 命中多个会员时的提示
+ *
+ * @param {string[]} memberIdList 候选会员号
+ * @returns {string}
+ */
+export function formatMultiMatch(memberIdList) {
+  return [
+    "该手机号/证件号在系统中匹配到多个会员，无法确定具体是哪一个。",
+    "请让用户确认需要查询哪一个会员，然后带上 memberId 重新查询，不要自行选择其中一个。",
+    "候选会员号：",
+    ...memberIdList.map((id) => `- ${id}`),
+  ].join("\n");
+}
+
+/**
+ * 把客户档案转成便于阅读的文本
+ *
+ * @param {import("./client.js").AccountProfile} profile
+ * @returns {string}
+ */
+export function formatProfile(profile) {
+  const lines = [];
+  if (profile.memberId) {
+    lines.push(`会员id：${profile.memberId}`);
+  }
+  if (profile.name) {
+    lines.push(`姓名：${profile.name}`);
+  }
+  if (profile.mobileFormat) {
+    lines.push(`手机号：${profile.mobileFormat}`);
+  }
+  if (profile.idTypeFormat || profile.idType) {
+    lines.push(`证件类型：${profile.idTypeFormat || profile.idType}`);
+  }
+  if (profile.idNoFormat) {
+    lines.push(`证件号码：${profile.idNoFormat}`);
+  }
+  if (profile.idValidityFormat || profile.idValidity) {
+    lines.push(`证件有效期：${profile.idValidityFormat || profile.idValidity}`);
+  }
+  return lines.length > 0 ? lines.join("\n") : JSON.stringify(profile);
+}
+
+/**
+ * 创建 MCP Server
+ *
+ * @param {import("./config.js").LeadMcpConfig} config
+ * @returns {McpServer}
+ */
+export function createServer(config) {
+  const server = new McpServer({
+    name: SERVER_NAME,
+    version: SERVER_VERSION,
+  });
+
+  server.registerTool(
+    TOOL_QUERY_ACCOUNT,
+    {
+      title: "查询客户账户信息",
+      description: TOOL_DESCRIPTION,
+      inputSchema: queryAccountInputSchema,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (args) => {
+      const { mobile, idNo, ownerNet, memberId } = args;
+
+      if (!mobile && !idNo && !memberId) {
+        logger.warn("工具调用参数缺失，mobile、idNo、memberId 至少需要提供一项");
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: "参数错误：手机号、身份证号、会员号至少需要提供一项。",
+            },
+          ],
+        };
+      }
+
+      try {
+        const profile = await queryAccount(config, { mobile, idNo, ownerNet, memberId });
+        const memberIdList = profile.memberIdList ?? [];
+
+        // 一个手机号/证件号可能对应多个会员，此时后端只返回候选会员号
+        if (memberIdList.length > 1) {
+          logger.info("客户信息命中多个会员", { memberIdList });
+          return {
+            content: [{ type: "text", text: formatMultiMatch(memberIdList) }],
+          };
+        }
+
+        if (!profile.found) {
+          logger.info("客户信息未命中", { mobile, ownerNet, memberId });
+          return {
+            content: [
+              {
+                type: "text",
+                text: ownerNet ? formatNotFoundWithNet(ownerNet) : NOT_FOUND_TEXT,
+              },
+            ],
+          };
+        }
+        logger.info("客户信息查询成功", { memberId: profile.memberId });
+        return {
+          content: [{ type: "text", text: formatProfile(profile) }],
+        };
+      } catch (error) {
+        const message = error instanceof LeadApiError ? error.message : String(error);
+        logger.error("客户信息查询失败", error);
+        return {
+          isError: true,
+          content: [{ type: "text", text: `查询失败：${message}` }],
+        };
+      }
+    },
+  );
+
+  return server;
+}

package/test/config.test.mjs

@@ -0,0 +1,157 @@
+/**
+ * 配置解析单元测试
+ *
+ * <p>运行：node test/config.test.mjs</p>
+ */
+
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  BUILTIN_ENVIRONMENTS,
+  loadConfig,
+  normalizeTransport,
+  resolveConfigFile,
+  splitBaseUrls,
+} from "../src/config.js";
+
+let passed = 0;
+
+/**
+ * 断言
+ *
+ * @param {string} name 用例名
+ * @param {Function} fn 断言函数
+ */
+function test(name, fn) {
+  try {
+    fn();
+    passed += 1;
+    console.log(`✓ ${name}`);
+  } catch (error) {
+    console.error(`✗ ${name}\n  ${error.message}`);
+    process.exitCode = 1;
+  }
+}
+
+// 用临时配置文件，避免污染真实环境
+const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "lead-mcp-test-"));
+const configFile = path.join(tmpDir, "config.json");
+fs.writeFileSync(
+  configFile,
+  JSON.stringify({
+    defaultEnvironment: "sit",
+    environments: {
+      sit: ["http://10.1.1.197:8081"],
+      prd: ["http://10.32.30.208:8081", "http://10.32.30.209:8081"],
+    },
+  }),
+);
+process.env.LEAD_MCP_CONFIG = configFile;
+
+test("内置只有 local，功能代码不依赖内网地址", () => {
+  assert.deepEqual(Object.keys(BUILTIN_ENVIRONMENTS), ["local"]);
+  const builtins = JSON.stringify(BUILTIN_ENVIRONMENTS);
+  assert.ok(
+    !/10\.\d+\.\d+\.\d+/.test(builtins),
+    "内置环境表里不应出现内网地址",
+  );
+});
+
+test("配置文件路径可覆盖", () => {
+  assert.equal(resolveConfigFile(), configFile);
+});
+
+test("默认用配置文件里的 defaultEnvironment", () => {
+  const config = loadConfig([]);
+  assert.equal(config.env, "sit");
+  assert.deepEqual(config.baseUrls, ["http://10.1.1.197:8081"]);
+});
+
+test("--env 从用户配置里取，支持多地址", () => {
+  const config = loadConfig(["--env", "prd"]);
+  assert.equal(config.env, "prd");
+  assert.deepEqual(config.baseUrls, [
+    "http://10.32.30.208:8081",
+    "http://10.32.30.209:8081",
+  ]);
+});
+
+test("未知环境直接报错并提示怎么配", () => {
+  assert.throws(() => loadConfig(["--env", "pro"]), /未知环境/);
+  assert.throws(() => loadConfig(["--env", "pro"]), /config\.json/);
+});
+
+test("--base-url 优先级高于 --env", () => {
+  const config = loadConfig(["--env", "prd", "--base-url", "http://example.com:8081"]);
+  assert.deepEqual(config.baseUrls, ["http://example.com:8081"]);
+});
+
+test("--base-url 支持逗号分隔多节点", () => {
+  const config = loadConfig([
+    "--base-url",
+    "http://a:8081, http://b:8081/ ,",
+  ]);
+  assert.deepEqual(config.baseUrls, ["http://a:8081", "http://b:8081"]);
+});
+
+test("未指定 --base-url 时环境标识跟随实际环境", () => {
+  const config = loadConfig(["--base-url", "http://example.com:8081"]);
+  assert.equal(config.env, "custom");
+});
+
+test("传输方式归一化", () => {
+  assert.equal(normalizeTransport("SSE"), "sse");
+  assert.equal(normalizeTransport(" http "), "http");
+  assert.throws(() => normalizeTransport("grpc"), /未知传输方式/);
+});
+
+test("默认 stdio 传输", () => {
+  const config = loadConfig([]);
+  assert.equal(config.transport, "stdio");
+});
+
+test("HTTP 模式必须配置访问令牌", () => {
+  assert.throws(
+    () => loadConfig(["--transport", "sse"]),
+    /必须配置访问令牌/,
+  );
+  const config = loadConfig(["--transport", "sse", "--auth-token", "secret"]);
+  assert.equal(config.transport, "sse");
+  assert.equal(config.authToken, "secret");
+  assert.equal(config.httpPath, "/sse");
+});
+
+test("http 传输默认端点是 /mcp", () => {
+  const config = loadConfig(["--transport", "http", "--auth-token", "secret"]);
+  assert.equal(config.httpPath, "/mcp");
+});
+
+test("HTTP 监听参数可覆盖", () => {
+  const config = loadConfig([
+    "--transport",
+    "sse",
+    "--auth-token",
+    "secret",
+    "--http-port",
+    "8088",
+    "--http-host",
+    "0.0.0.0",
+  ]);
+  assert.equal(config.httpPort, 8088);
+  assert.equal(config.httpHost, "0.0.0.0");
+});
+
+test("地址拆分工具", () => {
+  assert.deepEqual(splitBaseUrls("http://a:8081"), ["http://a:8081"]);
+  assert.deepEqual(splitBaseUrls(" , "), []);
+});
+
+fs.rmSync(tmpDir, { recursive: true, force: true });
+
+if (process.exitCode) {
+  console.error("\n有用例失败 ❌");
+} else {
+  console.log(`\n全部通过（${passed} 个用例）✅`);
+}

package/test/e2e-published.mjs

@@ -0,0 +1,118 @@
+/**
+ * 已发布包的端到端验证
+ *
+ * <p>用公网 npm 上的 @leadfund/lead-mcp（而不是本地源码）拉起 MCP Server，
+ * 打到 sit 环境，走完整协议握手，确认「公网安装 → MCP → 275 → MES」整条链路通。</p>
+ *
+ * <p>运行：node test/e2e-published.mjs [mobile]</p>
+ */
+
+import { spawn } from "node:child_process";
+import os from "node:os";
+
+const MOBILE = process.argv[2] ?? "13800000000";
+const ENV = process.env.LEAD_MCP_ENV ?? "sit";
+const OPERATOR = process.env.LEAD_MCP_OPERATOR ?? "dhh_6234";
+
+function start() {
+  // 直接用 npx 拉公网上的包，和 Claude Code 实际执行的命令一致
+  const child = spawn(
+    "npx",
+    ["-y", "--registry=https://registry.npmjs.org/", "@leadfund/lead-mcp", "--env", ENV],
+    {
+      stdio: ["pipe", "pipe", "pipe"],
+      // 不能在包自己的源码目录里跑：npx 会把本地 package.json 当作「已安装」，
+      // 直接去找 node_modules/.bin/lead-mcp，而它不是自己的依赖，软链不存在 → exit 127
+      cwd: os.tmpdir(),
+    },
+  );
+
+  const pending = new Map();
+  let buffer = "";
+  let stderr = "";
+
+  child.stdout.on("data", (chunk) => {
+    buffer += chunk.toString();
+    let index;
+    while ((index = buffer.indexOf("\n")) >= 0) {
+      const line = buffer.slice(0, index).trim();
+      buffer = buffer.slice(index + 1);
+      if (!line) continue;
+      const message = JSON.parse(line);
+      const resolver = pending.get(message.id);
+      if (resolver) {
+        pending.delete(message.id);
+        resolver(message);
+      }
+    }
+  });
+  child.stderr.on("data", (chunk) => {
+    stderr += chunk.toString();
+  });
+
+  let nextId = 1;
+  function send(method, params) {
+    const id = nextId++;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        pending.delete(id);
+        reject(new Error(`超时: ${method}\n${stderr}`));
+      }, 60000);
+      pending.set(id, (response) => {
+        clearTimeout(timer);
+        resolve(response);
+      });
+      child.stdin.write(
+        `${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`,
+      );
+    });
+  }
+  function notify(method, params) {
+    child.stdin.write(
+      `${JSON.stringify({ jsonrpc: "2.0", method, params })}\n`,
+    );
+  }
+  return { child, send, notify, getStderr: () => stderr };
+}
+
+const mcp = start();
+try {
+  const init = await mcp.send("initialize", {
+    protocolVersion: "2024-11-05",
+    capabilities: {},
+    clientInfo: { name: "e2e-published", version: "0.0.1" },
+  });
+  console.log("✓ initialize", JSON.stringify(init.result.serverInfo));
+  mcp.notify("notifications/initialized");
+
+  const list = await mcp.send("tools/list", {});
+  console.log(
+    "✓ tools/list",
+    list.result.tools.map((t) => t.name).join(", "),
+  );
+
+  const call = await mcp.send("tools/call", {
+    name: "dmmp_query_account",
+    arguments: { mobile: MOBILE },
+  });
+  console.log("✓ tools/call");
+  console.log(
+    call.result.content
+      .map((c) => c.text)
+      .join("\n")
+      .split("\n")
+      .map((l) => `    ${l}`)
+      .join("\n"),
+  );
+
+  const err = mcp.getStderr();
+  const envLine = err.split("\n").find((l) => l.includes("环境="));
+  if (envLine) {
+    console.log("✓ 启动日志", envLine.replace("[lead-mcp] INFO ", ""));
+  }
+} catch (error) {
+  console.error("端到端验证失败:", error.message);
+  process.exitCode = 1;
+} finally {
+  mcp.child.kill();
+}

package/test/http-curl-demo.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# 用 curl 完整走一遍 MCP over SSE 协议（不依赖任何 MCP 客户端）
+#
+# 用法：
+#   ./test/http-curl-demo.sh [端口] [令牌] [手机号]
+#
+# 默认：端口 3100、令牌 demo-token-abc、手机号 13800000000
+
+set -euo pipefail
+
+PORT="${1:-3100}"
+TOKEN="${2:-demo-token-abc}"
+MOBILE="${3:-13800000000}"
+BASE="http://127.0.0.1:${PORT}"
+STREAM="$(mktemp)"
+trap 'rm -f "$STREAM"' EXIT
+
+echo "▶ 1) 建立 SSE 流并取 sessionId"
+curl -s -N --max-time 20 -H "Authorization: Bearer ${TOKEN}" "${BASE}/sse" > "$STREAM" &
+CURL_PID=$!
+
+SESSION_ID=""
+for _ in $(seq 1 50); do
+  SESSION_ID=$(grep -o 'sessionId=[0-9a-f-]*' "$STREAM" 2>/dev/null | head -1 | cut -d= -f2 || true)
+  [ -n "$SESSION_ID" ] && break
+  sleep 0.2
+done
+[ -z "$SESSION_ID" ] && { echo "✗ 未能取得 sessionId"; kill $CURL_PID 2>/dev/null || true; exit 1; }
+echo "  sessionId=${SESSION_ID}"
+
+echo "▶ 2) initialize"
+curl -s -X POST "${BASE}/messages?sessionId=${SESSION_ID}" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl-demo","version":"0.0.1"}}}' \
+  > /dev/null
+sleep 1
+grep -o '"serverInfo":{[^}]*}' "$STREAM" | head -1 | sed 's/^/  /' || echo "  (未读到 initialize 响应)"
+
+echo "▶ 3) notifications/initialized"
+curl -s -X POST "${BASE}/messages?sessionId=${SESSION_ID}" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}' > /dev/null
+sleep 1
+
+echo "▶ 4) tools/list"
+curl -s -X POST "${BASE}/messages?sessionId=${SESSION_ID}" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' > /dev/null
+sleep 1
+grep -o '"name":"dmmp_query_account"' "$STREAM" | head -1 | sed 's/^/  工具: /' || echo "  (未读到 tools/list 响应)"
+
+echo "▶ 5) tools/call  mobile=${MOBILE}"
+curl -s -X POST "${BASE}/messages?sessionId=${SESSION_ID}" \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d "{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{\"name\":\"dmmp_query_account\",\"arguments\":{\"mobile\":\"${MOBILE}\"}}}" > /dev/null
+sleep 2
+grep -o '"text":"[^"]*"' "$STREAM" | tail -1 | sed 's/^/  /' || echo "  (未读到 tools/call 响应)"
+echo "  --- 原始帧 ---"
+grep -A1 '"id":3' "$STREAM" | tail -1 | sed 's/^/  /' || true
+
+kill $CURL_PID 2>/dev/null || true
+echo
+echo "✓ 完成"