JinDaGe - PostgreSQL & DuckDB MCP Details

article

README

🚀 MCP 数据库项目文档

本项目提供了一系列工具和资源，用于与 PostgreSQL 数据库和 Google Cloud Storage (GCS) 进行交互，帮助开发者更高效地管理和操作数据。

🚀 快速开始

要使用 MCP 数据库项目，你需要完成安装依赖、配置环境变量和初始化数据库这几个步骤。

📦 安装指南

1. 安装依赖

npm install github:dwarvesf/mcp-db # 安装主包
npm install duckdb # 安装 DuckDB 扩展
npx duckdb-install # 安装 DuckDB 二进制文件（如果需要）

2. 配置环境变量

项目运行依赖以下环境变量： | 环境变量名 | 必填 | 描述 | |---------------------------|------|----------------------------------------------| | DATABASE_URL | 是 | PostgreSQL 数据库连接 URL，格式为：postgresql://username:password@host:port/database | | GCS_BUCKET | 否 | 如果配置了 GCS，请指定默认操作的桶名 |

3. 初始化数据库

初始化 DuckDB 执行以下命令：

npx github:dwarvesf/duckdb-insert --help # 查看帮助信息

✨ 主要特性

可用工具

duckdb_insert：通过 DuckDB 在 PostgreSQL 数据库上执行 INSERT 语句。仅允许 INSERT 类型的查询。
duckdb_query：直接在 PostgreSQL 数据库 (postgres_db) 上使用 DuckDB 的 postgres_query 函数执行只读 SQL 查询。自动为未限定表名添加前缀（例如，my_table 转换为 postgres_db.public.my_table）。
duckdb_read_parquet：使用 DuckDB 查询 GCS 上的 Parquet 文件（如果配置了 GCS 的话）。
duckdb_update：通过 DuckDB 在 PostgreSQL 数据库上执行 UPDATE 语句。

可用资源

mcp://gcs/objects：列出指定 GCS 桶中的所有对象。
mcp://db/tables：列出配置的 PostgreSQL 数据库中的所有表及其列信息。

📚 详细文档

开发指南：集成新工具或资源

此项目使用 mcp-framework。要添加新的工具或资源，请按照以下步骤操作：

1. 创建新类

在 src/tools 或 src/resources 目录下创建一个新的 .ts 文件。
定义一个类，该类继承自 MCPTool 或 MCPResource。
实现所需的属性（name、description、工具的 schema）和方法（工具的 execute 方法或资源的 read 方法）。
在 schema 属性中使用 Zod 进行输入验证（仅适用于工具）。
在类的构造函数中初始化任何依赖关系（如数据库连接或 GCS 客户端），通常从 src/services/ 或 src/config.ts 中获取配置。

示例工具 (src/tools/my_tool.ts)：

import { MCPTool } from "mcp-framework";
import { z } from "zod";
import { formatSuccessResponse } from "../utils.js";
import { getDuckDBConnection } from "../services/duckdb.js"; // 示例依赖

const MyToolInputSchema = z.object({
  param1: z.string().describe("参数 1 的描述"),
});

type MyToolInput = z.infer<typeof MyToolInputSchema>;

export class MyTool extends MCPTool<MyToolInput> {
  name = "my_tool";
  description = "描述我的工具的功能。";
  schema = MyToolInputSchema;

  async execute(args: MyToolInput) {
    // 在此处实现具体的业务逻辑
    return formatSuccessResponse({
      message: `成功执行 my_tool 工具，参数为：${args.param1}`,
    });
  };
}

// 导出工具实例（可选）
export const myTool = new MyTool();

2. 注册新工具或资源

在项目根目录下创建或修改 src/tools/index.ts 或 src/resources/index.ts 文件，将新工具或资源导出：

// 示例：在 tools 目录下的 index.ts 文件
export { myTool } from "./my_tool";

3. 使用新工具或资源

新的工具或资源将在应用启动时自动注册，并可以通过 MCP 框架的 API 进行调用。

🔧 技术细节

其他注意事项

确保所有环境变量正确配置，尤其是在生产环境中。
在处理数据库连接时，请务必使用适当的错误处理和连接池管理。
对于 GCS 操作，请确保安装并配置了 Google Cloud SDK，并设置了正确的凭据。

PostgreSQL & DuckDB