@leadfund/lead-mcp 0.0.0-stage → 202610.2.0

package/README.md

@@ -1,3 +1,284 @@
-# 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 通道）
+
+## ⚠️ 使用前提
+
+**必须在公司网络或已连接 VPN 的环境下使用。**
+
+本包发布在公共 npm 上，任何人都能安装；但**后端 dmmp-system（275）部署在公司内网**，
+`10.1.1.197` / `10.32.30.208` / `10.32.30.209` 公网不可路由。
+
+- 包能正常下载安装 ✓
+- 但脱离内网后查询会超时失败（生产双节点会依次尝试后报错）
+
+包本身不含任何凭证，脱离内网也无法访问到客户数据。
+
+## 工具
+
+| 工具 | 说明 |
+|---|---|
+| `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
+
+### stdio 方式（本地 MCP Client）
+
+```bash
+claude mcp add-json lead-mcp '{
+  "command": "npx",
+  "args": ["-y", "--registry=https://registry.npmjs.org/", "@leadfund/lead-mcp", "--env", "sit"],
+  "env": {"LEAD_MCP_ENV": "sit"}
+}'
+```
+
+### 指定服务地址
+
+服务地址**不在包里**，由使用方指定。两种方式：
+
+**方式一：命令行参数（支持多个，逗号分隔）**
+
+```bash
+# 单个
+lead-mcp --base-url http://10.1.1.197:8081
+
+# 多个（按顺序故障转移，前一个不通自动切下一个）
+lead-mcp --base-url http://10.32.30.208:8081,http://10.32.30.209:8081
+```
+
+也可以用环境变量 `LEAD_MCP_BASE_URL`。**`--base-url` 优先级高于 `--env`。**
+
+**方式二：用户配置文件**（推荐，环境多时更清晰）
+
+默认路径 `~/.lead-mcp/config.json`，可用 `LEAD_MCP_CONFIG` 指定别处：
+
+```json
+{
+  "defaultEnvironment": "sit",
+  "environments": {
+    "local": ["http://localhost:8081"],
+    "sit": ["http://10.1.1.197:8081"],
+    "prd": ["http://10.32.30.208:8081", "http://10.32.30.209:8081"]
+  }
+}
+```
+
+之后用 `--env sit` / `--env prd` 引用；不写 `--env` 就用 `defaultEnvironment`。
+配置文件缺失时只有内置的 `local` 可用。
+
+```bash
+lead-mcp --env prd
+```
+
+### 为什么指定官方源
+
+```json
+"args": ["-y", "--registry=https://registry.npmjs.org/", "@leadfund/lead-mcp"]
+```
+
+npm 默认走淘宝源（`registry.npmmirror.com`），而**镜像源对新发布的包有同步延迟**——
+本包发布后淘宝源一度返回 404，导致 `npx` 装上却没有 bin，报 `lead-mcp: command not found`。
+显式指定官方源可以完全避开这个问题（官方源是源，镜像只是它的副本）。
+
+### operator 要不要配
+
+**默认不用配。** 没传 `--operator` 时，Server 会自动用操作系统账号（`os.userInfo().username`）作为操作人，
+限流维度和审计记录都有值。
+
+想要审计里直接是工号而不是机器账号，才需要显式配置：
+
+```json
+"args": ["-y", "--registry=https://registry.npmjs.org/", "@leadfund/lead-mcp", "--env", "sit", "--operator", "E10086"]
+```
+
+## HTTP(S) 模式（云端 MCP 服务）
+
+stdio 只适用于本地 MCP Client。要接入云端服务（如阿里云百炼），用 HTTP 模式。
+
+### 启动
+
+```bash
+# SSE 协议
+lead-mcp --transport sse --http-port 3100 --http-host 0.0.0.0 \
+  --auth-token <你的token> --env sit
+
+# Streamable HTTP 协议
+lead-mcp --transport http --http-port 3100 --http-host 0.0.0.0 \
+  --auth-token <你的token> --env sit
+```
+
+| 传输 | 端点 | 说明 |
+|---|---|---|
+| `stdio` | — | 默认，本地 MCP Client |
+| `sse` | `GET /sse` + `POST /messages?sessionId=` | 云端 MCP 常用 |
+| `http` | `POST /mcp` | Streamable HTTP，一站式 |
+
+**HTTP 模式下 `--auth-token` 必填**（没有令牌直接拒绝启动）—— 这套服务通常要暴露到公网，
+不设令牌等于不设防。客户端通过 `Authorization: Bearer <token>` 认证。
+`GET /health` 不鉴权，方便探活。
+
+### 百炼云端配置
+
+```json
+{
+  "type": "mcp",
+  "server_protocol": "sse",
+  "server_label": "lead-mcp",
+  "server_url": "https://你的域名/sse",
+  "headers": { "Authorization": "Bearer 你的token" }
+}
+```
+
+`server_protocol` 换成 `http` 时，`server_url` 用 `https://你的域名/mcp`。
+
+### 暴露到公网（ng 隧道示例）
+
+```bash
+lead-mcp --transport sse --http-host 0.0.0.0 --http-port 3100 \
+  --auth-token <你的token> --env sit
+
+# 另一个终端
+ng http 3100
+# 拿到 https://xxxx.ngrok-free.app
+```
+
+然后百炼里填 `https://xxxx.ngrok-free.app/sse` 和 Bearer 令牌。
+
+> ⚠️ 暴露到公网前请确认：
+> - `--auth-token` 已配置且足够随机
+> - 后端地址走 `--env` 指向内网，**不要**把 275 的直连地址暴露出去
+> - ng 隧道是临时地址，重启会变
+
+## 本地调试
+
+```bash
+node src/cli.js --help
+
+# 可视化调试
+npx @modelcontextprotocol/inspector node src/cli.js --base-url http://127.0.0.1:8081
+```
+
+### 测试
+
+```bash
+npm test        # 配置解析单元测试 + HTTP 端到端 + 冒烟测试
+node test/e2e-published.mjs [手机号]   # 用公网已发布的包跑真实链路（默认 sit）
+```
+
+> ⚠️ **在本包源码目录下不要用 `npx` 启动**：npx 会把本地 `package.json` 当作「已安装」，
+> 直接去找 `node_modules/.bin/lead-mcp`，而它不是自己的依赖、软链不存在，
+> 结果是 `sh: lead-mcp: command not found`（exit 127）。
+> 开发时用 `node src/cli.js`，或换到别的目录执行。
+
+- `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       # 入口，按 transport 分派
+│   ├── http.js      # HTTP(S) 传输：SSE / Streamable HTTP
+│   ├── server.js    # MCP Server 与工具注册
+│   ├── client.js    # dmmp-system HTTP 客户端
+│   ├── config.js    # 配置解析
+│   └── logger.js    # stderr 日志
+└── test/
+    ├── config.test.mjs   # 配置解析单元测试
+    ├── http.test.mjs     # HTTP(S) 传输端到端测试
+    ├── smoke.mjs         # 端到端冒烟测试
+    └── e2e-published.mjs # 用公网已发布的包跑真实链路
+```
+
+## 约束
+
+- **只读**：本 Server 只提供查询工具，不含任何写操作。
+- **日志走 stderr**：写 stdout 会破坏 JSON-RPC 协议。
+- **脱敏在服务端完成**：本项目不做脱敏，直接透传后端已脱敏的结果。
+- **限流在服务端做**：客户端侧计数可被绕过，服务端按「操作人」和「查询目标」两个维度限流。
+- **包内不含内网地址**：服务地址由使用方通过 `--base-url` 或 `~/.lead-mcp/config.json` 指定。
+- **HTTP 模式必须带令牌**：`--auth-token` 未配置时直接拒绝启动。

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@leadfund/lead-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "202610.2.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/http.test.mjs && node test/smoke.mjs",
+    "smoke": "node test/smoke.mjs",
+    "release": "npm test && npm publish --registry=https://registry.npmjs.org/ --access public",
+    "test:http": "node test/http.test.mjs"
+  },
+  "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"
+  },
+  "repository": {
+    "type": "git",
+    "url": "http://10.1.1.90/root/lead-mcp.git"
+  },
+  "homepage": "http://10.1.1.90/root/lead-mcp",
+  "bugs": {
+    "url": "http://10.1.1.90/root/lead-mcp/-/issues"
+  }
+}

package/src/cli.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { USAGE, isHelpRequested, loadConfig } from "./config.js";
+import { startHttpServer } from "./http.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();
+
+  if (config.transport === "stdio") {
+    const server = createServer(config);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logger.info(
+      `已启动（stdio），环境=${config.env}，服务地址=${config.baseUrls.join(", ")}，超时=${config.timeoutMs}ms`,
+    );
+    return;
+  }
+
+  // HTTP 模式常驻，直到进程被结束
+  await startHttpServer(config);
+}
+
+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);
+  }
+}