Postgresql & DuckDB

🚀 MCP 數據庫項目文檔

本項目提供了一系列工具和資源，用於與 PostgreSQL 數據庫和 Google Cloud Storage (GCS) 進行交互，幫助開發者更高效地管理和操作數據。

🚀 快速開始

要使用 MCP 數據庫項目，你需要完成安裝依賴、配置環境變量和初始化數據庫這幾個步驟。

📦 安裝指南

1. 安裝依賴

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

2. 配置環境變量

項目運行依賴以下環境變量：

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，並設置了正確的憑據。