@harneon-ai/db 0.0.1

package/dist/db/connection-manager.js

@@ -0,0 +1,83 @@
+/**
+ * 数据库连接池管理器
+ *
+ * 管理多个 PostgreSQL 数据源的连接池，采用懒初始化策略:
+ * - 构造时不创建任何连接，首次调用 getPool() 时才创建对应数据源的连接池
+ * - 使用 Promise Map 避免并发调用时重复创建连接池（竞态安全）
+ * - 所有连接池强制设置 default_transaction_read_only=on（数据库层面只读保护）
+ *
+ * 连接池参数:
+ * - max=3: 元数据查询不需要大连接池，3 个连接足够
+ * - idleTimeoutMillis=30000: 空闲 30 秒后释放连接
+ */
+import pg from 'pg';
+import { parseJdbcUrl } from '../config/parser.js';
+export class ConnectionManager {
+    /**
+     * 使用 Promise<pg.Pool> 而非 pg.Pool 存储，确保并发调用 getPool() 时
+     * 多个调用者 await 同一个 Promise，避免重复创建连接池导致资源泄漏
+     */
+    poolPromises = new Map();
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * 获取指定数据源的连接池（懒初始化，并发安全）
+     * @param dsName 数据源名称，对应 YAML 配置中 dataSources 下的 key（如 ds_0, ds_1）
+     * @throws 数据源不存在或 JDBC URL 解析失败时抛出错误
+     */
+    async getPool(dsName) {
+        const existing = this.poolPromises.get(dsName);
+        if (existing) {
+            return existing;
+        }
+        // 立即存入 Promise，后续并发调用会命中缓存
+        const promise = this.createPool(dsName);
+        this.poolPromises.set(dsName, promise);
+        return promise;
+    }
+    async createPool(dsName) {
+        const dsConfig = this.config.dataSources[dsName];
+        if (!dsConfig) {
+            throw new Error(`数据源 "${dsName}" 不存在，可用数据源: ${this.getAllDataSourceNames().join(', ')}`);
+        }
+        const jdbcUrl = dsConfig.jdbcUrl || dsConfig.url;
+        if (!jdbcUrl) {
+            throw new Error(`数据源 "${dsName}" 缺少 jdbcUrl 或 url 配置`);
+        }
+        const { host, port, database } = parseJdbcUrl(jdbcUrl);
+        return new pg.Pool({
+            host,
+            port,
+            database,
+            user: dsConfig.username,
+            password: dsConfig.password,
+            max: 3,
+            idleTimeoutMillis: 30000,
+            // 关键安全设置: 连接级别强制只读事务，即使 SQL 注入也无法执行写操作
+            options: '-c default_transaction_read_only=on',
+        });
+    }
+    /** 返回所有已配置的数据源名称列表 */
+    getAllDataSourceNames() {
+        return Object.keys(this.config.dataSources);
+    }
+    /**
+     * 重新加载配置: 关闭所有已创建的连接池并清空缓存
+     *
+     * 调用前应先原地修改 config 对象（因为所有 tool 闭包引用同一对象）。
+     * 调用后，下次 getPool() 会基于更新后的 config 懒初始化新连接池。
+     */
+    async reloadConfig() {
+        const pools = await Promise.all(Array.from(this.poolPromises.values()));
+        await Promise.all(pools.map(pool => pool.end()));
+        this.poolPromises.clear();
+    }
+    /** 关闭所有已创建的连接池，用于进程退出时的资源清理 */
+    async shutdown() {
+        const pools = await Promise.all(Array.from(this.poolPromises.values()));
+        await Promise.all(pools.map(pool => pool.end()));
+        this.poolPromises.clear();
+    }
+}

package/dist/db/metadata-queries.d.ts

@@ -0,0 +1,82 @@
+/**
+ * PostgreSQL 元数据查询封装
+ *
+ * 提供一组纯函数，每个函数接收 pg.Pool 参数，执行只读的元数据查询。
+ * 所有 SQL 仅查询 information_schema 和 pg_catalog 系统目录，不访问任何业务数据。
+ * 全部使用参数化查询（$1, $2）防止 SQL 注入。
+ *
+ * 函数一览:
+ * - listTables: 列出指定 schema 下的所有表和视图
+ * - describeTable: 查询表的列信息（含列注释）
+ * - describeIndexes: 查询表的索引信息（含索引方法和列）
+ * - getTableConstraints: 查询表的约束（主键、外键、唯一）
+ * - getTableStats: 查询表的统计信息（行数估算、表大小）
+ */
+import type pg from 'pg';
+/** information_schema.tables 查询结果 */
+export interface TableInfo {
+    table_name: string;
+    table_type: string;
+}
+/** information_schema.columns + pg_description 联查结果 */
+export interface ColumnInfo {
+    column_name: string;
+    data_type: string;
+    is_nullable: string;
+    column_default: string | null;
+    character_maximum_length: number | null;
+    comment: string | null;
+    ordinal_position: number;
+}
+/** pg_catalog 索引查询结果 */
+export interface IndexInfo {
+    index_name: string;
+    index_columns: string;
+    is_unique: boolean;
+    index_method: string;
+    index_definition: string;
+}
+/** information_schema.table_constraints 查询结果 */
+export interface ConstraintInfo {
+    constraint_name: string;
+    constraint_type: string;
+    columns: string;
+}
+/** pg_catalog 表统计查询结果 */
+export interface TableStats {
+    estimated_rows: number;
+    total_size: string;
+    table_size: string;
+    index_size: string;
+}
+/** 列出指定 schema 下的所有用户表和视图 */
+export declare function listTables(pool: pg.Pool, schema?: string): Promise<TableInfo[]>;
+/**
+ * 查询表的列信息，包含列注释
+ *
+ * 通过 LEFT JOIN pg_catalog.pg_description 获取列注释:
+ * - pg_statio_all_tables 用于获取表的 OID (relid)
+ * - pg_description 通过 objoid + objsubid(列序号) 关联到列注释
+ */
+export declare function describeTable(pool: pg.Pool, tableName: string, schema?: string): Promise<ColumnInfo[]>;
+/**
+ * 查询表的索引信息
+ *
+ * 通过 pg_catalog 系统表联查:
+ * - pg_index: 索引元数据（唯一性等）
+ * - pg_class: 索引和表的 OID 信息
+ * - pg_am: 索引访问方法（btree/hash/gin/gist 等）
+ * - pg_attribute: 索引包含的列名
+ */
+export declare function describeIndexes(pool: pg.Pool, tableName: string, schema?: string): Promise<IndexInfo[]>;
+/** 查询表的约束信息（主键、外键、唯一约束） */
+export declare function getTableConstraints(pool: pg.Pool, tableName: string, schema?: string): Promise<ConstraintInfo[]>;
+/**
+ * 查询表的统计信息
+ *
+ * 注意: estimated_rows 来自 pg_stat_user_tables.n_live_tup，是基于 ANALYZE 的估算值
+ * 如需精确行数需要执行 COUNT(*)，但这可能很慢且不在本工具的元数据查询范围内
+ *
+ * @returns 表统计信息，表不存在时返回 null
+ */
+export declare function getTableStats(pool: pg.Pool, tableName: string, schema?: string): Promise<TableStats | null>;

package/dist/db/metadata-queries.js

@@ -0,0 +1,113 @@
+/**
+ * PostgreSQL 元数据查询封装
+ *
+ * 提供一组纯函数，每个函数接收 pg.Pool 参数，执行只读的元数据查询。
+ * 所有 SQL 仅查询 information_schema 和 pg_catalog 系统目录，不访问任何业务数据。
+ * 全部使用参数化查询（$1, $2）防止 SQL 注入。
+ *
+ * 函数一览:
+ * - listTables: 列出指定 schema 下的所有表和视图
+ * - describeTable: 查询表的列信息（含列注释）
+ * - describeIndexes: 查询表的索引信息（含索引方法和列）
+ * - getTableConstraints: 查询表的约束（主键、外键、唯一）
+ * - getTableStats: 查询表的统计信息（行数估算、表大小）
+ */
+/** 列出指定 schema 下的所有用户表和视图 */
+export async function listTables(pool, schema = 'public') {
+    const result = await pool.query(`SELECT table_name, table_type
+     FROM information_schema.tables
+     WHERE table_schema = $1
+       AND table_type IN ('BASE TABLE', 'VIEW')
+     ORDER BY table_name`, [schema]);
+    return result.rows;
+}
+/**
+ * 查询表的列信息，包含列注释
+ *
+ * 通过 LEFT JOIN pg_catalog.pg_description 获取列注释:
+ * - pg_statio_all_tables 用于获取表的 OID (relid)
+ * - pg_description 通过 objoid + objsubid(列序号) 关联到列注释
+ */
+export async function describeTable(pool, tableName, schema = 'public') {
+    const result = await pool.query(`SELECT
+       c.column_name,
+       c.data_type,
+       c.is_nullable,
+       c.column_default,
+       c.character_maximum_length,
+       c.ordinal_position,
+       pgd.description AS comment
+     FROM information_schema.columns c
+     LEFT JOIN pg_catalog.pg_statio_all_tables st
+       ON st.schemaname = c.table_schema AND st.relname = c.table_name
+     LEFT JOIN pg_catalog.pg_description pgd
+       ON pgd.objoid = st.relid AND pgd.objsubid = c.ordinal_position
+     WHERE c.table_schema = $1 AND c.table_name = $2
+     ORDER BY c.ordinal_position`, [schema, tableName]);
+    return result.rows;
+}
+/**
+ * 查询表的索引信息
+ *
+ * 通过 pg_catalog 系统表联查:
+ * - pg_index: 索引元数据（唯一性等）
+ * - pg_class: 索引和表的 OID 信息
+ * - pg_am: 索引访问方法（btree/hash/gin/gist 等）
+ * - pg_attribute: 索引包含的列名
+ */
+export async function describeIndexes(pool, tableName, schema = 'public') {
+    const result = await pool.query(`SELECT
+       i.relname AS index_name,
+       pg_get_indexdef(i.oid) AS index_definition,
+       ix.indisunique AS is_unique,
+       am.amname AS index_method,
+       array_to_string(ARRAY(
+         SELECT a.attname
+         FROM pg_catalog.pg_attribute a
+         WHERE a.attrelid = i.oid
+         ORDER BY a.attnum
+       ), ', ') AS index_columns
+     FROM pg_catalog.pg_index ix
+     JOIN pg_catalog.pg_class t ON t.oid = ix.indrelid
+     JOIN pg_catalog.pg_class i ON i.oid = ix.indexrelid
+     JOIN pg_catalog.pg_namespace n ON n.oid = t.relnamespace
+     JOIN pg_catalog.pg_am am ON am.oid = i.relam
+     WHERE n.nspname = $1 AND t.relname = $2
+     ORDER BY i.relname`, [schema, tableName]);
+    return result.rows;
+}
+/** 查询表的约束信息（主键、外键、唯一约束） */
+export async function getTableConstraints(pool, tableName, schema = 'public') {
+    const result = await pool.query(`SELECT
+       tc.constraint_name,
+       tc.constraint_type,
+       string_agg(kcu.column_name, ', ' ORDER BY kcu.ordinal_position) AS columns
+     FROM information_schema.table_constraints tc
+     JOIN information_schema.key_column_usage kcu
+       ON tc.constraint_name = kcu.constraint_name
+       AND tc.table_schema = kcu.table_schema
+     WHERE tc.table_schema = $1 AND tc.table_name = $2
+     GROUP BY tc.constraint_name, tc.constraint_type
+     ORDER BY tc.constraint_type, tc.constraint_name`, [schema, tableName]);
+    return result.rows;
+}
+/**
+ * 查询表的统计信息
+ *
+ * 注意: estimated_rows 来自 pg_stat_user_tables.n_live_tup，是基于 ANALYZE 的估算值
+ * 如需精确行数需要执行 COUNT(*)，但这可能很慢且不在本工具的元数据查询范围内
+ *
+ * @returns 表统计信息，表不存在时返回 null
+ */
+export async function getTableStats(pool, tableName, schema = 'public') {
+    const result = await pool.query(`SELECT
+       s.n_live_tup AS estimated_rows,
+       pg_size_pretty(pg_total_relation_size(c.oid)) AS total_size,
+       pg_size_pretty(pg_table_size(c.oid)) AS table_size,
+       pg_size_pretty(pg_indexes_size(c.oid)) AS index_size
+     FROM pg_catalog.pg_stat_user_tables s
+     JOIN pg_catalog.pg_class c ON c.relname = s.relname
+     JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace AND n.nspname = s.schemaname
+     WHERE s.schemaname = $1 AND s.relname = $2`, [schema, tableName]);
+    return result.rows[0] ?? null;
+}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+/**
+ * DB Info Sync MCP Server 入口文件
+ *
+ * 架构概述:
+ * - 本项目是一个 MCP (Model Context Protocol) Server，通过 stdio 传输与 AI 客户端（如 Claude Desktop/Claude Code）通信
+ * - 提供只读的 PostgreSQL 数据库元数据查询能力，支持 ShardingSphere 风格的分片拓扑解析
+ * - 配置文件采用 YAML 格式，兼容 ShardingSphere 配置，管理多个数据源和分片规则
+ *
+ * 安全策略（多层防御）:
+ * 1. 连接级别: pg.Pool 设置 default_transaction_read_only=on，数据库层面禁止写操作
+ * 2. SQL 级别: query_metadata tool 仅允许查询 information_schema/pg_catalog 的 SELECT 语句
+ * 3. Tool 级别: 所有预定义 tool 只执行固定的元数据查询 SQL
+ *
+ * 模块结构:
+ * - src/config/  — 配置类型定义(types.ts)和 YAML 解析器(parser.ts)
+ * - src/db/      — 数据库连接池管理(connection-manager.ts)和元数据查询封装(metadata-queries.ts)
+ * - src/tools/   — 8 个 MCP Tool 的实现，每个 tool 一个文件
+ *
+ * 启动流程:
+ * 1. 读取 YAML 配置文件 → 2. 创建 ConnectionManager → 3. 注册 MCP Tools → 4. 启动 stdio 传输
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+/**
+ * DB Info Sync MCP Server 入口文件
+ *
+ * 架构概述:
+ * - 本项目是一个 MCP (Model Context Protocol) Server，通过 stdio 传输与 AI 客户端（如 Claude Desktop/Claude Code）通信
+ * - 提供只读的 PostgreSQL 数据库元数据查询能力，支持 ShardingSphere 风格的分片拓扑解析
+ * - 配置文件采用 YAML 格式，兼容 ShardingSphere 配置，管理多个数据源和分片规则
+ *
+ * 安全策略（多层防御）:
+ * 1. 连接级别: pg.Pool 设置 default_transaction_read_only=on，数据库层面禁止写操作
+ * 2. SQL 级别: query_metadata tool 仅允许查询 information_schema/pg_catalog 的 SELECT 语句
+ * 3. Tool 级别: 所有预定义 tool 只执行固定的元数据查询 SQL
+ *
+ * 模块结构:
+ * - src/config/  — 配置类型定义(types.ts)和 YAML 解析器(parser.ts)
+ * - src/db/      — 数据库连接池管理(connection-manager.ts)和元数据查询封装(metadata-queries.ts)
+ * - src/tools/   — 8 个 MCP Tool 的实现，每个 tool 一个文件
+ *
+ * 启动流程:
+ * 1. 读取 YAML 配置文件 → 2. 创建 ConnectionManager → 3. 注册 MCP Tools → 4. 启动 stdio 传输
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { parseConfig } from './config/parser.js';
+import { ConnectionManager } from './db/connection-manager.js';
+import { registerListDatasources } from './tools/list-datasources.js';
+import { registerListTables } from './tools/list-tables.js';
+import { registerDescribeTable } from './tools/describe-table.js';
+import { registerDescribeIndexes } from './tools/describe-indexes.js';
+import { registerShardingTopology } from './tools/sharding-topology.js';
+import { registerQueryMetadata } from './tools/query-metadata.js';
+import { registerTestConnection } from './tools/test-connection.js';
+import { registerSaveDatasourceConfig } from './tools/save-datasource-config.js';
+async function main() {
+    // 配置文件路径优先级: 命令行参数 > 环境变量 > 默认路径
+    // 全局安装时默认配置路径为 ~/.harneon-ai/db/datasource.yaml，与 npm 组织名 @harneon-ai 一致
+    const defaultConfigPath = path.join(os.homedir(), '.harneon-ai', 'db', 'datasource.yaml');
+    const configPath = process.argv[2] || process.env.DB_CONFIG_PATH || defaultConfigPath;
+    // 容错启动: 配置文件不存在时使用空配置，允许用户通过 save_datasource_config 创建首份配置
+    let config;
+    if (fs.existsSync(configPath)) {
+        config = parseConfig(configPath);
+    }
+    else {
+        config = { dataSources: {} };
+        console.error(`配置文件 ${configPath} 不存在，使用空配置启动。可通过 save_datasource_config 工具创建配置。`);
+    }
+    // ConnectionManager 采用懒初始化策略，此时不会创建任何数据库连接
+    const connectionManager = new ConnectionManager(config);
+    const server = new McpServer({
+        name: '@harneon-ai/db',
+        version: '0.0.1',
+    });
+    // 注册所有 MCP Tools
+    // 只读工具:
+    // - list_datasources: 查看数据源配置（纯配置读取，不连接数据库）
+    // - list_tables: 列出指定数据源的表
+    // - describe_table: 查询表结构（列、约束、统计信息）
+    // - describe_indexes: 查询表的索引信息
+    // - sharding_topology: 查看分片拓扑（纯配置解析，不连接数据库）
+    // - query_metadata: 执行自定义元数据查询（带安全过滤）
+    // 数据源注册工具:
+    // - test_connection: 测试 PostgreSQL 连接（独立于配置和连接池）
+    // - save_datasource_config: 保存数据源配置到 YAML 文件并更新内存状态
+    registerListDatasources(server, config, connectionManager);
+    registerListTables(server, config, connectionManager);
+    registerDescribeTable(server, config, connectionManager);
+    registerDescribeIndexes(server, config, connectionManager);
+    registerShardingTopology(server, config, connectionManager);
+    registerQueryMetadata(server, config, connectionManager);
+    registerTestConnection(server);
+    registerSaveDatasourceConfig(server, config, connectionManager, configPath);
+    // 优雅退出: 收到终止信号时关闭所有数据库连接池
+    const shutdown = async () => {
+        await connectionManager.shutdown();
+        process.exit(0);
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+    // MCP 使用 stdio 传输: stdin 接收请求，stdout 发送响应
+    // 注意: 应用日志必须输出到 stderr，避免干扰 MCP 协议通信
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error('MCP Server 启动失败:', error);
+    process.exit(1);
+});

package/dist/tools/describe-indexes.d.ts

@@ -0,0 +1,11 @@
+/**
+ * MCP Tool: describe_indexes
+ *
+ * 查询指定表的所有索引信息。
+ * 通过 pg_catalog 系统表查询，返回索引名称、包含列、唯一性、索引方法（btree/hash/gin 等）
+ * 以及完整的 CREATE INDEX 语句定义。
+ */
+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 registerDescribeIndexes(server: McpServer, _config: ParsedConfig, connectionManager: ConnectionManager): void;

package/dist/tools/describe-indexes.js

@@ -0,0 +1,36 @@
+/**
+ * MCP Tool: describe_indexes
+ *
+ * 查询指定表的所有索引信息。
+ * 通过 pg_catalog 系统表查询，返回索引名称、包含列、唯一性、索引方法（btree/hash/gin 等）
+ * 以及完整的 CREATE INDEX 语句定义。
+ */
+import { z } from 'zod';
+import { describeIndexes } from '../db/metadata-queries.js';
+export function registerDescribeIndexes(server, _config, connectionManager) {
+    server.tool('describe_indexes', '查询指定表的所有索引信息', {
+        datasource: z.string().describe('数据源名称'),
+        table: z.string().describe('表名'),
+        schema: z.string().optional().default('public').describe('Schema 名称，默认 public'),
+    }, async ({ datasource, table, schema }) => {
+        try {
+            const pool = await connectionManager.getPool(datasource);
+            const indexes = await describeIndexes(pool, table, schema);
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify(indexes, null, 2),
+                    }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ error: err instanceof Error ? err.message : String(err) }),
+                    }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/describe-table.d.ts

@@ -0,0 +1,14 @@
+/**
+ * MCP Tool: describe_table
+ *
+ * 查询指定表的完整结构信息，包含:
+ * - columns: 列定义（名称、类型、可空、默认值、注释）
+ * - constraints: 约束信息（主键、外键、唯一约束）
+ * - stats: 统计信息（行数估算、表大小、索引大小）
+ *
+ * 三个查询并行执行以减少延迟。
+ */
+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 registerDescribeTable(server: McpServer, _config: ParsedConfig, connectionManager: ConnectionManager): void;

package/dist/tools/describe-table.js

@@ -0,0 +1,45 @@
+/**
+ * MCP Tool: describe_table
+ *
+ * 查询指定表的完整结构信息，包含:
+ * - columns: 列定义（名称、类型、可空、默认值、注释）
+ * - constraints: 约束信息（主键、外键、唯一约束）
+ * - stats: 统计信息（行数估算、表大小、索引大小）
+ *
+ * 三个查询并行执行以减少延迟。
+ */
+import { z } from 'zod';
+import { describeTable, getTableConstraints, getTableStats } from '../db/metadata-queries.js';
+export function registerDescribeTable(server, _config, connectionManager) {
+    server.tool('describe_table', '查询指定表的详细结构（列信息、约束、统计）', {
+        datasource: z.string().describe('数据源名称'),
+        table: z.string().describe('表名'),
+        schema: z.string().optional().default('public').describe('Schema 名称，默认 public'),
+    }, async ({ datasource, table, schema }) => {
+        try {
+            const pool = await connectionManager.getPool(datasource);
+            // 并行查询列信息、约束和统计，减少总延迟
+            const [columns, constraints, stats] = await Promise.all([
+                describeTable(pool, table, schema),
+                getTableConstraints(pool, table, schema),
+                getTableStats(pool, table, schema),
+            ]);
+            const result = { columns, constraints, stats };
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify(result, null, 2),
+                    }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ error: err instanceof Error ? err.message : String(err) }),
+                    }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/list-datasources.d.ts

@@ -0,0 +1,11 @@
+/**
+ * MCP Tool: list_datasources
+ *
+ * 列出所有已配置的数据源连接信息。
+ * 这是一个纯配置读取操作，不连接任何数据库。
+ * 密码字段始终显示为 '***'，防止敏感信息泄露。
+ */
+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 registerListDatasources(server: McpServer, config: ParsedConfig, _connectionManager: ConnectionManager): void;

package/dist/tools/list-datasources.js

@@ -0,0 +1,40 @@
+/**
+ * MCP Tool: list_datasources
+ *
+ * 列出所有已配置的数据源连接信息。
+ * 这是一个纯配置读取操作，不连接任何数据库。
+ * 密码字段始终显示为 '***'，防止敏感信息泄露。
+ */
+import { parseJdbcUrl } from '../config/parser.js';
+export function registerListDatasources(server, config, _connectionManager) {
+    server.tool('list_datasources', '列出所有配置的数据源信息（密码已隐藏）', {}, // 无输入参数
+    async () => {
+        const datasources = Object.entries(config.dataSources).map(([name, ds]) => {
+            const jdbcUrl = ds.jdbcUrl || ds.url || '';
+            let host = '', port = 0, database = '';
+            try {
+                const parsed = parseJdbcUrl(jdbcUrl);
+                host = parsed.host;
+                port = parsed.port;
+                database = parsed.database;
+            }
+            catch {
+                // URL 解析失败时保留空值，不阻断返回
+            }
+            return {
+                name,
+                host,
+                port,
+                database,
+                username: ds.username,
+                password: '***', // 安全: 始终隐藏密码
+            };
+        });
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(datasources, null, 2),
+                }],
+        };
+    });
+}

package/dist/tools/list-tables.d.ts

@@ -0,0 +1,10 @@
+/**
+ * MCP Tool: list_tables
+ *
+ * 列出指定数据源中的所有用户表和视图。
+ * 查询 information_schema.tables，仅返回 BASE TABLE 和 VIEW 类型。
+ */
+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 registerListTables(server: McpServer, _config: ParsedConfig, connectionManager: ConnectionManager): void;

package/dist/tools/list-tables.js

@@ -0,0 +1,34 @@
+/**
+ * MCP Tool: list_tables
+ *
+ * 列出指定数据源中的所有用户表和视图。
+ * 查询 information_schema.tables，仅返回 BASE TABLE 和 VIEW 类型。
+ */
+import { z } from 'zod';
+import { listTables } from '../db/metadata-queries.js';
+export function registerListTables(server, _config, connectionManager) {
+    server.tool('list_tables', '列出指定数据源中的所有表和视图', {
+        datasource: z.string().describe('数据源名称，如 ds_0'),
+        schema: z.string().optional().default('public').describe('Schema 名称，默认 public'),
+    }, async ({ datasource, schema }) => {
+        try {
+            const pool = await connectionManager.getPool(datasource);
+            const tables = await listTables(pool, schema);
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify(tables, null, 2),
+                    }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ error: err instanceof Error ? err.message : String(err) }),
+                    }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/query-metadata.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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 { 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 registerQueryMetadata(server: McpServer, _config: ParsedConfig, connectionManager: ConnectionManager): void;