SemanticScholar_MCP

Deterministische Model-Context-Protocol-Schnittstellen für die drei Semantic-Scholar-API-Familien:

• S2AG — Academic-Graph-Suche, Metadaten, Autoren, Zitationen und Referenzen.

• Recommendations — der Paper-Empfehlungsdienst von Semantic Scholar.

• Datasets — Release-Erkennung, Dataset-Manifeste und inkrementelle Dataset-Updates.

Das Projekt bietet bewusst dünne API-Wrapper statt eines agentischen Literaturrecherche-Systems.

Design

Die zentrale Regel lautet:

Ein MCP-Toolaufruf entspricht einer dokumentierten Semantic-Scholar-Operation.

Die Server übernehmen Transportaufgaben wie Validierung, Authentifizierung, Rate-Limitierung, Wiederholungsversuche und Antwortnormalisierung.

Sie entscheiden nicht, welche Literatur wissenschaftlich wichtig ist.

Zum Beispiel:

Agent
  │
  ├── "Search for paired-pulse TMS papers"
  │         │
  │         ▼
  │       S2AG MCP
  │         │
  │         ▼
  │    Semantic Scholar
  │
  ├── "Recommend papers from these three seed papers"
  │         │
  │         ▼
  │  Recommendations MCP
  │         │
  │         ▼
  │    Semantic Scholar
  │
  └── "Describe the latest S2ORC dataset release"
            │
            ▼
       Datasets MCP
            │
            ▼
       Semantic Scholar

Suchexpansion, wissenschaftliche Interpretation, Zusammenfassung, Strategie zur Erkundung des Zitationsgraphen und Forschungssynthese bleiben Aufgaben des konsumierenden Agenten.

Related MCP server: Semantic Scholar MCP Server

Repository-Struktur

SemanticScholar_MCP/
├── src/
│   └── semantic_scholar_mcp/
│       ├── common/
│       │   ├── client.py
│       │   ├── errors.py
│       │   ├── models.py
│       │   ├── rate_limit.py
│       │   └── __init__.py
│       ├── datasets/
│       │   ├── server.py
│       │   └── __init__.py
│       ├── recommendations/
│       │   ├── server.py
│       │   └── __init__.py
│       ├── s2ag/
│       │   ├── server.py
│       │   └── __init__.py
│       └── __init__.py
├── tests/
├── AGENTS.md
├── CLAUDE.md
├── pyproject.toml
└── README.md

Voraussetzungen

• Python 3.11 oder neuer

• Internetzugriff auf Semantic Scholar

• optionaler Semantic-Scholar-API-Schlüssel

Die Implementierung verwendet die aktuelle v2-Linie des offiziellen Python-MCP-SDK.

Installation

Erstellen Sie eine virtuelle Umgebung:

py -3.14 -m venv .venv
.\.venv\Scripts\Activate.ps1

Installieren Sie das Paket im bearbeitbaren Modus mit Entwicklungsabhängigkeiten:

python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

Alternativ mit uv:

uv venv --python 3.14
uv pip install -e ".[dev]"

Python 3.14 ist nicht erforderlich; das Projekt unterstützt Python 3.11 und höher.

Nach der Konfiguration der Python-Paketumgebung führen Sie optional Tests aus:

pytest
ruff check .
ruff format --check .

Wenn Sie bereits SEMANTIC_SCHOLAR_API_KEY als Systemumgebungsvariable konfiguriert haben (siehe nächster Abschnitt, Authentifizierung), können Sie auch die Live-Integration testen:

pytest --run-integration

Hinweis: Wenn Sie die Systemumgebungsvariable nach dem Start eines VSCode-Fensters auf Ihren API-Schlüssel setzen, müssen Sie alle VSCode-Fenster schließen, um VSCode vollständig neu zu starten, bevor die Systemumgebung von Tools erfasst wird, die über VSCode-Erweiterungen ausgeführt werden!

Authentifizierung

Semantic Scholar unterstützt bei vielen API-Operationen den Zugriff ohne Authentifizierung.

Wenn ein API-Schlüssel verfügbar ist, legen Sie ihn den MCP-Prozessen über Folgendes offen:

$env:SEMANTIC_SCHOLAR_API_KEY = "..."

Platzieren Sie den Schlüssel nicht in:

• .mcp.json;

• .codex/config.toml;

• Quellcode;

• eingecheckten .env-Dateien;

• Test-Fixtures.

Die MCP-Server verwenden den Schlüssel automatisch, wenn er vorhanden ist.

Operationen, die eine Authentifizierung erfordern, sollten einen expliziten Fehler zurückgeben, wenn kein Schlüssel konfiguriert ist.

Hinweis (erneut): Wenn Sie die Systemumgebungsvariable nach dem Start eines VSCode-Fensters auf Ihren API-Schlüssel setzen, müssen Sie alle VSCode-Fenster schließen, um VSCode vollständig neu zu starten, bevor die Systemumgebung von Tools erfasst wird, die über VSCode-Erweiterungen ausgeführt werden!

Build-Updates

Die Skripte .\rebuild.ps1 und .\version.ps1 werden als Hilfsmittel bereitgestellt, um Versionsupdates beim Neuerstellen zu erleichtern:

rebuild.ps1

Um ohne automatisches Erhöhen der patch-Nummer neu zu erstellen, geben Sie explizit den Schalter an:

.\rebuild.ps1 -SkipVersionIncrement

Andernfalls erhöht .\rebuild.ps1 die Patch-Nummer in pyproject.toml direkt automatisch.

version.ps1

Um <major> | <minor> | <patch> ohne Neuaufbau zu erhöhen:

.\version.ps1 patch -NoRebuild

Um die minor-Version zu erhöhen, patch auf 0 zurückzusetzen und neu zu erstellen:

.\version.ps1 minor

Um die major-Version zu erhöhen, sowohl minor als auch patch auf 0 zurückzusetzen und neu zu erstellen:

.\version.ps1 major

MCP-Client-Konfiguration

Die drei Semantic-Scholar-MCP-Server können entweder konfiguriert werden:

• projektlokal, sodass sie nur innerhalb eines bestimmten Repositorys verfügbar sind; oder

• benutzerglobal, sodass sie über Repositorys hinweg verfügbar sind.

Die Server sind:

• s2ag — Semantic Scholar Academic Graph

• s2_recommendations — Semantic Scholar Recommendations API

• s2_datasets — Semantic Scholar Datasets API

Die folgenden Beispiele setzen voraus, dass dieses Repository installiert ist unter:

C:\MyRepos\Python\SemanticScholar_MCP

Passen Sie den Pfad nach Bedarf an.

Die Beispiele rufen bewusst den Python-Interpreter der virtuellen Umgebung mit python -m ... auf, statt die erzeugten semantic-scholar-*.exe-Konsolenlauncher direkt aufzurufen. Dies wird während der lokalen Entwicklung unter Windows empfohlen, da das Ausführen von Konsolenlaunchern verhindern kann, dass pip sie bei einer bearbeitbaren Neuinstallation ersetzt.

Codex

Codex unterstützt sowohl benutzerglobale als auch projektlokale config.toml-Dateien.

Projektlokale Codex-Konfiguration

Erstellen oder bearbeiten Sie:

<project>/.codex/config.toml

Zum Beispiel:

[mcp_servers.s2ag]
command = 'C:\MyRepos\Python\SemanticScholar_MCP\.venv\Scripts\python.exe'
args = ["-m", "semantic_scholar_mcp.s2ag.server"]
startup_timeout_sec = 15
tool_timeout_sec = 120
enabled = true

[mcp_servers.s2_recommendations]
command = 'C:\MyRepos\Python\SemanticScholar_MCP\.venv\Scripts\python.exe'
args = ["-m", "semantic_scholar_mcp.recommendations.server"]
startup_timeout_sec = 15
tool_timeout_sec = 120
enabled = true

[mcp_servers.s2_datasets]
command = 'C:\MyRepos\Python\SemanticScholar_MCP\.venv\Scripts\python.exe'
args = ["-m", "semantic_scholar_mcp.datasets.server"]
startup_timeout_sec = 15
tool_timeout_sec = 120
enabled = true

Projektbezogene Codex-Konfiguration wird nur für Projekte geladen, die Codex als vertrauenswürdig betrachtet.

Benutzerglobale Codex-Konfiguration

Um die Server Codex projektübergreifend zur Verfügung zu stellen, platzieren Sie dieselbe Konfiguration in:

~/.codex/config.toml

Unter Windows ist dies normalerweise:

%USERPROFILE%\.codex\config.toml

Zum Beispiel:

C:\Users\<username>\.codex\config.toml

Die MCP-Serverblöcke selbst sind identisch mit dem obigen projektlokalen Beispiel.

Codex-Konfiguration überprüfen

Von einem Terminal aus:

codex mcp list

Einzelne Registrierungen können auch mit Folgendem eingesehen werden:

codex mcp get s2ag
codex mcp get s2_recommendations
codex mcp get s2_datasets

Claude Code

Claude Code unterscheidet zwischen projektgeteilten und benutzerbezogenen MCP-Servern.

Projektlokale / projektgeteilte Claude-Konfiguration

Erstellen Sie:

<project>/.mcp.json

mit:

{
  "mcpServers": {
    "s2ag": {
      "command": "C:\\MyRepos\\Python\\SemanticScholar_MCP\\.venv\\Scripts\\python.exe",
      "args": [
        "-m",
        "semantic_scholar_mcp.s2ag.server"
      ]
    },
    "s2_recommendations": {
      "command": "C:\\MyRepos\\Python\\SemanticScholar_MCP\\.venv\\Scripts\\python.exe",
      "args": [
        "-m",
        "semantic_scholar_mcp.recommendations.server"
      ]
    },
    "s2_datasets": {
      "command": "C:\\MyRepos\\Python\\SemanticScholar_MCP\\.venv\\Scripts\\python.exe",
      "args": [
        "-m",
        "semantic_scholar_mcp.datasets.server"
      ]
    }
  }
}

Diese Datei kann in das konsumierende Repository eingecheckt werden, wenn die MCP-Konfiguration mit anderen Benutzern dieses Repositorys geteilt werden soll.

Benutzerglobale Claude-Konfiguration

Für die globale Claude-Code-Konfiguration ist der bevorzugte Ansatz, Claude Code die benutzerbezogenen MCP-Registrierungen verwalten zu lassen.

Führen Sie aus:

claude mcp add --scope user s2ag -- "C:\MyRepos\Python\SemanticScholar_MCP\.venv\Scripts\python.exe" -m semantic_scholar_mcp.s2ag.server

claude mcp add --scope user s2_recommendations -- "C:\MyRepos\Python\SemanticScholar_MCP\.venv\Scripts\python.exe" -m semantic_scholar_mcp.recommendations.server

claude mcp add --scope user s2_datasets -- "C:\MyRepos\Python\SemanticScholar_MCP\.venv\Scripts\python.exe" -m semantic_scholar_mcp.datasets.server

Claude Code speichert derzeit die benutzerbezogene MCP-Konfiguration in:

~/.claude.json

Unter Windows:

%USERPROFILE%\.claude.json

Die Verwendung von claude mcp add --scope user ist der manuellen Bearbeitung dieser Datei vorzuziehen, da Claude Code zusätzlichen Zustand in .claude.json besitzt.

Überprüfen Sie die Registrierungen mit:

claude mcp list

Wenn eine bestimmte Claude-Code-Version Probleme beim Laden benutzerbezogener MCP-Server hat, ist die Projektkonfiguration .mcp.json der einfachste Fallback.

Semantic-Scholar-API-Schlüssel

Viele Semantic-Scholar-Operationen funktionieren ohne Authentifizierung. Operationen, die einen API-Schlüssel benötigen, verwenden:

SEMANTIC_SCHOLAR_API_KEY

Speichern Sie den Schlüssel nicht in einer MCP-Konfigurationsdatei.

Unter Windows kann er als Benutzerumgebungsvariable gespeichert werden:

[Environment]::SetEnvironmentVariable(
    "SEMANTIC_SCHOLAR_API_KEY",
    "YOUR_API_KEY",
    "User"
)

Starten Sie VS Code, Codex, Claude Code oder andere MCP-Hosts nach dem Setzen der Variablen neu, damit neu gestartete MCP-Prozesse sie erben.

Die MCP-Server verwenden den Schlüssel automatisch, wenn er vorhanden ist, und bleiben andernfalls ohne Authentifizierung, wo Semantic Scholar anonymen Zugriff erlaubt.

Projektlokal vs. benutzerglobal

Eine nützliche Regel ist:

Für ein Forschungs-Repository, dessen Agenten explizit Literaturrecherche durchführen sollen, ist die projektlokale Konfiguration in der Regel vorzuziehen, weil die verfügbaren Recherche-Tools mit dem Repository mitgeliefert werden.

Für den allgemeinen persönlichen Zugriff auf Semantic Scholar aus beliebigen Projekten ist die benutzerglobale Konfiguration bequemer.

Gemeinsames Rate Limiting

Das anfängliche authentifizierte Ratelimit von Semantic Scholar gilt über API-Endpunkte hinweg und nicht unabhängig für jeden MCP-Server.

Dieses Repository verwendet daher einen gemeinsamen Limiter:

S2AG MCP ────────────────┐
                         │
Recommendations MCP ─────┼── shared limiter ──> Semantic Scholar
                         │
Datasets MCP ────────────┘

Die Standardimplementierung sollte über alle drei lokalen Server hinweg nicht mehr als ungefähr eine Upstream-Anfrage pro Sekunde zulassen.

Dies ist wichtig, wenn mehrere Hosts gleichzeitig laufen, zum Beispiel:

VS Code / Codex
Claude Code
MCP Inspector
tests

Der Limiter sollte diese Prozesse koordinieren, anstatt in jedem von ihnen eine unabhängige Uhr zu betreiben.

Wiederholungsverhalten

Vorübergehende Upstream-Fehler können mit begrenztem exponentiellem Backoff wiederholt werden.

Beispiele hierfür sind:

• HTTP 429;

• vorübergehende 5xx-Antworten;

• vorübergehende Netzwerkfehler.

Retry-After wird beachtet, sofern angegeben.

Gewöhnliche Clientfehler wie ungültige Anfragen, abgelehnte Authentifizierung und fehlende Ressourcen werden nicht immer wieder erneut versucht.

Wiederholungen sind begrenzt; der MCP-Server wiederholt nie auf unbestimmte Zeit.

S2AG MCP

Führen Sie aus:

semantic-scholar-s2ag

oder:

python -m semantic_scholar_mcp.s2ag.server

Die anfängliche API-Oberfläche soll Folgendes umfassen:

Die Paginierung bleibt explizit.

Eine Zitationsanfrage durchläuft den Zitationsgraphen nicht rekursiv.

Eine Suche löst nicht automatisch Folgeabfragen aus.

Recommendations MCP

Führen Sie aus:

semantic-scholar-recommendations

oder:

python -m semantic_scholar_mcp.recommendations.server

Die anfängliche Oberfläche ist bewusst klein:

Der Server übergibt die vom Aufrufer gewählten Startwerte an Semantic Scholar.

Er wählt keine eigenen Startwerte und wendet auch kein zweites, von einer LLM erzeugtes Ranking auf die Ergebnisse an.

Beispielhafter konzeptioneller Ablauf:

positive:
  paper A
  paper B
  paper C

negative:
  paper D

        │
        ▼

recommend_from_examples

        │
        ▼

Semantic Scholar recommendation ranking

Datasets MCP

Führen Sie aus:

semantic-scholar-datasets

oder:

python -m semantic_scholar_mcp.datasets.server

Die anfänglichen Tools sind:

Das Datasets MCP lädt bewusst nicht automatisch vollständige Semantic-Scholar-Datasets herunter.

Einige Semantic-Scholar-Datasets sind sehr groß. Das Abrufen eines Manifests ist eine geeignete MCP-Operation; das Starten eines Multi-Gigabyte-Korpus-Downloads erfordert explizite benutzergesteuerte Tools.

Ein künftiges dediziertes CLI könnte Befehle bereitstellen wie:

s2-dataset download ...
s2-dataset update ...
s2-dataset verify ...

ohne diese Operationen zu implizitem MCP-Verhalten zu machen.

Determinismus

Für dieses Projekt bedeutet deterministisch, dass die Tool-Semantik explizit und überprüfbar ist.

Ein Tool darf:

validate input
    ↓
wait for rate limiter
    ↓
make one documented API request
    ↓
retry transient transport failures if necessary
    ↓
normalize response
    ↓
return structured data

Ein Tool darf nicht stillschweigend zu Folgendem werden:

search
   ↓
search again with different terms
   ↓
fetch every page
   ↓
walk citations
   ↓
request recommendations
   ↓
rank with an LLM
   ↓
summarize papers

Die Orchestrierung auf höherer Ebene gehört außerhalb dieses Repositorys.

Paginierung

Die Paginierung wird vom Aufrufer gesteuert.

Wenn Semantic Scholar ein Fortsetzungstoken, einen Offset oder einen gleichwertigen Cursor zurückgibt, gibt der MCP-Server diesen Wert zurück.

Der Aufrufer kann explizit eine weitere Seite anfordern.

Der MCP-Server holt nicht automatisch alle verfügbaren Seiten.

Dies schützt sowohl Determinismus als auch API-Nutzung.

Felder

Wo Semantic Scholar explizite Antwortfelder unterstützt, sollten Tools nur die vom Aufrufer benötigten Felder anfordern.

Für die Benutzerfreundlichkeit kann ein kleiner Standardfeldsatz bereitgestellt werden.

Große Felder wie Abstracts oder Zitationskontexte sollten nicht automatisch angefordert werden, sofern sie nicht Teil des dokumentierten Tool-Standards sind.

Fehler

Upstream-Bedingungen sollten in stabile, verständliche MCP-Fehler übersetzt werden.

Beispiele:

authentication_required
rate_limited
not_found
invalid_request
upstream_error
transport_error

Wo nützlich, kann der strukturierte Fehler Folgendes beibehalten:

• HTTP-Status;

• Wiederholbarkeit;

• Anzahl der Versuche;

• Semantic Scholar-Fehlermeldung.

Geheimnisse dürfen niemals enthalten sein.

Entwicklung

Unit-Tests ausführen:

pytest

Linting ausführen:

ruff check .

Formatierung prüfen:

ruff format --check .

Formatierung anwenden:

ruff format .

Live-Semantic-Scholar-Tests sind separat gekennzeichnet:

pytest --run-integration

Normale Unit-Tests sollten HTTP-Interaktionen mocken und dürfen kein Semantic Scholar API-Kontingent verbrauchen.

Testphilosophie

Die wichtigsten Tests verifizieren die API-Treue.

Für jedes MCP-Tool sollten Tests Folgendes bestätigen:

input
  ↓
exact expected HTTP operation
  ↓
expected response normalization

Tests sollten außerdem das Fehlen versteckten Verhaltens überprüfen.

Beispielsweise sollte eine einzelne Zitationsanfrage genau einen Zitations-API-Vorgang auslösen – nicht automatisch nachfolgende Seiten oder Referenzen anfordern.

Beziehung zu Forschungswerkzeugen

Dieses Repository sollte domänenneutral bleiben.

Zum Beispiel kann es Folgendes bereitstellen:

paper A cites paper B

oder:

Semantic Scholar recommends paper C from seeds A and B

es sollte jedoch nicht den Schluss ziehen:

paper C is the strongest evidence for a particular neuroscience hypothesis

Ein separates Forschungs-Repository, Research MCP, oder ein menschlicher Forscher kann diese Interpretation vornehmen.

Diese Trennung ermöglicht es der Semantic Scholar-Ebene, weiterhin Folgendes zu sein:

• deterministisch;

• wiederverwendbar;

• einfach zu testen;

• unabhängig von jedem spezifischen wissenschaftlichen Gebiet;

• nutzbar durch verschiedene MCP-Hosts und Agenten.

Nutzung von Semantic Scholar

Dieses Projekt ist für legitime Forschungszwecke gedacht und muss die aktuelle Semantic Scholar API-Lizenz und -Dokumentation einhalten.

Die API-Nutzung sollte:

• aktive Ratenlimits respektieren;

• Batch-/Massenoperationen verwenden, wo angemessen;

• nur benötigte Felder anfordern;

• begrenzten exponentiellen Backoff verwenden;

• API-Zugangsdaten schützen;

• uneingeschränktes API-Crawling vermeiden;

• die Datasets-API bevorzugen, wenn wirklich korpusweiter Zugriff erforderlich ist.

Öffentliche Produkte oder Darstellungen, die Antwortdaten von Semantic Scholar verwenden, können zusätzliche Anforderungen an die Quellenangabe haben. Überprüfen Sie die aktuelle Semantic Scholar-Lizenz, bevor Sie eine öffentlich sichtbare Datenpräsentation hinzufügen.

Siehe AGENTS.md für die normativen Entwicklungs- und API-Nutzungsregeln für dieses Repository.