Deepspringai Parquet MCP Server

🚀 Parquet MCP 服務器

Parquet MCP 服務器是一個用於處理 Parquet 文件的工具，提供了嵌入、信息獲取、格式轉換以及 Markdown 處理等功能，能幫助用戶高效地對 Parquet 文件進行操作。

🚀 快速開始

項目結構

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"
)

✨ 主要特性

• 嵌入工具：為 Parquet 文件的指定列生成嵌入向量並保存到新列。
• Parquet 文件信息工具：獲取 Parquet 文件的基本信息和統計信息。
• DuckDB 轉換工具：將 Parquet 文件轉換為 DuckDB 表格文件。
• PostgreSQL 轉換工具：將 Parquet 文件數據導入 PostgreSQL 數據庫表中。
• Markdown 處理工具：將 Markdown 文件轉換為結構化的 Parquet 文件。

📦 安裝指南

使用命令行工具安裝

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"
)

高級用法

在實際項目中，你可以根據具體需求調整工具的參數，例如在處理大文件時調整 batch_size 或 chunk_size 以保證性能。

📚 詳細文檔

功能模塊

嵌入工具

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"}
    ]
}

🔧 技術細節

環境變量

在 .env 文件中添加必要的環境變量，如 OPENAI_API_KEY 和 OLLAMA_SERVER_URL，以確保 API 調用的正常進行。

依賴管理

項目依賴通過 requirements.txt 進行管理，確保安裝了所有依賴項，特別是 llama-cpp-python 和 duckdb。

性能優化

處理大文件時，建議分批處理，例如在 embed_parquet 中調整 batch_size 或在 convert_to_postgres 中調整 chunk_size，以保證性能。

📄 許可證

文檔中未提及許可證相關信息。

⚠️ 重要提示

• 確保安裝了所有依賴項，特別是 llama-cpp-python 和 duckdb。
• 設置正確的環境變量以避免 API 調用錯誤。
• 處理大文件時建議分批處理以保證性能。