PubMed Search

PubMed Search MCP

AI エージェント向けのプロフェッショナルな文献調査アシスタント — 単なる API ラッパーではありません

ドメイン駆動設計（DDD）に基づく MCP サーバーです。AI エージェント向けのインテリジェントな調査アシスタントとして、タスク指向の文献検索と分析機能を提供します。

✨ 含まれる機能：

• 🔧 41 個の MCP ツール — PubMed、Europe PMC、CORE、NCBI データベースへの効率的なアクセスと、バージョン管理された Research Chronicle
• 🛡️ マルチエージェントサービスモード — 一度デプロイするだけで複数のエージェントにサービスを提供できます。テナントごとのセッション、キャッシュ、アーティファクト、ベアラートークン認証、テナントごとの公平な共有制限を備えています。DEPLOYMENT.md をご覧ください。
• 🖼️ オープンアクセス論文の図表抽出 — PMC のオープンアクセス論文から図のキャプション、画像への直接リンク、PDF リンクを取得します。
• 📘 ドキュメントサイト — ユーザーワークフロー、アーキテクチャ、41 ツールのリファレンス、パイプラインのチュートリアル、ソース／ブローカーの契約、統合と運用、セキュリティ、デプロイメントを網羅した、言語切り替え可能なハンドブックをご覧ください。u9401066.github.io/pubmed-search-mcp
• 📖 GitHub Wiki — 同じ正規ドキュメントを GitHub 上でネイティブに閲覧できるミラーです。github.com/u9401066/pubmed-search-mcp/wiki
• 📚 Claude Skills 26 個 — AI エージェント向けのすぐに使えるワークフローガイド（Claude Code 専用）
• 📖 Copilot Instructions — VS Code GitHub Copilot の統合ガイド
• 調査の自動化 — スケジュールされたパイプラインの差分／ローカル通知、Chronicle の再構築サマリー、複数シードによる引用文献のスノーボーリング、options="exclude_seen" によるオプトイン式のセッション重複排除。

🌐 言語：English | 繁體中文

📘 ドキュメントマップ：README はプロジェクトへの簡潔な入口です。最適な閲覧体験には Docs Site を、GitHub 上でのネイティブなナビゲーションには GitHub Wiki をご利用ください。編集にはソースドキュメントをご利用ください：ユーザーガイド | 高度なワークフロー | 機能優先ガイド | 統合検索アーキテクチャ | 41 ツールの品質監査 | 60 リポジトリの学術検索ランドスケープ | プロバイダーのデータプレーン | BioMCP アーキテクチャ分析 | 開発者ガイド | 完全なインデックス

ドキュメントマップ · メンテナンススクリプト

---

研究自動化とポータブルなインストール — v0.8.0

スケジュールされたパイプラインは、範囲を限定した変更を報告し、通知の要約をローカルに保持します。 Chronicle の再構築要約では、前回のリビジョンと比較します。snowball パイプラインでは、 複数の引用シードを展開します。通常の検索では、options="exclude_seen" を指定して、このセッションで以前に返された PMID／DOI を limit の適用前に 除外できます。このオプションは pipeline= と併用できません。インターフェースは引き続き 41 個のツールを提供します。 使用ガイドと パイプラインのチュートリアルをご覧ください。

PyPI へのアップロード前に、レジストリのメタデータとプラグインの差異を確認します。リリースのスモークテストでは、 レジストリ環境の契約に基づき、対象のホイールに含まれる所有権マーカーとインストール済みの 41 個すべてのツールを検証します。レジストリへの公開は、GitHub OIDC を介した PyPI への公開後に行います。

実ワークフローのスモークテストとローカル事前テスト — v0.7.7

ローカルの pretest は、プッシュ前に完全な回帰テストを実行します。CI では Ubuntu／Windows のインストール済みアーティファクトと、実際の MCP／プロバイダーワークフローを重視します。公開時には、 対象のホイール／sdist と、root 以外のユーザーで実行中のコンテナを検証します。代替のテスト範囲を文書化したうえで、脆弱なテストまたは古くなったテストを 64 件削除しました。 テストポリシーと 段階的なリリースレビューをご覧ください。

バックグラウンドでの全文取得と信頼性の高いセクション読み込み — v0.7.6

オプトインの XML 先読みでは、後続の get_fulltext 呼び出しとダウンロードを共有します。キューに入った論文は、要求されるとフォアグラウンドで読み込まれます。検索結果には、そのまま使用できる読み込み引数が含まれます。見つからないセクションについては、要約で代用したり PDF を再取得したりせず、利用可能なタイトルを報告します。 先読みはデフォルトで無効です。 評価と リリースレビューをご覧ください。

入力の共通正規化 — v0.7.5

41 個すべてのツールで、JSON コンテナー、10 進数の数値文字列、明示的なブール値テキスト、列挙値の表記、生物医学識別子が自動的に補正されます。 公開スキーマには受け付けられる表現が含まれ、実行前エラーには正確なフィールドパスと修正条件が示されます。修正後に再試行したケースを含め、ネイティブ形式と正規化されたリクエストをすべてのツールで検証します。 入力形式と検証をご覧ください。

プロバイダーに配慮したスケジューリング — v0.7.4

パイプラインの各分岐は、依存関係の完了に応じて進行するようになりました。API リクエストのレート制限は変更していません。共有される同時実行数には、呼び出し元のうち最も保守的な制限が適用されます。429 のクールダウンは、タイムアウトやキャンセルされた PubMed ワーカーが発生しても維持されます。 過去の計画はドキュメントマップから参照できる場所にアーカイブされています。リリースレビューと オフラインの遅延実験をご覧ください。 固定遅延の計測結果は、稼働中のプロバイダーでのスループットや検索品質を示すものではありません。

コアのレビューと信頼性 — v0.7.3

10 段階のコアレビューを完了しました。223 個のソースファイルと 2,901 個の定義について、作成者による判断と現在のファイルハッシュを記録しています。このリリースでは、41 個すべてのツールを維持しながら、ソースの障害処理、論文の識別、永続化、キャンセル、エクスポート、評価チェックポイントを修正しました。ハーネスのインストールではユーザーによるカスタマイズを保持します。コントリビューターはプッシュ前にローカルで完全なテストを実行し、通常の CI では独立したスモークテストを実行します。動作の変更については変更履歴をご覧ください。ローカルでの回帰テスト結果は、新たな公開ベンチマークでの向上を示すものではありません。

研究品質と評価 — v0.7.2

このリリースでは、クエリを考慮したランキングと融合、ソースをまたいだ記事の重複排除、書誌情報の検証、セクションのフィルタリング、キャッシュ取得の並行処理が改善されています。正規の41ツールインターフェースに変更はありません。

ベンチマークレポートでは、コンポーネントの品質とエージェントパッケージ全体の価値を分けて評価しています。公開されている BEIR NFCorpus では、以前の BM25 コンポーネントの比較において、テストの nDCG@10 が 0.293357 から 0.297831 に改善しました。この結果は、このリリースのエージェント全体の性能を測定したものではありません。ネイティブ Codex／パッケージを対象とした3問のパイロットは、製品レベルの改善を立証するには規模が小さすぎます。5,000問の完全評価は準備済みですが、まだ開始されていません。

再現された不具合、検証の範囲、リビジョンのフィンガープリントについては、信頼性監査をご覧ください。参考文献の検証では書誌情報の整合性を確認します。論文が主張を裏付けているかどうかの確認には、該当する箇所を調べる必要があります。

🚀 クイックインストール

MCP Registry と Agent Plugin

公式 MCP Registry または GitHub MCP Registryに対応したクライアントでは、リリース後に io.github.u9401066/pubmed-search-mcpを検索してください。レジストリのメタデータにより、stdio 経由で uvx [email protected]が起動します。クライアントでNCBI_EMAIL を設定し、必要に応じてNCBI_API_KEYも設定してください。

Agent Plugins 1.0.0互換のクライアントでは、クライアントのプラグインインストーラーを使って、リポジトリの plugins/pubmed-search/ディレクトリをインストールしてください。バージョン固定された MCP ランチャーと研究スキルが同梱されています。 クライアントのプラグイン対応状況やインストール UI は異なります。インテグレーションをご覧ください。

前提条件

• Python 3.10+ — ダウンロード

• uv（推奨）— uv をインストール

  # macOS / Linux
  curl -LsSf https://astral.sh/uv/install.sh | sh
  # Windows
  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  

• NCBI Email — NCBI API ポリシーで必須とされています。有効なメールアドレスを指定してください。

• NCBI API Key (任意) — レート制限を引き上げる場合（10 req/s 対 3 req/s）は、こちらで取得してください。

• OpenAlex API Key (任意) — 認証済みのクレジット割り当てを使用するには、OPENALEX_API_KEYを設定してください。設定しない場合、リクエストには OpenAlex の現在の匿名利用枠が使用されます。mailtoは連絡先メタデータであり、認証情報ではありません。ソース固有のメールアドレスが設定されていない場合、サーバーは設定済みの実行時連絡先メールアドレスを OpenAlex、CrossRef、Unpaywall で再利用します。

インストールと起動

# Option 1: Zero-install with uvx (recommended for trying out)
uvx pubmed-search-mcp

# Option 2: Add as project dependency
uv add pubmed-search-mcp

# Option 3: pip install
pip install pubmed-search-mcp

Python SDK ファサード

プロセス内の Python インテグレーションでは、MCP ツールのモジュールをインポートする代わりに、安定した SDK ファサードを使用してください。

from pubmed_search.api import PubMedSearchClient, PubMedSearchConfig

async with PubMedSearchClient(PubMedSearchConfig(email="[email protected]")) as client:
    result = await client.unified_search("remimazolam ICU sedation", limit=20)

    print(result.articles)
    print(result.source_counts)
    print(result.source_errors)
    print(result.result_filter_counts)

エージェントによるツールの検索にはuvx pubmed-search-mcpまたは/mcpを使用してください。型付きオブジェクトのほうが MCP のレスポンス文字列を解析するより簡単な場合は、Python パッケージやノートブックからの呼び出しに SDK を使用してください。 SDK はアプリケーションのユースケースを直接実行し、MCP セッションジャーナルやアーティファクトの副作用を意図的に持ちません。永続的な再生とアーティファクトのロケーターが必要な場合は、MCP ツールを使用してください。 非同期コンテキストは、すべてのプロバイダークライアントと HTTP プールの所有権を持ち、それらを閉じます。長時間稼働するアプリケーションでasync withを使用しない場合は、シャットダウン時にawait client.aclose()を呼び出してください。

ランタイム契約を選択する

契約	コマンド	ネットワークと信頼境界
ローカル stdio	uvx pubmed-search-mcp	ローカルの AI クライアントを 1 つ使う場合に推奨。MCP ポートをリッスンしません
ローカルループバック HTTP	pubmed-search-mcp-http --mode local --host 127.0.0.1	信頼できる単一ユーザー向けの統合です。MCP リクエストは永続的な default テナントを共有し、ポートを公開してはいけません
マルチユーザーサービス	pubmed-search-mcp-http --mode service	HTTPS を介したリモート／チーム利用向けです。ベアラー認証、許可されたホスト／オリジン、プリンシパルごとのストレージが必須です

ローカルデプロイとサービスデプロイは、意図的に別々の契約になっています。 ローカル HTTP コマンドは、バインドアドレスだけを変更して公開サービスにしないで ください。明示的なローカルプロファイルでは、pmids="last"、セッション、 キャッシュ、エクスポートが、永続的な default テナント内で MCP リクエストや 再接続をまたいで保持されます。これは、強制されたループバック／Host／Origin の 境界内でのみ安全です。サービスモードでは、この信頼を引き継ぐことはなく、 ベアラープリンシパルがなければフェイルクローズします。サービス環境と Compose プロファイルについては、DEPLOYMENT.md を参照してください。 現在のサービスプロファイルは、1 つのサーバープロセス内で複数の認証済み プリンシパルに対応しています。セッション、ロック、アーティファクト、 サブスクリプションに共有バックエンドを導入するまでは、レプリカを 1 つに してください。

プロトコルの基準は MCP SDK v2（mcp>=2.0,<3）です。最新の 2026-07-28 クライアントは、initialize ハンドシェイクや Mcp-Session-Id を使わずに、 tools/list と tools/call を直接送信します。ローカルモードではファイル システム機能が保持されます。認証済みサービスの呼び出し元は、file: パイプラインを読み込んだり、ノートの output_dir／template_file を選択したり、 プロセス全体に適用されるパイプラインワークスペースを引き継いだりできません。 ノートの応答にはテナント相対の論理ロケーターを使い、サーバーのファイル システムパスは一切公開しません。サービス用 Compose スケジューラーは無効です。 機能の一覧については、統合と運用ガイドを 参照してください。

---

⚙️ 設定

この MCP サーバーは、MCP 互換のあらゆる AI ツールで動作します。お好みの クライアントを選択してください。

VS Code / Cursor (.vscode/mcp.json)

{
  "servers": {
    "pubmed-search": {
      "type": "stdio",
      "command": "uvx",
      "args": ["pubmed-search-mcp"],
      "env": {
        "NCBI_EMAIL": "[email protected]"
      }
    }
  }
}

任意：ブラウザーセッションによる PDF フォールバックを一度有効にすると、ツールで 自動的に利用できます。

{
  "servers": {
    "pubmed-search": {
      "type": "stdio",
      "command": "uvx",
      "args": ["pubmed-search-mcp"],
      "env": {
        "NCBI_EMAIL": "[email protected]",
        "BROWSER_FETCH_CONFIG": "{\"enabled\":true,\"auto_enabled\":true,\"broker_url\":\"http://127.0.0.1:8766/fetch\",\"token\":\"<random-32-byte-token>\",\"allowed_hosts\":[\"jamanetwork.com\",\"*.jamanetwork.com\",\"nejm.org\",\"*.nejm.org\"]}"
      }
    }
  }
}

この設定により、get_fulltext は、機関や出版社のランディングページに対して ローカルブローカーを自動的に試します。特定の呼び出しで無効にする場合に限り、 allow_browser_session=false を渡してください。

ダウンロードのインターセプトを有効にして、ローカルブローカーを起動します。

uv sync --extra browser-broker
uv run playwright install chromium
uv run python -c "import secrets; print(secrets.token_urlsafe(32))"
uv run pubmed-browser-fetch-broker --token "<same-random-32-byte-token>"

生成された値を両方のコマンド／設定にコピーしてください。公開済みのサンプル トークンを再利用しないでください。--token、BROWSER_FETCH_BROKER_TOKEN、 または共有の BROWSER_FETCH_TOKEN が必須です。ブローカーはシークレットを 生成したりログに記録したりせず、フェイルクローズします。ブローカーは、 ダウンロードのインターセプトを有効にした永続的なブラウザープロファイルを起動 します。ブローカーが制御するブラウザーウィンドウで一度ログインすれば、その後の PDF ダウンロードはネイティブの「名前を付けて保存」ダイアログを使わずに自動で 取得されます。

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "pubmed-search": {
      "command": "uvx",
      "args": ["pubmed-search-mcp"],
      "env": {
        "NCBI_EMAIL": "[email protected]"
      }
    }
  }
}

設定ファイルの場所：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

Claude Code

claude mcp add pubmed-search -- uvx pubmed-search-mcp

または、プロジェクトのルートにある .mcp.json に追加します。

{
  "mcpServers": {
    "pubmed-search": {
      "command": "uvx",
      "args": ["pubmed-search-mcp"],
      "env": {
        "NCBI_EMAIL": "[email protected]"
      }
    }
  }
}

Zed AI (settings.json)

Zed エディター（z.ai）は、MCP サーバーをネイティブで サポートしています。Zed の settings.json に追加します。

{
  "context_servers": {
    "pubmed-search": {
      "command": "uvx",
      "args": ["pubmed-search-mcp"],
      "env": {
        "NCBI_EMAIL": "[email protected]"
      }
    }
  }
}

ヒント：コマンドパレットを開いて zed: open settings を選択して編集するか、 Agent Panel → Settings →「Add Custom Server」に移動してください。

OpenClaw 🦞 (~/.openclaw/openclaw.json)

OpenClaw は、mcp-adapter pluginを 介して MCP サーバーを使用します。まずアダプターをインストールします。

openclaw plugins install mcp-adapter

次に、~/.openclaw/openclaw.json に追加します。

{
  "plugins": {
    "entries": {
      "mcp-adapter": {
        "enabled": true,
        "config": {
          "servers": [
            {
              "name": "pubmed-search",
              "transport": "stdio",
              "command": "uvx",
              "args": ["pubmed-search-mcp"],
              "env": {
                "NCBI_EMAIL": "[email protected]"
              }
            }
          ]
        }
      }
    }
  }
}

設定後、ゲートウェイを再起動します。

openclaw gateway restart
openclaw plugins list  # Should show: mcp-adapter | loaded

Cline (cline_mcp_settings.json)

{
  "mcpServers": {
    "pubmed-search": {
      "command": "uvx",
      "args": ["pubmed-search-mcp"],
      "env": {
        "NCBI_EMAIL": "[email protected]",
        "SEMANTIC_SCHOLAR_API_KEY": "your_semantic_scholar_key",
        "PUBMED_SEARCH_DISABLED_SOURCES": ""
      },
      "alwaysAllow": [],
      "disabled": false
    }
  }
}

その他の MCP クライアント

MCP 互換クライアントであれば、stdio トランスポートを介してこのサーバーを利用できます。

# Command
uvx pubmed-search-mcp

# With environment variable
[email protected] uvx pubmed-search-mcp

注：NCBI API ポリシーにより、NCBI_EMAIL は必須です。必要に応じて NCBI_API_KEY を設定すると、より高いレート制限（3 req/s から 10 req/s）を利用できます。 📖 詳細な統合ガイド：すべての環境変数、Copilot Studio のセットアップ、Docker のデプロイ、プロキシの設定、トラブルシューティングについては、docs/guides/INTEGRATIONS.md をご覧ください。

---

🎯 設計理念

基本方針：AI エージェントと学術検索エンジンの間に位置するインテリジェントなミドルウェアです。

このサーバーを選ぶ理由

ほかのツールは API への生のアクセスを提供します。このサーバーは、語彙の変換＋インテリジェントなルーティング＋研究分析を提供します。

課題	解決策
エージェントは ICD コードを使うが、PubMed は MeSH を必要とする	✅ ICD→MeSH の自動変換
データベースごとに API が異なる	✅ 統合検索による単一のエントリーポイント
臨床上の問いには構造化検索が必要	✅ PICO ハンドオフ＋パイプライン（validate_pico_plan がエージェントから渡された P/I/C/O を検証し、実行可能な template: pico パイプラインを返します）
医学用語の入力ミス	✅ ESpell による自動修正
1 つの情報源からの検索結果が多すぎる	✅ 複数ソースの並列検索と重複排除
研究の変遷をたどりたい	✅ 研究クロニクル＆ツリー：画期的な研究の検出、診断、サブトピックへの分岐、バージョン管理された改訂に対応
引用の文脈が不明確	✅ 引用ツリーによる前方・後方・ネットワーク検索
フルテキストにアクセスできない	✅ 複数ソースのフルテキスト（Europe PMC XML、Unpaywall の OA 所在情報、機関の直接アクセス／EZproxy、CORE、ダウンローダーのフォールバック）
遺伝子・医薬品の情報が複数のデータベースに分散している	✅ NCBI 拡張機能（Gene、PubChem、ClinVar）
最先端のプレプリントが必要	✅ プレプリント検索（arXiv、medRxiv、bioRxiv）。プレプリントの検出結果に基づくフィルタリングに対応しますが、査読状況は確認しません
文献管理ツールにエクスポートしたい	✅ ワンクリックエクスポート（公式 RIS／MEDLINE／CSL JSON、ローカル RIS／BibTeX／CSV／MEDLINE／JSON）

主な差別化要因

1. 語彙変換レイヤー - エージェントが自然な言葉で入力すると、各データベースの用語（MeSH、ICD-10、テキストマイニングで抽出されたエンティティ）に変換します
2. 統合検索ゲートウェイ - 1 回の unified_search() 呼び出しで、PubMed、Europe PMC、CORE、OpenAlex、Semantic Scholar、および有効化されているプレプリント／商用ソースに、対応機能に応じて振り分けて検索します
3. PICO ハンドオフ＋パイプライン - エージェントが P/I/C/O を抽出し、validate_pico_plan() が構造化された引き継ぎ内容を検証して、バックエンドの template: pico パイプラインが O を考慮した精度・再現率検索を実行します
4. 研究クロニクル＆系譜ツリー - ポリシーに基づくヒューリスティクスで節目を検出し、複数のシグナルによるスコアリングで画期的な論文を特定し、診断結果を提示します。バージョン管理された改訂を保存して差分を確認でき、サブトピックごとの分岐ツリーとして研究の変遷を可視化します
5. 引用ネットワーク分析 - 多層の引用ツリーを構築し、1 本の論文から研究分野全体を把握できます
6. 研究の全ライフサイクルに対応 - 検索 → 発見 → フルテキスト取得 → 分析 → エクスポートまで、すべてを 1 つのサーバーで行えます
7. エージェントを第一に考えた設計 - 人間が読むためではなく、機械による意思決定に最適化された出力を提供します

---

📡 外部 API とデータソース

この MCP サーバーは、複数の学術データベースおよび API と連携します。

主要なデータソース

ソース	対象範囲	用語体系	自動変換	説明
NCBI PubMed	3,600万件以上の論文	MeSH	✅ ネイティブ	生物医学文献の主要データベース
NCBI Entrez	複数データベース	MeSH	✅ ネイティブ	Gene、PubChem、ClinVar
Europe PMC	3,300万件以上	テキストマイニング	✅ 抽出	全文 XML アクセス
CORE	2億件以上	なし	➡️ フリーテキスト	オープンアクセスのアグリゲーター
Semantic Scholar	拡大を続けるグラフ＋オペレーターデータセット	S2 フィールド／バルク構文	✅ ブローカーがコンパイルするモード	関連度、範囲を限定したバルク取得、バッチ処理、引用グラフ、メタデータのみのリリース／差分プレーンに対応。パーティションのダウンロードには非対応
OpenAlex	拡大を続けるオープンな研究グラフ	トピック／キーワード	✅ キーワード＋範囲を限定したネイティブセマンティック検索	カーソル、コストの出所情報、エンティティグラフ、宣言済みのオペレーター向けスナップショットパスに対応。ローカルインデックスはまだありません
NIH iCite	PubMed	該当なし	該当なし	引用指標（RCR）

🔑 キー：✅ = 用語体系を完全にサポート | ➡️ = クエリをそのまま渡します（統制語彙は使用しません）

ICD コード：自動検出され、PubMed 検索の前に MeSH に変換されます

環境変数

# Required
[email protected]          # Required by NCBI policy

# Optional - For higher rate limits
NCBI_API_KEY=your_ncbi_api_key     # Get from: https://www.ncbi.nlm.nih.gov/account/settings/
CORE_API_KEY=your_core_api_key     # Get from: https://core.ac.uk/services/api
[email protected]      # Optional override; defaults to server/NCBI email
[email protected]     # Optional override; defaults to server/NCBI email
SEMANTIC_SCHOLAR_API_KEY=your_semantic_scholar_key # https://www.semanticscholar.org/product/api
OPENALEX_API_KEY=your_openalex_key # Raises the OpenAlex credit budget; actual grant is response-driven
PUBMED_SEARCH_DISABLED_SOURCES=    # Example: semantic_scholar

# Optional - Pipeline run-wide safety budgets
PUBMED_PIPELINE_RUN_TIMEOUT_SECONDS=120 # Shared end-to-end deadline (max 3600)
PUBMED_PIPELINE_MAX_EXTERNAL_CALLS=40   # Shared across sequential/parallel steps (max 1000)

# Optional - Network settings
HTTP_PROXY=http://proxy:8080       # HTTP proxy for API requests
HTTPS_PROXY=https://proxy:8080     # HTTPS proxy for API requests

# Optional - Institutional fulltext access
INSTITUTIONAL_DIRECT_FETCH=true    # Try DOI publisher pages before CORE fallback
EZPROXY_ENABLED=false              # Enable only after configuring EZPROXY_HOST + cookie
EZPROXY_HOST=ezproxy.example.edu
EZPROXY_COOKIE_FILE=/path/to/cookies.json

# Optional - Local note export
PUBMED_NOTES_DIR=/path/to/wiki/references  # save_literature_notes target folder
PUBMED_WORKSPACE_DIR=/path/to/project       # fallback: references/ under this workspace
PUBMED_DATA_DIR=~/.pubmed-search-mcp        # fallback: references/ under this data dir

CrossRef と Unpaywall は、ソース固有のメールアドレスが設定されていない限り、実行時サーバーの連絡先メールアドレス（NCBI_EMAIL、CLI の --email、または検出された git のメールアドレス）を再利用します。OpenAlex は匿名での通常利用を受け付け、オプションで API キーも利用できます。ブローカーは、恒久的な「ポライトプール」割り当てを前提とせず、応答に含まれるクレジット／レートのメタデータを読み取ります。

ローカルのノートエクスポートでは、ディレクトリを次の順序で解決します：output_dir 引数、PUBMED_NOTES_DIR、PUBMED_WORKSPACE_DIR/references、PUBMED_DATA_DIR/references、~/.pubmed-search-mcp/references。 このパス／テンプレートの選択は、信頼されたローカルモードにのみ適用されます。認証済みサービスのノートでは、常に現在のテナント専用の分離された references/ ディレクトリ内にある組み込み形式を使用します。 LLM の Wiki との互換性のため、wiki と foam のエクスポートでは、PMID、DOI、PMCID、またはフォールバック識別子に基づく安定したリンク先を使用します。タイトルはエイリアス／表示ラベルとして保持され、応答には解決できない Wiki リンクのチェック結果を示す wiki_validation が含まれます。

🔄 仕組み：ミドルウェアアーキテクチャ

┌─────────────────────────────────────────────────────────────────────────────┐
│                              AI AGENT                                        │
│                                                                              │
│   "Find papers about I10 hypertension treatment in diabetic patients"       │
│                                                                              │
└─────────────────────────────────┬───────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                     🔄 PUBMED SEARCH MCP (MIDDLEWARE)                        │
│  ┌─────────────────────────────────────────────────────────────────────────┐│
│  │  1️⃣ VOCABULARY TRANSLATION                                              ││
│  │     • ICD-10 "I10" → MeSH "Hypertension"                                ││
│  │     • "diabetic" → MeSH "Diabetes Mellitus"                             ││
│  │     • ESpell: "hypertention" → "hypertension"                           ││
│  └─────────────────────────────────────────────────────────────────────────┘│
│  ┌─────────────────────────────────────────────────────────────────────────┐│
│  │  2️⃣ INTELLIGENT ROUTING                                                 ││
│  │     ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐             ││
│  │     │ PubMed   │  │Europe PMC│  │   CORE   │  │ OpenAlex │             ││
│  │     │  36M+    │  │   33M+   │  │  200M+   │  │  250M+   │             ││
│  │     │  (MeSH)  │  │(fulltext)│  │  (OA)    │  │(metadata)│             ││
│  │     └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘             ││
│  │          └──────────────┴──────────────┴──────────────┘                 ││
│  │                              ▼                                          ││
│  │  3️⃣ RESULT AGGREGATION: Dedupe + Rank + Enrich                         ││
│  └─────────────────────────────────────────────────────────────────────────┘│
└─────────────────────────────────┬───────────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         UNIFIED RESULTS                                      │
│   • 150 unique papers (deduplicated from 4 sources)                          │
│   • Ranked by relevance + citation impact (RCR)                              │
│   • Full text links enriched from Europe PMC                                 │
└─────────────────────────────────────────────────────────────────────────────┘

---

🛠️ MCP ツールの概要

ツールを実用的なシステムとして理解したい場合は、41 個のツール名を暗記することから始めないでください。

まず、ツール使用ガイドをご覧ください。現在の 41 個のツールを 8 つの機能ファミリーに整理し、理論上の最小数を説明するとともに、人間とエージェントの両方に向けて、意図に基づくルーティング方法を紹介しています。

🔍 検索とクエリインテリジェンス

┌─────────────────────────────────────────────────────────────────┐
│                      SEARCH ENTRY POINT                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   unified_search()          ← 🌟 Single entry for all sources    │
│        │                                                         │
│        ├── Quick search     → Direct multi-source query          │
│        ├── Native semantic → Bounded OpenAlex semantic mode    │
│        ├── Systematic       → Bounded provider bulk/cursor mode  │
│        ├── PICO hints       → Detects comparison, shows P/I/C/O  │
│        └── ICD expansion    → Auto ICD→MeSH conversion           │
│                                                                  │
│   Sources: PubMed · Europe PMC · CORE · OpenAlex · S2            │
│   Auto: Deduplicate → Rank → Enrich full-text links              │
│                                                                  │
├─────────────────────────────────────────────────────────────────┤
│   QUERY INTELLIGENCE                                             │
│                                                                  │
│   generate_search_queries() → MeSH expansion + synonym discovery │
│   validate_pico_plan()              → Agent-provided PICO handoff        │
│   analyze_search_query()    → Query analysis without execution   │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

1つの検索エントリー、3つの取得ポリシー

汎用的な文献検索は、意図的に1つのMCPツール unified_search のみで公開しています。プロバイダー固有のAPIは、ブローカーの内部機能として維持されます。

# Default relevance/keyword routing across enabled sources
unified_search(query="treatment resistance")

# OpenAlex native semantic search (provider maximum 50 results)
unified_search(
    query="mechanisms of treatment resistance",
    sources="openalex",
    options="native_semantic",
)

# Deterministic/bounded retrieval: OpenAlex cursor and S2 bulk where selected
unified_search(
    query="melanoma AND immunotherapy",
    sources="openalex,semantic_scholar",
    options="systematic",
)

native_semantic と systematic は相互排他的であり、複数戦略による詳細検索の拡張を無効にします。明示的に指定されたソースで要求された取得モードがサポートされていない場合、ネットワーク呼び出しの前にエラーになります。ソースを自動選択する場合は、対応可能なプロバイダーのみが選択されます。limit は引き続きソースごとに最大100件です。そのため、systematic はプロバイダーを決定的かつ上限付きで実行することを意味し、網羅的なシステマティックレビューを保証するものではありません。構造化出力と成果物には、retrieval_mode とソースごとの source_metadata（要求されたモード／プロバイダーのモード、正規化またはコンパイル済みのクエリ、継続取得の可否、コスト／レート関連のメタデータ、利用可能な場合は警告）が記録されます。

公開リクエストの境界では、フェイルクローズを徹底します。limit は1から100までの整数でなければなりません。不明または不正な形式の filters／options、逆転または範囲外の年、サポートされていないランキングモードや出力モードは、プロバイダーへのI/Oが行われる前に検証エラーを返します。既定の詳細検索ポリシーでは、limit はソースごとの合計予算であり、そのソースの検索戦略間で分配されます。各戦略からそれぞれ limit 件を取得するわけではありません。戦略の呼び出しには、上限付きのグローバル／ソース別同時実行数とタイムアウトが適用されます。また、別のソースがタイムアウト、レート制限、または失敗した場合でも、成功したソースは引き続き利用できます。

このリリースでは、PubMed、Europe PMC、Scopus、Web of Science は引き続きキーワード検索のみです。これらのソースに対してシステマティック検索が明示的に要求された場合、1ページ分の結果をシステマティックな網羅性と誤って表示することなく、I/Oの前にエラーになります。

プロバイダーの制限とオペレーターのデータプレーン境界については、ソース契約、Semantic Scholar、OpenAlex を参照してください。

🔬 検索ツール（重要な論文を見つけた後）

                        Found important paper (PMID)
                                   │
           ┌───────────────────────┼───────────────────────┐
           │                       │                       │
           ▼                       ▼                       ▼
    ┌─────────────┐        ┌─────────────┐        ┌─────────────┐
    │  BACKWARD   │        │  SIMILAR    │        │  FORWARD    │
    │  ◀──────    │        │  ≈≈≈≈≈≈     │        │  ──────▶    │
    │             │        │             │        │             │
    │ get_article │        │find_related │        │find_citing  │
    │ _references │        │ _articles   │        │ _articles   │
    │             │        │             │        │             │
    │ Foundation  │        │  Similar    │        │ Follow-up   │
    │  papers     │        │   topic     │        │  research   │
    └─────────────┘        └─────────────┘        └─────────────┘

    fetch_article_details()   → Detailed article metadata
    get_citation_metrics()    → iCite RCR, citation percentile
    build_citation_tree()     → Full network visualization (6 formats)

📚 全文、図の抽出、エクスポート

検索後に論文を詳しく読む場合、unified_search(..., fulltext="prefetch") は、対象となるPMC XML論文を最大3件、バックグラウンドで準備します。後続の get_fulltext 呼び出しでは、準備済みまたは処理中のXMLを共有します。既定では無効であり、ポーリングや先回りしたPDF／ブラウザーへのアクセスは行いません。トレードオフと制限。

カテゴリー	ツール
全文	get_fulltext → PMCIDが利用可能な場合はEurope PMC XML。必要に応じて、DOIに基づくUnpaywall、機関の直接アクセス／EZproxy、CORE、ダウンローダーにフォールバックします
図	get_article_figures → PMC Open Access論文から図のラベル、キャプション、画像URL、PDFリンクを抽出します
図対応の全文	get_fulltext(include_figures=True) → 構造化された全文と合わせて図のメタデータを埋め込みます
テキストマイニング	get_text_mined_terms → 遺伝子、疾患、化学物質を抽出します
エクスポート	prepare_export → 公式のRIS／MEDLINE／CSL JSON、またはローカルのRIS／BibTeX／CSV／MEDLINE／JSON。save_literature_notes → ローカルのWiki／Foam互換／Markdown／MedPaper形式のノートと、コレクション単位のCSL JSON

get_fulltext は、coverage_status、正確な sources_tried／sources_completed、およびサニタイズ済みの source_errors を報告します。そのため、あるソースから利用可能な論文またはリンクが得られ、別のソースで失敗した場合、結果は partial となり、誤解を招くような完全成功や空の結果にはなりません。拡張PDF検索では、検索、ダウンロード、抽出、ツール出力、成果物を通じて、同じ不変の型付きカバレッジエンベロープが引き継がれます。

🖼️ OA 図を中心とした探索

エージェントが論文の本文だけでなく根拠となる図を必要とする場合は、PMC Open Access のパスを使用します。

• get_article_figures(source={"kind":"pmcid","value":"PMC12086443"}) → 図のラベル、キャプション、画像 URL、PDF／論文へのリンク
• get_fulltext(source={"kind":"pmcid","value":"PMC7096777"}, include_figures=True) → 図を本文中に含む構造化された全文
• 図の出力には論文の文脈が保持されるため、エージェントは各図を言及されているセクションに関連付けることができます

🧬 NCBI の拡張データベース

ツール	説明
search_gene	NCBI Gene データベースを検索
get_gene_details	NCBI Gene ID による遺伝子の詳細
get_gene_literature	遺伝子に関連付けられた PubMed 論文
search_compound	PubChem 化合物を検索
get_compound_details	PubChem CID による化合物の詳細
get_compound_literature	化合物に関連付けられた PubMed 論文
search_clinvar	ClinVar の臨床的変異を検索

🕰️ 研究の変遷記録と系統樹

ツール	説明
build_research_chronicle	画期的な研究の検出機能を備えた、永続化されたバージョン管理付きの研究の変遷記録を作成します。出力：summary、chronicle_map、timeline、tree、graph、evidence、milestones、mermaid、narrative、json
read_research_chronicle	リビジョンの読み込み、一覧表示、差分の確認、引用付きのナラティブ生成、マイルストーンの分布分析、または最大5つのトピックの比較を行います

# 1. Build from topic (retrieves PubMed, scores landmarks, clusters lineages)
build_research_chronicle(topic="remimazolam intraoperative", output="mermaid", max_events=30)

# 2. Continue an existing chronicle (inherits stored topic and filters to produce Revision N+1)
build_research_chronicle(chronicle_id="remimazolam-intraoperative-08c229f3")

# 3. Read revision diff, milestone analytics, or cross-topic comparison
read_research_chronicle(request={"action":"diff","chronicle_id":"remimazolam-intraoperative-08c229f3","from_revision":1})
read_research_chronicle(request={"action":"milestones","chronicle_id":"remimazolam-intraoperative-08c229f3"})
read_research_chronicle(request={"action":"compare","selection":{"kind":"topics","values":["remimazolam intraoperative","propofol intraoperative"]}})

mermaid は正規の統合ビューです。横方向の年軸（X軸）上で、観測された各研究系列（Y軸）が、取得した範囲内で最も早い日付の論文を起点に分岐します。これは説明可能なグループ分けであり、因果的な系譜や、その分野における真の最初の論文を主張するものではありません。系統の分類には、複数の論文で共有される MeSH ディスクリプターと著者キーワードを優先して使用します。該当するシグナルが単独の論文にしか見られない場合や不十分な場合は、警告を伴う研究段階へのフォールバックが発生します。同じ年の表示順は安定していますが、出版日の精度から前後関係を証明できない場合、その順序が先行関係を示すものではありません。Advanced Research Workflows (docs/guides/ADVANCED_RESEARCH_WORKFLOWS.md) と docs/design/RESEARCH_CHRONICLE_REFACTOR_SPEC.md を参照してください。

研究の変遷記録の Mermaid 出力は、構造化されたノードとエッジをもとに生成されます。ラベルの安全なエスケープ、循環や孤立ノードの修復、衝突しにくい ID、グラフサイズの制限に対応しています。研究の変遷記録全体が失敗するのではなく、リッチ構文から安全な構文、さらに最小限の構文へとフォールバックします。mermaid_validation.json には、すべての修正、フォールバック、視覚的に省略された項目が記録されます。chronicle.mmd は引き続き純粋な Mermaid ソースです。

研究の変遷記録のリビジョンは不変で、原子的に追記されます。セッションアーティファクトの永続化が有効な場合、アーティファクトの保存に失敗すると明示的に通知されますが、保存済みの研究の変遷記録リビジョンは引き続き利用できます。

トピック別のビルドでは、取得範囲を制限する前に PubMed に年の上限と下限を渡し、その後、最初と最後に観測された論文を保持しながら、画期的な研究と時間的な広がりをもとに上限まで補完します。監査記録には PubMed の returned／available 件数が記録されます。また、利用可能件数が不明な場合や、取得・選択の上限によりビューが網羅的でなくなる場合に警告が表示されます。PubMed のエラー、または論文の証拠がない範囲では、空のリビジョンは公開されません。

取得元情報では、ranking_requested と実際に適用された ranking を区別します。検証済みの引用数が実際に適用された場合に限り、iCite による並べ替えが適用されたと判定されます。バージョン管理された引用指標のカバレッジには、完了、一部、空、エラー、未要求の各結果が、安全な件数とエラー情報とともに記録されます。監査では、障害を引用数ゼロとして扱うのではなく、警告または失敗として処理します。

PMID の明示的な入力は厳密に検証されます（12345678 または PMID:12345678、正の ASCII 数字、最大20桁）。DOI やテキストの混在は、変換して受け入れるのではなく拒否されます。信頼できる出版日がないレコードは、日付のある項目の後に Undated として表示され、表示される年の範囲から除外されます。エントリー ID は、日付や分類器が修正されても、PMID／DOI による証拠の同一性を維持します。また、トピックの継続性には、Unicode、大小文字、空白を正規化した単一のキーを使用します。複数のシグナルを持つ論文には、明示的なクロスリンクを付けつつ、主分岐を1つだけ割り当てます。重複率が20％以上の場合、監査で警告されます。リビジョン差分で項目が存在しない場合、それは not_observed_in_revision を意味し、決定的な除外を意味するものではありません。

🏥 機関アクセスとICD変換

ツール	説明
configure_institutional_access	機関のリンクリゾルバーを設定します
get_institutional_link	OpenURL アクセスリンクを生成します
list_resolver_presets	リゾルバープリセットを一覧表示します
test_institutional_access	リゾルバーの設定をテストします
diagnose_institutional_access	直接 DOI、EZproxy、OpenURL のハンドオフ経路を診断します
convert_icd_mesh	ICD コードと MeSH 用語を相互変換します
unified_search	クエリ内の ICD コードを自動検出し、MeSH 用語に展開します

リゾルバーのベース URL には、クエリやフラグメントを含まない、認証情報なしの HTTP(S) URL を指定する必要があります。PMID 診断では、PubMed から DOI への処理結果が resolved、not_found、error のいずれかで報告されるため、上流の障害が DOI の欠落として報告されることはありません。

💾 セッション管理

ツール	説明
read_session	PMID、キャッシュ済み記事、要約、ログ、永続化された検索実行、再生引数、永続化アーティファクトを、アクションに応じて厳密に読み取ります

リソースを直接読み取れるエージェント向けに、動的な MCP リソースも利用できます。

• session://context — アクティブなセッションの状態
• session://last-search — 最新の検索メタデータ
• session://last-search/pmids — 最新の PMID リストと CSV 形式
• session://last-search/results — 最新の検索のキャッシュ済み記事ペイロード

永続化アーティファクト

セッション永続化が設定されている場合、再利用可能な unified_search および get_fulltext の応答について、永続化された MCP 出力アーティファクトが保存されます。ツールの応答はインデックスカードのような役割を果たします。エージェントがすぐに回答できるよう、件数、ソースに関する警告、アーティファクトのヒントを十分に含み、完全なエビデンスのペイロードは繰り返し読み取れるファイルに保持されます。コンパクトな artifact ロケーターには、artifact_id、artifact_uri、primary_file、summary、ファイル一覧、read_order、監査ステータス、正確な read_session(...) 取得ヒントが含まれます。ローカル MCP クライアントにも local_path と manifest_path を直接渡す場合に限り、PUBMED_ARTIFACT_INCLUDE_LOCAL_PATHS=true を設定してください。

サーバーのファイルシステムを読み取れないリモートクライアントは、セッションファサードを通じて同じコンテンツを取得できます。

read_session(request={"action":"list_artifacts"})
read_session(request={"action":"artifact","locator":{"kind":"artifact_id","value":"..."}})
read_session(request={"action":"artifact","locator":{"kind":"artifact_uri","value":"artifact://..."}})
read_session(request={"action":"artifact","locator":{"kind":"artifact_uri","value":"artifact://..."},"artifact_file":"audit.json"})
read_session(request={"action":"artifact","locator":{"kind":"artifact_uri","value":"artifact://..."},"artifact_file":"query_strategy.json"})
read_session(request={"action":"artifact","locator":{"kind":"artifact_uri","value":"artifact://..."},"artifact_file":"results.json","offset":0,"max_chars":200000})
read_session(request={"action":"list_artifacts","include_local_paths":true})

復旧可能な検索実行

セッション管理が有効な場合、すべての unified_search 呼び出しに安定した実行 ID が割り当てられます。これには通常の検索、検証／計画の失敗、およびインライン、saved:<name>、dry_run=true によるパイプライン実行が含まれます。構造化された結果とエラーには search_run のハンドオフが付加されます。Markdown では、同じ実行 ID がコンパクトな復旧メモとして返されます。通常の文献検索結果のエンベロープには、次の2つの独立した機械可読コントラクトが含まれます。

• search_status は、範囲が限定された取得結果を示します。state （completed、empty、partial、failed）、bounded=true、 exhaustive=false、返された件数、試行済み／成功／失敗／再試行可能な ソース、継続対象／完全性不明のソースリストが含まれます。
• search_run は復旧用のハンドオフです。安定した run_id、ジャーナルのステータス、 recoverable、正確な read_session の確認／再生引数、コミット済みの場合は アーティファクト URI が含まれます。 テナントスコープの search-run/v1 ジャーナルは、プロバイダーへの I/O や終端検証応答の前に公開され、サニタイズ済みリクエスト、プラン、ソースまたはパイプラインの各ステップにおける物理的な試行、件数、安全な失敗情報、結果参照、および該当する場合はアーティファクトロケーターを記録します。終端状態は completed、partial、failed、cancelled のいずれかになります。有効な検索で結果が 0 件の場合は、search_status.state が empty の completed ランになります。再起動時には、未完了の started／planned／running エントリーが消失するのではなく、1 回だけ interrupted として復旧されます。ドライランではない保存済みパイプラインには、さらに PipelineStore のレポート／実行履歴が保持されます。これは呼び出しレベルの検索ジャーナルを補完するものであり、置き換えるものではありません。

パイプラインのリプレイでは、元のインライン引数または saved:<name> 引数と、dry_run／stop_at が保持されます。キー、トークン、Cookie、パスワードなどの認証情報を含むパイプラインテキストは拒否され、失敗した実行として記録されます。プロバイダーの認証情報はサーバーの環境変数／設定に指定し、パイプラインの YAML や JSON には決して含めないでください。

read_session(request={"action":"search_runs"})
read_session(request={"action":"search_runs","status":"partial"})
read_session(request={"action":"search_run","run_id":"..."})
read_session(request={"action":"replay_search","run_id":"..."})

replay_search が返すのは、元の認証情報を含まない unified_search の kwargs のみです。ネットワーク呼び出しが自動実行されることはありません。エージェントまたはユーザーが内容を確認し、明示的に送信する必要があります。プロバイダーのカーソル／トークン値は、source_metadata と query_strategy.json に不透明な来歴情報として保持されますが、公開されているカーソル再開パラメーターはまだないため、リプレイでは新たに上限付き検索が開始されます。

終端ジャーナルへの書き込みを復旧できない場合、応答には search_run.status="history_unavailable"、history_available=false、意図された終端ステータス、および警告が含まれます。永続的な復旧が保証されないため、inspect／replay アクションは意図的に省略されます。検索結果自体は引き続き利用できる場合があります。

unified_search のアーティファクトには、リサーチ用エンベロープが使用されます。まずソース件数と完全性に関する警告を audit.json で確認し、次に実際に実行されたプランを正確に記録する query_strategy.json を確認してから、記事の全リストを含む results.json／results.toon を確認してください。これにより、学術的な追跡可能性を損なうことなく、MCP 応答のトークン数を抑えられます。

アーティファクトは計算済みの結果オブジェクトから生成されるため、アーティファクトを読み取っても検索や全文取得は再実行されません。 アーティファクトのディレクトリがアトミックに公開された後、セッションインデックスが更新される前にクラッシュが発生した場合、セッションの再読み込み時に、完全でチェックサムインデックス済みのマニフェストのみが検出され、search_run_id によって孤立したアーティファクトが検索ランに再リンクされます（古いアーティファクトについては、より慎重なクエリ照合が行われます）。 read_session はデフォルトでローカルファイルシステムのパスを秘匿します。local_path と manifest_path はサーバー上のローカルパスであり、移植可能なクライアントパスではありません。get_fulltext のアーティファクトには、購読または機関を通じてアクセスしたコンテンツを含め、記事本文が含まれる場合があります。出版社、ライセンス、および機関のアクセス条件に従って保存、共有してください。 大きな get_fulltext 応答は、アーティファクトが利用可能な場合、プレビューとしてインラインで返されます。保存された全文を取得するには、アーティファクトロケーターを使用してください。

1 つのソースで障害が発生しても検索全体を継続できる場合、JSON 応答には source_errors が含まれることがあります。Markdown 応答には Source warnings 行が表示されます。Semantic Scholar で HTTP 429 が発生した場合は、SEMANTIC_SCHOLAR_API_KEY を設定して後でもう一度試すか、sources="auto,-semantic_scholar" または PUBMED_SEARCH_DISABLED_SOURCES=semantic_scholar を指定して一時的に除外してください。

パイプライン管理

パイプライン管理では、単一の目的に特化した、スキーマに厳密に準拠する7つのツールを使用します。各ツールが受け付けるのは、その操作に関連するフィールドのみです。そのため、スペルミスや無関係な引数が指定されると、黙って無視されるのではなく、安全側に失敗します。

ツール	説明
save_pipeline	パイプライン設定を後で再利用できるように保存します（YAML/JSON、自動検証）
list_pipelines	保存済みパイプラインを一覧表示します（タグ／スコープで絞り込み）
load_pipeline	保存名を指定して読み込みます。信頼されたローカルの呼び出し元はファイルも読み込めます
delete_pipeline	パイプラインとその実行履歴を削除します
get_pipeline_history	記事の差分分析を含む実行履歴を表示します
schedule_pipeline	定期実行するパイプラインのスケジュールを作成または更新します
unschedule_pipeline	定期実行するパイプラインのスケジュールを削除します

認証済みのサービス呼び出し元は、テナントから決定されるストア内の名前付きパイプラインを使用します。workspace と file: へのアクセスはローカル限定です。サービスの Compose プロファイルは、単一リーダーを別途設計しない限り、スケジュールを実行しません。パイプライン履歴は安全側に失敗します。永続化された実行データに不正な形式のものが1つでもある場合、不完全な一覧や誤った「履歴なし」という結果を返す代わりに、安全で明示的なエラーを返します。

ステップごとのチュートリアル：

• 英語：docs/guides/PIPELINE_MODE_TUTORIAL.en.md
• 繁体字中国語：docs/guides/PIPELINE_MODE_TUTORIAL.md

👁️ ビジョンと画像検索

ツール	説明
prepare_figure_search	アップロードされた画像、画像 URL、またはデータ URI をエージェントのビジョン機能に渡し、検索語を抽出します
search_biomedical_images	Open-i でバイオメディカル画像を検索します（X線、顕微鏡画像、写真、図）

ユーザーが画像を提示し、エージェントがまずその意味を解釈する必要がある場合は、prepare_figure_search を使用します。このツールは MCP の ImageContent と、LLM エージェントが英語のバイオメディカル用語を抽出した後、類似する Open-i 画像を探すための search_biomedical_images、または関連論文を探すための unified_search を続けて実行するよう指示する内容を返します。

Open-i の結果には、ソースごとの型付きカバレッジ情報が付属します。有効な total=0 と空のリストは一致する結果がないことを意味します。不正なレスポンスやソースの停止は failed、有効な行と無効な行が混在する場合は partial です。失敗したソースは sources_used から除外され、その合計数は不明のままになります。また、Markdown には「画像がない」と断定する代わりに、サニタイズされたカバレッジ情報が表示されます。

📄 プレプリント検索

unified_search の options フラグを使って、arXiv、medRxiv、bioRxiv のプレプリントサーバーを検索します。

ソース、フィルター、オプションのトークンには、正規の表記を厳密に使用してください。カンマ区切りのトークンの前後に空白を入れたり、トークンを重複させたりしないでください。別名や大文字・小文字の異なる表記は拒否されます。

• preprints：プレプリントサーバーを検索し、article_type=PREPRINT としてプレプリントをメインの集約結果セットに統合します。
• include_detected_preprints：プレプリントサーバーのクロールを追加せず、選択した他の学術ソースからプレプリントのヒューリスティックによって特定されたレコードを保持します。

プレプリントのソースメタデータには、プロバイダーへのクエリ／検索期間、結果上限、判明していないコーパス総件数、ローカルでの年フィルター適用後の件数が含まれます。厳密な年範囲が指定されている場合、年が不明なレコードは除外されます。medRxiv／bioRxiv では、期間が限定された日付フィードに対してすべての語を文字どおりに照合するため、ブール式やグループ化されたクエリ構文は、暗黙に解釈し直されるのではなく、ネットワーク I/O の前に失敗します。

推奨される組み合わせ：

• options が空の場合：プレプリントと判定されたレコードは除外されます。このヒューリスティックによって、残りのすべてのレコードが査読済みだと証明されるわけではありません。
• options="preprints"：arXiv、medRxiv、bioRxiv を検索し、そのプレプリントをメインの結果と合わせて順位付けし、重複を除去します。
• options="include_detected_preprints"：プレプリントサーバーのクロールは行いません。選択したソースからすでに返された、プレプリントと判定されたレコードを保持します。

プレプリントの検出 — 次の条件に基づいて、論文をプレプリントとして特定します。

• ソース API から取得した論文種別（OpenAlex、CrossRef、Semantic Scholar）
• PubMed ID がなく、arXiv ID がある
• 既知のプレプリントサーバーのソース名またはジャーナル名
• プレプリントサーバーに対応する DOI プレフィックス（例：10.1101/ → bioRxiv／medRxiv、10.48550/ → arXiv）

研究の時系列上の系譜を把握するには、build_research_chronicle を使用してください。これは研究の時系列を扱う唯一の機能であり、監査済みのタイムライン、分岐マップ、説明、改訂履歴を提供します。

🧪 臨床試験登録の補助検索

ClinicalTrials.gov は暗黙的に検索されることはありません。期間を限定した登録情報の補助検索が役立つ場合は、検索に options="clinical_trials" を追加してください。これは文献ソースの検索計画、論文の順位付け、ソース件数とは別に扱われます。Markdown では最大 3 件のレコードを表示します。JSON／TOON では、同じ補助検索結果を構造化データとして返します。バージョン管理された clinical-trials-adjunct/v1 のカバレッジ情報には、取得状況と形式の状態、返された件数、完全性、警告、サニタイズされた失敗情報が、レスポンスと永続化されたアーティファクトの両方で一貫して記録されます。

unified_search(query="remimazolam ICU sedation", options="clinical_trials")

📊 件数優先の概要

unified_search では、順位付けされた一覧を読む前にルーティングの参考情報を確認したいエージェント向けに、既存のソースカバレッジと判断のヒントを先に表示することもできます。

オプションフラグ	説明
counts_first	ソース件数テーブル、カバレッジの概要、次に使うツールの推奨事項をレスポンスに追加します

例：

unified_search(query="remimazolam ICU sedation", options="counts_first")

このモードは、エージェントがソースを拡張するか、主要な PMID を確認するか、全文を取得するか、図表を抽出するか、タイムラインの探索に切り替えるかを判断する場合に役立ちます。

⏱️ MCP の進捗報告

MCP クライアントから進捗トークンが渡されると、unified_search、build_research_chronicle、get_fulltext、get_text_mined_terms は、主要な処理段階ごとに進捗を報告します。 これにより、時間のかかる検索中にエージェントが待機する「ブラックボックス」状態を軽減できます。 進捗コールバックは可能な範囲で実行され、厳格なタイムアウトは 100 ms です。応答が滞ったコールバックはキャンセルされます。ホストの不具合でキャンセルが抑止された場合、そのタスクはサーバーが所有する最大 32 件のプールに隔離されるため、バックグラウンド処理が無制限に増えることなく、コアツールの応答性が維持されます。

---

📋 エージェントの使用例

1️⃣ クイック検索（最も簡単）

# Agent just asks naturally - middleware handles everything
unified_search(query="remimazolam ICU sedation", limit=20)

# Or with clinical codes - auto-converted to MeSH
unified_search(query="I10 treatment in E11.9 patients")
#                     ↑ ICD-10           ↑ ICD-10
#                     Hypertension       Type 2 Diabetes

2️⃣ PICO 臨床疑問

シンプルな方法 — unified_search で直接検索できます（PICO への分解は不要です）。

# unified_search searches as-is; detects "A vs B" pattern and shows PICO hints in metadata
unified_search(query="Is remimazolam better than propofol for ICU sedation?")
# → Multi-source keyword search + PICO hint metadata in output
# ⚠️ This does NOT auto-decompose PICO or expand MeSH!
# For structured PICO search, use the Agent workflow below

エージェントのワークフロー — エージェントが提示する PICO とバックエンドのパイプライン検索を組み合わせます（臨床疑問におすすめです）。

┌─────────────────────────────────────────────────────────────────────────┐
│  "Is remimazolam better than propofol for ICU sedation?"                │
└─────────────────────────────────┬───────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         validate_pico_plan()                                     │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐                     │
│  │    P    │  │    I    │  │    C    │  │    O    │                     │
│  │  ICU    │  │remimaz- │  │propofol │  │sedation │                     │
│  │patients │  │  olam   │  │         │  │outcomes │                     │
│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘                     │
└───────┼────────────┼────────────┼────────────┼──────────────────────────┘
        │            │            │            │
        ▼            ▼            ▼            ▼
┌─────────────────────────────────────────────────────────────────────────┐
│              generate_search_queries() × 4 (parallel)                    │
│                                                                          │
│  P → "Intensive Care Units"[MeSH]                                        │
│  I → "remimazolam" [Supplementary Concept], "CNS 7056"                   │
│  C → "Propofol"[MeSH], "Diprivan"                                        │
│  O → "Conscious Sedation"[MeSH], "Deep Sedation"[MeSH]                   │
└─────────────────────────────────┬───────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────┐
│              Agent combines with Boolean logic                           │
│                                                                          │
│  (P) AND (I) AND (C) AND (O)  ← High precision                           │
│  (P) AND (I OR C) AND (O)     ← High recall                              │
└─────────────────────────────────┬───────────────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────────────┐
│              unified_search() (auto multi-source + dedup)                │
│                                                                          │
│  PubMed + Europe PMC + CORE + OpenAlex → Auto deduplicate & rank         │
└─────────────────────────────────────────────────────────────────────────┘

# Step 1: Agent extracts P/I/C/O, then validates the structured handoff
pico = validate_pico_plan(
    description="Is remimazolam better than propofol for ICU sedation?",
    p="ICU patients requiring sedation",
    i="remimazolam",
    c="propofol",
    o="sedation efficacy, delirium, hypotension"
)
# Returns validation plus a ready-to-run `template: pico` pipeline.

# Step 2: Get MeSH for each element (parallel!)
generate_search_queries(topic="ICU patients")   # P
generate_search_queries(topic="remimazolam")    # I
generate_search_queries(topic="propofol")       # C
generate_search_queries(topic="sedation")       # O

# Step 3: Either pass expanded fragments back as p_query/i_query/c_query/o_query
# or let the backend pipeline use the structured P/I/C/O labels.

# Step 4: Search (backend runs O-aware precision/recall searches, dedup, rank)
unified_search(
    query="Is remimazolam better than propofol for ICU sedation?",
    pipeline=pico["pipeline"]
)

3️⃣ 主要論文から調査

# Found landmark paper PMID: 33475315
find_related_articles(pmid="33475315")   # Similar methodology
find_citing_articles(pmid="33475315")    # Who built on this?
get_article_references(pmid="33475315")  # What's the foundation?

# Build complete research map
build_citation_tree(pmid="33475315", depth=2, output_format="mermaid")

4️⃣ 遺伝子／医薬品の調査

# Research a gene
search_gene(query="BRCA1", organism="human")
get_gene_literature(gene_id="672", limit=20)

# Research a drug compound
search_compound(query="propofol")
get_compound_literature(cid="4943", limit=20)

5️⃣ 検索結果のエクスポート

# Export last search results
prepare_export(pmids="last", format="ris")      # → EndNote/Zotero
prepare_export(pmids="last", format="bibtex", source="local")  # → LaTeX
prepare_export(pmids="last", format="csl")      # → CSL JSON from the official NCBI Citation API
save_literature_notes(pmids="last")              # → local wiki note + Foam-compatible wikilinks + CSL JSON
save_literature_notes(pmids="last", note_format="medpaper", output_dir="./references")
save_literature_notes(pmids="last", template_file="./reference-template.md")

# Retrieve full text for a selected paper from the last search
get_fulltext(source={"kind":"pmid","value":"12345678"}, extended_sources=True)

6️⃣ プレプリント検索

# Search preprint sources alongside the regular scholarly-source set
unified_search(query="COVID-19 vaccine efficacy", options="preprints")
# → Main aggregated results include labelled arXiv, medRxiv, and bioRxiv preprints

# Retain preprints detected in otherwise selected sources without adding a crawl
unified_search(query="CRISPR gene therapy", options="include_detected_preprints")

# Default heuristic policy
unified_search("diabetes treatment")
# → Detected preprints are filtered; remaining peer-review status is not proven

7️⃣ パイプライン（再利用可能な検索プラン）

# Save a template-based pipeline through the primary facade
save_pipeline(
    name="icu_sedation_weekly",
    config="template: pico\ntemplate_params:\n  P: ICU patients\n  I: remimazolam\n  C: propofol\n  O: delirium",
    tags=["anesthesia","sedation"],
    description="Weekly ICU sedation monitoring"
)

# Save a custom DAG pipeline
save_pipeline(
    name="brca1_comprehensive",
    config="""
steps:
  - id: expand
    action: expand
    params: { topic: BRCA1 breast cancer }
  - id: pubmed
    action: search
    params: { query: BRCA1, sources: [pubmed], limit: 50 }
  - id: expanded
    action: search
    inputs: [expand]
    params: { strategy: mesh, sources: [pubmed, openalex], limit: 50 }
  - id: merged
    action: merge
    inputs: [pubmed, expanded]
    params: { method: rrf }
  - id: enriched
    action: metrics
    inputs: [merged]
output:
  limit: 30
  ranking: quality
"""
)

# Execute a saved pipeline
unified_search(pipeline="saved:icu_sedation_weekly")

# List & manage
list_pipelines(tag="anesthesia")
load_pipeline(source="brca1_comprehensive")  # Review YAML
get_pipeline_history(name="icu_sedation_weekly")  # View past runs

---

🔍 検索モードの比較

┌─────────────────────────────────────────────────────────────────────────┐
│                        SEARCH MODE DECISION TREE                         │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│   "What kind of search do I need?"                                       │
│         │                                                                │
│         ├── Know exactly what to search?                                 │
│         │   └── unified_search(query="topic keywords")                   │
│         │       → Quick, auto-routing to best sources                    │
│         │                                                                │
│         ├── Have a clinical question (A vs B)?                           │
│         │   └── Agent P/I/C/O → validate_pico_plan() handoff                  │
│         │       → unified_search(template:pico) or expanded Boolean    │
│         │                                                                │
│         ├── Need comprehensive systematic coverage?                      │
│         │   └── generate_search_queries() → parallel search              │
│         │       → MeSH expansion, multiple strategies, merge             │
│         │                                                                │
│         └── Exploring from a key paper?                                  │
│             └── find_related/citing/references → build_citation_tree     │
│                 → Forward/backward citation network                      │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

モード	エントリーポイント	最適な用途	自動機能
クイック	unified_search()	トピックの高速検索	ICD→MeSH、複数ソース、重複排除
PICO	エージェントによる P/I/C/O -> validate_pico_plan()	臨床疑問	ハンドオフの検証 -> template:pico バックエンド検索
システマティック	generate_search_queries() → unified_search(options="systematic")	再現可能なレビューの出発点	MeSH／同義語に加え、上限付きの一括／カーソル実行。網羅性を保証するものではありません
ネイティブセマンティック	unified_search(options="native_semantic")	タイトル／抄録の概念的類似性	対応機能の検証、OpenAlex セマンティックモード、最大50件
探索	find_*_articles()	主要論文からの調査	引用ネットワーク、関連記事

---

🤖 Claude Skills（AI エージェントのワークフロー）

.claude/skills/ に用意されたワークフローガイドは、利用スキル（MCP サーバーの使用向け）と開発スキル（プロジェクトの保守向け）に分かれています。

📚 利用スキル（11件）— この MCP サーバーを使用する AI エージェント向け

スキル	説明
pubmed-quick-search	フィルターを使った基本検索
pubmed-systematic-search	MeSH の拡張、包括的な検索
pubmed-pico-search	臨床疑問の分解
pubmed-paper-exploration	引用ツリー、関連記事
pubmed-research-chronicle	永続的でバージョン管理された研究の変遷
pubmed-gene-drug-research	遺伝子／PubChem／ClinVar
pubmed-fulltext-access	Europe PMC、CORE の全文
pubmed-export-citations	RIS／BibTeX／CSV／CSL のエクスポートガイド
pubmed-multi-source-search	データベース横断の統合検索
pubmed-mcp-tools-reference	ツールの完全なリファレンスガイド
pipeline-persistence	検索プランの保存、読み込み、再利用

🔧 開発スキル（15）— プロジェクトのコントリビューター向け

スキル	説明
changelog-updater	CHANGELOG.md を自動更新します
code-refactor	DDD アーキテクチャのリファクタリング
code-reviewer	コード品質とセキュリティのレビュー
ddd-architect	新機能向けの DDD スキャフォールド
git-doc-updater	コミット前にドキュメントを同期します
git-precommit	コミット前ワークフローのオーケストレーション
memory-checkpoint	コンテキストを Memory Bank に保存します
memory-updater	Memory Bank ファイルを更新します
pdf-asset-extractor	引用に使える PDF アセットを抽出して一覧化します
project-init	新しいプロジェクトを初期化します
readme-i18n	README の多言語版を同期します
readme-updater	コード変更に合わせて README を同期します
roadmap-updater	ROADMAP.md のステータスを更新します
test-generator	テストスイートを生成します
tool-sync	MCP レジストリと生成されたツールドキュメントを一致させます

📁 場所：.claude/skills/*/SKILL.md（Claude Code 固有で、リポジトリのスキルの唯一の信頼できる情報源です） リポジトリのスキルを .github/skills/ に複製したり、分割したりしないでください。 これらのリポジトリのスキルはプロジェクトにスコープされており、バージョン管理下に置く必要があります。個人用のプロジェクト横断スキルは、このリポジトリではなく、~/.copilot/skills/ や ~/.claude/skills/ などのユーザーディレクトリに配置してください。

Research スキルのインストールでは、既存のカスタマイズが保持されます。インストールとアップグレードのポリシーを参照してください。コントリビューターはプッシュ前にローカルの全チェックを実行します。通常の CI では、より小規模な独立したスモークチェックを実行します。

完了した10フェーズのコアレビューでは、src/pubmed_search/ 内の Python ファイル223個すべてを対象としています。対象には、クラス456個と関数／メソッド／ネストされた関数2,445個が含まれます。2,901個すべての定義について、判定、根拠、現在のファイルの SHA-256 が記録されており、未対応または古いものはありません。これは執筆者によるセルフレビューであり、テスト結果とは別のものです。uv run python scripts/perf/symbol_inventory.py --require-reviewed src/ を実行して現在のツリーを再確認してください。その後のソース編集によって、影響を受けるレビューは無効になります。テストとスクリプトも一覧化されていますが、この完全なコアレビューの対象範囲には含まれません。

実際の MCP 回帰チェック

41個のパブリックツールすべてを、MCP プロトコル経由で、ソースツリーの stdio、Streamable HTTP、新規インストールした wheel の stdio を通じて呼び出します。 wheel の経路では、サーバーコードを空の仮想環境からのみインポートします。外部フィクスチャが提供するのは、決定論的なプロバイダー境界だけです。 決定論的な子サーバーが外部プロバイダーとの境界を置き換えます。レジストリ、スキーマ、アプリケーションサービス、永続化、アーティファクト、Chronicle のリビジョン、パイプライン、スケジューリングは実際のものを使用します。 オプトインの拡張 CI では、MCP 経由で返される Chronicle と引用の Mermaid ソースを、ピン留めされた Mermaid 11.16.1 でレンダリングします。そのため、プレゼンテーション層の構文破損があるとチェックは失敗します。 追加の実際の stdio による拒否チェックでは、廃止されたツール名、従来のフラットなリクエスト形式、曖昧なスカラー値、不正なコンテナーが引き続き拒否されることを確認します。

uv run pytest -q tests/test_all_tools_mcp_acceptance.py

テストアーキテクチャ、CI チェック、ライブプロバイダーとの境界については、開発者ガイドを参照してください。

---

🏗️ アーキテクチャ（DDD）

このプロジェクトでは、文献調査ドメインの知識をコアモデルとする ドメイン駆動設計（DDD） アーキテクチャを採用しています。

src/pubmed_search/
├── domain/                     # Core business logic
│   └── entities/article.py     # UnifiedArticle, Author, etc.
├── application/                # Use cases
│   ├── search/                 # QueryAnalyzer, ResultAggregator
│   ├── export/                 # Citation export (RIS, BibTeX...)
│   └── session/                # SessionManager
├── infrastructure/             # External systems
│   ├── ncbi/                   # Entrez, iCite, Citation Exporter
│   ├── sources/                # Europe PMC, CORE, CrossRef...
│   └── http/                   # HTTP clients
├── presentation/               # User interfaces
│   ├── mcp_server/             # MCP tools, prompts, resources
│   │   ├── tools/              # discovery, strategy, pico, export...
│   │   └── http_cli.py         # Canonical Streamable HTTP/SSE launcher
│   └── browser_fetch_broker.py # Optional isolated browser-fetch service
└── shared/                     # Cross-cutting concerns
    ├── exceptions.py           # Unified error handling
    └── async_utils.py          # Rate limiter, retry, circuit breaker

内部の仕組み（エージェントからは見えません）

仕組み	説明
セッション	自動作成、自動切り替え
キャッシュ	検索結果を自動キャッシュし、重複した API 呼び出しを回避
レート制限	NCBI API の制限（0.34s/0.1s）を自動的に遵守
MeSH 検索	generate_search_queries() が NCBI MeSH データベースに自動で問い合わせ
ESpell	自動スペル修正（remifentanyl → remifentanil）
クエリ分析	提案された各クエリについて、PubMed による実際の解釈を表示

語彙変換レイヤー（主要機能）

私たちの中核的な価値：私たちは、エージェントと検索エンジンの間に立つインテリジェントなミドルウェアとして、語彙の標準化を自動的に処理するため、エージェントが各データベースの用語を把握する必要はありません。

データソースごとに、異なる統制語彙体系が使われています。このサーバーは自動変換を提供します。

API／データベース	語彙体系	自動変換
PubMed / NCBI	MeSH（Medical Subject Headings）	✅ expand_with_mesh() による完全サポート
ICD コード	ICD-10-CM / ICD-9-CM	✅ MeSH への自動検出・変換
Europe PMC	テキストマイニングされたエンティティ（遺伝子、疾患、化学物質）	✅ get_text_mined_terms() による抽出
OpenAlex	トピック／キーワード（モデルによる推論）	✅ ブローカーによるキーワードモード。選択時は範囲を限定したネイティブのセマンティックモード
Semantic Scholar	S2 フィールド／一括クエリ構文	✅ ブローカーが関連性モードまたは範囲を限定した一括モードを選択。プロバイダーの注釈で出所を保持
CORE	なし	❌ フリーテキストのみ
CrossRef	なし	❌ フリーテキストのみ

ICD → MeSH の自動変換

ICD コード（例：高血圧を表す I10）で検索すると、unified_search() が自動的に次の処理を行います。

1. detect_and_expand_icd_codes() を使用して ICD-10／ICD-9 のパターンを検出します
2. 内部マッピング（ICD10_TO_MESH、ICD9_TO_MESH）から対応する MeSH 用語を検索します
3. MeSH の同義語でクエリを拡張し、包括的に検索します

# Agent calls unified_search with clinical terminology
unified_search(query="I10 treatment outcomes")

# Server auto-expands to PubMed-compatible query
"(I10 OR Hypertension[MeSH]) treatment outcomes"

📖 アーキテクチャの詳細：ARCHITECTURE.md

MeSH の自動拡張＋クエリ分析

generate_search_queries("remimazolam sedation") を呼び出すと、内部で次の処理が行われます。

1. ESpell による修正 — スペルミスを修正します
2. MeSH クエリ — Entrez.esearch(db="mesh") で標準語彙を取得します
3. 同義語の抽出 — MeSH Entry Terms から同義語を取得します
4. クエリ分析 — 各クエリを PubMed がどのように解釈するかを分析します

{
  "mesh_terms": [
    {
      "input": "remimazolam",
      "preferred": "remimazolam [Supplementary Concept]",
      "synonyms": ["CNS 7056", "ONO 2745"]
    }
  ],
  "all_synonyms": ["CNS 7056", "ONO 2745", ...],
  "suggested_queries": [
    {
      "id": "q1_title",
      "query": "(remimazolam sedation)[Title]",
      "purpose": "Exact title match - highest precision",
      "estimated_count": 8,
      "pubmed_translation": "\"remimazolam sedation\"[Title]"
    },
    {
      "id": "q3_and",
      "query": "(remimazolam AND sedation)",
      "purpose": "All keywords required",
      "estimated_count": 561,
      "pubmed_translation": "(\"remimazolam\"[Supplementary Concept] OR \"remimazolam\"[All Fields]) AND (\"sedate\"[All Fields] OR ...)"
    }
  ]
}

クエリ分析の価値：エージェントは remimazolam AND sedation がこの2つの単語だけを検索すると考えますが、実際には PubMed はこれを Supplementary Concept と同義語に拡張し、検索結果は8件から561件に増えます。これにより、エージェントは意図した検索と実際の検索の違いを理解できます。

---

🔒 ローカル HTTPS デモとサービスのデプロイ

同梱の自己署名証明書と curl -k を使う手順はローカル TLS デモであり、 本番環境向けのセキュリティ設定ではありません。共有サービスでは、 DEPLOYMENT.md の説明に従って、認証付きサービス用 Compose ファイルと 信頼できる証明書を使用してください。

ローカル HTTPS のスモークテスト

# Step 1: Generate SSL certificates
./scripts/generate-ssl-certs.sh

# Step 2: Start HTTPS service (Docker)
./scripts/start-https-docker.sh up

# Verify deployment
curl -k https://localhost/

HTTPS エンドポイント

サービス	URL	説明
MCP	https://localhost/mcp	Streamable HTTP MCP エンドポイント
ヘルス	https://localhost/health	ヘルスチェック
レディネス	https://localhost/ready	レディネスチェック
情報	https://localhost/info	実行時のトランスポートとエンドポイントのメタデータ
エクスポート	https://localhost/exports	ローカルで準備されたエクスポートの一覧。サービスモードではベアラー認証とテナントスコープが必要

リモート MCP クライアントの設定

{
  "mcpServers": {
    "pubmed-search": {
      "url": "https://localhost/mcp"
    }
  }
}

---

🏢 Microsoft Copilot Studio との連携

PubMed Search MCP を Microsoft 365 Copilot（Word、Teams、Outlook）と連携します！

クイックスタート

# Unpublished local schema/protocol smoke only; never tunnel local mode
pubmed-search-mcp-http --mode local --transport streamable-http \
  --copilot-compatible --host 127.0.0.1 --port 8765

# Public Copilot endpoint: authenticated service mode is mandatory
export PUBMED_AUTH_TOKENS="copilot:$(openssl rand -hex 32)"
export NGROK_DOMAIN="your-assigned-domain.ngrok.dev"
./scripts/start-copilot-studio.sh --with-ngrok

Copilot Studio の設定

フィールド	値
サーバー名	PubMed Search
サーバー URL	https://your-server.com/mcp
認証	サービスモードでは Bearer トークンを使用します。未公開のローカルデモの場合に限り、None を使用します

📖 完全なドキュメント：copilot-studio/README.md

パッケージ化された Copilot HTTP のセマンティクスには、pubmed-search-mcp-http --copilot-compatible を使用してください。run_server.py はソースツリーでの開発用ラッパーです。run_copilot.py は、同じ正式な 41 ツールの厳格なレジストリを対象とするループバック専用のスモークテスト起動ツールであり、別個の互換性レイヤーではありません。トンネルスクリプトには割り当て済みの NGROK_DOMAIN が必要です。また、使用中のバックエンドポートがあると起動を拒否し、--mode service がレディネスと未認証リクエストの拒否チェックに合格した後にのみ公開します。

⚠️ 注：SSE トランスポートは 2025 年 8 月以降非推奨です。streamable-http を使用してください。

---

📖 詳細なドキュメント：

• アーキテクチャ → ARCHITECTURE.md
• パイプラインのチュートリアル（英語）→ docs/guides/PIPELINE_MODE_TUTORIAL.en.md
• パイプラインのチュートリアル（zh-TW）→ docs/guides/PIPELINE_MODE_TUTORIAL.md
• デプロイガイド → DEPLOYMENT.md
• Copilot Studio → copilot-studio/README.md

---

🔐 セキュリティ

セキュリティ機能

レイヤー	機能	説明
HTTPS	TLS 終端	リモート認証情報には必須です。付属の自己署名プロファイルはローカル専用です
Bearer 認証	安定したプリンシパル	サービスモードでは必須であり、テナント認可に使用されます
テナントストレージ	ファイルシステムの分離	セッション、成果物、エクスポート、履歴、パイプラインは、認証済みプリンシパルの配下に保存されます
公平性とレートポリシー	テナント単位の同時実行数＋共有の上流予算	1 人の呼び出し元が上流 API の利用枠を使い切ることを防ぎます
セキュリティヘッダー	クリックジャッキング／MIME 対策の強化	リバースプロキシのヘッダーは認証を補完しますが、CSRF の認可を行うものではありません
シークレットの取り扱い	実行時のシークレット注入	API キーと Bearer トークンは、デプロイ用シークレットまたは環境変数から取得する必要があります。コミットしたり、ログに記録したりしないでください

詳しいデプロイ手順については、DEPLOYMENT.md を参照してください。

---

📤 エクスポート形式

主要な文献管理ツールと互換性のある形式で、検索結果をエクスポートできます。

形式	ソース	互換性のあるツール	用途
RIS	公式またはローカル	EndNote、Zotero、Mendeley	汎用インポート
MEDLINE	公式またはローカル	PubMed ツール	PubMed 形式でのネイティブなアーカイブ
CSL JSON	公式	引用処理ツール	プログラムによる引用スタイルの設定
BibTeX	ローカル	LaTeX、Overleaf、JabRef	学術論文の執筆
CSV	ローカル	Excel、Google Sheets	データ分析
JSON	ローカル	プログラムからのアクセス	カスタム処理

エクスポートされるフィールド

• 基本情報：PMID、タイトル、著者、ジャーナル、出版年、巻、号、ページ
• 識別子：DOI、PMC ID、ISSN
• コンテンツ：抄録（HTML タグを除去）
• メタデータ：言語、出版タイプ、キーワード
• アクセス情報：DOI URL、PMC URL、全文の利用可否

特殊文字の処理

• BibTeX のエクスポートでは、適切な LaTeX エンコードに pylatexenc を使用します
• 北欧文字（ø、æ、å）、ウムラウト（ü、ö、ä）、アクセント付き文字は正しく変換されます
• 例：Søren Hansen → S{\o}ren Hansen

---

📚 引用

出版ワークスペースには、改稿した原稿、確認済みの参考文献、エビデンスマップ、ローカルでの PDF／arXiv ソースのビルドが含まれています。これは arXiv 識別子のない作業用ドラフトです。以下の公開済みソフトウェアを引用してください。著者：Tz-Ping Gau、Kaohsiung Medical University Hospital。

GitHub では、CITATION.cff に基づいて このリポジトリを引用 が表示されます。研究、方法のセクション、または社内技術レポートで PubMed Search MCP を使用する場合は、GitHub が生成する引用を使用するか、リポジトリのメタデータをそのまま再利用してください。

@software{pubmed_search_mcp,
  title = {PubMed Search MCP},
  author = {Gau, Tz-Ping},
  version = {0.8.0},
  year = {2026},
  url = {https://github.com/u9401066/pubmed-search-mcp}
}

---

📄 ライセンス

Apache License 2.0 — LICENSE を参照してください。

---

🔗 リンク

• GitHub リポジトリ
• PyPI パッケージ
• NCBI Entrez Programming Utilities