cq-mcp-server 0.1.0

package/README.md

@@ -0,0 +1,158 @@
+# CloudQuery MCP Server 使用指南
+
+本 MCP Server 连接 CloudQuery 平台，提供四个工具，让 AI 能够探索数据库结构并执行 SQL 查询。
+
+## 工具调用顺序
+
+```
+list_databases → list_tables → get_table_columns → execute_sql
+```
+
+**必须按顺序调用**：后续工具所需的 `connection_id`、`connection_type`、`database`、`schema` 参数，都只能从前面的工具返回结果中获取，不能凭空猜测。
+
+---
+
+## 工具详解
+
+### 1. `list_databases` — 查询数据库清单
+
+**无需任何参数。**
+
+返回所有数据库连接及其下的数据库列表，格式如下：
+
+```
+## 连接: pg-prod  (connection_id=1, connection_type=PostgreSQL)
+  - pam
+  - postgres
+```
+
+**从返回结果中记录：**
+- `connection_id`（数字）
+- `connection_type`（字符串，如 `PostgreSQL`）
+- 目标数据库名称（如 `pam`）
+
+---
+
+### 2. `list_tables` — 查询表清单
+
+**参数（全部必填）：**
+
+| 参数 | 来源 | 说明 |
+|------|------|------|
+| `connection_id` | list_databases 返回 | 数字 |
+| `connection_type` | list_databases 返回 | 如 `PostgreSQL` |
+| `database` | list_databases 返回 | 数据库名，如 `pam` |
+| `schema` | 推断或尝试 | PostgreSQL 常用 `public` 或与库同名（如 `pam`）；若 `public` 无结果，改用库名 |
+
+返回该 schema 下所有表名列表。
+
+**从返回结果中记录：** 目标表名（如 `auth_role`）
+
+---
+
+### 3. `get_table_columns` — 查询表字段
+
+**参数（全部必填）：**
+
+| 参数 | 来源 |
+|------|------|
+| `connection_id` | list_databases |
+| `connection_type` | list_databases |
+| `database` | list_databases |
+| `schema` | list_tables 调用时使用的 schema |
+| `table` | list_tables 返回 |
+
+返回字段名、数据类型、长度、是否可空、业务注释，格式：
+
+```
+字段名                    类型            长度     可空   注释
+---------------------------------------------------------------------------
+id                        int8            19       否     主键
+role_name                 varchar         64       否     角色名称
+role_code                 varchar         32       否     角色编码
+```
+
+**从返回结果中记录：** 字段名列表，用于编写 SQL。
+
+---
+
+### 4. `execute_sql` — 执行 SQL
+
+**参数：**
+
+| 参数 | 来源 | 说明 |
+|------|------|------|
+| `connection_id` | list_databases | |
+| `connection_type` | list_databases | 默认 `PostgreSQL` |
+| `database` | list_databases | |
+| `schema` | 同 list_tables | 作为 SQL 的 search_path |
+| `sql` | 根据字段结构编写 | 一次只执行一条语句 |
+
+**SELECT 返回格式：**
+```
+id | role_name | role_code | description
+----------------------------------------
+1  | 超级管理员  | SUPER_ADMIN | 系统最高权限
+2  | 普通用户   | USER        | 默认角色
+
+共 8 行  耗时 12ms
+```
+
+**DML 返回格式：**
+```
+执行成功
+影响行数: 1
+耗时: 5ms
+```
+
+---
+
+## 典型场景：查询角色表数据
+
+以下是完整的 6 步流程示例：
+
+**Step 1** — 调用 `list_databases`（无参数）
+- 获得：`connection_id=1, connection_type=PostgreSQL`，数据库列表包含 `pam`
+
+**Step 2** — 调用 `list_tables`
+```json
+{ "connection_id": 1, "connection_type": "PostgreSQL", "database": "pam", "schema": "pam" }
+```
+- 获得：表列表，找到 `auth_role`
+
+**Step 3** — 调用 `get_table_columns`
+```json
+{ "connection_id": 1, "connection_type": "PostgreSQL", "database": "pam", "schema": "pam", "table": "auth_role" }
+```
+- 获得：字段列表 `id, role_name, role_code, description, ...`
+
+**Step 4** — 根据字段编写 SQL：
+```sql
+SELECT id, role_name, role_code, description FROM pam.auth_role LIMIT 20
+```
+
+**Step 5** — 调用 `execute_sql`
+```json
+{
+  "connection_id": 1,
+  "connection_type": "PostgreSQL",
+  "database": "pam",
+  "schema": "pam",
+  "sql": "SELECT id, role_name, role_code, description FROM pam.auth_role LIMIT 20"
+}
+```
+- 获得：查询结果
+
+---
+
+## 注意事项
+
+1. **schema 选择**：PostgreSQL 数据库的 schema 名通常与数据库同名（如数据库 `pam` 对应 schema `pam`），而不是 `public`。若 `public` 无结果，改用数据库名作为 schema。
+
+2. **单条执行**：`execute_sql` 每次只能执行一条 SQL 语句，不支持批量执行。
+
+3. **结果上限**：SELECT 查询最多返回 500 行。
+
+4. **SQL 写法**：建议在表名前加 schema 前缀（如 `pam.auth_role`），避免歧义。
+
+5. **参数不能猜测**：`connection_id` 和 `connection_type` 必须通过 `list_databases` 获取，不能假设固定值。

package/dist/index.js

@@ -0,0 +1,279 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import forge from "node-forge";
+const BASE_URL = process.env.CQ_BASE_URL ?? "http://10.10.2.73";
+const USERNAME = process.env.CQ_USERNAME ?? "admin001";
+const PASSWORD = process.env.CQ_PASSWORD ?? "Hello123$";
+// MCP 协议通过 stdio 通信，日志必须输出到 stderr 避免污染 stdout
+const log = {
+    info: (...args) => process.stderr.write(`[INFO]  ${args.join(" ")}\n`),
+    warn: (...args) => process.stderr.write(`[WARN]  ${args.join(" ")}\n`),
+    error: (...args) => process.stderr.write(`[ERROR] ${args.join(" ")}\n`),
+};
+let sessionCookie = null;
+// ── 认证 ──────────────────────────────────────────────────────────
+/** 用 RSA 公钥加密密码（与前端 JSEncrypt 行为一致） */
+function encryptPassword(publicKeyB64, password) {
+    const derBytes = forge.util.decode64(publicKeyB64);
+    const asn1 = forge.asn1.fromDer(derBytes);
+    const publicKey = forge.pki.publicKeyFromAsn1(asn1);
+    const encrypted = publicKey.encrypt(password, "RSAES-PKCS1-V1_5");
+    return forge.util.encode64(encrypted);
+}
+async function login() {
+    log.info(`登录 ${BASE_URL}，用户: ${USERNAME}`);
+    const keyResp = await fetch(`${BASE_URL}/user/sys/transmission/publicKey`);
+    if (!keyResp.ok)
+        throw new Error(`获取公钥失败: HTTP ${keyResp.status}`);
+    const keyData = (await keyResp.json());
+    if (keyData.resCode !== 10000)
+        throw new Error(`获取公钥异常: ${keyData.resCode}`);
+    const encryptedPassword = encryptPassword(keyData.data.publicKey, PASSWORD);
+    const resp = await fetch(`${BASE_URL}/user/login`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ userId: USERNAME, password: encryptedPassword }),
+    });
+    if (!resp.ok)
+        throw new Error(`登录请求失败: HTTP ${resp.status}`);
+    const data = (await resp.json());
+    if (data.resCode !== 10000)
+        throw new Error(`登录失败: ${data.resMsg}`);
+    // SESSION cookie = base64(sessionId)
+    const sid = data.data?.sessionId;
+    if (sid) {
+        sessionCookie = Buffer.from(sid).toString("base64");
+        log.info("登录成功");
+        return;
+    }
+    const setCookie = resp.headers.get("set-cookie") ?? "";
+    const match = setCookie.match(/SESSION=([^;]+)/);
+    if (match) {
+        sessionCookie = match[1];
+        log.info("登录成功（cookie）");
+    }
+    else {
+        throw new Error("登录成功但未获取到 SESSION");
+    }
+}
+// ── HTTP 封装 ─────────────────────────────────────────────────────
+async function post(path, body) {
+    if (!sessionCookie)
+        await login();
+    const resp = await fetch(`${BASE_URL}${path}`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Cookie: `SESSION=${sessionCookie}`,
+        },
+        body: JSON.stringify(body),
+    });
+    if (resp.status === 401 || resp.status === 403) {
+        log.warn("Session 已过期，重新登录...");
+        sessionCookie = null;
+        await login();
+        return post(path, body);
+    }
+    if (!resp.ok)
+        throw new Error(`HTTP ${resp.status} ${path}`);
+    const result = (await resp.json());
+    if (result.resCode !== 10000)
+        throw new Error(`[${result.resCode}] ${result.resMsg}`);
+    return result.data;
+}
+async function metaNode(payload) {
+    const data = await post("/dms/meta/node", {
+        ...payload,
+        globalHavePermissionFlag: false,
+    });
+    return data?.data ?? [];
+}
+// ── MCP Server ────────────────────────────────────────────────────
+const server = new McpServer({
+    name: "cq-mcp-server",
+    version: "0.1.0",
+});
+// ── 工具一：查询数据库清单 ─────────────────────────────────────────
+server.tool("list_databases", `查询所有数据库连接及其下的数据库实例列表。
+
+用途：了解当前 CloudQuery 平台上有哪些数据库连接，以及每个连接下有哪些数据库。
+返回：连接名称、连接ID、数据库类型，以及每个连接下的数据库列表。
+后续：拿到 connection_id 和 connection_type 后，可调用 list_tables 查看具体库的表。`, {}, async () => {
+    log.info("list_databases: 查询连接列表");
+    const connections = await metaNode({ nodeType: "root", nodePath: "/root" });
+    if (!connections.length)
+        return { content: [{ type: "text", text: "未找到任何数据库连接" }] };
+    const lines = [];
+    for (const conn of connections) {
+        const { connectionId, connectionType, nodeName } = conn;
+        lines.push(`## 连接: ${nodeName}  (connection_id=${connectionId}, connection_type=${connectionType})`);
+        const databases = await metaNode({
+            nodeType: "connection",
+            nodePath: `/root/${connectionId}`,
+            nodePathWithType: `/CONNECTION:${connectionId}`,
+            connectionId,
+            connectionType,
+        });
+        log.info(`  └─ ${nodeName}: ${databases.length} 个数据库`);
+        if (databases.length) {
+            for (const db of databases)
+                lines.push(`  - ${db.nodeName}`);
+        }
+        else {
+            lines.push("  (无数据库)");
+        }
+        lines.push("");
+    }
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+});
+// ── 工具二：查询表清单 ────────────────────────────────────────────
+server.tool("list_tables", `查询指定数据库 Schema 下的所有普通表。
+
+用途：了解某个数据库 Schema 下有哪些表，为后续字段查询或 SQL 编写做准备。
+参数说明：
+  - connection_id / connection_type：从 list_databases 获取
+  - database：数据库名称（如 pam、postgres）
+  - schema：Schema 名称，PostgreSQL 常用 public 或与库同名的 schema（如 pam）
+返回：表名列表及总数。
+后续：用 get_table_columns 查看具体表的字段结构。`, {
+    connection_id: z.number().describe("数据库连接ID，从 list_databases 获取"),
+    connection_type: z.string().describe("数据库类型，如 PostgreSQL、MySQL，从 list_databases 获取"),
+    database: z.string().describe("数据库名称，如 pam、postgres"),
+    schema: z.string().default("public").describe("Schema 名称，PostgreSQL 默认 public"),
+}, async ({ connection_id, connection_type, database, schema }) => {
+    log.info(`list_tables: ${database}.${schema} (conn=${connection_id})`);
+    const tables = await metaNode({
+        nodeType: "tableGroup",
+        nodePath: `/root/${connection_id}/${database}/${schema}/tables`,
+        nodePathWithType: `/CONNECTION:${connection_id}/DATABASE:${database}/SCHEMA:${schema}`,
+        connectionId: connection_id,
+        connectionType: connection_type,
+    });
+    if (!tables.length) {
+        return { content: [{ type: "text", text: `${database}.${schema} 下未找到任何表` }] };
+    }
+    log.info(`  └─ 共 ${tables.length} 张表`);
+    const lines = [`${database}.${schema} 共 ${tables.length} 张表：`, ""];
+    for (const t of tables)
+        lines.push(`- ${t.nodeName}`);
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+});
+// ── 工具三：查询表字段 ────────────────────────────────────────────
+server.tool("get_table_columns", `查询指定表的完整字段定义，包括字段名、数据类型、长度、是否可空、业务注释。
+
+用途：了解表结构，辅助编写精确的 SQL 查询语句。
+参数说明：
+  - connection_id / connection_type：从 list_databases 获取
+  - database / schema：从 list_databases 获取
+  - table：从 list_tables 获取
+返回：字段名、数据类型（如 int8/varchar/timestamp）、长度、是否可空（是/否）、字段注释。`, {
+    connection_id: z.number().describe("数据库连接ID，从 list_databases 获取"),
+    connection_type: z.string().describe("数据库类型，如 PostgreSQL、MySQL"),
+    database: z.string().describe("数据库名称"),
+    schema: z.string().describe("Schema 名称"),
+    table: z.string().describe("表名，从 list_tables 获取"),
+}, async ({ connection_id, connection_type, database, schema, table }) => {
+    log.info(`get_table_columns: ${database}.${schema}.${table} (conn=${connection_id})`);
+    const columns = await metaNode({
+        nodeType: "columnGroup",
+        nodePath: `/root/${connection_id}/${database}/${schema}/tables/${table}/columns`,
+        nodePathWithType: `/CONNECTION:${connection_id}/DATABASE:${database}/SCHEMA:${schema}/TABLE:${table}`,
+        connectionId: connection_id,
+        connectionType: connection_type,
+    });
+    if (!columns.length) {
+        return { content: [{ type: "text", text: `表 ${database}.${schema}.${table} 未找到字段信息` }] };
+    }
+    log.info(`  └─ ${columns.length} 个字段`);
+    const lines = [
+        `表 ${database}.${schema}.${table}  共 ${columns.length} 个字段：`,
+        "",
+        `${"字段名".padEnd(25)} ${"类型".padEnd(15)} ${"长度".padEnd(8)} ${"可空".padEnd(6)} 注释`,
+        "-".repeat(75),
+    ];
+    for (const col of columns) {
+        const opts = col.nodeOptions ?? {};
+        lines.push(`${col.nodeName.padEnd(25)} ${(opts.dataType ?? "").padEnd(15)} ${(opts.dataLength ?? "").padEnd(8)} ${(opts.isNullable ? "是" : "否").padEnd(6)} ${opts.comments ?? ""}`);
+    }
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+});
+// ── 工具四：执行 SQL ──────────────────────────────────────────────
+server.tool("execute_sql", `在指定数据库上执行 SQL 语句，返回查询结果或执行状态。
+
+用途：直接运行 SQL 查询数据，或执行 DML（INSERT/UPDATE/DELETE）操作。
+参数说明：
+  - connection_id / connection_type：从 list_databases 获取
+  - database：数据库名称
+  - schema：SQL 执行的默认 Schema 上下文（即 search_path），默认 public
+  - sql：SQL 语句，支持 SELECT / INSERT / UPDATE / DELETE
+返回：
+  - SELECT：列名表头 + 数据行（最多返回 500 行），以及总行数和执行耗时
+  - DML：影响行数和执行耗时
+  - 错误：具体错误信息
+注意：一次只执行一条 SQL 语句。`, {
+    connection_id: z.number().describe("数据库连接ID，从 list_databases 获取"),
+    connection_type: z.string().default("PostgreSQL").describe("数据库类型，如 PostgreSQL、MySQL"),
+    database: z.string().describe("数据库名称"),
+    schema: z.string().default("public").describe("执行 SQL 的默认 Schema，默认 public"),
+    sql: z.string().describe("SQL 语句，一次执行一条"),
+}, async ({ connection_id, connection_type, database, schema, sql }) => {
+    const tabKey = `mcp-${Date.now()}`;
+    const preview = sql.length > 60 ? sql.slice(0, 60) + "..." : sql;
+    log.info(`execute_sql: [${database}.${schema}] ${preview}`);
+    const data = await post("/dms/segment/statement/blocking/execute", {
+        connectionId: connection_id,
+        dataSourceType: connection_type,
+        databaseName: database,
+        operatingObject: schema,
+        statements: [sql],
+        offset: 0,
+        rowCount: 500,
+        tabKey,
+        plSql: false,
+        sortModels: null,
+        filterModel: null,
+        autoCommit: false,
+        actionType: null,
+    });
+    const infos = data?.executionInfos ?? [];
+    const lines = [];
+    for (const info of infos) {
+        const log_msg = info.executeLogInfo?.message;
+        const resp = info.response;
+        if (!resp?.success) {
+            const errMsg = resp?.executeError?.message ?? log_msg?.error ?? "执行失败";
+            log.error(`SQL 执行失败: ${errMsg}`);
+            lines.push(`错误: ${errMsg}`);
+            continue;
+        }
+        // DML（无结果集）
+        if (!resp.resultData?.length) {
+            const affected = log_msg?.affectedRows ?? 0;
+            const ms = log_msg?.duration ?? 0;
+            log.info(`  └─ 执行成功，影响 ${affected} 行，${ms}ms`);
+            lines.push(`执行成功\n影响行数: ${affected}\n耗时: ${ms}ms`);
+            continue;
+        }
+        // SELECT
+        const resultData = resp.resultData;
+        const colInfos = resp.columnInfos ?? [];
+        const colNames = colInfos.length
+            ? colInfos.map((c) => c.columnName)
+            : Object.keys(resultData[0]);
+        const ms = log_msg?.duration ?? 0;
+        log.info(`  └─ 返回 ${resultData.length} 行，${ms}ms`);
+        lines.push(colNames.join(" | "));
+        lines.push("-".repeat(Math.max(colNames.join(" | ").length, 20)));
+        for (const row of resultData) {
+            lines.push(colNames.map((col) => String(row[col]?.value ?? "")).join(" | "));
+        }
+        lines.push(`\n共 ${resultData.length} 行  耗时 ${ms}ms`);
+    }
+    return { content: [{ type: "text", text: lines.join("\n") || "无输出" }] };
+});
+// ── 启动 ──────────────────────────────────────────────────────────
+log.info(`CloudQuery MCP Server 启动  BASE_URL=${BASE_URL}  USER=${USERNAME}`);
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "cq-mcp-server",
+  "version": "0.1.0",
+  "description": "MCP Server for CloudQuery platform — list databases, list tables, inspect columns, and execute SQL via MCP tools.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "cq-mcp-server": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "cloudquery",
+    "database",
+    "sql",
+    "model-context-protocol"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "node-forge": "^1.3.3",
+    "zod": "^4.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.2",
+    "@types/node-forge": "^1.3.14",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}