@timmy_hu/pg-query-tool 1.0.0

package/.xpertai-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "PostgreSQL 查询工具",
+  "code": "pg-query-tool",
+  "version": "1.0.0",
+  "description": "提供 PostgreSQL 数据库查询能力的 XpertAI 插件，支持自定义 SQL 执行、连接池管理和结果格式化",
+  "createdBy": "fpi",
+  "platform": "https://app.xpertai.cn/",
+  "main": "index.js"
+}

package/README.md

@@ -0,0 +1,157 @@
+# PostgreSQL 查询工具 (pg-query-tool)
+
+> XpertAI 插件 — 提供 PostgreSQL 数据库查询能力，支持自定义 SQL 执行、连接池管理和结果格式化。
+
+## 插件简介
+
+`pg-query-tool` 是一个 XpertAI 平台插件，通过 MCP Tool 形式暴露 PostgreSQL 数据库查询能力。它基于 `pg` 驱动和连接池实现，支持参数化查询、表结构查看和自动行数限制。
+
+## 适用场景
+
+- 在 XpertAI 对话中直接查询 PostgreSQL 数据库
+- 通过自然语言驱动的 AI Agent 执行结构化 SQL 查询
+- 数据探查、表结构查看、快速验证查询结果
+- 业务数据检索与报表数据获取
+
+## 目录结构
+
+```text
+pg-query-tool/
+├── .xpertai-plugin/
+│   └── plugin.json          # 插件清单
+├── index.js                  # 入口文件，导出 XpertPlugin
+├── package.json              # npm 包定义
+├── README.md
+├── src/
+│   ├── pg-query-tool.module.js       # NestJS 模块
+│   ├── pg-query-tool.service.js      # 核心服务（连接池 + 查询）
+│   ├── schemas/
+│   │   ├── config.schema.js          # 配置 Schema
+│   │   └── tool.schema.js            # 工具输入输出 Schema
+│   └── mcp/
+│       ├── pg-query-tool.mcp-server.js  # MCP Server 工具集
+│       └── tools/
+└── examples/
+    └── request.example.json          # 请求示例
+```
+
+## 安装
+
+```bash
+# 在 XpertAI 平台通过 npm 安装
+# 插件包名: @timmy_hu/pg-query-tool
+# 版本: 1.0.0
+```
+
+## 配置项
+
+| 配置项 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| `host` | string | 是 | - | PostgreSQL 主机地址 |
+| `port` | number | 否 | 5432 | PostgreSQL 端口 |
+| `database` | string | 是 | - | 数据库名称 |
+| `username` | string | 是 | - | 数据库用户名 |
+| `password` | string | 是 | - | 数据库密码 |
+| `maxPoolSize` | number | 否 | 10 | 连接池最大连接数 |
+| `queryTimeout` | number | 否 | 30000 | 查询超时（毫秒） |
+| `ssl` | boolean | 否 | false | 是否启用 SSL |
+
+## MCP 工具列表
+
+### 1. execute-query（执行SQL查询）
+
+执行任意 SQL 查询语句，支持参数化查询和自动行数限制。
+
+**入参：**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `sql` | string | 是 | SQL 查询语句 |
+| `params` | array | 否 | 参数化查询参数 |
+| `limit` | number | 否 | 返回行数限制，默认 1000 |
+
+**返回示例：**
+
+```json
+{
+  "success": true,
+  "rowCount": 2,
+  "rows": [
+    { "id": 1, "name": "Alice" },
+    { "id": 2, "name": "Bob" }
+  ],
+  "fields": [
+    { "name": "id", "dataTypeID": 23 },
+    { "name": "name", "dataTypeID": 1043 }
+  ],
+  "duration": 12
+}
+```
+
+### 2. list-tables（获取表列表）
+
+获取指定 schema 下的所有表。
+
+**入参：**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `schema` | string | 否 | schema 名称，默认 public |
+
+### 3. describe-table（获取表结构）
+
+获取指定表的列结构信息。
+
+**入参：**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `tableName` | string | 是 | 表名称 |
+| `schema` | string | 否 | schema 名称，默认 public |
+
+## 调用示例
+
+```javascript
+// 执行查询
+const result = await mcpTool['execute-query'].handler({
+  sql: 'SELECT * FROM users WHERE id = $1',
+  params: [1],
+  limit: 100
+});
+
+// 获取表列表
+const tables = await mcpTool['list-tables'].handler({
+  schema: 'public'
+});
+
+// 获取表结构
+const columns = await mcpTool['describe-table'].handler({
+  tableName: 'users'
+});
+```
+
+## 常见错误和处理
+
+| 错误 | 原因 | 处理方式 |
+|------|------|----------|
+| `ECONNREFUSED` | 数据库未启动或地址错误 | 检查 host/port 配置和数据库状态 |
+| `password authentication failed` | 用户名或密码错误 | 检查 username/password 配置 |
+| `relation does not exist` | 表名不存在 | 先用 list-tables 确认表名 |
+| `timeout` | 查询超时 | 调整 queryTimeout 或优化 SQL |
+
+## 安全注意事项
+
+- **参数化查询**：始终使用 `$1, $2` 参数化查询，避免 SQL 注入
+- **只读建议**：生产环境建议配置只读数据库用户
+- **行数限制**：默认限制 1000 行，防止大量数据传输
+- **密码安全**：密码通过 XpertAI 配置项管理，不会暴露在代码中
+
+## 使用方式
+
+1. 在 XpertAI 平台安装此插件
+2. 配置 PostgreSQL 连接信息（host、port、database、username、password）
+3. 在 AI 对话中通过自然语言触发 SQL 查询
+
+## 下一步
+
+前往 [XpertAI 平台](https://app.xpertai.cn) 使用此插件。

package/index.js

@@ -0,0 +1,27 @@
+/**
+ * PostgreSQL 查询工具 - XpertAI 插件入口
+ * 导出有效的 XpertPlugin 对象，供 XpertAI 平台加载
+ */
+
+const { PgQueryToolModule } = require('./src/pg-query-tool.module');
+
+const plugin = {
+  meta: {
+    name: "pg-query-tool",
+    version: "1.0.0",
+    displayName: "PostgreSQL 查询工具",
+    description: "提供 PostgreSQL 数据库查询能力，支持自定义 SQL 执行、连接池管理和结果格式化",
+    author: "fpi"
+  },
+  register(ctx) {
+    return {
+      module: PgQueryToolModule,
+      providers: [],
+      controllers: [],
+      exports: []
+    };
+  }
+};
+
+module.exports = plugin;
+module.exports.default = plugin;

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@timmy_hu/pg-query-tool",
+  "version": "1.0.0",
+  "description": "PostgreSQL 查询工具 XpertAI 插件，支持自定义 SQL 执行、连接池管理和结果格式化",
+  "main": "index.js",
+  "scripts": {
+    "build": "tsc",
+    "test": "node test/self-check.js"
+  },
+  "keywords": [
+    "xpertai",
+    "plugin",
+    "postgresql",
+    "pg",
+    "query",
+    "database"
+  ],
+  "author": "fpi",
+  "license": "MIT",
+  "dependencies": {
+    "pg": "^8.13.0"
+  },
+  "peerDependencies": {
+    "@xpert-ai/plugin-sdk": "^3.14.0"
+  },
+  "files": [
+    "index.js",
+    "src/",
+    ".xpertai-plugin/",
+    "README.md"
+  ]
+}

package/src/mcp/pg-query-tool.mcp-server.js

@@ -0,0 +1,108 @@
+/**
+ * PostgreSQL 查询工具 - MCP Server
+ * 暴露 MCP Tool 能力供 XpertAI 平台调用
+ */
+
+const { PgQueryToolService } = require('../pg-query-tool.service');
+
+/**
+ * 创建 MCP Server 工具集
+ * @param {Object} config - 插件配置（来自 configSchema）
+ * @returns {Object} 工具定义对象
+ */
+function createMcpTools(config) {
+  const service = new PgQueryToolService(config);
+
+  return {
+    /** 执行 SQL 查询 */
+    'execute-query': {
+      name: '执行SQL查询',
+      code: 'execute-query',
+      description: '在 PostgreSQL 数据库上执行 SQL 查询语句，支持参数化查询',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          sql: { type: 'string', description: '要执行的 SQL 查询语句' },
+          params: {
+            type: 'array',
+            description: 'SQL 参数化查询的参数数组',
+            items: {}
+          },
+          limit: { type: 'integer', description: '返回结果最大行数限制，默认 1000' }
+        },
+        required: ['sql']
+      },
+      outputSchema: {
+        type: 'object',
+        properties: {
+          success: { type: 'boolean' },
+          rowCount: { type: 'integer' },
+          rows: { type: 'array' },
+          fields: { type: 'array' },
+          duration: { type: 'number' },
+          error: { type: 'string' }
+        }
+      },
+      handler: async (args) => {
+        const { sql, params = [], limit = 1000 } = args;
+        return service.executeQuery(sql, params, limit);
+      }
+    },
+
+    /** 获取表列表 */
+    'list-tables': {
+      name: '获取表列表',
+      code: 'list-tables',
+      description: '获取 PostgreSQL 数据库中指定 schema 下的所有表列表',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          schema: { type: 'string', description: 'schema 名称，默认 public' }
+        }
+      },
+      outputSchema: {
+        type: 'object',
+        properties: {
+          success: { type: 'boolean' },
+          rowCount: { type: 'integer' },
+          rows: { type: 'array' },
+          duration: { type: 'number' }
+        }
+      },
+      handler: async (args) => {
+        const { schema = 'public' } = args;
+        return service.listTables(schema);
+      }
+    },
+
+    /** 获取表结构 */
+    'describe-table': {
+      name: '获取表结构',
+      code: 'describe-table',
+      description: '获取 PostgreSQL 指定表的列结构信息（列名、类型、是否可空等）',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          tableName: { type: 'string', description: '表名称' },
+          schema: { type: 'string', description: 'schema 名称，默认 public' }
+        },
+        required: ['tableName']
+      },
+      outputSchema: {
+        type: 'object',
+        properties: {
+          success: { type: 'boolean' },
+          rowCount: { type: 'integer' },
+          rows: { type: 'array' },
+          duration: { type: 'number' }
+        }
+      },
+      handler: async (args) => {
+        const { tableName, schema = 'public' } = args;
+        return service.describeTable(tableName, schema);
+      }
+    }
+  };
+}
+
+module.exports = { createMcpTools };

package/src/pg-query-tool.module.js

@@ -0,0 +1,31 @@
+/**
+ * PostgreSQL 查询工具 - NestJS 模块定义
+ * 注册 service 和 MCP 工具
+ */
+
+const { PgQueryToolService } = require('./pg-query-tool.service');
+const { createMcpTools } = require('./mcp/pg-query-tool.mcp-server');
+
+class PgQueryToolModule {
+  static register(config) {
+    const service = new PgQueryToolService(config);
+    const mcpTools = createMcpTools(config);
+
+    return {
+      module: PgQueryToolModule,
+      providers: [
+        { provide: 'PG_QUERY_TOOL_CONFIG', useValue: config },
+        { provide: 'PG_QUERY_TOOL_SERVICE', useValue: service },
+        { provide: 'PG_QUERY_TOOL_MCP_TOOLS', useValue: mcpTools }
+      ],
+      controllers: [],
+      exports: [
+        'PG_QUERY_TOOL_CONFIG',
+        'PG_QUERY_TOOL_SERVICE',
+        'PG_QUERY_TOOL_MCP_TOOLS'
+      ]
+    };
+  }
+}
+
+module.exports = { PgQueryToolModule };

package/src/pg-query-tool.service.js

@@ -0,0 +1,140 @@
+/**
+ * PostgreSQL 查询工具 - 核心服务
+ * 封装 pg.Pool 连接池管理和查询执行逻辑
+ */
+
+// 延迟加载 pg 模块，避免插件加载时因缺少运行时依赖而失败
+let Pool = null;
+
+class PgQueryToolService {
+  constructor(config) {
+    this.config = config;
+    this.pool = null;
+  }
+
+  /**
+   * 初始化连接池
+   */
+  async init() {
+    if (this.pool) return;
+
+    if (!Pool) {
+      const pg = require('pg');
+      Pool = pg.Pool;
+    }
+
+    this.pool = new Pool({
+      host: this.config.host,
+      port: this.config.port || 5432,
+      database: this.config.database,
+      user: this.config.username,
+      password: this.config.password,
+      max: this.config.maxPoolSize || 10,
+      idleTimeoutMillis: 30000,
+      connectionTimeoutMillis: this.config.queryTimeout || 30000,
+      ssl: this.config.ssl ? { rejectUnauthorized: false } : false
+    });
+
+    this.pool.on('error', (err) => {
+      console.error('[pg-query-tool] 连接池异常:', err.message);
+    });
+  }
+
+  /**
+   * 执行 SQL 查询
+   * @param {string} sql - SQL 语句
+   * @param {Array} params - 参数化查询参数
+   * @param {number} limit - 返回行数限制
+   * @returns {Object} 查询结果
+   */
+  async executeQuery(sql, params = [], limit = 1000) {
+    await this.init();
+
+    // 自动追加 LIMIT（如果原 SQL 没有且 limit > 0）
+    let finalSql = sql.trim();
+    if (limit > 0 && !/^SELECT\s+/i.test(finalSql)) {
+      // 非 SELECT 语句不加 LIMIT
+    } else if (limit > 0 && !/\bLIMIT\b/i.test(finalSql)) {
+      finalSql = `${finalSql} LIMIT ${limit}`;
+    }
+
+    const startTime = Date.now();
+    try {
+      const result = await this.pool.query(finalSql, params);
+      const duration = Date.now() - startTime;
+
+      return {
+        success: true,
+        rowCount: result.rowCount,
+        rows: result.rows,
+        fields: result.fields ? result.fields.map(f => ({
+          name: f.name,
+          dataTypeID: f.dataTypeID
+        })) : [],
+        duration
+      };
+    } catch (err) {
+      const duration = Date.now() - startTime;
+      return {
+        success: false,
+        rowCount: 0,
+        rows: [],
+        duration,
+        error: err.message
+      };
+    }
+  }
+
+  /**
+   * 获取表列表
+   * @param {string} schema - schema 名称，默认 public
+   * @returns {Object} 查询结果
+   */
+  async listTables(schema = 'public') {
+    const sql = `
+      SELECT
+        table_name AS "tableName",
+        table_schema AS "schema",
+        table_type AS "type"
+      FROM information_schema.tables
+      WHERE table_schema = $1
+      ORDER BY table_name
+    `;
+    return this.executeQuery(sql, [schema], 0);
+  }
+
+  /**
+   * 获取表结构
+   * @param {string} tableName - 表名
+   * @param {string} schema - schema 名称
+   * @returns {Object} 查询结果
+   */
+  async describeTable(tableName, schema = 'public') {
+    const sql = `
+      SELECT
+        column_name AS "columnName",
+        data_type AS "dataType",
+        character_maximum_length AS "maxLength",
+        is_nullable AS "nullable",
+        column_default AS "defaultValue",
+        ordinal_position AS "position"
+      FROM information_schema.columns
+      WHERE table_name = $1 AND table_schema = $2
+      ORDER BY ordinal_position
+    `;
+    return this.executeQuery(sql, [tableName, schema], 0);
+  }
+
+  /**
+   * 销毁连接池
+   */
+  async destroy() {
+    if (this.pool) {
+      await this.pool.end();
+      this.pool = null;
+      console.log('[pg-query-tool] 连接池已关闭');
+    }
+  }
+}
+
+module.exports = { PgQueryToolService };

package/src/schemas/config.schema.js

@@ -0,0 +1,34 @@
+/**
+ * PostgreSQL 查询工具 - 配置 Schema
+ * 使用 zod 声明插件配置项
+ */
+
+const { z } = require('zod');
+
+const configSchema = z.object({
+  /** PostgreSQL 主机地址 */
+  host: z.string().describe('PostgreSQL 主机地址，例如 127.0.0.1'),
+
+  /** PostgreSQL 端口 */
+  port: z.number().int().default(5432).describe('PostgreSQL 端口，默认 5432'),
+
+  /** 数据库名称 */
+  database: z.string().describe('数据库名称'),
+
+  /** 用户名 */
+  username: z.string().describe('数据库用户名'),
+
+  /** 密码 */
+  password: z.string().describe('数据库密码'),
+
+  /** 连接池最大连接数 */
+  maxPoolSize: z.number().int().default(10).describe('连接池最大连接数，默认 10'),
+
+  /** 查询超时时间（毫秒） */
+  queryTimeout: z.number().int().default(30000).describe('查询超时时间（毫秒），默认 30000'),
+
+  /** 是否启用 SSL */
+  ssl: z.boolean().default(false).describe('是否启用 SSL 连接，默认 false')
+});
+
+module.exports = { configSchema };

package/src/schemas/tool.schema.js

@@ -0,0 +1,44 @@
+/**
+ * PostgreSQL 查询工具 - 查询工具 Schema
+ * 定义 MCP 工具的输入输出 Schema
+ */
+
+const { z } = require('zod');
+
+/** 执行查询工具入参 */
+const executeQuerySchema = z.object({
+  sql: z.string().describe('要执行的 SQL 查询语句'),
+  params: z.array(z.any()).optional().describe('SQL 参数化查询的参数数组，例如 [1, "test"]'),
+  limit: z.number().int().optional().describe('返回结果最大行数限制，不传则使用默认值 1000')
+});
+
+/** 执行查询工具出参 */
+const queryResultSchema = z.object({
+  success: z.boolean().describe('查询是否成功'),
+  rowCount: z.number().int().describe('返回的行数'),
+  rows: z.array(z.record(z.any())).describe('查询结果行数组'),
+  fields: z.array(z.object({
+    name: z.string(),
+    dataTypeID: z.number().optional()
+  })).optional().describe('字段元信息'),
+  duration: z.number().describe('查询耗时（毫秒）'),
+  error: z.string().optional().describe('错误信息（仅失败时存在）')
+});
+
+/** 获取表列表工具入参 */
+const listTablesSchema = z.object({
+  schema: z.string().optional().describe('指定 schema 名称，默认为 public')
+});
+
+/** 获取表结构工具入参 */
+const describeTableSchema = z.object({
+  tableName: z.string().describe('表名称'),
+  schema: z.string().optional().describe('指定 schema 名称，默认为 public')
+});
+
+module.exports = {
+  executeQuerySchema,
+  queryResultSchema,
+  listTablesSchema,
+  describeTableSchema
+};