@harneon-ai/db 0.0.1

package/README.md

@@ -0,0 +1,338 @@
+# Harneon DB MCP Server
+
+一个 MCP (Model Context Protocol) Server，为 AI 助手提供只读的 PostgreSQL 数据库元数据查询能力，支持 ShardingSphere 风格的多数据源分片拓扑解析。
+
+## 功能概览
+
+- 查看多数据源配置信息
+- 查询任意数据源的表列表、表结构、索引信息
+- 解析 ShardingSphere 分片拓扑（逻辑表 → 实际数据节点映射）
+- 执行自定义元数据查询（仅允许 information_schema / pg_catalog）
+- 多层安全防护，严禁任何数据写入和业务数据读取
+
+## 快速开始
+
+### 1. 全局安装
+
+```bash
+npm install -g @harneon-ai/db
+```
+
+### 2. 在 Claude Desktop 中使用
+
+编辑 Claude Desktop 配置文件（`claude_desktop_config.json`）：
+
+```json
+{
+  "mcpServers": {
+    "harneon-db": {
+      "command": "harneon-db"
+    }
+  }
+}
+```
+
+### 3. 在 Claude Code 中使用
+
+```bash
+claude mcp add harneon-db -- harneon-db
+```
+
+### 4. 配置数据源
+
+配置文件默认保存在 `~/.harneon-ai/db/datasource.yaml`。
+
+你可以手动创建该文件，也可以启动后通过 `save_datasource_config` 工具添加数据源（目录会自动创建）。
+
+如需使用自定义配置路径：
+
+```bash
+harneon-db /path/to/datasource.yaml
+```
+
+或通过环境变量：
+
+```bash
+DB_CONFIG_PATH=/path/to/datasource.yaml harneon-db
+```
+
+### 5. 开发模式运行
+
+```bash
+npm run dev
+```
+
+## 配置文件格式
+
+配置文件采用 YAML 格式，兼容 ShardingSphere 配置：
+
+```yaml
+dataSources:
+  ds_0:
+    dataSourceClassName: com.zaxxer.hikari.HikariDataSource
+    driverClassName: org.postgresql.Driver
+    jdbcUrl: jdbc:postgresql://localhost:5432/shop_db_0
+    username: postgres
+    password: your_password
+  ds_1:
+    jdbcUrl: jdbc:postgresql://localhost:5432/shop_db_1
+    username: postgres
+    password: your_password
+
+rules:
+  - !SHARDING
+    tables:
+      tbl_order:
+        actualDataNodes: ds_$->{0..1}.tbl_order_$->{0..3}
+        tableStrategy:
+          standard:
+            shardingColumn: order_id
+            shardingAlgorithmName: tbl_order_inline
+    defaultShardingColumn: corporation_id
+    defaultDatabaseStrategy:
+      standard:
+        shardingColumn: corporation_id
+        shardingAlgorithmName: database_inline
+    shardingAlgorithms:
+      database_inline:
+        type: INLINE
+        props:
+          algorithm-expression: ds_$->{corporation_id % 2}
+      tbl_order_inline:
+        type: INLINE
+        props:
+          algorithm-expression: tbl_order_$->{order_id % 4}
+```
+
+配置路径优先级：命令行参数 > `DB_CONFIG_PATH` 环境变量 > `~/.harneon-ai/db/datasource.yaml`
+
+## MCP Tools 说明
+
+### list_datasources
+
+列出所有已配置的数据源信息。密码字段显示为 `***`。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| （无参数） | | | |
+
+返回示例：
+
+```json
+[
+  {
+    "name": "ds_0",
+    "host": "localhost",
+    "port": 5432,
+    "database": "shop_db_0",
+    "username": "postgres",
+    "password": "***"
+  }
+]
+```
+
+### list_tables
+
+列出指定数据源中的所有用户表和视图。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| datasource | string | 是 | 数据源名称，如 `ds_0` |
+| schema | string | 否 | Schema 名称，默认 `public` |
+
+返回示例：
+
+```json
+[
+  { "table_name": "tbl_order_0", "table_type": "BASE TABLE" },
+  { "table_name": "tbl_order_1", "table_type": "BASE TABLE" }
+]
+```
+
+### describe_table
+
+查询指定表的详细结构，包含列信息、约束和统计数据。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| datasource | string | 是 | 数据源名称 |
+| table | string | 是 | 表名 |
+| schema | string | 否 | Schema 名称，默认 `public` |
+
+返回示例：
+
+```json
+{
+  "columns": [
+    {
+      "column_name": "id",
+      "data_type": "bigint",
+      "is_nullable": "NO",
+      "column_default": "nextval('tbl_order_0_id_seq'::regclass)",
+      "character_maximum_length": null,
+      "ordinal_position": 1,
+      "comment": "主键ID"
+    }
+  ],
+  "constraints": [
+    {
+      "constraint_name": "tbl_order_0_pkey",
+      "constraint_type": "PRIMARY KEY",
+      "columns": "id"
+    }
+  ],
+  "stats": {
+    "estimated_rows": 15000,
+    "total_size": "2048 kB",
+    "table_size": "1536 kB",
+    "index_size": "512 kB"
+  }
+}
+```
+
+### describe_indexes
+
+查询指定表的所有索引信息。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| datasource | string | 是 | 数据源名称 |
+| table | string | 是 | 表名 |
+| schema | string | 否 | Schema 名称，默认 `public` |
+
+返回示例：
+
+```json
+[
+  {
+    "index_name": "tbl_order_0_pkey",
+    "index_columns": "id",
+    "is_unique": true,
+    "index_method": "btree",
+    "index_definition": "CREATE UNIQUE INDEX tbl_order_0_pkey ON public.tbl_order_0 USING btree (id)"
+  },
+  {
+    "index_name": "idx_order_corporation",
+    "index_columns": "corporation_id",
+    "is_unique": false,
+    "index_method": "btree",
+    "index_definition": "CREATE INDEX idx_order_corporation ON public.tbl_order_0 USING btree (corporation_id)"
+  }
+]
+```
+
+### sharding_topology
+
+查看分片拓扑信息。这是纯配置解析操作，不连接数据库。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| table | string | 否 | 逻辑表名（不传则返回所有表的拓扑） |
+
+返回示例：
+
+```json
+[
+  {
+    "logicalTable": "tbl_order",
+    "actualDataNodes": [
+      "ds_0.tbl_order_0",
+      "ds_0.tbl_order_1",
+      "ds_1.tbl_order_0",
+      "ds_1.tbl_order_1"
+    ],
+    "nodeCount": 4,
+    "tableStrategy": "standard",
+    "shardingColumn": "order_id",
+    "algorithmName": "tbl_order_inline",
+    "algorithmType": "INLINE",
+    "algorithmExpression": "tbl_order_$->{order_id % 2}",
+    "databaseStrategy": "standard",
+    "databaseShardingColumn": "corporation_id"
+  }
+]
+```
+
+### query_metadata
+
+执行自定义的元数据查询。仅允许查询 `information_schema` 或 `pg_catalog` 的 SELECT 语句。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| datasource | string | 是 | 数据源名称 |
+| sql | string | 是 | SQL 查询语句 |
+
+安全限制：
+- 必须以 `SELECT` 开头
+- 不允许包含分号（禁止多语句）
+- 不允许包含写操作关键字（INSERT/UPDATE/DELETE/DROP/ALTER 等）
+- `FROM` 子句必须直接引用 `information_schema` 或 `pg_catalog`
+
+合法查询示例：
+
+```sql
+SELECT column_name, data_type FROM information_schema.columns WHERE table_name = 'tbl_order_0'
+```
+
+```sql
+SELECT relname, reltuples FROM pg_catalog.pg_class WHERE relkind = 'r'
+```
+
+## 安全机制
+
+本工具采用多层防御策略确保数据安全：
+
+| 层级 | 措施 | 说明 |
+|------|------|------|
+| 连接层 | `default_transaction_read_only=on` | pg.Pool 级别强制只读，即使 SQL 注入也无法写入 |
+| SQL 层 | 白名单过滤 | query_metadata 仅允许 SELECT + information_schema/pg_catalog |
+| Tool 层 | 固定查询 | 预定义 tool 只执行硬编码的参数化查询 |
+| 输出层 | 密码遮蔽 | 所有输出中密码显示为 `***` |
+
+## 项目结构
+
+```
+src/
+├── index.ts                    # MCP Server 入口，组装所有组件
+├── config/
+│   ├── types.ts                # Zod 配置 schema 和 TypeScript 类型定义
+│   └── parser.ts               # YAML 解析、DataNodes 展开、JDBC URL 解析
+├── db/
+│   ├── connection-manager.ts   # 多数据源连接池管理（懒初始化、并发安全）
+│   └── metadata-queries.ts     # PostgreSQL 元数据查询 SQL 封装
+└── tools/
+    ├── list-datasources.ts     # Tool: 列出数据源
+    ├── list-tables.ts          # Tool: 列出表
+    ├── describe-table.ts       # Tool: 表结构详情
+    ├── describe-indexes.ts     # Tool: 索引详情
+    ├── sharding-topology.ts    # Tool: 分片拓扑
+    └── query-metadata.ts       # Tool: 通用元数据查询（带安全过滤）
+config/
+├── datasource.yaml             # 实际配置文件（.gitignore 忽略，含密码）
+└── datasource.example.yaml     # 示例配置文件
+```
+
+## 常用场景
+
+### 了解数据库全貌
+
+1. 调用 `list_datasources` 查看有哪些数据源
+2. 调用 `sharding_topology` 了解分片规则和数据分布
+3. 对感兴趣的数据源调用 `list_tables` 查看有哪些表
+
+### 了解某张表的结构
+
+1. 调用 `describe_table` 查看列定义、约束和统计信息
+2. 调用 `describe_indexes` 查看索引设计
+
+### 跨分片对比表结构
+
+1. 调用 `sharding_topology` 获取逻辑表对应的所有物理节点
+2. 对不同数据源的分片表分别调用 `describe_table` 对比结构差异
+
+### 自定义元数据查询
+
+使用 `query_metadata` 执行灵活的 information_schema / pg_catalog 查询，例如：
+- 查找所有包含某列名的表
+- 统计各 schema 下的表数量
+- 查看表的存储参数

package/config/datasource.example.yaml

@@ -0,0 +1,62 @@
+dataSources:
+  ds_0:
+    dataSourceClassName: com.zaxxer.hikari.HikariDataSource
+    driverClassName: org.postgresql.Driver
+    jdbcUrl: jdbc:postgresql://localhost:5432/shop_db_0
+    username: postgres
+    password: your_password_here
+  ds_1:
+    dataSourceClassName: com.zaxxer.hikari.HikariDataSource
+    driverClassName: org.postgresql.Driver
+    jdbcUrl: jdbc:postgresql://localhost:5432/shop_db_1
+    username: postgres
+    password: your_password_here
+
+rules:
+  - !SHARDING
+    tables:
+      tbl_order_master:
+        actualDataNodes: ds_$->{0..1}.tbl_order_master_$->{0..1}
+        tableStrategy:
+          standard:
+            shardingColumn: order_id
+            shardingAlgorithmName: tbl_order_master_inline
+      tbl_order_detail:
+        actualDataNodes: ds_$->{0..1}.tbl_order_detail_$->{0..1}
+        tableStrategy:
+          standard:
+            shardingColumn: order_id
+            shardingAlgorithmName: tbl_order_detail_inline
+      tbl_shop:
+        actualDataNodes: ds_$->{0..1}.tbl_shop_$->{0..1}
+        tableStrategy:
+          standard:
+            shardingColumn: shop_id
+            shardingAlgorithmName: tbl_shop_inline
+    defaultShardingColumn: corporation_id
+    defaultDatabaseStrategy:
+      standard:
+        shardingColumn: corporation_id
+        shardingAlgorithmName: database_inline
+    defaultTableStrategy:
+      none:
+    shardingAlgorithms:
+      database_inline:
+        type: INLINE
+        props:
+          algorithm-expression: ds_$->{corporation_id % 2}
+      tbl_order_master_inline:
+        type: INLINE
+        props:
+          algorithm-expression: tbl_order_master_$->{order_id % 2}
+      tbl_order_detail_inline:
+        type: INLINE
+        props:
+          algorithm-expression: tbl_order_detail_$->{order_id % 2}
+      tbl_shop_inline:
+        type: INLINE
+        props:
+          algorithm-expression: tbl_shop_$->{shop_id % 2}
+
+props:
+  sql-show: true

package/dist/config/parser.d.ts

@@ -0,0 +1,61 @@
+/**
+ * YAML 配置文件解析器
+ *
+ * 负责将 ShardingSphere 风格的 YAML 配置文件解析为 ParsedConfig 结构。
+ *
+ * 核心难点:
+ * 1. ShardingSphere YAML 使用自定义标签 `!SHARDING`，标准 YAML 解析器不认识该标签
+ *    解决: 使用 yaml 库的 customTags 将 `!SHARDING` 标签的 map 解析为普通 JS 对象
+ * 2. actualDataNodes 使用 `$->{start..end}` 语法表示范围，需展开为笛卡尔积
+ *    示例: ds_$->{0..1}.tbl_$->{0..2} 展开为 6 个节点
+ * 3. JDBC URL 格式 `jdbc:postgresql://host:port/db` 需要提取为 pg.Pool 可用的参数
+ */
+import { type ParsedConfig } from './types.js';
+/**
+ * 解析 YAML 配置文件
+ *
+ * 解析流程:
+ * 1. 读取 YAML 文件，使用自定义标签处理器解析 `!SHARDING` 标签
+ * 2. 逐个验证 dataSources 中的数据源配置（Zod 校验）
+ * 3. 从 rules 数组中查找分片规则（通过检测 tables/shardingAlgorithms 等键来识别）
+ *
+ * @param filePath YAML 配置文件路径
+ * @returns 解析后的配置对象
+ * @throws Zod 验证错误（如必填字段缺失）或文件读取错误
+ */
+export declare function parseConfig(filePath: string): ParsedConfig;
+/**
+ * 展开 ShardingSphere 的 actualDataNodes 表达式为具体节点列表
+ *
+ * 表达式语法: 使用 `$->{start..end}` 表示数字范围
+ * 支持多段范围，结果为所有范围的笛卡尔积
+ *
+ * @example
+ * expandDataNodes('ds_$->{0..1}.tbl_order_$->{0..1}')
+ * // 结果: ['ds_0.tbl_order_0', 'ds_0.tbl_order_1', 'ds_1.tbl_order_0', 'ds_1.tbl_order_1']
+ *
+ * @example
+ * expandDataNodes('ds_0.tbl_config')  // 无范围表达式，原样返回
+ * // 结果: ['ds_0.tbl_config']
+ *
+ * @param expression ShardingSphere actualDataNodes 表达式
+ * @returns 展开后的所有数据节点列表，格式为 "数据源名.表名"
+ */
+export declare function expandDataNodes(expression: string): string[];
+/**
+ * 从 JDBC URL 中提取 PostgreSQL 连接参数
+ *
+ * 支持的格式:
+ * - jdbc:postgresql://host:port/database
+ * - jdbc:postgresql://host/database （端口默认 5432）
+ * - postgresql://host:port/database （无 jdbc: 前缀）
+ *
+ * @param jdbcUrl JDBC 格式的数据库连接 URL
+ * @returns { host, port, database } 供 pg.Pool 使用的连接参数
+ * @throws 当 URL 格式不匹配时抛出错误
+ */
+export declare function parseJdbcUrl(jdbcUrl: string): {
+    host: string;
+    port: number;
+    database: string;
+};

package/dist/config/parser.js

@@ -0,0 +1,165 @@
+/**
+ * YAML 配置文件解析器
+ *
+ * 负责将 ShardingSphere 风格的 YAML 配置文件解析为 ParsedConfig 结构。
+ *
+ * 核心难点:
+ * 1. ShardingSphere YAML 使用自定义标签 `!SHARDING`，标准 YAML 解析器不认识该标签
+ *    解决: 使用 yaml 库的 customTags 将 `!SHARDING` 标签的 map 解析为普通 JS 对象
+ * 2. actualDataNodes 使用 `$->{start..end}` 语法表示范围，需展开为笛卡尔积
+ *    示例: ds_$->{0..1}.tbl_$->{0..2} 展开为 6 个节点
+ * 3. JDBC URL 格式 `jdbc:postgresql://host:port/db` 需要提取为 pg.Pool 可用的参数
+ */
+import fs from 'node:fs';
+import { parse as parseYaml, YAMLMap } from 'yaml';
+import { DataSourceConfigSchema, ShardingRuleConfigSchema, } from './types.js';
+/**
+ * 解析 YAML 配置文件
+ *
+ * 解析流程:
+ * 1. 读取 YAML 文件，使用自定义标签处理器解析 `!SHARDING` 标签
+ * 2. 逐个验证 dataSources 中的数据源配置（Zod 校验）
+ * 3. 从 rules 数组中查找分片规则（通过检测 tables/shardingAlgorithms 等键来识别）
+ *
+ * @param filePath YAML 配置文件路径
+ * @returns 解析后的配置对象
+ * @throws Zod 验证错误（如必填字段缺失）或文件读取错误
+ */
+export function parseConfig(filePath) {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const raw = parseYaml(content, {
+        customTags: [
+            {
+                // ShardingSphere 使用 `!SHARDING` YAML 标签标记分片规则
+                // 这里将其解析为普通 JS 对象，后续由 Zod schema 验证
+                tag: '!SHARDING',
+                collection: 'map',
+                resolve(value) {
+                    if (value instanceof YAMLMap) {
+                        return value.toJSON();
+                    }
+                    return value;
+                },
+            },
+        ],
+    });
+    // 解析数据源配置: 每个数据源独立用 Zod 验证
+    const rawDs = raw['dataSources'];
+    if (!rawDs) {
+        throw new Error('配置文件缺少 dataSources 字段');
+    }
+    const dataSources = {};
+    for (const [name, dsConfig] of Object.entries(rawDs)) {
+        dataSources[name] = DataSourceConfigSchema.parse(dsConfig);
+    }
+    // 解析分片规则: rules 是一个数组，其中 `!SHARDING` 标签的元素已被解析为普通对象
+    // 通过检测对象中是否包含分片相关的键来识别分片规则（而非依赖 YAML 标签信息）
+    let shardingRule;
+    const rules = raw['rules'];
+    if (rules && Array.isArray(rules)) {
+        for (const rule of rules) {
+            if (rule && typeof rule === 'object') {
+                const ruleObj = rule;
+                if (ruleObj['tables'] || ruleObj['shardingAlgorithms'] || ruleObj['defaultShardingColumn']) {
+                    shardingRule = ShardingRuleConfigSchema.parse(ruleObj);
+                    break;
+                }
+            }
+        }
+    }
+    const props = raw['props'];
+    return { dataSources, shardingRule, props };
+}
+/**
+ * 展开 ShardingSphere 的 actualDataNodes 表达式为具体节点列表
+ *
+ * 表达式语法: 使用 `$->{start..end}` 表示数字范围
+ * 支持多段范围，结果为所有范围的笛卡尔积
+ *
+ * @example
+ * expandDataNodes('ds_$->{0..1}.tbl_order_$->{0..1}')
+ * // 结果: ['ds_0.tbl_order_0', 'ds_0.tbl_order_1', 'ds_1.tbl_order_0', 'ds_1.tbl_order_1']
+ *
+ * @example
+ * expandDataNodes('ds_0.tbl_config')  // 无范围表达式，原样返回
+ * // 结果: ['ds_0.tbl_config']
+ *
+ * @param expression ShardingSphere actualDataNodes 表达式
+ * @returns 展开后的所有数据节点列表，格式为 "数据源名.表名"
+ */
+export function expandDataNodes(expression) {
+    // 匹配 $->{start..end} 模式，如 $->{0..3}
+    const rangePattern = /\$->\{(\d+)\.\.(\d+)\}/g;
+    // 收集表达式中的所有范围段
+    const ranges = [];
+    let match;
+    while ((match = rangePattern.exec(expression)) !== null) {
+        ranges.push({
+            start: parseInt(match[1], 10),
+            end: parseInt(match[2], 10),
+            match: match[0], // 完整匹配文本，用于后续替换
+        });
+    }
+    // 无范围表达式时直接返回
+    if (ranges.length === 0) {
+        return [expression];
+    }
+    // 为每个范围生成数值数组，然后计算笛卡尔积
+    const valueSets = ranges.map(r => {
+        const values = [];
+        for (let i = r.start; i <= r.end; i++) {
+            values.push(i);
+        }
+        return values;
+    });
+    const combinations = cartesianProduct(valueSets);
+    // 将每种组合代入表达式模板，生成具体节点名
+    return combinations.map(combo => {
+        let result = expression;
+        for (let i = 0; i < ranges.length; i++) {
+            result = result.replace(ranges[i].match, String(combo[i]));
+        }
+        return result;
+    });
+}
+/**
+ * 计算多个数组的笛卡尔积
+ * @example cartesianProduct([[0,1], [0,1]]) → [[0,0], [0,1], [1,0], [1,1]]
+ */
+function cartesianProduct(arrays) {
+    if (arrays.length === 0)
+        return [[]];
+    const [first, ...rest] = arrays;
+    const restProduct = cartesianProduct(rest);
+    const result = [];
+    for (const val of first) {
+        for (const combo of restProduct) {
+            result.push([val, ...combo]);
+        }
+    }
+    return result;
+}
+/**
+ * 从 JDBC URL 中提取 PostgreSQL 连接参数
+ *
+ * 支持的格式:
+ * - jdbc:postgresql://host:port/database
+ * - jdbc:postgresql://host/database （端口默认 5432）
+ * - postgresql://host:port/database （无 jdbc: 前缀）
+ *
+ * @param jdbcUrl JDBC 格式的数据库连接 URL
+ * @returns { host, port, database } 供 pg.Pool 使用的连接参数
+ * @throws 当 URL 格式不匹配时抛出错误
+ */
+export function parseJdbcUrl(jdbcUrl) {
+    const url = jdbcUrl.replace(/^jdbc:/, '');
+    const match = url.match(/postgresql:\/\/([^:/]+)(?::(\d+))?\/([^?]+)/);
+    if (!match) {
+        throw new Error(`无法解析 JDBC URL: ${jdbcUrl}`);
+    }
+    return {
+        host: match[1],
+        port: match[2] ? parseInt(match[2], 10) : 5432,
+        database: match[3],
+    };
+}