@djmima/pubmed-mcp 1.2.2 → 1.2.3

package/CHANGELOG.md

@@ -1,77 +1,90 @@
-# 変更履歴
+# Changelog
 
-このプロジェクトの主な変更を記録します。
-書式は [Keep a Changelog](https://keepachangelog.com/ja/1.1.0/) に、バージョン番号は [セマンティック バージョニング](https://semver.org/lang/ja/) に従います。
+**English** · [日本語](CHANGELOG_ja.md)
+
+All notable changes to this project are recorded in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [1.2.3] - 2026-11-07
+
+### Added
+
+- Added an English changelog. `CHANGELOG.md` is now in English and `CHANGELOG_ja.md` in Japanese; both are included in the npm package.
+
+### Fixed
+
+- The npm package now includes the Japanese README (`README_ja.md`), which was missing.
+
 ## [1.2.2] - 2026-11-06
 
-### 変更
+### Changed
 
-- npm パッケージの説明に CLI を加えました。
+- The npm package description now mentions the CLI.
 
 ## [1.2.1] - 2026-11-05
 
-### 修正
+### Fixed
 
-- `search_articles`（CLI の `pubmed search`）で、NCBI の検索サーバーの障害時に `Cannot read properties of undefined (reading 'length')` で失敗していたのを、NCBI が返したエラーメッセージ（例: `Search is temporarily unavailable`）を返すようにしました。NCBI は障害時に HTTP 200 で ID の一覧のない応答を返すことがあり、これを検索結果として扱っていました。
+- `search_articles` (`pubmed search` in the CLI) failed with `Cannot read properties of undefined (reading 'length')` when NCBI's search servers had an outage. It now returns the error message NCBI sent (for example, `Search is temporarily unavailable`). During outages NCBI can answer with HTTP 200 and no list of IDs, and this response was treated as a search result.
 
 ## [1.2.0] - 2026-11-04
 
-### 追加
+### Added
 
-- CLI に `-v` / `--version` を追加しました。インストールされている `pubmed` のバージョンを表示します。
+- Added `-v` / `--version` to the CLI. It prints the version of the installed `pubmed`.
 
-### 修正
+### Fixed
 
-- MCP サーバーが `initialize` の応答（`serverInfo.version`）でバージョンを常に `1.0.0` と返していたのを、`package.json` のバージョンを返すようにしました。
+- The MCP server always reported its version as `1.0.0` in the `initialize` response (`serverInfo.version`). It now reports the version in `package.json`.
 
 ## [1.1.0] - 2026-11-04
 
-### 変更
+### Changed
 
-- **HTTP モードで `ALLOWED_SUBJECTS` を必須にしました。** 未設定または空のときは起動時に終了します。これまでは空のとき、認可サーバー（WorkOS AuthKit）で有効なトークンを取得できるユーザー全員が `/mcp` を使えました。
-- HTTP モードで、`/mcp` への GET と DELETE に 405 を返すようにしました。ステートレスなサーバーには GET で開く SSE ストリームに送るものがなく、開いたままのストリームがサーバーインスタンスと Cloud Run のリクエストを占有していました。
+- **`ALLOWED_SUBJECTS` is now required in HTTP mode.** The server exits at startup if it is unset or empty. Previously, when it was empty, anyone who could get a valid token from the authorization server (WorkOS AuthKit) could use `/mcp`.
+- In HTTP mode, GET and DELETE requests to `/mcp` now return 405. A stateless server has nothing to send on an SSE stream opened by GET, and open streams tied up server instances and Cloud Run requests.
 
-### セキュリティ
+### Security
 
-- MCP サーバーが `.env` を起動時のカレントディレクトリから読み込んでいたのをやめ、パッケージ自身のルート（ソースからビルドした場合はリポジトリ直下）からだけ読み込むようにしました（CLI はもともとこの動作です）。MCP クライアントは開いているプロジェクトのディレクトリでサーバーを起動するため、そのプロジェクトの `.env` に `PORT` があると HTTP モードで起動し、`HTTPS_PROXY` と `NODE_TLS_REJECT_UNAUTHORIZED=0` があると NCBI への通信（API キーを含む）を第三者のプロキシが読み書きできました。
-- ID を受け取るツール（`get_article_metadata`、`find_related_articles`、`get_copyright_status`、`get_full_text_article`、`convert_article_ids`）で、1 つの値に 1 つの ID だけを受け付けるようにしました。NCBI はカンマを ID の区切りとして扱うため、`"1,2,3"` のような値で 1 回あたりの上限を超える件数を取得できました。上限のなかった `find_related_articles` の `pmids` も 200 件までにしました。
-- `lookup_article_by_citation` で、引用の各項目に含まれる `|` と改行を空白に置き換えるようにしました。どちらも ECitMatch の区切り文字なので、項目がずれたり別の引用として送られたりして、結果が別の引用に対応づけられるおそれがありました。
-- NCBI へのリクエストに 60 秒のタイムアウトを設けました。応答のない接続で、ツールの呼び出し（HTTP モードではクライアントのリクエスト）が止まったままになることがなくなります。
-- NCBI へのリクエストがリダイレクトされたときは、HTTPS で `*.ncbi.nlm.nih.gov` に向かうものだけをたどるようにしました。API キーはクエリ文字列に含まれ、リダイレクト先にも引き継がれます。
-- エラーメッセージの中の API キーは、NCBI が返した本文のどこに現れても伏せるようにしました。ネットワークエラーには、API キーを含む axios のエラーオブジェクトを付けないようにしました。
-- HTTP モードで、`exp` と `sub` のないアクセストークンを拒否するようにしました。
-- HTTP モードで、リクエスト本文の JSON をトークンの検証後に解析するようにしました。不正な形式や大きすぎる本文などのエラーには、スタックトレースを含む HTML ではなく JSON を返し、`X-Powered-By` ヘッダーも送らないようにしました。Docker イメージでは `NODE_ENV=production` を設定し、依存パッケージのインストールスクリプトを実行しないようにしました。
-- `@modelcontextprotocol/sdk`、`axios`、`express` の最低バージョンを、既知の脆弱性の修正を含むバージョンに上げました。
-- GitHub Actions のアクションをコミット SHA で固定し、`actions/checkout` が認証情報を `.git` に残さないようにしました。
+- The MCP server no longer loads `.env` from the current directory at startup. It loads it only from the package's own root (the repository root when built from source), as the CLI already did. MCP clients start the server in the directory of the open project, so a `PORT` in that project's `.env` started the server in HTTP mode, and `HTTPS_PROXY` with `NODE_TLS_REJECT_UNAUTHORIZED=0` let a third-party proxy read and modify traffic to NCBI, including the API key.
+- Tools that take IDs (`get_article_metadata`, `find_related_articles`, `get_copyright_status`, `get_full_text_article`, `convert_article_ids`) now accept only one ID per value. NCBI treats commas as ID separators, so a value such as `"1,2,3"` could fetch more records than the per-call limit allows. `pmids` in `find_related_articles`, which had no limit, is now capped at 200.
+- `lookup_article_by_citation` now replaces `|` and line breaks in each citation field with spaces. Both are ECitMatch delimiters, so they could shift fields or split a citation in two, and results could be matched to a different citation.
+- Requests to NCBI now time out after 60 seconds, so a connection that never answers no longer leaves a tool call (in HTTP mode, the client's request) hanging.
+- When a request to NCBI is redirected, only redirects over HTTPS to `*.ncbi.nlm.nih.gov` are followed. The API key is in the query string and is carried over to the redirect target.
+- The API key is now masked in error messages wherever it appears in the body NCBI returned. Network errors no longer carry the axios error object, which contains the API key.
+- In HTTP mode, access tokens without `exp` or `sub` are rejected.
+- In HTTP mode, the JSON request body is parsed after the token is verified. Errors such as malformed or oversized bodies return JSON instead of HTML with a stack trace, and the `X-Powered-By` header is no longer sent. The Docker image sets `NODE_ENV=production` and does not run install scripts of dependencies.
+- Raised the minimum versions of `@modelcontextprotocol/sdk`, `axios`, and `express` to releases that fix known vulnerabilities.
+- Pinned GitHub Actions to commit SHAs, and `actions/checkout` no longer leaves credentials in `.git`.
 
 ## [1.0.2] - 2026-11-03
 
-### 変更
+### Changed
 
-- README を英語にしました。日本語版は `README_ja.md` に移し、両方の冒頭に npm のバージョン・パッケージサイズ・ライセンス・Node.js のバージョン・CI のバッジと、言語の切り替えリンクを付けました。
+- The README is now in English. The Japanese version moved to `README_ja.md`. Both start with badges for the npm version, package size, license, Node.js version, and CI, plus links to switch languages.
 
 ## [1.0.1] - 2026-11-01
 
-### 変更
+### Changed
 
-- NCBI へのリクエストに付ける連絡先（`email` パラメータ）を、ダミーの `pubmed-mcp@example.com` から開発者の転送用アドレスに変更しました。NCBI の E-utilities 利用ガイドラインは、`email` に利用者ではなく開発者のアドレスを使うよう求めています。
-- README の「ライセンス」の節で、NCBI の免責事項・著作権表示へのリンクをはっきり示しました。
+- Changed the contact address sent to NCBI (the `email` parameter) from the placeholder `pubmed-mcp@example.com` to the developer's forwarding address. NCBI's E-utilities usage guidelines ask for the developer's address in `email`, not the end user's.
+- The "License" section of the README now links clearly to NCBI's disclaimer and copyright notice.
 
 ## [1.0.0] - 2026-10-29
 
-npm パッケージ [`@djmima/pubmed-mcp`](https://www.npmjs.com/package/@djmima/pubmed-mcp) として最初に公開した版です。
+The first release, published to npm as [`@djmima/pubmed-mcp`](https://www.npmjs.com/package/@djmima/pubmed-mcp).
 
-### 追加
+### Added
 
-- 7 つの MCP ツール: `search_articles`、`get_article_metadata`、`find_related_articles`、`lookup_article_by_citation`、`convert_article_ids`、`get_full_text_article`、`get_copyright_status`
-- stdio と、OAuth で保護した Streamable HTTP の 2 つのトランスポート（`PORT` を設定すると HTTP モード）
-- 同じツールをシェルから実行する `pubmed` CLI と、エージェント向けの Skill（`skills/pubmed-cli`）
+- Seven MCP tools: `search_articles`, `get_article_metadata`, `find_related_articles`, `lookup_article_by_citation`, `convert_article_ids`, `get_full_text_article`, `get_copyright_status`
+- Two transports: stdio, and Streamable HTTP protected by OAuth (HTTP mode when `PORT` is set)
+- The `pubmed` CLI, which runs the same tools from the shell, and an agent skill (`skills/pubmed-cli`)
 - MIT License
 
-[Unreleased]: https://github.com/DJMIMA/PubMed_MCP/compare/v1.2.2...HEAD
+[Unreleased]: https://github.com/DJMIMA/PubMed_MCP/compare/v1.2.3...HEAD
+[1.2.3]: https://github.com/DJMIMA/PubMed_MCP/compare/v1.2.2...v1.2.3
 [1.2.2]: https://github.com/DJMIMA/PubMed_MCP/compare/v1.2.1...v1.2.2
 [1.2.1]: https://github.com/DJMIMA/PubMed_MCP/compare/v1.2.0...v1.2.1
 [1.2.0]: https://github.com/DJMIMA/PubMed_MCP/compare/v1.1.0...v1.2.0

package/CHANGELOG_ja.md

@@ -0,0 +1,94 @@
+# 変更履歴
+
+[English](CHANGELOG.md) · **日本語**
+
+このプロジェクトの主な変更を記録します。
+書式は [Keep a Changelog](https://keepachangelog.com/ja/1.1.0/) に、バージョン番号は [セマンティック バージョニング](https://semver.org/lang/ja/) に従います。
+
+## [Unreleased]
+
+## [1.2.3] - 2026-11-07
+
+### 追加
+
+- 変更履歴の英語版を追加しました。`CHANGELOG.md` が英語版、`CHANGELOG_ja.md` が日本語版です。どちらも npm パッケージに含めます。
+
+### 修正
+
+- npm パッケージに日本語版の README（`README_ja.md`）が含まれていなかったのを、含めるようにしました。
+
+## [1.2.2] - 2026-11-06
+
+### 変更
+
+- npm パッケージの説明に CLI を加えました。
+
+## [1.2.1] - 2026-11-05
+
+### 修正
+
+- `search_articles`（CLI の `pubmed search`）で、NCBI の検索サーバーの障害時に `Cannot read properties of undefined (reading 'length')` で失敗していたのを、NCBI が返したエラーメッセージ（例: `Search is temporarily unavailable`）を返すようにしました。NCBI は障害時に HTTP 200 で ID の一覧のない応答を返すことがあり、これを検索結果として扱っていました。
+
+## [1.2.0] - 2026-11-04
+
+### 追加
+
+- CLI に `-v` / `--version` を追加しました。インストールされている `pubmed` のバージョンを表示します。
+
+### 修正
+
+- MCP サーバーが `initialize` の応答（`serverInfo.version`）でバージョンを常に `1.0.0` と返していたのを、`package.json` のバージョンを返すようにしました。
+
+## [1.1.0] - 2026-11-04
+
+### 変更
+
+- **HTTP モードで `ALLOWED_SUBJECTS` を必須にしました。** 未設定または空のときは起動時に終了します。これまでは空のとき、認可サーバー（WorkOS AuthKit）で有効なトークンを取得できるユーザー全員が `/mcp` を使えました。
+- HTTP モードで、`/mcp` への GET と DELETE に 405 を返すようにしました。ステートレスなサーバーには GET で開く SSE ストリームに送るものがなく、開いたままのストリームがサーバーインスタンスと Cloud Run のリクエストを占有していました。
+
+### セキュリティ
+
+- MCP サーバーが `.env` を起動時のカレントディレクトリから読み込んでいたのをやめ、パッケージ自身のルート（ソースからビルドした場合はリポジトリ直下）からだけ読み込むようにしました（CLI はもともとこの動作です）。MCP クライアントは開いているプロジェクトのディレクトリでサーバーを起動するため、そのプロジェクトの `.env` に `PORT` があると HTTP モードで起動し、`HTTPS_PROXY` と `NODE_TLS_REJECT_UNAUTHORIZED=0` があると NCBI への通信（API キーを含む）を第三者のプロキシが読み書きできました。
+- ID を受け取るツール（`get_article_metadata`、`find_related_articles`、`get_copyright_status`、`get_full_text_article`、`convert_article_ids`）で、1 つの値に 1 つの ID だけを受け付けるようにしました。NCBI はカンマを ID の区切りとして扱うため、`"1,2,3"` のような値で 1 回あたりの上限を超える件数を取得できました。上限のなかった `find_related_articles` の `pmids` も 200 件までにしました。
+- `lookup_article_by_citation` で、引用の各項目に含まれる `|` と改行を空白に置き換えるようにしました。どちらも ECitMatch の区切り文字なので、項目がずれたり別の引用として送られたりして、結果が別の引用に対応づけられるおそれがありました。
+- NCBI へのリクエストに 60 秒のタイムアウトを設けました。応答のない接続で、ツールの呼び出し（HTTP モードではクライアントのリクエスト）が止まったままになることがなくなります。
+- NCBI へのリクエストがリダイレクトされたときは、HTTPS で `*.ncbi.nlm.nih.gov` に向かうものだけをたどるようにしました。API キーはクエリ文字列に含まれ、リダイレクト先にも引き継がれます。
+- エラーメッセージの中の API キーは、NCBI が返した本文のどこに現れても伏せるようにしました。ネットワークエラーには、API キーを含む axios のエラーオブジェクトを付けないようにしました。
+- HTTP モードで、`exp` と `sub` のないアクセストークンを拒否するようにしました。
+- HTTP モードで、リクエスト本文の JSON をトークンの検証後に解析するようにしました。不正な形式や大きすぎる本文などのエラーには、スタックトレースを含む HTML ではなく JSON を返し、`X-Powered-By` ヘッダーも送らないようにしました。Docker イメージでは `NODE_ENV=production` を設定し、依存パッケージのインストールスクリプトを実行しないようにしました。
+- `@modelcontextprotocol/sdk`、`axios`、`express` の最低バージョンを、既知の脆弱性の修正を含むバージョンに上げました。
+- GitHub Actions のアクションをコミット SHA で固定し、`actions/checkout` が認証情報を `.git` に残さないようにしました。
+
+## [1.0.2] - 2026-11-03
+
+### 変更
+
+- README を英語にしました。日本語版は `README_ja.md` に移し、両方の冒頭に npm のバージョン・パッケージサイズ・ライセンス・Node.js のバージョン・CI のバッジと、言語の切り替えリンクを付けました。
+
+## [1.0.1] - 2026-11-01
+
+### 変更
+
+- NCBI へのリクエストに付ける連絡先（`email` パラメータ）を、ダミーの `pubmed-mcp@example.com` から開発者の転送用アドレスに変更しました。NCBI の E-utilities 利用ガイドラインは、`email` に利用者ではなく開発者のアドレスを使うよう求めています。
+- README の「ライセンス」の節で、NCBI の免責事項・著作権表示へのリンクをはっきり示しました。
+
+## [1.0.0] - 2026-10-29
+
+npm パッケージ [`@djmima/pubmed-mcp`](https://www.npmjs.com/package/@djmima/pubmed-mcp) として最初に公開した版です。
+
+### 追加
+
+- 7 つの MCP ツール: `search_articles`、`get_article_metadata`、`find_related_articles`、`lookup_article_by_citation`、`convert_article_ids`、`get_full_text_article`、`get_copyright_status`
+- stdio と、OAuth で保護した Streamable HTTP の 2 つのトランスポート（`PORT` を設定すると HTTP モード）
+- 同じツールをシェルから実行する `pubmed` CLI と、エージェント向けの Skill（`skills/pubmed-cli`）
+- MIT License
+
+[Unreleased]: https://github.com/DJMIMA/PubMed_MCP/compare/v1.2.3...HEAD
+[1.2.3]: https://github.com/DJMIMA/PubMed_MCP/compare/v1.2.2...v1.2.3
+[1.2.2]: https://github.com/DJMIMA/PubMed_MCP/compare/v1.2.1...v1.2.2
+[1.2.1]: https://github.com/DJMIMA/PubMed_MCP/compare/v1.2.0...v1.2.1
+[1.2.0]: https://github.com/DJMIMA/PubMed_MCP/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/DJMIMA/PubMed_MCP/compare/v1.0.2...v1.1.0
+[1.0.2]: https://github.com/DJMIMA/PubMed_MCP/compare/v1.0.1...v1.0.2
+[1.0.1]: https://github.com/DJMIMA/PubMed_MCP/compare/v1.0.0...v1.0.1
+[1.0.0]: https://github.com/DJMIMA/PubMed_MCP/releases/tag/v1.0.0

package/README.md

@@ -766,12 +766,12 @@ Publishing a Release on GitHub makes [`.github/workflows/release.yml`](.github/w
 The new version is not published until a maintainer approves it on npmjs.com with 2FA. This way, a compromised workflow or dependency cannot publish on its own.
 Because the workflow uses npm [Trusted Publishing](https://docs.npmjs.com/trusted-publishers/) (OIDC), no npm token is stored in the repository.
 
-PRs that make changes add them to `[Unreleased]` in [`CHANGELOG.md`](CHANGELOG.md). To release:
+PRs that make changes add the same entry to `[Unreleased]` in both [`CHANGELOG.md`](CHANGELOG.md) (English) and [`CHANGELOG_ja.md`](CHANGELOG_ja.md) (Japanese). To release:
 
 1. On a release branch, run `npm version patch --no-git-tag-version` (or `minor` / `major`) to bump the version in `package.json`
    (GitHub adds the tag in step 3, so don't tag here)
-2. Move the contents of `[Unreleased]` in `CHANGELOG.md` under a heading for the new version (for example, `## [1.0.1] - 2026-11-01`), update the comparison links at the end, then open a PR and merge it into main
-3. On GitHub, publish a Release targeting main with the tag `v<version>` (for example, `v1.0.1`). Paste the corresponding part of `CHANGELOG.md` into the release notes
+2. In both `CHANGELOG.md` and `CHANGELOG_ja.md`, move the contents of `[Unreleased]` under a heading for the new version (for example, `## [1.0.1] - 2026-11-01`), update the comparison links at the end, then open a PR and merge it into main
+3. On GitHub, publish a Release targeting main with the tag `v<version>` (for example, `v1.0.1`). Paste the corresponding part of `CHANGELOG.md` (English) into the release notes
 4. The workflow checks that the tag matches the version in `package.json`, runs typecheck, lint, tests, and build, and then stages the publish
 5. Review it on the **Staged Packages** tab of the package page on npmjs.com and click **Approve** (2FA required). You can also approve from the CLI with `npm stage approve <stage-id>`
 

package/README_ja.md

@@ -0,0 +1,827 @@
+<h1 align="center">PubMed MCP/CLI</h1>
+
+<p align="center"><strong>AI アシスタントから、医学・生命科学の文献を検索して読む。</strong></p>
+
+<p align="center">PubMed と PubMed Central を、Claude・Codex・シェルから。</p>
+
+<p align="center">
+  <a href="#tools">ツール</a> ·
+  <a href="#インストール"><strong>インストール</strong></a> ·
+  <a href="#使い方">使い方</a> ·
+  <a href="#cli">CLI</a> ·
+  <a href="#google-cloud-run-へのデプロイ">デプロイ</a> ·
+  <a href="CHANGELOG_ja.md">変更履歴</a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@djmima/pubmed-mcp"><img alt="npm version" src="https://img.shields.io/npm/v/@djmima/pubmed-mcp?label=npm&color=cb3837"></a>
+  <a href="https://packagephobia.com/result?p=@djmima/pubmed-mcp"><img alt="npm unpacked size" src="https://img.shields.io/npm/unpacked-size/@djmima/pubmed-mcp"></a>
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue"></a>
+  <a href="https://nodejs.org/"><img alt="Node.js version" src="https://img.shields.io/node/v/@djmima/pubmed-mcp"></a>
+  <a href="https://github.com/DJMIMA/PubMed_MCP/actions/workflows/ci.yml"><img alt="CI status" src="https://github.com/DJMIMA/PubMed_MCP/actions/workflows/ci.yml/badge.svg"></a>
+</p>
+
+<p align="center"><a href="README.md">English</a> · <strong>日本語</strong></p>
+
+**無料でオープンソース。自分のパソコンで動かせます。** NCBI E-utilities API を通じて、Claude や Codex などの LLM クライアントから [PubMed](https://pubmed.ncbi.nlm.nih.gov/) と [PubMed Central（PMC）](https://www.ncbi.nlm.nih.gov/pmc/) を扱えるようにする [MCP（Model Context Protocol）](https://modelcontextprotocol.io/) サーバーとコマンドラインツールです。アカウントは不要で、NCBI API キーも任意です。
+
+## Tools
+
+| Tool | 説明 |
+|------|------|
+| `search_articles` | PubMed構文またはキーワードで文献を検索。ATM診断・フィールド制限・日付フィルタ・ソート・ページネーション対応 |
+| `get_article_metadata` | PMIDを指定してタイトル・抄録・著者・MeSH語・キーワードなどを取得 |
+| `find_related_articles` | ELinkを使って関連文献や他DBへのリンクを検索 |
+| `lookup_article_by_citation` | 雑誌名・年・巻・筆頭著者などの引用情報からPMIDを逆引き |
+| `convert_article_ids` | PMID・PMCID・DOI を相互変換 |
+| `get_full_text_article` | PMC Open Access記事の本文全文をプレーンテキストで取得 |
+| `get_copyright_status` | 全文取得の可否（`has_full_text`）・ライセンス・著作権表示・OAステータスを確認。PMCのEFetchメタデータを使用（旧PMC OA Web Serviceは2026-08-25に廃止） |
+
+同じツールは、シェルから `pubmed` コマンドとしても実行できます（「[CLI](#cli)」を参照）。
+
+---
+
+## `search_articles` の ATM 診断とフィールド制限
+
+PubMed はタグのない検索語に Automatic Term Mapping（ATM）を適用します。ATM は MeSH、
+雑誌名、著者名などへ検索語を展開するため、意図しない変換や、引用句が句インデックスに
+存在しないことによる検索のフォールバックが起こる場合があります。
+
+`search_articles` は次の任意の `field` 値を受け取り、クエリ内のタグなし語をすべてその
+フィールドへ制限します。
+
+- `title`
+- `tiab`（Title/Abstract）
+- `mesh`
+- `author`
+- `journal`
+- `affiliation`
+
+クエリ内に明示的なフィールドタグがある語では、そのタグが `field` より優先されます。
+`field` を省略した場合の検索動作は従来どおりです。`all` は ATM を無効化しないため、
+公開パラメータには含めていません。
+
+レスポンスには、NCBI ESearch の診断を正規化した次のフィールドが常に含まれます。
+
+```json
+{
+  "warnings": {
+    "phrases_ignored": [],
+    "quoted_phrases_not_found": [],
+    "output_messages": []
+  },
+  "errors": {
+    "phrases_not_found": [],
+    "fields_not_found": []
+  }
+}
+```
+
+この `errors` は NCBI ESearch が返す検索語・フィールドの診断であり、通信エラーや
+MCP ツール自体の実行エラーとは別の情報です。
+これらのキーは診断がない場合も空配列として返ります。低件数や0件を「文献なし」と判断する
+前に、`query_translation`、`warnings`、`errors` を確認してください。複数語を同一フィールドで
+確実に検索する場合は各語へタグを付け、引用句が句インデックスにない場合の隣接検索には
+`[ti:~0]` または `[tiab:~0]` を使用できます。
+
+---
+
+## 必要環境
+
+- **Node.js** 22 以上（`npx` と `npm` は Node.js に同梱されています）
+- **NCBI API キー**（任意。なくても動作するが、レートリミットが 3 req/s に制限される）
+- **jq**（任意。[CLI](#cli) の出力から必要なフィールドを取り出すのに使う）
+
+---
+
+## インストール
+
+npm パッケージ [`@djmima/pubmed-mcp`](https://www.npmjs.com/package/@djmima/pubmed-mcp) として公開しています。
+
+- **MCP サーバーとして使う場合**は、インストールは不要です。MCP クライアントの設定に `npx -y @djmima/pubmed-mcp@latest` を書くと、
+  起動時に最新版が自動でダウンロードされます（後述の「[使い方](#使い方)」を参照）。
+- **[CLI](#cli) を使う場合**は、グローバルにインストールします。
+
+```bash
+npm install -g @djmima/pubmed-mcp
+```
+
+`pubmed` と `pubmed-mcp` の 2 つのコマンドが登録されます。更新は `npm update -g @djmima/pubmed-mcp`、
+削除は `npm rm -g @djmima/pubmed-mcp` です。
+
+ソースコードを修正して使いたい場合は「[ソースからビルドする](#ソースからビルドする)」を参照してください。
+
+### NCBI API キーの設定（推奨）
+
+APIキーを取得するとレートリミットが 3 → 8 req/s に向上します。
+
+1. [NCBI アカウント](https://www.ncbi.nlm.nih.gov/account/)を作成してAPIキーを発行
+2. 環境変数 `NCBI_API_KEY` にセット（後述のクライアント別設定を参照）
+
+MCP クライアントからローカルで起動する場合は、クライアント設定の `env` でキーを渡してください。
+サーバーが `.env` を読み込むのはパッケージ自身のルート（[ソースからビルドした](#ソースからビルドする)場合はリポジトリ直下）だけで、
+起動時のカレントディレクトリからは読み込みません。そのため、MCP クライアントで開いているプロジェクトの `.env` で設定が変わることはありません。
+
+APIキーは、このサーバーを運用する個人または組織が所有・管理するものを設定してください。
+リポジトリにはAPIキーを同梱しません。レスポンス中にNCBI APIの `echo` が含まれる場合も、
+`api_key` 値は `<redacted>` にマスクされます。
+
+クライアント側ではプロセスごとに簡易レートリミッターをかけています。APIキーなしでは最大
+3 req/s、APIキーありではNCBI上限の10 req/sに対して余裕を持たせた8 req/sで送信します（NCBIは到着時刻で数えるため、回線の揺らぎ分の余裕）。HTTP 429 が返った場合は最大2回まで待機して再試行します。
+同一プロセス内の並列呼び出しは自動的に間隔調整されますが、Cloud Runなどで複数インスタンスを
+動かす場合は全インスタンス合算でNCBIの上限を超えないようにしてください。目安として、単一
+インスタンスではAPIキーありで8並列程度、APIキーなしで2並列程度までに抑える運用を推奨します。
+
+---
+
+## 使い方
+
+### Claude Desktop（ローカル・stdio）
+
+`claude_desktop_config.json` の `mcpServers` にサーバーを追加します。
+
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "pubmed-local": {
+      "command": "npx",
+      "args": ["-y", "@djmima/pubmed-mcp@latest"],
+      "env": {
+        "NCBI_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+- 他のサーバーが登録済みの場合は、`mcpServers` の中に `"pubmed-local": { ... }` を並べて追加します（前の項目との間のカンマを忘れずに）。
+- Windows で起動しない場合は、`"command": "cmd"`、`"args": ["/c", "npx", "-y", "@djmima/pubmed-mcp@latest"]` に変えてください。
+- `@latest` を付けると、起動のたびに npm に最新版があるか確認します。版を固定したい場合は `@djmima/pubmed-mcp@1.0.0` のように書きます。
+- サーバー名を `pubmed-local` にしておくと、リモート版（`pubmed-remote`）や同じツール名を持つ他の PubMed コネクタと区別しやすくなります。
+
+設定後、Claude Desktop を完全に終了してから再起動してください。ウィンドウを閉じただけではアプリが常駐したままになることがあります（Windows ではタスクトレイのアイコンから終了できます）。
+この設定のサーバーは、Claude Desktop の Code タブで開いたセッションにも読み込まれます。
+
+起動しない場合は、ログ（Windows: `%APPDATA%\Claude\logs\mcp-server-pubmed-local.log`、macOS: `~/Library/Logs/Claude/mcp-server-pubmed-local.log`）を確認してください。
+
+---
+
+### Claude Code（ローカル・stdio）
+
+`claude mcp add` で登録します。`--scope user` を付けるとすべてのプロジェクトで使えます。
+
+```bash
+claude mcp add --env NCBI_API_KEY=your_api_key_here --transport stdio --scope user pubmed-local -- npx -y @djmima/pubmed-mcp@latest
+```
+
+- `--` より後ろは、サーバーの起動コマンドとしてそのまま渡されます。
+- Windows（WSL ではない環境）では、`--` の後ろを `cmd /c npx -y @djmima/pubmed-mcp@latest` にしてください。
+- `--env` の直後にサーバー名を書くと `KEY=value` の続きとして解釈されてエラーになるため、間に別のオプション（ここでは `--transport stdio`）を挟みます。
+- 登録内容は `~/.claude.json`（user / local スコープ）またはプロジェクト直下の `.mcp.json`（project スコープ）に保存されます。`~/.claude/settings.json` に `mcpServers` を書いても読み込まれません。
+- Claude Desktop の Code タブだけで使う場合は、上記の `claude_desktop_config.json` への登録で読み込まれるため、この手順は不要です。
+
+登録後、`claude mcp list` または Claude Code 内の `/mcp` で接続状態を確認できます。
+
+---
+
+### Codex（ローカル・stdio）
+
+Codex のデスクトップアプリ・CLI・IDE 拡張は、同じ設定ファイル `~/.codex/config.toml`（Windows: `%USERPROFILE%\.codex\config.toml`）を共有します。次のブロックを追記してください。
+
+```toml
+[mcp_servers.pubmed-local]
+command = "npx"
+args = ["-y", "@djmima/pubmed-mcp@latest"]
+
+[mcp_servers.pubmed-local.env]
+NCBI_API_KEY = "your_api_key_here"
+```
+
+- Windows で起動しない場合は、`command = "cmd"`、`args = ["/c", "npx", "-y", "@djmima/pubmed-mcp@latest"]` に変えてください。
+- Codex は OS の環境変数をそのまま MCP サーバーへ渡しません。API キーは上のように `env` に書くか、`[mcp_servers.pubmed-local]` に `env_vars = ["NCBI_API_KEY"]` を追加して Codex 側の環境変数から転送してください。
+
+CLI からは `codex mcp add` でも登録できます。
+
+```bash
+codex mcp add pubmed-local --env NCBI_API_KEY=your_api_key_here -- npx -y @djmima/pubmed-mcp@latest
+```
+
+設定後は Codex を再起動してください（デスクトップアプリでは **Settings → MCP servers** の **Restart**）。同じ画面の **Add server** から登録することもできます。CLI と IDE 拡張では `/mcp` で接続中のサーバーを確認できます。
+
+---
+
+### Anthropic API（プログラムからの利用）
+
+```python
+import os
+
+import anthropic
+
+client = anthropic.Anthropic()
+response = client.beta.messages.create(
+    model="claude-opus-5",
+    max_tokens=16000,
+    messages=[{
+        "role": "user",
+        "content": "Find recent papers on CRISPR gene editing in cancer treatment"
+    }],
+    mcp_servers=[{
+        "type": "url",
+        "url": "https://pubmed-mcp-PROJECT_NUMBER.asia-northeast1.run.app/mcp",
+        "name": "pubmed",
+        # /mcp は OAuth で保護されているため、アクセストークンが必要
+        "authorization_token": os.environ["PUBMED_MCP_TOKEN"],
+    }],
+    tools=[{"type": "mcp_toolset", "mcp_server_name": "pubmed"}],
+    betas=["mcp-client-2025-11-20"]
+)
+```
+
+Anthropic API の MCP コネクタは HTTP で公開されたリモートサーバーにしか接続できないため、先に Cloud Run へデプロイしておく必要があります。
+デプロイ方法は後述の「[Google Cloud Run へのデプロイ](#google-cloud-run-へのデプロイ)」、アクセストークンの取得方法は「[クライアント別の接続設定](#クライアント別の接続設定)」を参照してください。
+
+---
+
+### ソースからビルドする
+
+ソースコードを修正して使う場合は、リポジトリをクローンしてビルドします。
+
+```bash
+git clone https://github.com/DJMIMA/PubMed_MCP.git
+cd PubMed_MCP
+npm install
+npm run build
+```
+
+MCP クライアントの設定では、`npx -y @djmima/pubmed-mcp@latest` の代わりに `node /absolute/path/to/PubMed_MCP/dist/index.js` を指定します
+（Windows のパスは `C:/path/to/PubMed_MCP/dist/index.js` のようにスラッシュ区切りで書きます）。
+CLI として使う場合は、続けて `npm link` を実行すると `pubmed` と `pubmed-mcp` コマンドが登録されます（解除は `npm rm -g @djmima/pubmed-mcp`）。
+
+`dist/` はリポジトリに含まれません。`git pull` でソースを更新したら `npm run build` を再実行し、
+MCP クライアントを再起動してください。起動中のサーバーは再起動するまで古いビルドのまま動きます。
+
+### ローカル開発
+
+```bash
+# .env ファイルを作成してAPIキーを設定
+cp .env.example .env
+# .env を編集して NCBI_API_KEY を記入
+
+# stdio モードで起動（デフォルト）
+npm run dev
+
+# HTTP モードで起動（PORT を設定すると有効になる。OAuth の環境変数も必須）
+PORT=8080 npm run dev
+# → http://localhost:8080/mcp   MCP エンドポイント（Bearer トークン必須）
+# → http://localhost:8080/health ヘルスチェック
+```
+
+HTTP モードは起動時に `OAUTH_ISSUER`・`OAUTH_JWKS_URL`・`MCP_RESOURCE_URL`・`ALLOWED_SUBJECTS` を読み込み、1 つでも未設定だと次のエラーで終了します。
+
+```
+Fatal error: Error: Missing required environment variable: OAUTH_ISSUER
+```
+
+`.env` にこれらの値を設定してから起動してください（各値の意味は「[環境変数](#環境変数)」を参照）。
+`/health` や 401 応答を確かめるだけなら仮の値（URL の変数は URL 形式）でも起動できますが、`/mcp` を実際に呼び出すには
+`MCP_RESOURCE_URL` を `aud` として発行されたアクセストークンが必要です。認証なしでツールを試す場合は stdio モードを使ってください。
+
+---
+
+## CLI
+
+MCP サーバーと同じツールを、シェルから `pubmed` コマンドとして実行できます。出力は MCP ツールと同じ JSON で、
+標準出力またはファイル（`-o`）に書き出されます。結果をファイルに保存して `jq` で必要なフィールドだけを取り出せば、
+Claude Code や Codex などのエージェントが大量のメタデータをコンテキストに読み込まずに済みます。
+
+たとえば `TP53 AND myelodysplastic syndromes[mh]` の上位 20 件のメタデータは約 108 KB ありますが、
+PMID・年・タイトルだけを取り出すと 3.2 KB（約 1/34）になります。全文は 1 本で数万文字あります。
+
+### インストール
+
+```bash
+npm install -g @djmima/pubmed-mcp
+```
+
+`pubmed --help` が表示されれば完了です。インストールされているバージョンは `pubmed --version`（または `-v`）で確認できます。
+
+NCBI API キーは環境変数 `NCBI_API_KEY` から読み込みます。シェルの設定ファイル（`~/.bashrc`、`~/.zshrc` など）に
+`export NCBI_API_KEY=your_api_key_here` を書くか、Windows では `setx NCBI_API_KEY your_api_key_here` を一度実行してから
+ターミナルを開き直してください。
+
+[ソースからビルドして](#ソースからビルドする) `npm link` で登録した場合は、環境変数がなければリポジトリ直下の `.env`
+（`cp .env.example .env` で作成）も読み込むため、どのディレクトリから実行してもキーが使われます。
+
+### コマンド
+
+| コマンド | 対応する MCP ツール | 入力 | 1 リクエストの件数 |
+|---|---|---|---|
+| `pubmed search <query>` | `search_articles` | 検索式（`-` で標準入力から） | — |
+| `pubmed metadata <pmid>...` | `get_article_metadata` | PMID | 200 |
+| `pubmed related <pmid>...` | `find_related_articles` | PMID | 200 |
+| `pubmed citation --journal <雑誌> --year <年> ...` | `lookup_article_by_citation` | オプション、または `--input` で JSON 配列か JSON Lines | 100 |
+| `pubmed convert <id>...` | `convert_article_ids` | PMID・PMCID・DOI のいずれか（`--id-type` で指定） | 200 |
+| `pubmed fulltext <pmcid>...` | `get_full_text_article` | PMCID | 20 |
+| `pubmed copyright <pmid>...` | `get_copyright_status` | PMID | 50 |
+
+- オプション名は MCP のパラメータ名をケバブケースにしたものです（`max_results` → `--max-results`、`date_from` → `--date-from` など）。詳しくは `pubmed <command> --help` を参照してください。
+- ID は引数（空白またはカンマ区切り）で渡すか、`-` を指定して標準入力から 1 行 1 件で渡します。
+- 1 リクエストの件数を超える ID は自動で分割して順番に送り、結果を 1 つの JSON にまとめます。MCP ツールの件数上限（メタデータなら 200 件）は受けません。
+- `-o <file>` を付けると JSON をファイルに書き出し、件数とファイルサイズを標準エラー出力に表示します。
+- 終了コードは、成功で 0、NCBI やファイル操作のエラーで 1、使い方の誤りで 2 です。エラーの内容は標準エラー出力に出ます。
+
+### 使用例
+
+```bash
+# 検索して、PubMed が検索式をどう解釈したかを確認する
+pubmed search "TP53[tiab] AND myelodysplastic syndromes[mh]" --max-results 200 -o search.json
+jq '{total_count, query_translation, warnings, errors}' search.json
+
+# ヒットした全件のメタデータを取得し、PMID・年・雑誌・タイトルの一覧にする
+jq -r '.pmids[]' search.json | pubmed metadata - -o meta.json
+jq -r '.articles[] | [.identifiers.pmid, .publication_date.year, .journal.iso_abbreviation, .title] | @tsv' meta.json
+
+# 全文を取得できる論文だけ全文を取得し、必要な箇所だけを検索する
+jq -r '.pmids[]' search.json | pubmed copyright - -o rights.json
+jq -r '.statuses[] | select(.has_full_text) | .pmcid' rights.json | pubmed fulltext - -o full.json
+jq -r '.articles[].full_text' full.json | grep -n -i 'venetoclax'
+```
+
+### エージェントから使う
+
+[`skills/pubmed-cli/SKILL.md`](skills/pubmed-cli/SKILL.md) は、CLI の使い方（結果はファイルに保存して jq で読む、ID はまとめて 1 回で渡す、など）と
+jq のレシピをエージェントに教える Skill です。ユーザー単位のスキルフォルダにコピーすると、どのプロジェクトでも使われます。
+Claude Code（Claude Desktop の Code タブを含む）は `~/.claude/skills/`、Codex は `~/.agents/skills/` から読み込みます
+（Windows では `~` が `%USERPROFILE%` になります）。
+
+Skill は npm パッケージにも含まれているので、`npm install -g` でインストールした場合は次のコマンドでコピーできます
+（Windows では Git Bash で実行してください）。
+
+```bash
+SKILL_DIR="$(npm root -g)/@djmima/pubmed-mcp/skills/pubmed-cli"
+mkdir -p ~/.claude/skills ~/.agents/skills
+cp -r "$SKILL_DIR" ~/.claude/skills/
+cp -r "$SKILL_DIR" ~/.agents/skills/
+```
+
+ソースからビルドした場合は、リポジトリ直下で `SKILL_DIR=skills/pubmed-cli` としてから同じコマンドを実行します。
+パッケージや Skill を更新したときは、もう一度コピーしてください。
+
+Claude Code でコマンドを実行するたびに許可を求められないようにするには、`~/.claude/settings.json` の `permissions.allow` に
+`pubmed` と `jq` を追加します（既に設定がある場合は配列に追記してください）。
+
+```json
+{
+  "permissions": {
+    "allow": ["Bash(pubmed:*)", "Bash(jq:*)"]
+  }
+}
+```
+
+注意点:
+
+- CLI はシェルを実行できる環境（Claude Code、Codex など）でしか使えません。claude.ai のチャットや、Cloud Run にデプロイしたカスタムコネクタからは、これまでどおり MCP サーバーを使ってください。
+- NCBI のレート制限はプロセスごとにかかります。`pubmed` を並列で複数起動すると合計で上限を超えるため、ID はまとめて 1 回の実行で渡してください。
+- Windows では Git Bash か PowerShell 7 でパイプラインを実行してください。Windows PowerShell 5.1 の `>` はファイルを UTF-16 で保存するため、代わりに `-o` を使ってください。
+
+---
+
+## Google Cloud Run へのデプロイ
+
+このサーバーは Docker コンテナとして Google Cloud Run にデプロイできます。
+`PORT` 環境変数が設定されると自動的に HTTP モードで起動し、Streamable HTTP トランスポートで MCP クライアントと通信します。
+
+HTTP モードの `/mcp` は **OAuth 2.0 で保護** されています。サーバーは OAuth のリソースサーバーとして動作し、
+リクエストごとに Bearer トークン（JWT）の署名・発行者（`iss`）・対象（`aud`）・有効期限を、認可サーバーの公開鍵（JWKS）で検証します。
+ログイン画面やトークンの発行は外部の認可サーバーが担当します（ここでは WorkOS AuthKit を使います）。
+
+Cloud Run 自体は `--allow-unauthenticated` で公開します。Cloud Run の IAM 認証（IAP を含む）は claude.ai からの接続と両立しないため、
+アクセス制御は Cloud Run ではなくアプリ側の OAuth で行います。
+
+| パス | 認証 | 内容 |
+|------|------|------|
+| `/mcp` | Bearer トークン必須 | MCP エンドポイント |
+| `/.well-known/oauth-protected-resource` | 不要 | 認可サーバーの場所を示すメタデータ（RFC 9728） |
+| `/health` | 不要 | ヘルスチェック |
+
+```
+Claude（Web / Desktop / モバイル）・Claude Code・Anthropic API
+        │  Authorization: Bearer <WorkOS AuthKit が発行したアクセストークン>
+        ▼
+  Cloud Run（--allow-unauthenticated）
+        │  /mcp で JWT を検証し、ALLOWED_SUBJECTS で利用者を限定
+        ▼
+  MCP ハンドラ
+```
+
+Claude の各アプリと Claude Code は、トークンなしのリクエストに返る 401 応答（`WWW-Authenticate` ヘッダー）から
+メタデータをたどって認可サーバーを見つけ、ブラウザでのログインを経てトークンを取得します。
+Anthropic API から使う場合は、呼び出し側でトークンを用意して渡します。
+
+### 前提条件
+
+- Google Cloud プロジェクト（課金が有効なもの）
+- [gcloud CLI](https://cloud.google.com/sdk/docs/install) インストール済み・ログイン済み
+- [WorkOS](https://workos.com/) アカウント（AuthKit を OAuth 認可サーバーとして使用）
+
+### ステップ 1 — プロジェクトと API の準備
+
+```bash
+# デプロイ先プロジェクトをセット
+gcloud config set project MY_PROJECT_ID
+
+# 必要な API を有効化（初回のみ）
+gcloud services enable \
+  run.googleapis.com \
+  artifactregistry.googleapis.com \
+  cloudbuild.googleapis.com \
+  secretmanager.googleapis.com  # NCBI_API_KEY を管理する場合のみ
+```
+
+### ステップ 2 — Artifact Registry リポジトリを作成（初回のみ）
+
+```bash
+gcloud artifacts repositories create pubmed-mcp \
+  --repository-format=docker \
+  --location=asia-northeast1 \
+  --description="PubMed MCP Server"
+```
+
+### ステップ 3 — シークレットを Secret Manager に登録
+
+NCBI API キーをコマンド履歴やログに残さないために Secret Manager を使います。
+
+```bash
+# NCBI API キーを登録
+echo -n "your_ncbi_api_key" | \
+  gcloud secrets create ncbi-api-key \
+    --data-file=- \
+    --replication-policy=automatic
+```
+
+### ステップ 4 — コンテナイメージをビルドしてプッシュ
+
+Cloud Build を使うとローカルに Docker をインストールせずにビルドできます。
+`gcloud builds submit` はカレントディレクトリのファイルを Cloud Build に送信するため、
+**事前にリポジトリをクローンしておく必要があります。**
+
+```bash
+# リポジトリをクローンしてディレクトリに移動
+git clone https://github.com/DJMIMA/PubMed_MCP.git
+cd PubMed_MCP
+
+# Cloud Build でビルド（ローカルに Docker 不要）
+gcloud builds submit \
+  --region=asia-northeast1 \
+  --tag asia-northeast1-docker.pkg.dev/MY_PROJECT_ID/pubmed-mcp/server:latest
+```
+
+ローカルの Docker でビルドする場合:
+
+```bash
+gcloud auth configure-docker asia-northeast1-docker.pkg.dev
+
+docker build -t asia-northeast1-docker.pkg.dev/MY_PROJECT_ID/pubmed-mcp/server:latest .
+docker push asia-northeast1-docker.pkg.dev/MY_PROJECT_ID/pubmed-mcp/server:latest
+```
+
+### ステップ 5 — OAuth 認可サーバー（WorkOS AuthKit）を設定
+
+まず MCP エンドポイントの公開 URL を決めます。Cloud Run のサービスには
+`https://サービス名-プロジェクト番号.リージョン.run.app` 形式の URL が割り当てられるため、デプロイ前に確定できます。
+
+```bash
+PROJECT_NUMBER=$(gcloud projects describe MY_PROJECT_ID --format='value(projectNumber)')
+MCP_RESOURCE_URL="https://pubmed-mcp-${PROJECT_NUMBER}.asia-northeast1.run.app/mcp"
+echo "$MCP_RESOURCE_URL"
+```
+
+この URL が `MCP_RESOURCE_URL` です。WorkOS の Resource Indicator や各クライアントに登録する URL とは**完全に同じ文字列**にしてください
+（クライアントは接続先の URL とメタデータの `resource` が一致するかを確認し、サーバーはトークンの `aud` をこの値と照合します）。
+Cloud Run には `https://pubmed-mcp-xxxx-an.a.run.app` 形式の URL も割り当てられ、どちらでもアクセスできますが、OAuth で使う URL はどちらか一方に統一します。
+
+次に WorkOS ダッシュボードで AuthKit を設定します。
+
+1. **Connect → Configuration** で **Dynamic Client Registration** を有効にする（claude.ai などの MCP クライアントが、自分自身を OAuth クライアントとして登録できるようにするため）
+2. `MCP_RESOURCE_URL` を **Resource Indicator** として登録する（アクセストークンの `aud` がこの URL になる）
+3. AuthKit ドメインの認可サーバーメタデータを開き、`issuer` と `jwks_uri` の値を控える
+
+   ```bash
+   curl https://YOUR_AUTHKIT_DOMAIN/.well-known/oauth-authorization-server
+   # → {"issuer":"https://YOUR_AUTHKIT_DOMAIN", ..., "jwks_uri":"https://YOUR_AUTHKIT_DOMAIN/oauth2/jwks", ...}
+   ```
+
+WorkOS の Staging 環境と Production 環境は、設定も AuthKit ドメインも別々です。環境を切り替えるときは上の設定をやり直し、
+`OAUTH_ISSUER`・`OAUTH_JWKS_URL` も差し替えてください。
+
+### ステップ 6 — Cloud Run にデプロイ
+
+ステップ 5 で控えた値を使ってデプロイします。`ALLOWED_SUBJECTS` には最初は仮の値（ここでは `placeholder`）を入れておきます（理由はステップ 8 を参照）。
+
+```bash
+# ステップ 5 で控えた issuer と jwks_uri の値に置き換える
+OAUTH_ISSUER="https://YOUR_AUTHKIT_DOMAIN"
+OAUTH_JWKS_URL="https://YOUR_AUTHKIT_DOMAIN/oauth2/jwks"
+
+gcloud run deploy pubmed-mcp \
+  --image asia-northeast1-docker.pkg.dev/MY_PROJECT_ID/pubmed-mcp/server:latest \
+  --region asia-northeast1 \
+  --port 8080 \
+  --memory 512Mi \
+  --cpu 1 \
+  --timeout 300 \
+  --allow-unauthenticated \
+  --set-secrets NCBI_API_KEY=ncbi-api-key:latest \
+  --set-env-vars "OAUTH_ISSUER=${OAUTH_ISSUER},OAUTH_JWKS_URL=${OAUTH_JWKS_URL},MCP_RESOURCE_URL=${MCP_RESOURCE_URL},ALLOWED_SUBJECTS=placeholder"
+```
+
+| 変数 | 設定する値 |
+|------|-----------|
+| `OAUTH_ISSUER` | 認可サーバーメタデータの `issuer`。トークンの `iss` と完全一致で照合されるので、末尾の `/` の有無も含めてそのままコピーする |
+| `OAUTH_JWKS_URL` | 同じメタデータの `jwks_uri`。トークンの署名検証に使う公開鍵の URL |
+| `MCP_RESOURCE_URL` | ステップ 5 で決めた MCP エンドポイントの URL。トークンの `aud` と照合し、`/.well-known/oauth-protected-resource` の `resource` としても公開される |
+| `ALLOWED_SUBJECTS` | 接続を許可するユーザー ID（トークンの `sub`）のカンマ区切りリスト。必須（ないと、AuthKit で有効なトークンを取得できるユーザー全員が接続できてしまう） |
+
+`OAUTH_ISSUER`・`OAUTH_JWKS_URL`・`MCP_RESOURCE_URL`・`ALLOWED_SUBJECTS` のどれかが欠けていると、サーバーは起動時に
+`Missing required environment variable: ...` で終了し、デプロイは失敗します。失敗した場合は Cloud Run のログでこのメッセージを確認してください
+（Cloud Console で設定した場合は、変数名の前後に空白が入っていないかも確認してください）。
+
+> **`--set-env-vars` と `--update-env-vars` の違い**: `--set-env-vars` は既存の環境変数をすべて削除してから、指定した値を設定します（指定しなかった変数は消えます）。
+> デプロイ後に一部の値だけを追加・変更するときは、既存の値とマージされる `--update-env-vars` を使ってください（`gcloud run services update` でも使えます）。
+
+### ステップ 7 — 動作確認
+
+`/health` と `/.well-known/oauth-protected-resource` は認証なしで応答します。`/mcp` はトークンなしでは **401 が返れば正常** です。
+
+**Linux / macOS (bash)**
+
+```bash
+PROJECT_NUMBER=$(gcloud projects describe MY_PROJECT_ID --format='value(projectNumber)')
+CLOUD_RUN_URL="https://pubmed-mcp-${PROJECT_NUMBER}.asia-northeast1.run.app"
+
+# ヘルスチェック
+curl "$CLOUD_RUN_URL/health"
+# → ok
+
+# Protected Resource Metadata（resource が MCP_RESOURCE_URL、authorization_servers が OAUTH_ISSUER になっていることを確認）
+curl "$CLOUD_RUN_URL/.well-known/oauth-protected-resource"
+# → {"resource":"https://pubmed-mcp-PROJECT_NUMBER.asia-northeast1.run.app/mcp","authorization_servers":["https://YOUR_AUTHKIT_DOMAIN"],"bearer_methods_supported":["header"]}
+
+# MCP エンドポイント（トークンなしなので 401。-i でヘッダーも表示。ヒアドキュメントでクォート問題を回避）
+curl -i "$CLOUD_RUN_URL/mcp" \
+  -X POST \
+  -H "Content-Type: application/json" \
+  -d @- <<'EOF'
+{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"0.0.1"}}}
+EOF
+```
+
+`/mcp` の応答は次のようになります（抜粋。HTTP のバージョンやヘッダー名の大文字・小文字は環境によって異なります）。
+
+```
+HTTP/2 401
+www-authenticate: Bearer resource_metadata="https://pubmed-mcp-PROJECT_NUMBER.asia-northeast1.run.app/.well-known/oauth-protected-resource", error="missing_token"
+content-type: application/json; charset=utf-8
+
+{"error":"missing_token"}
+```
+
+MCP クライアントは `WWW-Authenticate` ヘッダーの `resource_metadata` をたどって認可サーバーを見つけます。
+トークンの検証に失敗した場合は `error="invalid_token"` の 401、トークンは有効でも `sub` が `ALLOWED_SUBJECTS` にない場合は 403（`{"error":"forbidden"}`）が返ります。
+
+**Windows（コマンドプロンプト）**
+
+```cmd
+:: %CLOUD_RUN_URL% に URL を設定してから実行（PROJECT_NUMBER は自分のプロジェクト番号に置き換える）
+set CLOUD_RUN_URL=https://pubmed-mcp-PROJECT_NUMBER.asia-northeast1.run.app
+
+curl "%CLOUD_RUN_URL%/health"
+
+curl "%CLOUD_RUN_URL%/.well-known/oauth-protected-resource"
+
+curl -i "%CLOUD_RUN_URL%/mcp" -X POST -H "Content-Type: application/json" -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-03-26\",\"capabilities\":{},\"clientInfo\":{\"name\":\"test\",\"version\":\"0.0.1\"}}}"
+```
+
+**Windows（PowerShell）**
+
+```powershell
+$CLOUD_RUN_URL = "https://pubmed-mcp-PROJECT_NUMBER.asia-northeast1.run.app"
+
+curl.exe "$CLOUD_RUN_URL/health"
+
+curl.exe "$CLOUD_RUN_URL/.well-known/oauth-protected-resource"
+
+curl.exe -i "$CLOUD_RUN_URL/mcp" -X POST -H "Content-Type: application/json" `
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"0.0.1"}}}'
+```
+
+### ステップ 8 — 自分のユーザー ID を ALLOWED_SUBJECTS に登録
+
+Dynamic Client Registration では誰でも OAuth クライアントを登録できるため、`ALLOWED_SUBJECTS` で接続できるユーザーを限定します
+（ないと AuthKit にログインできるユーザー全員が `/mcp` を使えてしまい、AuthKit でサインアップを許可している場合は第三者も含まれるため、未設定ではサーバーが起動しません）。
+設定する値はアクセストークンの `sub`（WorkOS のユーザー ID。`user_` で始まる値）です。
+
+サーバーは拒否したユーザーの `sub` をログに記録します。そのため、仮の値を入れた状態で一度接続し、拒否されたときのログから確認します。
+
+1. 後述の「[クライアント別の接続設定](#クライアント別の接続設定)」の手順で claude.ai などから接続し、WorkOS AuthKit でログインします。
+   `sub` が `ALLOWED_SUBJECTS` に含まれていないため接続は 403 で失敗し、サーバーのログに `[auth] forbidden subject: ...` が記録されます。
+2. ログから自分の `sub` を確認します（WorkOS ダッシュボードの **Users** で確認できるユーザー ID と同じ値です）。
+
+   ```bash
+   gcloud run services logs read pubmed-mcp \
+     --region asia-northeast1 \
+     --log-filter='textPayload:"forbidden subject"' \
+     --limit 5
+   # → ... [auth] forbidden subject: user_01XXXXXXXXXXXXXXXXXXXXXXXX
+   ```
+
+3. その値を設定します。`--update-env-vars` なので、ほかの環境変数はそのまま残ります。
+
+   ```bash
+   gcloud run services update pubmed-mcp \
+     --region asia-northeast1 \
+     --update-env-vars ALLOWED_SUBJECTS=user_01XXXXXXXXXXXXXXXXXXXXXXXX
+   ```
+
+   複数のユーザーを許可する場合は、値にカンマが含まれるため `^@^` で区切り文字を変えて指定します
+   （例: `--update-env-vars '^@^ALLOWED_SUBJECTS=user_01AAAA,user_01BBBB'`。Windows の cmd / PowerShell では `^` を `^^^^` と書きます。詳しくは `gcloud topic escaping` を参照）。
+4. クライアントから接続し直します。
+
+---
+
+### クライアント別の接続設定
+
+デプロイ後、各クライアントに MCP エンドポイントの URL を登録します。URL は `MCP_RESOURCE_URL` と**完全に同じ文字列**
+（例: `https://pubmed-mcp-PROJECT_NUMBER.asia-northeast1.run.app/mcp`）にしてください。
+初回接続時に WorkOS AuthKit のログイン画面が開きます。ログインしたアカウントの `sub` が `ALLOWED_SUBJECTS` に含まれていれば接続できます
+（自分の `sub` を登録する手順はステップ 8 を参照）。
+
+**Claude（Web 版・Claude Desktop）— カスタムコネクタ**
+
+リモートサーバーは「カスタムコネクタ」として追加します（[Claude ヘルプセンター](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)）。
+カスタムコネクタは Free プランでも 1 つまで利用できます。
+
+- Pro / Max プラン
+  1. [claude.ai](https://claude.ai) または Claude Desktop で **Customize > Connectors** を開く
+  2. **+** → **Add custom connector** をクリック
+  3. URL（`MCP_RESOURCE_URL`）を入力して **Add** をクリック
+  4. 追加したコネクタの **Connect** から認証する（WorkOS AuthKit のログイン画面が開く）
+- Team / Enterprise プラン
+  1. オーナーが **Organization settings > Connectors** を開き、**Add** → **Custom** にカーソルを合わせて **Web** を選ぶ
+  2. URL（`MCP_RESOURCE_URL`）を入力して **Add** をクリック
+  3. 各メンバーが **Customize > Connectors** でこのコネクタを探し、**Connect** から認証する
+
+**Advanced settings** の OAuth Client ID / OAuth Client Secret は空欄のままで構いません（Dynamic Client Registration でクライアントが自動登録されます）。
+チャットで使うときは、入力欄左下の **+** → **Connectors** から会話ごとに有効にします。
+
+Claude Desktop の `claude_desktop_config.json` はローカル（stdio）サーバー用の設定で、`"type"` や `"url"` を書いてもリモートサーバーには接続されません。
+Desktop でもリモートサーバーは上記のカスタムコネクタとして追加してください（Web 版で追加したコネクタは Desktop でもそのまま使えます）。
+
+**Claude モバイルアプリ（Android / iOS）**
+
+Web 版または Claude Desktop で追加したカスタムコネクタは、同じアカウントのモバイルアプリでもそのまま使えます。
+モバイルアプリからのコネクタ追加はベータ機能のため、追加は Web 版か Desktop で行ってください。
+
+**Claude Code**
+
+```bash
+claude mcp add --transport http --scope user pubmed-remote https://pubmed-mcp-PROJECT_NUMBER.asia-northeast1.run.app/mcp
+```
+
+Claude Code は `~/.claude/settings.json` の `mcpServers` を読み込まないため、`claude mcp add` で登録します。
+登録後、Claude Code で `/mcp` を開いて `pubmed-remote` を選び、ブラウザで WorkOS AuthKit にログインして認証します。
+
+**Anthropic API（Python）**
+
+```python
+import os
+
+import anthropic
+
+client = anthropic.Anthropic()
+response = client.beta.messages.create(
+    model="claude-opus-5",
+    max_tokens=16000,
+    messages=[{"role": "user", "content": "..."}],
+    mcp_servers=[{
+        "type": "url",
+        "url": "https://pubmed-mcp-PROJECT_NUMBER.asia-northeast1.run.app/mcp",
+        "name": "pubmed",
+        "authorization_token": os.environ["PUBMED_MCP_TOKEN"],
+    }],
+    tools=[{"type": "mcp_toolset", "mcp_server_name": "pubmed"}],
+    betas=["mcp-client-2025-11-20"]
+)
+```
+
+MCP コネクタは OAuth のログインもトークンの更新も行いません。WorkOS AuthKit がこのサーバー向けに発行したアクセストークン
+（`aud` が `MCP_RESOURCE_URL` で、`sub` が `ALLOWED_SUBJECTS` に含まれるもの）を呼び出し側で取得して `authorization_token` に渡し、
+有効期限が切れたら取得し直してください。
+
+テスト用のトークンは MCP Inspector で取得できます（[MCP connector ドキュメント](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector#authentication)）。
+
+1. `npx @modelcontextprotocol/inspector` を実行
+2. **Transport type** で **Streamable HTTP** を選び、URL に `MCP_RESOURCE_URL` を入力
+3. **Open Auth Settings** → **Quick OAuth Flow** をクリックし、WorkOS AuthKit でログイン
+4. **Authentication complete** まで進めたら、表示された `access_token` の値をコピー
+
+---
+
+### イメージを更新する（再デプロイ）
+
+```bash
+cd PubMed_MCP
+git pull
+
+gcloud builds submit \
+  --region=asia-northeast1 \
+  --tag asia-northeast1-docker.pkg.dev/MY_PROJECT_ID/pubmed-mcp/server:latest
+
+gcloud run services update pubmed-mcp \
+  --region asia-northeast1 \
+  --image asia-northeast1-docker.pkg.dev/MY_PROJECT_ID/pubmed-mcp/server:latest
+```
+
+`--image` だけを指定した更新では、環境変数とシークレットの設定はそのまま引き継がれます。
+
+---
+
+## 開発コマンド
+
+```bash
+npm run build      # TypeScript をコンパイル → dist/
+npm run dev        # tsx で直接実行（開発用）
+npm run cli -- search "CRISPR" --max-results 5   # CLI を tsx で直接実行（開発用）
+npm test           # テストスイートを実行
+npm run typecheck  # 型チェックのみ（コンパイルなし）
+npm run lint       # ESLint を実行
+```
+
+### npm へのリリース（メンテナー向け）
+
+GitHub で Release を公開すると、[`.github/workflows/release.yml`](.github/workflows/release.yml) が npm に公開を申請します（[staged publishing](https://docs.npmjs.com/staged-publishing/)）。
+メンテナーが npmjs.com で 2FA を使って承認するまで、新しいバージョンは公開されません。ワークフローや依存パッケージが乗っ取られても、それだけでは公開できないようにするためです。
+npm の [Trusted Publishing](https://docs.npmjs.com/trusted-publishers/)（OIDC）を使うため、npm のトークンはリポジトリに保存しません。
+
+変更を加える PR では、[`CHANGELOG.md`](CHANGELOG.md)（英語）と [`CHANGELOG_ja.md`](CHANGELOG_ja.md)（日本語）の両方の `[Unreleased]` に同じ内容を追記しておきます。リリースの手順は次のとおりです。
+
+1. リリース用のブランチで `npm version patch --no-git-tag-version`（または `minor` / `major`）を実行し、`package.json` のバージョンを上げる
+   （タグは手順 3 で GitHub が付けるため、ここでは付けません）
+2. `CHANGELOG.md` と `CHANGELOG_ja.md` のそれぞれで、`[Unreleased]` の内容を新しいバージョンの見出し（例: `## [1.0.1] - 2026-11-01`）の下に移し、末尾の比較リンクを更新して、PR を作って main にマージする
+3. GitHub で、main を対象に `v<バージョン>`（例: `v1.0.1`）のタグを付けた Release を公開する。リリースノートには `CHANGELOG.md`（英語）の該当部分を貼る
+4. ワークフローがタグと `package.json` のバージョンが一致するか確かめ、型チェック・lint・テスト・ビルドを通してから公開を申請する
+5. npmjs.com のパッケージページの **Staged Packages** タブで内容を確認し、**Approve** を押す（2FA が必要）。CLI では `npm stage approve <stage-id>` でも承認できる
+
+バージョンの上げ方の目安は、不具合の修正やドキュメントの変更が `patch`、ツールやオプションの追加が `minor`、
+ツール名・引数・出力の形を変えて既存の使い方が動かなくなる変更が `major` です。
+
+初回だけは手動で公開します。Trusted Publishing はパッケージが npm に存在しないと設定できないためです。
+
+1. 2FA を有効にした npm アカウントで `npm login` し、main の最新を `npm publish` で公開する（保留になった場合は上記の手順 5 のとおり承認する）
+2. npmjs.com のパッケージ設定 → **Trusted Publisher** で GitHub Actions を選び、リポジトリ `DJMIMA/PubMed_MCP`、ワークフロー `release.yml` を登録する。
+   **Allowed actions** は `npm stage publish`（常に許可）だけにし、`npm publish` と `npm dist-tag` は許可しない
+3. 同じ設定画面の **Publishing access** で **Require two-factor authentication and disallow tokens** を選ぶ
+
+---
+
+## 環境変数
+
+| 変数 | 必須 | 説明 |
+|------|------|------|
+| `NCBI_API_KEY` | 任意 | NCBIのAPIキー。設定するとレートリミットが 3 → 8 req/s になる |
+| `PORT` | 任意 | 設定するとHTTPモードで起動。Cloud Run はこの変数を自動で注入する |
+| `OAUTH_ISSUER` | HTTPモードでは必須 | 認可サーバーの issuer（認可サーバーメタデータの `issuer`）。トークンの `iss` と照合する |
+| `OAUTH_JWKS_URL` | HTTPモードでは必須 | 認可サーバーの JWKS の URL（同じメタデータの `jwks_uri`）。トークンの署名検証に使う |
+| `MCP_RESOURCE_URL` | HTTPモードでは必須 | MCP エンドポイントの公開 URL。トークンの `aud` と照合し、Protected Resource Metadata の `resource` として公開する |
+| `ALLOWED_SUBJECTS` | HTTPモードでは必須 | 接続を許可するトークン `sub` のカンマ区切りリスト |
+
+`OAUTH_ISSUER`・`OAUTH_JWKS_URL`・`MCP_RESOURCE_URL`・`ALLOWED_SUBJECTS` は HTTP モードでのみ使われ、stdio モードでは不要です。
+値の決め方は「[Google Cloud Run へのデプロイ](#google-cloud-run-へのデプロイ)」のステップ 5〜8 を参照してください。
+
+`.env` ファイルを使う場合は `.env.example` をコピーして編集してください。
+本番環境では、`NCBI_API_KEY` は Cloud Run の `--set-secrets` で Secret Manager から渡し、OAuth 関連の値は `--set-env-vars` / `--update-env-vars` で設定してください。
+
+---
+
+## 参考リンク
+
+- [MCP ドキュメント](https://modelcontextprotocol.io/docs)
+- [NCBI E-utilities ドキュメント](https://www.ncbi.nlm.nih.gov/books/NBK25499/)
+- [NCBI APIキー登録](https://www.ncbi.nlm.nih.gov/account/)
+- [PubMed 検索ヘルプ](https://pubmed.ncbi.nlm.nih.gov/help/)
+- [Cloud Run ドキュメント](https://cloud.google.com/run/docs)
+- [Secret Manager ドキュメント](https://cloud.google.com/secret-manager/docs)
+
+---
+
+## ライセンス
+
+このリポジトリのソースコードは [MIT License](LICENSE) で公開しています。
+
+- このプロジェクトは NCBI / NLM（米国国立医学図書館）とは関係のない非公式のツールです。
+- PubMed / PMC へのアクセスには NCBI の E-utilities を使います。利用時は [NCBI の免責事項・著作権表示を含む利用ポリシー](https://www.ncbi.nlm.nih.gov/home/about/policies/)（NCBI Disclaimer and Copyright notice）と [E-utilities の利用ガイドライン](https://www.ncbi.nlm.nih.gov/books/NBK25497/) に従ってください。
+- ガイドラインに従い、NCBI へのリクエストにはこのソフトウェアの名前（`tool=pubmed-mcp`）と開発者の連絡先（`email`）を付けています。このコードを改変して別のソフトウェアとして配布する場合は、`src/pubmed/client.ts` の `TOOL_NAME` と `TOOL_EMAIL` を自分の値に変えてください。
+- MIT License が適用されるのはこのソフトウェアのコードだけです。取得した抄録や全文の著作権は各著者・出版社に帰属します。論文ごとのライセンスは `get_copyright_status` で確認できます。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djmima/pubmed-mcp",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "description": "MCP server and CLI for searching and reading PubMed and PubMed Central literature",
   "license": "MIT",
   "author": "DJ MIMA",
@@ -31,7 +31,9 @@
   "files": [
     "dist",
     "skills",
-    "CHANGELOG.md"
+    "README_ja.md",
+    "CHANGELOG.md",
+    "CHANGELOG_ja.md"
   ],
   "scripts": {
     "build": "tsc",