Skip to main content
Glama

PubMed Search MCP

PyPI version Python 3.10+ License: Apache 2.0 MCP CI

Professional Literature Research Assistant for AI Agents - More than just an API wrapper

PubMed Search MCP research workflow

A Domain-Driven Design (DDD) based MCP server that serves as an intelligent research assistant for AI agents, providing task-oriented literature search and analysis capabilities.

✨ What's Included:

  • 🔧 41 MCP Tools - Streamlined PubMed, Europe PMC, CORE, NCBI database access, and the versioned Research Chronicle

  • 🛡️ Multi-Agent Service Mode - Deploy once and serve many agents: per-tenant sessions, caches, and artifacts, bearer-token auth, and per-tenant fair-share limits. See DEPLOYMENT.md

  • 🖼️ OA Figure Extraction - Pull figure captions, direct image URLs, and PDF links from PMC Open Access articles

  • 📘 Docs Site - Browse the complete language-switchable handbook: user workflows, architecture, 41-tool reference, pipeline tutorials, source/broker contracts, integrations and operations, security, and deployment at u9401066.github.io/pubmed-search-mcp

  • 📖 GitHub Wiki - GitHub-native mirror of the same canonical documentation at github.com/u9401066/pubmed-search-mcp/wiki

  • 📚 26 Claude Skills - Ready-to-use workflow guides for AI agents (Claude Code-specific)

  • 📖 Copilot Instructions - VS Code GitHub Copilot integration guide

  • Research automation - Scheduled pipeline diffs/local notifications, Chronicle rebuild summaries, multi-seed citation snowballing, and opt-in session deduplication with options="exclude_seen".

🌐 Language: English | 繁體中文

📘 Documentation Map: README is the quick project entry point. Use the Docs Site for the best reading experience, the GitHub Wiki for GitHub-native navigation, and source docs for edits: User guide | Advanced workflows | Capability-first guide | Unified Search architecture | 41-tool quality audit | 60-repository academic retrieval landscape | Provider data planes | BioMCP architecture analysis | Developer guide | Complete index

Documentation map · Maintenance scripts


Research automation and portable installation — v0.8.0

Scheduled pipelines report bounded changes and retain local notification summaries. Chronicle rebuild summaries compare the previous revision; snowball pipelines expand multiple citation seeds. Normal searches can opt into options="exclude_seen" to filter previously returned PMID/DOI identities in this session before limit; the option is rejected with pipeline=. The interface remains 41 tools. See the usage guide and pipeline tutorial.

Registry metadata and plugin drift are checked before PyPI upload. Release smoke verifies the exact wheel's ownership marker and all 41 installed tools under the registry environment contract; registry publication follows PyPI via GitHub OIDC.

Related MCP server: ScholarMCP

Real workflow smoke and local pretest — v0.7.7

Local pretest runs the complete regression gate before push. CI focuses on Ubuntu/Windows installed artifacts and real MCP/provider workflows; publication verifies the exact wheel/sdist and a running non-root container. Removed 64 weak or obsolete tests with documented replacement coverage. See the testing policy and phased release review.

Background fulltext and reliable section reads — v0.7.6

Opt-in XML prefetch shares downloads with later get_fulltext calls. Queued articles become foreground reads when requested; search returns ready-to-use read arguments. Missing sections report available titles without substituting abstracts or repeating PDF retrieval. Prefetch remains off by default. See the assessment and release review.

Shared input normalization — v0.7.5

All 41 tools share automatic correction for JSON containers, decimal numeric strings, explicit boolean text, enum spelling and biomedical identifiers. Published schemas include accepted representations; pre-execution errors provide precise field paths and repair constraints. Native and normalized requests are verified across all tools, including one corrected retry. See input formats and validation.

Provider-safe scheduling — v0.7.4

Pipeline branches now proceed as their dependencies finish while API request-rate limits remain unchanged. Shared concurrency uses the most conservative caller limit; 429 cooldowns survive timeouts and cancelled PubMed workers. Historical plans are archived behind a documentation map. See the release review and offline latency experiment; fixed-delay timing is not a live-provider throughput or retrieval-quality claim.

Core review and reliability — v0.7.3

Completed the ten-phase core review: 223 source files and 2,901 definitions with authored decisions and current file hashes. This release repairs source-failure handling, article identity, persistence, cancellation, exports, and evaluation checkpoints while keeping all 41 tools. Harness installation preserves user customizations; contributors run the full local gate before push, with an independent smoke gate in ordinary CI. See the changelog for behavior changes. Local regression results do not establish a new public benchmark gain.

Research quality and evaluation — v0.7.2

This release improves query-aware ranking and fusion, cross-source article deduplication, bibliographic verification, section filtering, and concurrent cache fetches. The canonical 41-tool interface remains unchanged.

The benchmark report separates component quality from the value of the complete agent package. On public BEIR NFCorpus, an earlier BM25 component comparison improved test nDCG@10 from 0.293357 to 0.297831. That result does not measure this release's full agent performance. The three-question native Codex/package pilot is too small to establish a product-level gain; the complete 5,000-question evaluation is prepared but has not been started.

Read the reliability audit for reproduced defects, validation boundaries, and revision fingerprints. Reference verification checks bibliographic consistency; confirming that a paper supports a claim still requires inspecting the relevant passage.

🚀 Quick Install

MCP Registry and Agent Plugin

In clients that support the official MCP Registry or GitHub MCP Registry, look up io.github.u9401066/pubmed-search-mcp once the release is published. Registry metadata launches uvx pubmed-search-mcp@0.8.0 over stdio; configure NCBI_EMAIL and optionally NCBI_API_KEY in the client.

For Agent Plugins 1.0.0-compatible clients, install the repository's plugins/pubmed-search/ directory using the client's plugin installer. It bundles the version-pinned MCP launcher and research skills; client plugin support and installation UI vary. See integrations.

Prerequisites

  • Python 3.10+ — Download

  • uv (recommended) — Install uv

    # macOS / Linux
    curl -LsSf https://astral.sh/uv/install.sh | sh
    # Windows
    powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  • NCBI Email — Required by NCBI API policy. Any valid email address.

  • NCBI API Key (optional) — Get one here for higher rate limits (10 req/s vs 3 req/s)

  • OpenAlex API Key (optional) — set OPENALEX_API_KEY to use an authenticated credit allocation; without it, requests use OpenAlex's current anonymous casual-use budget. mailto is contact metadata, not authentication. Without source-specific emails, the server reuses the configured runtime contact email for OpenAlex, CrossRef, and Unpaywall.

Install & Run

# Option 1: Zero-install with uvx (recommended for trying out)
uvx pubmed-search-mcp

# Option 2: Add as project dependency
uv add pubmed-search-mcp

# Option 3: pip install
pip install pubmed-search-mcp

Python SDK Facade

For in-process Python integrations, use the stable SDK facade instead of importing MCP tool modules:

from pubmed_search.api import PubMedSearchClient, PubMedSearchConfig

async with PubMedSearchClient(PubMedSearchConfig(email="your@email.com")) as client:
    result = await client.unified_search("remimazolam ICU sedation", limit=20)

    print(result.articles)
    print(result.source_counts)
    print(result.source_errors)
    print(result.result_filter_counts)

Use uvx pubmed-search-mcp or /mcp for agent tool discovery. Use the SDK for Python package/notebook calls where a typed object is easier than parsing an MCP response string. The SDK executes the application use case directly and intentionally has no MCP session journal or artifact side effects; use the MCP tool when durable replay and artifact locators are required. The async context owns and closes every provider client and HTTP pool. If a long-lived application does not use async with, call await client.aclose() during shutdown.

Choose a Runtime Contract

Contract

Command

Network and trust boundary

Local stdio

uvx pubmed-search-mcp

Recommended for one local AI client; no listening MCP port

Local loopback HTTP

pubmed-search-mcp-http --mode local --host 127.0.0.1

Trusted single-user integration; MCP requests share the durable default tenant, and the port must never be published

Multi-user service

pubmed-search-mcp-http --mode service

Remote/team use behind HTTPS; bearer auth, allowed hosts/origins, and per-principal storage are mandatory

Local and service deployments are intentionally separate contracts. Do not turn the local HTTP command into a public service by changing only its bind address. The explicit local profile retains pmids="last", sessions, cache, and exports across MCP requests and reconnects in its durable default tenant; this is safe only inside the enforced loopback/Host/Origin boundary. Service mode never inherits that trust: it fails closed without a bearer principal. Use DEPLOYMENT.md for the service environment and Compose profile. The current service profile supports many authenticated principals in one server process; keep one replica until sessions, locks, artifacts, and subscriptions have shared backends.

The protocol baseline is MCP SDK v2 (mcp>=2.0,<3). Modern 2026-07-28 clients send tools/list and tools/call directly, without an initialize handshake or Mcp-Session-Id. Local mode retains filesystem features. Authenticated service callers cannot load file: pipelines, select note output_dir/template_file, or inherit a process-wide pipeline workspace. Note responses use tenant-relative logical locators and never reveal server filesystem paths. The service Compose scheduler is disabled. See the Integrations & Operations Guide for the capability matrix.


⚙️ Configuration

This MCP server works with any MCP-compatible AI tool. Choose your preferred client:

VS Code / Cursor (.vscode/mcp.json)

{
  "servers": {
    "pubmed-search": {
      "type": "stdio",
      "command": "uvx",
      "args": ["pubmed-search-mcp"],
      "env": {
        "NCBI_EMAIL": "your@email.com"
      }
    }
  }
}

Optional: enable browser-session PDF fallback once and let tools auto-use it:

{
  "servers": {
    "pubmed-search": {
      "type": "stdio",
      "command": "uvx",
      "args": ["pubmed-search-mcp"],
      "env": {
        "NCBI_EMAIL": "your@email.com",
        "BROWSER_FETCH_CONFIG": "{\"enabled\":true,\"auto_enabled\":true,\"broker_url\":\"http://127.0.0.1:8766/fetch\",\"token\":\"<random-32-byte-token>\",\"allowed_hosts\":[\"jamanetwork.com\",\"*.jamanetwork.com\",\"nejm.org\",\"*.nejm.org\"]}"
      }
    }
  }
}

With this setting, get_fulltext will automatically try the local broker for institutional or publisher landing pages. Pass allow_browser_session=false only when you want to suppress it for a specific call.

Run the local broker with download interception:

uv sync --extra browser-broker
uv run playwright install chromium
uv run python -c "import secrets; print(secrets.token_urlsafe(32))"
uv run pubmed-browser-fetch-broker --token "<same-random-32-byte-token>"

Copy the generated value into both commands/configurations; never reuse a published example token. --token, BROWSER_FETCH_BROKER_TOKEN, or the shared BROWSER_FETCH_TOKEN is required; the broker fails closed instead of generating or logging a secret. The broker launches a persistent browser profile with download interception enabled. Log in once inside that broker-controlled browser window, and subsequent PDF downloads will be captured automatically without a native "Save As" dialog.

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "pubmed-search": {
      "command": "uvx",
      "args": ["pubmed-search-mcp"],
      "env": {
        "NCBI_EMAIL": "your@email.com"
      }
    }
  }
}

Config file location:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • Linux: ~/.config/Claude/claude_desktop_config.json

Claude Code

claude mcp add pubmed-search -- uvx pubmed-search-mcp

Or add to .mcp.json in your project root:

{
  "mcpServers": {
    "pubmed-search": {
      "command": "uvx",
      "args": ["pubmed-search-mcp"],
      "env": {
        "NCBI_EMAIL": "your@email.com"
      }
    }
  }
}

Zed AI (settings.json)

Zed editor (z.ai) supports MCP servers natively. Add to your Zed settings.json:

{
  "context_servers": {
    "pubmed-search": {
      "command": "uvx",
      "args": ["pubmed-search-mcp"],
      "env": {
        "NCBI_EMAIL": "your@email.com"
      }
    }
  }
}

Tip: Open Command Palette → zed: open settings to edit, or go to Agent Panel → Settings → "Add Custom Server".

OpenClaw 🦞 (~/.openclaw/openclaw.json)

OpenClaw uses MCP servers via the mcp-adapter plugin. Install the adapter first:

openclaw plugins install mcp-adapter

Then add to ~/.openclaw/openclaw.json:

{
  "plugins": {
    "entries": {
      "mcp-adapter": {
        "enabled": true,
        "config": {
          "servers": [
            {
              "name": "pubmed-search",
              "transport": "stdio",
              "command": "uvx",
              "args": ["pubmed-search-mcp"],
              "env": {
                "NCBI_EMAIL": "your@email.com"
              }
            }
          ]
        }
      }
    }
  }
}

Restart the gateway after configuration:

openclaw gateway restart
openclaw plugins list  # Should show: mcp-adapter | loaded

Cline (cline_mcp_settings.json)

{
  "mcpServers": {
    "pubmed-search": {
      "command": "uvx",
      "args": ["pubmed-search-mcp"],
      "env": {
        "NCBI_EMAIL": "your@email.com",
        "SEMANTIC_SCHOLAR_API_KEY": "your_semantic_scholar_key",
        "PUBMED_SEARCH_DISABLED_SOURCES": ""
      },
      "alwaysAllow": [],
      "disabled": false
    }
  }
}

Other MCP Clients

Any MCP-compatible client can use this server via stdio transport:

# Command
uvx pubmed-search-mcp

# With environment variable
NCBI_EMAIL=your@email.com uvx pubmed-search-mcp

Note: NCBI_EMAIL is required by NCBI API policy. Optionally set NCBI_API_KEY for higher rate limits (10 req/s vs 3 req/s). 📖 Detailed Integration Guides: See docs/guides/INTEGRATIONS.md for all environment variables, Copilot Studio setup, Docker deployment, proxy configuration, and troubleshooting.


🎯 Design Philosophy

Core Positioning: The intelligent middleware between AI Agents and academic search engines.

Why This Server?

Other tools give you raw API access. We give you vocabulary translation + intelligent routing + research analysis:

Challenge

Our Solution

Agent uses ICD codes, PubMed needs MeSH

✅ Auto ICD→MeSH conversion

Multiple databases, different APIs

✅ Unified Search single entry point

Clinical questions need structured search

✅ PICO handoff + pipeline (validate_pico_plan validates agent-provided P/I/C/O and returns a runnable template: pico pipeline)

Typos in medical terms

✅ ESpell auto-correction

Too many results from one source

✅ Parallel multi-source with dedup

Need to trace research evolution

✅ Research Chronicle & Tree with landmark detection, diagnostics, sub-topic branching, and versioned revisions

Citation context is unclear

✅ Citation Tree forward/backward/network

Can't access full text

✅ Multi-source fulltext (Europe PMC XML, Unpaywall OA locations, institutional direct/EZproxy, CORE, and downloader fallbacks)

Gene/drug info scattered across DBs

✅ NCBI Extended (Gene, PubChem, ClinVar)

Need cutting-edge preprints

✅ Preprint search (arXiv, medRxiv, bioRxiv) with detected-preprint filtering; this does not verify peer-review status

Export to reference managers

✅ One-click export (official RIS/MEDLINE/CSL JSON; local RIS/BibTeX/CSV/MEDLINE/JSON)

Key Differentiators

  1. Vocabulary Translation Layer - Agent speaks naturally, we translate to each database's terminology (MeSH, ICD-10, text-mined entities)

  2. Unified Search Gateway - One unified_search() call, capability-aware dispatch across PubMed, Europe PMC, CORE, OpenAlex, Semantic Scholar, and enabled preprint/commercial sources

  3. PICO Handoff + Pipeline - the Agent extracts P/I/C/O, validate_pico_plan() validates that structured handoff, and the backend template: pico pipeline executes O-aware precision/recall searches

  4. Research Chronicle & Lineage Tree - Detect milestones with policy-driven heuristics, identify landmark papers via multi-signal scoring, surface diagnostics, persist versioned revisions you can diff, and visualize research evolution as branching trees by sub-topic

  5. Citation Network Analysis - Build multi-level citation trees to map an entire research landscape from a single paper

  6. Full Research Lifecycle - From search → discovery → full text → analysis → export, all in one server

  7. Agent-First Design - Output optimized for machine decision-making, not human reading


📡 External APIs & Data Sources

This MCP server integrates with multiple academic databases and APIs:

Core Data Sources

Source

Coverage

Vocabulary

Auto-Convert

Description

NCBI PubMed

36M+ articles

MeSH

✅ Native

Primary biomedical literature

NCBI Entrez

Multi-DB

MeSH

✅ Native

Gene, PubChem, ClinVar

Europe PMC

33M+

Text-mined

✅ Extraction

Full text XML access

CORE

200M+

None

➡️ Free-text

Open access aggregator

Semantic Scholar

Evolving graph + operator datasets

S2 fields / bulk syntax

✅ Broker-compiled modes

Relevance, bounded bulk, batch, citation graph, and metadata-only release/diff plane; no partition download

OpenAlex

Evolving open research graph

Topics / keywords

✅ Keyword + bounded native semantic

Cursor, cost provenance, entity graph, and declared operator snapshot path; no local index yet

NIH iCite

PubMed

N/A

N/A

Citation metrics (RCR)

🔑 Key: ✅ = Full vocabulary support | ➡️ = Query pass-through (no controlled vocabulary)

ICD Codes: Auto-detected and converted to MeSH before PubMed search

Environment Variables

# Required
NCBI_EMAIL=your@email.com          # Required by NCBI policy

# Optional - For higher rate limits
NCBI_API_KEY=your_ncbi_api_key     # Get from: https://www.ncbi.nlm.nih.gov/account/settings/
CORE_API_KEY=your_core_api_key     # Get from: https://core.ac.uk/services/api
CROSSREF_EMAIL=your@email.com      # Optional override; defaults to server/NCBI email
UNPAYWALL_EMAIL=your@email.com     # Optional override; defaults to server/NCBI email
SEMANTIC_SCHOLAR_API_KEY=your_semantic_scholar_key # https://www.semanticscholar.org/product/api
OPENALEX_API_KEY=your_openalex_key # Raises the OpenAlex credit budget; actual grant is response-driven
PUBMED_SEARCH_DISABLED_SOURCES=    # Example: semantic_scholar

# Optional - Pipeline run-wide safety budgets
PUBMED_PIPELINE_RUN_TIMEOUT_SECONDS=120 # Shared end-to-end deadline (max 3600)
PUBMED_PIPELINE_MAX_EXTERNAL_CALLS=40   # Shared across sequential/parallel steps (max 1000)

# Optional - Network settings
HTTP_PROXY=http://proxy:8080       # HTTP proxy for API requests
HTTPS_PROXY=https://proxy:8080     # HTTPS proxy for API requests

# Optional - Institutional fulltext access
INSTITUTIONAL_DIRECT_FETCH=true    # Try DOI publisher pages before CORE fallback
EZPROXY_ENABLED=false              # Enable only after configuring EZPROXY_HOST + cookie
EZPROXY_HOST=ezproxy.example.edu
EZPROXY_COOKIE_FILE=/path/to/cookies.json

# Optional - Local note export
PUBMED_NOTES_DIR=/path/to/wiki/references  # save_literature_notes target folder
PUBMED_WORKSPACE_DIR=/path/to/project       # fallback: references/ under this workspace
PUBMED_DATA_DIR=~/.pubmed-search-mcp        # fallback: references/ under this data dir

CrossRef and Unpaywall reuse the runtime server contact email (NCBI_EMAIL, CLI --email, or detected git email) unless a source-specific email is configured. OpenAlex accepts casual anonymous use and an optional API key; the broker reads its response credit/rate metadata instead of assuming a permanent "polite pool" quota.

Local note export resolves directories in this order: output_dir argument, PUBMED_NOTES_DIR, PUBMED_WORKSPACE_DIR/references, PUBMED_DATA_DIR/references, then ~/.pubmed-search-mcp/references. This path/template selection applies only to trusted local mode. Authenticated service notes always use a built-in format below the current tenant's isolated references/ directory. For LLM wiki compatibility, wiki and foam exports use stable link targets based on PMID, DOI, PMCID, or fallback identifiers; titles remain aliases/display labels, and the response includes wiki_validation for unresolved wikilink checks.

🔄 How It Works: The Middleware Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                              AI AGENT                                        │
│                                                                              │
│   "Find papers about I10 hypertension treatment in diabetic patients"       │
│                                                                              │
└─────────────────────────────────┬───────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                     🔄 PUBMED SEARCH MCP (MIDDLEWARE)                        │
│  ┌─────────────────────────────────────────────────────────────────────────┐│
│  │  1️⃣ VOCABULARY TRANSLATION                                              ││
│  │     • ICD-10 "I10" → MeSH "Hypertension"                                ││
│  │     • "diabetic" → MeSH "Diabetes Mellitus"                             ││
│  │     • ESpell: "hypertention" → "hypertension"                           ││
│  └─────────────────────────────────────────────────────────────────────────┘│
│  ┌─────────────────────────────────────────────────────────────────────────┐│
│  │  2️⃣ INTELLIGENT ROUTING                                                 ││
│  │     ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐             ││
│  │     │ PubMed   │  │Europe PMC│  │   CORE   │  │ OpenAlex │             ││
│  │     │  36M+    │  │   33M+   │  │  200M+   │  │  250M+   │             ││
│  │     │  (MeSH)  │  │(fulltext)│  │  (OA)    │  │(metadata)│             ││
│  │     └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘             ││
│  │          └──────────────┴──────────────┴──────────────┘                 ││
│  │                              ▼                                          ││
│  │  3️⃣ RESULT AGGREGATION: Dedupe + Rank + Enrich                         ││
│  └─────────────────────────────────────────────────────────────────────────┘│
└─────────────────────────────────┬───────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         UNIFIED RESULTS                                      │
│   • 150 unique papers (deduplicated from 4 sources)                          │
│   • Ranked by relevance + citation impact (RCR)                              │
│   • Full text links enriched from Europe PMC                                 │
└─────────────────────────────────────────────────────────────────────────────┘

🛠️ MCP Tools Overview

If you want to understand the tool surface as a usable system, do not start by memorizing 41 tool names.

Start with the Tools Usage Guide: it compresses the current 41 tools into 8 capability families, explains the theoretical lower bound, and gives intent-based routing for both humans and agents.

🔍 Search & Query Intelligence

Search and query intelligence workflow

┌─────────────────────────────────────────────────────────────────┐
│                      SEARCH ENTRY POINT                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   unified_search()          ← 🌟 Single entry for all sources    │
│        │                                                         │
│        ├── Quick search     → Direct multi-source query          │
│        ├── Native semantic → Bounded OpenAlex semantic mode    │
│        ├── Systematic       → Bounded provider bulk/cursor mode  │
│        ├── PICO hints       → Detects comparison, shows P/I/C/O  │
│        └── ICD expansion    → Auto ICD→MeSH conversion           │
│                                                                  │
│   Sources: PubMed · Europe PMC · CORE · OpenAlex · S2            │
│   Auto: Deduplicate → Rank → Enrich full-text links              │
│                                                                  │
├─────────────────────────────────────────────────────────────────┤
│   QUERY INTELLIGENCE                                             │
│                                                                  │
│   generate_search_queries() → MeSH expansion + synonym discovery │
│   validate_pico_plan()              → Agent-provided PICO handoff        │
│   analyze_search_query()    → Query analysis without execution   │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

One search entry, three retrieval policies

Generic literature discovery is intentionally exposed through exactly one MCP tool: unified_search. Provider-specific APIs remain internal broker capabilities:

# Default relevance/keyword routing across enabled sources
unified_search(query="treatment resistance")

# OpenAlex native semantic search (provider maximum 50 results)
unified_search(
    query="mechanisms of treatment resistance",
    sources="openalex",
    options="native_semantic",
)

# Deterministic/bounded retrieval: OpenAlex cursor and S2 bulk where selected
unified_search(
    query="melanoma AND immunotherapy",
    sources="openalex,semantic_scholar",
    options="systematic",
)

native_semantic and systematic are mutually exclusive and disable the multi-strategy deep-search expansion. Explicit source selections fail before a network call when a requested retrieval mode is unsupported; automatic source selection retains only capable providers. limit remains at most 100 per source, so systematic means deterministic, bounded provider execution—not an exhaustive systematic-review guarantee. Structured output and artifacts record retrieval_mode plus per-source source_metadata (requested/provider mode, canonical or compiled query, continuation availability, cost/rate metadata, and warnings when available).

The public request boundary is fail-closed. limit must be an integer from 1 through 100; unknown or malformed filters / options, reversed or out-of-range years, and unsupported ranking or output modes return a validation error before provider I/O. In the default deep-search policy, limit is one total budget per source divided across that source's query strategies—not limit results for every strategy. Strategy calls use bounded global/per-source concurrency and timeouts, and successful sources remain usable when another source times out, is rate-limited, or fails.

PubMed, Europe PMC, Scopus, and Web of Science remain keyword-only in this release; explicit systematic requests for those sources fail before I/O instead of mislabeling a single page as systematic coverage.

See Source Contracts, Semantic Scholar, and OpenAlex for provider limits and operator data-plane boundaries.

🔬 Discovery Tools (After Finding Key Papers)

Article discovery and citation workflow

                        Found important paper (PMID)
                                   │
           ┌───────────────────────┼───────────────────────┐
           │                       │                       │
           ▼                       ▼                       ▼
    ┌─────────────┐        ┌─────────────┐        ┌─────────────┐
    │  BACKWARD   │        │  SIMILAR    │        │  FORWARD    │
    │  ◀──────    │        │  ≈≈≈≈≈≈     │        │  ──────▶    │
    │             │        │             │        │             │
    │ get_article │        │find_related │        │find_citing  │
    │ _references │        │ _articles   │        │ _articles   │
    │             │        │             │        │             │
    │ Foundation  │        │  Similar    │        │ Follow-up   │
    │  papers     │        │   topic     │        │  research   │
    └─────────────┘        └─────────────┘        └─────────────┘

    fetch_article_details()   → Detailed article metadata
    get_citation_metrics()    → iCite RCR, citation percentile
    build_citation_tree()     → Full network visualization (6 formats)

📚 Full Text, Figure Extraction & Export

For searches followed by close reading, unified_search(..., fulltext="prefetch") prepares up to three eligible PMC XML articles in the background. Later get_fulltext calls share ready/in-flight XML. Default is off; no polling or speculative PDF/browser access. Tradeoffs and limits.

Full text, figures, and biomedical image workflow

Category

Tools

Full Text

get_fulltext → Europe PMC XML when a PMCID is available; DOI-backed Unpaywall, institutional direct/EZproxy, CORE, and downloader fallbacks when needed

Figures

get_article_figures → Extract figure labels, captions, image URLs, and PDF links from PMC Open Access articles

Figure-aware Full Text

get_fulltext(include_figures=True) → Embed figure metadata alongside structured fulltext

Text Mining

get_text_mined_terms → Extract genes, diseases, chemicals

Export

prepare_export → official RIS/MEDLINE/CSL JSON or local RIS/BibTeX/CSV/MEDLINE/JSON; save_literature_notes → local wiki/Foam-compatible/Markdown/MedPaper-style notes plus collection-level CSL JSON

get_fulltext reports coverage_status, exact sources_tried / sources_completed, and sanitized source_errors. A usable article or link from one source plus a failure from another is therefore partial, not a misleading complete success or empty result. Extended PDF discovery carries the same immutable typed coverage envelope through discovery, download, extraction, tool output, and artifacts.

🖼️ OA Figure-First Exploration

Use the PMC Open Access path when an agent needs evidence figures, not just article text:

  • get_article_figures(source={"kind":"pmcid","value":"PMC12086443"}) → Figure labels, captions, image URLs, and PDF/article links

  • get_fulltext(source={"kind":"pmcid","value":"PMC7096777"}, include_figures=True) → Structured fulltext with figures inline

  • Figure output preserves article context, so agents can connect each figure back to the sections where it is mentioned

🧬 NCBI Extended Databases

NCBI extended biomedical data workflow

Tool

Description

search_gene

Search NCBI Gene database

get_gene_details

Gene details by NCBI Gene ID

get_gene_literature

PubMed articles linked to a gene

search_compound

Search PubChem compounds

get_compound_details

Compound details by PubChem CID

get_compound_literature

PubMed articles linked to a compound

search_clinvar

Search ClinVar clinical variants

🕰️ Research Chronicle & Lineage Tree

Research Chronicle Architecture and Lineage Flow Evaluation and timeline workflow

Tool

Description

build_research_chronicle

Build a persisted, versioned chronicle with landmark detection. Output: summary, chronicle_map, timeline, tree, graph, evidence, milestones, mermaid, narrative, json

read_research_chronicle

Load, list, diff revisions, narrate with citations, analyze milestone distribution, or compare up to five topics

# 1. Build from topic (retrieves PubMed, scores landmarks, clusters lineages)
build_research_chronicle(topic="remimazolam intraoperative", output="mermaid", max_events=30)

# 2. Continue an existing chronicle (inherits stored topic and filters to produce Revision N+1)
build_research_chronicle(chronicle_id="remimazolam-intraoperative-08c229f3")

# 3. Read revision diff, milestone analytics, or cross-topic comparison
read_research_chronicle(request={"action":"diff","chronicle_id":"remimazolam-intraoperative-08c229f3","from_revision":1})
read_research_chronicle(request={"action":"milestones","chronicle_id":"remimazolam-intraoperative-08c229f3"})
read_research_chronicle(request={"action":"compare","selection":{"kind":"topics","values":["remimazolam intraoperative","propofol intraoperative"]}})

mermaid is the canonical combined view: a horizontal year spine (X-axis) with each observed research line (Y-axis) branching at its earliest dated paper within the retrieved scope. This is an explainable grouping, not a causal genealogy or a claim about the field's true first paper. Lineages prefer MeSH descriptors and author keywords shared by multiple papers; singleton-only or insufficient signals trigger a warned research-stage fallback. Same-year display order is stable, but does not assert precedence when publication precision cannot prove it. See Advanced Research Workflows (docs/guides/ADVANCED_RESEARCH_WORKFLOWS.md) and docs/design/RESEARCH_CHRONICLE_REFACTOR_SPEC.md.

Chronicle Mermaid output is built from structured nodes and edges, with safe label escaping, cycle/orphan repair, collision-resistant IDs, and bounded graph size. It falls back from rich to safe to minimal syntax instead of failing the whole chronicle. mermaid_validation.json records every correction, fallback, and omitted visual item; chronicle.mmd remains pure Mermaid source.

Chronicle revisions are immutable and appended atomically. When session artifact persistence is enabled, artifact failure is surfaced explicitly while the saved Chronicle revision remains available.

Topic builds send year limits to PubMed before bounded retrieval, then preserve the first and last observed papers while filling the cap with landmarks and temporal spread. The audit records PubMed returned / available counts and warns when availability is unknown or any retrieval/selection cap makes the view non-exhaustive. PubMed errors or a scope with no article evidence do not publish an empty revision.

Retrieval provenance separates ranking_requested from the effective ranking. iCite ordering is claimed only when a validated citation count was actually applied. The versioned citation-metrics coverage records complete, partial, empty, error, and not-requested outcomes with safe counts and errors; the audit warns or fails rather than treating an outage as zero citations.

Explicit PMID input is strict (12345678 or PMID:12345678, positive ASCII digits, at most 20 digits); DOI or mixed text is rejected instead of being coerced. Records without a reliable publication date appear as Undated after dated entries and are excluded from the displayed year span. Entry IDs follow PMID/DOI evidence identity across date or classifier corrections, and topic continuity uses one Unicode/case/whitespace canonical key. Multi-signal papers keep one primary branch plus explicit cross-links; overlap of 20% or more is audited as a warning. In revision diffs, absence means not_observed_in_revision, never conclusive retirement.

🏥 Institutional Access & ICD Conversion

Institutional access workflow

Tool

Description

configure_institutional_access

Configure institution's link resolver

get_institutional_link

Generate OpenURL access link

list_resolver_presets

List resolver presets

test_institutional_access

Test resolver configuration

diagnose_institutional_access

Diagnose direct DOI, EZproxy, and OpenURL handoff paths

convert_icd_mesh

Convert between ICD codes and MeSH terms (bidirectional)

unified_search

Auto-detect ICD codes in queries and expand them to MeSH

Resolver bases must be credential-free HTTP(S) URLs without a query or fragment. PMID diagnosis reports resolved, not_found, or error for the PubMed-to-DOI step, so an upstream outage is never described as a missing DOI.

💾 Session Management

Session and pipeline workflow

Tool

Description

read_session

Strict action-discriminated reader for PMIDs, cached articles, summaries, logs, durable search runs, replay arguments, and persistent artifacts

Dynamic MCP resources are also available for agents that can read resources directly:

  • session://context — active session status

  • session://last-search — latest search metadata

  • session://last-search/pmids — latest PMID list + CSV form

  • session://last-search/results — cached article payloads for the latest search

Persistent Artifacts

Persistent MCP output artifacts are saved for reusable unified_search and get_fulltext responses when session persistence is configured. Tool responses act like index cards: they include enough counts, source warnings, and artifact hints for an agent to answer immediately, while the full evidence payload stays in files that can be read repeatedly. The compact artifact locator includes artifact_id, artifact_uri, primary_file, summary, file inventory, read_order, audit status, and exact read_session(...) retrieval hints. Set PUBMED_ARTIFACT_INCLUDE_LOCAL_PATHS=true only when a local MCP client should also receive local_path and manifest_path directly.

Remote clients that cannot read the server filesystem can retrieve the same content through the session facade:

read_session(request={"action":"list_artifacts"})
read_session(request={"action":"artifact","locator":{"kind":"artifact_id","value":"..."}})
read_session(request={"action":"artifact","locator":{"kind":"artifact_uri","value":"artifact://..."}})
read_session(request={"action":"artifact","locator":{"kind":"artifact_uri","value":"artifact://..."},"artifact_file":"audit.json"})
read_session(request={"action":"artifact","locator":{"kind":"artifact_uri","value":"artifact://..."},"artifact_file":"query_strategy.json"})
read_session(request={"action":"artifact","locator":{"kind":"artifact_uri","value":"artifact://..."},"artifact_file":"results.json","offset":0,"max_chars":200000})
read_session(request={"action":"list_artifacts","include_local_paths":true})

Recoverable search runs

When session management is active, every unified_search invocation receives a stable run ID. This includes normal searches, validation/planning failures, and inline, saved:<name>, or dry_run=true pipeline execution. Structured results and errors attach the search_run handoff; Markdown returns the same run ID as a compact recovery note. Normal literature-result envelopes expose two separate machine contracts:

  • search_status describes the bounded retrieval outcome: state (completed, empty, partial, or failed), bounded=true, exhaustive=false, returned count, attempted/successful/failed/retryable sources, and continuation/unknown-completeness source lists.

  • search_run is the recovery handoff: stable run_id, journal status, recoverable, exact read_session inspect/replay arguments, and the artifact URI when one was committed.

The tenant-scoped search-run/v1 journal is published before provider I/O or a terminal validation response and records the sanitized request, plan, physical per-source or per-pipeline-step attempts, counts, safe failures, result references, and artifact locator when applicable. It reaches a terminal completed, partial, failed, or cancelled state; a valid zero-result search is a completed run whose search_status.state is empty. On restart, an unfinished started / planned / running entry is recovered once as interrupted instead of disappearing. A non-dry-run saved pipeline additionally keeps its PipelineStore report/run history; that is complementary to the invocation-level search journal, not a replacement for it.

Pipeline replay preserves the original inline or saved:<name> argument plus dry_run / stop_at. Pipeline text containing keys, tokens, cookies, passwords, or other credential material is rejected and recorded as a failed run; provider credentials belong in server environment/configuration, never pipeline YAML or JSON.

read_session(request={"action":"search_runs"})
read_session(request={"action":"search_runs","status":"partial"})
read_session(request={"action":"search_run","run_id":"..."})
read_session(request={"action":"replay_search","run_id":"..."})

replay_search only returns the original credential-free unified_search kwargs. It never executes a network call automatically; the agent or user must review and explicitly submit them. Provider cursor/token values are retained as opaque provenance in source_metadata and query_strategy.json, but there is no public cursor-resume parameter yet, so replay starts a new bounded search.

If the terminal journal write cannot be recovered, the response reports search_run.status="history_unavailable", history_available=false, the intended terminal status, and a warning. It deliberately omits inspect/replay actions because durable recovery is not guaranteed; the search result itself may still be usable.

unified_search artifacts use a research envelope. Start with audit.json for source-count and completeness warnings, then query_strategy.json for the exact executed plan, and finally results.json / results.toon for the complete article list. This keeps MCP response tokens small without losing academic traceability.

Artifacts are generated from the already-computed result object, so reading an artifact does not rerun searches or fulltext retrieval. If a crash occurs after an artifact directory is atomically published but before the session index is updated, session reload discovers only complete, checksum-indexed manifests and relinks the orphaned artifact to its search run by search_run_id (with a conservative query match for older artifacts). read_session redacts local filesystem paths by default; local_path and manifest_path are server-local paths, not portable client paths. Artifacts from get_fulltext may contain article body text, including subscription or institutionally accessed content. Store and share them according to publisher, license, and institutional access terms. Large get_fulltext responses are returned inline as a preview when an artifact is available; use the artifact locator to retrieve the saved full content.

When one source fails but the overall search can continue, JSON responses may include source_errors; markdown responses show a Source warnings line. For Semantic Scholar HTTP 429s, set SEMANTIC_SCHOLAR_API_KEY, retry later, or temporarily exclude it with sources="auto,-semantic_scholar" or PUBMED_SEARCH_DISABLED_SOURCES=semantic_scholar.

Pipeline Management

Session and pipeline workflow

Pipeline management uses seven single-purpose, schema-exact tools. Each tool accepts only the fields relevant to that operation, so misspelled or unrelated arguments fail closed instead of being silently ignored.

Tool

Description

save_pipeline

Save a pipeline config for later reuse (YAML/JSON, auto-validated)

list_pipelines

List saved pipelines (filter by tag/scope)

load_pipeline

Load by saved name; trusted local callers may also load a file

delete_pipeline

Delete pipeline and its execution history

get_pipeline_history

View execution history with article diff analysis

schedule_pipeline

Create or update a recurring pipeline schedule

unschedule_pipeline

Remove a recurring pipeline schedule

Authenticated service callers use named pipelines in their tenant-derived store; workspace and file: access are local-only. The service Compose profile does not execute schedules without a separately designed single leader. Pipeline history is fail-closed: one malformed persisted run produces a safe explicit error instead of a partial list or a false “no history” result.

Step-by-step tutorials:

Full text, figures, and biomedical image workflow

Tool

Description

prepare_figure_search

Handoff an uploaded image, image URL, or data URI to agent vision for search-term extraction

search_biomedical_images

Search biomedical images across Open-i (X-ray, microscopy, photos, diagrams)

Use prepare_figure_search when the user supplies an image and the agent must interpret its meaning first. The tool returns MCP ImageContent plus instructions for the LLM agent to extract English biomedical terms, then continue with search_biomedical_images for similar Open-i images or unified_search for related papers.

Open-i results carry typed per-source coverage. A valid total=0 and empty list means no matches; a malformed response or source outage is failed, and mixed valid/invalid rows are partial. Failed sources are excluded from sources_used, their total stays unknown, and Markdown shows the sanitized coverage instead of claiming “no images.”

Search arXiv, medRxiv, and bioRxiv preprint servers via unified_search options flags:

Source, filter, and option tokens use exact canonical spelling. Do not add whitespace around comma-separated tokens or repeat a token; aliases and case variants are rejected.

  • preprints: Search preprint servers and merge preprints into the main aggregated result set with article_type=PREPRINT.

  • include_detected_preprints: Keep records identified by the preprint heuristic in otherwise selected scholarly sources, without adding a preprint-server crawl.

Preprint source metadata reports the provider query/window, result limit, unknown corpus total, and local year-filter counts. Unknown-year records are excluded when a hard year range is requested. medRxiv/bioRxiv use a bounded date feed with literal all-term filtering, so Boolean or grouped query syntax fails before network I/O instead of being silently reinterpreted.

Recommended combinations:

  • Empty options: Records detected as preprints are filtered. This heuristic does not prove that every remaining record was peer reviewed.

  • options="preprints": Searches arXiv, medRxiv, and bioRxiv, then ranks/dedupes those preprints with the main results.

  • options="include_detected_preprints": No preprint-server crawl; detected preprints already returned by selected sources are retained.

Preprint detection — articles are identified as preprints by:

  • Article type from source API (OpenAlex, CrossRef, Semantic Scholar)

  • arXiv ID present without PubMed ID

  • Known preprint server source or journal name

  • DOI prefix matching preprint servers (e.g., 10.1101/ → bioRxiv/medRxiv, 10.48550/ → arXiv)

For chronological research lineage, use build_research_chronicle; it is the only research-chronology capability and supplies the audited timeline, branching map, narrative, and revision history.

🧪 Clinical-Trial Registry Adjunct

ClinicalTrials.gov is never queried implicitly. Add options="clinical_trials" to a search when a bounded registry adjunct is useful. It remains separate from the literature-source plan, article ranking, and source counts. Markdown renders up to three records; JSON/TOON returns the same requested adjunct as structured data. The versioned clinical-trials-adjunct/v1 coverage records retrieval and format status, returned count, completeness, warnings, and sanitized failures consistently across the response and durable artifact.

unified_search(query="remimazolam ICU sedation", options="clinical_trials")

📊 Count-First Orientation

unified_search can also front-load the existing source coverage and decision hints for agents that want routing help before reading the ranked list:

Option Flag

Description

counts_first

Add a source-count table, coverage summary, and next-tool recommendations to the response

Example:

unified_search(query="remimazolam ICU sedation", options="counts_first")

This mode is useful when the agent should decide whether to expand a source, inspect the lead PMID, fetch fulltext, extract figures, or pivot into timeline exploration.

⏱️ MCP Progress Reporting

When the MCP client provides a progress token, unified_search, build_research_chronicle, get_fulltext, and get_text_mined_terms emit progress updates for their major phases. This reduces the "black box" wait time for agents during longer searches. Progress callbacks are best-effort and have a 100 ms hard deadline. A stalled callback is cancelled; if a broken host suppresses cancellation, its task is quarantined in a server-owned pool capped at 32 entries so core tools remain responsive without unbounded background work.


📋 Agent Usage Examples

1️⃣ Quick Search (Simplest)

# Agent just asks naturally - middleware handles everything
unified_search(query="remimazolam ICU sedation", limit=20)

# Or with clinical codes - auto-converted to MeSH
unified_search(query="I10 treatment in E11.9 patients")
#                     ↑ ICD-10           ↑ ICD-10
#                     Hypertension       Type 2 Diabetes

2️⃣ PICO Clinical Question

PICO clinical search workflow

Simple path — unified_search can search directly (no PICO decomposition):

# unified_search searches as-is; detects "A vs B" pattern and shows PICO hints in metadata
unified_search(query="Is remimazolam better than propofol for ICU sedation?")
# → Multi-source keyword search + PICO hint metadata in output
# ⚠️ This does NOT auto-decompose PICO or expand MeSH!
# For structured PICO search, use the Agent workflow below

Agent workflow — agent-provided PICO + backend pipeline search (recommended for clinical questions):

┌─────────────────────────────────────────────────────────────────────────┐
│  "Is remimazolam better than propofol for ICU sedation?"                │
└─────────────────────────────────┬───────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         validate_pico_plan()                                     │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐                     │
│  │    P    │  │    I    │  │    C    │  │    O    │                     │
│  │  ICU    │  │remimaz- │  │propofol │  │sedation │                     │
│  │patients │  │  olam   │  │         │  │outcomes │                     │
│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘                     │
└───────┼────────────┼────────────┼────────────┼──────────────────────────┘
        │            │            │            │
        ▼            ▼            ▼            ▼
┌─────────────────────────────────────────────────────────────────────────┐
│              generate_search_queries() × 4 (parallel)                    │
│                                                                          │
│  P → "Intensive Care Units"[MeSH]                                        │
│  I → "remimazolam" [Supplementary Concept], "CNS 7056"                   │
│  C → "Propofol"[MeSH], "Diprivan"                                        │
│  O → "Conscious Sedation"[MeSH], "Deep Sedation"[MeSH]                   │
└─────────────────────────────────┬───────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────┐
│              Agent combines with Boolean logic                           │
│                                                                          │
│  (P) AND (I) AND (C) AND (O)  ← High precision                           │
│  (P) AND (I OR C) AND (O)     ← High recall                              │
└─────────────────────────────────┬───────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────┐
│              unified_search() (auto multi-source + dedup)                │
│                                                                          │
│  PubMed + Europe PMC + CORE + OpenAlex → Auto deduplicate & rank         │
└─────────────────────────────────────────────────────────────────────────┘
# Step 1: Agent extracts P/I/C/O, then validates the structured handoff
pico = validate_pico_plan(
    description="Is remimazolam better than propofol for ICU sedation?",
    p="ICU patients requiring sedation",
    i="remimazolam",
    c="propofol",
    o="sedation efficacy, delirium, hypotension"
)
# Returns validation plus a ready-to-run `template: pico` pipeline.

# Step 2: Get MeSH for each element (parallel!)
generate_search_queries(topic="ICU patients")   # P
generate_search_queries(topic="remimazolam")    # I
generate_search_queries(topic="propofol")       # C
generate_search_queries(topic="sedation")       # O

# Step 3: Either pass expanded fragments back as p_query/i_query/c_query/o_query
# or let the backend pipeline use the structured P/I/C/O labels.

# Step 4: Search (backend runs O-aware precision/recall searches, dedup, rank)
unified_search(
    query="Is remimazolam better than propofol for ICU sedation?",
    pipeline=pico["pipeline"]
)

3️⃣ Explore from Key Paper

# Found landmark paper PMID: 33475315
find_related_articles(pmid="33475315")   # Similar methodology
find_citing_articles(pmid="33475315")    # Who built on this?
get_article_references(pmid="33475315")  # What's the foundation?

# Build complete research map
build_citation_tree(pmid="33475315", depth=2, output_format="mermaid")

4️⃣ Gene/Drug Research

# Research a gene
search_gene(query="BRCA1", organism="human")
get_gene_literature(gene_id="672", limit=20)

# Research a drug compound
search_compound(query="propofol")
get_compound_literature(cid="4943", limit=20)

5️⃣ Export Results

# Export last search results
prepare_export(pmids="last", format="ris")      # → EndNote/Zotero
prepare_export(pmids="last", format="bibtex", source="local")  # → LaTeX
prepare_export(pmids="last", format="csl")      # → CSL JSON from the official NCBI Citation API
save_literature_notes(pmids="last")              # → local wiki note + Foam-compatible wikilinks + CSL JSON
save_literature_notes(pmids="last", note_format="medpaper", output_dir="./references")
save_literature_notes(pmids="last", template_file="./reference-template.md")

# Retrieve full text for a selected paper from the last search
get_fulltext(source={"kind":"pmid","value":"12345678"}, extended_sources=True)
# Search preprint sources alongside the regular scholarly-source set
unified_search(query="COVID-19 vaccine efficacy", options="preprints")
# → Main aggregated results include labelled arXiv, medRxiv, and bioRxiv preprints

# Retain preprints detected in otherwise selected sources without adding a crawl
unified_search(query="CRISPR gene therapy", options="include_detected_preprints")

# Default heuristic policy
unified_search("diabetes treatment")
# → Detected preprints are filtered; remaining peer-review status is not proven

7️⃣ Pipeline (Reusable Search Plans)

# Save a template-based pipeline through the primary facade
save_pipeline(
    name="icu_sedation_weekly",
    config="template: pico\ntemplate_params:\n  P: ICU patients\n  I: remimazolam\n  C: propofol\n  O: delirium",
    tags=["anesthesia","sedation"],
    description="Weekly ICU sedation monitoring"
)

# Save a custom DAG pipeline
save_pipeline(
    name="brca1_comprehensive",
    config="""
steps:
  - id: expand
    action: expand
    params: { topic: BRCA1 breast cancer }
  - id: pubmed
    action: search
    params: { query: BRCA1, sources: [pubmed], limit: 50 }
  - id: expanded
    action: search
    inputs: [expand]
    params: { strategy: mesh, sources: [pubmed, openalex], limit: 50 }
  - id: merged
    action: merge
    inputs: [pubmed, expanded]
    params: { method: rrf }
  - id: enriched
    action: metrics
    inputs: [merged]
output:
  limit: 30
  ranking: quality
"""
)

# Execute a saved pipeline
unified_search(pipeline="saved:icu_sedation_weekly")

# List & manage
list_pipelines(tag="anesthesia")
load_pipeline(source="brca1_comprehensive")  # Review YAML
get_pipeline_history(name="icu_sedation_weekly")  # View past runs

🔍 Search Mode Comparison

┌─────────────────────────────────────────────────────────────────────────┐
│                        SEARCH MODE DECISION TREE                         │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│   "What kind of search do I need?"                                       │
│         │                                                                │
│         ├── Know exactly what to search?                                 │
│         │   └── unified_search(query="topic keywords")                   │
│         │       → Quick, auto-routing to best sources                    │
│         │                                                                │
│         ├── Have a clinical question (A vs B)?                           │
│         │   └── Agent P/I/C/O → validate_pico_plan() handoff                  │
│         │       → unified_search(template:pico) or expanded Boolean    │
│         │                                                                │
│         ├── Need comprehensive systematic coverage?                      │
│         │   └── generate_search_queries() → parallel search              │
│         │       → MeSH expansion, multiple strategies, merge             │
│         │                                                                │
│         └── Exploring from a key paper?                                  │
│             └── find_related/citing/references → build_citation_tree     │
│                 → Forward/backward citation network                      │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

Mode

Entry Point

Best For

Auto-Features

Quick

unified_search()

Fast topic search

ICD→MeSH, multi-source, dedup

PICO

Agent P/I/C/O -> validate_pico_plan()

Clinical questions

Validate handoff -> template:pico backend search

Systematic

generate_search_queries() → unified_search(options="systematic")

Reproducible review seed

MeSH/synonyms plus bounded bulk/cursor execution; not an exhaustiveness claim

Native semantic

unified_search(options="native_semantic")

Conceptual similarity in title/abstract space

Capability validation; OpenAlex semantic mode, max 50

Exploration

find_*_articles()

From key paper

Citation network, related


🤖 Claude Skills (AI Agent Workflows)

Pre-built workflow guides in .claude/skills/, divided into Usage Skills (for using the MCP server) and Development Skills (for maintaining the project):

📚 Usage Skills (11) — For AI Agents Using This MCP Server

Skill

Description

pubmed-quick-search

Basic search with filters

pubmed-systematic-search

MeSH expansion, comprehensive

pubmed-pico-search

Clinical question decomposition

pubmed-paper-exploration

Citation tree, related articles

pubmed-research-chronicle

Persistent, versioned research evolution

pubmed-gene-drug-research

Gene/PubChem/ClinVar

pubmed-fulltext-access

Europe PMC, CORE full text

pubmed-export-citations

RIS/BibTeX/CSV/CSL export guidance

pubmed-multi-source-search

Cross-database unified search

pubmed-mcp-tools-reference

Complete tool reference guide

pipeline-persistence

Save, load, reuse search plans

🔧 Development Skills (15) — For Project Contributors

Skill

Description

changelog-updater

Auto-update CHANGELOG.md

code-refactor

DDD architecture refactoring

code-reviewer

Code quality & security review

ddd-architect

DDD scaffold for new features

git-doc-updater

Sync docs before commits

git-precommit

Pre-commit workflow orchestration

memory-checkpoint

Save context to Memory Bank

memory-updater

Update Memory Bank files

pdf-asset-extractor

Extract and inventory citation-ready PDF assets

project-init

Initialize new projects

readme-i18n

Multilingual README sync

readme-updater

Sync README with code changes

roadmap-updater

Update ROADMAP.md status

test-generator

Generate test suites

tool-sync

Keep the MCP registry and generated tool documentation aligned

📁 Location: .claude/skills/*/SKILL.md (Claude Code-specific, and the single source of truth for repo skills) Do not mirror or split repo skills into .github/skills/. These repo skills are project-scoped and should remain version-controlled. Personal cross-project skills belong in a user directory such as ~/.copilot/skills/ or ~/.claude/skills/, not in this repository.

Research skill installation preserves existing customizations. See the installation and upgrade policy. Contributors run the full local gate before push; ordinary CI runs a smaller independent smoke gate.

The completed ten-phase core review covers all 223 Python files in src/pubmed_search/: 456 classes and 2,445 functions/methods/nested functions. Each of the 2,901 definitions has a recorded decision, evidence, and current file SHA-256; none are pending or stale. This is an authored self-review, separate from test results. Recheck the current tree with uv run python scripts/perf/symbol_inventory.py --require-reviewed src/; subsequent source edits invalidate affected reviews. Tests and scripts are inventoried but are outside this complete core-review claim.

Real MCP Regression Gate

Every one of the 41 public tools is called through the MCP protocol over source-tree stdio, Streamable HTTP, and stdio from a freshly installed wheel. The wheel path imports server code exclusively from its blank virtual environment; the external fixture supplies only deterministic provider seams. The deterministic child server replaces external-provider boundaries; registry, schemas, application services, persistence, artifacts, Chronicle revisions, pipelines, and scheduling remain real. The opt-in extended CI also renders the exact Chronicle and citation Mermaid sources returned over MCP with pinned Mermaid 11.16.1, so presentation-layer syntax damage fails the gate. An additional real-stdio rejection pass confirms that retired tool names, legacy flat request shapes, ambiguous scalar values, and malformed containers remain rejected.

uv run pytest -q tests/test_all_tools_mcp_acceptance.py

See the Developer Guide for the test architecture, CI gates, and live-provider boundary.


🏗️ Architecture (DDD)

This project uses Domain-Driven Design (DDD) architecture, with literature research domain knowledge as the core model.

src/pubmed_search/
├── domain/                     # Core business logic
│   └── entities/article.py     # UnifiedArticle, Author, etc.
├── application/                # Use cases
│   ├── search/                 # QueryAnalyzer, ResultAggregator
│   ├── export/                 # Citation export (RIS, BibTeX...)
│   └── session/                # SessionManager
├── infrastructure/             # External systems
│   ├── ncbi/                   # Entrez, iCite, Citation Exporter
│   ├── sources/                # Europe PMC, CORE, CrossRef...
│   └── http/                   # HTTP clients
├── presentation/               # User interfaces
│   ├── mcp_server/             # MCP tools, prompts, resources
│   │   ├── tools/              # discovery, strategy, pico, export...
│   │   └── http_cli.py         # Canonical Streamable HTTP/SSE launcher
│   └── browser_fetch_broker.py # Optional isolated browser-fetch service
└── shared/                     # Cross-cutting concerns
    ├── exceptions.py           # Unified error handling
    └── async_utils.py          # Rate limiter, retry, circuit breaker

Internal Mechanisms (Transparent to Agent)

Mechanism

Description

Session

Auto-create, auto-switch

Cache

Auto-cache search results, avoid duplicate API calls

Rate Limit

Auto-comply with NCBI API limits (0.34s/0.1s)

MeSH Lookup

generate_search_queries() auto-queries NCBI MeSH database

ESpell

Auto spelling correction (remifentanyl → remifentanil)

Query Analysis

Each suggested query shows how PubMed actually interprets it

Vocabulary Translation Layer (Key Feature)

Our Core Value: We are the intelligent middleware between Agent and Search Engines, automatically handling vocabulary standardization so Agent doesn't need to know each database's terminology.

Different data sources use different controlled vocabulary systems. This server provides automatic conversion:

API / Database

Vocabulary System

Auto-Conversion

PubMed / NCBI

MeSH (Medical Subject Headings)

✅ Full support via expand_with_mesh()

ICD Codes

ICD-10-CM / ICD-9-CM

✅ Auto-detect & convert to MeSH

Europe PMC

Text-mined entities (Gene, Disease, Chemical)

✅ get_text_mined_terms() extraction

OpenAlex

Topics / keywords (model-inferred)

✅ Broker keyword mode; bounded native semantic mode when selected

Semantic Scholar

S2 fields / bulk query syntax

✅ Broker chooses relevance or bounded bulk mode; provider annotations keep provenance

CORE

None

❌ Free-text only

CrossRef

None

❌ Free-text only

Automatic ICD → MeSH Conversion

When searching with ICD codes (e.g., I10 for Hypertension), unified_search() automatically:

  1. Detects ICD-10/ICD-9 patterns via detect_and_expand_icd_codes()

  2. Looks up corresponding MeSH terms from internal mapping (ICD10_TO_MESH, ICD9_TO_MESH)

  3. Expands query with MeSH synonyms for comprehensive search

# Agent calls unified_search with clinical terminology
unified_search(query="I10 treatment outcomes")

# Server auto-expands to PubMed-compatible query
"(I10 OR Hypertension[MeSH]) treatment outcomes"

📖 Full architecture documentation: ARCHITECTURE.md

MeSH Auto-Expansion + Query Analysis

When calling generate_search_queries("remimazolam sedation"), internally it:

  1. ESpell Correction - Fix spelling errors

  2. MeSH Query - Entrez.esearch(db="mesh") to get standard vocabulary

  3. Synonym Extraction - Get synonyms from MeSH Entry Terms

  4. Query Analysis - Analyze how PubMed interprets each query

{
  "mesh_terms": [
    {
      "input": "remimazolam",
      "preferred": "remimazolam [Supplementary Concept]",
      "synonyms": ["CNS 7056", "ONO 2745"]
    }
  ],
  "all_synonyms": ["CNS 7056", "ONO 2745", ...],
  "suggested_queries": [
    {
      "id": "q1_title",
      "query": "(remimazolam sedation)[Title]",
      "purpose": "Exact title match - highest precision",
      "estimated_count": 8,
      "pubmed_translation": "\"remimazolam sedation\"[Title]"
    },
    {
      "id": "q3_and",
      "query": "(remimazolam AND sedation)",
      "purpose": "All keywords required",
      "estimated_count": 561,
      "pubmed_translation": "(\"remimazolam\"[Supplementary Concept] OR \"remimazolam\"[All Fields]) AND (\"sedate\"[All Fields] OR ...)"
    }
  ]
}

Value of Query Analysis: Agent thinks remimazolam AND sedation only searches these two words, but PubMed actually expands to Supplementary Concept + synonyms, results go from 8 to 561. This helps Agent understand the difference between intent and actual search.


🔒 Local HTTPS Demo and Service Deployment

The bundled self-signed certificates and curl -k flow are a local TLS demo, not a production security profile. For a shared service, use the authenticated service Compose file and a trusted certificate as described in DEPLOYMENT.md.

Local HTTPS Smoke Test

# Step 1: Generate SSL certificates
./scripts/generate-ssl-certs.sh

# Step 2: Start HTTPS service (Docker)
./scripts/start-https-docker.sh up

# Verify deployment
curl -k https://localhost/

HTTPS Endpoints

Service

URL

Description

MCP

https://localhost/mcp

Streamable HTTP MCP endpoint

Health

https://localhost/health

Health check

Ready

https://localhost/ready

Readiness check

Info

https://localhost/info

Runtime transport and endpoint metadata

Exports

https://localhost/exports

Local prepared export listing; service mode requires bearer auth and tenant scope

Remote MCP Client Configuration

{
  "mcpServers": {
    "pubmed-search": {
      "url": "https://localhost/mcp"
    }
  }
}

🏢 Microsoft Copilot Studio Integration

Integrate PubMed Search MCP with Microsoft 365 Copilot (Word, Teams, Outlook)!

Quick Start

# Unpublished local schema/protocol smoke only; never tunnel local mode
pubmed-search-mcp-http --mode local --transport streamable-http \
  --copilot-compatible --host 127.0.0.1 --port 8765

# Public Copilot endpoint: authenticated service mode is mandatory
export PUBMED_AUTH_TOKENS="copilot:$(openssl rand -hex 32)"
export NGROK_DOMAIN="your-assigned-domain.ngrok.dev"
./scripts/start-copilot-studio.sh --with-ngrok

Copilot Studio Configuration

Field

Value

Server name

PubMed Search

Server URL

https://your-server.com/mcp

Authentication

Bearer token for service mode; None only for an unpublished local demo

📖 Full documentation: copilot-studio/README.md

Use pubmed-search-mcp-http --copilot-compatible for packaged Copilot HTTP semantics. run_server.py remains a source-tree development wrapper; run_copilot.py is a loopback-only smoke launcher for the same canonical 41-tool strict registry, not a second compatibility surface. The tunnel script requires an assigned NGROK_DOMAIN, refuses occupied backend ports, and publishes only after --mode service passes readiness and unauthenticated-rejection checks.

⚠️ Note: SSE transport deprecated since Aug 2025. Use streamable-http.


📖 More documentation:


🔐 Security

Security Features

Layer

Feature

Description

HTTPS

TLS termination

Required for remote credentials; the bundled self-signed profile is local-only

Bearer authentication

Stable principal

Mandatory in service mode and used for tenant authorization

Tenant storage

Filesystem isolation

Sessions, artifacts, exports, chronicles, and pipelines are stored below the authenticated principal

Fairness and rate policy

Tenant concurrency + shared upstream budgets

Prevents one caller from multiplying an upstream API allowance

Security headers

Clickjacking/MIME hardening

Reverse-proxy headers complement authentication; they are not CSRF authorization

Secret handling

Runtime secret injection

API keys and bearer tokens must come from deployment secrets/environment and must not be committed or logged

See DEPLOYMENT.md for detailed deployment instructions.


📤 Export Formats

Export and local notes workflow

Export your search results in formats compatible with major reference managers:

Format

Source

Compatible With

Use Case

RIS

official or local

EndNote, Zotero, Mendeley

Universal import

MEDLINE

official or local

PubMed tools

Native PubMed-style archiving

CSL JSON

official

Citation processors

Programmatic citation styling

BibTeX

local

LaTeX, Overleaf, JabRef

Academic writing

CSV

local

Excel, Google Sheets

Data analysis

JSON

local

Programmatic access

Custom processing

Exported Fields

  • Core: PMID, Title, Authors, Journal, Year, Volume, Issue, Pages

  • Identifiers: DOI, PMC ID, ISSN

  • Content: Abstract (HTML tags cleaned)

  • Metadata: Language, Publication Type, Keywords

  • Access: DOI URL, PMC URL, Full-text availability

Special Character Handling

  • BibTeX exports use pylatexenc for proper LaTeX encoding

  • Nordic characters (ø, æ, å), umlauts (ü, ö, ä), and accents are correctly converted

  • Example: Søren Hansen → S{\o}ren Hansen


📚 Citation

The publication workspace contains the rewritten manuscript, reviewed references, evidence map and local PDF/arXiv source build. It is a working draft without an arXiv identifier; cite the released software below. Author: Tz-Ping Gau, Kaohsiung Medical University Hospital.

GitHub will show Cite this repository from CITATION.cff. If you use PubMed Search MCP in research, methods sections, or internal technical reports, prefer the GitHub-generated citation or reuse the repository metadata directly.

@software{pubmed_search_mcp,
  title = {PubMed Search MCP},
  author = {Gau, Tz-Ping},
  version = {0.8.0},
  year = {2026},
  url = {https://github.com/u9401066/pubmed-search-mcp}
}

📄 License

Apache License 2.0 - see LICENSE


Available Tools

41 tools
analyze_search_queryA
Read-onlyIdempotent

Analyze a search query without executing the search.

Useful for understanding how unified_search will process your query before actually running it.

Args: query: The search query to analyze

Returns: Analysis including: - Complexity level (SIMPLE/MODERATE/COMPLEX/AMBIGUOUS) - Intent (LOOKUP/EXPLORATION/COMPARISON/SYSTEMATIC) - PICO elements (if detected) - Recommended sources - Recommended strategies

Inputs: query (required).

build_citation_treeA
Read-onlyIdempotent

Build a citation tree (network) from a single article.

🌳 Creates a visual citation network showing research lineage:

  • Forward (citing): Who cites this paper? (newer research)

  • Backward (references): What does this paper cite? (foundational work)

⚠️ IMPORTANT: Only accepts ONE PMID at a time to control API load. For multiple papers, call this tool separately for each.

📊 Output Formats (output_format parameter):

  • "cytoscape": Cytoscape.js format (default, academic standard)

  • "g6": AntV G6 format (modern, high-performance)

  • "d3": D3.js force graph format (flexible, Observable)

  • "vis": vis-network format (simple, quick prototypes)

  • "graphml": GraphML XML (desktop tools: Gephi, yEd, VOSviewer)

  • "mermaid": Mermaid diagram (VS Code preview, Markdown)

Args: pmid: Single PubMed ID (e.g., "12345678"). Only ONE PMID accepted - do NOT pass multiple. depth: How many levels to traverse (1-3, default 2). - depth=1: Direct citations/references only - depth=2: Also get citations of citations (recommended) - depth=3: Maximum depth (can be slow, ~100+ API calls) direction: Which direction to build the tree: - "forward": Only citing articles (who cites this) - "backward": Only references (what this cites) - "both": Both directions (default, recommended) limit_per_level: Max articles to fetch per node per level (default 5) output_format: Graph format for visualization (default "cytoscape") - "cytoscape": Cytoscape.js (academic standard, bioinformatics) - "g6": AntV G6 (modern, TypeScript, great for large graphs) - "d3": D3.js force layout (most flexible, Observable notebooks) - "vis": vis-network (simple and easy) - "graphml": GraphML XML (Gephi, VOSviewer, yEd, Pajek) - "mermaid": Mermaid diagram (preview in VS Code Markdown)

Returns: Markdown summary followed by JSON with graph data in the requested format. Includes metadata and statistics regardless of format.

Example usage: # Build 2-level tree for a paper (default Cytoscape.js format) build_citation_tree(pmid="33475315", depth=2, direction="both")

# Use AntV G6 format for modern web visualization
build_citation_tree(pmid="33475315", depth=2, output_format="g6")

# Export GraphML for Gephi analysis
build_citation_tree(pmid="33475315", depth=2, output_format="graphml")

Inputs: pmid (required), depth, direction, output_format, +1 more.

build_research_chronicleA

Build a persisted, versioned, evidence-backed Research Chronicle.

A chronicle is the durable record of how a research topic evolved, and the single entry point for research-evolution work (it replaces the older one-shot timeline tools). It is stored with a monotonic revision number, so re-running it later produces revision N+1 and you can diff revisions to see exactly what changed.

The primary axis is chronological; research branches are a secondary organizing dimension. Both come from the same stored snapshot, and preserve shared provenance in output="timeline" and output="tree". Agreement between projections is not independent evidence verification.

Every entry carries:

  • a one-sentence claim with inline citations

  • supporting / contradicting / updating evidence articles

  • a research branch (lineage) assignment

  • provenance and a confidence score

The typed provenance graph links Topic → Branch → Entry → EvidenceArticle and is validated against edge invariants. The audit reports evidence coverage, identifier coverage, branch coverage, graph integrity, and chronology gaps, so you always know how complete the picture is.

Args: topic: Research topic (drug, gene, disease, intervention). Required unless pmids or a stored chronicle_id is supplied. pmids: Delimited PMIDs, a string array or JSON array string, or "last" to chronicle the previous search results instead of running a new search. max_events: Maximum timeline events to consider (topic mode). Omit to inherit the continued revision's value, else 30. min_year: Earliest publication year to include (topic mode). max_year: Latest publication year to include (topic mode). chronicle_id: Continue an existing chronicle (creates revision N+1) instead of deriving the ID from the topic. Passing it alone re-runs the stored scope, so the resulting diff shows research movement rather than a changed window. output: "summary" (default compact Markdown with the chronological spine), "json", "chronicle_map", "timeline", "tree", "graph", "evidence", "milestones", "mermaid" (horizontal time spine with lineage branches), or "narrative". "json", "chronicle_map", "timeline", "tree", "graph", "evidence", and "milestones" return JSON; the rest return Markdown.

Returns: The requested rendering plus an artifact locator when durable artifact persistence is enabled and succeeds. The artifact contains the full snapshot, projections, evidence table, milestone analysis, and audit regardless of output. Artifact failure is reported but does not roll back the already saved Chronicle revision.

Examples: build_research_chronicle(topic="remimazolam") build_research_chronicle(pmids="last", topic="My Reading List") build_research_chronicle(topic="CAR-T therapy", output="mermaid") build_research_chronicle(chronicle_id="remimazolam-9f2b1c4d")

Inputs: pmids, topic, output, max_year, +3 more.

configure_institutional_accessA
DestructiveIdempotent

Configure your institution's link resolver for full-text access.

═══════════════════════════════════════════════════════════════════════════════ 🏛️ INSTITUTIONAL ACCESS CONFIGURATION ═══════════════════════════════════════════════════════════════════════════════

This tool configures OpenURL link resolver integration, allowing you to access paywalled articles through your institution's library subscription.

Remote service callers may call this tool with no configuration arguments to inspect the operator-installed configuration, but cannot mutate the server-owned, deployment-wide OpenURL settings. Configure those at deployment time or from a trusted local server instead.

═══════════════════════════════════════════════════════════════════════════════ HOW IT WORKS: ═══════════════════════════════════════════════════════════════════════════════

  1. Your library subscribes to journals through publishers

  2. Library provides a "Link Resolver" service (SFX, 360 Link, Primo, etc.)

  3. OpenURL passes article metadata to the resolver

  4. Resolver checks your subscriptions and provides full-text access

═══════════════════════════════════════════════════════════════════════════════ USAGE: ═══════════════════════════════════════════════════════════════════════════════

Option 1: Use a preset (easiest) ───────────────────────────────── configure_institutional_access(preset="ntu")

Available presets:

  • 台灣: "ntu" (台大), "ncku" (成大), "nthu" (清大), "nycu" (陽明交大)

  • 美國: "harvard", "stanford", "mit", "yale"

  • 英國: "oxford", "cambridge"

  • 通用: "sfx", "360link", "primo" (需要 resolver_url)

Option 2: Custom URL ───────────────────── configure_institutional_access( resolver_url="https://your.library.edu/openurl" )

Option 3: Disable ───────────────────── configure_institutional_access(enable=False)

═══════════════════════════════════════════════════════════════════════════════ FINDING YOUR RESOLVER URL: ═══════════════════════════════════════════════════════════════════════════════

  1. Go to your library's website

  2. Look for "Find Full Text", "Link Resolver", or "OpenURL"

  3. Or search: "[Your University] link resolver"

  4. The URL usually looks like:

Args: resolver_url: Your institution's link resolver URL preset: Use a known institution's preset configuration enable: Whether to enable OpenURL links (default: True) Returns: Configuration status message

Inputs: enable, preset, resolver_url.

convert_icd_meshA
Read-onlyIdempotent

Query the curated ICD/MeSH crosswalk in one explicit direction.

Use icd_to_mesh with one complete ICD-9-CM or ICD-10-CM code, or mesh_to_icd with a MeSH term. The returned mapping is a limited convenience crosswalk, not a substitute for a current licensed UMLS terminology service.

Inputs: value (required), direction (required).

delete_pipelineA
DestructiveIdempotent

Permanently delete a saved pipeline configuration and execution history.

For the default tenant, any process-level schedule is removed only after the stored pipeline deletion succeeds. Isolated tenants never mutate the shared process scheduler.

Args: name: Name of the saved pipeline to delete.

Returns: Confirmation of deletion.

Inputs: name (required).

diagnose_institutional_accessA
Read-onlyIdempotent

Diagnose why institutional fulltext access succeeds or fails for an article.

Runs up to three probes and reports each path's outcome:

  1. Direct fetch (Phase 1, IP-aware) — follows https://doi.org/<doi> and classifies whether the publisher served fulltext, a paywall, or a login page. Works automatically when your network IP is on the publisher's institutional allow-list (campus / VPN).

  2. EZproxy fetch (Phase 2, BYO-cookie) — rewrites the publisher hostname to your library's EZproxy host and replays your exported browser session cookie. Configured via env vars:

    • EZPROXY_HOST (e.g. ezproxy.lib.ntu.edu.tw)

    • EZPROXY_COOKIE_FILE (path to browser-exported cookies.json)

    • EZPROXY_ENABLED=1

  3. OpenURL handoff — generated for you to open manually in a browser when the automated paths fail.

Usage: diagnose_institutional_access( source={"kind": "doi", "value": "10.1097/ALN.0000000000003599"} )

diagnose_institutional_access(
    source={"kind": "pmid", "value": "38353755"},
    try_ezproxy=False
)

Args: source: Exactly one PMID or DOI. A PMID is resolved to a DOI when possible so direct and EZproxy probes can run. try_direct: Run the Phase 1 direct probe (default True). try_ezproxy: Run the Phase 2 EZproxy probe (default True).

Returns: Markdown report listing every probe's status, classification, and advice on the next action to take.

Inputs: source (required), try_direct, try_ezproxy.

fetch_article_detailsB
Read-onlyIdempotent

Fetch detailed information for one or more PubMed articles.

Args: pmids: PubMed IDs - accepts multiple formats: - "12345678" (single) - "12345678,87654321" (comma-separated) - "PMID:12345678" (with prefix) - ["12345678", "87654321"] (list) - '["12345678", "87654321"]' (JSON array string) - Newlines, semicolons, pipes, and Chinese separators are also accepted. Inputs are string-only and fail as a complete batch when any PMID is invalid.

Returns: Detailed information for each article.

Inputs: pmids (required), output_format.

find_citing_articlesA
Read-onlyIdempotent

Find articles that cite a given PubMed article. Uses PubMed Central's citation data to find papers that reference this article.

═══════════════════════════════════════════════════════════════ 📈 FORWARD CITATION SEARCH (Impact Tracking) ═══════════════════════════════════════════════════════════════

Direction: Source Paper → Papers that cite it (FORWARD in time)

USE CASES: ──────────

  • 🔬 Track research impact: Who built on this work?

  • 📊 Find follow-up studies: What happened after this discovery?

  • 🔄 Identify controversies: Papers that challenge or refute findings

  • 📚 Literature review: Ensure you have the latest developments

COMPLEMENTARY TOOLS: ────────────────────

  • get_article_references(): BACKWARD search (what this paper cited)

  • find_related_articles(): Similar papers (topic-based, not citation-based)

═══════════════════════════════════════════════════════════════ EXAMPLE: ═══════════════════════════════════════════════════════════════

Find papers that cite a landmark CRISPR paper

find_citing_articles(pmid="23287718", limit=20) → Returns papers published AFTER 2012 that reference this work

Then analyze citation metrics

get_citation_metrics(pmids="last") → See which citing papers are most influential

Args: pmid: PubMed ID of the source article ("12345678" or "PMID:12345678"). limit: Maximum number of citing articles to return (1-100, default: 10).

Returns: List of citing articles with details.

Inputs: pmid (required), limit.

generate_search_queriesA
Read-onlyIdempotent

Gather search intelligence for a topic - returns RAW MATERIALS for Agent to decide.

This tool provides the BUILDING BLOCKS for search, not finished queries. The Agent decides how to use them.

══════════════════════════════════════════════════════════════════════ TWO USAGE MODES: ══════════════════════════════════════════════════════════════════════

MODE 1: KEYWORD SEARCH (single topic) ───────────────────────────────────── User: "搜尋 remimazolam 的文獻"

Step 1: generate_search_queries("remimazolam") Step 2: Build a Boolean query from returned materials Step 3: analyze_search_query(query="<combined_boolean_query>") Step 4: unified_search(query="<combined_boolean_query>")

══════════════════════════════════════════════════════════════════════

MODE 2: PICO SEARCH (clinical question) ─────────────────────────────────────── User: "remimazolam 在 ICU 鎮靜比 propofol 好嗎?會減少 delirium 嗎?"

Step 1: Agent extracts P/I/C/O from the clinical question, then calls validate_pico_plan(description=..., p=..., i=..., c=..., o=...) to validate the structured handoff and get a runnable PICO pipeline.

Step 2: For EACH PICO element, call generate_search_queries() IN PARALLEL: - generate_search_queries("ICU patients") → P materials - generate_search_queries("remimazolam") → I materials - generate_search_queries("propofol") → C materials - generate_search_queries("delirium") → O materials

Step 3: Combine materials using Boolean logic: High precision: (P_terms) AND (I_terms) AND (C_terms) AND (O_terms) Recall-oriented: (P_terms) AND (I_terms OR C_terms); validate against eligible seed papers

Step 4: Add Clinical Query filter if appropriate: - filters="clinical_query:therapy" → 治療效果比較 - filters="clinical_query:diagnosis" → 診斷相關 - filters="clinical_query:prognosis" → 預後相關 - filters="clinical_query:etiology" → 病因相關

Step 5: Validate the final query with analyze_search_query()
Step 6: Execute unified_search() with the final Boolean query

══════════════════════════════════════════════════════════════════════

Features:

  • Spelling correction via NCBI ESpell

  • MeSH term lookup for standardized vocabulary

  • Synonym expansion from MeSH database

  • Query analysis: Shows how PubMed actually interprets each query (Agent's understanding vs PubMed's actual interpretation)

Args: topic: Search topic - can be a single keyword or PICO element strategy: Affects suggested_queries (if included) - "comprehensive": Multiple angles, includes reviews (default) - "focused": Adds RCT publication-type filter; study quality still requires appraisal - "exploratory": Broader search with more synonyms check_spelling: Whether to check/correct spelling (default: True) include_suggestions: Include pre-built query suggestions (default: True)

Returns: JSON with RAW MATERIALS: - corrected_topic: Spell-checked topic - keywords: Extracted significant keywords - mesh_terms: MeSH data with preferred terms and synonyms - all_synonyms: Flattened list of all synonyms - suggested_queries: Optional pre-built queries with: - estimated_count: How many results PubMed would return - pubmed_translation: How PubMed actually interprets the query

Inputs: topic (required), strategy, check_spelling, include_suggestions.

get_article_figuresA
Read-onlyIdempotent

Get structured figure metadata (label, caption, image URL) and PDF links from a PMC Open Access article.

Returns all figures with their captions and direct image URLs, plus PDF download links for the complete article.

source is a discriminated identifier object, so the schema itself requires exactly one explicit PMID or PMCID.

Args: source: {"kind":"pmcid","value":"PMC12086443"} or {"kind":"pmid","value":"40384072"}. include_subfigures: Parse sub-figures (e.g., Figure 3A, 3B) as separate entries. include_tables: Also extract tables rendered as images.

Returns: Structured figure data with image URLs, captions, and PDF links.

Example: get_article_figures(source={"kind":"pmcid","value":"PMC12086443"})

Inputs: source (required), output_format, include_tables, include_subfigures.

get_article_referencesA
Read-onlyIdempotent

Get the references (bibliography) of a PubMed article.

Returns the list of articles that this paper cites in its bibliography. This is the OPPOSITE of find_citing_articles:

  • get_article_references: Papers THIS article cites (backward in time)

  • find_citing_articles: Papers that cite THIS article (forward in time)

═══════════════════════════════════════════════════════════════ 📚 BACKWARD CITATION SEARCH (Foundation Discovery) ═══════════════════════════════════════════════════════════════

Direction: Source Paper → Papers it cited (BACKWARD in time)

USE CASES: ──────────

  • 🏛️ Find foundational papers: Core works the field builds on

  • ⚗️ Methodology sources: Papers describing techniques used

  • 📖 Background reading: Build understanding of a topic

  • 🔍 Verify claims: Check sources for specific assertions

═══════════════════════════════════════════════════════════════ EXAMPLE WORKFLOW: ═══════════════════════════════════════════════════════════════

Start with a recent review article

get_article_references(pmid="38123456", limit=50) → Get the bibliography of this review

Find most-cited foundational papers

get_citation_metrics(pmids="last", sort_by="citation_count") → Identify which references are the most influential

Read a foundational paper

fetch_article_details(pmids="12345678") → Get full details of an important reference

Args: pmid: PubMed ID of the source article ("12345678" or "PMID:12345678"). limit: Maximum number of references to return (1-100, default: 20).

Returns: List of referenced articles with details.

Inputs: pmid (required), limit.

get_citation_metricsA
Read-onlyIdempotent

Get citation metrics from NIH iCite for articles.

Returns field-normalized citation data including:

  • citation_count: Total number of citations

  • relative_citation_ratio (RCR): Field-normalized metric (1.0 = average)

  • nih_percentile: Percentile ranking (0-100)

  • citations_per_year: Citation velocity

  • apt: Approximate Potential to Translate (clinical relevance 0-1)

Can sort and filter results by citation metrics.

Args: pmids: PubMed IDs - accepts multiple formats: - "12345678,87654321" (comma-separated) - ["12345678", "87654321"] (list) - '["12345678", "87654321"]' (JSON array string) - "PMID:12345678" (with prefix) - "last" to use PMIDs from the last search Batches are fail-closed and limited to 1,000 items before deduplication. sort_by: Metric to sort by: - "citation_count": Raw citation count (default) - "relative_citation_ratio": Field-normalized (recommended) - "nih_percentile": Percentile ranking - "citations_per_year": Citation velocity min_citations: Filter out articles with fewer citations min_rcr: Filter out articles with RCR below threshold (e.g., 1.0 = average) min_percentile: Filter out articles below percentile (e.g., 50 = top half)

Returns: Articles with citation metrics, sorted and filtered as requested. iCite transport or response failures return an explicit retryable error and are never rendered as an empty/unindexed result.

Inputs: pmids (required), min_rcr, sort_by, min_citations, +2 more.

get_compound_detailsB
Read-onlyIdempotent

Get detailed information about a compound by PubChem CID.

Args: cid: PubChem Compound ID

Returns: JSON with compound details including formula, SMILES, properties

Inputs: cid (required).

get_compound_literatureA
Read-onlyIdempotent

Get PubMed articles linked to a compound.

Uses NCBI's curated compound-to-publication links.

Args: cid: PubChem Compound ID limit: Maximum PubMed IDs to return (1-100)

Returns: JSON with linked PubMed IDs

Inputs: cid (required), limit.

get_fulltextA

🔥 Enhanced multi-source fulltext retrieval.

Automatically tries multiple sources to find the best fulltext:

  1. Europe PMC (if PMC ID available)

  2. Unpaywall (finds OA versions via DOI)

  3. Institutional direct/EZproxy fetch (when DOI-backed and enabled)

  4. CORE (open-access repository metadata and available text)

With extended_sources=True, also searches: 5. CrossRef (publisher links) 6. DOAJ (Gold OA journals) 7. Zenodo (research repository) 8. PubMed LinkOut (external providers) 9. Semantic Scholar, OpenAlex, arXiv, bioRxiv, medRxiv

source is a discriminated identifier object, so the schema itself requires exactly one explicit PMID, PMCID, or DOI kind.

Args: source: One object such as {"kind":"pmid","value":"12345678"}, {"kind":"pmcid","value":"PMC7096777"}, or {"kind":"doi","value":"10.1001/jama.2024.1234"}. sections: Filter body sections (e.g., "introduction,methods,results"). Missing titles are reported with available sections; abstracts are never substituted for missing body evidence. include_pdf_links: Include PDF download links (default: True). False skips link enrichment when structured fulltext is already available. include_figures: Include figure metadata with image URLs (default: False) extended_sources: Search the extended downloader chain after the standard policy (default: False) output_format: Response format - "markdown" (default), "json", or "toon" allow_browser_session: Control browser-session fallback. - True: force broker fallback when configured - False: disable broker fallback - None: use auto mode from broker configuration

Returns: Fulltext content with PDF links from all available sources.

Example: get_fulltext(source={"kind":"pmcid","value":"PMC7096777"}) get_fulltext(source={"kind":"doi","value":"10.1038/s41586-021-03819-2"})

Inputs: source (required), sections, output_format, include_figures, +3 more.

get_gene_detailsA
Read-onlyIdempotent

Get detailed information about a gene by NCBI Gene ID.

Args: gene_id: NCBI Gene ID (from search results or known)

Returns: JSON with gene details including symbol, name, summary, location

Inputs: gene_id (required).

get_gene_literatureA
Read-onlyIdempotent

Get PubMed articles linked to a gene.

This uses NCBI's curated gene-to-publication links, which are more precise than keyword searches.

Args: gene_id: NCBI Gene ID limit: Maximum PubMed IDs to return (1-100)

Returns: JSON with linked PubMed IDs

Inputs: gene_id (required), limit.

get_pipeline_historyA
Read-onlyIdempotent

Get execution history for a saved pipeline.

Shows past execution results with diff analysis: which articles are new compared to the previous run.

Args: name: Name of the saved pipeline. limit: Maximum number of history entries to return (default: 5).

Returns: Execution history with date, article count, new/removed articles, status.

Inputs: name (required), limit.

get_text_mined_termsB
Read-onlyIdempotent

Get text-mined annotations from Europe PMC.

Returns entities extracted from the article text including genes, diseases, chemicals, organisms, and more. source is exactly one PMID or PMCID.

Args: source: {"kind":"pmid","value":"12345678"} or {"kind":"pmcid","value":"PMC7096777"}. semantic_type: Filter by entity type. Options: - "GENE_PROTEIN": Genes and proteins - "DISEASE": Diseases and conditions - "CHEMICAL": Drugs and chemicals - "ORGANISM": Species and organisms - "GO_TERM": Gene Ontology terms - None: Return all types (default)

Returns: List of text-mined entities with counts and sections.

Inputs: source (required), output_format, semantic_type.

list_pipelinesA
Read-onlyIdempotent

List all saved pipeline configurations.

Args: tag: Filter by tag (e.g., "sedation"). Empty = show all. scope: Filter by scope: "workspace", "global", or "" (show all).

Returns: Table of saved pipelines with name, scope, description, tags.

Inputs: tag, scope.

list_resolver_presetsA
Read-onlyIdempotent

List available institutional link resolver presets.

═══════════════════════════════════════════════════════════════════════════════ 📚 AVAILABLE RESOLVER PRESETS ═══════════════════════════════════════════════════════════════════════════════

These presets contain pre-configured URLs for common institutions. Use them with configure_institutional_access(preset="name").

Returns: List of available presets with URLs

Inputs: no named parameters.

load_pipelineA
Read-onlyIdempotent

Load a pipeline configuration for review or editing.

Loads from either source:

  • Saved name: "weekly_remimazolam" or "saved:weekly_remimazolam"

  • Local-only file: "file:path/to/pipeline.yaml" (disabled for authenticated service callers)

The returned YAML can be reviewed, modified, and then:

  • Executed directly: unified_search(pipeline="")

  • Saved with changes: save_pipeline(name="...", config="")

Args: source: Pipeline source identifier (see above).

Returns: Full pipeline YAML content + metadata.

Inputs: source (required).

prepare_exportA

Export citations to reference manager formats.

╔═══════════════════════════════════════════════════════════════════╗ ║ RECOMMENDED: Use source="official" (default) for best quality ║ ╚═══════════════════════════════════════════════════════════════════╝

When to Use

  • Exporting references to EndNote, Zotero, Mendeley

  • Creating BibTeX for LaTeX documents

  • Generating citation lists for manuscripts

Source Options

Source

Formats

Quality

Speed

official

ris, medline, csl

★★★★★

Fast

local

ris, bibtex, csv, medline, json

★★★★

Fast

Format Selection Guide

  • ris: EndNote, Zotero, Mendeley (official recommended)

  • medline: NBIB format for PubMed tools

  • csl: JSON for programmatic citation styling

  • bibtex: LaTeX documents (local only)

  • csv: Data analysis, Excel (local only)

Args: pmids: Articles to export. Accepts: - "last" → results from previous search - "12345678,87654321" → comma-separated PMIDs - ["12345678", "87654321"] → list of PMIDs - '["12345678", "87654321"]' → JSON array string - "PMID:12345678" → with prefix format: Export format (default: "ris") - official API: ris, medline, csl - local only: bibtex, csv, json include_abstract: Include abstracts in output (default: True). False requires source="local"; official payloads are returned unmodified. source: Citation source (default: "official") - "official": NCBI Citation API (recommended, best quality) - "local": Local formatting (more formats, offline capable)

Returns: JSON with status and export_text containing formatted citations.

Examples: # Export last search results (recommended) prepare_export(pmids="last", format="ris")

# Export specific PMIDs to BibTeX
prepare_export(pmids="12345678,87654321", format="bibtex", source="local")

# Get CSL-JSON for programmatic use
prepare_export(pmids="last", format="csl", source="official")

Inputs: pmids (required), format, source, include_abstract.

read_research_chronicleA
Read-onlyIdempotent

Read stored Research Chronicles: load, list, diff, narrate, analyze, compare.

This is the read facade over chronicles created by build_research_chronicle. Chronicles persist across sessions, so you can revisit a topic weeks later and see precisely what moved. Because the evidence is already stored, analysis and comparison are instant and do not re-run any search.

Actions:

  • "load": read one revision (defaults to latest) in any output format

  • "list": list stored chronicles, most recently updated first

  • "diff": compare two revisions — added, not observed/removed from the later view, and updated entries, plus evidence churn, branch churn, and the audit status transition. Absence does not prove retirement.

  • "narrate": render evidence-backed Markdown where every claim carries its entry ID and article identifiers

  • "milestones": entry-type and status distribution, per-year activity, evidence quality, and landmark entries for one chronicle

  • "compare": compare 2-5 chronicles side by side, including the evidence articles they share

The required request discriminator makes invalid field combinations unrepresentable. compare takes one typed selection containing either 2-5 topic strings or 2-5 Chronicle IDs.

Returns: Markdown or JSON text depending on the action and output format.

Examples: read_research_chronicle(request={"action":"list"}) read_research_chronicle(request={"action":"load","chronicle_id":"remimazolam-9f2b1c4d","output":"tree"}) read_research_chronicle(request={"action":"diff","chronicle_id":"remimazolam-9f2b1c4d","from_revision":1}) read_research_chronicle(request={"action":"narrate","chronicle_id":"remimazolam-9f2b1c4d","mode":"full"}) read_research_chronicle(request={"action":"milestones","chronicle_id":"remimazolam-9f2b1c4d"}) read_research_chronicle(request={"action":"compare","selection":{"kind":"topics","values":["remimazolam","propofol"]}})

Inputs: request (required).

read_sessionA
Read-onlyIdempotent

Read session data through one schema-exact discriminated request.

Actions:

  • pmids: return PMIDs for one recorded search

  • article: return one cached article payload

  • summary: return current session summary and optional history

  • list_artifacts: list persistent MCP output artifact manifests

  • artifact: read one persistent artifact by artifact_id or artifact_uri

  • search_runs: list durable unified_search run envelopes

  • search_run: read one run by stable run_id

  • replay_search: return credential-free unified_search replay arguments

Each action accepts only its own fields. For remote artifact reads, select an artifact_id or artifact_uri locator and use artifact_file plus offset/max_chars to page through large files. Local paths remain redacted unless both include_local_paths and the server setting allow them.

Inputs: request (required).

save_literature_notesA
Destructive

Save searched articles as guided local wiki/Foam/Markdown notes.

When to Use

  • After unified_search, persist the selected literature into a local note library.

  • Give agents a structured alternative to generic write_file calls.

  • Create wiki notes with Foam-compatible wikilinks, MedPaper-like reference notes, and frontmatter.

  • Use stable wiki/Foam link targets and return wiki_validation for unresolved-link checks.

Local Directory Resolution

  1. output_dir argument, if provided

  2. PUBMED_NOTES_DIR environment variable

  3. PUBMED_WORKSPACE_DIR/references

  4. PUBMED_DATA_DIR/references

Authenticated Service Boundary

Remote authenticated callers cannot choose output_dir or template_file. Their notes always go to references/ under the current tenant's installed SessionManager data root; process-wide notes/workspace environment paths are intentionally ignored.

Args: pmids: Articles to save. Accepts "last", delimited PMID text, a string array, or a JSON array string. output_dir: Optional target folder for notes. note_format: "wiki" (default, Foam-compatible), "foam", "markdown", or "medpaper". include_abstract: Include abstracts in article notes. overwrite: Overwrite existing per-article notes when filenames collide. create_index: Create a collection index note linking saved articles. collection_name: Optional title/file stem for the index note. template_file: Optional Markdown template with placeholders like {title}, {pmid}, {citation_key}. include_csl_json: Write references.csl.json beside notes for citation-manager handoff.

Returns: JSON with written/skipped files, index information, and wiki_validation. Local callers receive filesystem paths. Authenticated callers receive tenant-relative logical locators and never receive server host paths.

Examples: save_literature_notes(pmids="last") save_literature_notes(pmids="last", note_format="medpaper", output_dir="./references") save_literature_notes(pmids="12345678,87654321", template_file="./ref-template.md")

Inputs: pmids, overwrite, output_dir, note_format, +5 more.

save_pipelineA
Destructive

Save a pipeline configuration for later reuse.

The config format is identical to unified_search's pipeline parameter (YAML or JSON). Saved pipelines can be loaded later by name: unified_search(pipeline="saved:weekly_remimazolam")

Args: name: Unique identifier (alphanumeric + hyphens/underscores, max 64 chars). Overwrites if name already exists (upsert semantics). config: Pipeline YAML/JSON string. Same format as unified_search pipeline param. tags: Bounded array of canonical tags (e.g., ["anesthesia", "sedation"]). description: Human-readable description of the pipeline's purpose. scope: Storage scope - "workspace" (project-level, git-trackable), "global" (user-level, cross-project), or "auto" (workspace if available, otherwise global). Default: "auto".

Returns: Confirmation with pipeline metadata.

Inputs: name (required), config (required), tags, scope, +1 more.

schedule_pipelineB
Destructive

Schedule a saved pipeline for periodic execution.

Args: name: Saved pipeline name. cron: Required 5-field cron expression. Example: "0 9 * * 1" (Mon 9am). diff_mode: When True, store diff-mode preference with the schedule. notify: When True, store notify preference with the schedule.

Returns: Schedule confirmation or removal result.

Inputs: cron (required), name (required), notify, diff_mode.

search_biomedical_imagesA
Read-onlyIdempotent

🖼️ Search biomedical images from NLM Open-i.

Searches medical/scientific images from Open-i and returns image URLs with metadata (caption, article info, MeSH terms).

═══════════════════════════════════════════════════════════════ ⚠️ CRITICAL - LANGUAGE REQUIREMENT: ═══════════════════════════════════════════════════════════ Open-i ONLY supports English queries. If the user queries in non-English (Chinese, Japanese, Korean, etc.), you MUST:

  1. Translate the query to English medical terminology first

  2. Then call this tool with the English query Example: "喉頭水腫" → "laryngeal edema" "胸部X光肺炎" → "chest X-ray pneumonia"

The tool has built-in translation hints for common CJK medical terms, but YOU should always verify the translation is correct.

═══════════════════════════════════════════════════════════ SOURCES: ═══════════════════════════════════════════════════════════════

  • Open-i (NLM): X-ray, microscopy, clinical images

═══════════════════════════════════════════════════════════════ EXAMPLES: ═══════════════════════════════════════════════════════════════

General image search: search_biomedical_images("chest pneumonia CT scan")

X-ray only: search_biomedical_images("fracture", image_type="x")

Microscopy images: search_biomedical_images("histology liver", image_type="mc")

Clinical teaching images (MedPix): search_biomedical_images("pneumothorax", collection="mpx")

Case reports with CC-BY license, sorted by date: search_biomedical_images( "lung cancer", article_type="cr", license_type="by", sort_by="d" )

Cardiology specialty images: search_biomedical_images("echocardiogram", specialty="c")

Video content only: search_biomedical_images("surgery technique", video_only=True)

═══════════════════════════════════════════════════════════════

Args: query: Search query (e.g., "chest X-ray pneumonia") image_type: Filter by image type (Open-i only): Positive filters: - "c": CT scan images - "g": Graphics / line art / diagrams - "m": MRI images - "mc": Microscopy / histology images - "p": PET scan images - "ph": Photographs / clinical photos - "u": Ultrasound images - "x": X-ray images Exclusion filters: - "xg": Exclude Graphics (removes graphic images from results) - "xm": Exclude Multipanel (removes multipanel images) - None: All types (default) collection: Filter by collection (Open-i only): - "pmc": PubMed Central articles - "mpx": MedPix clinical teaching images (high quality) - "cxr": Chest X-ray collection - "hmd": History of Medicine - "usc": USC collection - None: All collections (default) limit: Maximum number of images to return (default 10, max 50) sort_by: Sort results by (Open-i only): - "r": Relevance (default) - "d": Date (newest first) - "o": Oldest first - "t": Title - "e": Education relevance - "g": Graphics priority article_type: Filter by article type (Open-i only): - "cr": Case Report - "or": Original Research - "re": Review - "sr": Systematic Review - "ra": Research Article - "ed": Editorial - "lt": Letter - "bk": Book - and more... (see API docs) specialty: Filter by medical specialty (Open-i only): - "r": Radiology - "c": Cardiology - "ne": Neurology - "pu": Pulmonology - "d": Dermatology - "g": Gastroenterology - "or": Orthopedics - "o": Ophthalmology - "s": Surgery - "p": Pediatrics - "id": Infectious Disease - "i": Immunology - and more... (see API docs) license_type: Filter by Creative Commons license (Open-i only): - "by": CC-BY (Attribution) - "bync": CC-BY-NC (Attribution-NonCommercial) - "byncnd": CC-BY-NC-ND (Attribution-NonCommercial-NoDerivs) - "byncsa": CC-BY-NC-SA (Attribution-NonCommercial-ShareAlike) subset: Filter by subject subset (Open-i only): - "b": Behavioral Sciences - "c": Cancer - "e": Ethics - "s": Surgery - "x": Toxicology search_fields: Search in specific fields (Open-i only): - "t": Title only - "m": MeSH terms only - "ab": Abstract only - "msh": MeSH heading only - "c": Caption only - "a": Author only video_only: If True, only return video content (default False) hmp_type: History of Medicine publication type. Requires collection="hmd".

Returns: Formatted image results with URLs, captions, and article metadata

Inputs: query (required), limit, subset, sort_by, +8 more.

search_clinvarA
Read-onlyIdempotent

Search ClinVar for clinical variants.

═══════════════════════════════════════════════════════════════ USE CASES: ═══════════════════════════════════════════════════════════════

  • Look up clinical significance of genetic variants

  • Find variants associated with diseases

  • Research gene-disease associations

  • Get variant pathogenicity classifications

Args: query: Gene name, variant, or disease condition limit: Maximum results (1-50)

Returns: JSON with variant records including significance and conditions

Inputs: query (required), limit.

search_compoundB
Read-onlyIdempotent

Search PubChem for chemical compounds.

═══════════════════════════════════════════════════════════════ USE CASES: ═══════════════════════════════════════════════════════════════

  • Look up drug/compound information

  • Find molecular formula and structure

  • Get compound synonyms and identifiers

  • Research chemical properties

Args: query: Compound name or description limit: Maximum results (1-50)

Returns: JSON with compound records including names, formulas, properties

Inputs: query (required), limit.

search_geneA
Read-onlyIdempotent

Search NCBI Gene database for gene information.

═══════════════════════════════════════════════════════════════ USE CASES: ═══════════════════════════════════════════════════════════════

  • Look up gene function and description

  • Find gene aliases and official symbols

  • Get chromosome location

  • Find genes by name or function

Args: query: Gene name, symbol, or function keyword organism: Filter by organism (e.g., "human", "Homo sapiens", "mouse") limit: Maximum results (1-50)

Returns: JSON with gene records including symbols, names, locations

Inputs: query (required), limit, organism.

test_institutional_accessA
Read-onlyIdempotent

Test your institutional link resolver configuration.

═══════════════════════════════════════════════════════════════════════════════ 🧪 TEST INSTITUTIONAL ACCESS ═══════════════════════════════════════════════════════════════════════════════

Tests if your configured link resolver is:

  1. Properly configured

  2. Reachable (network connection)

  3. Returns a valid response

NOTE: This only tests if the resolver endpoint is reachable. Actual full-text access depends on your institution's subscriptions.

═══════════════════════════════════════════════════════════════════════════════ FREE TEST OPTIONS: ═══════════════════════════════════════════════════════════════════════════════

If you don't have institutional access, you can test with:

  1. Use "test_free" preset (EBSCO public resolver): configure_institutional_access(preset="test_free") test_institutional_access()

  2. Most university resolvers will respond even without VPN, they just won't provide full-text (shows "Access options" page)

Args: pmid: PMID to use for testing (default: 38353755)

Returns: Test results including: - Configuration status - Network reachability - Generated OpenURL - Link to test manually

Inputs: pmid.

unschedule_pipelineA
DestructiveIdempotent

Remove the active schedule for a saved pipeline.

Args: name: Saved pipeline name whose schedule will be removed.

Returns: Removed schedule metadata, or a native MCP error when none exists.

Inputs: name (required).

validate_pico_planA
Read-onlyIdempotent

Validate agent-provided P/I/C/O and return a runnable PICO pipeline.

question_type and profile are closed enums. sources is an explicit array of supported unified-search providers; malformed values fail instead of being silently replaced. When question_type is omitted, the application service infers it from the clinical question.

Inputs: c, i, o, p, +9 more.

verify_reference_listA
Read-onlyIdempotent

Verify a plain-text reference list against PubMed evidence.

First version scope: - Reference-list verification only - Client supplies the extracted reference list text - Backend parses entries and resolves them via PMID / DOI / ECitMatch

Second version scope: - Adds unresolved review workflow for partial_match and unresolved rows - Returns a manual-review queue with retry queries and review checklist - Supports human-in-the-loop acceptance/rejection in client-side workflows

Args: reference_text: Plain-text references, ideally one per line or a numbered reference list extracted from a file. Limited to 200,000 characters / 400,000 UTF-8 bytes; each entry is limited to 4,000 characters / 8,000 UTF-8 bytes. source_name: Optional single-line file label for reporting (up to 255 characters / 512 UTF-8 bytes). max_references: Hard input-entry limit from 1 through 200. Inputs above the selected limit are rejected instead of truncated.

Returns: JSON verification report with parsed fields, matched PubMed evidence, per-reference verification status, and explicit source_unavailable / not_checked rows when evidence could not be assessed.

Inputs: reference_text (required), source_name, max_references.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 41 tools

    Disambiguation4/5

    Most tools target a distinct resource+action, and the descriptions actively disambiguate the riskiest clusters (find_related_articles vs find_citing_articles vs get_article_references, and fulltext vs details vs figures vs text-mined terms). Residual overlap exists in the institutional-access cluster (test_institutional_access vs diagnose_institutional_access vs get_institutional_link) and between build_citation_tree and the single-hop citation tools, but an agent can still pick correctly from the docs.

    Naming Consistency4/5

    Nearly all 41 tools use snake_case verb_noun (get_fulltext, search_gene, build_citation_tree, list_pipelines, unschedule_pipeline), which makes the surface predictable and groupable. The only real deviation is unified_search (adjective_noun, no verb), plus the mildly inconsistent use of fetch_/get_ for article details.

    Tool Count3/5

    The domain is genuinely broad (literature search, citation networks, gene/compound/ClinVar lookups, images, fulltext, export, notes, pipelines, institutional access, sessions), so a large surface is defensible. Still, 41 tools is heavy, and several clusters are inflated — 7 pipeline-lifecycle tools and 5 institutional-access tools — pushing well past the comfortable 3-15 range.

    Completeness4/5

    Coverage is unusually thorough: end-to-end search with query/PICO planning, citation graph traversal, metrics, fulltext and figures, export, and even pipeline scheduling plus persistent research chronicles with diffs. Gaps are minor — notes can only be saved (no read/list/delete counterpart), and there is no direct author/journal browse beyond unified_search.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      An MCP server that enables coding agents to search academic papers, ingest full-text PDFs, extract structured details, and manage citations in literature research workflows.
      33
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      AI-powered research assistant MCP server for searching academic papers and answering research questions with DOI citations.
      3
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      An advanced scholarly research MCP server that enables AI assistants to discover, fetch, process, and manage academic papers across multiple sources like arXiv, PubMed, and Semantic Scholar, with capabilities for summarization, citation analysis, and concept relationship extraction.
      2
      -