parquet_mcp_server

一个强大的 MCP (模型控制协议) 服务器，提供用于操作和分析 Parquet 文件的工具。该服务器旨在与 Claude Desktop 配合使用，并提供五个主要功能：

1. 文本嵌入生成: 使用 Ollama 模型将 Parquet 文件中的文本列转换为向量嵌入
2. Parquet 文件分析: 提取有关 Parquet 文件的详细信息，包括模式、行数和文件大小
3. DuckDB 集成: 将 Parquet 文件转换为 DuckDB 数据库，以实现高效的查询和分析
4. PostgreSQL 集成: 将 Parquet 文件转换为 PostgreSQL 表，并支持 pgvector 进行向量相似性搜索
5. Markdown 处理: 将 markdown 文件转换为带有元数据的分块文本，保留文档结构和链接

此服务器特别适用于：

• 处理大型 Parquet 数据集的数据科学家
• 需要文本数据向量嵌入的应用程序
• 需要分析或转换 Parquet 文件的项目
• 受益于 DuckDB 快速查询功能的工作流程
• 需要使用 PostgreSQL 和 pgvector 进行向量相似性搜索的应用程序

安装

通过 Smithery 安装

要通过 Smithery 为 Claude Desktop 自动安装 Parquet MCP Server：

npx -y @smithery/cli install @DeepSpringAI/parquet_mcp_server --client claude

克隆此存储库

git clone ...
cd parquet_mcp_server

创建并激活虚拟环境

uv venv
.venv\Scripts\activate  # 在 Windows 上
source .venv/bin/activate  # 在 macOS/Linux 上

安装包

uv pip install -e .

环境变量

创建一个包含以下变量的 .env 文件：

EMBEDDING_URL=  # 嵌入服务的 URL
OLLAMA_URL=    # Ollama 服务器的 URL
EMBEDDING_MODEL=nomic-embed-text  # 用于生成嵌入的模型

# PostgreSQL 配置
POSTGRES_DB=your_database_name
POSTGRES_USER=your_username
POSTGRES_PASSWORD=your_password
POSTGRES_HOST=localhost
POSTGRES_PORT=5432

与 Claude Desktop 一起使用

将其添加到您的 Claude Desktop 配置文件 (claude_desktop_config.json)：

{
  "mcpServers": {
    "parquet-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/home/${USER}/workspace/parquet_mcp_server/src/parquet_mcp_server",
        "run",
        "main.py"
      ]
    }
  }
}

可用工具

该服务器提供五个主要工具：

1. 嵌入 Parquet: 将嵌入添加到 Parquet 文件中的特定列

   • 必需参数：
     • input_path: 输入 Parquet 文件的路径
     • output_path: 保存输出的路径
     • column_name: 包含要嵌入的文本的列
     • embedding_column: 新嵌入列的名称
     • batch_size: 每个批次中要处理的文本数量（为了更好的性能）

2. Parquet 信息: 获取有关 Parquet 文件的详细信息

   • 必需参数：
     • file_path: 要分析的 Parquet 文件的路径

3. 转换为 DuckDB: 将 Parquet 文件转换为 DuckDB 数据库

   • 必需参数：
     • parquet_path: 输入 Parquet 文件的路径
   • 可选参数：
     • output_dir: 保存 DuckDB 数据库的目录（默认为与输入文件相同的目录）

4. 转换为 PostgreSQL: 将 Parquet 文件转换为支持 pgvector 的 PostgreSQL 表

   • 必需参数：
     • parquet_path: 输入 Parquet 文件的路径
     • table_name: 要创建或追加到的 PostgreSQL 表的名称

5. 处理 Markdown: 将 markdown 文件转换为带有元数据的结构化块

   • 必需参数：
     • file_path: 要处理的 markdown 文件的路径
     • output_path: 保存输出 parquet 文件的路径
   • 特点：
     • 保留文档结构和链接
     • 提取节标题和元数据
     • 针对大型文件进行内存优化
     • 可配置的块大小和重叠

示例提示

以下是一些您可以与代理一起使用的示例提示：

用于嵌入：

"请嵌入 parquet 文件 '/path/to/input.parquet' 中的 'text' 列，并将输出保存到 '/path/to/output.parquet'。使用 'embeddings' 作为最终列名，批处理大小为 2"

用于 Parquet 信息：

"请给我一些关于 parquet 文件 '/path/to/input.parquet' 的信息"

用于 DuckDB 转换：

"请将 parquet 文件 '/path/to/input.parquet' 转换为 DuckDB 格式，并将其保存在 '/path/to/output/directory' 中"

用于 PostgreSQL 转换：

"请将 parquet 文件 '/path/to/input.parquet' 转换为名为 'my_table' 的 PostgreSQL 表"

用于 Markdown 处理：

"请处理 markdown 文件 '/path/to/input.md' 并将块保存到 '/path/to/output.parquet'"

测试 MCP 服务器

该项目在 src/tests 目录中包含一个全面的测试套件。您可以使用以下命令运行所有测试：

python src/tests/run_tests.py

或者运行单个测试：

# 测试嵌入功能
python src/tests/test_embedding.py

# 测试 parquet 信息工具
python src/tests/test_parquet_info.py

# 测试 DuckDB 转换
python src/tests/test_duckdb_conversion.py

# 测试 PostgreSQL 转换
python src/tests/test_postgres_conversion.py

# 测试 Markdown 处理
python src/tests/test_markdown_processing.py

您也可以直接使用客户端测试服务器：

from parquet_mcp_server.client import (
    convert_to_duckdb, 
    embed_parquet, 
    get_parquet_info, 
    convert_to_postgres,
    process_markdown_file  # 新的 markdown 处理函数
)

# 测试 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"
)

故障排除

1. 如果您收到 SSL 验证错误，请确保您的 .env 文件中的 SSL 设置正确
2. 如果未生成嵌入，请检查：
   • Ollama 服务器正在运行且可访问
   • 指定的模型在您的 Ollama 服务器上可用
   • 文本列存在于您的输入 Parquet 文件中
3. 如果 DuckDB 转换失败，请检查：
   • 输入 Parquet 文件存在且可读
   • 您在输出目录中具有写入权限
   • Parquet 文件未损坏
4. 如果 PostgreSQL 转换失败，请检查：
   • 您的 .env 文件中的 PostgreSQL 连接设置正确
   • PostgreSQL 服务器正在运行且可访问
   • 您具有创建/修改表的必要权限
   • pgvector 扩展已安装在您的数据库中

API 响应格式

嵌入以以下格式返回：

{
    "object": "list",
    "data": [{
        "object": "embedding",
        "embedding": [0.123, 0.456, ...],
        "index": 0
    }],
    "model": "llama2",
    "usage": {
        "prompt_tokens": 4,
        "total_tokens": 4
    }
}

每个嵌入向量都作为 NumPy 数组存储在 Parquet 文件中的指定嵌入列中。

DuckDB 转换工具返回一条成功消息，其中包含已创建的数据库文件的路径；如果转换失败，则返回一条错误消息。

PostgreSQL 转换工具返回一条成功消息，指示是创建了新表还是将数据追加到了现有表。

markdown 分块工具将 markdown 文件处理成块，并将它们保存为具有以下列的 Parquet 文件：

• text: 每个块的文本内容
• metadata: 关于块的附加元数据（例如，标题、节信息）

该工具返回一条成功消息，其中包含已创建的 Parquet 文件的路径；如果处理失败，则返回一条错误消息。