@harneon-ai/db 0.0.1

package/dist/tools/query-metadata.js

@@ -0,0 +1,83 @@
+/**
+ * MCP Tool: query_metadata
+ *
+ * 允许 AI 执行自定义的元数据查询，提供灵活性的同时通过严格的安全过滤确保安全。
+ *
+ * 安全验证规则（全部通过才允许执行）:
+ * 1. SQL 必须以 SELECT 开头
+ * 2. SQL 不能包含分号（防止多语句攻击）
+ * 3. SQL 不能包含写操作关键字（INSERT/UPDATE/DELETE/DROP/ALTER/CREATE/TRUNCATE/GRANT/REVOKE）
+ * 4. SQL 的 FROM 子句必须直接引用 information_schema 或 pg_catalog（防止通过构造字符串绕过）
+ *
+ * 注意: 这是 SQL 级别的安全层，连接级别还有 default_transaction_read_only=on 作为兜底
+ */
+import { z } from 'zod';
+/** 禁止的写操作关键字 */
+const FORBIDDEN_KEYWORDS = /\b(INSERT|UPDATE|DELETE|DROP|ALTER|CREATE|TRUNCATE|GRANT|REVOKE)\b/i;
+/**
+ * FROM 子句必须直接引用 information_schema 或 pg_catalog
+ * 这比简单的子字符串检查更安全: 防止通过 WHERE 'information_schema'='information_schema' 绕过
+ */
+const ALLOWED_FROM_SCHEMAS = /\bFROM\s+(?:ONLY\s+)?(?:information_schema|pg_catalog)\b/i;
+/**
+ * 验证 SQL 是否为合法的元数据查询
+ * @returns 错误信息（字符串）或 null（验证通过）
+ */
+function validateMetadataQuery(sql) {
+    const trimmed = sql.trim();
+    if (!/^SELECT\b/i.test(trimmed)) {
+        return '仅允许 SELECT 语句';
+    }
+    // 拒绝分号: 防止通过 SELECT 1; DELETE FROM ... 形式的多语句攻击
+    if (trimmed.includes(';')) {
+        return '不允许包含分号（禁止多语句查询）';
+    }
+    if (FORBIDDEN_KEYWORDS.test(trimmed)) {
+        return '检测到禁止的关键字（INSERT/UPDATE/DELETE/DROP/ALTER/CREATE/TRUNCATE/GRANT/REVOKE）';
+    }
+    // 要求 FROM 子句直接引用系统 schema，而非仅在 SQL 中出现该字符串
+    if (!ALLOWED_FROM_SCHEMAS.test(trimmed)) {
+        return '仅允许查询 information_schema 或 pg_catalog 的 SELECT 语句（FROM 子句必须引用这些 schema）';
+    }
+    return null;
+}
+export function registerQueryMetadata(server, _config, connectionManager) {
+    server.tool('query_metadata', '执行自定义的元数据查询（仅允许查询 information_schema 或 pg_catalog 的 SELECT 语句）', {
+        datasource: z.string().describe('数据源名称'),
+        sql: z.string().describe('SQL 查询语句（仅允许 SELECT information_schema/pg_catalog）'),
+    }, async ({ datasource, sql }) => {
+        // 先验证 SQL 安全性，不通过则直接返回错误
+        const error = validateMetadataQuery(sql);
+        if (error) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ error }),
+                    }],
+                isError: true,
+            };
+        }
+        try {
+            const pool = await connectionManager.getPool(datasource);
+            const result = await pool.query(sql);
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            rowCount: result.rowCount,
+                            rows: result.rows,
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ error: err instanceof Error ? err.message : String(err) }),
+                    }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/save-datasource-config.d.ts

@@ -0,0 +1,15 @@
+/**
+ * MCP Tool: save_datasource_config
+ *
+ * 将数据源配置持久化到 YAML 文件并更新内存状态。
+ *
+ * 设计要点:
+ * - 原地修改 config 对象: 所有现有 tool 闭包捕获了同一个 config 引用，
+ *   原地修改避免引入间接层，确保所有 tool 立即看到新配置
+ * - 写入失败时不修改内存: 先写入磁盘，成功后再更新内存状态，保证一致性
+ * - 调用 connectionManager.reloadConfig() 清空旧连接池缓存
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ParsedConfig } from '../config/types.js';
+import { ConnectionManager } from '../db/connection-manager.js';
+export declare function registerSaveDatasourceConfig(server: McpServer, config: ParsedConfig, connectionManager: ConnectionManager, configPath: string): void;

package/dist/tools/save-datasource-config.js

@@ -0,0 +1,112 @@
+/**
+ * MCP Tool: save_datasource_config
+ *
+ * 将数据源配置持久化到 YAML 文件并更新内存状态。
+ *
+ * 设计要点:
+ * - 原地修改 config 对象: 所有现有 tool 闭包捕获了同一个 config 引用，
+ *   原地修改避免引入间接层，确保所有 tool 立即看到新配置
+ * - 写入失败时不修改内存: 先写入磁盘，成功后再更新内存状态，保证一致性
+ * - 调用 connectionManager.reloadConfig() 清空旧连接池缓存
+ */
+import { z } from 'zod';
+import { mergeConfigs, writeConfigFile } from '../config/writer.js';
+export function registerSaveDatasourceConfig(server, config, connectionManager, configPath) {
+    server.tool('save_datasource_config', '保存数据源配置到 YAML 文件。支持添加一个或多个数据源，可选配置分片规则。', {
+        dataSources: z.array(z.object({
+            name: z.string().describe('数据源名称，如 ds_0'),
+            jdbcUrl: z.string().describe('JDBC URL，如 jdbc:postgresql://host:port/database'),
+            username: z.string().describe('数据库用户名'),
+            password: z.string().describe('数据库密码'),
+        })).min(1).describe('数据源列表，至少 1 个'),
+        shardingRule: z.object({
+            tables: z.record(z.string(), z.object({
+                actualDataNodes: z.string(),
+                tableStrategy: z.object({
+                    none: z.union([z.null(), z.object({})]).optional(),
+                    standard: z.object({
+                        shardingColumn: z.string(),
+                        shardingAlgorithmName: z.string(),
+                    }).optional(),
+                    complex: z.object({
+                        shardingColumns: z.string(),
+                        shardingAlgorithmName: z.string(),
+                    }).optional(),
+                }).optional(),
+            })).optional(),
+            defaultShardingColumn: z.string().optional(),
+            defaultDatabaseStrategy: z.object({
+                standard: z.object({
+                    shardingColumn: z.string(),
+                    shardingAlgorithmName: z.string(),
+                }).optional(),
+                none: z.union([z.null(), z.object({})]).optional(),
+            }).optional(),
+            defaultTableStrategy: z.object({
+                standard: z.object({
+                    shardingColumn: z.string(),
+                    shardingAlgorithmName: z.string(),
+                }).optional(),
+                none: z.union([z.null(), z.object({})]).optional(),
+            }).optional(),
+            shardingAlgorithms: z.record(z.string(), z.object({
+                type: z.string(),
+                props: z.record(z.string(), z.union([z.string(), z.number()])).optional(),
+            })).optional(),
+        }).optional().describe('可选的分片规则配置'),
+    }, async (params) => {
+        // 1. 将 dataSources 数组转换为 Record<string, DataSourceConfig> 格式
+        const incomingDataSources = {};
+        for (const ds of params.dataSources) {
+            incomingDataSources[ds.name] = {
+                jdbcUrl: ds.jdbcUrl,
+                username: ds.username,
+                password: ds.password,
+            };
+        }
+        const incomingConfig = {
+            dataSources: incomingDataSources,
+            shardingRule: params.shardingRule,
+        };
+        // 2. 合并到现有配置
+        const merged = mergeConfigs(config, incomingConfig);
+        // 3. 写入磁盘（失败时抛出异常，不会执行后续内存修改）
+        try {
+            writeConfigFile(configPath, merged);
+        }
+        catch (err) {
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: `写入配置文件失败: ${errorMessage}` }),
+                    }],
+            };
+        }
+        // 4. 原地修改 config 对象，确保所有 tool 闭包立即看到新配置
+        // 清空现有 dataSources 再赋值，保持引用不变
+        for (const key of Object.keys(config.dataSources)) {
+            delete config.dataSources[key];
+        }
+        Object.assign(config.dataSources, merged.dataSources);
+        config.shardingRule = merged.shardingRule;
+        config.props = merged.props;
+        // 5. 清空旧连接池缓存，下次使用时会基于新配置创建
+        await connectionManager.reloadConfig();
+        // 6. 返回成功摘要
+        const savedNames = params.dataSources.map(ds => ds.name);
+        const hasSharding = !!params.shardingRule;
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        success: true,
+                        savedDataSources: savedNames,
+                        shardingConfigured: hasSharding,
+                        configFile: configPath,
+                        totalDataSources: Object.keys(config.dataSources).length,
+                    }),
+                }],
+        };
+    });
+}

package/dist/tools/sharding-topology.d.ts

@@ -0,0 +1,20 @@
+/**
+ * MCP Tool: sharding_topology
+ *
+ * 展示 ShardingSphere 分片拓扑信息。
+ * 这是一个纯配置解析操作，不连接任何数据库。
+ *
+ * 解析逻辑:
+ * 1. 从配置中读取分片规则（tables + shardingAlgorithms）
+ * 2. 使用 expandDataNodes() 展开 actualDataNodes 表达式为具体节点列表
+ * 3. 解析表级分片策略（standard/complex），回退到默认策略
+ * 4. 查找对应的分片算法类型和表达式
+ * 5. 组装完整的拓扑信息返回
+ *
+ * 策略解析优先级:
+ * 表级 tableStrategy > 全局 defaultTableStrategy > defaultShardingColumn
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type ParsedConfig } from '../config/types.js';
+import { type ConnectionManager } from '../db/connection-manager.js';
+export declare function registerShardingTopology(server: McpServer, config: ParsedConfig, _connectionManager: ConnectionManager): void;

package/dist/tools/sharding-topology.js

@@ -0,0 +1,111 @@
+/**
+ * MCP Tool: sharding_topology
+ *
+ * 展示 ShardingSphere 分片拓扑信息。
+ * 这是一个纯配置解析操作，不连接任何数据库。
+ *
+ * 解析逻辑:
+ * 1. 从配置中读取分片规则（tables + shardingAlgorithms）
+ * 2. 使用 expandDataNodes() 展开 actualDataNodes 表达式为具体节点列表
+ * 3. 解析表级分片策略（standard/complex），回退到默认策略
+ * 4. 查找对应的分片算法类型和表达式
+ * 5. 组装完整的拓扑信息返回
+ *
+ * 策略解析优先级:
+ * 表级 tableStrategy > 全局 defaultTableStrategy > defaultShardingColumn
+ */
+import { z } from 'zod';
+import { expandDataNodes } from '../config/parser.js';
+export function registerShardingTopology(server, config, _connectionManager) {
+    server.tool('sharding_topology', '查看分片拓扑信息：逻辑表名、分片列、分片算法、实际数据节点', {
+        table: z.string().optional().describe('逻辑表名（不传则返回所有表的拓扑）'),
+    }, async ({ table }) => {
+        const shardingRule = config.shardingRule;
+        if (!shardingRule || !shardingRule.tables) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ message: '未配置分片规则' }),
+                    }],
+            };
+        }
+        const tables = shardingRule.tables;
+        const algorithms = shardingRule.shardingAlgorithms || {};
+        // 支持查询单表或全部表的拓扑
+        const filteredEntries = table
+            ? Object.entries(tables).filter(([name]) => name === table)
+            : Object.entries(tables);
+        if (filteredEntries.length === 0) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ message: table ? `逻辑表 "${table}" 未找到分片规则` : '无分片表配置' }),
+                    }],
+            };
+        }
+        const topology = filteredEntries.map(([logicalTable, tableConfig]) => {
+            // 展开 actualDataNodes 表达式为具体节点列表
+            const actualDataNodes = expandDataNodes(tableConfig.actualDataNodes);
+            // 解析表级分片策略
+            let shardingColumn;
+            let shardingAlgorithmName;
+            let strategyType = 'none';
+            const strategy = tableConfig.tableStrategy;
+            if (strategy?.standard) {
+                strategyType = 'standard';
+                shardingColumn = strategy.standard.shardingColumn;
+                shardingAlgorithmName = strategy.standard.shardingAlgorithmName;
+            }
+            else if (strategy?.complex) {
+                strategyType = 'complex';
+                shardingColumn = strategy.complex.shardingColumns;
+                shardingAlgorithmName = strategy.complex.shardingAlgorithmName;
+            }
+            // 表级策略为 none 时，回退到全局默认表策略
+            if (!strategy || strategy.none !== undefined) {
+                if (shardingRule.defaultTableStrategy?.standard) {
+                    strategyType = 'standard (default)';
+                    shardingColumn = shardingRule.defaultTableStrategy.standard.shardingColumn;
+                    shardingAlgorithmName = shardingRule.defaultTableStrategy.standard.shardingAlgorithmName;
+                }
+            }
+            // 最终兜底: 使用全局默认分片列
+            if (!shardingColumn && shardingRule.defaultShardingColumn) {
+                shardingColumn = shardingRule.defaultShardingColumn;
+            }
+            // 根据算法名称查找算法详情
+            let algorithmType;
+            let algorithmExpression;
+            if (shardingAlgorithmName && algorithms[shardingAlgorithmName]) {
+                const algo = algorithms[shardingAlgorithmName];
+                algorithmType = algo.type; // 如 INLINE, MOD
+                algorithmExpression = algo.props?.['algorithm-expression']?.toString();
+            }
+            // 数据库级分片策略（通常按 corporation_id 分库）
+            let databaseStrategy = 'none';
+            let dbShardingColumn;
+            if (shardingRule.defaultDatabaseStrategy?.standard) {
+                databaseStrategy = 'standard';
+                dbShardingColumn = shardingRule.defaultDatabaseStrategy.standard.shardingColumn;
+            }
+            return {
+                logicalTable,
+                actualDataNodes,
+                nodeCount: actualDataNodes.length,
+                tableStrategy: strategyType,
+                shardingColumn,
+                algorithmName: shardingAlgorithmName,
+                algorithmType,
+                algorithmExpression,
+                databaseStrategy,
+                databaseShardingColumn: dbShardingColumn,
+            };
+        });
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(topology, null, 2),
+                }],
+        };
+    });
+}

package/dist/tools/test-connection.d.ts

@@ -0,0 +1,9 @@
+/**
+ * MCP Tool: test_connection
+ *
+ * 测试 PostgreSQL 数据库连接是否可用。
+ * 完全独立于现有配置和连接池，使用临时连接执行 SELECT version() 验证。
+ * 支持两种输入方式: 分字段输入或 JDBC URL 输入。
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerTestConnection(server: McpServer): void;

package/dist/tools/test-connection.js

@@ -0,0 +1,100 @@
+/**
+ * MCP Tool: test_connection
+ *
+ * 测试 PostgreSQL 数据库连接是否可用。
+ * 完全独立于现有配置和连接池，使用临时连接执行 SELECT version() 验证。
+ * 支持两种输入方式: 分字段输入或 JDBC URL 输入。
+ */
+import { z } from 'zod';
+import pg from 'pg';
+export function registerTestConnection(server) {
+    server.tool('test_connection', '测试 PostgreSQL 数据库连接。支持分字段输入（host/port/database）或 jdbcUrl 输入。', {
+        host: z.string().optional().describe('数据库主机地址（与 jdbcUrl 二选一）'),
+        port: z.number().default(5432).describe('数据库端口，默认 5432'),
+        database: z.string().optional().describe('数据库名称（与 jdbcUrl 二选一）'),
+        username: z.string().describe('数据库用户名'),
+        password: z.string().describe('数据库密码'),
+        jdbcUrl: z.string().optional().describe('JDBC URL，如 jdbc:postgresql://host:port/database（与 host/database 二选一）'),
+    }, async (params) => {
+        let host;
+        let port;
+        let database;
+        // 从 jdbcUrl 或分字段中解析连接参数
+        if (params.jdbcUrl) {
+            const parsed = parseTestJdbcUrl(params.jdbcUrl);
+            if (!parsed) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({ connected: false, error: `无法解析 JDBC URL: ${params.jdbcUrl}` }),
+                        }],
+                };
+            }
+            host = parsed.host;
+            port = parsed.port;
+            database = parsed.database;
+        }
+        else if (params.host && params.database) {
+            host = params.host;
+            port = params.port;
+            database = params.database;
+        }
+        else {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ connected: false, error: '请提供 jdbcUrl 或者 host + database 参数' }),
+                    }],
+            };
+        }
+        // 创建临时连接池进行测试
+        const pool = new pg.Pool({
+            host,
+            port,
+            database,
+            user: params.username,
+            password: params.password,
+            max: 1,
+            connectionTimeoutMillis: 10000,
+            // 测试连接也使用只读模式，避免任何意外写入
+            options: '-c default_transaction_read_only=on',
+        });
+        try {
+            const result = await pool.query('SELECT version()');
+            const serverVersion = result.rows[0]?.version ?? 'unknown';
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ connected: true, serverVersion }),
+                    }],
+            };
+        }
+        catch (err) {
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ connected: false, error: errorMessage }),
+                    }],
+            };
+        }
+        finally {
+            await pool.end();
+        }
+    });
+}
+/**
+ * 从 JDBC URL 中提取连接参数（工具内部使用，与 parser.ts 的 parseJdbcUrl 独立）
+ * 不抛出异常，解析失败返回 null
+ */
+function parseTestJdbcUrl(jdbcUrl) {
+    const url = jdbcUrl.replace(/^jdbc:/, '');
+    const match = url.match(/postgresql:\/\/([^:/]+)(?::(\d+))?\/([^?]+)/);
+    if (!match)
+        return null;
+    return {
+        host: match[1],
+        port: match[2] ? parseInt(match[2], 10) : 5432,
+        database: match[3],
+    };
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@harneon-ai/db",
+  "version": "0.0.1",
+  "description": "MCP Server for database metadata sync with ShardingSphere topology support",
+  "type": "module",
+  "bin": {
+    "harneon-db": "dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "config/datasource.example.yaml",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["mcp", "postgresql", "database", "metadata", "shardingsphere", "harneon"],
+  "author": "lyuzb <lyuzb@lyuzb.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitee.com/harneon/harneon-db.git"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "pg": "^8.13.1",
+    "yaml": "^2.7.1",
+    "zod": "^3.24.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.14",
+    "@types/pg": "^8.11.11",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3"
+  }
+}