jstage-mcp

Сервер FastMCP stdio, предоставляющий J-STAGE WebAPI в виде трёх инструментов для использования с Claude Desktop.

Для чего это нужно

J-STAGE хранит полные тексты журналов, издаваемых японскими научными обществами, и этот сервер ищет внутри статей, а не по каталогу. Термин, который ни один каталогизатор не выбрал в качестве ключевого слова, всё равно можно найти, если автор использовал его в аргументации, что делает этот сервер маршрутом для концепций, которые циркулируют до того, как получают название.

Разрешите DOI J-STAGE прямо в его запись или пройдите по томам и выпускам журнала, чтобы увидеть весь ряд.

Запустите термин здесь и в cinii-mcp и прочитайте разрыв: большое расхождение говорит вам, принадлежит ли ваш словарь описанию каталога или прозе поля, что является выводом о литературе до того, как он станет выводом в ней.

Related MCP server: Japan Data MCP

Инструменты

Все инструменты возвращают один типизированный JSON-конверт ответа с двуязычными (английский / японский) названиями, авторами и названиями журналов, где J-STAGE их предоставляет — см. Формат ответа ниже. Требование атрибуции JST выполняется полем attribution конверта, присутствующим в каждом ответе.

Формат ответа

Каждый инструмент возвращает один JSON-конверт ответа, созданный mediation.py и определённый в response-schema.json. Версия схемы 2.3.0. Один и тот же модуль и схема поставляются байт-идентично во всём семействе серверов, поэтому конверт от одного сервера может быть прочитан потребителем, написанным для другого.

Конверт сообщает, как был выполнен поиск, а не только то, что было найдено:

• searched_for — при поисковых операциях фактически отправленный термин, его обнаруженный алфавит и режим сопоставления, вынесенные в начало конверта, чтобы ретранслирующий клиент не мог его отбросить. Операции выборки (jstage_get_article_by_doi, jstage_list_issues) опускают его: им был передан идентификатор, и они не выбирали термин.

• query — input_terms как предоставлено, normalized как отправлено, и обнаруженный script. Эта пара является записью любого преобразования, выполненного между языком вызывающего и корпусом.

• matching_mode — full_text_broad для этого сервера. Он говорит вам, как читать result.total.

• result.breadth — none, narrow (1–50), broad (51–1000), very_broad (>1000). Пороги намеренно низкие: несколько сотен совпадений, которые выглядят как литература, помечаются, а не проходят без пометки.

• items[].matched_in — в каком поле было найдено совпадение, для каждой записи.

• receipt — метка времени ISO 8601, SHA-256, вычисленный по нормализованному запросу и его параметрам, и возвращённые идентификаторы. Хэш проверяет термин, который у вас уже есть; его нельзя инвертировать для получения термина, поэтому единицей депозита является конверт, а не квитанция.

• attribution — обязательная строка атрибуции, в каждом ответе.

Диагностические коды

Типизированные и закрытые. Диагностика никогда не является прозой, которую клиент должен разбирать.

Квитанции запросов

Каждый конверт может быть помещён в журнал JSONL, доступный только для добавления и с хэш-цепочкой, с помощью ledger.py. Он выключен, если не установлен MCP_RECEIPT_DIR (или устаревший MCP_RECEIPT_LOG), и сбой ведения журнала проглатывается, а не вызывается — поиск важнее, чем запись о нём. Секреты редактируются перед составлением строки.

Начиная со схемы 2.3.0 конверт говорит об этом. Когда ответ не депонируется, emit() добавляет RECEIPT_NOT_DEPOSITED, если переменная не установлена, или RECEIPT_WRITE_FAILED, если она установлена и запись не попала. Тогда разрыв виден в артефакте, который становится записью, а не только в файле конфигурации. mediation.deposit_enabled() сообщает тот же факт по запросу.

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

Папка и один файл на сервер. MCP_RECEIPT_DIR указывает на каталог, и каждый сервер записывает свой собственный <server>.jsonl внутри него. Это не опрятность. Добавление — это чтение последнего хэша, затем запись, и блокировка вокруг него — это блокировка потока, которая действует в пределах одного процесса, а не между несколькими — шесть серверов — это шесть процессов, и два, отвечающих в один и тот же момент, оба прочитают одного и того же предшественника и оба заявят на него права. Измерено, а не теоретизировано: шесть процессов, записывающих 150 строк в один файл, дали четырнадцать развилок. MCP_RECEIPT_LOG по-прежнему работает и по-прежнему корректен для одного сервера; это неправильная форма для семейства.

install.ps1 настраивает это для всех шести и записывает README в папку.

Проверьте одну цепочку или всю папку:

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

verify завершается с ненулевым кодом при сбое и сообщает, какой именно вид он нашёл: развилку (параллельные писатели — ошибка конфигурации, и каждая строка всё ещё на месте), отсутствующую строку, переупорядочивание или вмешательство (строка, которая не хэшируется в своё собственное содержимое). Только последнее является утверждением о честности, и сообщение о них одинаково побудило бы читателя принять одно за другое. Манифест — это объект для цитирования: одно описание всего депозита — количество строк на файл, первая и последняя метки времени, конечные хэши и объединённые итоги по серверу, алфавиту и сеансу.

Установка

Пакет устанавливает консольный скрипт jstage-mcp. Он имеет пространство имён, поэтому может разделять одно окружение с остальной частью этого семейства серверов.

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

В Windows:

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

Или прямо из репозитория, без клонирования:

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

Проверьте установку:

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

Это громко завершится ошибкой, если пакет или один из его поставляемых модулей отсутствует. Не используйте jstage-mcp --help в качестве проверки: неизвестные аргументы игнорируются, сервер запускается, читает конец ввода и завершается с кодом 0, поэтому он сообщает об успехе независимо от состояния кода.

Установка более чем одного

Шесть независимых пакетов. Ни один не импортирует другой, ни один не зависит от другого, и каждый устанавливается и отвечает сам по себе — pip install . в этом каталоге является полной установкой этого сервера и ничего больше.

Они разделяют три вещи: конверт ответа, журнал запросов и — если вы запускаете более одного — папку квитанций. install.ps1 поставляется байт-идентично во все шесть и обрабатывает это. Он устанавливает этот сервер по умолчанию, потому что клонирование одного репозитория не является запросом на пять дополнительных.

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

Любой подмножество, которое вы назовёте, регистрируется в одной папке квитанций, запрашивается один раз. Скрипт предпочитает соседнюю копию сети, переносит уже зарегистрированные учётные данные, а не спрашивает снова, оставляет серверы, о которых его не просили, в покое и останавливается, а не угадывает, где уже зарегистрированные серверы расходятся в отношении папки или ярлыка сеанса. Он также утверждает, что ledger.py и mediation.py байт-идентичны во всём, что он установил, чтобы две версии конверта не могли незаметно оказаться в одном окружении.

Конфигурация Claude Desktop

Добавьте запись в %APPDATA%\Claude\claude_desktop_config.json в раздел mcpServers, указывающую на консольный скрипт в окружении, в которое вы установили. В macOS или Linux используйте абсолютный путь к .venv/bin/jstage-mcp.

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

Изменено в 3.0.0. Более ранние версии регистрировались по пути — "command": "…\\python.exe", "args": ["…\\server.py"]. Эта запись не запустит эту версию, потому что server.py теперь является модулем внутри пакета, а не скриптом рядом с его импортами. Замените её на консольный скрипт выше.

Перезапустите Claude Desktop. Три инструмента должны появиться в разделе «jstage» в списке инструментов.

Ограничение скорости

Сервер обеспечивает минимальный интервал в одну секунду между исходящими запросами в соответствии с запретом JST на массовые загрузки. Лимит действует на процесс; если вы запускаете несколько сеансов Claude Desktop одновременно, вы можете его превысить, так что не делайте этого.

Ограничения

• Нет инструмента поиска журналов. jstage_search_journals существовал в v1.x и был удалён в v2.0.0. J-STAGE объявил конечную точку поиска журналов (service=4) 26 марта 2026 года, и публичный API всё ещё отклоняет этот код службы с ERR_004; инструмент, который молча возвращается к поиску по томам, не является поиском журналов, и этот сервер предпочёл бы не предлагать такой. Пока JST не активирует service=4, используйте jstage_list_issues с известным названием, ISSN или cdjournal.

• jstage_get_article_by_doi требует DOI, выданные J-STAGE. WebAPI не предоставляет параметр запроса doi=. Инструмент разбирает DOI, соответствующие шаблону J-STAGE (10.<registrant>/<cdjournal>.<vol>.<no>_<page>), на cdjournal+vol и сопоставляет результат с ответом. Для DOI вне этого шаблона инструмент возвращает URL разрешения doi.org с примечанием.

• Коммерческое использование требует регистрации. Согласно Условиям использования JST, для коммерческого использования требуется форма заявки, отправленная на contact@jstage.jst.go.jp. Для исследовательских и учебных целей это не требуется.

Примечания к API

Конечная точка: https://api.jstage.jst.go.jp/searchapi/do

Используемые коды служб:

• service=2 — Тома/выпуски

• service=3 — Поиск статей

• service=4 — Поиск журналов (документирован, отклоняется с ERR_004 по состоянию на 23 августа 2026 г.; не используется ни одним инструментом)

Допустимые параметры запроса поиска статей, подтверждённые на живом API: material, article, author, affil, keyword, abst, text, issn, cdjournal, vol, no, pubyearfrom, pubyearto, start, count.

Атрибуция

Работает на J-STAGE

Эта строка включена в каждый ответ инструмента.

Цитирование

Если это программное обеспечение поддерживает ваше исследование, пожалуйста, процитируйте его. См. CITATION.cff или используйте кнопку «Cite this repository» на GitHub.

Лицензия

MIT © 2026 Christopher Gerteis.

Эта лицензия распространяется только на серверный код. Она не предоставляет никаких прав на контент J-STAGE или J-STAGE WebAPI, которые остаются под управлением Условий использования JST.

Отказ от ответственности

Исследовательский инструмент, поддерживаемый на основе принципа «наилучших усилий» и предоставляемый «как есть», без каких-либо гарантий. Не аффилирован с Japan Science and Technology Agency и не одобрен ею. JST не предоставляет поддержку для WebAPI.

Автор

Dr Christopher Gerteis, SOAS University of London.