MCP Csv Postgres

🚀 CSV to PostgreSQL MCP Server

このMCP (Model Context Protocol) サーバーは、CSVファイルをPostgreSQLデータベースに読み込み、検証と進捗追跡を行います。

✨ 主な機能

• CSV検証：CSV構造を検証し、詳細なエラーメッセージを提供します。
• 効率的な読み込み：PostgreSQLのCOPYコマンドを使用して、高速な一括読み込みを行います。
• 進捗追跡：長時間かかるインポートの進捗バーを表示します。
• 柔軟な設定：データベース名をオプションで指定できます（デフォルトは csvimports）。
• エラー報告：検証エラーの正確な行番号と列情報を提供します。

📦 インストール

PyPIからのインストール

pip install mcp-csv-postgres

またはuvを使用する場合：

uv pip install mcp-csv-postgres

ソースからのインストール

リポジトリをクローンし、uvでインストールします：

git clone https://github.com/raviramadoss/mcp-csv-postgres.git
cd mcp-csv-postgres
uv sync --all-extras

💻 使用例

MCPサーバーとしての使用

オプション1: PyPIからインストールした後

Claude Desktopの設定ファイル（macOSでは~/Library/Application Support/Claude/claude_desktop_config.json）に追加します：

{
  "mcpServers": {
    "mcp-csv-postgres": {
      "command": "uv",
      "args": [
        "tool",
        "run",
        "--from",
        "mcp-csv-postgres",
        "mcp-csv-postgres"
      ]
    }
  }
}

オプション2: ローカル開発用

{
  "mcpServers": {
    "mcp-csv-postgres": {
      "command": "uv",
      "args": [
        "tool",
        "run",
        "--from",
        "/path/to/mcp-csv-postgres",
        "--python",
        "3.10",
        "mcp-csv-postgres"
      ]
    }
  }
}

またはコマンドラインから直接実行します：

mcp-csv-postgres

ツール: load_csv_to_postgres

CSVファイルをPostgreSQLデータベースに読み込みます。 パラメータ:

• file_path (必須): CSVファイルのパス
• dbname (オプション): データベース名（デフォルト: csvimports）
• host (オプション): PostgreSQLホスト（デフォルト: localhost）
• port (オプション): PostgreSQLポート（デフォルト: 5432）
• user (オプション): PostgreSQLユーザー（デフォルト: postgres）
• password (オプション): PostgreSQLパスワード
• table_name (オプション): テーブル名（指定されない場合はファイル名から導出） 戻り値:
• データベース名、テーブル名、および読み込まれた行数を含む成功メッセージ
• 詳細な検証またはデータベースエラーを含むエラーメッセージ

サーバーのテスト

クイックテスト

テストスクリプトを実行して、サーバーの動作を確認します：

uv run python test_server.py

これにより以下のことが行われます：

1. サンプルCSVファイルを作成します。
2. それらをPostgreSQLに読み込むテストを行います。
3. 検証エラー報告のテストを行います。
4. 詳細な出力を表示します。

サンプルデータを使用した手動テスト

sample_data.csvにサンプルCSVファイルが用意されています。手動でテストするには：

# Python/IPythonで
import asyncio
from mcp_csv_postgres.server import call_tool

result = asyncio.run(call_tool(
    "load_csv_to_postgres",
    {"file_path": "sample_data.csv"}
))
print(result[0].text)

MCPインスペクターを使用したテスト

MCPインスペクターツールを使用してテストするには：

npx @modelcontextprotocol/inspector uv run mcp-csv-postgres

VS Codeの起動構成

.vscode/launch.jsonには以下が含まれています：

• Run MCP Server: サーバーをデバッグモードで起動します。
• Test MCP Server with Sample CSV: テストスクリプトを実行します。
• Run All Tests: 完全なテストスイートを実行します。
• Run Specific Test: 単一のテストファイルをデバッグします。

🔧 開発

テストの実行

uv run pytest

コードカバレッジ

uv run pytest --cov-report=html

カバレッジレポートはhtmlcov/index.htmlで確認できます。 現在のカバレッジ: >90%

プリコミットフック

コミット前にテストを実行するようにプリコミットフックが設定されています：

uv run pre-commit install
uv run pre-commit run --all-files

🔧 技術詳細

モジュール

• validator.py: 詳細なエラー報告を伴うCSV検証
  • ファイルの存在と読み取り可能性のチェック
  • CSV構造の検証
  • 行の一貫性の検証
  • 自動方言検出
• database.py: PostgreSQLデータベース操作
  • 接続管理
  • データベースの作成
  • CSVヘッダーからのテーブル作成
  • 行のカウント
• loader.py: COPYコマンドを使用したCSV読み込み
  • tqdmによる進捗追跡
  • 効率的な一括読み込み
  • エラー処理とロールバック
• server.py: MCPサーバーの実装
  • stdioトランスポート
  • ツールの登録
  • エラー処理

エラー処理

サーバーは詳細なエラーメッセージを提供します：

• 検証エラー: CSVの問題の正確な行番号と説明
• データベースエラー: 接続、パーミッション、およびSQLエラー
• ファイルエラー: パーミッション、エンコーディング、およびファイルが見つからないエラー

サンプル

基本的な使用法

{
  "tool": "load_csv_to_postgres",
  "arguments": {
    "file_path": "/path/to/data.csv"
  }
}

高度な使用法

{
  "tool": "load_csv_to_postgres",
  "arguments": {
    "file_path": "/path/to/data.csv",
    "dbname": "mydb",
    "table_name": "my_table"
  }
}

📄 ライセンス

MIT