Copilot instructions

1# GitHub Copilot Instructions for PubMed Search MCP
2 
3This document provides guidance for AI assistants working with the PubMed Search MCP server.
4 
5---
6 
7## Repository Hook Notes
8 
9- `unicode-mojibake` blocks newly staged corrupted emoji/UTF-8 artifacts while allowing valid emoji; restore garbled text as UTF-8 before committing.
10 
11## ⚡ 開發環境規範 (CRITICAL)
12 
13### 套件管理：使用 UV (NOT pip)
14 
15本專案**必須**使用 [UV](https://github.com/astral-sh/uv) 管理所有 Python 依賴。
16**所有命令（包括測試、lint、type check）一律透過 `uv run` 執行**，確保使用正確的虛擬環境與依賴版本。
17 
18> 💡 **UV 非常高效**：UV 使用 Rust 實作，比 pip 快 10-100 倍。即使是 `uv run pytest`，UV 也會在毫秒級確認環境一致後直接執行，幾乎零開銷。
19 
20```bash
21# ❌ 禁止使用 (一律禁止直接呼叫，必須透過 uv run)
22pip install <package>
23python -m pytest
24pytest
25ruff check .
26mypy src/
27 
28# ✅ 正確使用
29uv add <package>           # 新增依賴
30uv add --dev <package>     # 新增開發依賴
31uv remove <package>        # 移除依賴
32uv sync                    # 同步依賴
33uv run pytest              # 透過 uv 執行測試（自動多核）
34uv run python script.py    # 透過 uv 執行 Python
35```
36 
37### 程式碼品質工具（全部透過 uv run 執行）
38 
39```bash
40uv run ruff check .        # Lint 檢查
41uv run ruff check . --fix  # Lint 自動修復
42uv run ruff format .       # 格式化
43uv run mypy src/ tests/    # 型別檢查（含 src 和 tests）
44uv run pytest              # ⩡ 多核平行測試（預設 -n auto --timeout=60）
45uv run pytest --cov        # 多核 + 覆蓋率
46```
47 
48> ⚠️ **永遠不要**直接呼叫 `pytest`、`ruff`、`mypy`，一律使用 `uv run` 前綴。
49 
50### 🔒 Pre-commit Hooks (自動品質守門)
51 
52本專案使用 [pre-commit](https://pre-commit.com/) 在每次 commit 時自動執行品質檢查。
53 
54```bash
55# 首次設定（uv sync 安裝依賴後）
56uv run pre-commit install                       # 安裝 pre-commit hook
57uv run pre-commit install --hook-type pre-push  # 安裝 pre-push hook
58 
59# 手動執行所有 hooks
60uv run pre-commit run --all-files
61 
62# 更新 hook 版本（建議每月一次）
63uv run pre-commit autoupdate
64```
65 
66**Commit 階段自動檢查：**
67- trailing-whitespace / end-of-file-fixer (自動修復)
68- check-yaml / check-toml / check-json / check-ast
69- check-added-large-files / check-merge-conflict / debug-statements / detect-private-key
70- check-byte-order-marker / fix-byte-order-marker (自動修復)
71- check-builtin-literals / check-case-conflict / check-docstring-first
72- check-executables-have-shebangs / check-shebang-scripts-are-executable
73- check-symlinks / destroyed-symlinks / check-vcs-permalinks
74- check-illegal-windows-names / mixed-line-ending (自動修復)
75- no-commit-to-branch (保護 main/master)
76- name-tests-test (強制 test_*.py 命名)
77- **ruff** lint (自動修復) + **ruff-format** (自動修復)
78- **bandit** 安全掃描 (medium+ severity, `pyproject.toml [tool.bandit]`)
79- **vulture** 死碼掃描 (`vulture_whitelist.py` 管理白名單)
80- **deptry** 依賴衛生 (`pyproject.toml [tool.deptry]`)
81- **semgrep** SAST 靜態安全分析 — **已移至 pre-push** (記憶體 300-500MB)
82- **mypy** type check — **已移至 pre-push** (記憶體 500MB-1GB)
83- **async-test-checker** async/sync 測試一致性 (`scripts/check_async_tests.py`)
84- **file-hygiene** 檔案衛生檢查 (`scripts/hooks/check_file_hygiene.py`)，只審查**新增**路徑；已在 HEAD 的檔案當初已被接受，再擋一次只會跟自動修復型 hook 互鎖
85- **commit-size-guard** 限制每次 commit ≤30 檔案 (`scripts/hooks/check_commit_size.py`)
86- **tool-count-sync** MCP 工具文檔同步 (`scripts/hooks/check_tool_sync.py`, 自動修復)
87- **skills-frontmatter** 驗證 `.claude/skills/*/SKILL.md` 的 YAML frontmatter (`scripts/hooks/check_skills_frontmatter.py`)
88- **evolution-cycle** 一致性驗證 (`scripts/hooks/check_evolution_cycle.py`)
89- **future-annotations** 強制 `from __future__ import annotations` (`scripts/hooks/check_future_annotations.py`, 自動修復)
90- **no-print-in-src** 禁止 src/ 使用 print() (`scripts/hooks/check_no_print.py`)
91- **ddd-layer-imports** DDD 層級依賴檢查 (`scripts/hooks/check_ddd_layers.py`)
92- **no-type-ignore-bare** 禁止裸 `# type: ignore` (`scripts/hooks/check_type_ignore.py`)
93- **docstring-tools** MCP 工具必須有文檔字串 (`scripts/hooks/check_docstring_tools.py`)
94- **no-env-inner-layers** 禁止內層 DDD 使用 os.environ (`scripts/hooks/check_env_config.py`)
95- **tenant-scoped-storage** presentation 層儲存路徑須經 `tenant_data_dir()` (`scripts/hooks/check_tenant_scoped_storage.py`)
96- **source-counts-guard** 確保每來源 API 回傳量顯示 (`scripts/hooks/check_source_counts.py`)
97- **todo-scanner** TODO/FIXME 掃描器 (警告, 不阻擋) (`scripts/hooks/check_todo_scanner.py`)
98- **instruction-drift** 工具 docstring 變更偵測 (警告, 不阻擋) (`scripts/hooks/check_instruction_drift.py`)
99 
100**Push 階段自動檢查：**
101- **mypy** type check (`uv run mypy src/`, 記憶體 500MB-1GB)
102- **semgrep** SAST 靜態安全分析 (`p/python` ruleset, 記憶體 300-500MB)
103- **pytest** 全套測試 (`-n auto --timeout=60 -m "not integration"`)，排除會打真實第三方 API 的 integration 測試；需要時手動跑 `uv run pytest -m integration`
104 
105```bash
106# 跳過特定 hook
107SKIP=mypy git commit -m "quick fix"
108# 跳過所有 hooks（慎用）
109git commit --no-verify -m "emergency fix"
110```
111 
112### 🔄 自演化循環 (Self-Evolution Cycle - IMPORTANT)
113 
114本專案的 Instruction、Skill、Hook 形成一個自我演化的閉迴系統：
115 
116```
117Instruction (copilot-instructions.md)
118    │ 定義規範、引導 AI 使用 Skills
119    ▼
120Skill (SKILL.md 檔案)
121    │ 確保建構完整、創建新 Hook
122    ▼
123Hook (.pre-commit-config.yaml + scripts/hooks/)
124    │ 自動執行檢查、自動修正
125    ▼
126evolution-cycle hook (check_evolution_cycle.py)
127    │ 驗證三者一致性、報告不同步處
128    ▼
129Feedback → 更新 Instruction & Skill → 循環完成
130```
131 
132**新增 Hook 的完整流程：**
1331. 創建 hook 腳本 → `scripts/hooks/<name>.py`
1342. 註冊到 `.pre-commit-config.yaml`
1353. 更新 `copilot-instructions.md` (Commit 階段自動檢查列表)
1364. 更新 `git-precommit SKILL.md` (架構圖 + Hook 設定檔案表)
1375. 更新 `CONTRIBUTING.md` (hooks 表格)
1386. 執行 `uv run python scripts/hooks/check_evolution_cycle.py` 驗證
139 
140> ⚠️ 如果只做了 1-2 而沒有 3-5，evolution-cycle hook 會在下次 commit 時報錯。
141 
142**套件版本自動演化：**
143```bash
144uv run pre-commit autoupdate    # 更新 ruff、pre-commit-hooks 等版本
145uv run pre-commit run --all-files  # 驗證更新後所有 hook 正常
146```
147 
148### ⏱️ 測試執行時間 (IMPORTANT - 請務必閱讀)
149 
150本專案**強制**使用 **pytest-xdist** 多核平行測試（透過 `addopts = "-n auto --timeout=60"` 全局強制）。
151 
152```bash
153# ✅ 所有測試命令自動帶 -n auto --timeout=60（不需手動加）
154uv run pytest                # 多核執行（~67 秒）
155uv run pytest tests/ -q      # 多核 + 簡潔輸出
156 
157# ✅ 導向檔案避免 terminal buffer 溢出
158uv run pytest tests/ -q --no-header 2&gt;&amp;1 &gt; scripts/_tmp/test_result.txt
159# 等待 ~70 秒後再讀取結果
160 
161# ✅ 多核 + 覆蓋率（pytest-cov 完全支援 xdist）
162uv run pytest --cov -q
163 
164# ⚠️ 僅在需要 benchmark 時停用 xdist
165uv run pytest tests/test_performance.py --benchmark-only -p no:xdist
166```
167 
168| 指標 | 數值 |
169|------|------|
170| 測試檔案數 | 60+ |
171| 測試案例數 | 2200+ |
172| 測試程式碼行數 | 30,000+ |
173| ⚡ 多核執行時間 (`-n auto`) | **~67 秒** |
174| 每個測試超時 | 60 秒 (`--timeout=60`) |
175| 建議 terminal timeout | **120,000+ ms** |
176 
177> 💡 **pytest-xdist** 使用多 process 平行化，每個 worker 為獨立 process，singleton 隔離無衝突。
178> ⚠️ `pytest-benchmark` 在 xdist 模式下自動停用（benchmark 需要單核確保精確度）。
179 
180### 🔄 Async/Sync 測試一致性檢查 (MANDATORY)
181 
182本專案使用 `asyncio_mode = "auto"`，所有 async 方法的測試必須正確使用 `await` 和 `AsyncMock`。
183**每次新增或修改測試時，必須執行** `scripts/check_async_tests.py` 確認無 async/sync 不一致。
184 
185```bash
186# ✅ 必須在 commit 前執行
187uv run python scripts/check_async_tests.py
188 
189# 詳細模式（查看每個問題的具體位置）
190uv run python scripts/check_async_tests.py --verbose
191 
192# 自動修復 missing await（僅修復可安全自動修復的問題）
193uv run python scripts/check_async_tests.py --fix
194```
195 
196#### 常見反模式與修正
197 
198```python
199# ❌ 錯誤：使用 Mock() mock async 方法
200mock_searcher = Mock()
201mock_searcher.search.return_value = []
202result = await searcher.search(...)  # TypeError: can't await Mock
203 
204# ✅ 正確：使用 AsyncMock()
205mock_searcher = AsyncMock()
206mock_searcher.search.return_value = []
207result = await searcher.search(...)  # 正常運作
208 
209# ❌ 錯誤：忘記 await async 方法
210result = client.search(query="test")  # 返回 coroutine，非結果
211 
212# ✅ 正確：加上 await
213result = await client.search(query="test")  # 返回實際結果
214 
215# ❌ 錯誤：sync def 測試呼叫 async 方法
216def test_something():
217    result = client.search(...)  # 永遠不會正確執行
218 
219# ✅ 正確：使用 async def
220async def test_something():
221    result = await client.search(...)
222```
223 
224#### 檢查清單（每次寫測試時）
225 
226- [ ] async 方法的 mock 是否使用 `AsyncMock()`？
227- [ ] 所有 async 方法呼叫是否加了 `await`？
228- [ ] 測試函數是否為 `async def`？（當測試呼叫 async 方法時）
229- [ ] `scripts/check_async_tests.py` 執行結果為 0 issues？
230 
231### 依賴管理檔案
232 
233- `pyproject.toml` - 主要依賴定義
234- `uv.lock` - 鎖定版本 (自動生成，勿手動編輯)
235 
236### 🧹 檔案衛生規範 (File Hygiene - MANDATORY)
237 
238AI Agent 在工作過程中**絕對禁止**在專案中留下臨時檔案。違反此規範等同程式碼品質問題。
239 
240#### 禁止事項
241 
242```
243# ❌ 禁止：將測試結果導向檔案
244uv run pytest > test_results.txt
245uv run pytest 2>&1 | Out-File result.txt
246 
247# ❌ 禁止：在 scripts/ 放一次性修復腳本
248scripts/auto_fix_something.py
249scripts/fix_async_tests_v3.py
250 
251# ❌ 禁止：在根目錄放任何臨時產出物
252failed_lines.txt, test_summary.txt, v3_result.txt
253```
254 
255#### 正確做法
256 
257```bash
258# ✅ 正確：直接在終端看測試結果
259uv run pytest --timeout=60
260 
261# ✅ 正確：若真需要臨時檔案，放在 scripts/_tmp/ (已被 .gitignore 排除)
262uv run pytest &gt; scripts/_tmp/result.txt
263 
264# ✅ 正確：修復腳本執行完畢後立即刪除
265Remove-Item scripts/_tmp/fix_script.py
266 
267# ✅ 正確：commit 前確認無臨時檔案
268git status --short | Where-Object { $_ -match '^\?\?' }
269```
270 
271#### 允許在根目錄的檔案（白名單）
272 
273| 類型 | 檔案 |
274|------|------|
275| 設定 | `pyproject.toml`, `Dockerfile`, `docker-compose*.yml`, `.gitignore`, `uv.lock` |
276| 狀態 | `.instruction_drift_fingerprint` |
277| 文檔 | `README.md`, `README.zh-TW.md`, `CHANGELOG.md`, `CONSTITUTION.md`, `ARCHITECTURE.md`, `ROADMAP.md`, `CONTRIBUTING.md`, `DEPLOYMENT.md`, `CITATION.cff`, `AGENTS.md`, `LICENSE` |
278| Entrypoints | `pubmed-search-mcp`, `pubmed-search-mcp-http`, `pubmed-browser-fetch-broker`, `run_copilot.py`, `run_server.py` |
279 
280> ⚠️ **任何不在白名單的檔案出現在根目錄都是錯誤。**
281 
282### 🚫 禁止重造輪子與過度設計 (No Reinventing the Wheel - MANDATORY)
283 
284AI Agent **必須持續檢查**是否存在以下反模式，並在每次新增或修改程式碼時主動排查：
285 
286#### 重造輪子 (Reinventing the Wheel)
287 
288```
289# ❌ 禁止：自己實作已有標準庫/第三方可完成的功能
290手寫 HTTP retry/backoff     → 用 tenacity 或 httpx 內建 retry
291手寫 JSON schema 驗證       → 用 pydantic
292手寫 rate limiter           → 用現有的 asyncio.Semaphore 或 aiolimiter
293手寫 URL 解析/編碼          → 用 urllib.parse / yarl
294手寫日期解析                → 用 dateutil.parser
295手寫 CSV/XML 解析器         → 用 csv / lxml / xml.etree
296自己包裝 logging 框架       → 直接用 logging 標準庫
297手寫 LRU cache              → 用 functools.lru_cache / cachetools
298```
299 
300#### 過度設計 (Over-Engineering)
301 
302```
303# ❌ 禁止：
304- 只有一個實作卻建立 Abstract Base Class + Interface + Factory
305- 為了「未來擴展」加入目前未使用的參數/類別/層
306- 包裝層只是直接轉發呼叫，沒有增加任何邏輯 (Thin Wrapper 無價值)
307- 為只用一次的功能建立獨立模組
308- 把 3 行能解決的問題寫成 30 行的 class hierarchy
309- 給 cfg/env 變數寫複雜的 getter/setter，直接讀取即可
310 
311# ✅ 正確做法：
312- YAGNI (You Ain't Gonna Need It) — 只實作當前需要的
313- 優先使用函數，不需要狀態就不要用 class
314- 先用最簡單的方案，有證據需要時才重構
315- 第三方庫已解決的問題，直接 uv add 而非手寫
316```
317 
318#### 檢查清單 (每次 code review 時)
319 
320- [ ] 這個功能有沒有現成的標準庫/第三方能做到？
321- [ ] 這個 class 是否可以用簡單的函數取代？
322- [ ] 這個抽象層是否真的有多個實作？還是只有一個？
323- [ ] 這段程式碼有沒有「只是轉發」的 wrapper？
324- [ ] 有沒有為「未來可能」而非「現在需要」而寫的程式碼？
325 
326---
327 
328## 🏗️ 專案架構 (DDD v0.2.0)
329 
330本專案採用 **Domain-Driven Design (DDD)** 分層架構：
331 
332```
333src/pubmed_search/
334├── domain/                 # 核心業務邏輯
335│   └── entities/           # 實體 (UnifiedArticle, TimelineEvent)
336├── application/            # 應用服務/用例
337│   ├── search/             # QueryAnalyzer, ResultAggregator
338│   ├── export/             # 引用匯出 (RIS, BibTeX...)
339│   ├── session/            # SessionManager
340│   └── timeline/           # TimelineBuilder, MilestoneDetector
341├── infrastructure/         # 外部系統整合
342│   ├── ncbi/               # Entrez, iCite, Citation Exporter
343│   ├── sources/            # Europe PMC, CORE, CrossRef...
344│   └── http/               # HTTP 客戶端
345├── presentation/           # 使用者介面
346│   ├── mcp_server/         # MCP 工具、提示、資源
347│   └── api/                # Auxiliary HTTP API (not pubmed_search.api)
348└── shared/                 # 跨層共用
349    ├── exceptions.py       # 例外處理
350    └── async_utils.py      # 非同步工具 (CircuitBreaker, RateLimiter, etc.)
351```
352 
353### Source Client 設計模式 (BaseAPIClient)
354 
355所有外部 API 客戶端（`infrastructure/sources/`）都繼承自 `BaseAPIClient`：
356 
357```python
358# base_client.py 提供：
359# - 自動 retry on 429 (Rate Limit) + Retry-After 支援
360# - Rate limiting (configurable min_interval)
361# - CircuitBreaker 錯誤容忍
362# - 統一的 httpx.AsyncClient 管理
363 
364class MySourceClient(BaseAPIClient):
365    _service_name = "MyAPI"
366 
367    def __init__(self):
368        super().__init__(base_url="https://api.example.com", min_interval=0.1)
369 
370    # 覆寫 _handle_expected_status() 處理 404 等預期狀態碼
371    # 覆寫 _parse_response() 自訂回應解析
372    # 覆寫 _execute_request() 自訂請求邏輯 (e.g., POST)
373```
374 
375**已整合的 8 個客戶端：** CrossRef, OpenAlex, Semantic Scholar, NCBI Extended, Europe PMC, CORE, Open-i, Unpaywall
376 
377### 導入規則
378 
379```python
380# Stable Python SDK facade for external package/notebook callers
381from pubmed_search.api import PubMedSearchClient, PubMedSearchConfig
382 
383client = PubMedSearchClient(PubMedSearchConfig(email="your@email.com"))
384 
385# Low-level/internal usage only
386from pubmed_search.infrastructure.ncbi import LiteratureSearcher
387 
388# ❌ 避免：深層相對導入
389from ...infrastructure.ncbi import LiteratureSearcher
390```
391 
392---
393 
394## 🎯 Project Overview
395 
396PubMed Search MCP is a **professional literature research assistant** that provides:
397- **45 MCP Tools** for literature search and analysis
398- **Multi-source search**: PubMed, Europe PMC (33M+), CORE (200M+)
399- **NCBI databases**: Gene, PubChem, ClinVar
400- **Full text access**: Direct XML/text retrieval
401- **Research Timeline**: Milestone detection, temporal evolution analysis
402- **Official Citation Export**: NCBI Citation Exporter API (RIS, MEDLINE, CSL)
403 
404---
405 
406## 🔍 Search Strategy Selection
407 
408### Quick Search (Default)
409**Trigger**: "find papers about...", "search for...", "any articles on..."
410```python
411unified_search(query="<topic>", limit=10)
412```
413 
414When an agent needs a lightweight topic overview in the same response, prefer:
415```python
416unified_search(query="<topic>", options="context_graph")
417```
418 
419### Systematic Search
420**Trigger**: "comprehensive search", "systematic review", "find all papers"
421```python
422# Step 1: Get MeSH terms and synonyms
423generate_search_queries(topic="<topic>")
424 
425# Step 2: Build a Boolean query from MeSH terms and synonyms
426# Step 3: Validate the final query
427analyze_search_query(query="<combined_boolean_query>")
428 
429# Step 4: Execute the search
430unified_search(query="<combined_boolean_query>")
431```
432 
433### PICO Clinical Question
434**Trigger**: "Is A better than B?", "Does X reduce Y?", comparative questions
435```python
436# Step 1: Agent extracts P/I/C/O, then validates the structured handoff
437parse_pico(
438    description="<clinical question>",
439    p="<Population>",
440    i="<Intervention/exposure>",
441    c="<Comparator, optional>",
442    o="<Outcome, recommended>"
443)
444 
445# Step 2: Get materials for each PICO element (parallel!)
446generate_search_queries(topic="<P>")
447generate_search_queries(topic="<I>")
448generate_search_queries(topic="<C>")
449generate_search_queries(topic="<O>")
450 
451# Step 3: Combine with Boolean logic
452# (P) AND (I) AND (C) AND (O)
453 
454# Step 4: Validate and execute
455analyze_search_query(query="<combined_boolean_query>")
456unified_search(query="<combined_boolean_query>")
457```
458 
459---
460 
461## 📚 Tool Categories
462 
463### 搜尋工具
464*Unified multi-source literature search gateway*
465 
466| Tool | Purpose |
467|------|---------|
468| `unified_search` | Unified Search - Single entry point for multi-source academic search. |
469 
470 
471### 查詢智能
472*MeSH expansion, agent-provided PICO handoff, and query analysis*
473 
474| Tool | Purpose |
475|------|---------|
476| `parse_pico` | Validate agent-provided PICO elements and return a runnable search plan. |
477| `generate_search_queries` | Gather search intelligence for a topic - returns RAW MATERIALS for Agent to decide. |
478| `analyze_search_query` | Analyze a search query without executing the search. |
479 
480 
481### 文章探索
482*相關文章、引用網路*
483 
484| Tool | Purpose |
485|------|---------|
486| `fetch_article_details` | Fetch detailed information for one or more PubMed articles. |
487| `find_related_articles` | Find articles related to a given PubMed article. |
488| `find_citing_articles` | Find articles that cite a given PubMed article. |
489| `get_article_references` | Get the references (bibliography) of a PubMed article. |
490| `get_citation_metrics` | Get citation metrics from NIH iCite for articles. |
491 
492 
493### 全文工具
494*全文取得與文本挖掘*
495 
496| Tool | Purpose |
497|------|---------|
498| `get_fulltext` | Enhanced multi-source fulltext retrieval. |
499| `get_text_mined_terms` | Get text-mined annotations from Europe PMC. |
500 
501 
502### NCBI 延伸
503*Gene, PubChem, ClinVar*
504 
505| Tool | Purpose |
506|------|---------|
507| `search_gene` | Search NCBI Gene database for gene information. |
508| `get_gene_details` | Get detailed information about a gene by NCBI Gene ID. |
509| `get_gene_literature` | Get PubMed articles linked to a gene. |
510| `search_compound` | Search PubChem for chemical compounds. |
511| `get_compound_details` | Get detailed information about a compound by PubChem CID. |
512| `get_compound_literature` | Get PubMed articles linked to a compound. |
513| `search_clinvar` | Search ClinVar for clinical variants. |
514 
515 
516### 引用網絡
517*引用樹建構與探索*
518 
519| Tool | Purpose |
520|------|---------|
521| `build_citation_tree` | Build a citation tree (network) from a single article. |
522 
523 
524### 匯出工具
525*引用格式匯出與本機文獻筆記保存*
526 
527| Tool | Purpose |
528|------|---------|
529| `prepare_export` | Export citations to reference manager formats. |
530| `save_literature_notes` | Save searched articles as guided local wiki/Foam/Markdown notes. |
531 
532 
533### Session 管理
534*PMID 暫存與歷史*
535 
536| Tool | Purpose |
537|------|---------|
538| `read_session` | Read session data through a single facade. |
539| `get_session_pmids` | 取得 session 中暫存的 PMID 列表。 |
540| `get_cached_article` | 從 session 快取取得文章詳情。 |
541| `get_session_summary` | 取得當前 session 的摘要資訊。 |
542| `get_session_log` | 取得當前 session 的 activity log 與搜尋歷史摘要。 |
543 
544 
545### 機構訂閱
546*OpenURL Link Resolver*
547 
548| Tool | Purpose |
549|------|---------|
550| `configure_institutional_access` | Configure your institution's link resolver for full-text access. |
551| `get_institutional_link` | Generate institutional access link (OpenURL) for an article. |
552| `list_resolver_presets` | List available institutional link resolver presets. |
553| `test_institutional_access` | Test your institutional link resolver configuration. |
554| `diagnose_institutional_access` | Diagnose why institutional fulltext access succeeds or fails for an article. |
555 
556 
557### 視覺搜索
558*圖片分析與搜索 (實驗性)*
559 
560| Tool | Purpose |
561|------|---------|
562| `analyze_figure_for_search` | Analyze a scientific figure or image for literature search. |
563 
564 
565### ICD 轉換
566*ICD-10 與 MeSH 轉換*
567 
568| Tool | Purpose |
569|------|---------|
570| `convert_icd_mesh` | Convert between ICD codes and MeSH terms (bidirectional). |
571 
572 
573### 引用驗證
574*Reference list verification with PubMed evidence*
575 
576| Tool | Purpose |
577|------|---------|
578| `verify_reference_list` | Verify a plain-text reference list against PubMed evidence. |
579 
580 
581### 圖表擷取
582*文章圖表與視覺資料擷取*
583 
584| Tool | Purpose |
585|------|---------|
586| `get_article_figures` | Get structured figure metadata (label, caption, image URL) and PDF links from a PMC Open Access arti |
587 
588 
589### 研究編年史
590*研究演化脈絡：持久化、可版本比對、證據支撐的時序主軸與分支投影*
591 
592| Tool | Purpose |
593|------|---------|
594| `build_research_chronicle` | Build a persisted, versioned, evidence-backed Research Chronicle. |
595| `read_research_chronicle` | Read stored Research Chronicles: load, list, diff, narrate, analyze, compare. |
596 
597 
598### 圖片搜尋
599*生物醫學圖片搜尋*
600 
601| Tool | Purpose |
602|------|---------|
603| `search_biomedical_images` | Search biomedical images across Open-i and Europe PMC. |
604 
605 
606### Pipeline 管理
607*Pipeline 持久化、載入、排程*
608 
609| Tool | Purpose |
610|------|---------|
611| `manage_pipeline` | Manage saved pipelines through a single facade. |
612| `save_pipeline` | Save a pipeline configuration for later reuse. |
613| `list_pipelines` | List all saved pipeline configurations. |
614| `load_pipeline` | Load a pipeline configuration for review or editing. |
615| `delete_pipeline` | Delete a saved pipeline configuration and its execution history. |
616| `get_pipeline_history` | Get execution history for a saved pipeline. |
617| `schedule_pipeline` | Schedule a saved pipeline for periodic execution. |
618 
619---
620 
621## 📋 Common Workflows
622 
623### 1. Find Papers on a Topic
624```python
625unified_search(query="remimazolam ICU sedation", limit=10)
626```
627 
628### 2. Explore from a Key Paper
629```python
630# Found an important paper (PMID: 12345678)
631find_related_articles(pmid="12345678")   # Similar papers
632find_citing_articles(pmid="12345678")    # Who cited this?
633get_article_references(pmid="12345678")  # What did it cite?
634```
635 
636### 3. Get Full Text
637```python
638# Structured full text from PMC / Europe PMC
639get_fulltext(pmcid="PMC7096777", sections="introduction,results")
640 
641# DOI or PMID-based retrieval with broader source fallback
642get_fulltext(doi="10.1038/s41586-021-03819-2", extended_sources=True)
643```
644 
645### 4. Research a Gene
646```python
647search_gene(query="BRCA1", organism="human")
648get_gene_details(gene_id="672")
649get_gene_literature(gene_id="672", limit=20)
650```
651 
652### 5. Research a Drug
653```python
654search_compound(query="propofol")
655get_compound_details(cid="4943")
656get_compound_literature(cid="4943", limit=20)
657```
658 
659### 6. Export Results
660```python
661prepare_export(pmids="last", format="ris")  # Last search
662save_literature_notes(pmids="last")  # Default wiki note + Foam-compatible wikilinks + CSL JSON
663get_fulltext(pmid="12345678", extended_sources=True)  # Retrieve selected paper full text
664```
665 
666---
667 
668## 📌 文檔自動同步規則 (IMPORTANT)
669 
670當 MCP 工具被 **新增、移除、或重新命名** 時，以下文件必須同步更新：
671 
672### 手動修改（AI Agent 負責）
6731. `tool_registry.py` — 更新 `TOOL_CATEGORIES` dict
6742. `tools/__init__.py` — import + 呼叫 `register_*_tools()`
675 
676### 自動同步（腳本負責）
677```bash
678uv run python scripts/count_mcp_tools.py --update-docs
679```
680 
681此腳本自動更新以下 6 個文件：
682- `instructions.py` — SERVER_INSTRUCTIONS 工具列表
683- `.github/copilot-instructions.md` — Tool Categories 表格
684- `.claude/skills/pubmed-mcp-tools-reference/SKILL.md` — 完整工具參考
685- `TOOLS_INDEX.md` — 工具索引
686- `README.md` / `README.zh-TW.md` — 工具數量
687 
688> ⚠️ **必須在 git commit 前執行**。詳見 `.claude/skills/tool-sync/SKILL.md`。
689 
690當 `save_literature_notes` 或 pipeline tutorial 這類 agent-facing export/persistence 行為變更時，還要同步 `AGENTS.md`、`.github/agents/research.agent.md`、`.clinerules/`、相關 `.claude/skills/`，並用 `scripts/build_docs_site.py` 更新 `docs/site-content/**` 與 skill reference copies。
691 
692---
693 
694## ⚠️ Important Notes
695 
6961. **Session Auto-management**: Search results are automatically cached. Use `pmids="last"` to reference previous searches.
697 
6981. **Tool Progress**: `unified_search`, timeline tools, and Europe PMC fulltext/text-mining tools can emit MCP progress updates when the client provides a progress token.
699 
7002. **Session Resources and Artifacts**: Agents that support MCP resources can read `session://last-search`, `session://last-search/pmids`, and `session://last-search/results` instead of reconstructing recent search state from chat context. When `unified_search` returns an `artifact_summary`, use its `artifact_uri` with `read_session(action="artifact", artifact_uri=...)`; inspect `audit.json`, `query_strategy.json`, and `results.json` or `results.toon` for complete evidence.
701 
7023. **Parallel Execution**: When generating search strategies or PICO elements, call `generate_search_queries()` in parallel for efficiency.
703 
7044. **MeSH Expansion**: `generate_search_queries()` automatically expands terms using NCBI MeSH database. This finds papers using different terminology but same concepts.
705 
7065. **Rate Limits**: The server automatically handles NCBI API rate limits. No manual throttling needed.
707 
7086. **Full Text Priority**:
709   - Europe PMC: Best for medical/biomedical, structured XML
710   - CORE: Best for broader coverage, includes preprints
711 
7127. **Citation Metrics**: Use `get_citation_metrics()` with `sort_by="rcr"` to find high-impact papers (RCR = Relative Citation Ratio).
713 
714---
715 
716## 🔗 MCP Prompts Available
717 
718The server provides pre-defined prompts for common workflows:
719- `quick_search` - Fast topic search
720- `systematic_search` - Comprehensive MeSH-expanded search
721- `pico_search` - Clinical question decomposition
722- `explore_paper` - Deep exploration from a key paper
723- `gene_drug_research` - Gene or drug focused research
724- `export_results` - Export and full text access
725- `find_open_access` - Find OA versions
726- `literature_review` - Full review workflow
727- `text_mining_workflow` - Extract entities from papers
728 
729Use `prompts/list` to see available prompts, `prompts/get` to retrieve guidance.
730