parquet_mcp_server

一个强大的MCP（模型控制协议）服务器，提供进行网络搜索和查找相似内容的工具。此服务器旨在与Claude Desktop配合使用，并提供了两大主要功能：

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

此服务器特别适用于：

• 需要网络搜索能力的应用程序
• 基于搜索查询需要找到相似内容的项目

安装

通过Smithery安装

要通过Smithery自动安装Parquet MCP Server用于Claude Desktop，请运行以下命令：

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=http://sample-url.com/api/embed  # 嵌入服务的URL
OLLAMA_URL=http://sample-url.com/  # Ollama服务器的URL
EMBEDDING_MODEL=sample-model  # 用于生成嵌入的模型
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：要合并的搜索查询列表

示例提示

这里有一些示例提示，您可以与代理一起使用：

对于网络搜索：

"请对'macbook'和'laptop'进行网络搜索并抓取第一页的结果"

对于从搜索中提取信息：

"请从之前关于'macbook'的搜索中提取相关信息"

测试MCP服务器

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

python src/tests/run_tests.py

或者单独运行测试：

# 测试网络搜索
python src/tests/test_search_web.py

# 测试从搜索中提取信息
python src/tests/test_extract_info_from_search.py

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

from parquet_mcp_server.client import (
    perform_search_and_scrape,  # 新的网络搜索函数
    find_similar_chunks  # 新的提取信息函数
)

# 执行网络搜索
perform_search_and_scrape(["macbook", "laptop"], page_number=1)

# 从搜索结果中提取信息
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 OR REPLACE FUNCTION match_web_search(
  query_embedding vector(1024),  -- 调整向量大小
  match_threshold float,
  match_count int  -- 用户定义的结果数量限制
)
RETURNS TABLE (
  id bigint,
  metadata jsonb,
  text TEXT,  -- 添加到结果中的文本列
  date TIMESTAMP,  -- 使用日期列而不是created_at
  similarity float
)
LANGUAGE plpgsql
AS $$
BEGIN
  RETURN QUERY
  SELECT
    web_search.id,
    web_search.metadata,
    web_search.text,  -- 返回块的全文
    web_search.date,  -- 返回日期时间戳
    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,  -- 按日期降序排序（最新优先）
           web_search.embedding <=> query_embedding  -- 按相似度排序
  LIMIT match_count;  -- 根据用户指定的数量限制结果
END;
$$;

此函数允许您在PostgreSQL数据库中存储的向量嵌入上执行相似性搜索，返回满足指定相似性阈值的结果，并根据用户输入限制结果数量。结果按日期和相似性排序。

创建Postgres表

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

    -- 这将被自动更新
    date TIMESTAMP DEFAULT NOW()
);