Deep Research Toolkit（traceable-research-mcp）

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

本專案是 CYC2002tommy/Deep-Research-Agent 的獨立 MIT 授權改作，原始版權與授權保留於 NOTICE 與 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 -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 第 4 節。

Claude Code（推薦，一次設定全機通用）

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）：

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

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

免安裝直接跑 / 確認環境

uvx traceable-research-mcp doctor
uvx traceable-research-mcp serve

詳細操作見 操作說明.md，完整說明見 說明書.md。

使用

1. 切到你要放這份研究的資料夾，啟動 Claude Code（報告會落在這個資料夾）：

   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）。

開發

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

授權

MIT。見 LICENSE 與 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; the original copyright and MIT license are retained in NOTICE and 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

# 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):

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):

   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 and NOTICE.