jstage-mcp

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

用途

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

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

在这里和 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 — 每响应中必需的署名行。

诊断代码

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

查询收据

每个信封都可以由 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" 按钮。

许可证

MIT © 2026 Christopher Gerteis。

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

免责声明

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

作者

Dr Christopher Gerteis，SOAS University of London。