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()
);