jstage-mcp

J-STAGE WebAPI를 세 가지 도구로 노출하는 FastMCP stdio 서버로, Claude Desktop에서 사용할 수 있습니다.

용도

J-STAGE는 일본 학회가 발행하는 학술지의 전문(full text)을 보유하고 있으며, 이 서버는 목록(catalogue)이 아닌 논문 내부를 검색합니다. 목록 작성자가 키워드로 선택하지 않은 용어라도 저자가 논증에서 사용했다면 찾을 수 있으므로, 아직 명명되기 전에 유통되는 개념을 추적하는 경로가 됩니다.

J-STAGE DOI를 레코드로 직접 변환하거나, 학술지의 권·호 체계를 따라 전체 발행분을 살펴볼 수 있습니다.

이 서버와 cinii-mcp에서 동일한 용어를 검색하고 그 차이를 읽어 보십시오. 큰 차이는 해당 용어가 목록 기술(description)에 속하는지, 학계의 산문에 속하는지를 알려주며, 이는 문헌 안에서의 발견이기 전에 문헌에 관한 발견입니다.

Related MCP server: Japan Data MCP

도구

모든 도구는 J-STAGE가 제공하는 경우 이중 언어(영어/일본어) 제목, 저자, 학술지 이름을 포함하는 단일 유형의 JSON 응답 봉투(envelope)를 반환합니다 — 아래 응답 형식 참조. JST 귀속(attribution) 요구 사항은 모든 응답에 포함된 봉투의 attribution 필드로 충족됩니다.

응답 형식

모든 도구는 mediation.py가 구성하고 response-schema.json에 정의된 단일 JSON 응답 봉투를 반환합니다. 스키마 버전 2.3.0. 동일한 모듈과 스키마가 서버 제품군 전체에 바이트 단위로 동일하게(vendored) 포함되므로, 한 서버의 봉투는 다른 서버용으로 작성된 소비자(consumer)가 읽을 수 있습니다.

봉투는 무엇을 찾았는지뿐 아니라 어떻게 검색했는지도 보고합니다:

• searched_for — 검색 작업에서 실제로 전송된 용어, 감지된 문자 체계(script), 일치 모드를 봉투 상단에 올려 중계 클라이언트가 이를 누락할 수 없게 합니다. 가져오기 작업(jstage_get_article_by_doi, jstage_list_issues)에서는 생략됩니다. 식별자를 전달받았고 용어를 선택하지 않았기 때문입니다.

• query — 제공된 input_terms, 전송된 normalized, 감지된 script. 이 쌍은 호출자의 언어와 말뭉치(corpus) 사이에서 수행된 모든 렌더링의 기록입니다.

• 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, 반환된 식별자. 해시는 이미 보유한 용어를 검증할 수 있지만 역산하여 용어를 생성할 수는 없으므로, 예치(deposit)의 단위는 receipt가 아닌 봉투입니다.

• attribution — 모든 응답에 포함된 필수 크레딧 문구.

진단 코드

유형화되고 폐쇄적입니다. 진단은 클라이언트가 파싱해야 하는 산문이 아닙니다.

쿼리 receipts

모든 봉투는 ledger.py에 의해 추가 전용(append-only), 해시 체인 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을 작성합니다. 이는 정리정돈이 아닙니다. 추가는 마지막 해시를 읽고 쓰는 방식이며, 그 주변의 잠금은 스레드 잠금으로 하나의 프로세스 내에서만 유효하고 여러 프로세스 간에는 유효하지 않습니다 — 여섯 서버는 여섯 프로세스이며, 동시에 응답하는 두 서버는 동일한 선행자를 읽고 둘 다 이를 선행자로 주장하게 됩니다. 이론이 아닌 측정 결과입니다: 6개 프로세스가 한 파일에 150줄을 쓰는 동안 14개의 포크(fork)가 발생했습니다. 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는 실패 시 0이 아닌 종료 코드를 반환하고 발견한 종류를 알려줍니다: 포크(동시 작성자 — 구성 오류이며 모든 줄은 여전히 존재), 누락 줄, 순서 변경, 또는 변조(자체 내용에 해시되지 않는 줄). 마지막 것만 정직성에 관한 주장이며, 이를 동일하게 보고하면 독자가 둘을 혼동하게 될 수 있습니다. 매니페스트(manifest)가 인용 대상입니다: 전체 예치물에 대한 하나의 설명 — 파일별 줄 수, 첫 번째 및 마지막 타임스탬프, 최종 해시, 서버·문자 체계·세션별 합계.

설치

패키지는 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 .은 이 서버만의 완전한 설치이며 다른 것은 없습니다.

단, 세 가지를 공유합니다: 응답 봉투, 쿼리 원장, 그리고 둘 이상을 실행하는 경우 receipts 폴더. install.ps1은 여섯 서버 모두에 바이트 단위로 동일하게 포함되며 이를 처리합니다. 기본적으로 이 서버를 설치합니다. 저장소 하나를 클론하는 것이 다섯 개를 더 요청하는 것이 아니기 때문입니다.

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

이름을 지정한 하위 집합이 무엇이든 한 번만 요청되는 단일 receipts 폴더에 등록됩니다. 스크립트는 네트워크보다 형제 체크아웃을 선호하고, 이미 등록된 자격 증명을 다시 묻지 않고 전달하며, 요청되지 않은 서버는 건드리지 않고, 이미 등록된 서버가 폴더나 세션 슬러그에 대해 의견이 다르면 추측하지 않고 중지합니다. 또한 설치한 모든 항목에서 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의 대량 다운로드 금지에 따라 아웃바운드 요청 사이에 1초의 최소 간격을 적용합니다. 제한은 프로세스별입니다. 여러 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.

귀속

Powered by J-STAGE

이 문자열은 모든 도구 응답에 포함됩니다.

인용

이 소프트웨어가 연구를 지원한다면 인용해 주십시오. CITATION.cff를 참조하거나 GitHub의 "Cite this repository" 버튼을 사용하십시오.

라이선스

MIT © 2026 Christopher Gerteis.

이 라이선스는 서버 코드에만 적용됩니다. J-STAGE 콘텐츠 또는 J-STAGE WebAPI에 대한 권한은 부여하지 않으며, 이는 JST의 이용 약관에 따라 관리됩니다.

면책 조항

최선의 노력으로 유지 관리되고 보증 없이 "있는 그대로" 제공되는 연구 도구입니다. 일본과학기술진흥기구(JST)와 제휴하거나 보증하지 않습니다. JST는 WebAPI에 대한 지원을 제공하지 않습니다.

저자

Dr Christopher Gerteis, SOAS University of London.