PubMed Search

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.

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 [email protected] 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

  bash

  # macOS / Linuxcurl -LsSf https://astral.sh/uv/install.sh | sh# Windowspowershell -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 dependencyuv add pubmed-search-mcp
# Option 3: pip installpip 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="[email protected]")) 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

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": "[email protected]"      }    }  }}

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": "[email protected]",        "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-brokeruv run playwright install chromiumuv 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": "[email protected]"      }    }  }}

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": "[email protected]"      }    }  }}

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": "[email protected]"      }    }  }}

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": "[email protected]"              }            }          ]        }      }    }  }}

Restart the gateway after configuration:

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

Cline (cline_mcp_settings.json)

{  "mcpServers": {    "pubmed-search": {      "command": "uvx",      "args": ["pubmed-search-mcp"],      "env": {        "NCBI_EMAIL": "[email protected]",        "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:

# Commanduvx pubmed-search-mcp
# With environment variable[email protected] 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:

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

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

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

Environment Variables

# Required[email protected]          # Required by NCBI policy
# Optional - For higher rate limitsNCBI_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[email protected]      # Optional override; defaults to server/NCBI email[email protected]     # Optional override; defaults to server/NCBI emailSEMANTIC_SCHOLAR_API_KEY=your_semantic_scholar_key # https://www.semanticscholar.org/product/apiOPENALEX_API_KEY=your_openalex_key # Raises the OpenAlex credit budget; actual grant is response-drivenPUBMED_SEARCH_DISABLED_SOURCES=    # Example: semantic_scholar
# Optional - Pipeline run-wide safety budgetsPUBMED_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 settingsHTTP_PROXY=http://proxy:8080       # HTTP proxy for API requestsHTTPS_PROXY=https://proxy:8080     # HTTPS proxy for API requests
# Optional - Institutional fulltext accessINSTITUTIONAL_DIRECT_FETCH=true    # Try DOI publisher pages before CORE fallbackEZPROXY_ENABLED=false              # Enable only after configuring EZPROXY_HOST + cookieEZPROXY_HOST=ezproxy.example.eduEZPROXY_COOKIE_FILE=/path/to/cookies.json
# Optional - Local note exportPUBMED_NOTES_DIR=/path/to/wiki/references  # save_literature_notes target folderPUBMED_WORKSPACE_DIR=/path/to/project       # fallback: references/ under this workspacePUBMED_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 sourcesunified_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 selectedunified_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]

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]

🕰️ Research Chronicle & Lineage Tree

[Research Chronicle Architecture and Lineage Flow] [Evaluation and timeline workflow]

# 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 comparisonread_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]

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]

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.

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:

• English: docs/guides/PIPELINE_MODE_TUTORIAL.en.md
• 繁體中文: docs/guides/PIPELINE_MODE_TUTORIAL.md

👁️ Vision & Image Search

[Full text, figures, and biomedical image workflow]

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.”

📄 Preprint Search

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:

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 everythingunified_search(query="remimazolam ICU sedation", limit=20)
# Or with clinical codes - auto-converted to MeSHunified_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 metadataunified_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 handoffpico = 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")   # Pgenerate_search_queries(topic="remimazolam")    # Igenerate_search_queries(topic="propofol")       # Cgenerate_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: 33475315find_related_articles(pmid="33475315")   # Similar methodologyfind_citing_articles(pmid="33475315")    # Who built on this?get_article_references(pmid="33475315")  # What's the foundation?
# Build complete research mapbuild_citation_tree(pmid="33475315", depth=2, output_format="mermaid")

4️⃣ Gene/Drug Research

# Research a genesearch_gene(query="BRCA1", organism="human")get_gene_literature(gene_id="672", limit=20)
# Research a drug compoundsearch_compound(query="propofol")get_compound_literature(cid="4943", limit=20)

5️⃣ Export Results

# Export last search resultsprepare_export(pmids="last", format="ris")      # → EndNote/Zoteroprepare_export(pmids="last", format="bibtex", source="local")  # → LaTeXprepare_export(pmids="last", format="csl")      # → CSL JSON from the official NCBI Citation APIsave_literature_notes(pmids="last")              # → local wiki note + Foam-compatible wikilinks + CSL JSONsave_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 searchget_fulltext(source={"kind":"pmid","value":"12345678"}, extended_sources=True)

6️⃣ Preprint Search

# Search preprint sources alongside the regular scholarly-source setunified_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 crawlunified_search(query="CRISPR gene therapy", options="include_detected_preprints")
# Default heuristic policyunified_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 facadesave_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 pipelinesave_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 pipelineunified_search(pipeline="saved:icu_sedation_weekly")
# List & managelist_pipelines(tag="anesthesia")load_pipeline(source="brca1_comprehensive")  # Review YAMLget_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                      ││                                                                          │└─────────────────────────────────────────────────────────────────────────┘

🤖 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

🔧 Development Skills (15) — For Project Contributors

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

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:

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 terminologyunified_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 deploymentcurl -k https://localhost/

HTTPS Endpoints

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 modepubmed-search-mcp-http --mode local --transport streamable-http \  --copilot-compatible --host 127.0.0.1 --port 8765
# Public Copilot endpoint: authenticated service mode is mandatoryexport 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

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

• Architecture → ARCHITECTURE.md
• Pipeline tutorial (English) → docs/guides/PIPELINE_MODE_TUTORIAL.en.md
• Pipeline tutorial (zh-TW) → docs/guides/PIPELINE_MODE_TUTORIAL.md
• Deployment guide → DEPLOYMENT.md
• Copilot Studio → copilot-studio/README.md

🔐 Security

Security Features

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:

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

🔗 Links

• GitHub Repository
• PyPI Package
• NCBI Entrez Programming Utilities