@wsh19991219/mcp-server 0.1.1 → 0.1.3

package/README.md

@@ -1,18 +1,28 @@
 # @data_mgr/mcp-server
 
-Data Manager MCP Server — 通过 MCP 协议对接 Data Manager 后端 API，提供数据分析查询能力。
+Data Manager MCP Server — 通过 [MCP](https://modelcontextprotocol.io) 协议对接 Data Manager 后端 API，为 Claude Code 等 AI Agent 提供数据查询与分析能力。
 
-## Install
+## 功能
+
+- **鉴权管理**：浏览器一键登录，JWT 自动续期
+- **表结构探索**：模糊搜表、查看列定义
+- **数据查询**：预定义指标 + 自定义只读 SQL
+- **多库支持**：主库及多个区域数据库 group
+- **安全约束**：SQL 只读、敏感字段自动脱敏
+
+## 安装
 
 ```bash
 npm install -g @data_mgr/mcp-server
 ```
 
-Requires **Node.js 18+**.
+需要 **Node.js 18+**。
+
+## 快速集成
 
-## Claude Code 集成
+### Claude Code
 
-在 `.claude/settings.json` 中添加：
+在项目根目录 `.claude/settings.json` 中添加：
 
 ```json
 {
@@ -24,22 +34,65 @@ Requires **Node.js 18+**.
 }
 ```
 
+或使用 npx（无需全局安装）：
+
+```json
+{
+  "mcpServers": {
+    "data-mgr": {
+      "command": "npx",
+      "args": ["-y", "@data_mgr/mcp-server"]
+    }
+  }
+}
+```
+
+### Cursor
+
+在 `.cursor/mcp.json` 中添加同样的配置。
+
 ## MCP 工具
 
-| 工具 | 功能 |
-|------|------|
-| `check_auth` | 检查登录状态 |
-| `login` | 浏览器登录 |
-| `analytics_query` | 预定义指标查询 |
-| `api_request` | 通用 API 请求（含自定义 SQL） |
+| 工具 | 功能 | 说明 |
+| --- | --- | --- |
+| `check_auth` | 检查登录状态 | 返回用户名、token 有效期 |
+| `login` | 浏览器登录 | 打开浏览器完成 OAuth 登录 |
+| `analytics_query` | 预定义指标查询 | 支持 metric、filters、limit 等参数 |
+| `api_request` | 通用 REST 请求 | GET/POST/PUT/DELETE，含自定义 SQL |
+
+### api_request 端点
+
+| 端点 | 方法 | 用途 |
+| --- | --- | --- |
+| `/health` | GET | 健康检查，返回可用数据库 group |
+| `/api/v1/analytics/catalog` | GET | 列出可用指标和数据库 group |
+| `/api/v1/analytics/schema?q=<关键词>` | GET | 模糊搜索表名 |
+| `/api/v1/analytics/schema?tables=<表名>` | GET | 查看表的列结构 |
+| `/api/v1/analytics/sql` | POST | 执行自定义只读 SQL |
 
 ## 环境变量
 
 | 变量 | 说明 | 默认值 |
-|------|------|--------|
-| `DATA_MGR_API_URL` | 后端 API 地址 | `http://127.0.0.1:8092` |
+| --- | --- | --- |
+| `DATA_MGR_API_URL` | 后端 API 地址 | `http://42.194.226.85:8092` |
 | `DATA_MGR_CONFIG_DIR` | 配置文件目录 | `~/.data-mgr` |
 
+## 使用示例
+
+安装后在 Claude Code 对话中直接使用自然语言：
+
+- "查看 photonpay_card_transaction 的表结构"
+- "查询 photonpay 渠道最近 24 小时的卡交易笔数和金额"
+- "对比三个渠道昨日的交易量"
+- "生成昨日渠道交易日报"
+
+## 相关包
+
+| 包名 | 用途 |
+| --- | --- |
+| [`@data_mgr/cli`](https://www.npmjs.com/package/@data_mgr/cli) | Data Manager CLI，适用于 Cursor Agent |
+| [`weather-query-cli`](https://www.npmjs.com/package/weather-query-cli) | 天气查询 CLI |
+
 ## License
 
 MIT

package/SKILL.md

@@ -9,56 +9,123 @@ description: >-
 
 # Data Manager MCP Server
 
-通过 MCP 协议对接 Data Manager 后端 API，提供数据分析查询能力。
+通过 MCP 协议对接 Data Manager 后端 API，为 AI Agent 提供数据查询与分析能力。
 
-## MCP 工具总览
+## 快速开始
+
+1. 全局安装：`npm install -g @data_mgr/mcp-server`
+2. 注册 MCP 服务（见下方 [注册](#注册到-claude-code) 章节）
+3. 对话中触发登录：Agent 会自动调用 `login` 工具打开浏览器
+
+## MCP 工具
 
 | 工具 | 功能 | 关键参数 |
-|------|------|---------|
-| `check_auth` | 检查登录状态 | 无 |
-| `login` | 浏览器登录 | `openBrowser` (可选) |
-| `analytics_query` | 预定义指标查询 | `metric`(必填), `db`, `params`, `filters`, `limit` |
-| `api_request` | 通用 API 请求 | `method`(必填), `path`(必填), `body`, `query` |
+| --- | --- | --- |
+| `check_auth` | 检查登录状态，返回 username / token 有效期 | 无 |
+| `login` | 浏览器登录获取 JWT | `openBrowser`: bool（默认 true） |
+| `analytics_query` | 查询预定义指标 | `metric`(必填), `db`, `params`, `filters`, `limit` |
+| `api_request` | 通用 REST 请求（GET/POST/PUT/DELETE） | `method`(必填), `path`(必填), `body`, `query` |
 
-## 通过 api_request 可访问的 REST 端点
+### api_request 可访问的 REST 端点
 
-| 端点 | 方法 | 用途 | 对应 Skill |
-|------|------|------|-----------|
-| `/api/v1/analytics/catalog` | GET | 列出可用指标和数据库 group | data-query, data-analysis |
-| `/api/v1/analytics/schema?q=<关键词>` | GET | 模糊搜表名 | schema-explorer |
-| `/api/v1/analytics/schema?tables=<表名>` | GET | 查看表列结构 | schema-explorer |
-| `/api/v1/analytics/sql` | POST | 自定义只读 SQL | data-query, data-analysis |
-| `/health` | GET | 健康检查 | — |
+| 端点 | 方法 | 用途 |
+| --- | --- | --- |
+| `/health` | GET | 健康检查，返回可用数据库 group 列表 |
+| `/api/v1/analytics/catalog` | GET | 列出可用指标和数据库 group |
+| `/api/v1/analytics/schema?q=<关键词>` | GET | 模糊搜表名 |
+| `/api/v1/analytics/schema?tables=<表名>` | GET | 查看指定表的列结构 |
+| `/api/v1/analytics/sql` | POST | 执行自定义只读 SQL（SELECT/WITH） |
 
-## 子 Skill 列表
+## 子 Skill
 
 | Skill | 触发词 | 用途 |
-|-------|--------|------|
-| `schema-explorer` | 查表/表结构/搜表/字段 | 表结构探索 |
-| `data-query` | 查数据/指标/统计/SQL | 数据查询（指标 + SQL） |
-| `data-analysis` | 数据分析/对账/报表/漏斗 | 六步分析流程 |
-| `daily-channel-report` | 日报/每日报表/昨日交易 | 渠道交易日报 |
+| --- | --- | --- |
+| `schema-explorer` | 查表、表结构、搜表、字段 | 探索数据库表结构 |
+| `data-query` | 查数据、指标、统计、SQL | 预定义指标查询 + 自定义 SQL |
+| `data-analysis` | 数据分析、对账、报表、漏斗 | 六步数据分析流程 |
+| `daily-channel-report` | 日报、每日报表、昨日交易 | 渠道交易日报（笔数、金额、趋势） |
+
+## 渠道速查
+
+| channel_id | 渠道名 | 交易表名 | 主金额字段（USD） |
+| --- | --- | --- | --- |
+| 1 | Photon (photonpay) | `photonpay_card_transaction` | `txn_principal_change_amount` |
+| 2 | Interlace | `interlace_card_transaction` | `transaction_amount` |
+| 3 | PingPong | `pingpong_card_transaction` | `billing_amount` |
+
+> **注意：** 各渠道金额字段不同，禁止混用。详见各子 Skill 文档。
+
+## 数据库 Group
+
+| group 名 | 说明 |
+| --- | --- |
+| `default` | 主库（默认） |
+| `prod_vn` | 越南 |
+| `prod_vero` | Vero |
+| `prod_zenia` | Zenia |
+| `prod_jtpay` | JT Pay |
 
 ## 标准工作流
 
 ```
-1. check_auth        → 检查是否已登录
-2. login             → 未登录时触发浏览器登录
-3. catalog/schema    → 定位数据（api_request GET）
-4. query/sql         → 取数（analytics_query 或 api_request POST）
-5. 格式化交付        → 结构化结论
+1. check_auth          → 检查是否已登录
+2. login               → 未登录时触发浏览器登录
+3. catalog / schema    → 定位目标数据（api_request GET）
+4. query / sql         → 取数（analytics_query 或 api_request POST SQL）
+5. 格式化交付          → 结构化结论 + 洞察
+```
+
+## 示例
+
+### 查询表结构
+
+```json
+// api_request
+{ "method": "GET", "path": "/api/v1/analytics/schema?tables=photonpay_card_transaction" }
+```
+
+### 执行自定义 SQL
+
+```json
+// api_request
+{
+  "method": "POST",
+  "path": "/api/v1/analytics/sql",
+  "body": {
+    "db": "default",
+    "sql": "SELECT COUNT(*) AS cnt, SUM(txn_principal_change_amount) AS total_usd FROM photonpay_card_transaction WHERE created_time >= DATE_SUB(NOW(), INTERVAL 24 HOUR)"
+  }
+}
 ```
 
 ## 注册到 Claude Code
 
+### 方式一：全局安装后注册（推荐）
+
+```bash
+npm install -g @data_mgr/mcp-server
+```
+
 在 `.claude/settings.json` 中添加：
 
 ```json
 {
   "mcpServers": {
     "data-mgr": {
-      "command": "node",
-      "args": ["$(npm root -g)/@data_mgr/mcp-server/bin/data-mgr-mcp.js"]
+      "command": "data-mgr-mcp"
+    }
+  }
+}
+```
+
+### 方式二：npx 直接运行（无需全局安装）
+
+```json
+{
+  "mcpServers": {
+    "data-mgr": {
+      "command": "npx",
+      "args": ["-y", "@data_mgr/mcp-server"]
     }
   }
 }
@@ -67,23 +134,23 @@ description: >-
 ## 环境变量
 
 | 变量 | 说明 | 默认值 |
-|------|------|--------|
+| --- | --- | --- |
 | `DATA_MGR_API_URL` | 后端 API 地址 | `http://127.0.0.1:8092` |
 | `DATA_MGR_CONFIG_DIR` | 配置文件目录 | `~/.data-mgr` |
 
 ## 错误处理
 
-| 错误 | 处理 |
-|------|------|
+| 错误 | 处理方式 |
+| --- | --- |
 | `Not logged in` | 调用 `login` 工具 |
 | `Login timed out` | 重新调用 `login`，手动打开返回的 URL |
 | Token 过期 | 重新调用 `login` |
-| API 403/401 | 检查 token 或重新登录 |
-| API 参数错误 | 检查 metric/db/SQL 参数 |
+| API 401 / 403 | 检查 token 或重新登录 |
+| API 参数错误 | 检查 metric / db / SQL 参数是否正确 |
 
 ## 安全
 
-- **禁止**在回复中输出完整 token
-- 写/删操作前确认用户意图
-- SQL 仅允许 SELECT/WITH（只读），禁止 DML、注释、多语句
-- 敏感数据（手机/身份证/邮箱/银行卡）会被后端自动脱敏
+- **禁止**在回复中输出完整 token 或密码
+- 写 / 删除操作前必须确认用户意图
+- SQL 仅允许 `SELECT` / `WITH`（只读），禁止 DML、注释、多语句
+- 敏感数据（手机、身份证、邮箱、银行卡）由后端自动脱敏

package/lib/config.js

@@ -8,9 +8,15 @@ const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
 
 /** @typedef {{ apiUrl?: string, token?: string, username?: string, userId?: number, tenantId?: number, expiresIn?: string, expiresAt?: string, loggedInAt?: string }} DataMgrConfig */
 
-export const DEFAULT_API_URL = "http://127.0.0.1:8092";
+/** Production API (port 8092 serves plain HTTP; use HTTPS only via reverse proxy on 443). */
+export const DEFAULT_API_URL = "http://42.194.226.85:8092";
 export const LOGIN_PATH = "/api/v1/auth/login";
 
+/** @param {string} url */
+export function normalizeApiUrl(url) {
+  return String(url).trim().replace(/\/$/, "");
+}
+
 /** @param {string | number | undefined} expiresIn @param {Date} [from] */
 export function computeExpiresAt(expiresIn, from = new Date()) {
   if (expiresIn === undefined || expiresIn === null || expiresIn === "") return undefined;
@@ -68,9 +74,9 @@ export function getConfigPath() {
 /** @returns {string} */
 export function getApiUrl() {
   const fromEnv = process.env.DATA_MGR_API_URL?.trim();
-  if (fromEnv) return fromEnv.replace(/\/$/, "");
+  if (fromEnv) return normalizeApiUrl(fromEnv);
   const cfg = loadConfig();
-  if (cfg.apiUrl) return cfg.apiUrl.replace(/\/$/, "");
+  if (cfg.apiUrl) return normalizeApiUrl(cfg.apiUrl);
   return DEFAULT_API_URL;
 }
 

package/lib/login-server.js

@@ -3,6 +3,40 @@ import { randomBytes } from "node:crypto";
 import { spawn } from "node:child_process";
 import { getApiUrl, LOGIN_PATH } from "./config.js";
 
+const CORS_HEADERS = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+  "Access-Control-Allow-Headers": "Content-Type",
+};
+
+/** @param {import('node:http').ServerResponse} res @param {number} status @param {Record<string, unknown>} body */
+function sendJson(res, status, body) {
+  res.writeHead(status, { "Content-Type": "application/json; charset=utf-8", ...CORS_HEADERS });
+  res.end(JSON.stringify(body));
+}
+
+/** @param {unknown} err @param {string} apiUrl */
+function formatUpstreamError(err, apiUrl) {
+  const base = err instanceof Error ? err : new Error(String(err));
+  const cause = base.cause instanceof Error ? base.cause : null;
+  const code = /** @type {{ code?: string }} */ (cause ?? base).code;
+  const msg = cause?.message ?? base.message;
+
+  if (code === "ECONNREFUSED" || code === "ENOTFOUND" || code === "ETIMEDOUT") {
+    return `无法连接 API（${apiUrl}）：${msg}`;
+  }
+  if (/packet length too long/i.test(msg)) {
+    return `协议不匹配：${apiUrl} 使用了 HTTPS，但该端口可能只提供 HTTP。请改为 http:// 或配置 443 反向代理。`;
+  }
+  if (/certificate|UNABLE_TO_VERIFY|self signed|ALTNAME_INVALID/i.test(msg)) {
+    return `HTTPS 证书校验失败（${apiUrl}）。请使用与证书匹配的域名，或配置 NODE_EXTRA_CA_CERTS。`;
+  }
+  if (base.name === "TypeError" && /fetch failed/i.test(base.message)) {
+    return `请求 API 失败（${apiUrl}）：${msg || base.message}`;
+  }
+  return msg || base.message;
+}
+
 const LOGIN_PAGE = String.raw`<!DOCTYPE html>
 <html lang="zh-CN">
 <head>
@@ -130,14 +164,14 @@ const SUCCESS_PAGE = String.raw`<!DOCTYPE html>
 /**
  * Start local login server, open browser, return token when login succeeds.
  * Modified for MCP: uses onLoginUrl callback instead of console.log.
- * @param {{ timeoutMs?: number, openBrowser?: boolean, onLoginUrl?: (url: string) => void }} [options]
+ * @param {{ timeoutMs?: number, openBrowser?: boolean, apiUrl?: string, onLoginUrl?: (url: string) => void }} [options]
  * @returns {Promise<LoginResult>}
  */
 export function runBrowserLogin(options = {}) {
   const timeoutMs = options.timeoutMs ?? 5 * 60 * 1000;
   const openBrowser = options.openBrowser !== false;
   const onLoginUrl = options.onLoginUrl ?? (() => {});
-  const apiUrl = getApiUrl();
+  const apiUrl = options.apiUrl ?? getApiUrl();
   const state = randomBytes(16).toString("hex");
 
   return new Promise((resolve, reject) => {
@@ -154,6 +188,12 @@ export function runBrowserLogin(options = {}) {
     server = http.createServer(async (req, res) => {
       const url = new URL(req.url ?? "/", "http://127.0.0.1");
 
+      if (req.method === "OPTIONS" && url.pathname === "/api/login") {
+        res.writeHead(204, CORS_HEADERS);
+        res.end();
+        return;
+      }
+
       if (req.method === "GET" && (url.pathname === "/" || url.pathname === "/login")) {
         res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
         res.end(LOGIN_PAGE.replace("__API_URL__", apiUrl));
@@ -165,26 +205,34 @@ export function runBrowserLogin(options = {}) {
         req.on("data", (chunk) => { body += chunk; });
         req.on("end", async () => {
           try {
-            const { username, password } = JSON.parse(body);
+            const { username, password } = JSON.parse(body || "{}");
             if (!username || !password) {
-              res.writeHead(400, { "Content-Type": "application/json" });
-              res.end(JSON.stringify({ error: "username and password required" }));
+              sendJson(res, 400, { error: "username and password required" });
               return;
             }
 
-            const loginRes = await fetch(`${apiUrl}${LOGIN_PATH}`, {
-              method: "POST",
-              headers: { "Content-Type": "application/json" },
-              body: JSON.stringify({ username, password }),
-            });
+            const loginEndpoint = `${apiUrl}${LOGIN_PATH}`;
+            let loginRes;
+            try {
+              loginRes = await fetch(loginEndpoint, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ username, password }),
+              });
+            } catch (fetchErr) {
+              sendJson(res, 502, {
+                error: formatUpstreamError(fetchErr, apiUrl),
+                message: formatUpstreamError(fetchErr, apiUrl),
+              });
+              return;
+            }
 
             const data = await loginRes.json().catch(() => ({}));
 
             // API returns {code, message, data} — check code for errors
             if (!loginRes.ok || (data.code != null && data.code !== 0)) {
               const message = data.message ?? data.error ?? `Login failed (HTTP ${loginRes.status}, code ${data.code})`;
-              res.writeHead(loginRes.ok ? 401 : loginRes.status, { "Content-Type": "application/json" });
-              res.end(JSON.stringify({ error: message }));
+              sendJson(res, loginRes.ok ? 401 : loginRes.status, { error: message, message });
               return;
             }
 
@@ -192,16 +240,15 @@ export function runBrowserLogin(options = {}) {
             const inner = data.data ?? {};
             const token = data.token ?? inner.token ?? inner.access_token;
             if (!token) {
-              res.writeHead(502, { "Content-Type": "application/json" });
-              res.end(JSON.stringify({
+              sendJson(res, 502, {
                 error: "API response missing token field",
+                message: "API response missing token field",
                 debug: { topKeys: Object.keys(data), innerKeys: Object.keys(inner) },
-              }));
+              });
               return;
             }
 
-            res.writeHead(200, { "Content-Type": "application/json" });
-            res.end(JSON.stringify({ ok: true }));
+            sendJson(res, 200, { ok: true });
 
             const loggedInAt = new Date().toISOString();
             const expiresIn = (inner.expires_in ?? data.expires_in) != null
@@ -218,9 +265,9 @@ export function runBrowserLogin(options = {}) {
               loginUrl: `http://127.0.0.1:${server?.address()?.port ?? "?"}/login`,
             });
           } catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            res.writeHead(500, { "Content-Type": "application/json" });
-            res.end(JSON.stringify({ error: message }));
+            const message = formatUpstreamError(err, apiUrl);
+            console.error("[data-mgr login]", message, err);
+            sendJson(res, 500, { error: message, message });
           }
         });
         return;

package/lib/tools.js

@@ -184,6 +184,7 @@ export function registerTools(server) {
         const expiresAt = computeExpiresAt(result.expiresIn, new Date(result.loggedInAt));
 
         saveConfig({
+          apiUrl: getApiUrl(),
           token: result.token,
           username: result.username,
           userId: result.userId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wsh19991219/mcp-server",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "MCP server for Data Manager API — stdio transport, JWT auth",
   "type": "module",
   "main": "lib/tools.js",