# paper-search MCP

日本語・英語の学術論文を検索し、本文の取得可能性を判定し、公開 PDF をローカル収集する MCP サーバー。Claude Code などの LLM エージェントから利用することを想定しています。

- **英語論文**: arXiv(API キー不要)
- **日本語論文**: CiNii Research(API キー不要。appid は任意)
- **本文解決**: arXiv PDF / J-STAGE 公開論文 / 検索結果に含まれる既知 URL(機関リポジトリ等)

データソースごとの API 差異はサーバー内部で吸収し、LLM には統一された 4 つの Tool だけを公開します。

## 提供 Tool

| Tool | 役割 |
|---|---|
| `search_papers` | 日英複数ソースの並列検索。正規化・重複除去・ランキング済みの候補を返す |
| `inspect_papers` | 複数論文の詳細と本文取得可能性(available / restricted 等)を一括調査 |
| `collect_papers` | 公開 PDF を一括ダウンロードしローカル保存(SHA-256 記録、重複防止) |
| `get_collected_papers` | 収集済みファイルのローカルパス等を返す |

すべてバッチ入力(`paper_ids[]`)で、一部の失敗があっても成功分は返します(部分成功)。

## セットアップ

要件: [uv](https://docs.astral.sh/uv/)(Python 3.12+ は uv が自動管理)

```bash
git clone <this-repo>
cd mcp-paper-search
uv sync
```

### Claude Code への登録

プロジェクトルート(または利用したいワークスペース)の `.mcp.json` に追加:

```json
{
  "mcpServers": {
    "paper-search": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-paper-search", "paper-search-mcp"],
      "env": {
        "PAPER_SEARCH_DATA_DIR": "/path/to/mcp-paper-search/data"
      }
    }
  }
}
```

### 環境変数

| 変数 | 必須 | 説明 |
|---|---|---|
| `PAPER_SEARCH_DATA_DIR` | 任意 | PDF・収集記録の保存先(デフォルト `./data`) |
| `CINII_APP_ID` | 任意 | CiNii Research の appid。なしでも動作するが、継続利用には NII への[アプリケーション登録](https://support.nii.ac.jp/ja/cinii/api/developer)を推奨 |

## 使い方の例

Claude Code に次のように依頼すると、search → inspect → collect のワークフローが実行されます。

```text
組込みソフトウェア開発における AI エージェント活用について、
日本語と英語の論文を探して、関連度の高いものを PDF で収集して。
```

収集した PDF は `data/papers/{年}/{paper-id}.pdf` に保存されます。

## 開発

```bash
uv run pytest                  # offline テスト(実 API は叩かない)
uv run pytest -m live          # 実 API との整合検証(arXiv / CiNii)
uv run ruff check src tests   # lint
uv run mypy                    # 型チェック(strict)
```

設計ドキュメントは [docs/plan.md](docs/plan.md)、開発時の規約は [CLAUDE.md](CLAUDE.md) を参照してください。

### 実装状況

- ✅ Phase 1–7: ドメインモデル / arXiv・CiNii 検索 / 検索統合(重複除去・ランキング)/ arXiv・J-STAGE 本文解決 / PDF 収集 / MCP サーバー
- ⬜ Phase 8: 機関リポジトリ・DOI Resolver
- ⬜ Phase 9: SQLite 永続化(現状は検索結果がプロセス内メモリのため、**サーバー再起動後は再検索が必要**)
- ⬜ Skills(paper-discovery / literature-survey / paper-collection)

## 制約・ポリシー

- 公開・合法的に取得可能な本文のみ収集します(認証突破・Shadow Library 非対応)
- 各 API にはホスト単位の rate limit(arXiv 3 秒 / CiNii 1 秒 / J-STAGE 2 秒)を設けています
- ダウンロード対象 URL はサーバーが解決した候補のみに限定し、SSRF 検証を行います