@leadfund/lead-mcp 0.0.0-stage → 202610.1.0

package/README.md

@@ -1,3 +1,188 @@
-# Temporary Holding Version
+# lead-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+利得零售系统 MCP Server —— 客户账户信息**只读**查询。
+
+以 stdio 传输向 MCP Client（Claude Code、Claude Desktop 等）暴露工具，
+工具的真实实现在 dmmp-system（系统 id 275）的 `/ai/**` 接口上，本项目只做协议适配。
+
+- 纯 JavaScript（ESM）+ JSDoc，**无构建步骤**，装完即用
+- 只提供只读工具，不含任何写操作
+- 日志一律走 stderr（stdio 传输下 stdout 是 JSON-RPC 通道）
+
+## 工具
+
+| 工具 | 说明 |
+|---|---|
+| `dmmp_query_account` | 根据手机号或身份证号查询客户账户信息，网点号可选 |
+
+**入参**
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `mobile` | string | 与 `idNo` / `memberId` 至少提供一项 | 完整手机号，11 位且以 1 开头 |
+| `idNo` | string | 与 `mobile` / `memberId` 至少提供一项 | 完整身份证号，15 位或 18 位 |
+| `ownerNet` | string | 否 | 网点号，传入后仅返回该网点下的客户 |
+| `memberId` | string | 否 | 会员号，命中多个会员时确认后带上再查 |
+
+**返回**：会员 id、姓名、手机号（脱敏）、证件类型、证件号码（脱敏）、证件有效期。
+
+### 一号多会员
+
+一个手机号/证件号可能对应多个会员（MES 的 `T_MES_BASE.REG_ACCOUNT` 不唯一）。
+
+命中多个时后端只返回候选会员号，**不返回任何档案字段**，避免臆断。
+本 Server 会转成一段明确的确认提示：
+
+```
+该手机号/证件号在系统中匹配到多个会员，无法确定具体是哪一个。
+请让用户确认需要查询哪一个会员，然后带上 memberId 重新查询，不要自行选择其中一个。
+候选会员号：
+- M20001
+- M20002
+```
+
+### 网点号的语义
+
+传入网点号后结果唯一 —— 手机号/证件号在该网点下要么查到唯一账户、要么查不到。
+查不到时的提示会区分两种情况：
+
+| 场景 | 提示 |
+|---|---|
+| 未传网点号 | 未查询到该客户信息。 |
+| 传了网点号 | 未查询到该客户信息。该手机号/证件号在网点 {ownerNet} 下没有账户，可能该客户不属于该网点。 |
+
+### 错误语义（重要）
+
+| 场景 | MCP 返回 | 模型应有的行为 |
+|---|---|---|
+| 查不到客户 | `content`，正文为「未查询到该客户信息。」 | 直接回答未查询到，**禁止推测** |
+| 命中多个会员 | `content`，正文为候选会员号清单 | 请用户确认后带 `memberId` 重查，**不要自行挑一个** |
+| 参数不合法 | `isError: true` | 向用户澄清需要手机号、身份证号或会员号 |
+| 接口失败 / 超时 | `isError: true` | 向用户说明查询失败，不要编造数据 |
+
+「查不到」和「命中多个」刻意**不**作为错误返回：一旦标记成错误，模型会认为工具故障并自行编造客户资产。
+
+## 安装
+
+```bash
+npm install
+```
+
+发布到私有 registry 后即可用 `npx` 直接拉起，无需本地安装。
+
+## 接入 Claude Code
+
+```bash
+claude mcp add-json lead-mcp '{
+  "command": "npx",
+  "args": ["-y", "@leadfund/lead-mcp", "--env", "sit", "--operator", "E10086"]
+}'
+```
+
+### 环境
+
+| 环境 | 服务地址 |
+|---|---|
+| `local` | `http://localhost:8081` |
+| `sit` | `http://10.1.1.197:8081` |
+| `prd` | `http://10.32.30.208:8081`、`http://10.32.30.209:8081` |
+
+- 默认环境是 `local` —— 打错环境名不至于直接连到生产。
+- **未知环境名直接报错退出**，不会静默回落到默认环境。
+- 生产是双节点：只有网络错误、超时、5xx 这类「节点不可用」才会自动切到下一个节点；
+  查不到、参数错误这类业务失败不切换，直接返回。
+- 上次成功的节点会被记住并优先使用，避免每次都从第一个节点试探。
+
+配置项：
+
+| 配置 | 来源 | 默认值 |
+|---|---|---|
+| `--env` / `LEAD_MCP_ENV` | 命令行 / 环境变量 | `local` |
+| `--base-url` / `LEAD_MCP_BASE_URL` | 命令行 / 环境变量 | 无（用 `--env` 的地址） |
+| `--timeout` / `LEAD_MCP_TIMEOUT_MS` | 命令行 / 环境变量 | `10000` |
+| `--token` / `LEAD_MCP_TOKEN` | 命令行 / 环境变量 | 无 |
+| `--operator` / `LEAD_MCP_OPERATOR` | 命令行 / 环境变量 | 无配置时退化为操作系统账号 |
+
+> `--base-url` 保留，且**优先级高于 `--env`**，逗号分隔多个地址时同样按顺序故障转移：
+> `--base-url http://a:8081,http://b:8081`
+
+> 密钥类配置请走环境变量，不要写进 MCP 配置文件——`claude mcp add-json` 的内容会明文落到 `~/.claude.json`。
+
+### 调用方身份与环境
+
+MCP 协议本身不传递登录身份，本 Server 会把操作人信息与环境标识放进请求头带给后端：
+
+| 请求头 | 来源 | 用途 |
+|---|---|---|
+| `X-Operator` | `--operator` / `LEAD_MCP_OPERATOR`，未配置时为操作系统账号 | 服务端限流维度 + 审计记录 |
+| `X-Operator-Os` | 操作系统账号（`os.userInfo().username`） | 便于后端把 OS 账号二次解析成工号 |
+| `X-Lead-Env` | 当前环境（`local` / `sit` / `prd` / `custom`） | 审计里区分查询打在哪个环境 |
+
+**建议显式配置工号**，否则审计里只能看到操作系统账号：
+
+```bash
+claude mcp add-json lead-mcp '{
+  "command": "npx",
+  "args": ["-y", "@leadfund/lead-mcp", "--env", "sit", "--operator", "E10086"]
+}'
+```
+
+## 本地调试
+
+```bash
+node src/cli.js --help
+
+# 可视化调试
+npx @modelcontextprotocol/inspector node src/cli.js --base-url http://127.0.0.1:8081
+```
+
+### 测试
+
+```bash
+npm test        # 配置解析单元测试 + 端到端冒烟测试
+```
+
+- `test/config.test.mjs` —— 环境选择、地址优先级、未知环境报错等纯逻辑
+- `test/smoke.mjs` —— 拉起 mock 的 dmmp-system，再以子进程方式拉起真实的 MCP Server，
+  走完整协议握手，覆盖命中 / 未命中 / 多会员 / 参数非法 / 下游异常 / 操作人透传 /
+  环境透传 / **节点故障转移**
+
+## 与后端的关系
+
+```
+Claude Code
+    │ stdio (JSON-RPC)
+    ▼
+lead-mcp (Node/JS)                       ← 本项目
+    │ HTTP POST /ai/account/query
+    ▼
+dmmp-system (系统 id 275)                ← 业务真源：鉴权、白名单、脱敏、审计
+    │ Dubbo
+    ▼
+MES MemberQueryFacade
+```
+
+工具清单、参数 Schema、脱敏规则以 dmmp-system 侧
+`dmmp-system/src/main/java/com/lead/system/controller/ai/README.md` 为准。
+
+## 目录结构
+
+```
+lead-mcp/
+├── package.json
+├── src/
+│   ├── cli.js       # 入口，stdio 传输
+│   ├── server.js    # MCP Server 与工具注册
+│   ├── client.js    # dmmp-system HTTP 客户端
+│   ├── config.js    # 配置解析
+│   └── logger.js    # stderr 日志
+└── test/
+    └── smoke.mjs    # 端到端冒烟测试
+```
+
+## 约束
+
+- **只读**：本 Server 只提供查询工具，不含任何写操作。
+- **日志走 stderr**：写 stdout 会破坏 JSON-RPC 协议。
+- **脱敏在服务端完成**：本项目不做脱敏，直接透传后端已脱敏的结果。
+- **限流在服务端做**：客户端侧计数可被绕过，服务端按「操作人」和「查询目标」两个维度限流。

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@leadfund/lead-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "202610.1.0",
+  "description": "利得零售系统 MCP Server —— 客户账户信息只读查询",
+  "type": "module",
+  "bin": {
+    "lead-mcp": "./src/cli.js"
+  },
+  "main": "./src/cli.js",
+  "files": [
+    "src",
+    "test",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node src/cli.js",
+    "inspector": "npx @modelcontextprotocol/inspector node src/cli.js",
+    "test": "node test/config.test.mjs && node test/smoke.mjs",
+    "smoke": "node test/smoke.mjs",
+    "release": "npm test && npm publish --registry=https://registry.npmjs.org/ --access public"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "leadbank",
+    "lead-mcp"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^3.25.76 || ^4.0.0"
+  }
+}

package/src/cli.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { USAGE, isHelpRequested, loadConfig } from "./config.js";
+import { logger } from "./logger.js";
+import { createServer } from "./server.js";
+
+async function main() {
+  if (isHelpRequested()) {
+    // --help 是给人看的，走 stdout；正常运行期 stdout 属于 JSON-RPC 通道
+    process.stdout.write(USAGE);
+    return;
+  }
+
+  const config = loadConfig();
+  const server = createServer(config);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  logger.info(
+    `已启动，环境=${config.env}，服务地址=${config.baseUrls.join(", ")}，超时=${config.timeoutMs}ms`,
+  );
+}
+
+main().catch((error) => {
+  logger.error("启动失败", error);
+  process.exit(1);
+});

package/src/client.js

@@ -0,0 +1,182 @@
+import { logger } from "./logger.js";
+
+/**
+ * dmmp-system 账户信息查询接口
+ *
+ * <p>对应 dmmp-system 的 {@code POST /ai/account/query}，
+ * 返回 {@code DataResult<AiMcpAccountResponse>}。</p>
+ *
+ * <p>生产环境是双节点，这里按地址顺序做故障转移：只有网络错误、超时、
+ * 5xx 这类「节点不可用」才会切到下一个节点；业务失败（查不到、参数错误）
+ * 直接返回，不做无谓的重试。</p>
+ */
+
+/**
+ * @typedef {Object} AccountProfile
+ * @property {boolean} [found] 是否查询到客户
+ * @property {string} [memberId] 会员 id，命中多个会员时为空
+ * @property {string[]} [memberIdList] 命中的会员 id 列表，长度大于 1 表示命中多个会员
+ * @property {string} [name] 姓名
+ * @property {string} [mobile] 手机号
+ * @property {string} [mobileFormat] 手机号（脱敏）
+ * @property {string} [idType] 证件类型
+ * @property {string} [idTypeFormat] 证件类型（中文名）
+ * @property {string} [idNo] 证件号码
+ * @property {string} [idNoFormat] 证件号码（脱敏）
+ * @property {string} [idValidity] 证件有效期
+ * @property {string} [idValidityFormat] 证件有效期（格式化）
+ */
+
+/**
+ * @typedef {Object} AccountQueryParams
+ * @property {string} [mobile] 完整手机号
+ * @property {string} [idNo] 完整身份证号
+ * @property {string} [ownerNet] 网点号，可选
+ * @property {string} [memberId] 会员号，命中多个会员时确认后带上再查
+ */
+
+/**
+ * @typedef {Object} ApiResult
+ * @property {number} code
+ * @property {string} [message]
+ * @property {AccountProfile} [data]
+ */
+
+/**
+ * 上一次成功的服务地址，下次优先尝试
+ *
+ * <p>避免每次都从第一个节点开始试探，也避免第一个节点故障时把
+ * 故障转移的额外延迟带到每次调用上。</p>
+ */
+let preferredBaseUrl = null;
+
+/**
+ * 接口调用异常
+ */
+export class LeadApiError extends Error {
+  /**
+   * @param {string} message
+   * @param {string} [detail]
+   * @param {boolean} [failoverable] 是否可以切换到下一个节点重试
+   */
+  constructor(message, detail, failoverable = false) {
+    super(message);
+    this.name = "LeadApiError";
+    /** @type {string|undefined} */
+    this.detail = detail;
+    /** @type {boolean} */
+    this.failoverable = failoverable;
+  }
+}
+
+/**
+ * 调整地址顺序，把上次成功的节点放到最前面
+ *
+ * @param {string[]} baseUrls 地址列表
+ * @returns {string[]} 调整后的地址列表
+ */
+function orderBaseUrls(baseUrls) {
+  if (!preferredBaseUrl || !baseUrls.includes(preferredBaseUrl)) {
+    return baseUrls;
+  }
+  return [preferredBaseUrl, ...baseUrls.filter((url) => url !== preferredBaseUrl)];
+}
+
+/**
+ * 查询客户账户信息
+ *
+ * @param {import("./config.js").LeadMcpConfig} config
+ * @param {AccountQueryParams} params
+ * @returns {Promise<AccountProfile>}
+ * @throws {LeadApiError} 所有节点都不可用或接口返回业务错误
+ */
+export async function queryAccount(config, params) {
+  const urls = orderBaseUrls(config.baseUrls);
+  let lastError = null;
+
+  for (const baseUrl of urls) {
+    try {
+      const profile = await requestOnce(config, baseUrl, params);
+      preferredBaseUrl = baseUrl;
+      return profile;
+    } catch (error) {
+      if (!(error instanceof LeadApiError) || !error.failoverable) {
+        throw error;
+      }
+      lastError = error;
+      logger.warn("节点不可用，尝试下一个", { baseUrl, error: error.message });
+    }
+  }
+
+  throw (
+    lastError ??
+    new LeadApiError("没有可用的服务地址", undefined, true)
+  );
+}
+
+/**
+ * 向单个节点发起一次查询
+ *
+ * @param {import("./config.js").LeadMcpConfig} config
+ * @param {string} baseUrl 服务地址
+ * @param {AccountQueryParams} params 查询参数
+ * @returns {Promise<AccountProfile>}
+ */
+async function requestOnce(config, baseUrl, params) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), config.timeoutMs);
+
+  /** @type {Record<string, string>} */
+  const headers = { "Content-Type": "application/json" };
+  if (config.token) {
+    headers.Authorization = `Bearer ${config.token}`;
+  }
+  // 调用方身份：服务端据此限流与审计，MCP 协议本身不传递登录身份
+  if (config.operator) {
+    headers["X-Operator"] = config.operator;
+  }
+  if (config.operatorOs) {
+    headers["X-Operator-Os"] = config.operatorOs;
+  }
+  // 环境标识：服务端审计需要区分查询打在哪个环境（生产数据尤其敏感）
+  headers["X-Lead-Env"] = config.env;
+
+  try {
+    const response = await fetch(`${baseUrl}/ai/account/query`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(params),
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      // 5xx 视为节点故障可切换，4xx 是请求本身有问题，换节点也没用
+      const failoverable = response.status >= 500;
+      throw new LeadApiError(
+        `接口返回 HTTP ${response.status}`,
+        `${response.status} ${response.statusText}`,
+        failoverable,
+      );
+    }
+
+    const body = /** @type {ApiResult} */ (await response.json());
+    if (body.code !== 0) {
+      throw new LeadApiError(body.message || `接口返回错误码 ${body.code}`, `code=${body.code}`, false);
+    }
+    return body.data ?? {};
+  } catch (error) {
+    if (error instanceof LeadApiError) {
+      throw error;
+    }
+    if (error instanceof Error && error.name === "AbortError") {
+      throw new LeadApiError(`请求超时（${config.timeoutMs}ms）`, undefined, true);
+    }
+    throw new LeadApiError(
+      `请求 dmmp-system 失败：${error instanceof Error ? error.message : String(error)}`,
+      undefined,
+      true,
+    );
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/config.js

@@ -0,0 +1,194 @@
+import os from "node:os";
+
+/**
+ * 运行配置
+ *
+ * <p>配置来源优先级：命令行参数 &gt; 环境变量 &gt; 默认值。</p>
+ */
+
+/**
+ * @typedef {Object} LeadMcpConfig
+ * @property {string} env 环境标识：local / sit / prd / custom
+ * @property {string[]} baseUrls dmmp-system（系统 id 275）服务地址列表，多个时按顺序故障转移
+ * @property {number} timeoutMs 单次请求超时（毫秒）
+ * @property {string|undefined} token 访问令牌，可选
+ * @property {string|undefined} operator 操作人标识（工号），用于服务端限流与审计
+ * @property {string|undefined} operatorOs 操作人操作系统账号
+ */
+
+/**
+ * 各环境的服务地址
+ *
+ * <p>生产为双节点，客户端会按顺序故障转移，避免单点故障导致工具不可用。</p>
+ */
+export const ENVIRONMENTS = {
+  local: {
+    label: "本地开发",
+    baseUrls: ["http://localhost:8081"],
+  },
+  sit: {
+    label: "集成测试",
+    baseUrls: ["http://10.1.1.197:8081"],
+  },
+  prd: {
+    label: "生产",
+    baseUrls: ["http://10.32.30.208:8081", "http://10.32.30.209:8081"],
+  },
+};
+
+/**
+ * 默认环境
+ *
+ * <p>默认走 local：打错环境名不至于直接连到生产。</p>
+ */
+export const DEFAULT_ENV = "local";
+
+export const DEFAULT_TIMEOUT_MS = 10000;
+
+export const USAGE = `lead-mcp —— 利得零售系统 MCP Server
+
+用法：
+  lead-mcp [选项]
+
+选项：
+  --env <环境>         目标环境，默认 ${DEFAULT_ENV}
+                       ${Object.entries(ENVIRONMENTS)
+                         .map(([name, env]) => `${name}(${env.label}) ${env.baseUrls.join(",")}`)
+                         .join("\n                       ")}
+                       也可用环境变量 LEAD_MCP_ENV；未知环境名会直接报错退出
+  --base-url <url>     直接指定服务地址，逗号分隔多个时按顺序故障转移
+                       优先级高于 --env，也可用环境变量 LEAD_MCP_BASE_URL
+  --timeout <ms>       单次请求超时毫秒数，默认 ${DEFAULT_TIMEOUT_MS}
+                       也可用环境变量 LEAD_MCP_TIMEOUT_MS
+  --token <token>      访问令牌，可选，也可用环境变量 LEAD_MCP_TOKEN
+  --operator <工号>    操作人标识，用于服务端限流与审计
+                       也可用环境变量 LEAD_MCP_OPERATOR；未配置时退化为操作系统账号
+  -h, --help           查看帮助
+`;
+
+/**
+ * 解析操作人的操作系统账号
+ *
+ * @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} name 环境名
+ * @returns {string} 环境名
+ * @throws {Error} 环境名非法
+ */
+export function normalizeEnv(name) {
+  const env = String(name).trim().toLowerCase();
+  if (!ENVIRONMENTS[env]) {
+    throw new Error(
+      `未知环境 "${name}"，可选值：${Object.keys(ENVIRONMENTS).join(" / ")}`,
+    );
+  }
+  return env;
+}
+
+/**
+ * 解析服务地址列表
+ *
+ * @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[]} [argv]
+ * @returns {LeadMcpConfig}
+ * @throws {Error} 环境名非法
+ */
+export function loadConfig(argv = process.argv.slice(2)) {
+  const args = parseArgs(argv);
+
+  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";
+
+  // 环境名非法直接失败：静默回落到默认环境可能把请求打到错误的环境
+  const env =
+    rawEnv && rawEnv !== "true"
+      ? normalizeEnv(rawEnv)
+      : hasBaseUrl
+        ? "custom"
+        : DEFAULT_ENV;
+
+  // 显式指定的地址优先级更高，可直接指定多个做故障转移
+  const baseUrls = hasBaseUrl ? splitBaseUrls(rawBaseUrl) : ENVIRONMENTS[env].baseUrls;
+  if (baseUrls.length === 0) {
+    throw new Error("没有可用的服务地址，请检查 --env / --base-url 配置");
+  }
+
+  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(),
+  };
+}
+
+/**
+ * 是否请求帮助
+ *
+ * @param {string[]} [argv]
+ * @returns {boolean}
+ */
+export function isHelpRequested(argv = process.argv.slice(2)) {
+  return argv.includes("--help") || argv.includes("-h");
+}

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

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,98 @@
+/**
+ * 配置解析单元测试
+ *
+ * <p>运行：node test/config.test.mjs</p>
+ */
+
+import assert from "node:assert/strict";
+import { ENVIRONMENTS, loadConfig, normalizeEnv, 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;
+  }
+}
+
+test("环境名归一化", () => {
+  assert.equal(normalizeEnv("PRD"), "prd");
+  assert.equal(normalizeEnv(" sit "), "sit");
+});
+
+test("未知环境名直接报错，不静默回落", () => {
+  assert.throws(() => normalizeEnv("pro"), /未知环境/);
+  assert.throws(() => normalizeEnv(""), /未知环境/);
+});
+
+test("默认环境是 local", () => {
+  const config = loadConfig([]);
+  assert.equal(config.env, "local");
+  assert.deepEqual(config.baseUrls, ENVIRONMENTS.local.baseUrls);
+});
+
+test("--env 选择环境", () => {
+  const config = loadConfig(["--env", "sit"]);
+  assert.equal(config.env, "sit");
+  assert.deepEqual(config.baseUrls, ["http://10.1.1.197:8081"]);
+});
+
+test("生产环境带两个节点", () => {
+  const config = loadConfig(["--env", "prd"]);
+  assert.equal(config.env, "prd");
+  assert.equal(config.baseUrls.length, 2);
+  assert.deepEqual(config.baseUrls, [
+    "http://10.32.30.208:8081",
+    "http://10.32.30.209:8081",
+  ]);
+});
+
+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 时环境标识为 custom", () => {
+  const config = loadConfig(["--base-url", "http://example.com:8081"]);
+  assert.equal(config.env, "custom");
+});
+
+test("环境变量优先于默认值", () => {
+  process.env.LEAD_MCP_ENV = "sit";
+  try {
+    const config = loadConfig([]);
+    assert.equal(config.env, "sit");
+  } finally {
+    delete process.env.LEAD_MCP_ENV;
+  }
+});
+
+test("地址拆分工具", () => {
+  assert.deepEqual(splitBaseUrls("http://a:8081"), ["http://a:8081"]);
+  assert.deepEqual(splitBaseUrls(" , "), []);
+});
+
+if (process.exitCode) {
+  console.error("\n有用例失败 ❌");
+} else {
+  console.log(`\n全部通过（${passed} 个用例）✅`);
+}

package/test/smoke.mjs

@@ -0,0 +1,348 @@
+/**
+ * 端到端冒烟测试
+ *
+ * <p>起一个 mock 的 dmmp-system，再以子进程方式拉起真实的 MCP Server，
+ * 走完整的 MCP 协议握手（initialize → tools/list → tools/call），
+ * 校验工具清单、命中、未命中、参数非法、下游异常五种场景的返回语义。</p>
+ *
+ * <p>运行：node test/smoke.mjs</p>
+ */
+
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import assert from "node:assert/strict";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLI = path.join(__dirname, "..", "src", "cli.js");
+
+/**
+ * mock 的 dmmp-system
+ */
+function startMockBackend() {
+  const state = { lastHeaders: null };
+  const server = createServer((req, res) => {
+    state.lastHeaders = req.headers;
+    let body = "";
+    req.on("data", (chunk) => {
+      body += chunk;
+    });
+    req.on("end", () => {
+      const params = body ? JSON.parse(body) : {};
+      res.setHeader("Content-Type", "application/json");
+
+      if (params.mobile === "13800000000") {
+        res.end(
+          JSON.stringify({
+            code: 0,
+            message: "接口调用成功",
+            data: {
+              found: true,
+              memberId: "M10086",
+              name: "张*",
+              mobile: "13800000000",
+              mobileFormat: "138****0000",
+              idType: "01",
+              idTypeFormat: "身份证",
+              idNo: "310101199001011234",
+              idNoFormat: "310101********1234",
+              idValidity: "9999-12-31",
+              idValidityFormat: "长期有效",
+            },
+          }),
+        );
+        return;
+      }
+      if (params.memberId === "M20001") {
+        // 带上 memberId 复查：唯一命中
+        res.end(
+          JSON.stringify({
+            code: 0,
+            message: "接口调用成功",
+            data: {
+              found: true,
+              memberId: "M20001",
+              memberIdList: ["M20001"],
+              name: "李*",
+              mobileFormat: "136****0000",
+              idTypeFormat: "身份证",
+              idNoFormat: "310101********5678",
+              idValidityFormat: "长期有效",
+            },
+          }),
+        );
+        return;
+      }
+      if (params.mobile === "13600000000") {
+        // 一个手机号对应多个会员：后端只返回候选会员号，不返回档案
+        res.end(
+          JSON.stringify({
+            code: 0,
+            message: "接口调用成功",
+            data: { found: true, memberIdList: ["M20001", "M20002"] },
+          }),
+        );
+        return;
+      }
+      if (params.mobile === "13900000000") {
+        res.statusCode = 500;
+        res.end(JSON.stringify({ code: 500, message: "下游服务异常" }));
+        return;
+      }
+      // 未命中
+      res.end(JSON.stringify({ code: 0, message: "接口调用成功", data: { found: false } }));
+    });
+  });
+  return new Promise((resolve) => {
+    server.listen(0, "127.0.0.1", () => {
+      resolve({ server, port: server.address().port, state });
+    });
+  });
+}
+
+/**
+ * 以 stdio 方式拉起 MCP Server，并提供 JSON-RPC 调用能力
+ */
+function startMcpServer(baseUrl, extraArgs = []) {
+  const child = spawn(
+    process.execPath,
+    [CLI, "--base-url", baseUrl, "--operator", "E10086", ...extraArgs],
+    { stdio: ["pipe", "pipe", "pipe"] },
+  );
+
+  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;
+    nextId += 1;
+    const message = { jsonrpc: "2.0", id, method, params };
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        pending.delete(id);
+        reject(new Error(`请求超时: ${method}\n${stderr}`));
+      }, 10000);
+      pending.set(id, (response) => {
+        clearTimeout(timer);
+        resolve(response);
+      });
+      child.stdin.write(`${JSON.stringify(message)}\n`);
+    });
+  }
+
+  function notify(method, params) {
+    child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", method, params })}\n`);
+  }
+
+  return { child, send, notify, getStderr: () => stderr };
+}
+
+/**
+ * 取一个已被占用的端口（先监听再关闭），用来模拟不可用的节点
+ *
+ * @returns {Promise<number>} 端口
+ */
+async function getClosedPort() {
+  return new Promise((resolve) => {
+    const server = createServer();
+    server.listen(0, "127.0.0.1", () => {
+      const { port } = server.address();
+      server.close(() => resolve(port));
+    });
+  });
+}
+
+/**
+ * 故障转移：第一个节点不可用时自动切到第二个
+ */
+async function testFailover() {
+  const closedPort = await getClosedPort();
+  const { server: mock, port } = await startMockBackend();
+  const mcp = startMcpServer(`http://127.0.0.1:${closedPort},http://127.0.0.1:${port}`);
+
+  try {
+    const init = await mcp.send("initialize", {
+      protocolVersion: "2024-11-05",
+      capabilities: {},
+      clientInfo: { name: "smoke-test", version: "0.0.1" },
+    });
+    assert.equal(init.result.serverInfo.name, "lead-mcp");
+    mcp.notify("notifications/initialized");
+
+    const hit = await mcp.send("tools/call", {
+      name: "dmmp_query_account",
+      arguments: { mobile: "13800000000" },
+    });
+    assert.ok(!hit.result.isError, "首节点不可用时应自动切到第二个节点");
+    assert.ok(hit.result.content[0].text.includes("M10086"), "应命中第二个节点的数据");
+    console.log("✓ 节点故障转移（首个节点不可用 → 自动切换）");
+  } finally {
+    mcp.child.kill();
+    mock.close();
+  }
+}
+
+async function main() {
+  const { server: mock, port, state } = await startMockBackend();
+  const baseUrl = `http://127.0.0.1:${port}`;
+  const mcp = startMcpServer(baseUrl);
+
+  try {
+    // 1. initialize
+    const init = await mcp.send("initialize", {
+      protocolVersion: "2024-11-05",
+      capabilities: {},
+      clientInfo: { name: "smoke-test", version: "0.0.1" },
+    });
+    assert.equal(init.result.serverInfo.name, "lead-mcp", "serverInfo.name");
+    console.log("✓ initialize", JSON.stringify(init.result.serverInfo));
+    mcp.notify("notifications/initialized");
+
+    // 2. tools/list
+    const list = await mcp.send("tools/list", {});
+    const tools = list.result.tools;
+    assert.equal(tools.length, 1, "应当只有一个工具");
+    const tool = tools[0];
+    assert.equal(tool.name, "dmmp_query_account");
+    assert.ok(tool.description.includes("未查询到"), "描述里要写清未查询到的处理方式");
+    const props = tool.inputSchema.properties;
+    assert.ok(props.mobile && props.idNo && props.ownerNet, "参数应包含 mobile/idNo/ownerNet");
+    assert.equal(tool.inputSchema.required, undefined, "mobile/idNo 非必填，由服务端校验二者其一");
+    console.log("✓ tools/list", tool.name, JSON.stringify(tool.inputSchema.required ?? []));
+
+    // 3. 命中
+    const hit = await mcp.send("tools/call", {
+      name: "dmmp_query_account",
+      arguments: { mobile: "13800000000" },
+    });
+    const hitText = hit.result.content[0].text;
+    assert.ok(!hit.result.isError, "命中不应是错误");
+    assert.ok(hitText.includes("M10086"), "应返回会员id");
+    assert.ok(hitText.includes("138****0000"), "应返回脱敏手机号");
+    assert.ok(hitText.includes("310101********1234"), "应返回脱敏证件号");
+    assert.ok(hitText.includes("长期有效"), "应返回证件有效期");
+    console.log("✓ tools/call 命中\n", hitText.split("\n").map((l) => `    ${l}`).join("\n"));
+
+    // 4. 未命中：正常返回，不是错误
+    const miss = await mcp.send("tools/call", {
+      name: "dmmp_query_account",
+      arguments: { mobile: "13700000000" },
+    });
+    assert.ok(!miss.result.isError, "未命中不应标记为错误");
+    assert.equal(miss.result.content[0].text, "未查询到该客户信息。");
+    console.log("✓ tools/call 未命中（非错误）", miss.result.content[0].text);
+
+    // 5. 参数非法：缺少手机号、身份证号与会员号
+    const invalid = await mcp.send("tools/call", {
+      name: "dmmp_query_account",
+      arguments: { ownerNet: "0001" },
+    });
+    assert.equal(invalid.result.isError, true, "参数非法应为错误");
+    assert.ok(invalid.result.content[0].text.includes("至少"));
+    console.log("✓ tools/call 参数非法（isError）", invalid.result.content[0].text);
+
+    // 6. 下游异常：isError
+    const broken = await mcp.send("tools/call", {
+      name: "dmmp_query_account",
+      arguments: { mobile: "13900000000" },
+    });
+    assert.equal(broken.result.isError, true, "下游异常应为错误");
+    console.log("✓ tools/call 下游异常（isError）", broken.result.content[0].text);
+
+    // 7. 命中多个会员：不是错误，要列出候选会员号让用户确认
+    const multi = await mcp.send("tools/call", {
+      name: "dmmp_query_account",
+      arguments: { mobile: "13600000000" },
+    });
+    assert.ok(!multi.result.isError, "多会员命中不应标记为错误");
+    const multiText = multi.result.content[0].text;
+    assert.ok(multiText.includes("M20001"), "应列出候选会员号");
+    assert.ok(multiText.includes("M20002"), "应列出候选会员号");
+    assert.ok(multiText.includes("memberId"), "应提示用 memberId 重新查询");
+    console.log("✓ tools/call 多会员命中（非错误）\n" + multiText.split("\n").map((l) => `    ${l}`).join("\n"));
+
+    // 8. 指定网点却查不到：提示该客户不在该网点下
+    const missWithNet = await mcp.send("tools/call", {
+      name: "dmmp_query_account",
+      arguments: { mobile: "13700000000", ownerNet: "0001" },
+    });
+    assert.ok(!missWithNet.result.isError, "未命中不应标记为错误");
+    assert.ok(
+      missWithNet.result.content[0].text.includes("0001"),
+      "指定网点未命中时应说明是网点范围问题",
+    );
+    console.log("✓ tools/call 指定网点未命中", missWithNet.result.content[0].text);
+
+    // 9. 带上 memberId 复查：应命中唯一账户
+    const byMemberId = await mcp.send("tools/call", {
+      name: "dmmp_query_account",
+      arguments: { memberId: "M20001", mobile: "13600000000" },
+    });
+    assert.ok(!byMemberId.result.isError, "按 memberId 复查不应是错误");
+    assert.ok(byMemberId.result.content[0].text.includes("会员id：M20001"), "按 memberId 应命中唯一账户");
+    console.log("✓ tools/call 带 memberId 复查", byMemberId.result.content[0].text.split("\n")[0]);
+
+    // 10. 调用方身份必须随请求透传给后端（限流与审计依赖它）
+    const headers = state.lastHeaders ?? {};
+    assert.equal(headers["x-operator"], "E10086", "应透传操作人标识");
+    assert.ok(headers["x-operator-os"], "应透传操作人操作系统账号");
+    console.log(
+      "✓ 操作人身份透传",
+      `X-Operator=${headers["x-operator"]} X-Operator-Os=${headers["x-operator-os"]}`,
+    );
+
+    // 11. 环境标识必须随请求透传，服务端审计要能区分打在哪个环境
+    assert.equal(headers["x-lead-env"], "custom", "应透传环境标识");
+    console.log("✓ 环境标识透传", `X-Lead-Env=${headers["x-lead-env"]}`);
+
+    // 12. 日志必须走 stderr：stdout 全程只承载 JSON-RPC（上面的解析已经证明）
+    assert.ok(
+      mcp.getStderr().includes("[lead-mcp]"),
+      "日志应输出到 stderr",
+    );
+    assert.ok(
+      mcp.getStderr().includes("已启动"),
+      "启动日志应输出到 stderr",
+    );
+    console.log("✓ 日志输出位置 stderr（stdout 仅承载 JSON-RPC）");
+  } finally {
+    mcp.child.kill();
+    mock.close();
+  }
+
+  console.log("\n全部通过 ✅");
+}
+
+main()
+  .then(() => testFailover())
+  .then(() => {
+    console.log("故障转移用例通过 ✅");
+  })
+  .catch((error) => {
+    console.error("冒烟测试失败:", error);
+    process.exit(1);
+  });