jstage-mcp
jstage-mcp
Сервер FastMCP stdio, предоставляющий J-STAGE WebAPI в виде трёх инструментов для использования с Claude Desktop.
Для чего это нужно
J-STAGE хранит полные тексты журналов, издаваемых японскими научными обществами, и этот сервер ищет внутри статей, а не по каталогу. Термин, который ни один каталогизатор не выбрал в качестве ключевого слова, всё равно можно найти, если автор использовал его в аргументации, что делает этот сервер маршрутом для концепций, которые циркулируют до того, как получают название.
Разрешите DOI J-STAGE прямо в его запись или пройдите по томам и выпускам журнала, чтобы увидеть весь ряд.
Запустите термин здесь и в cinii-mcp и прочитайте разрыв: большое расхождение говорит вам, принадлежит ли ваш словарь описанию каталога или прозе поля, что является выводом о литературе до того, как он станет выводом в ней.
Related MCP server: Japan Data MCP
Инструменты
Инструмент | Назначение |
| Полнотекстовый / по автору / по названию / по журналу поиск по статьям J-STAGE |
| Список томов и выпусков для известного названия, ISSN или |
| Разрешить DOI J-STAGE в полную запись статьи |
Все инструменты возвращают один типизированный 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— обязательная строка атрибуции, в каждом ответе.
Диагностические коды
Типизированные и закрытые. Диагностика никогда не является прозой, которую клиент должен разбирать.
Код | Уровень | Значение |
| info | Записи возвращены; нечего отмечать. |
| warning | Совпадение найдено по полному тексту, где многословные термины сопоставляются свободно, поэтому высокий |
| warning | Запрос был на латинице, поэтому он сопоставил только романизированные и английские метаданные. Повторите запрос на кандзи или кане. |
| warning | Нет записей для этого представления. Попробуйте эмический или компонентный термин, или альтернативное японское написание. |
| error | API ответил, и ответил с ошибкой. |
| error | Запрос не завершился. Отличается от |
| info | Ответ не был записан в журнал запросов, потому что не настроен пункт назначения квитанций. Поиск не затронут; никакая квитанция не сохраняется. |
| warning | Пункт назначения квитанций установлен, запись была предпринята, но не попала. Отличается от строки выше, потому что одно является выбором, а другое — ошибкой. |
Квитанции запросов
Каждый конверт может быть помещён в журнал 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.jsonverify завершается с ненулевым кодом при сбое и сообщает, какой именно вид он нашёл: развилку (параллельные писатели — ошибка конфигурации, и каждая строка всё ещё на месте), отсутствующую строку, переупорядочивание или вмешательство (строка, которая не хэшируется в своё собственное содержимое). Только последнее является утверждением о честности, и сообщение о них одинаково побудило бы читателя принять одно за другое. Манифест — это объект для цитирования: одно описание всего депозита — количество строк на файл, первая и последняя метки времени, конечные хэши и объединённые итоги по серверу, алфавиту и сеансу.
Установка
Пакет устанавливает консольный скрипт 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.
Available Tools
3 toolsjstage_get_article_by_doiARead-onlyIdempotent
Resolve a J-STAGE DOI to its article record. Returns the unified envelope (operation 'resolve_doi') with one item on success, or zero items plus a diagnostic when the DOI is not in J-STAGE's issuance pattern or is unmatched.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only/idempotent/non-destructive behavior. The description adds meaningful behavioral context beyond annotations by specifying the response envelope, the operation name ('resolve_doi'), and the success/failure contract (one item vs. zero items plus diagnostic). This clarifies what happens in edge cases, which is not covered by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary purpose and then the response behavior. There is no redundancy or unnecessary detail. Every sentence contributes to understanding the tool's function and outcomes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (one parameter) and the presence of an output schema, the description covers the essential aspects: the operation, success/failure representation, and error handling. It does not mention pagination or other complexities because they are not applicable. The schema description handles the parameter format. Overall, it is complete for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description for the 'doi' parameter already explains that it can be with or without the doi.org prefix, providing semantic meaning. Although the context signal says schema description coverage is 0%, the actual schema includes a description, so the baseline of 3 applies. The tool description adds no additional parameter information beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb 'resolve' and the resource 'a J-STAGE DOI to its article record.' It is specific and clearly distinguishes from the siblings (search_articles and list_issues) by focusing on DOI-based lookup. The purpose is immediately understandable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly mention when to use this tool versus the alternatives. However, the purpose (DOI to article) strongly implies usage when a DOI is available. There are no explicit exclusions or comparisons to siblings, so guidance is only implied, not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
jstage_list_issuesARead-onlyIdempotent
Return the volume/issue spine of a journal (by material/issn/cdjournal).
Navigation aid, not literature retrieval: returns structural JSON (volumes with publisher/journal metadata), not the record envelope.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the description does not repeat those. It adds useful behavioral context: the return is 'structural JSON (volumes with publisher/journal metadata), not the record envelope'. This clarifies the nature of the output beyond what annotations capture and reinforces the navigation-purpose distinction. It does not contradict any annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with the core purpose, and immediately clarifies what it is not. Every word earns its place; there is no redundant or vague language.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple (one params object) and the description covers the essential purpose and output shape. An output schema exists, so the detailed return structure is likely defined elsewhere. The description could elaborate on pagination (count/start) or use cases, but for a navigation aid the current level is adequate. The only minor gap is not mentioning the filtering options beyond identifiers, but they are in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% (description does not discuss the parameters object). The description mentions 'by material/issn/cdjournal', covering three of the seven fields, but omits count, start, pubyearfrom, and pubyearto. Given the low coverage, the description should compensate more, but it does highlight the primary identifiers. The schema itself provides titles and constraints for the remaining fields, so this is a partial compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Return the volume/issue spine of a journal'. It also differentiates from siblings by asserting it is a 'Navigation aid, not literature retrieval', which precisely matches the listing vs. search/article functions. This leaves no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: this is for navigation, not literature retrieval. It implies when to use it (when you need the structural spine) and when not (for literature retrieval, likely using search or get-article siblings). It also names the key identifiers ('by material/issn/cdjournal') but does not explicitly mention alternative tool names or exact conditions for choosing this over siblings. This is close to full guidance, but not explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
jstage_search_articlesARead-onlyIdempotent
Search articles on J-STAGE. Returns the unified response envelope.
J-STAGE matches text against full text and treats multi-word terms
loosely, so a high result.total is often noisy — read matching_mode
(full_text_broad), result.breadth, and the diagnostics before treating
a count as the size of a literature. A SCRIPT_LATIN_QUERY diagnostic means
the query matched Latin-script text and metadata only; re-issue in kanji/kana. The same
string can return very different totals on CiNii (metadata conjunction).
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the bar is lower, and the description still adds substantial context. It explains full-text broad matching, loose multi-word handling, the meaning of matching_mode/result.breadth/diagnostics, SCRIPT_LATIN_QUERY implications, and differences from CiNii. This goes far beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and then provides a dense but relevant paragraph of caveats. Every sentence earns its place, with no filler or repetition of annotation information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the search tool's complexity and the existing output schema, the description covers the response envelope, diagnostics, matching behavior, and cross-source caveats. It does not explicitly address when to choose this tool over siblings or provide examples, but the essential invocation and result-interpretation context is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% at the top level, but the nested schema properties have individual descriptions. The tool description adds meaningful semantics for the central text parameter, explaining full-text matching, noise, and re-issuing in kanji/kana, which is not in the schema. It does not discuss filters or pagination, but those are covered in the nested schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Search articles on J-STAGE' and 'Returns the unified response envelope,' clearly stating the verb, resource, and scope. It is distinguishable from siblings like jstage_list_issues and jstage_get_article_by_doi by the search focus, though it does not explicitly contrast itself with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives practical guidance for interpreting noisy results and re-issuing Latin-script queries in kanji/kana, which helps an agent act after receiving results. However, it does not explicitly state when to prefer this tool over the sibling tools or when not to use it, so usage selection is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
3 tool updates
v3.0.0- First observed
jstage_get_article_by_doi - First observed
jstage_list_issues - First observed
jstage_search_articles
TDQS
Scored across 3 tools
Each tool targets a distinct operation: full-text search, DOI resolution, and journal issue navigation. There is no real overlap between query-based retrieval and known-identifier lookup, and list_issues is explicitly separated from article record retrieval.
All tool names follow a consistent jstage_<verb>_<object> pattern using snake_case and a shared prefix. The verbs search, get, and list are predictable and clearly map to their respective actions.
Three tools is at the lower end of a well-scoped range, but each tool earns its place by covering a core workflow. The count feels minimal yet sufficient for a focused J-STAGE article server.
Core discovery workflows are covered: searching articles, resolving a DOI, and navigating journal issues. Minor gaps exist for directly listing articles inside a specific issue or retrieving articles by non-DOI identifiers, but these are workable via search.
Maintenance
Related MCP Connectors
Search 150M+ academic works, journals, and funders via Crossref API.
Search DataCite datasets and software, fetch DOI metadata, trace relations, format citations.
Google Scholar search results, citation counts and citation export formats, as structured JSON.
Wikipedia, Wikidata and Wiktionary as clean JSON, not HTML. 1.9M searchable. Free, no auth.
Related MCP Servers
- AlicenseAqualityAmaintenanceEnables querying Japan's national academic database, CiNii Research, for articles, books, dissertations, KAKEN projects, and researcher profiles via seven MCP tools.72MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to query Japanese public data (laws, corporations, statistics) from official government APIs, returning normalized English metadata with source attribution.1MIT
- AlicenseAqualityDmaintenanceEnables searching CiNii Research for academic articles, books, grants, and research data, and retrieving metadata for individual items.2MIT
- AlicenseAqualityCmaintenanceEnables scholarly metadata lookups from the Crossref REST API, including works, members, journals, funders, types, licenses, and prefixes, as tools for LLM clients.1847 PyPIMIT