parquet_mcp_server

一个功能强大的MCP（模型控制协议）服务器，提供用于执行网络搜索和查找相似内容的工具。此服务器专为Claude Desktop设计，并具有以下主要功能：

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

此服务器特别适用于：

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

安装指南

通过Smithery安装

自动使用Smithery安装Parquet MCP Server for 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  # 向量嵌入服务地址
VECTOR_DB_HOST=host.docker.internal  # PostgreSQL向量数据库的主机名或IP地址
VECTOR_DB_PORT=5432  # PostgreSQL端口，默认为5432
VECTOR_DB_NAME=vector_db  # 数据库名称
VECTOR_DB_USER=postgres  # 数据库用户名
VECTOR_DB_PASSWORD=postgres  # 数据库密码

使用说明

安装PostgreSQL和pgVector扩展

1. 在PostgreSQL中创建一个新数据库并启用pgVector扩展：

CREATE EXTENSION vector;

2. 创建用于存储搜索结果的表：

CREATE TABLE web_search (
    id SERIAL PRIMARY KEY,
    text TEXT,  # 存储完整的网页内容或文本片段
    metadata JSONB,  # 包含URL、标题等元数据
    embedding VECTOR(1024),  # 文本对应的向量嵌入，维度为1024
    created_at TIMESTAMP DEFAULT NOW()  # 记录创建时间
);

测试指南

初始化数据库

使用以下命令初始化PostgreSQL数据库并插入示例数据：

psql -h host.docker.internal -U postgres -d vector_db -f init.sql

搜索测试

向服务器发送一个包含嵌入向量的搜索请求，例如：

POST /api/search HTTP/1.1
Content-Type: application/json

{
    "embedding": [0.1, 0.2, ..., 0.3],  # 长度为1024的向量
    "match_threshold": 0.7,  # 相似性阈值，默认0.7
    "match_count": 5  # 最大返回结果数，默认5
}

PostgreSQL相似性搜索函数

为了在PostgreSQL中执行基于向量的相似性搜索，请使用以下SQL函数：

-- 创建用于相似性搜索的函数
CREATE OR REPLACE FUNCTION match_web_search(
  query_embedding vector(1024),  # 查询向量，长度必须为1024
  match_threshold float,  # 相似性阈值
  match_count int  # 最大返回结果数，默认5
)
RETURNS TABLE (
  id bigint,
  metadata jsonb,
  text TEXT,  # 返回完整的文本内容
  created_at TIMESTAMP,  # 返回创建时间戳
  similarity float
)
LANGUAGE plpgsql
AS $$
BEGIN
  RETURN QUERY
  SELECT
    web_search.id,
    web_search.metadata,
    web_search.text,
    web_search.created_at,
    1 - (web_search.embedding <=> query_embedding) as similarity
  FROM web_search
  WHERE 1 - (web_search.embedding <=> query_embedding) > match_threshold
  ORDER BY web_search.created_at DESC,  # 按时间排序，最新结果优先
           web_search.embedding <=> query_embedding  # 按相似性排序
  LIMIT match_count;  # 限制返回结果数量
END;
$$;

这个函数允许在PostgreSQL中执行基于向量的相似性搜索，根据指定的阈值和结果数限制返回符合条件的结果。结果按时间戳降序排列，再按相似性排序。

后端代码示例

以下是后端服务的一个简单实现示例：

from fastapi import FastAPI, HTTPException
import requests
import json
from typing import List, Optional

app = FastAPI()

class SearchResults(BaseModel):
    id: int
    metadata: dict
    text: str
    created_at: datetime
    similarity: float

@app.post("/api/search", response_model=List[SearchResults])
async def search(web_search: WebSearch) -> List[SearchResults]:
    try:
        # 执行相似性搜索查询
        response = requests.post(
            "http://localhost:8000/api/vector/search",
            json={
                "vector": web_search.embedding,
                "threshold": 0.7,
                "count": 5
            }
        )
        
        if response.status_code != 200:
            raise HTTPException(status_code=500, detail="搜索失败")
            
        return response.json()
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

其他注意事项

• 确保PostgreSQL版本为13或更高，以支持向量数据类型。
• pgVector扩展必须正确安装，并且数据库已启用该扩展。
• 网络搜索功能依赖于第三方爬虫工具（如requests和beautifulsoup4），请确保这些库已安装并配置正确。
• 在生产环境中使用时，请根据实际需求调整相似性阈值和结果返回数量。