# research-mcp-lab

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

## 特徴

- **MCP サーバ**（[Model Context Protocol](https://modelcontextprotocol.io)）— 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`）は凍結スナップショット＝再現可能な基準データを見る。

## セットアップ

```bash
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）

```bash
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 ルーティング）
```