jstage-mcp

Ein FastMCP- Stdio-Server, der die J-STAGE WebAPI als drei Tools für die Verwendung mit Claude Desktop bereitstellt.

Wozu das dient

J-STAGE enthält die Volltexte von Zeitschriften, die von japanischen wissenschaftlichen Gesellschaften veröffentlicht werden, und dieses Tool durchsucht die Artikel selbst und nicht einen Katalog. Ein Begriff, den kein Katalogisierer als Schlagwort gewählt hat, ist dennoch auffindbar, wenn ein Autor ihn in einem Argument verwendet hat – das macht dies zum Weg für Konzepte, die zirkulieren, bevor sie benannt werden.

Lösen Sie eine J-STAGE-DOI direkt zu ihrem Datensatz auf, oder gehen Sie die Band- und Heftfolge einer Zeitschrift durch, um einen vollständigen Jahrgang zu sehen.

Führen Sie einen Begriff hier und auf cinii-mcp aus und lesen Sie die Differenz: Eine große Abweichung zeigt Ihnen, ob Ihre Terminologie zur Katalogbeschreibung gehört oder zur Prosa des Fachgebiets – ein Befund über die Literatur, bevor er ein Befund in ihr ist.

Related MCP server: Japan Data MCP

Tools

Alle Tools geben ein typisiertes JSON-Antwort-Envelope mit zweisprachigen (Englisch/Japanisch) Titeln, Autoren und Zeitschriftennamen zurück, sofern J-STAGE sie liefert – siehe Antwortformat unten. Die JST-Namensnennungspflicht wird durch das attribution-Feld des Envelopes erfüllt, das in jeder Antwort enthalten ist.

Antwortformat

Jedes Tool gibt ein JSON-Antwort-Envelope zurück, das von mediation.py erstellt und in response-schema.json definiert ist. Schema-Version 2.3.0. Dasselbe Modul und dasselbe Schema sind byte-identisch über die Serverfamilie hinweg gebündelt, sodass ein Envelope von einem Server von einem Client gelesen werden kann, der für einen anderen geschrieben wurde.

Das Envelope berichtet, wie die Suche durchgeführt wurde, nicht nur, was sie gefunden hat:

• searched_for — bei Suchvorgängen der tatsächlich gesendete Begriff, seine erkannte Schrift und der Abgleichmodus, an die Spitze des Envelopes gehoben, damit ein weiterleitender Client ihn nicht verwerfen kann. Abrufoperationen (jstage_get_article_by_doi, jstage_list_issues) lassen ihn weg: Sie haben eine Kennung erhalten und keinen Begriff gewählt.

• query — input_terms wie angegeben, normalized wie gesendet und das erkannte script. Dieses Paar ist die Aufzeichnung jeder Umsetzung, die zwischen der Sprache des Aufrufers und dem Korpus vorgenommen wurde.

• matching_mode — full_text_broad für diesen Server. Es sagt Ihnen, wie result.total zu lesen ist.

• result.breadth — none, narrow (1–50), broad (51–1000), very_broad (>1000). Die Schwellenwerte sind bewusst niedrig: ein paar hundert Treffer, die wie ein Literaturbestand wirken, werden markiert und nicht unbeanstandet durchgereicht.

• items[].matched_in — in welchem Feld der Treffer erzielt wurde, pro Datensatz.

• receipt — ein ISO-8601-Zeitstempel, ein SHA-256 über die normalisierte Abfrage und ihre Parameter sowie die zurückgegebenen Kennungen. Der Hash verifiziert einen Begriff, den Sie bereits besitzen; er kann nicht umgekehrt werden, um einen zu erzeugen, also ist die Einheit der Hinterlegung das Envelope, nicht der Beleg.

• attribution — die erforderliche Quellenangabe, in jeder Antwort.

Diagnosecodes

Typisiert und abgeschlossen. Eine Diagnose ist nie Prosa, die der Client parsen muss.

Abfragebelege

Jedes Envelope kann von ledger.py in ein Append-only-JSONL-Log mit Hash-Verkettung hinterlegt werden. Es ist aus, sofern nicht MCP_RECEIPT_DIR (oder das veraltete MCP_RECEIPT_LOG) gesetzt ist, und ein Protokollierungsfehler wird verschluckt statt ausgelöst – eine Suche ist wichtiger als ihre Aufzeichnung. Geheimnisse werden geschwärzt, bevor eine Zeile erstellt wird.

Seit Schema 2.3.0 macht das Envelope dies deutlich. Wenn eine Antwort nicht hinterlegt wird, hängt emit() RECEIPT_NOT_DEPOSITED an, wenn die Variable nicht gesetzt ist, oder RECEIPT_WRITE_FAILED, wenn sie gesetzt ist und der Schreibvorgang nicht angekommen ist. Die Lücke ist dann in dem Artefakt sichtbar, das zur Aufzeichnung wird, statt nur in einer Konfigurationsdatei. mediation.deposit_enabled() meldet denselben Sachverhalt auf Anfrage.

MCP_RECEIPT_DIR=C:\path\to\receipts        # a folder, not a file
MCP_RECEIPT_SESSION=project-or-article-slug
MCP_RECEIPT_STRICT=1                         # optional: make logging failure raise
MCP_RECEIPT_LOG=C:\path\to\receipts.jsonl  # legacy single file; ignored when _DIR is set

Ein Ordner, und eine Datei pro Server. MCP_RECEIPT_DIR zeigt auf ein Verzeichnis, und jeder Server schreibt sein eigenes <server>.jsonl hinein. Das ist keine Ordnungsliebe. Anhängen bedeutet „letzten Hash lesen, dann schreiben“, und die Sperre darum ist eine Thread-Sperre, die innerhalb eines Prozesses gilt und nicht zwischen mehreren – sechs Server sind sechs Prozesse, und zwei, die im selben Moment antworten, lesen beide denselben Vorgänger und beanspruchen beide ihn. Gemessen, nicht theoretisiert: Sechs Prozesse, die 150 Zeilen in eine Datei schreiben, erzeugten vierzehn Forks. MCP_RECEIPT_LOG funktioniert weiterhin und ist für einen einzelnen Server weiterhin korrekt; es ist die falsche Form für eine Familie.

install.ps1 richtet dies für alle sechs ein und schreibt eine README in den Ordner.

Prüfen Sie eine Kette oder den gesamten Ordner:

jstage-mcp-ledger verify      receipts/jstage.jsonl
jstage-mcp-ledger verify-dir  receipts
jstage-mcp-ledger manifest    receipts        # writes receipts/manifest.json

verify beendet sich bei einem Fehler mit einem Exitcode ungleich Null und teilt mit, welche Art es gefunden hat: einen Fork (gleichzeitige Schreiber – ein Konfigurationsfehler, und jede Zeile ist trotzdem noch vorhanden), eine fehlende Zeile, eine Umordnung oder Manipulation (eine Zeile, deren Hash nicht zu ihrem eigenen Inhalt passt). Nur Letzteres ist eine Aussage über Ehrlichkeit, und sie gleich zu melden, würde einen Leser dazu einladen, eines für das andere zu halten. Das Manifest ist das anzuführende Objekt: eine Beschreibung der gesamten Hinterlegung – Zeilenzahlen pro Datei, erste und letzte Zeitstempel, End-Hashes und kombinierte Summen nach Server, Schriftsystem und Sitzung.

Installation

Das Paket installiert ein Konsolenskript mit dem Namen jstage-mcp. Es ist in einen Namensraum eingebettet, sodass es sich eine Umgebung mit dem Rest dieser Serverfamilie teilen kann.

python3 -m venv .venv
.venv/bin/pip install .

Unter Windows:

py -3.11 -m venv .venv
.venv\Scripts\pip.exe install .

Oder direkt aus dem Repository, ohne Klonen:

uvx --from "git+https://github.com/ckgerteis/jstage-mcp" jstage-mcp

Installation prüfen:

.venv/bin/python -c "import jstage_mcp; print(jstage_mcp.__version__)"

Das schlägt laut fehl, wenn das Paket oder eines seiner gebündelten Module fehlt. Verwenden Sie nicht jstage-mcp --help als Prüfung: unbekannte Argumente werden ignoriert, der Server startet, liest das Eingabeende und beendet sich mit Exitcode 0, sodass er unabhängig vom Zustand des Codes Erfolg meldet.

Installation weiterer Pakete

Sechs unabhängige Pakete. Keins importiert ein anderes, keins hängt von einem anderen ab, und jedes installiert und antwortet für sich – pip install . in diesem Verzeichnis ist eine vollständige Installation dieses Servers und sonst nichts.

Sie teilen sich jedoch drei Dinge: ein Antwort-Envelope, ein Abfragejournal und – wenn Sie mehr als einen ausführen – einen Belegordner. install.ps1 ist byte-identisch in alle sechs eingebettet und übernimmt das. Es installiert standardmäßig diesen Server, denn das Klonen eines Repositorys ist keine Anfrage nach fünf weiteren.

.\install.ps1                        # this server
.\install.ps1 -All                   # all six
.\install.ps1 -Servers jstage,cinii        # a chosen subset

Welche Teilmenge Sie auch immer nennen, sie wird gegen einen einzigen Belegordner registriert, nach dem nur einmal gefragt wird. Das Skript zieht ein Checkout in einem benachbarten Verzeichnis dem Netzwerk vor, übernimmt bereits registrierte Anmeldedaten, statt erneut zu fragen, lässt Server, nach denen es nicht gefragt wurde, unangetastet und stoppt, anstatt zu raten, wenn die bereits registrierten Server beim Ordner oder beim Sitzungs-Slug voneinander abweichen. Es prüft außerdem, dass ledger.py und mediation.py über alles, was es installiert hat, byte-identisch sind, sodass nicht unbemerkt zwei Envelope-Versionen in einer Umgebung landen können.

Claude-Desktop-Konfiguration

Fügen Sie unter mcpServers einen Eintrag zu %APPDATA%\Claude\claude_desktop_config.json hinzu, der auf das Konsolenskript in der Umgebung zeigt, in die Sie installiert haben. Verwenden Sie unter macOS oder Linux den absoluten Pfad zu .venv/bin/jstage-mcp.

{
  "mcpServers": {
    "jstage": {
      "command": "C:\\path\\to\\.venv\\Scripts\\jstage-mcp.exe"
    }
  }
}

Geändert in 3.0.0. Frühere Versionen wurden per Pfad registriert – "command": "…\\python.exe", "args": ["…\\server.py"]. Dieser Eintrag wird diese Version nicht starten, denn server.py ist jetzt ein Modul innerhalb eines Pakets und kein Skript neben seinen Importen. Ersetzen Sie ihn durch das obige Konsolenskript.

Starten Sie Claude Desktop neu. Die drei Tools sollten in der Tool-Liste unter „jstage“ erscheinen.

Ratenbegrenzung

Der Server erzwingt ein Mindestintervall von einer Sekunde zwischen ausgehenden Anfragen, im Einklang mit JSTs Verbot von Massendownloads. Das Limit gilt pro Prozess; wenn Sie mehrere Claude-Desktop-Sitzungen gleichzeitig ausführen, können Sie es überschreiten – also tun Sie das nicht.

Einschränkungen

• Es gibt kein Zeitschriftensuch-Tool. jstage_search_journals existierte in v1.x und wurde in v2.0.0 entfernt. J-STAGE hat am 26. März 2026 einen Zeitschriftensuch-Endpunkt (service=4) angekündigt, und die öffentliche API lehnt diesen Servicecode weiterhin mit ERR_004 ab; ein Tool, das stillschweigend auf die Bandsuche zurückfällt, ist keine Zeitschriftensuche, und dieser Server möchte lieber keins anbieten. Bis JST service=4 aktiviert, verwenden Sie jstage_list_issues mit einem bekannten Titel, einer ISSN oder cdjournal.

• jstage_get_article_by_doi erfordert von J-STAGE vergebene DOIs. Die WebAPI bietet keinen doi=-Abfrageparameter an. Das Tool zerlegt DOIs, die dem Muster von J-STAGE folgen (10.<registrant>.<cdjournal>.<vol>.<no>_<page>), in cdjournal+vol und gleicht das Ergebnis mit der Antwort ab. Für DOIs außerhalb dieses Musters gibt das Tool die Auflösungs-URL von doi.org mit einem Hinweis zurück.

• Kommerzielle Nutzung erfordert eine Registrierung. Gemäß den JST-Nutzungsbedingungen erfordert die kommerzielle Nutzung ein Antragsformular, das an contact@jstage.jst.go.jp gesendet wird. Forschungs- und Lehrnutzung nicht.

API-Hinweise

Endpunkt: https://api.jstage.jst.go.jp/searchapi/do

Verwendete Servicecodes:

• service=2 — Bände/Hefte

• service=3 — Artikelsuche

• service=4 — Zeitschriftensuche (dokumentiert, wird mit Stand 23. August 2026 mit ERR_004 abgelehnt; von keinem Tool verwendet)

Gültige Artikelsuch-Abfrageparameter, gegen die Live-API bestätigt: material, article, author, affil, keyword, abst, text, issn, cdjournal, vol, no, pubyearfrom, pubyearto, start, count.

Namensnennung

Powered by J-STAGE

Diese Zeichenkette ist in jeder Tool-Antwort enthalten.

Zitation

Wenn diese Software Ihre Forschung unterstützt, zitieren Sie sie bitte. Siehe CITATION.cff oder verwenden Sie den Button „Cite this repository“ auf GitHub.

Lizenz

MIT © 2026 Christopher Gerteis.

Diese Lizenz gilt nur für den Servercode. Sie gewährt keine Rechte an J-STAGE-Inhalten oder der J-STAGE-WebAPI, die weiterhin den Nutzungsbedingungen von JST unterliegen.

Haftungsausschluss

Ein Forschungstool, das nach bestem Bemühen gepflegt und ohne Gewährleistung „wie besehen“ bereitgestellt wird. Es ist weder mit der Japan Science and Technology Agency verbunden noch von ihr unterstützt. JST bietet keinen Support für die WebAPI an.

Autor

Dr Christopher Gerteis, SOAS University of London.