PubMed Search MCP

Professioneller Literatur-Rechercheassistent für KI-Agenten - Mehr als nur ein API-Wrapper

Ein auf Domain-Driven Design (DDD) basierender MCP-Server, der als intelligenter Rechercheassistent für KI-Agenten dient und aufgabenorientierte Literatursuche und -analyse bereitstellt.

✨ Was ist enthalten:

• 🔧 45 MCP-Tools - Optimierter Zugriff auf PubMed-, Europe PMC-, CORE- und NCBI-Datenbanken sowie Research Chronicle / Context Graph

• 🛡️ Multi-Agent-Dienstmodus - Einmal bereitstellen und viele Agenten bedienen: mandantenbezogene Sitzungen, Caches und Artefakte, Bearer-Token-Authentifizierung und mandantenbezogene Fair-Share-Limits. Siehe DEPLOYMENT.md

• 🖼️ OA-Abbildungsextraktion - Abbildungslegenden, direkte Bild-URLs und PDF-Links aus PMC-Open-Access-Artikeln abrufen

• 📘 Dokumentationsseite - Durchsuchen Sie das vollständige, sprachumschaltbare Handbuch: Benutzer-Workflows, Architektur, Referenz der 45 Tools, Pipeline-Tutorials, Quell-/Broker-Verträge, Integrationen und Betrieb, Sicherheit und Bereitstellung unter u9401066.github.io/pubmed-search-mcp

• 📖 GitHub-Wiki - GitHub-nativer Spiegel derselben kanonischen Dokumentation unter github.com/u9401066/pubmed-search-mcp/wiki

• 📚 26 Claude Skills - Einsatzbereite Workflow-Anleitungen für KI-Agenten (Claude Code-spezifisch)

• 📖 Copilot Instructions - Integrationsanleitung für VS Code GitHub Copilot

🌐 Sprache: Englisch | 繁體中文

📘 Dokumentationsübersicht: Die README ist der schnelle Einstieg in das Projekt. Verwenden Sie die Dokumentationsseite für das beste Leseerlebnis, das GitHub-Wiki für GitHub-native Navigation und die Quelldokumente für Bearbeitungen: Benutzerhandbuch | Erweiterte Workflows | Fähigkeitenorientierter Leitfaden | Provider-Datenebenen | BioMCP-Architekturanalyse | Entwicklerhandbuch | Vollständiger Index

🚀 Schnellinstallation

Voraussetzungen

• Python 3.10+ — Download

• uv (empfohlen) — uv installieren

  # 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-E-Mail — Erforderlich gemäß NCBI-API-Richtlinie. Jede gültige E-Mail-Adresse.

• NCBI-API-Schlüssel (optional) — Hier erhalten für höhere Ratenlimits (10 req/s vs. 3 req/s)

• OpenAlex-API-Schlüssel (optional) — setzen Sie OPENALEX_API_KEY, um ein authentifiziertes Kontingent zu nutzen; ohne diesen verwenden Anfragen das aktuelle anonyme Gelegenheitsnutzungsbudget von OpenAlex. mailto ist Kontaktmetadaten, keine Authentifizierung. Ohne quellspezifische E-Mails verwendet der Server die konfigurierte Laufzeit-Kontakt-E-Mail für OpenAlex, CrossRef und Unpaywall.

Installation und Ausführung

# 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-Fassade

Für In-Process-Python-Integrationen verwenden Sie die stabile SDK-Fassade anstelle des Importierens von MCP-Toolmodulen:

from pubmed_search.api import PubMedSearchClient, PubMedSearchConfig

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

print(result.articles)
print(result.source_counts)
print(result.artifact)  # artifact locator when persistence is enabled

Verwenden Sie uvx pubmed-search-mcp oder /mcp für die Tool-Erkennung durch Agenten. Verwenden Sie das SDK für Python-Paket-/Notebook-Aufrufe, wenn ein typisiertes Objekt einfacher ist als das Parsen einer MCP-Antwortzeichenfolge.

Laufzeitvertrag wählen

Lokale- und Dienstbereitstellungen sind bewusst getrennte Verträge. Machen Sie den lokalen HTTP-Befehl nicht zu einem öffentlichen Dienst, indem Sie nur seine Bindungsadresse ändern. Das explizite lokale Profil behält pmids="last", Sitzungen, Cache und Exporte über MCP-Anfragen und Wiederverbindungen in seinem dauerhaften default-Mandanten; dies ist nur innerhalb der erzwungenen Loopback-/Host-/Origin-Grenze sicher. Der Dienstmodus erbt dieses Vertrauen nie: Er schlägt ohne Bearer-Prinzipal fehl. Verwenden Sie DEPLOYMENT.md für die Dienstumgebung und das Compose-Profil. Das aktuelle Dienstprofil unterstützt viele authentifizierte Prinzipalen in einem Serverprozess; halten Sie eine Replik, bis Sitzungen, Sperren, Artefakte und Abonnements gemeinsame Backends haben.

Die Protokollbasis ist MCP SDK v2 (mcp>=2.0,<3). Moderne Clients vom 28.07.2026 senden tools/list und tools/call direkt, ohne initialize-Handshake oder Mcp-Session-Id. Der lokale Modus behält Dateisystemfunktionen. Authentifizierte Dienstaufrufer können keine file:-Pipelines laden, keine Notiz-output_dir/template_file auswählen oder einen prozessweiten Pipeline-Arbeitsbereich erben; der Compose-Scheduler des Dienstes ist deaktiviert. Siehe den Integrations- und Betriebsleitfaden für die Fähigkeitsmatrix.

Related MCP server: ScholarMCP

⚙️ Konfiguration

Dieser MCP-Server funktioniert mit jedem MCP-kompatiblen KI-Tool. Wählen Sie Ihren bevorzugten 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: Aktivieren Sie den PDF-Rückgriff der Browsersitzung einmal und lassen Sie Tools ihn automatisch verwenden:

{
  "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\"]}"
      }
    }
  }
}

Mit dieser Einstellung versucht get_fulltext automatisch den lokalen Broker für institutionelle oder Verlags-Landingpages. Übergeben Sie allow_browser_session=false nur, wenn Sie es für einen bestimmten Aufruf unterdrücken möchten.

Führen Sie den lokalen Broker mit Download-Interception aus:

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>"

Kopieren Sie den generierten Wert in beide Befehle/Konfigurationen; verwenden Sie niemals ein veröffentlichtes Beispiel-Token erneut. Wenn --token weggelassen wird, generiert der Broker und gibt ein hochentropisches Laufzeit-Token aus. Der Broker startet ein persistentes Browserprofil mit aktivierter Download-Interception. Melden Sie sich einmal in diesem brokerkontrollierten Browserfenster an, und nachfolgende PDF-Downloads werden automatisch ohne systemeigenen „Speichern unter"-Dialog erfasst.

Claude Desktop (claude_desktop_config.json)

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

Speicherort der Konfigurationsdatei:

• 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

Oder fügen Sie .mcp.json in Ihrem Projektstammverzeichnis hinzu:

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

Zed AI (settings.json)

Der Zed-Editor (z.ai) unterstützt MCP-Server nativ. Fügen Sie zu Ihrem Zed settings.json hinzu:

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

Tipp: Öffnen Sie die Befehlspalette → zed: open settings zum Bearbeiten, oder gehen Sie zu Agent Panel → Einstellungen → „Add Custom Server".

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

OpenClaw verwendet MCP-Server über das mcp-adapter-Plugin. Installieren Sie zuerst den Adapter:

openclaw plugins install mcp-adapter

Fügen Sie dann zu ~/.openclaw/openclaw.json hinzu:

{
  "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"
              }
            }
          ]
        }
      }
    }
  }
}

Starten Sie das Gateway nach der Konfiguration neu:

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",
        "S2_API_KEY": "your_semantic_scholar_key",
        "PUBMED_SEARCH_DISABLED_SOURCES": ""
      },
      "alwaysAllow": [],
      "disabled": false
    }
  }
}

Andere MCP-Clients

Jeder MCP-kompatible Client kann diesen Server über stdio-Transport verwenden:

# Command
uvx pubmed-search-mcp

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

Hinweis: NCBI_EMAIL ist gemäß der NCBI-API-Richtlinie erforderlich. Optional können Sie NCBI_API_KEY für höhere Ratenlimits setzen (10 req/s vs. 3 req/s). 📖 Detaillierte Integrationsanleitungen: Siehe docs/INTEGRATIONS.md für alle Umgebungsvariablen, Copilot-Studio-Einrichtung, Docker-Bereitstellung, Proxy-Konfiguration und Fehlerbehebung.

🎯 Designphilosophie

Kernpositionierung: Die intelligente Middleware zwischen KI-Agenten und akademischen Suchmaschinen.

Warum dieser Server?

Andere Tools bieten Ihnen reinen API-Zugriff. Wir bieten Ihnen Vokabelübersetzung + intelligente Weiterleitung + Rechercheanalyse:

Zentrale Unterscheidungsmerkmale

1. Vokabelübersetzungsschicht - Der Agent spricht natürlich, wir übersetzen in die Terminologie jeder Datenbank (MeSH, ICD-10, Text-Mining-Entitäten)

2. Einheitliches Such-Gateway - Ein unified_search()-Aufruf, fähigkeitsbewusste Verteilung über PubMed, Europe PMC, CORE, OpenAlex, Semantic Scholar und aktivierte Preprint-/kommerzielle Quellen

3. PICO-Übergabe + Pipeline - Der Agent extrahiert P/I/C/O, parse_pico() validiert diese strukturierte Übergabe, und die Backend-template: pico-Pipeline führt O-bewusste Präzisions-/Recall-Suchen aus

4. Forschungschronik und Abstammungsbaum - Erkennen Sie Meilensteine mit richtlinienbasierten Heuristiken, identifizieren Sie wegweisende Paper durch Multi-Signal-Scoring, zeigen Sie Diagnosen an, speichern Sie versionierte Überarbeitungen, die Sie diffen können, und visualisieren Sie die Forschungsentwicklung als verzweigte Bäume nach Unterthema

5. Zitationsnetzwerk-Analyse - Erstellen Sie mehrstufige Zitationsbäume, um eine gesamte Forschungslandschaft von einem einzelnen Paper aus zu kartieren

6. Vollständiger Forschungslebenszyklus - Von Suche → Entdeckung → Volltext → Analyse → Export, alles in einem Server

7. Agent-First-Design - Ausgabe optimiert für maschinelle Entscheidungsfindung, nicht für menschliches Lesen

📡 Externe APIs & Datenquellen

Dieser MCP-Server integriert mehrere akademische Datenbanken und APIs:

Zentrale Datenquellen

🔑 Legende: ✅ = Vollständige Vokabularunterstützung | ➡️ = Query-Durchgriff (kein kontrolliertes Vokabular)

ICD-Codes: Automatisch erkannt und vor der PubMed-Suche in MeSH konvertiert

Umgebungsvariablen

# 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
S2_API_KEY=your_s2_api_key         # Alias: SEMANTIC_SCHOLAR_API_KEY
OPENALEX_API_KEY=your_openalex_key # Raises the OpenAlex credit budget; actual grant is response-driven
PUBMED_SEARCH_DISABLED_SOURCES=    # Example: semantic_scholar

# 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 und Unpaywall verwenden die Kontakt-E-Mail des Laufzeitservers (NCBI_EMAIL, CLI --email oder erkannte Git-E-Mail) erneut, sofern keine quellenspezifische E-Mail konfiguriert ist. OpenAlex akzeptiert gelegentliche anonyme Nutzung und einen optionalen API-Schlüssel; der Broker liest die Antwort-Kredit-/Raten-Metadaten, anstatt eine dauerhafte "polite pool"-Kontingent anzunehmen.

Der lokale Notizenexport löst Verzeichnisse in dieser Reihenfolge auf: output_dir-Argument, PUBMED_NOTES_DIR, PUBMED_WORKSPACE_DIR/references, PUBMED_DATA_DIR/references, dann ~/.pubmed-search-mcp/references. Diese Pfad-/Vorlagenauswahl gilt nur für den vertrauenswürdigen lokalen Modus. Authentifizierte Dienstnotizen verwenden immer ein eingebautes Format unterhalb des isolierten references/-Verzeichnisses des aktuellen Mandanten. Für LLM-Wiki-Kompatibilität verwenden wiki- und foam-Exporte stabile Link-Ziele basierend auf PMID, DOI, PMCID oder Fallback-Identifikatoren; Titel bleiben Aliase/Anzeigelabels, und die Antwort enthält wiki_validation für unaufgelöste Wikilink-Prüfungen.

🔄 So funktioniert's: Die Middleware-Architektur

┌─────────────────────────────────────────────────────────────────────────────┐
│                              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-Übersicht

Wenn Sie die Tool-Oberfläche als nutzbares System verstehen möchten, beginnen Sie nicht mit dem Auswendiglernen von 45 Tool-Namen.

Beginnen Sie mit dem Tools Usage Guide: Er komprimiert die aktuellen 45 Tools in 8 Fähigkeitsfamilien, erklärt die theoretische Untergrenze und bietet absichtsbasierte Weiterleitung für Menschen und Agenten.

🔍 Such- & Abfrage-Intelligenz

┌─────────────────────────────────────────────────────────────────┐
│                      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 │
│   parse_pico()              → Agent-provided PICO handoff        │
│   analyze_search_query()    → Query analysis without execution   │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Ein Sucheinstieg, drei Abrufrichtlinien

Generische Literaturrecherche wird absichtlich über genau ein MCP-Tool bereitgestellt: unified_search. Anbieterspezifische APIs bleiben interne Broker-Fähigkeiten:

# 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="pubmed,openalex,semantic_scholar",
    options="systematic",
)

native_semantic und systematic schließen sich gegenseitig aus und deaktivieren die Multi-Strategie-Deep-Search-Erweiterung. Explizite Quellenauswahlen schlagen vor einem Netzwerkaufruf fehl, wenn ein angeforderter Abrufmodus nicht unterstützt wird; die automatische Quellenauswahl behält nur fähige Anbieter. limit bleibt bei höchstens 100 pro Quelle, daher bedeutet systematic deterministische, begrenzte Anbieterausführung—keine erschöpfende Systematic-Review-Garantie. Strukturierte Ausgabe und Artefakte erfassen retrieval_mode sowie pro Quelle source_metadata (angeforderter/Anbietermodus, kanonische oder kompilierte Abfrage, Fortsetzungsverfügbarkeit, Kosten-/Raten-Metadaten, und Warnungen, sofern verfügbar).

Die öffentliche Anforderungsgrenze ist fail-closed. limit muss eine Ganzzahl von 1 bis 100 sein; unbekannte oder fehlerhafte filters/options, umgekehrte oder außerhalb des Bereichs liegende Jahre sowie nicht unterstützte Ranking- oder Ausgabemodi geben einen Validierungsfehler zurück, bevor die Anbieter-I/O erfolgt. In der Standard-Deep-Search-Richtlinie ist limit ein Gesamtbudget pro Quelle, das auf die Abfragestrategien dieser Quelle aufgeteilt wird—nicht limit-Ergebnisse für jede Strategie. Strategieaufrufe verwenden begrenzte globale/Pro-Quellen-Nebenläufigkeit und Zeitüberschreitungen, und erfolgreiche Quellen bleiben nutzbar, wenn eine andere Quelle zeitüberschreitet, ratenbegrenzt ist oder fehlschlägt.

Europe PMC, Scopus und Web of Science bleiben in dieser Version reine Schlüsselwort-Suchen; explizite systematische Anfragen für diese Quellen schlagen vor der I/O fehl, anstatt eine einzelne Seite fälschlich als systematische Abdeckung zu kennzeichnen.

Siehe Source Contracts, Semantic Scholar und OpenAlex für Anbieterlimits und Operator-Datenebenen-Grenzen.

🔬 Entdeckungstools (Nach dem Finden wichtiger Paper)

                        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)

📚 Volltext, Figurenextraktion & Export

🖼️ OA-Figuren-zuerst-Erkundung

Nutzen Sie den PMC-Open-Access-Pfad, wenn ein Agent Beweisfiguren benötigt, nicht nur Artikeltext:

• get_article_figures(identifier="PMC12086443") → Figurenbeschriftungen, Bildunterschriften, Bild-URLs und PDF-/Artikellinks

• get_fulltext(pmcid="PMC7096777", include_figures=True) → Strukturierter Volltext mit Inline-Figuren

• Die Figurenausgabe bewahrt den Artikelkontext, sodass Agenten jede Figur mit den Abschnitten verbinden können, in denen sie erwähnt wird.

🧬 NCBI-Erweiterte Datenbanken

🕰️ Forschungschronik und Abstammungsbaum

mermaid ist die kanonische kombinierte Ansicht: eine horizontale Jahresachse, bei der jede beobachtete Forschungslinie an ihrem frühesten datierten Paper innerhalb des abgerufenen Bereichs abzweigt. Dies ist eine erklärbare Gruppierung, keine kausale Genealogie oder eine Behauptung über das tatsächliche erste Paper des Feldes. Linien bevorzugen MeSH-Deskriptoren und Autorenschlüsselwörter, die von mehreren Papers geteilt werden; Nur-Singleton- oder unzureichende Signale lösen einen gewarnten Research-Stage-Fallback aus. Die Anzeigereihenfolge im selben Jahr ist stabil, beansprucht aber keine Präzedenz, wenn die Publikationsgenauigkeit sie nicht belegen kann. timeline_mermaid bewahrt die ältere flache Zeitstrahlansicht. Siehe den implementierten Vertrag in docs/RESEARCH_CHRONICLE_REFACTOR_SPEC.md.

Chronicle-Mermaid-Ausgabe wird aus strukturierten Knoten und Kanten aufgebaut, mit sicherer Label-Escaping, Zyklus-/Waisen-Reparatur, kollisionsresistenten IDs und begrenzter Graphgröße. Sie fällt von reichhaltiger auf sichere auf minimale Syntax zurück, anstatt das gesamte Chronicle scheitern zu lassen. mermaid_validation.json zeichnet jede Korrektur, jeden Fallback und jedes ausgelassene visuelle Element auf; chronicle.mmd bleibt reine Mermaid-Quelle.

Chronicle-Revisionen sind unveränderlich und werden atomar angehängt. Wenn die Persistenz von Sitzungsartefakten aktiviert ist, wird ein Artefaktfehler explizit angezeigt, während die gespeicherte Chronicle-Revision verfügbar bleibt.

Topic-Builds senden Jahresgrenzen an PubMed, bevor der begrenzte Abruf erfolgt, und behalten dann die ersten und letzten beobachteten Papers bei, während sie die Obergrenze mit Meilensteinen und zeitlicher Streuung füllen. Das Audit zeichnet die PubMed-Werte returned / available auf und warnt, wenn die Verfügbarkeit unbekannt ist oder eine Abruf-/Auswahlgrenze die Ansicht nicht erschöpfend macht. PubMed-Fehler oder ein Umfang ohne Artikelbelege veröffentlichen keine leere Revision.

Die explizite PMID-Eingabe ist streng (12345678 oder PMID:12345678, positive ASCII-Ziffern, höchstens 20 Stellen); DOI oder gemischter Text wird abgelehnt, statt umgewandelt zu werden. Datensätze ohne zuverlässiges Veröffentlichungsdatum erscheinen nach den datierten Einträgen als Undated und sind von der angezeigten Jahresspanne ausgeschlossen. Eintrags-IDs folgen der PMID/DOI-Belegidentität über Datums- oder Klassifikator-Korrekturen hinweg, und die Themenkontinuität verwendet einen einzigen Unicode-/Groß-/Kleinschreibungs-/Leerzeichen-Kanonischen Schlüssel. Multi-Signal-Paper behalten einen primären Zweig plus explizite Querverweise; eine Überlappung von 20 % oder mehr wird als Warnung geprüft. In Revisions-Diffs bedeutet Abwesenheit not_observed_in_revision / removed_from_view, niemals endgültige Außerdienststellung.

🏥 Institutioneller Zugriff & ICD-Konvertierung

💾 Sitzungsverwaltung

Dynamische MCP-Ressourcen sind auch für Agenten verfügbar, die Ressourcen direkt lesen können:

• session://context — aktiver Sitzungsstatus

• session://last-search — Metadaten der letzten Suche

• session://last-search/pmids — neueste PMID-Liste + CSV-Formular

• session://last-search/results — zwischengespeicherte Artikel-Payloads für die letzte Suche

Persistente Artefakte

Persistente MCP-Ausgabeartefakte werden für wiederverwendbare unified_search- und get_fulltext-Antworten gespeichert, wenn die Sitzungspersistenz konfiguriert ist. Tool-Antworten fungieren wie Karteikarten: Sie enthalten genügend Zählwerte, Quellenwarnungen und Artefakthinweise, damit ein Agent sofort antworten kann, während die vollständigen Belegdaten in Dateien liegen, die wiederholt gelesen werden können. Der kompakte artifact-Locator umfasst artifact_id, artifact_uri, primary_file, summary, Dateiinventar, read_order, Audit-Status und genaue read_session(...)-Abrufhinweise. Setzen Sie PUBMED_ARTIFACT_INCLUDE_LOCAL_PATHS=true nur, wenn ein lokaler MCP-Client auch local_path und manifest_path direkt erhalten soll.

Ferne Clients, die das Server-Dateisystem nicht lesen können, können denselben Inhalt über die Sitzungsfassade abrufen:

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

Wiederherstellbare Suchläufe

Wenn die Sitzungsverwaltung aktiv ist, erhält jeder unified_search-Aufruf eine stabile Lauf-ID. Dies umfasst normale Suchen, Validierungs-/Planungsfehler sowie Inline-, saved:<name>- oder dry_run=true-Pipelineausführung. Strukturierte Ergebnisse und Fehler fügen den search_run-Übergabewert an; Markdown gibt dieselbe Lauf-ID als kompakten Wiederherstellungshinweis zurück. Normale Literatur-Ergebnisumschläge legen zwei getrennte Maschinenverträge offen:

• search_status beschreibt das Ergebnis des begrenzten Abrufs: state (completed, empty, partial oder failed), bounded=true, exhaustive=false, Anzahl der zurückgegebenen Ergebnisse, versuchte/erfolgreiche/fehlgeschlagene/wiederholbare Quellen sowie Listen für Fortsetzung/unbekannte Vollständigkeit.

• search_run ist der Wiederherstellungs-Übergabewert: stabile run_id, Journalstatus, recoverable, genaue read_session-Inspektions-/Wiederholungsargumente und die Artefakt-URI, sofern eine festgeschrieben wurde.

Das mandantenbezogene search-run/v1-Journal wird vor Provider-I/O oder einer terminalen Validierungsantwort veröffentlicht und zeichnet die bereinigte Anfrage, den Plan, physische Versuche pro Quelle oder pro Pipelineschritt, Zählwerte, sichere Fehler, Ergebnisreferenzen und gegebenenfalls den Artefakt-Locator auf. Es erreicht einen terminalen Zustand completed, partial, failed oder cancelled; eine gültige Suche mit null Ergebnissen ist ein completed-Lauf, dessen search_status.state empty ist. Beim Neustart wird ein unvollendeter Eintrag started / planned / running einmal als interrupted wiederhergestellt, statt zu verschwinden. Eine gespeicherte Pipeline ohne Trockenlauf behält zusätzlich ihren PipelineStore-Bericht/ihre Laufhistorie; das ergänzt das aufrufebezogene Suchjournal, ersetzt es jedoch nicht.

Pipeline-Wiedergabe bewahrt das ursprüngliche Inline- oder saved:<name>-Argument sowie dry_run / stop_at. Pipeline-Text, der Schlüssel, Tokens, Cookies, Passwörter oder anderes Anmeldeinformationsmaterial enthält, wird abgelehnt und als fehlgeschlagener Lauf aufgezeichnet; Anbieter-Anmeldeinformationen gehören in die Serverumgebung/-konfiguration, niemals in Pipeline-YAML oder -JSON.

read_session(action="search_runs")
read_session(action="search_runs", run_status="partial")
read_session(action="search_run", run_id="...")
read_session(action="replay_search", run_id="...")

replay_search gibt nur die ursprünglichen anmeldeinformationsfreien unified_search-kwargs zurück. Es führt niemals automatisch einen Netzwerkaufruf aus; der Agent oder Benutzer muss sie prüfen und explizit einreichen. Anbieter-Cursor-/Token-Werte werden als undurchsichtige Herkunft in source_metadata und query_strategy.json aufbewahrt, aber es gibt noch keinen öffentlichen Cursor-Resume-Parameter, daher startet die Wiedergabe eine neue begrenzte Suche.

Wenn der terminale Journal-Schreibvorgang nicht wiederhergestellt werden kann, meldet die Antwort search_run.status="history_unavailable", history_available=false, den beabsichtigten terminalen Status und eine Warnung. Sie lässt Inspektions-/Wiederholungsaktionen bewusst aus, da eine dauerhafte Wiederherstellung nicht garantiert ist; das Suchergebnis selbst kann weiterhin verwendbar sein.

unified_search-Artefakte verwenden einen Forschungs-Umschlag. Beginnen Sie mit audit.json für Quellenanzahl- und Vollständigkeitswarnungen, dann query_strategy.json für den exakt ausgeführten Plan und schließlich results.json / results.toon für die vollständige Artikelliste. Dies hält die MCP-Antwort-Tokens klein, ohne die akademische Rückverfolgbarkeit zu verlieren.

Artefakte werden aus dem bereits berechneten Ergebnisobjekt erzeugt, sodass das Lesen eines Artefakts keine Suchen oder Volltextabrufe erneut ausführt. Wenn ein Absturz auftritt, nachdem ein Artefaktverzeichnis atomar veröffentlicht wurde, aber bevor der Sitzungsindex aktualisiert wird, findet die Sitzungswiederherstellung nur vollständige, prüfsummenindizierte Manifeste und verknüpft das verwaiste Artefakt über search_run_id erneut mit seinem Suchlauf (mit einem konservativen Abfrageabgleich für ältere Artefakte). read_session schwärzt standardmäßig lokale Dateisystempfade; local_path und manifest_path sind serverlokale Pfade, keine portablen Client-Pfade. Artefakte von get_fulltext können Artikel-Volltexte enthalten, einschließlich Abonnement- oder institutionell zugänglicher Inhalte. Speichern und teilen Sie sie gemäß den Bedingungen von Verlag, Lizenz und institutionellem Zugriff. Große get_fulltext-Antworten werden inline als Vorschau zurückgegeben, wenn ein Artefakt verfügbar ist; verwenden Sie den Artefakt-Locator, um den gespeicherten vollständigen Inhalt abzurufen.

Wenn eine Quelle ausfällt, die Gesamtsuche aber fortgesetzt werden kann, können JSON-Antworten source_errors enthalten; Markdown-Antworten zeigen eine Zeile Source warnings. Bei HTTP-429-Antworten von Semantic Scholar setzen Sie S2_API_KEY / SEMANTIC_SCHOLAR_API_KEY, versuchen Sie es später erneut oder schließen Sie die Quelle vorübergehend mit sources="auto,-semantic_scholar" oder PUBMED_SEARCH_DISABLED_SOURCES=semantic_scholar aus.

Pipeline-Verwaltung

manage_pipeline ist die primäre Fassade für Pipeline-CRUD, -Verlauf und -Zeitplanung. Die spezifischeren Pipeline-Tools bleiben als Kompatibilitäts-Wrapper verfügbar.

Authentifizierte Dienstaufrufer verwenden benannte Pipelines in ihrem mandantenabhängigen Speicher; workspace- und file:-Zugriff sind nur lokal verfügbar. Das Compose-Profil des Dienstes führt keine Zeitpläne aus, ohne dass ein separat entworfenes Single-Leader-System vorhanden ist.

Schritt-für-Schritt-Tutorials:

• Englisch: docs/PIPELINE_MODE_TUTORIAL.en.md

• 繁體中文: docs/PIPELINE_MODE_TUTORIAL.md

👁️ Vision & Bildsuche

Verwenden Sie analyze_figure_for_search, wenn der Benutzer ein Bild bereitstellt und der Agent zuerst dessen Bedeutung interpretieren muss. Das Tool gibt MCP-ImageContent plus Anweisungen für den LLM-Agenten zurück, englische biomedizinische Begriffe zu extrahieren, und dann mit search_biomedical_images für ähnliche Open-i-Bilder oder unified_search für verwandte Paper fortzufahren.

📄 Preprint-Suche

Durchsuchen Sie die Preprint-Server arXiv, medRxiv und bioRxiv über unified_search-options-Flags:

• preprints: Durchsucht Preprint-Server und führt Preprints mit dem Haupt-Aggregatsergebnis zusammen, mit article_type=PREPRINT.

• all_types: Behält nicht-peerreviewte Inhalte, die bereits von ausgewählten wissenschaftlichen Quellen zurückgegeben wurden, auch ohne Preprint-Server-Durchsuchung.

Empfohlene Kombinationen:

• Leere options: Nur peer-reviewte Ergebnisse; preprint-ähnliche Datensätze werden herausgefiltert.

• options="preprints": Durchsucht arXiv, medRxiv und bioRxiv, rankt/dedupliziert diese Preprints dann mit den Hauptergebnissen.

• options="preprints, all_types": Gleiche Preprint-Server-Durchsuchung, zusätzlich werden andere nicht-peerreviewte Datensätze ausgewählter Quellen beibehalten.

• options="all_types": Keine Preprint-Server-Durchsuchung, aber nicht-peerreviewte Einträge aus durchsuchten Quellen werden beibehalten.

Preprint-Erkennung — Artikel werden anhand der folgenden Kriterien als Preprints identifiziert:

• Artikeltyp aus der Quellen-API (OpenAlex, CrossRef, Semantic Scholar)

• arXiv-ID vorhanden ohne PubMed-ID

• Bekannte Preprint-Server-Quelle oder Zeitschriftenname

• DOI-Präfix, das zu Preprint-Servern passt (z. B. 10.1101/ → bioRxiv/medRxiv, 10.48550/ → arXiv)

🌳 Research-Context-Graph

unified_search kann eine leichtgewichtige Forschungs-Abstammungsansicht anhängen, die aus PMID-gestützten Ranglisten-Ergebnissen aufgebaut ist:

Dies ist nützlich, wenn ein Agent eine schnelle thematische Verzweigung benötigt, ohne einen zweiten build_research_chronicle-Aufruf auszuführen.

🧪 Clinical-Trial-Register-Ergänzung

ClinicalTrials.gov wird niemals implizit abgefragt. Fügen Sie options="trials" zu einer Markdown-Suche hinzu, wenn eine begrenzte Register-Ergänzung sinnvoll ist. Sie bleibt getrennt vom Literaturquellen-Plan und den Quellenzahlen; das dauerhafte Artefakt zeichnet seine gekürzte physische Abfrage und das Ergebnis unter adjunct_queries auf. Strukturierte JSON/TOON-Suchen führen diese nur anzeigende Ergänzung nicht aus.

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

📊 Count-First-Orientierung

unified_search kann auch die vorhandene Quellenabdeckung und Entscheidungshinweise voranstellen, für Agenten, die Routing-Hilfe wünschen, bevor sie die Rangliste lesen:

Beispiel:

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

Dieser Modus ist nützlich, wenn der Agent entscheiden soll, ob er eine Quelle erweitern, die führende PMID prüfen, Volltext abrufen, Abbildungen extrahieren oder zur Zeitachsen-Exploration übergehen soll.

⏱️ MCP-Fortschrittsmeldung

Wenn der MCP-Client ein Fortschritts-Token bereitstellt, senden unified_search, build_research_chronicle, get_fulltext und get_text_mined_terms Fortschrittsmeldungen für ihre Hauptphasen. Dies reduziert die „Black-Box“-Wartezeit für Agenten bei längeren Suchen. Fortschritts-Callbacks sind Best-Effort und werden vom Server während eines aktiven Tool-Aufrufs nicht abgebrochen, wodurch hostseitige Canceled: Canceled-Meldungen vermieden werden, die durch Fortschritts-Benachrichtigungs-Gegenstau entstehen.

📋 Beispiele für die Agentennutzung

1️⃣ Schnellsuche (am einfachsten)

# 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-klinische Frage

Einfacher Weg — unified_search kann direkt suchen (keine PICO-Zerlegung):

# 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

Agenten-Workflow — vom Agenten bereitgestelltes PICO + Backend-Pipeline-Suche (empfohlen für klinische Fragen):

┌─────────────────────────────────────────────────────────────────────────┐
│  "Is remimazolam better than propofol for ICU sedation?"                │
└─────────────────────────────────┬───────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         parse_pico()                                     │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐                     │
│  │    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 = parse_pico(
    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️⃣ Von einem Schlüsselartikel aus erkunden

# 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️⃣ Gen-/Medikamentenforschung

# 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️⃣ Ergebnisse exportieren

# 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(pmid="12345678", extended_sources=True)

6️⃣ Preprint-Suche

# Include preprints alongside peer-reviewed results
unified_search(query="COVID-19 vaccine efficacy", options="preprints")
# → Main aggregated results include labelled arXiv, medRxiv, and bioRxiv preprints

# Include preprints and retain non-peer-reviewed items in main results
unified_search(query="CRISPR gene therapy", options="preprints, all_types")
# → Preprint-server crawl + non-peer-reviewed items retained in main results

# Only peer-reviewed (default behavior)
unified_search("diabetes treatment")
# → Preprints from any source automatically filtered out

# Add a research context graph preview to the same search response
unified_search("remimazolam ICU sedation", options="context_graph")

7️⃣ Pipeline (Wiederverwendbare Suchpläne)

# Save a template-based pipeline through the primary facade
manage_pipeline(
  action="save",
    name="icu_sedation_weekly",
    config="template: pico\nparams:\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
manage_pipeline(
  action="save",
    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
manage_pipeline(action="list", tag="anesthesia")
manage_pipeline(action="load", source="brca1_comprehensive")  # Review YAML
manage_pipeline(action="history", name="icu_sedation_weekly")  # View past runs

🔍 Vergleich der Suchmodi

┌─────────────────────────────────────────────────────────────────────────┐
│                        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 → parse_pico() 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     │
│                 → Citation network, research context                     │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

🤖 Claude-Skills (KI-Agenten-Workflows)

Vorgefertigte Workflow-Anleitungen in .claude/skills/, unterteilt in Nutzungs-Skills (für die Verwendung des MCP-Servers) und Entwicklungs-Skills (für die Projektpflege):

📚 Nutzungs-Skills (11) — Für KI-Agenten, die diesen MCP-Server verwenden

🔧 Entwicklungs-Skills (15) — Für Projektbeitragende

📁 Speicherort: .claude/skills/*/SKILL.md (Claude-Code-spezifisch und die einzige Quelle der Wahrheit für Repo-Skills) Spiegle oder teile Repo-Skills nicht in .github/skills/ auf. Diese Repo-Skills sind projektspezifisch und sollten versioniert bleiben. Persönliche projektübergreifende Skills gehören in ein Benutzerverzeichnis wie ~/.copilot/skills/ oder ~/.claude/skills/, nicht in dieses Repository.

🏗️ Architektur (DDD)

Dieses Projekt verwendet eine Domain-Driven-Design (DDD)-Architektur, mit dem Domänenwissen der Literaturrecherche als Kernmodell.

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...
│   └── api/                    # Auxiliary HTTP API routes (not pubmed_search.api)
└── shared/                     # Cross-cutting concerns
    ├── exceptions.py           # Unified error handling
    └── async_utils.py          # Rate limiter, retry, circuit breaker

Interne Mechanismen (Für Agenten transparent)

Vokabular-Übersetzungsschicht (Kernfunktion)

Unser Kernwert: Wir sind die intelligente Middleware zwischen Agent und Suchmaschinen, die automatisch die Vokabular-Standardisierung übernimmt, sodass der Agent die Terminologie jeder Datenbank nicht kennen muss.

Verschiedene Datenquellen verwenden unterschiedliche kontrollierte Vokabularsysteme. Dieser Server bietet eine automatische Konvertierung:

Automatische ICD→MeSH-Konvertierung

Bei der Suche mit ICD-Codes (z. B. I10 für Hypertonie) führt unified_search() automatisch Folgendes aus:

1. Erkennt ICD-10/ICD-9-Muster über detect_and_expand_icd_codes()

2. Schlägt entsprechende MeSH-Begriffe aus der internen Zuordnung nach (ICD10_TO_MESH, ICD9_TO_MESH)

3. Erweitert die Abfrage um MeSH-Synonyme für eine umfassende Suche

# 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"

📖 Vollständige Architekturdokumentation: ARCHITECTURE.md

MeSH-Auto-Expansion + Abfrageanalyse

Beim Aufruf von generate_search_queries("remimazolam sedation") wird intern:

1. ESpell-Korrektur – Rechtschreibfehler beheben

2. MeSH-Abfrage – Entrez.esearch(db="mesh") zum Abrufen des Standardvokabulars

3. Synonymextraktion – Synonyme aus MeSH-Eintragsbegriffen abrufen

4. Abfrageanalyse – Analysieren, wie PubMed jede Abfrage interpretiert

{
  "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 ...)"
    }
  ]
}

Wert der Abfrageanalyse: Der Agent denkt, remimazolam AND sedation durchsucht nur diese zwei Wörter, aber PubMed erweitert tatsächlich um Supplementary Concept + Synonyme; die Ergebnisse steigen von 8 auf 561. Dies hilft dem Agenten, den Unterschied zwischen Absicht und tatsächlicher Suche zu verstehen.

🔒 Lokale HTTPS-Demo und Service-Bereitstellung

Die gebündelten selbstsignierten Zertifikate und der curl -k-Ablauf sind eine lokale TLS-Demo, kein Produktionssicherheitsprofil. Für einen gemeinsam genutzten Dienst verwenden Sie die authentifizierte Service-Compose-Datei und ein vertrauenswürdiges Zertifikat, wie in DEPLOYMENT.md beschrieben.

Lokaler 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-Endpunkte

Remote-MCP-Client-Konfiguration

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

🏢 Microsoft-Copilot-Studio-Integration

Integrieren Sie PubMed Search MCP mit Microsoft 365 Copilot (Word, Teams, Outlook)!

Schnellstart

# 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-Konfiguration

📖 Vollständige Dokumentation: copilot-studio/README.md

Verwenden Sie pubmed-search-mcp-http --copilot-compatible für verpackte Copilot-HTTP-Semantik. run_server.py bleibt ein Entwicklungs-Wrapper im Quellbaum; verwenden Sie run_copilot.py nur für Loopback-only-12-Tool-Primitive-Schema-Smoke-Tests. Diese vereinfachte Oberfläche ruft weiterhin den gemeinsamen Runner über unified_search(query, limit, min_year, max_year, sources, options) auf und stellt read_session im Primitive-Schema für Suchlauf, Wiedergabeargumente und Artefaktwiederherstellung bereit; es stellt keinen PubMed-spezifischen Generalsuch-Alias bereit. Das Tunnel-Skript erfordert eine zugewiesene NGROK_DOMAIN, lehnt belegte Backend-Ports ab und veröffentlicht erst, nachdem --mode service die Bereitschafts- und Ablehnungsprüfungen für nicht authentifizierte Zugriffe bestanden hat.

⚠️ Hinweis: SSE-Transport seit Aug. 2025 veraltet. Verwenden Sie streamable-http.

📖 Weitere Dokumentation:

• Architektur → ARCHITECTURE.md

• Pipeline-Tutorial (Englisch) → docs/PIPELINE_MODE_TUTORIAL.en.md

• Pipeline-Tutorial (zh-TW) → docs/PIPELINE_MODE_TUTORIAL.md

• Bereitstellungsleitfaden → DEPLOYMENT.md

• Copilot Studio → copilot-studio/README.md

🔐 Sicherheit

Sicherheitsfunktionen

Weitere Einzelheiten zur Bereitstellung finden Sie in DEPLOYMENT.md.

📤 Exportformate

Exportieren Sie Ihre Suchergebnisse in Formaten, die mit gängigen Referenzverwaltungsprogrammen kompatibel sind:

Exportierte Felder

• Kern: PMID, Titel, Autoren, Zeitschrift, Jahr, Band, Ausgabe, Seiten

• Kennungen: DOI, PMC-ID, ISSN

• Inhalt: Abstract (HTML-Tags bereinigt)

• Metadaten: Sprache, Publikationstyp, Schlüsselwörter

• Zugriff: DOI-URL, PMC-URL, Verfügbarkeit des Volltexts

Behandlung von Sonderzeichen

• BibTeX-Exporte verwenden pylatexenc für eine korrekte LaTeX-Kodierung

• Nordische Zeichen (ø, æ, å), Umlaute (ü, ö, ä) und Akzente werden korrekt konvertiert

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

📚 Zitierung

GitHub zeigt Cite this repository aus CITATION.cff. Wenn Sie PubMed Search MCP in Forschung, Methodenteilen oder internen technischen Berichten verwenden, bevorzugen Sie die von GitHub generierte Zitierung oder verwenden Sie direkt die Repository-Metadaten.

@software{pubmed_search_mcp,
  title = {PubMed Search MCP},
  author = {u9401066},
  url = {https://github.com/u9401066/pubmed-search-mcp}
}

📄 Lizenz

Apache License 2.0 – siehe LICENSE

🔗 Links

• GitHub-Repository

• PyPI-Paket

• NCBI Entrez Programming Utilities