# Deep Research Toolkit（traceable-research-mcp）

可追溯的學術文獻研究 **MCP server**：用免費 API（OpenAlex、Europe PMC、
Crossref、Unpaywall）搜尋、去重、驗證 DOI、索引證據，產生**每個主張都連回
證據 ID** 的繁中／英文報告。伺服器本身**不需要任何 LLM 金鑰**，也**不規避
付費牆或存取控制**。

本專案是 [CYC2002tommy/Deep-Research-Agent](https://github.com/CYC2002tommy/Deep-Research-Agent)
的**獨立 MIT 授權改作**，原始版權與授權保留於 [`NOTICE`](NOTICE) 與 [`LICENSE`](LICENSE)。

## 功能

- 搜尋 **OpenAlex** 與 **Europe PMC**，用 **Crossref** 驗證 DOI，
  用 **Unpaywall** 尋找合法開放全文。
- 以透明、機器可讀的規則去重與篩選，保留每筆的納入／排除原因。
- 區分三種證據層級：`full_text`、`abstract_only`、`metadata_only`。
- 驗證每個實證主張都連到證據 ID，再匯出 Markdown、APA 7th DOCX、
  CSV 證據矩陣與 JSON。
- 所有資料只存在專案的 `.deep-research/`，不收集任何遙測。

## 需求

- **uv**（會自動準備 Python 3.11+）
  ```powershell
  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  ```
- **一個聯絡 email**（`UNPAYWALL_EMAIL`）：給 OpenAlex 免費 polite pool、
  Crossref、Unpaywall 使用。**免費使用不需要** `OPENALEX_API_KEY`
  （那是 OpenAlex Premium 付費功能）。

## 安裝

**先開啟 PowerShell**，再執行下列其中一種。因為用了 `--scope user`（全機生效），
這個安裝指令**在哪個資料夾執行都可以**。

> 之後**做研究**時，報告會產生在你**啟動 Claude Code 的那個資料夾**，
> 所以要在想放結果的資料夾開啟 Claude Code — 詳見 [操作說明.md](操作說明.md) 第 4 節。

### Claude Code（推薦，一次設定全機通用）
```powershell
claude mcp add deep-research --scope user -e UNPAYWALL_EMAIL="你的email" -- uvx traceable-research-mcp serve
```

### Claude Code 內建市集（連 skill 一起裝）
```
/plugin marketplace add jush-website/traceable-research-mcp
/plugin install deep-research-toolkit
```

### Codex

先安裝 Codex（`npm install -g @openai/codex`，需 Node.js 並登入 OpenAI），
然後一行加入（跟 Claude 幾乎一樣，旗標是 `--env`）：

```powershell
codex mcp add deep-research --env UNPAYWALL_EMAIL="你的email" -- uvx traceable-research-mcp serve
```

完整步驟見 [操作說明.md](操作說明.md) 第 3B 節。

### 免安裝直接跑 / 確認環境
```powershell
uvx traceable-research-mcp doctor
uvx traceable-research-mcp serve
```

詳細操作見 [操作說明.md](操作說明.md)，完整說明見 [說明書.md](說明書.md)。

## 使用

1. **切到你要放這份研究的資料夾，啟動 Claude Code**（報告會落在這個資料夾）：
   ```powershell
   cd D:\我的研究\都市樹木
   claude
   ```
2. **直接用中文講需求**，例如：
   > 用 deep-research 幫我針對「都市行道樹的抗旱機制」做一份可追溯的文獻回顧，繁體中文，standard 模式。
3. **AI 會照流程走，每一步都要你參與**：
   - 建立**草稿**計畫（此時**不會連網**）
   - 把計畫給你看 → **你確認後**才開始搜尋
   - 搜尋 → 去重篩選 → 驗證 DOI → 抓合法開放全文 → 索引證據
   - 產生報告草稿，**每個主張都連到證據 ID**，並驗證
   - 匯出四種格式
4. **產出**在該資料夾的 `.deep-research\reports\`：`.md`、`.docx`（APA 7th）、
   `.csv`（證據矩陣）、`.json`。

> 想加**自己的 PDF**：計畫還是草稿時，跟 AI 說「把這個 PDF 加進來」並給檔案路徑。
>
> `quick` / `standard` / `deep` 三種規模上限不同（摘要 30/100/250、全文 5/20/40）。

## 開發

```powershell
uv sync --extra dev
uv run pytest -m "not online" -q
uv run ruff check .
uv run mypy src
```

## 授權

MIT。見 [`LICENSE`](LICENSE) 與 [`NOTICE`](NOTICE)。

---

# Deep Research Toolkit (English)

A locally installed **MCP server** that runs **traceable** scholarly literature
reviews over free APIs (OpenAlex, Europe PMC, Crossref, Unpaywall) and
exports bilingual reports where **every empirical claim links to evidence IDs**.
The server needs **no LLM key** and never bypasses paywalls or access controls.

This is an **independent MIT-licensed adaptation** of
[CYC2002tommy/Deep-Research-Agent](https://github.com/CYC2002tommy/Deep-Research-Agent);
the original copyright and MIT license are retained in [`NOTICE`](NOTICE) and
[`LICENSE`](LICENSE).

## What it does

- Searches **OpenAlex** and **Europe PMC**, verifies DOIs through
  **Crossref**, resolves legal open access through **Unpaywall**.
- Deduplicates and screens with transparent, machine-readable rules.
- Indexes evidence at three levels: `full_text`, `abstract_only`, `metadata_only`.
- Validates claim-to-evidence links, then exports Markdown, APA 7th DOCX,
  a CSV evidence matrix, and JSON.
- Stores all data under `.deep-research/`; collects no telemetry.

## Requirements

- **uv** (auto-provisions Python 3.11+).
- `UNPAYWALL_EMAIL` (required) — contact email for OpenAlex's free polite pool,
  Crossref, and Unpaywall. `OPENALEX_API_KEY` is optional (paid Premium only).

## Install

```powershell
# Claude Code (recommended)
claude mcp add deep-research --scope user -e UNPAYWALL_EMAIL="you@example.com" -- uvx traceable-research-mcp serve

# Or run directly
uvx traceable-research-mcp serve
```

Claude Code built-in marketplace:
```
/plugin marketplace add jush-website/traceable-research-mcp
/plugin install deep-research-toolkit
```

Codex — install Codex first (`npm install -g @openai/codex`), then one line
(same as Claude, the flag is `--env`):
```powershell
codex mcp add deep-research --env UNPAYWALL_EMAIL="you@example.com" -- uvx traceable-research-mcp serve
```

## Usage

1. `cd` into the folder for this research, then start Claude Code (reports land there):
   ```powershell
   cd D:\research\urban-trees
   claude
   ```
2. Ask in natural language, e.g. *"Use deep-research to run a traceable literature
   review on drought resilience of urban street trees, in English, standard profile."*
3. The agent drafts a plan (no network yet) → **you approve** → search → screen →
   verify DOIs → fetch legal open access → index evidence → draft a report with
   claim→evidence links → export.
4. Outputs land in `.deep-research/reports/` in that folder: `.md`, `.docx`
   (APA 7th), `.csv` (evidence matrix), `.json`.

Add your own PDF while the plan is still a draft: tell the agent to add it and give the path.

## License

MIT. See [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE).