research-mcp-lab

Hacker News × arXiv を横断する research intelligence エージェントの MCP サーバ。 自然文の問いを SQL / 全文検索に変換し、根拠（実行した SQL・検索ヒット）つきで答える。

特徴

• MCP サーバ（Model Context Protocol）— Claude Code 等の AI クライアントから「道具」として呼べる。
• DuckDB + FTS — HN/arXiv のメタデータを列指向 DB に格納し、BM25 で全文検索。
• 根拠を返す — どのツールを・どんな SQL / 検索で答えたかを併記する。
• ライブ取得（スクレイピング） — refresh_data で最新の HN×arXiv を取得し、別ストア（data/live/）に保存。凍結スナップショット（data/snapshot/）は再現性のため不変。

ツール

ツール	役割
get_schema(live=False)	テーブル/列の意味・FTS 対象を返す（AI が SQL/検索の前に読む）
run_sql(sql, live=False)	読み取り専用 SQL を実行し表形式で返す（＝根拠 SQL）
search_text(query, target="papers", live=False)	BM25 全文検索（papers の abstract / comments の本文）
refresh_data(top_n=120)	HN×arXiv を取得して live ストアを更新（スクレイピング）

live=True を付けると refresh_data 後の最新データに対して問い合わせる。 既定（live=False）は凍結スナップショット＝再現可能な基準データを見る。

セットアップ

uv sync --dev

# 凍結スナップショット(data/snapshot/*.csv)から DuckDB を構築
PYTHONPATH=src uv run python -c "from research_mcp.data import build_db; build_db()"

uv run pytest

# MCP サーバを stdio 起動
PYTHONPATH=src uv run python -m research_mcp

MCP クライアントへの登録（例: Claude Code）

claude mcp add research-intelligence -s user \
  -e PYTHONPATH="$PWD/src" \
  -- uv run --directory "$PWD" python -m research_mcp

データ

• data/snapshot/*.csv — HN/arXiv の凍結スナップショット（公開データ）。eval / デモの再現性の基準。
• data/live/ — refresh_data が再生成（.gitignore 済み）。

データ源（API キー不要）

• Hacker News API（Firebase）— https://hacker-news.firebaseio.com/v0/
• arXiv API（Atom）— http://export.arxiv.org/api/query

構成

src/research_mcp/
  sources.py   # HN/arXiv 取得・arxiv_id 抽出・サニタイズ・build_snapshot
  data.py      # スナップショット→DuckDB、メタデータ層、FTS、接続
  server.py    # MCP ツール(get_schema / run_sql / search_text / refresh_data)
  __main__.py  # `python -m research_mcp` で stdio 起動
tests/         # pytest（取得の純関数・MCP ツール・live ルーティング）