parquet_mcp_server

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

1. 文本嵌入生成：使用Ollama模型将Parquet文件中的文本列转换为向量嵌入
2. Parquet文件分析：提取有关Parquet文件的详细信息，包括模式、行数和文件大小
3. DuckDB集成：将Parquet文件转换为DuckDB数据库，以便进行高效的查询和分析
4. PostgreSQL集成：将Parquet文件转换为支持pgvector的PostgreSQL表，以实现向量相似性搜索
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  # On Windows
source .venv/bin/activate  # On macOS/Linux

安装包

uv pip install -e .

环境

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

EMBEDDING_URL=  # URL for the embedding service
OLLAMA_URL=    # URL for Ollama server
EMBEDDING_MODEL=nomic-embed-text  # Model to use for generating embeddings

# PostgreSQL Configuration
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 文件的路径
   • 特性：
     • 保留文档结构和链接
     • 提取节标题和元数据
     • 针对大文件进行内存优化
     • 可配置的块大小和重叠

示例提示

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

对于嵌入：

"Please embed the column 'text' in the parquet file '/path/to/input.parquet' and save the output to '/path/to/output.parquet'. Use 'embeddings' as the final column name and a batch size of 2"

对于 Parquet 信息：

"Please give me some information about the parquet file '/path/to/input.parquet'"

对于 DuckDB 转换：

"Please convert the parquet file '/path/to/input.parquet' to DuckDB format and save it in '/path/to/output/directory'"

对于 PostgreSQL 转换：

"Please convert the parquet file '/path/to/input.parquet' to a PostgreSQL table named 'my_table'"

对于 Markdown 处理：

"Please process the markdown file '/path/to/input.md' and save the chunks to '/path/to/output.parquet'"

测试 MCP 服务器

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

python src/tests/run_tests.py

或者单独运行单个测试：

# Test embedding functionality
python src/tests/test_embedding.py

# Test parquet information tool
python src/tests/test_parquet_info.py

# Test DuckDB conversion
python src/tests/test_duckdb_conversion.py

# Test PostgreSQL conversion
python src/tests/test_postgres_conversion.py

# Test Markdown processing
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  # New markdown processing function
)

# Test DuckDB conversion
result = convert_to_duckdb(
    parquet_path="input.parquet",
    output_dir="db_output"
)

# Test embedding
result = embed_parquet(
    input_path="input.parquet",
    output_path="output.parquet",
    column_name="text",
    embedding_column="embeddings",
    batch_size=2
)

# Test parquet information
result = get_parquet_info("input.parquet")

# Test PostgreSQL conversion
result = convert_to_postgres(
    parquet_path="input.parquet",
    table_name="my_table"
)

# Test markdown processing
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文件路径的成功消息；如果处理失败，则返回错误消息。