parquet_mcp_server

parquet_mcp_server

Web 検索と類似コンテンツの検索を行うツールを提供する、強力な MCP（Model Control Protocol）サーバーです。このサーバーは Claude Desktop と連携するよう設計されており、主に次の 2 つの機能を提供します。

1. Web 検索：Web 検索を実行し、結果をスクレイピングします
2. 類似検索：過去の検索から関連情報を抽出します

このサーバーは、特に次の用途に役立ちます。

• Web 検索機能を必要とするアプリケーション
• 検索クエリに基づいて類似コンテンツを見つける必要があるプロジェクト

インストール

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  # 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"
      ]
    }
  }
}

利用可能なツール

このサーバーは主に次の 2 つのツールを提供します。

1. Web 検索：Web 検索を実行し、結果をスクレイピングします

   • 必須パラメーター：
     • queries：検索クエリのリスト
   • オプションのパラメーター：
     • page_number：検索結果のページ番号（デフォルトは 1）

2. 検索結果から情報を抽出：過去の検索から関連情報を抽出します

   • 必須パラメーター：
     • queries：統合する検索クエリのリスト

プロンプトの例

エージェントで使用できるプロンプトの例を紹介します。

Web 検索の場合：

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