de en es ja ko ru zh

jstage-mcp

Name: jstage-mcp
Author: ckgerteis

by ckgerteis

Overview Schema Source Related Servers Discussions Admin

Python

Local

jstage-mcp

一个 FastMCP stdio 服务器，将 J-STAGE WebAPI 以三个工具的形式提供给 Claude Desktop 使用。

用途

J-STAGE 收录了日本学会出版的期刊全文，本工具在文章内部进行搜索，而非在目录中搜索。如果一个术语没有被编目员选作关键词，但作者在论证中使用过它，它仍然可以被找到，这使得本工具成为那些在命名之前已经流通的概念的搜索途径。

将 J-STAGE DOI 直接解析到其记录，或沿着期刊的卷期结构浏览，以查看完整的出版序列。

在这里和 cinii-mcp 上运行同一个术语并比较差异：两者差距很大时，可以判断你的词汇属于目录描述还是领域散文——这本身就是一个关于文献的发现，而不仅仅是在文献中的发现。

Related MCP server: Japan Data MCP

工具

工具	用途
`jstage_search_articles`	在 J-STAGE 文章中进行全文 / 作者 / 标题 / 期刊搜索
`jstage_list_issues`	获取已知标题、ISSN 或 `cdjournal` 的卷期结构
`jstage_get_article_by_doi`	将 J-STAGE DOI 解析到其完整文章记录

所有工具都返回一个带类型的 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 — 每响应中必需的署名行。

诊断代码

带类型且封闭。诊断绝不是客户端必须解析的散文。

代码	级别	含义
`OK`	信息	返回了记录；无需标记。
`BROAD_FULLTEXT`	警告	匹配是在全文上进行的，其中多词术语是松散匹配的，因此较高的 `result.total` 往往是噪声。
`SCRIPT_LATIN_QUERY`	警告	查询是拉丁字母，因此仅匹配了罗马化英文和英文元数据。请改用汉字或假名。
`LITERAL_COMPOUND_EMPTY`	警告	此渲染没有记录。尝试一个本族语或成分术语，或另一种日语渲染。
`API_ERROR`	错误	API 已响应，且响应为错误。
`TRANSPORT_ERROR`	错误	请求未完成。与 `API_ERROR` 区分是因为失败的搜索其结果未知，绝不能将其记录为不存在。
`RECEIPT_NOT_DEPOSITED`	信息	响应未写入查询账本，因为未配置收据目标。搜索不受影响；但没有收据存留。
`RECEIPT_WRITE_FAILED`	警告	已设置收据目标，写操作已尝试但未成功。与上一行区分是因为一个是选择，另一个是故障。

查询收据

每个信封都可以由 ledger.py 存储到一个仅追加的、哈希链式的 JSONL 日志中。默认是关闭的，除非设置了 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 于 2026 年 3 月 26 日宣布了一个期刊搜索端点（service=4），但公共 API 仍然拒绝该服务代码并返回 ERR_004；一个静默回退到卷搜索的工具并不是期刊搜索，这个服务器宁愿不提供它。在 JST 激活 service=4 之前，请对已知的标题、ISSN 或 cdjournal 使用 jstage_list_issues。
jstage_get_article_by_doi 要求 J-STAGE 签发的 DOI。 WebAPI 不暴露 doi= 查询参数。该工具将符合 J-STAGE 模式（10.<registrant>/<cdjournal>.<vol>.<no>_<page>）的 DOI 分解为 cdjournal+vol，并将结果与响应进行匹配。对于模式之外的 DOI，该工具返回 doi.org 解析 URL 并附注说明。
商业使用需要注册。 根据 JST 使用条款，商业用途需要向 contact@jstage.jst.go.jp 提交申请表。研究和教学用途不需要。

API 说明

端点：https://api.jstage.jst.go.jp/searchapi/do

使用的服务代码：

service=2 — 卷/期
service=3 — 文章搜索
service=4 — 期刊搜索（已记录，截至 2026 年 8 月 23 日以 ERR_004 拒绝；任何工具均未使用）

已确认可用于实时 API 的文章搜索查询参数： material, article, author, affil, keyword, abst, text, issn, cdjournal, vol, no, pubyearfrom, pubyearto, start, count。

署名

由 J-STAGE 提供支持

此字符串包含在每个工具响应中。

引用

如果此软件支持你的研究，请引用它。请参见 CITATION.cff，或使用 GitHub 上的 "Cite this repository" 按钮。

许可证

本许可证仅涵盖服务器代码。它不授予对 J-STAGE 内容或 J-STAGE WebAPI 的任何权利，这两者仍受 JST 的使用条款管辖。

免责声明

一个研究工具，以尽力而为的方式维护，并按“原样”提供，不附带任何担保。与 Japan Science and Technology Agency 无关联，亦未经其认可。JST 不提供对 WebAPI 的支持。

作者

Dr Christopher Gerteis，SOAS University of London。

Available Tools

3 tools

jstage_get_article_by_doiA

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

A4/5.0

Behavior4/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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_issuesA

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

A4.2/5.0

Behavior4/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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_articlesA

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

A4/5.0

Behavior5/5

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.

Conciseness4/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose4/5

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.

Usage Guidelines3/5

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 updatesv3.0.0Aug 27, 2026
- First observedjstage_get_article_by_doi
- First observedjstage_list_issues
- First observedjstage_search_articles

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.3/5.0

Scored 2026-09-08 22:20 across 3 tools

Disambiguation5/5

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.

Naming Consistency5/5

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.

Tool Count5/5

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.

Completeness4/5

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

ActivityNo data

ResponsivenessSyncing

Resources

Related MCP Connectors

Crossref Scholarly Data
io.github.Taru0208
Search 150M+ academic works, journals, and funders via Crossref API.
Search Research & Data Open Data
2
https://aligned-kettledrum--crossref-mcp-server.apify.actor/mcp
datacite-mcp-serverA
io.github.cyanheads
Search DataCite datasets and software, fetch DOI metadata, trace relations, format citations.
Research & Data Open Data Search
611
https://datacite.caseyjhand.com/mcp
OpenAlex Scientific Citation Graph & Research SearchC
io.ceadigital
Search 250M+ academic works, citation graphs, DOIs, and institutional research via OpenAlex.
Research & Data Search Open Data
281
https://ceadigital.io/mcp/openalex
Google Scholar Remote MCP ServerA
com.hasdata
Google Scholar search results, citation counts and citation export formats, as structured JSON.
Research & Data Search Web Scraping
3113
https://mcp.hasdata.com/api/mcp?apis=google_scholar

Related MCP Servers

cinii-mcp
Research & Data Open Data
ckgerteis
A
license
A
quality
A
maintenance
Enables querying Japan's national academic database, CiNii Research, for articles, books, dissertations, KAKEN projects, and researcher profiles via seven MCP tools.
Updated 5 days ago (2026-11-01 03:49 UTC)
11
3
MIT
Japan Data MCP
Government Data Open Data
yurukusa
A
license
Not graded
quality
D
maintenance
Enables AI agents to query Japanese public data (laws, corporations, statistics) from official government APIs, returning normalized English metadata with source attribution.
Updated 4 months ago (2026-07-06 11:13 UTC)
1
MIT
mcp-cinii
Research & Data Open Data
iwaokimura
A
license
A
quality
D
maintenance
Enables searching CiNii Research for academic articles, books, grants, and research data, and retrieving metadata for individual items.
Updated 4 months ago (2026-07-10 05:40 UTC)
2
MIT
crossref-mcp
Research & Data Open Data
jtl-neo
A
license
A
quality
C
maintenance
Enables scholarly metadata lookups from the Crossref REST API, including works, members, journals, funders, types, licenses, and prefixes, as tools for LLM clients.
Updated 4 months ago (2026-06-24 11:35 UTC)
18
39 PyPI
MIT