Deepspringai Parquet MCP Server

🚀 Parquet MCP サーバ

Parquet MCP サーバは、Parquet ファイルの操作や変換を行うためのサーバです。様々なツールを提供し、Parquet ファイルの情報取得、DuckDB や PostgreSQL への変換、Markdown ファイルの処理などが可能です。

🚀 クイックスタート

📦 インストール

プロジェクト構造

parquet-mcp-server/
├── README.md                # プロジェクト説明ファイル
├── src/                    # ソースコードディレクトリ
│   ├── __init__.py         # パッケージ初期化ファイル
│   ├── client.py           # MCPクライアントインターフェース
│   └── tools/              # ツールモジュール
│       ├── embedding.py    # 埋め込みツール
│       ├── parquet_info.py  # Parquet ファイル情報ツール
│       ├── duckdb_conversion.py  # DuckDB 変換ツール
│       ├── postgres_conversion.py  # PostgreSQL 変換ツール
│       └── markdown_processing.py  # Markdown 処理ツール
├── tests/                  # テストケースディレクトリ
│   ├── __init__.py         # テストパッケージ初期化ファイル
│   ├── test_embedding.py    # 埋め込み機能テスト
│   ├── test_parquet_info.py  # Parquet ファイル情報ツールテスト
│   ├── test_duckdb_conversion.py  # DuckDB 変換テスト
│   ├── test_postgres_conversion.py  # PostgreSQL 変換テスト
│   └── test_markdown_processing.py  # Markdown 処理テスト
└── requirements.txt        # プロジェクト依存関係管理ファイル

環境変数

.env ファイルに以下の環境変数を追加してください。

# 必要な設定
OPENAI_API_KEY=your_openai_api_key  # OpenAI API キー

# オプション設定（必要に応じて調整）
OLLAMA_SERVER_URL=http://localhost:11434  # Ollama サーバのアドレス、デフォルトはローカル

インストールと実行

コマンドラインツールを使用したインストール

pip install -r requirements.txt  # 依存関係のインストール
python src/run_server.py  # MCP サーバの起動

テストクライアントの使用

from parquet_mcp_server.client import (
    convert_to_duckdb, 
    embed_parquet, 
    get_parquet_info, 
    convert_to_postgres,
    process_markdown_file
)

# DuckDB 変換のテスト
result = convert_to_duckdb(
    parquet_path="input.parquet",
    output_dir="db_output"
)

# 埋め込み機能のテスト
result = embed_parquet(
    input_path="input.parquet",
    output_path="output.parquet", 
    column_name="text",
    embedding_column="embeddings",
    batch_size=2
)

# Parquet ファイル情報ツールのテスト
result = get_parquet_info("input.parquet")

# PostgreSQL 変換のテスト
result = convert_to_postgres(
    parquet_path="input.parquet", 
    table_name="my_table"
)

# Markdown 処理のテスト
result = process_markdown_file(
    file_path="input.md",
    output_path="output.parquet"
)

✨ 主な機能

💻 使用例

基本的な使用法

# 各ツールの使用例
from parquet_mcp_server.client import (
    convert_to_duckdb, 
    embed_parquet, 
    get_parquet_info, 
    convert_to_postgres,
    process_markdown_file
)

# DuckDB 変換
convert_to_duckdb(parquet_path="input.parquet", output_dir="db_output")

# 埋め込み
embed_parquet(input_path="input.parquet", output_path="output.parquet", column_name="text", embedding_column="embeddings", batch_size=2)

# Parquet ファイル情報取得
get_parquet_info("input.parquet")

# PostgreSQL 変換
convert_to_postgres(parquet_path="input.parquet", table_name="my_table")

# Markdown 処理
process_markdown_file(file_path="input.md", output_path="output.parquet")

各機能モジュールの詳細

埋め込みツール

def embed_parquet(
    input_path: str,
    output_path: str, 
    column_name: str = "text",
    embedding_column: str = "embeddings", 
    batch_size: int = 16
) -> None:
    # 機能：指定された列に埋め込みベクトルを生成し、新しい列に保存する
    # 入力：
    #   input_path: 入力 Parquet ファイルのパス
    #   output_path: 出力 Parquet ファイルのパス
    #   column_name: 埋め込みを生成する列名、デフォルトは "text"
    #   embedding_column: 埋め込み結果を保存する列名、デフォルトは "embeddings"
    #   batch_size: 処理バッチサイズ、デフォルトは 16

Parquet ファイル情報ツール

def get_parquet_info(parquet_path: str) -> Dict:
    # 機能：Parquet ファイルの基本情報と統計情報を取得する
    # 入力：
    #   parquet_path: Parquet ファイルのパス
    # 出力：
    #   Dict: ファイルサイズ、行数、列情報などを含む辞書

DuckDB 変換ツール

def convert_to_duckdb(
    parquet_path: str, 
    output_path: str,
    table_name: str = "parquet_table"
) -> None:
    # 機能：Parquet ファイルを DuckDB テーブルファイルに変換する
    # 入力：
    #   parquet_path: 入力 Parquet ファイルのパス
    #   output_path: 出力 .db ファイルのパス
    #   table_name: ターゲットテーブル名、デフォルトは "parquet_table"

PostgreSQL 変換ツール

def convert_to_postgres(
    parquet_path: str,
    host: str,
    database: str,
    user: str,
    password: str,
    table_name: str = "parquet_table",
    chunk_size: int = 1000
) -> None:
    # 機能：Parquet ファイルのデータを PostgreSQL データベースのテーブルにインポートする
    # 入力：
    #   parquet_path: 入力 Parquet ファイルのパス
    #   host: データベースのホストアドレス
    #   database: データベース名
    #   user: データベースのユーザ名
    #   password: データベースのパスワード
    #   table_name: ターゲットテーブル名、デフォルトは "parquet_table"
    #   chunk_size: 一度に挿入するデータ量、デフォルトは 1000

Markdown 処理ツール

def process_markdown_file(
    file_path: str,
    output_path: str,
    encoding: str = "utf-8",
    split_by: str = None,
    keep_separators: bool = False
) -> None:
    # 機能：Markdown ファイルを構造化された Parquet ファイルに変換する
    # 入力：
    #   file_path: 入力 Markdown ファイルのパス
    #   output_path: 出力 Parquet ファイルのパス
    #   encoding: 文字エンコーディング、デフォルトは "utf-8"
    #   split_by: 内容を区切る区切り文字（オプション）
    #   keep_separators: 区切り文字を保持するかどうか、デフォルトは False

🔧 技術詳細

テスト

テストサーバの起動

python src/run_server.py  # MCP サーバを起動する

テストケースの実行

python -m pytest tests/  # すべてのテストケースを実行する
python -m pytest tests/test_embedding.py  # 埋め込み機能のテスト
python -m pytest tests/test_parquet_info.py  # Parquet ファイル情報ツールのテスト
python -m pytest tests/test_duckdb_conversion.py  # DuckDB 変換ツールのテスト
python -m pytest tests/test_postgres_conversion.py  # PostgreSQL 変換ツールのテスト
python -m pytest tests/test_markdown_processing.py  # Markdown 処理ツールのテスト

API 応答形式

埋め込み応答

{
    "status": "success",
    "message": "embedding completed successfully",
    "result": {
        "input_count": 100,
        "output_file": "output.parquet"
    }
}

ファイル情報応答

{
    "file_size": "12.5 MB",
    "num_rows": 1000,
    "columns": [
        {"name": "text", "type": "string"},
        {"name": "label", "type": "int"}
    ]
}

📄 注意事項

⚠️ 重要な注意事項

• すべての依存関係をインストールしてください。特に llama-cpp-python と duckdb を確認してください。
• API 呼び出しエラーを避けるために、正しい環境変数を設定してください。
• 大きなファイルを処理する場合は、パフォーマンスを確保するためにバッチ処理を行うことをおすすめします。