parquet_mcp_server

parquet_mcp_server

功能强大的 MCP（模型控制协议）服务，提供用于执行网络搜索和查找相似内容的工具。此服务专为与 Claude Desktop 配合使用而设计，提供两项主要功能：

1. 网络搜索：执行网络搜索并抓取结果
2. 相似度搜索：从之前的搜索中提取相关信息

此服务尤其适用于：

• 需要网络搜索功能的应用
• 需要根据搜索查询查找相似内容的项目

安装

通过 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=http://sample-url.com/api/embed  # URL for the embedding service
OLLAMA_URL=http://sample-url.com/  # URL for Ollama server
EMBEDDING_MODEL=sample-model  # Model to use for generating embeddings
SEARCHAPI_API_KEY=your_searchapi_api_key
FIRECRAWL_API_KEY=your_firecrawl_api_key
VOYAGE_API_KEY=your_voyage_api_key
AZURE_OPENAI_ENDPOINT=http://sample-url.com/azure_openai
AZURE_OPENAI_API_KEY=your_azure_openai_api_key

在 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. 搜索网络：执行网络搜索并抓取结果

   • 必需参数：
     • queries：搜索查询列表
   • 可选参数：
     • page_number：搜索结果的页码（默认为 1）

2. 从搜索中提取信息：从之前的搜索中提取相关信息

   • 必需参数：
     • queries：要合并的搜索查询列表

示例提示词

以下是可与 Agent 搭配使用的一些示例提示词：

用于网络搜索：

"Please perform a web search for 'macbook' and 'laptop' and scrape the results from page 1"

用于从搜索中提取信息：

"Please extract relevant information from the previous searches for 'macbook'"

测试 MCP 服务

项目在 src/tests 目录中包含一套完整的测试。你可以使用以下命令运行所有测试：

python src/tests/run_tests.py

也可以运行单项测试：

# Test Web Search
python src/tests/test_search_web.py

# Test Extract Info from Search
python src/tests/test_extract_info_from_search.py

你还可以直接使用客户端测试此服务：

from parquet_mcp_server.client import (
    perform_search_and_scrape,  # New web search function
    find_similar_chunks  # New extract info function
)

# Perform a web search
perform_search_and_scrape(["macbook", "laptop"], page_number=1)

# Extract information from the search results
find_similar_chunks(["macbook"])

故障排除

1. 如果出现 SSL 验证错误，请确保 .env 文件中的 SSL 设置正确
2. 如果未生成嵌入向量，请检查：
   • Ollama 服务是否正在运行且可访问
   • 指定的模型是否在 Ollama 服务上可用
   • 输入 Parquet 文件中是否存在文本列
3. 如果 DuckDB 转换失败，请检查：
   • 输入 Parquet 文件是否存在且可读取
   • 你是否拥有输出目录的写入权限
   • Parquet 文件是否损坏
4. 如果 PostgreSQL 转换失败，请检查：
   • .env 文件中的 PostgreSQL 连接设置是否正确
   • PostgreSQL 服务是否正在运行且可访问
   • 你是否拥有创建或修改表所需的权限
   • 数据库中是否安装了 pgvector 扩展

用于向量相似度搜索的 PostgreSQL 函数

要在 PostgreSQL 中执行向量相似度搜索，可以使用以下函数：

-- Create the function for vector similarity search
CREATE OR REPLACE FUNCTION match_web_search(
  query_embedding vector(1024),  -- Adjusted vector size
  match_threshold float,
  match_count int  -- User-defined limit for number of results
)
RETURNS TABLE (
  id bigint,
  metadata jsonb,
  text TEXT,  -- Added text column to the result
  date TIMESTAMP,  -- Using the date column instead of created_at
  similarity float
)
LANGUAGE plpgsql
AS $$
BEGIN
  RETURN QUERY
  SELECT
    web_search.id,
    web_search.metadata,
    web_search.text,  -- Returning the full text of the chunk
    web_search.date,  -- Returning the date timestamp
    1 - (web_search.embedding <=> query_embedding) as similarity
  FROM web_search
  WHERE 1 - (web_search.embedding <=> query_embedding) > match_threshold
  ORDER BY web_search.date DESC,  -- Sort by date in descending order (newest first)
           web_search.embedding <=> query_embedding  -- Sort by similarity
  LIMIT match_count;  -- Limit the results to the match_count specified by the user
END;
$$;

此函数可用于对存储在 PostgreSQL 数据库中的向量嵌入执行相似度搜索，返回符合指定相似度阈值的结果，并根据用户输入限制结果数量。结果按日期和相似度排序。

创建 Postgres 表

CREATE TABLE web_search (
    id SERIAL PRIMARY KEY,
    text TEXT,
    metadata JSONB,
    embedding VECTOR(1024),

    -- This will be auto-updated
    date TIMESTAMP DEFAULT NOW()
);