Postgresql & DuckDB

🚀 MCP データベースプロジェクトドキュメント

MCP データベースプロジェクトは、PostgreSQL データベースと DuckDB を利用したデータ操作を提供します。様々なツールとリソースを使って、データの挿入、クエリ、更新などの操作が可能です。

🚀 クイックスタート

このプロジェクトを使用するには、まずインストールと設定を行う必要があります。以下の手順に従って進めてください。

📦 インストール

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：GCS を設定した場合、DuckDB を使用して GCS 上の Parquet ファイルをクエリします。
• 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 がインストールされ、正しい認証情報が設定されていることを確認してください。