@wsh19991219/mcp-server 0.1.1

package/README.md

@@ -0,0 +1,45 @@
+# @data_mgr/mcp-server
+
+Data Manager MCP Server — 通过 MCP 协议对接 Data Manager 后端 API，提供数据分析查询能力。
+
+## Install
+
+```bash
+npm install -g @data_mgr/mcp-server
+```
+
+Requires **Node.js 18+**.
+
+## Claude Code 集成
+
+在 `.claude/settings.json` 中添加：
+
+```json
+{
+  "mcpServers": {
+    "data-mgr": {
+      "command": "data-mgr-mcp"
+    }
+  }
+}
+```
+
+## MCP 工具
+
+| 工具 | 功能 |
+|------|------|
+| `check_auth` | 检查登录状态 |
+| `login` | 浏览器登录 |
+| `analytics_query` | 预定义指标查询 |
+| `api_request` | 通用 API 请求（含自定义 SQL） |
+
+## 环境变量
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `DATA_MGR_API_URL` | 后端 API 地址 | `http://127.0.0.1:8092` |
+| `DATA_MGR_CONFIG_DIR` | 配置文件目录 | `~/.data-mgr` |
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: data-mgr-mcp
+description: >-
+  Data Manager 数据分析网关 MCP 服务。通过 MCP 工具对接 data-mgr 后端，
+  提供鉴权、表结构探索、数据查询、自定义 SQL 能力。
+  子 Skill: schema-explorer（查表）, data-query（查数据）, data-analysis（分析流程）, daily-channel-report（日报）。
+  Triggers: data-mgr, data_mgr, analytics, 数据管理, 数据分析, 数据查询, 查表, 报表.
+---
+
+# Data Manager MCP Server
+
+通过 MCP 协议对接 Data Manager 后端 API，提供数据分析查询能力。
+
+## MCP 工具总览
+
+| 工具 | 功能 | 关键参数 |
+|------|------|---------|
+| `check_auth` | 检查登录状态 | 无 |
+| `login` | 浏览器登录 | `openBrowser` (可选) |
+| `analytics_query` | 预定义指标查询 | `metric`(必填), `db`, `params`, `filters`, `limit` |
+| `api_request` | 通用 API 请求 | `method`(必填), `path`(必填), `body`, `query` |
+
+## 通过 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 | 健康检查 | — |
+
+## 子 Skill 列表
+
+| Skill | 触发词 | 用途 |
+|-------|--------|------|
+| `schema-explorer` | 查表/表结构/搜表/字段 | 表结构探索 |
+| `data-query` | 查数据/指标/统计/SQL | 数据查询（指标 + SQL） |
+| `data-analysis` | 数据分析/对账/报表/漏斗 | 六步分析流程 |
+| `daily-channel-report` | 日报/每日报表/昨日交易 | 渠道交易日报 |
+
+## 标准工作流
+
+```
+1. check_auth        → 检查是否已登录
+2. login             → 未登录时触发浏览器登录
+3. catalog/schema    → 定位数据（api_request GET）
+4. query/sql         → 取数（analytics_query 或 api_request POST）
+5. 格式化交付        → 结构化结论
+```
+
+## 注册到 Claude Code
+
+在 `.claude/settings.json` 中添加：
+
+```json
+{
+  "mcpServers": {
+    "data-mgr": {
+      "command": "node",
+      "args": ["$(npm root -g)/@data_mgr/mcp-server/bin/data-mgr-mcp.js"]
+    }
+  }
+}
+```
+
+## 环境变量
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `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 参数 |
+
+## 安全
+
+- **禁止**在回复中输出完整 token
+- 写/删操作前确认用户意图
+- SQL 仅允许 SELECT/WITH（只读），禁止 DML、注释、多语句
+- 敏感数据（手机/身份证/邮箱/银行卡）会被后端自动脱敏

package/bin/data-mgr-mcp.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerTools } from "../lib/tools.js";
+
+const server = new McpServer({
+  name: "data-mgr",
+  version: "0.1.0",
+});
+
+registerTools(server);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/lib/api.js

@@ -0,0 +1,49 @@
+import { getApiUrl, loadConfig, hasValidToken } from "./config.js";
+
+/**
+ * @param {string} path - API path starting with /
+ * @param {RequestInit} [init]
+ */
+export async function apiRequest(path, init = {}) {
+  const cfg = loadConfig();
+  if (!hasValidToken()) {
+    throw new Error("Not logged in. Run: data-mgr login");
+  }
+
+  const base = getApiUrl();
+  const url = `${base}${path.startsWith("/") ? path : `/${path}`}`;
+  const headers = new Headers(init.headers);
+  headers.set("Authorization", `Bearer ${cfg.token}`);
+  if (init.body && !headers.has("Content-Type")) {
+    headers.set("Content-Type", "application/json");
+  }
+
+  const res = await fetch(url, { ...init, headers });
+  const text = await res.text();
+  let data;
+  try {
+    data = text ? JSON.parse(text) : null;
+  } catch {
+    data = text;
+  }
+
+  if (!res.ok) {
+    const msg =
+      typeof data === "object" && data && ("message" in data || "error" in data)
+        ? String(data.message ?? data.error)
+        : `HTTP ${res.status}`;
+    const err = new Error(msg);
+    err.status = res.status;
+    err.body = data;
+    throw err;
+  }
+
+  return data;
+}
+
+/** @param {Record<string, string>} [query] */
+export function buildQuery(query) {
+  if (!query || Object.keys(query).length === 0) return "";
+  const params = new URLSearchParams(query);
+  return `?${params.toString()}`;
+}

package/lib/config.js

@@ -0,0 +1,87 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const CONFIG_DIR = process.env.DATA_MGR_CONFIG_DIR
+  ?? path.join(os.homedir(), ".data-mgr");
+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";
+export const LOGIN_PATH = "/api/v1/auth/login";
+
+/** @param {string | number | undefined} expiresIn @param {Date} [from] */
+export function computeExpiresAt(expiresIn, from = new Date()) {
+  if (expiresIn === undefined || expiresIn === null || expiresIn === "") return undefined;
+  const seconds = Number(expiresIn);
+  if (!Number.isNaN(seconds) && seconds > 0) {
+    return new Date(from.getTime() + seconds * 1000).toISOString();
+  }
+  const asDate = new Date(String(expiresIn));
+  if (!Number.isNaN(asDate.getTime())) return asDate.toISOString();
+  return undefined;
+}
+
+/** @returns {DataMgrConfig} */
+export function loadConfig() {
+  try {
+    const raw = fs.readFileSync(CONFIG_FILE, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+/** @param {Partial<DataMgrConfig>} patch */
+export function saveConfig(patch) {
+  const current = loadConfig();
+  const next = { ...current, ...patch };
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(next, null, 2), "utf8");
+  try {
+    fs.chmodSync(CONFIG_FILE, 0o600);
+  } catch {
+    // Windows may not support chmod the same way
+  }
+  return next;
+}
+
+export function clearToken() {
+  const {
+    token,
+    username,
+    userId,
+    tenantId,
+    expiresIn,
+    expiresAt,
+    loggedInAt,
+    ...rest
+  } = loadConfig();
+  saveConfig(rest);
+}
+
+export function getConfigPath() {
+  return CONFIG_FILE;
+}
+
+/** @returns {string} */
+export function getApiUrl() {
+  const fromEnv = process.env.DATA_MGR_API_URL?.trim();
+  if (fromEnv) return fromEnv.replace(/\/$/, "");
+  const cfg = loadConfig();
+  if (cfg.apiUrl) return cfg.apiUrl.replace(/\/$/, "");
+  return DEFAULT_API_URL;
+}
+
+export function hasValidToken() {
+  const cfg = loadConfig();
+  if (!cfg.token) return false;
+  const expiresAt =
+    cfg.expiresAt ??
+    (cfg.expiresIn && cfg.loggedInAt
+      ? computeExpiresAt(cfg.expiresIn, new Date(cfg.loggedInAt))
+      : undefined);
+  if (!expiresAt) return true;
+  return new Date(expiresAt).getTime() > Date.now();
+}

package/lib/login-server.js

@@ -0,0 +1,320 @@
+import http from "node:http";
+import { randomBytes } from "node:crypto";
+import { spawn } from "node:child_process";
+import { getApiUrl, LOGIN_PATH } from "./config.js";
+
+const LOGIN_PAGE = String.raw`<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Data Manager 登录</title>
+  <style>
+    * { box-sizing: border-box; }
+    body {
+      margin: 0; min-height: 100vh; display: grid; place-items: center;
+      font-family: system-ui, -apple-system, "Segoe UI", sans-serif;
+      background: linear-gradient(135deg, #0f172a, #1e3a5f);
+      color: #e2e8f0;
+    }
+    .card {
+      width: min(400px, 92vw); padding: 2rem; border-radius: 16px;
+      background: rgba(15, 23, 42, 0.9); border: 1px solid #334155;
+      box-shadow: 0 20px 50px rgba(0,0,0,.35);
+    }
+    h1 { margin: 0 0 .25rem; font-size: 1.35rem; }
+    p { margin: 0 0 1.5rem; color: #94a3b8; font-size: .9rem; }
+    label { display: block; margin-bottom: .35rem; font-size: .85rem; color: #cbd5e1; }
+    input {
+      width: 100%; padding: .65rem .75rem; margin-bottom: 1rem;
+      border: 1px solid #475569; border-radius: 8px; background: #0f172a; color: #f8fafc;
+      font-size: 1rem;
+    }
+    input:focus { outline: 2px solid #3b82f6; border-color: #3b82f6; }
+    button {
+      width: 100%; padding: .75rem; border: none; border-radius: 8px;
+      background: #2563eb; color: #fff; font-size: 1rem; font-weight: 600; cursor: pointer;
+    }
+    button:hover { background: #1d4ed8; }
+    button:disabled { opacity: .6; cursor: not-allowed; }
+    .msg { margin-top: 1rem; font-size: .9rem; min-height: 1.25rem; }
+    .err { color: #f87171; }
+    .ok { color: #4ade80; }
+    .api { font-size: .75rem; color: #64748b; word-break: break-all; margin-top: 1rem; }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <h1>Data Manager</h1>
+    <p>请输入账号和密码，登录成功后 CLI 将自动保存 token。</p>
+    <form id="form">
+      <label for="username">账号</label>
+      <input id="username" name="username" autocomplete="username" required />
+      <label for="password">密码</label>
+      <input id="password" name="password" type="password" autocomplete="current-password" required />
+      <button type="submit" id="btn">登录</button>
+    </form>
+    <div id="msg" class="msg"></div>
+    <div class="api">API: __API_URL__</div>
+  </div>
+  <script>
+    const form = document.getElementById('form');
+    const msg = document.getElementById('msg');
+    const btn = document.getElementById('btn');
+    form.addEventListener('submit', async (e) => {
+      e.preventDefault();
+      msg.textContent = '';
+      msg.className = 'msg';
+      btn.disabled = true;
+      btn.textContent = '登录中…';
+      try {
+        const res = await fetch('/api/login', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            username: form.username.value,
+            password: form.password.value,
+          }),
+        });
+        const data = await res.json().catch(() => ({}));
+        if (!res.ok) {
+          throw new Error(data.message || data.error || ('HTTP ' + res.status));
+        }
+        window.location.href = '/success';
+      } catch (err) {
+        msg.textContent = err.message || '登录失败';
+        msg.className = 'msg err';
+        btn.disabled = false;
+        btn.textContent = '登录';
+      }
+    });
+  </script>
+</body>
+</html>`;
+
+const SUCCESS_PAGE = String.raw`<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8" />
+  <title>登录成功</title>
+  <style>
+    body {
+      margin: 0; min-height: 100vh; display: grid; place-items: center;
+      font-family: system-ui, sans-serif; background: #0f172a; color: #e2e8f0;
+      text-align: center;
+    }
+    h1 { color: #4ade80; }
+    p { color: #94a3b8; }
+  </style>
+</head>
+<body>
+  <div>
+    <h1>✓ 登录成功</h1>
+    <p>Token 已保存到本地，可以关闭此窗口并返回终端。</p>
+  </div>
+</body>
+</html>`;
+
+/**
+ * @typedef {object} LoginResult
+ * @property {string} token
+ * @property {string} [username]
+ * @property {number} [userId]
+ * @property {number} [tenantId]
+ * @property {string} [expiresIn]
+ * @property {string} [expiresAt]
+ * @property {string} loggedInAt
+ * @property {string} loginUrl - The URL the user should visit to log in
+ */
+
+/**
+ * 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]
+ * @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 state = randomBytes(16).toString("hex");
+
+  return new Promise((resolve, reject) => {
+    /** @type {import('node:http').Server | null} */
+    let server = null;
+    /** @type {NodeJS.Timeout | null} */
+    let timer = null;
+
+    const cleanup = () => {
+      if (timer) clearTimeout(timer);
+      server?.close();
+    };
+
+    server = http.createServer(async (req, res) => {
+      const url = new URL(req.url ?? "/", "http://127.0.0.1");
+
+      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));
+        return;
+      }
+
+      if (req.method === "POST" && url.pathname === "/api/login") {
+        let body = "";
+        req.on("data", (chunk) => { body += chunk; });
+        req.on("end", async () => {
+          try {
+            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" }));
+              return;
+            }
+
+            const loginRes = await fetch(`${apiUrl}${LOGIN_PATH}`, {
+              method: "POST",
+              headers: { "Content-Type": "application/json" },
+              body: JSON.stringify({ username, password }),
+            });
+
+            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 }));
+              return;
+            }
+
+            // Token may be at data.token, data.data.token, or data.data.access_token
+            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({
+                error: "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 }));
+
+            const loggedInAt = new Date().toISOString();
+            const expiresIn = (inner.expires_in ?? data.expires_in) != null
+              ? String(inner.expires_in ?? data.expires_in) : undefined;
+
+            cleanup();
+            resolve({
+              token,
+              username: inner.username ?? data.username ?? username,
+              userId: inner.user_id ?? data.user_id,
+              tenantId: inner.tenant_id ?? data.tenant_id,
+              expiresIn,
+              loggedInAt,
+              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 }));
+          }
+        });
+        return;
+      }
+
+      if (req.method === "GET" && url.pathname === "/success") {
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+        res.end(SUCCESS_PAGE);
+        return;
+      }
+
+      if (req.method === "GET" && url.pathname === "/callback") {
+        if (url.searchParams.get("state") && url.searchParams.get("state") !== state) {
+          res.writeHead(400, { "Content-Type": "text/plain" });
+          res.end("Invalid state");
+          return;
+        }
+        const token = url.searchParams.get("token") ?? url.searchParams.get("access_token");
+        if (token) {
+          res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+          res.end(SUCCESS_PAGE);
+          cleanup();
+          resolve({
+            token,
+            username: url.searchParams.get("username") ?? undefined,
+            loggedInAt: new Date().toISOString(),
+            loginUrl: `http://127.0.0.1:${server?.address()?.port ?? "?"}/login`,
+          });
+          return;
+        }
+      }
+
+      res.writeHead(404, { "Content-Type": "text/plain" });
+      res.end("Not found");
+    });
+
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      if (!addr || typeof addr === "string") {
+        cleanup();
+        reject(new Error("Failed to bind login server"));
+        return;
+      }
+
+      const loginUrl = `http://127.0.0.1:${addr.port}/login`;
+
+      // Notify caller of the login URL (replaces console.log for MCP compatibility)
+      onLoginUrl(loginUrl);
+
+      if (openBrowser) {
+        openUrl(loginUrl);
+      }
+
+      timer = setTimeout(() => {
+        cleanup();
+        reject(new Error("Login timed out. Open the URL above in your browser and try again."));
+      }, timeoutMs);
+    });
+
+    server.on("error", (err) => {
+      cleanup();
+      reject(err);
+    });
+  });
+}
+
+/** @param {string} url */
+function openUrl(url) {
+  const platform = process.platform;
+  let child;
+
+  if (platform === "win32") {
+    child = spawn("cmd.exe", ["/c", "start", "", url], {
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true,
+    });
+  } else if (platform === "darwin") {
+    child = spawn("open", [url], { detached: true, stdio: "ignore" });
+  } else {
+    child = spawn("xdg-open", [url], { detached: true, stdio: "ignore" });
+  }
+
+  child.on("error", () => {
+    if (platform === "win32") {
+      spawn(
+        "powershell.exe",
+        ["-NoProfile", "-Command", `Start-Process -FilePath '${url.replace(/'/g, "''")}'`],
+        { detached: true, stdio: "ignore", windowsHide: true },
+      ).unref();
+      return;
+    }
+    // Browser open failed - caller already has the URL via onLoginUrl callback
+  });
+
+  child.unref();
+}

package/lib/tools.js

@@ -0,0 +1,214 @@
+import { z } from "zod";
+import {
+  loadConfig,
+  saveConfig,
+  getApiUrl,
+  hasValidToken,
+  computeExpiresAt,
+  getConfigPath,
+} from "./config.js";
+import { apiRequest, buildQuery } from "./api.js";
+
+/**
+ * Register all data-mgr tools on the MCP server.
+ * @param {import("@modelcontextprotocol/sdk/server/mcp.js").McpServer} server
+ */
+export function registerTools(server) {
+
+  // Tool 1: analytics_query — wraps POST /mcp
+  server.tool(
+    "analytics_query",
+    "Query the data-mgr analytics API. Send a structured query with database, metric, parameters, and filters. Returns tabular results (columns + rows).",
+    {
+      db: z.string().optional().describe("Database group name (empty for default)"),
+      metric: z.string().describe("Metric or table name to query"),
+      params: z.record(z.any()).optional().describe("Query parameters (key-value pairs)"),
+      filters: z.record(z.string()).optional().describe("Filter conditions (key-value pairs)"),
+      limit: z.number().int().optional().describe("Max rows to return"),
+    },
+    async ({ db, metric, params, filters, limit }) => {
+      if (!hasValidToken()) {
+        return {
+          content: [{
+            type: "text",
+            text: "Error: Not logged in. Use the `check_auth` tool first, then run `login` if needed.",
+          }],
+          isError: true,
+        };
+      }
+      try {
+        const body = { metric };
+        if (db) body.db = db;
+        if (params) body.params = params;
+        if (filters) body.filters = filters;
+        if (limit != null) body.limit = limit;
+
+        const data = await apiRequest("/mcp", {
+          method: "POST",
+          body: JSON.stringify(body),
+        });
+
+        // Format response as readable text
+        const lines = [
+          `Query: db=${db ?? "(default)"}, metric=${metric}`,
+          `Columns: ${data.columns?.map(c => c.name ?? c).join(", ") || "(none)"}`,
+          `Rows: ${data.total ?? data.rows?.length ?? 0} (showing ${data.rows?.length ?? 0})`,
+          `Duration: ${data.duration_ms ?? "?"}ms`,
+        ];
+        if (data.message) lines.push(`Message: ${data.message}`);
+
+        // Table output
+        if (data.columns?.length && data.rows?.length) {
+          lines.push("");
+          const colNames = data.columns.map(c => c.name ?? c);
+          lines.push(colNames.join("\t"));
+          for (const row of data.rows) {
+            lines.push(colNames.map(k => row[k] ?? "").join("\t"));
+          }
+        }
+
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+      } catch (err) {
+        return {
+          content: [{ type: "text", text: `API Error: ${err.message}` }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // Tool 2: api_request — generic authenticated API request
+  server.tool(
+    "api_request",
+    "Make a generic authenticated API request to the data-mgr backend. Supports GET, POST, PUT, DELETE with optional JSON body and query parameters.",
+    {
+      method: z.enum(["GET", "POST", "PUT", "DELETE"]).describe("HTTP method"),
+      path: z.string().describe("API path, e.g. /api/v1/datasets"),
+      body: z.record(z.any()).optional().describe("JSON request body (for POST/PUT)"),
+      query: z.record(z.string()).optional().describe("Query parameters (key-value pairs)"),
+    },
+    async ({ method, path, body, query }) => {
+      if (!hasValidToken()) {
+        return {
+          content: [{
+            type: "text",
+            text: "Error: Not logged in. Use `check_auth` then `login`.",
+          }],
+          isError: true,
+        };
+      }
+      try {
+        const fullPath = `${path}${buildQuery(query)}`;
+        const init = { method };
+        if (body) init.body = JSON.stringify(body);
+
+        const data = await apiRequest(fullPath, init);
+        return {
+          content: [{
+            type: "text",
+            text: typeof data === "string" ? data : JSON.stringify(data, null, 2),
+          }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text", text: `API Error: ${err.message}` }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // Tool 3: check_auth — check login status
+  server.tool(
+    "check_auth",
+    "Check whether the user is logged in to data-mgr and the JWT token is valid. Returns login status, username, token expiry, and API URL.",
+    {},
+    async () => {
+      const cfg = loadConfig();
+      const apiUrl = getApiUrl();
+      const loggedIn = hasValidToken();
+
+      const expiresAt =
+        cfg.expiresAt ??
+        (cfg.expiresIn && cfg.loggedInAt
+          ? computeExpiresAt(cfg.expiresIn, new Date(cfg.loggedInAt))
+          : null);
+
+      const info = {
+        loggedIn,
+        apiUrl,
+        username: cfg.username ?? null,
+        userId: cfg.userId ?? null,
+        tenantId: cfg.tenantId ?? null,
+        expiresAt,
+        configPath: getConfigPath(),
+      };
+
+      if (!loggedIn) {
+        return {
+          content: [{
+            type: "text",
+            text: `Not logged in.\nAPI: ${apiUrl}\nRun the \`login\` tool or manually: data-mgr login\n\n${JSON.stringify(info, null, 2)}`,
+          }],
+        };
+      }
+
+      return {
+        content: [{
+          type: "text",
+          text: `Logged in as: ${cfg.username ?? "(unknown)"}\n\n${JSON.stringify(info, null, 2)}`,
+        }],
+      };
+    }
+  );
+
+  // Tool 4: login — trigger browser login flow
+  server.tool(
+    "login",
+    "Trigger the data-mgr browser login flow. Opens a browser window for the user to enter credentials. Returns login result on success. If browser cannot be opened, returns the URL for manual visit.",
+    {
+      openBrowser: z.boolean().optional().describe("Whether to open browser automatically (default true)"),
+    },
+    async ({ openBrowser }) => {
+      try {
+        const { runBrowserLogin } = await import("./login-server.js");
+
+        // Collect login URL from the callback
+        let loginUrl = "";
+        const result = await runBrowserLogin({
+          openBrowser: openBrowser !== false,
+          timeoutMs: 5 * 60 * 1000,
+          onLoginUrl: (url) => { loginUrl = url; },
+        });
+
+        const expiresAt = computeExpiresAt(result.expiresIn, new Date(result.loggedInAt));
+
+        saveConfig({
+          token: result.token,
+          username: result.username,
+          userId: result.userId,
+          tenantId: result.tenantId,
+          expiresIn: result.expiresIn,
+          expiresAt,
+          loggedInAt: result.loggedInAt,
+        });
+
+        const lines = [
+          `Logged in as: ${result.username ?? "(unknown)"}`,
+          `User ID: ${result.userId}`,
+          `Tenant ID: ${result.tenantId}`,
+          `Token saved to: ${getConfigPath()}`,
+          `Expires: ${expiresAt ?? "(unknown)"}`,
+        ];
+        if (loginUrl) lines.unshift(`Login URL: ${loginUrl}`);
+
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+      } catch (err) {
+        return {
+          content: [{ type: "text", text: `Login failed: ${err.message}` }],
+          isError: true,
+        };
+      }
+    }
+  );
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@wsh19991219/mcp-server",
+  "version": "0.1.1",
+  "description": "MCP server for Data Manager API — stdio transport, JWT auth",
+  "type": "module",
+  "main": "lib/tools.js",
+  "bin": {
+    "data-mgr-mcp": "bin/data-mgr-mcp.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "skills",
+    "SKILL.md",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0"
+  },
+  "scripts": {
+    "start": "node bin/data-mgr-mcp.js"
+  }
+}

package/skills/daily-channel-report/SKILL.md

@@ -0,0 +1,94 @@
+---
+
+## name: daily-channel-report
+description: 渠道交易日报：按固定口径查昨日数据、输出【最终结论】
+triggers:
+  - 日报
+  - 每日报表
+  - 定时报表
+  - 昨日交易
+  - daily report
+  - 交易汇总
+
+## 适用场景
+
+用户或定时任务要求生成**某一渠道、某一自然日**的交易汇总（笔数、金额、趋势等）。
+
+## 固定流程（必须按序）
+
+### 1. 确认参数
+
+- 渠道：`channel_id=1` Photon · `2` Interlace · `3` PingPong
+- 日期：默认**昨天**（自然日）
+- 数据库 group：默认 `default`，用户指定则用对应 group
+
+定时任务已写明参数时勿重复追问。
+
+### 2. 鉴权
+
+```
+check_auth → 未登录则 login
+```
+
+### 3. 定位表
+
+```
+api_request: GET /api/v1/analytics/schema?q=<渠道关键词>&db=<group>
+api_request: GET /api/v1/analytics/schema?tables=<目标表>&db=<group>
+```
+
+渠道表名参考：
+
+- channel_id=1 → `photonpay_card_transaction`
+- channel_id=2 → `interlace_card_transaction`
+- channel_id=3 → `pingpong_card_transaction`
+
+### 4. 查数
+
+```
+analytics_query:
+  metric: "<指标>"           # 或用 api_request SQL
+  db: "<group>"
+  filters: { "channel_id": "<N>", "date": "<YYYY-MM-DD>" }
+```
+
+或自定义 SQL：
+
+```
+api_request: POST /api/v1/analytics/sql
+  body:
+    db: "<group>"
+    sql: "SELECT COUNT(*) AS cnt, SUM(<主金额字段>) AS total FROM <表> WHERE channel_id = <N> AND DATE(create_time) = '<日期>'"
+```
+
+**禁止未调用工具就写具体数字。**
+
+### 5. 交付
+
+用 **【最终结论】** 标题，包含：
+
+- 日期、渠道、数据库 group
+- 笔数、金额（注明 USD 口径字段名）
+- 1~2 条洞察（趋势、异常、占比）
+- 如有空值/异常数据，注明条数
+
+## 金额口径
+
+
+| 渠道          | 主金额字段                         |
+| ----------- | ----------------------------- |
+| 1 photon    | `txn_principal_change_amount` |
+| 2 interlace | `transaction_amount`          |
+| 3 pingpong  | `billing_amount`              |
+
+
+## 日期占位
+
+用户或外部编排可在提示词中使用 `{{today}}`、`{{yesterday}}`；由调用方在传入前展开。
+
+## 禁止
+
+- 索要 JWT / token
+- 编造未出现在 tool_result 中的数字
+- 用错主金额字段（见上表）
+

package/skills/data-analysis/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: data-analysis
+description: 数据分析师流程：六步检查清单 + 三阶段取数；含渠道术语与 USD 金额口径
+triggers:
+  - 数据分析
+  - 对账
+  - 报表
+  - 漏斗
+  - 留存
+  - 流失
+  - 渠道对比
+  - 趋势
+  - 同比
+  - 环比
+---
+
+## 适用场景
+
+查业务数据、对账、报表、指标含义、漏斗/留存类分析。简单查数请用 `data-query` Skill。
+
+## 任务分级（先判断再动手）
+
+| 类型 | 识别 | 执行方式 |
+|------|------|----------|
+| **A 单点查数** | 一句问金额/笔数/某日统计 | 仅三阶段 |
+| **B 对账/渠道对比** | 两源差异、多 channel_id | 三阶段 + 对账模板 |
+| **C 探索/漏斗/报告** | 留存、流失、多维对比 | 三阶段 + 六步中间产物 |
+
+## 六步检查清单
+
+| 步 | 目标 | 手段 | 交付物 |
+|:--:|------|------|--------|
+| 1 | **明确目标** | 澄清或复述需求 | 分析对象、时间范围、指标定义 |
+| 2 | 数据收集 | `api_request` catalog → schema → query/sql | 用了哪些表/指标；0 行须说明 |
+| 3 | 数据处理 | SQL WHERE/JOIN/去重/口径过滤 | 过滤条件、去重规则、主金额字段名 |
+| 4 | 探索 EDA | 分组、趋势、同比 | 至少 2 个维度 |
+| 5 | 建模（可选） | SQL 聚合或可解释对比 | 无模型则跳过 |
+| 6 | **呈现报告** | 结构化中文结论 | 现状 → 洞察 → 建议 |
+
+## 连贯三阶段执行
+
+### 阶段 0：澄清（缺参时）
+
+时间窗、平台/`channel_id`、`db=` 部署库等缺失时，**必须**列出 2~4 个候选让用户选择。禁止猜默认值。
+
+### 阶段 1：定位（数据模型）
+
+```
+check_auth → login（如需）
+api_request: GET /api/v1/analytics/catalog              # 看可用指标和数据库
+api_request: GET /api/v1/analytics/schema?q=<关键词>     # 搜表
+api_request: GET /api/v1/analytics/schema?tables=<表名>  # 看列名与类型
+```
+
+确认渠道层级与主金额列。
+
+### 阶段 2：画像（样例 + 汇总）
+
+在写业务结论 SQL **之前**必须：
+
+```
+api_request: POST /api/v1/analytics/sql
+  body: { "sql": "SELECT 关键列 FROM 表 LIMIT 10", "db": "<group>" }    -- 样例
+
+api_request: POST /api/v1/analytics/sql
+  body: { "sql": "SELECT COUNT(*), AVG(x), MIN(x), MAX(x) FROM 表", "db": "<group>" }  -- 汇总
+```
+
+先列出各列类型印象与汇总表，再进入分析。
+
+### 阶段 3：分析 + 交付
+
+```
+analytics_query: { metric: "...", db: "...", params: {...}, filters: {...} }
+-- 或 --
+api_request: POST /api/v1/analytics/sql
+  body: { "sql": "SELECT ...", "db": "<group>", "limit": 100 }
+```
+
+交付格式：**现状 → 洞察 → 建议**，附局限说明。
+
+## 任务模板
+
+### 对账（类型 B）
+
+1. 复述：对账双方、时间窗、channel_id、主金额字段
+2. 分别查询两边汇总，SQL 注释写对齐键
+3. 交付：**差额、可能原因、未对齐条数**
+
+### 渠道对比（类型 B）
+
+1. 每个 channel_id 独立 SELECT + 正确主金额列
+2. EDA：至少「合计 + 按日或按状态」两维
+3. 交付：表格对比 + 占比
+
+### 漏斗/留存（类型 C）
+
+1. 明确漏斗步骤或留存定义
+2. `api_request` schema 找行为/表 → SQL 分步计数
+3. 交付：各步转化率 + 流失最大节点 + 建议
+
+## 渠道术语
+
+| 层级 | 取值 |
+|------|------|
+| 部署库 | `default` 主库, `prod_vn` 越南, `prod_vero` Vero, `prod_zenia` Zenia, `prod_jtpay` JT Pay |
+| 渠道编号 | 1=photon, 2=interlace, 3=pingpong |
+
+## 金额口径（USD）
+
+| 渠道 | 主金额字段 |
+|:----:|------------|
+| 1 | `txn_principal_change_amount` |
+| 2 | `transaction_amount` |
+| 3 | `billing_amount` |
+
+## 禁止
+
+- 未调用工具就给出具体数字
+- 编造未出现在 tool_result 中的数字
+- 索要 JWT / token
+- 为同一问题重复搜 schema

package/skills/data-query/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: data-query
+description: 数据查询：查指标、查数据、执行预定义 metric 查询或自定义只读 SQL
+triggers:
+  - 数据查询
+  - 查数据
+  - 指标
+  - 统计
+  - 多少笔
+  - 多少钱
+  - 金额
+  - 笔数
+  - sql
+  - SQL
+  - query
+  - analytics
+---
+
+## 适用场景
+
+用户问业务数据：金额、笔数、统计、指标值。本 Skill 覆盖两种取数方式：预定义指标查询 和 自定义 SQL。
+
+## 固定流程
+
+### 1. 鉴权检查
+
+```
+check_auth → 未登录则 login
+```
+
+### 2. 定位数据（先搞清楚查什么）
+
+**查看可用指标：**
+```
+api_request: GET /api/v1/analytics/catalog
+```
+返回 `metrics`（可用指标列表）和 `databases`（可用数据库 group）。
+
+**查看表结构（如需 SQL）：**
+```
+api_request: GET /api/v1/analytics/schema?q=<关键词>&db=<group>
+api_request: GET /api/v1/analytics/schema?tables=<表名>&db=<group>
+```
+
+### 3. 取数（二选一）
+
+**方式 A — 预定义指标查询：**
+```
+analytics_query:
+  metric: "<指标ID>"
+  db: "<group>"          # 可选
+  params: { ... }        # 可选，指标参数
+  filters: { ... }       # 可选，过滤条件
+  limit: 100             # 可选
+```
+
+**方式 B — 自定义 SQL：**
+```
+api_request:
+  method: POST
+  path: /api/v1/analytics/sql
+  body:
+    db: "<group>"        # 可选
+    sql: "SELECT ..."
+    limit: 100           # 可选，默认 100，最大 500
+```
+
+SQL 限制：
+- 仅允许 SELECT / WITH（只读）
+- 禁止 DML（INSERT/UPDATE/DELETE）
+- 禁止注释（`--`、`/* */`）
+- 禁止多语句（`;` 分隔）
+- 最大 16KB
+
+### 4. 交付
+
+- 数字必须来自 tool_result，禁止编造
+- 0 行结果须说明「未查到数据」
+- 标注使用的 db group 和主金额字段名
+- 敏感数据（手机/身份证/邮箱等）会被自动脱敏
+
+## 渠道术语
+
+| 层级 | 含义 | 取值 |
+|------|------|------|
+| 部署/区域 | 独立数据库实例 | `db=default` 主库；`db=prod_vn` 越南；`db=prod_vero` Vero；`db=prod_zenia` Zenia；`db=prod_jtpay` JT Pay |
+| 支付平台 | 第三方品牌 | photon, pingpong, interlace |
+| 渠道编号 | channel_id | 1=photon, 2=interlace, 3=pingpong |
+
+## 金额统计口径（USD）
+
+| 渠道 | 主金额字段 | 禁止替代 |
+|:----:|------------|----------|
+| 1 photon | `txn_principal_change_amount` | `transaction_amount` / `amount` / `arrival_amount` |
+| 2 interlace | `transaction_amount` | `billing_amount` |
+| 3 pingpong | `billing_amount` | `transaction_amount` |
+
+## 注意
+
+- 未调用工具就给出具体数字是**严格禁止**的
+- 主字段为空时报告空值条数，勿静默换列凑数
+- 跨渠道汇总时分渠道取主金额字段再相加，禁止三渠道共用同一列名

package/skills/schema-explorer/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: schema-explorer
+description: 数据库表结构探索：模糊搜表名、查看列详情、了解数据模型
+triggers:
+  - 查表
+  - 表结构
+  - 搜表
+  - 有哪些表
+  - 字段
+  - 列名
+  - schema
+  - tables
+  - 数据库结构
+  - INFORMATION_SCHEMA
+---
+
+## 适用场景
+
+用户想了解数据库有哪些表、某张表的字段结构、按关键词搜索相关表。
+
+## 固定流程
+
+### 1. 鉴权检查
+
+```
+check_auth → 未登录则 login
+```
+
+### 2. 搜索表（模糊查找）
+
+用 `api_request` 调 REST 端点：
+
+```
+api_request: GET /api/v1/analytics/schema?q=<关键词>&db=<group>&limit=50
+```
+
+参数说明：
+- `q` — 模糊搜表名/表注释（最多 64 字符，禁 `% _ ;` 等特殊字符）
+- `db` — 数据库 group，空则 default（可选值：`prod_vn`, `prod_vero`, `prod_zenia`, `prod_jtpay`）
+- `limit` — 最多返回表数，默认 50，最大 100
+
+### 3. 查看表列结构（精确查找）
+
+搜到目标表后，用精确表名查列：
+
+```
+api_request: GET /api/v1/analytics/schema?tables=<表名1>,<表名2>&db=<group>
+```
+
+返回每张表的：列名、类型、是否可空、默认值、注释、键类型。
+
+### 4. 交付格式
+
+- 列出表名 + 注释 + 预估行数
+- 对关键表列出列名、类型、注释
+- 标注主键和敏感列
+- 如发现渠道相关表，提醒用户 channel_id 含义：1=photon, 2=interlace, 3=pingpong
+
+## 注意
+
+- `q` 参数禁止 `% _ ;` 等特殊字符
+- 单次搜索最多返回 100 张表
+- 结果可能有缓存延迟（schema 缓存周期取决于服务端配置）