Paper Chaser MCP

Paper Chaser MCP

リリース状況： リポジトリ、CLI、Docker イメージのメタデータ、および公開 MCP ID は、現在 paper-chaser-mcp に統一されています。GHCR イメージと GitHub リリースアセットが、公開向けの主要な配布チャネルです。PyPI は、アカウントの復旧と信頼できるパブリッシャーの設定が完了するまで、意図的に公開を保留しています。

学術研究向けの MCP サーバーです。論文の検索、引用の追跡、著者の検索、壊れた参考文献の修復、種の詳細情報の調査、規制文書の取得を、AI アシスタントが直接呼び出せる 1 つの FastMCP サーバーから実行できます。

プロバイダー： Semantic Scholar · arXiv · OpenAlex · CORE · SerpApi Google Scholar（オプトイン、有料） · Crossref · Unpaywall · ECOS · FederalRegister.gov · GovInfo

---

目次

• 何ができますか？
• ガイド付きプロファイルとエキスパートプロファイル
• クイックスタート
• ツール選択のクイックガイド
• 主要なワークフロー
• エージェントの応答仕様
• エクスポートの延期に関する設計
• 移行に関する注意
• インストール
• 設定
• ツール
• リソースとプロンプト
• Microsoft パッケージングアセット
• MCP Inspector を使用したテスト
• 開発
• ガイド
• ライセンス
• リンク

---

できること

Paper Chaser MCP は現在、ガイド付き優先の設計です。デフォルトで公開される機能は、誤用しにくく、信頼性について明確になるよう設計されています。

• デフォルトの調査エントリーポイント：research は、発見、既知項目の再取得、引用の修正、規制関連の振り分けを、信頼度を示す単一の経路で処理します。ガイド付き利用向けに、サーバーが管理する品質優先ポリシーを適用します。
• 根拠に基づくフォローアップ：follow_up_research は、保存済みの単一の searchSessionId に基づいて回答します。省略された場合、サーバーは該当するセッションが一意の場合にのみ推定します。保存済みセッションのフォローアップでは、保存されたメタデータだけで十分な場合、混在するソース群を、トピックに沿った根拠、弱いコンテキスト、対象外の手がかりに分類できます。
• 判断メタデータ：ガイド付きの応答には executionProvenance が表示されます。また、曖昧なフォローアップやソースの検査では、不透明なエラーの代わりに、構造化された sessionResolution ／ sourceResolution ペイロードが返されます。
• 参照情報を優先した解決：resolve_reference は、DOI／arXiv／URL、引用の一部、規制関連の形式の参照を処理します。また、DOI／arXiv／論文 URL の完全一致入力は、あいまいな修正に回るのではなく、正確なアンカーとして解決されます。タイトルのみの一致が曖昧な場合や、メタデータが矛盾する場合は、multiple_candidates または needs_disambiguation が返されることがあります。これらは引用にそのまま使える解決結果ではなく、候補アンカーとして扱ってください。
• 簡潔なトップレベルの回答：ガイド付きの research は、推奨事項を先に示す短い summary から始まり、その下に構造化された根拠、手がかり、出所情報を引き続き提供します。
• ソースの監査可能性：inspect_source は、出所情報、信頼状態、一致が弱い理由、品質を考慮した直接読み込みの次の手順とともに、単一の sourceId を提示します。searchSessionId を省略できるのは、互換性のある保存済みセッションが1つだけ存在する場合に限られます。
• 実行時の正確な状態：get_runtime_status は、低レベルの診断を必要とせず、アクティブなプロファイル／トランスポートとプロバイダー状態の警告を表示します。configuredSmartProvider は設定済みのスマートバンドルを示し、activeSmartProvider は直近の有効な実行経路を示します。コールドスタート時のスナップショットは、最初のスマート呼び出しが完了する前に決定的なフォールバックを主張するのではなく、暫定状態であることを明示的に警告します。また、トップレベルのプロバイダーセットは、まとめて扱うのではなく、disabledProviderSet、suppressedProviderSet、degradedProviderSet、quotaLimitedProviderSet に分けて表示されます。
• エキスパート向けの詳細も引き続き利用可能：オペレーター向けのワークフローでは、エキスパートプロファイルのもとで、生データ／スマート／プロバイダー固有のツールも引き続き利用できます。

ガイド付きプロファイルとエキスパートプロファイル

公開する機能を選択するには PAPER_CHASER_TOOL_PROFILE を使用します。

プロファイル	デフォルト	公開される機能	想定ユーザー
guided	はい	research、follow_up_research、resolve_reference、inspect_source、get_runtime_status	コンテキストが限られているユーザーやエージェント
expert	いいえ	ガイド付きツールに加え、生データ／プロバイダー固有の各種機能（search_papers*、スマートグラフツール、規制関連の直接ツール、全診断機能）。有効な機能と無効化されたツールの表示設定に従います。	パワーユーザーやオペレーター向けのワークフロー

実用上のデフォルト設定は、PAPER_CHASER_TOOL_PROFILE=guided と PAPER_CHASER_HIDE_DISABLED_TOOLS=true です。

クイックスタート

ローカルで最も手早く利用するには、ソースからインストールし、stdio モードで MCP クライアントにサーバーを追加します。

pip install -e .

{
  "mcpServers": {
    "paper-chaser": {
      "command": "python",
      "args": ["-m", "paper_chaser_mcp"],
      "env": {
        "PAPER_CHASER_TOOL_PROFILE": "guided",
        "PAPER_CHASER_HIDE_DISABLED_TOOLS": "true",
        "PAPER_CHASER_ENABLE_SEMANTIC_SCHOLAR": "true",
        "PAPER_CHASER_ENABLE_ARXIV": "true",
        "PAPER_CHASER_ENABLE_CORE": "false"
      }
    }
  }
}

次に、MCP クライアントで以下のプロンプトのいずれかを実行します。

• コーディングエージェント向けの検索拡張生成を調査し、信頼できる結果だけを返してください。
• 直近のsearchSessionIdを使って、根拠に基づくフォローアップの質問に1つ回答してください。
• この引用の一部を解決してください：Vaswani et al. 2017 Attention Is All You Need.
• 50 CFR 17.95に基づいて、カリフォルニアコンドルに関する規制の変遷を調査してください。

シェル実行または Docker Compose 用のローカル環境テンプレートが必要な場合は、.env.example を .env にコピーし、使用するプロバイダーのみを設定してください。

---

クイックツール選択ガイド

目的	まず使うもの
情報の発見、文献レビュー、規制の経緯の調査	research
保存済みの結果に基づく追加質問	follow_up_research
引用／DOI／arXiv／URL／参考文献の整理	resolve_reference
返された情報源を利用する前に監査する	inspect_source
環境／ランタイムの違いを説明する	get_runtime_status
プロバイダーを直接制御する、または専門的なページネーションが必要な場合	エキスパートプロファイルに切り替え、raw／プロバイダー固有のツールを使用する

コアワークフロー

1. まずガイド付きリサーチを行う

research(query="retrieval-augmented generation for coding agents", limit=5)
→ inspect resultStatus, answerability, summary, evidence, leads, routingSummary
→ if resultStatus=needs_disambiguation with clarification.reason=underspecified_reference_fragment:
  tighten the anchor or pivot to resolve_reference instead of forcing retrieval
→ if resultStatus=abstained and sources are suppressed: inspect suppressedSourceSummaries before rerunning or escalating
→ save searchSessionId for follow-up or source inspection

2. 根拠に基づいて追加質問を1つする

follow_up_research(searchSessionId="...", question="What evaluation tradeoffs show up here?")
→ inspect answerStatus
→ if answered: use answer + evidence (compact default: sources are identified by selectedEvidenceIds)
→ if abstained/insufficient_evidence: use nextActions, suppressedSourceSummaries, and inspect_source
→ mixed saved sessions can still answer relevance-triage questions such as which items are on-topic vs off-target
→ uniquely anchored recommendation asks can also return a safe start-here answer plus topRecommendation
→ if you omit searchSessionId and multiple saved sessions exist: provide it explicitly
→ for full source records pass responseMode="standard"; for diagnostics responseMode="debug"
→ for selection asks ("where should I start?", "most recent?"), read topRecommendation

3. 可能であれば、広範な検索の前に参考文献を解決する

resolve_reference(reference="10.1038/nrn3241")
→ exact DOI/arXiv/paper URL should resolve directly when supported
resolve_reference(reference="Rockstrom et al planetary boundaries 2009 Nature 461 472")
→ inspect status and bestMatch/alternatives
→ only treat bestMatch as citation-ready when status=resolved
→ if status=multiple_candidates or needs_disambiguation: pick a candidate or add a stronger author/year/venue clue before citing it
→ if resolved: run research with the resolved anchor

4. 引用する前に、情報源を1つ確認する

inspect_source(searchSessionId="...", evidenceId="...")
→ inspect verificationStatus, topicalRelevance, whyClassifiedAsWeakMatch, confidenceSignals, canonicalUrl, directReadRecommendations
→ if searchSessionId is omitted and inference is ambiguous, rerun with an explicit saved session id

5. 回答の保留と確認を明示的に扱う

• research.resultStatus が abstained または needs_disambiguation の場合、統合した内容を捏造しないでください。具体的な手掛かりを加えて絞り込みます。たとえば、DOI、正確なタイトル、種名、機関、年、掲載誌などです。
• research が clarification.reason=underspecified_reference_fragment を伴う needs_disambiguation を返した場合、サーバーは曖昧な引用／参考文献の断片に対する推測的な検索を意図的に停止しています。手掛かりを絞り込むか、resolve_reference に切り替えてください。
• follow_up_research.answerStatus が abstained または insufficient_evidence の場合、安全上のシグナルとして扱ってください。inspect_source を使用し、範囲を絞って research を再実行してください。

6. 細かな制御が必要な場合のエキスパート向けフォールバック

PAPER_CHASER_TOOL_PROFILE=expert
→ search_papers_smart / ask_result_set / map_research_landscape / expand_research_graph
→ search_papers / search_papers_bulk and provider-specific families
→ search_federal_register / get_federal_register_document / get_cfr_text for direct regulatory primary-source control

エキスパート向けスマートツールでは、品質を優先するデフォルトモードは deep です。レイテンシの低下に見合う範囲の絞り込みが必要な場合に限り balanced を使用し、fast はスモークテストまたはデバッグ用にしてください。

ガイド付きの research では、公開されている latencyProfile ノブを受け付けなくなりました。このポリシーはサーバーが管理しており、現在は、初回の結果が不十分な場合に1回の限定的なレビュー強化を行う、deep ベースの品質優先パスが適用されます。

エージェントの応答契約

以下を、主なガイド付き契約として扱ってください。

フィールドまたはパターン	表示される場所	対応方法
resultStatus	research	succeeded、partial、needs_disambiguation、abstained、failed
answerability	research、follow_up_research	grounded、limited、insufficient
evidence	research、follow_up_research	確認や引用に使用する、正規の根拠付きソースレコードです
leads	research、follow_up_research、エキスパート向けスマートツール	根拠付きの証拠として扱わず、信頼性が低い、フィルタリングされた、または話題から外れた候補を確認します
evidenceGaps	research、follow_up_research	隠れた但し書きではなく、現在の回答に対する明示的な制限として扱います
routingSummary	research、follow_up_research	意図、アンカー、プロバイダー計画、存在する場合は規制サブタイプまたはエンティティカード、および結果が部分的である理由を確認します
coverageSummary	research、follow_up_research	統合結果を信頼する前に、プロバイダーの網羅性と完全性を確認します
executionProvenance	ガイド付きツール	結果の生成に使用されたサーバーポリシー、デフォルトのレイテンシ設定、フォールバック経路を確認します
confidenceSignals	research、follow_up_research、inspect_source	answerabilityに取って代わることなく、証拠の質、統合モード、ソース範囲ラベルなどの補足的な信頼性の手がかりを確認します
evidenceUsePlan	follow_up_research	統合形式の追加調査では、回答サブタイプ、直接回答に対応する証拠ID、裏付けのない部分、取得の十分性を確認してから回答を信頼します
sessionResolution	follow_up_research、inspect_source	セッションが推定、修復、欠落、または曖昧な場合に使用します
sourceResolution	inspect_source	要求されたソースIDが一致したか、解決できなかったか、または利用可能なIDを使った再試行が必要かを確認します
abstentionDetails	根拠が弱い場合のガイド付きツール	回答の差し控えや証拠不足に対する、実行可能な理由と復旧のヒントとして扱います
nextActions	ガイド付きツール	根拠が弱い場合にサーバーが推奨する復旧経路として扱います
clarification	research	範囲が明確な確認依頼が提示されている場合に限り、ユーザーに質問します
answerStatus	follow_up_research	answered、abstained、insufficient_evidence。根拠のあるansweredには、話題に沿った検証済みソース、QAで読めるテキスト、非決定論的なプロバイダー、中以上の信頼度が必要です。そうでない場合はinsufficient_evidenceが想定されます。
topRecommendation	follow_up_research（比較・選定の依頼）	sourceId、recommendationReason、comparativeAxis（例：beginner_friendly、recency、authority）を含む構造化された選択結果です。アンカーが一意に定まる「どこから始めればよいですか？」という依頼には、より広範な統合では限定的な回答にとどまる場合でも、この経路で安全に回答できます。
responseMode	follow_up_researchの入力	compact（デフォルト。全ソースとレガシーフィールドを非表示）、standard、debug。
includeLegacyFields	follow_up_researchの入力	コンパクトモードでレガシーのverifiedFindings／unverifiedLeadsを復元するには、trueに設定します。
fullTextUrlFound / bodyTextEmbedded / qaReadableText	inspect_source	URLの検出、本文テキストの埋め込み、QA統合で実際に利用可能なテキストを区別します。互換性のための別名としてfullTextObservedが引き続き表示される場合がありますが、永続的な契約は分割されたフィールドです。
evidenceId	evidence[*]	ソースごとの来歴確認のため、inspect_sourceに渡します
runtimeSummary	get_runtime_statusおよびエキスパート向け診断	有効なプロファイル、スマートプロバイダーの状態、警告を確認します

広範な機関ガイダンスを見つける場合、ガイド付きルーティングは引き続き 規制に関する一次情報ソースの経路を使用します。話題から外れた権威ある文書が leadsとして表示される場合もありますが、最上位の推奨では、クエリに関連する ガイダンスや政策文書より優先してはなりません。 ソースレベルの監査では、権威あるレコードが弱い一致またはトピック外の候補として保持された理由を説明する主な情報として、whyClassifiedAsWeakMatch と confidenceSignals.sourceScopeLabel ／ confidenceSignals.sourceScopeReason を確認してください。

追加の信頼性および根拠付けのシグナルが、llm-guidance フェーズ 4 の展開で導入されました。ガイド付き応答では、confidenceSignals.evidenceQualityProfile、confidenceSignals.synthesisMode、confidenceSignals.evidenceProfileDetail、confidenceSignals.synthesisPath、confidenceSignals.trustRevisionNarrative と、権威はあるもののトピックへの応答性が高くない一次資料のレコードをまとめた trustSummary.authoritativeButWeak バケットを確認できます。searchStrategy には、regulatoryIntent、intentFamily、種および規制に関する根拠付けを示す subjectCard、欠けている主体チェーンの根拠を説明する subjectChainGaps が表示される場合があります。inspect_source では、直接読み込みの各提案に、{trustLevel, whyRecommended, cautions} の形式の directReadRecommendationDetails エントリが対応付けられるため、エージェントは品質に基づいて直接読み込みの優先順位を決められます。これらのシグナルの読み取り方と活用方法については、Paper Chaser Golden Paths と Guided And Smart Robustness Notes を参照してください。

エクスポート設計の延期

この展開では、セッションのエクスポートは意図的に延期されています。将来的には、format に ris、 bibtex、または csv を指定する export_search_session(searchSessionId, format) の形式を予定しています。エクスポートは guided-v2 のソース／引用スキーマを使用し、公開コントラクトを再度書き換えずに導入できます。

移行に関する注意

以前、smart/raw-first のインターフェースを直接使用していた場合は、次の手順に従ってください。

1. search_papers_smart または search_papers の代わりに research から始めてください。
2. デフォルトの根拠に基づく QA には、ask_result_set の代わりに follow_up_research を使用してください。
3. 既知の項目を最初に復元する手順では、resolve_citation ／ search_papers_match の代わりに resolve_reference を使用してください。
4. PAPER_CHASER_TOOL_PROFILE=expert を設定して、明示的なオペレーター向けワークフローではエキスパートツールを引き続き使用してください。
5. ガイド付きの research に latencyProfile を送信しないでください。このポリシーは現在、サーバーが内部で管理しています。
6. エキスパート向けのスマートツールでは、deep がデフォルトになりました。レイテンシーの低いフォールバックを使用する場合は、balanced を明示的に選択してください。
7. ガイド付きラッパーで executionProvenance、sessionResolution、sourceResolution、abstentionDetails が表示されるようになります。

破壊的変更について詳しくは、Guided Reset Migration Note を参照してください。

---

インストール

現在の配布方法：

• ソースチェックアウト：現時点で最も直接的なローカル利用方法です。特に開発や MCP デスクトップクライアントに適しています。
• GHCR イメージ：Docker ベースの MCP クライアント向けの主要なコンテナー配布チャネルです。
• GitHub リリースアセット：v* タグを作成すると、wheel と sdist のアーティファクトがビルドされ、レビュー用のドラフト GitHub リリースに添付されます。
• PyPI：現時点では意図的に利用を制限しています。この方法が再開されるまでは、ソースからのインストールか GitHub リリースのアーティファクトを使用してください。

ソースからローカルにインストールする場合：

pip install -e .

AI レイヤーを追加する場合のオプションの追加機能：

• 決定論的モードを含む、共有スマートレイヤーのランタイムのみ：pip install -e ".[ai]"
• OpenAI または Azure OpenAI のプロバイダーサポート：pip install -e ".[ai,openai]"
• Hugging Face チャットルーターのサポート：pip install -e ".[ai,huggingface]"
• NVIDIA プロバイダーのサポート：pip install -e ".[ai,nvidia]"
• Anthropic プロバイダーのサポート：pip install -e ".[ai,anthropic]"
• Google プロバイダーのサポート：pip install -e ".[ai,google]"
• Mistral プロバイダーのサポート：pip install -e ".[ai,mistral]"
• Azure AI Foundry の評価結果公開ヘルパー：pip install -e ".[eval-foundry]"
• Hugging Face の評価結果公開ヘルパー：pip install -e ".[eval-huggingface]"
• どちらの評価結果公開ヘルパーも使用する場合：pip install -e ".[eval]"
• オプションの FAISS バックエンドを使用する場合は、上記のいずれかのコマンドに ,ai-faiss を追加してください。

Azure OpenAI では、同じ openai 追加機能を使用します。 Hugging Face では専用の huggingface 追加機能を使用します。この機能は、OpenAI 互換の SDK と LangChain OpenAI アダプターをインストールします。このリポジトリでは、埋め込みを無効にしたチャット専用のスマートプロバイダーパスとして説明しています。 評価結果公開ヘルパーには、意図的に別々の追加機能を使用します。eval-foundry は Azure AI Foundry のデータセットアップロードをサポートし、eval-huggingface は Hugging Face のデータセットリポジトリまたはバケットへの公開をサポートします。これらの追加機能は、スマートプロバイダーのチャットランタイムとは独立しています。

設定

ローカル環境変数の仕様全体は .env.example に記載されています。このファイルには、docker-compose.yaml でサポートされている公開ローカル設定項目が反映されています。Azure 固有の識別子、シークレット、Bicep パラメーターについては、docs/azure-deployment.md に分けて記載しています。

デスクトップ MCP クライアント

HTTP が特に必要な場合を除き、デスクトップ MCP クライアントでは stdio トランスポートを使用してください。 サーバー定義については、上記の クイックスタート の JSON 例を参照してください。

• Claude Desktop の設定パス：
  • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows：%APPDATA%\Claude\claude_desktop_config.json
• Cursor：Cursor の設定に同じ MCP サーバー定義を追加します。

検索ブローカーと機能フラグ

ガイド付きモードは research から開始します。以下のブローカー制御およびプロバイダー固有の制御は、エキスパート向けの設定です。

領域	デフォルト	主な変数	備考
ツールプロファイル	guided	PAPER_CHASER_TOOL_PROFILE	guided ではコンテキスト消費の少ない5つのツールが公開されます。expert では、機能の有効化状況と PAPER_CHASER_HIDE_DISABLED_TOOLS の設定に応じて、より広範な生データ／プロバイダー固有の機能が公開されます
ガイド付きポリシー	品質優先	PAPER_CHASER_GUIDED_RESEARCH_LATENCY_PROFILE、PAPER_CHASER_GUIDED_FOLLOW_UP_LATENCY_PROFILE、PAPER_CHASER_GUIDED_ALLOW_PAID_PROVIDERS、PAPER_CHASER_GUIDED_ESCALATION_ENABLED、PAPER_CHASER_GUIDED_ESCALATION_MAX_PASSES、PAPER_CHASER_GUIDED_ESCALATION_ALLOW_PAID_PROVIDERS	ガイド付きの research ／ follow_up_research では、クライアントの latencyProfile の設定は適用されず、サーバー側で管理されるこれらのデフォルトが使用されます
検索ブローカー	semantic_scholar,arxiv,core,serpapi_google_scholar	PAPER_CHASER_ENABLE_SEMANTIC_SCHOLAR、PAPER_CHASER_ENABLE_ARXIV、PAPER_CHASER_ENABLE_CORE、PAPER_CHASER_ENABLE_SERPAPI、PAPER_CHASER_PROVIDER_ORDER	SerpApi はオプトインで有料です。CORE はデフォルトで無効です
OpenAlex ツールファミリー	有効	PAPER_CHASER_ENABLE_OPENALEX、OPENALEX_API_KEY、OPENALEX_MAILTO	明示的なツールファミリーであり、デフォルトのブローカーホップではありません
ScholarAPI ツールファミリー	無効	PAPER_CHASER_ENABLE_SCHOLARAPI、SCHOLARAPI_API_KEY	発見、モニタリング、全文、PDF を扱う明示的なファミリーです。preferredProvider または providerOrder を指定すれば、オプトインのブローカーターゲットとしても利用できます。ScholarAPI をソースとする論文の検索結果には、アクセス／全文メタデータを示す独立した contentAccess ブロックが含まれるようになりました。
エンリッチメント	有効	PAPER_CHASER_ENABLE_CROSSREF、CROSSREF_MAILTO、CROSSREF_TIMEOUT_SECONDS、PAPER_CHASER_ENABLE_UNPAYWALL、UNPAYWALL_EMAIL、UNPAYWALL_TIMEOUT_SECONDS、PAPER_CHASER_ENABLE_OPENALEX	論文または DOI をすでに取得している場合に使用します
ECOS	有効	PAPER_CHASER_ENABLE_ECOS、ECOS_BASE_URL、ECOS_TIMEOUT_SECONDS、ドキュメントのタイムアウトおよびサイズ関連の変数、TLS 関連の変数	種とドキュメントのワークフローに使用します
Federal Register ／ GovInfo	有効	PAPER_CHASER_ENABLE_FEDERAL_REGISTER、PAPER_CHASER_ENABLE_GOVINFO_CFR、GOVINFO_API_KEY、GovInfo のタイムアウトおよびサイズ関連の変数	Federal Register の検索にキーは不要です。権威ある CFR の取得には GovInfo を使用します
スマートレイヤー	無効	OPENAI_API_KEY、OPENROUTER_API_KEY、OPENROUTER_BASE_URL、OPENROUTER_HTTP_REFERER、OPENROUTER_TITLE、HUGGINGFACE_API_KEY、HUGGINGFACE_BASE_URL、NVIDIA_API_KEY、NVIDIA_NIM_BASE_URL、AZURE_OPENAI_API_KEY、AZURE_OPENAI_ENDPOINT、AZURE_OPENAI_API_VERSION、ANTHROPIC_API_KEY、GOOGLE_API_KEY、MISTRAL_API_KEY、PAPER_CHASER_ENABLE_AGENTIC、モデルおよびインデックス関連の変数	追加機能のみを提供します。openai、azure-openai、anthropic、nvidia、google、mistral、huggingface、openrouter、deterministic をサポートします。OpenAI にはリポジトリに登録済みのモデルデフォルトが含まれます。Anthropic、NVIDIA、Google、Mistral では、これらの OpenAI デフォルトが変更されていない場合、プロバイダーのデフォルトに自動で切り替わります。また、Azure OpenAI ではデプロイ名で両方のロールを上書きできます。Hugging Face と OpenRouter は、HUGGINGFACE_BASE_URL と OPENROUTER_BASE_URL で設定する OpenAI 互換のチャットルーターとして説明されています。どちらもこのリポジトリではチャットのみをサポートし、埋め込み機能は有効にしません。OpenRouter は、プロバイダー名のプレフィックスが付いたモデル ID など、明示的に指定されたプランナーモデル名と合成モデル名をそのまま使用します。セルフホストの NIM では NVIDIA_NIM_BASE_URL は任意です。ホスト型の NVIDIA API Catalog にアクセスする場合は空欄にしてください。このコードベースでは埋め込みの信頼性に問題があったため、デフォルトでは無効のままです。埋め込みの改善は今回のリリースの対象外です。ScholarAPI が有効な場合、スマート検索で ScholarAPI にルーティングし、providerBudget.maxScholarApiCalls によって呼び出し回数に上限を設定することもできます。
無効なツールを非表示	guided のデフォルトは true、expert のデフォルトは false	PAPER_CHASER_HIDE_DISABLED_TOOLS	guided モードでは、行き詰まりにつながるツールの選択を減らすため、この設定をオンにします。expert モードでは通常、運用者が状況を確認できるようオフにします

スマートレイヤーのモデルのデフォルト

PAPER_CHASER_ENABLE_AGENTIC=true を有効にし、モデル変数を意図的に上書きしない場合の、プランナー／統合処理の実効デフォルトです。

PAPER_CHASER_AGENTIC_PROVIDER	プランナーのデフォルト	統合処理のデフォルト	解決ルール
openai	gpt-5.4-mini	gpt-5.4	チェックイン済みの PAPER_CHASER_PLANNER_MODEL および PAPER_CHASER_SYNTHESIS_MODEL のデフォルトをそのまま使用します
azure-openai	gpt-5.4-mini	gpt-5.4	AZURE_OPENAI_PLANNER_DEPLOYMENT または AZURE_OPENAI_SYNTHESIS_DEPLOYMENT が設定されていない限り、同じモデル変数を使用します。設定されている場合は、それらのデプロイ名が優先されます
anthropic	claude-haiku-4-5	claude-sonnet-4-6	プランナー／統合処理のモデルがチェックイン済みの OpenAI デフォルトのままの場合に限り、ランタイムがこれらのプロバイダーのデフォルトに切り替えます
nvidia	nvidia/nemotron-3-nano-30b-a3b	nvidia/nemotron-3-super-120b-a12b	プランナー／統合処理のモデルがチェックイン済みの OpenAI デフォルトのままの場合に限り、ランタイムがこれらのプロバイダーのデフォルトに切り替えます
google	gemini-2.5-flash	gemini-2.5-pro	プランナー／統合処理のモデルがチェックイン済みの OpenAI デフォルトのままの場合に限り、ランタイムがこれらのプロバイダーのデフォルトに切り替えます
mistral	mistral-medium-latest	mistral-large-latest	プランナー／統合処理のモデルがチェックイン済みの OpenAI デフォルトのままの場合に限り、ランタイムがこれらのプロバイダーのデフォルトに切り替えます
huggingface	moonshotai/Kimi-K2.5	moonshotai/Kimi-K2.5	プランナー／統合処理のモデルがチェックイン済みの OpenAI デフォルトのままの場合に限り、ランタイムがこれらのプロバイダーのデフォルトに切り替えます。リクエストは HUGGINGFACE_BASE_URL に送信され、パスはチャット専用のままです
openrouter	なし	なし	ランタイムは明示的に指定されたプランナー／統合処理のモデル値を維持し、リクエストを OPENROUTER_BASE_URL に送信します。最初の試行のパスはチャット専用のままです
deterministic	該当なし	該当なし	外部 LLM 呼び出しは行われず、モデル選択のメタデータは deterministic として報告されます

PAPER_CHASER_EMBEDDING_MODEL のデフォルトは text-embedding-3-large ですが、PAPER_CHASER_DISABLE_EMBEDDINGS=false を設定するまでは埋め込みは無効です。このコードベースでは埋め込みの信頼性に問題があり、改善は現在のガイド付きポリシーリリースの対象外であるため、デフォルトでは無効のままです。現在のプロバイダー構成では、埋め込みを使用するのは明示的にサポートしているプロバイダーのみです。そのため、OpenAI 互換ルーターを使用していても、Hugging Face のドキュメントに記載されたパスはチャット専用のままです。

推奨する基本設定：一般的な学術ワークフローでは Semantic Scholar、OpenAlex、Crossref、Unpaywall を有効にします。全文または PDF の取得を明示的に行う場合は ScholarAPI を有効にします。SerpApi は有料の検索漏れ回復手段のため、オプトインのままにします。

特に重要なブローカーのルール：

• デフォルトの検索フォールバック順序は、Semantic Scholar、arXiv、CORE、そして有効な場合は SerpApi です。
• preferredProvider、providerOrder、PAPER_CHASER_PROVIDER_ORDER では、core、semantic_scholar、arxiv、scholarapi、serpapi、または serpapi_google_scholar を指定できます。
• publicationDateOrYear、fieldsOfStudy、publicationTypes、openAccessPdf、minCitationCount など、Semantic Scholar 専用のフィルターを指定すると、互換性のないプロバイダーがブローカーによってスキップされる場合があります。
• ブローカーの応答には brokerMetadata.providerUsed、brokerMetadata.attemptedProviders、brokerMetadata.recommendedPaginationTool が含まれるため、エージェントは適切な次の手順に進めます。

トランスポートとデプロイモード

モード	デフォルト	主な変数	使用する場面
デスクトップの stdio	stdio	必須のものはありません	Claude Desktop、Cursor、ローカルでの MCP サブプロセスの起動
直接 HTTP 実行	オプトイン	PAPER_CHASER_TRANSPORT、PAPER_CHASER_HTTP_HOST、PAPER_CHASER_HTTP_PORT、PAPER_CHASER_HTTP_PATH	デプロイ用ラッパーを使わずにローカル統合テストを行う場合
HTTP ラッパー	オプトイン	PAPER_CHASER_HTTP_AUTH_TOKEN、PAPER_CHASER_HTTP_AUTH_HEADER、PAPER_CHASER_ALLOWED_ORIGINS	ホスト型 HTTP デプロイと同等の環境をローカルで用意する場合
Docker Compose の公開設定	localhost のデフォルト	PAPER_CHASER_PUBLISHED_HOST、PAPER_CHASER_PUBLISHED_PORT	ホスト側の HTTP ポートマッピングのみを制御する場合

主な違い：

• PAPER_CHASER_HTTP_HOST と PAPER_CHASER_HTTP_PORT は、シェルからの直接実行とホスト型デプロイを制御します。Docker Compose では、コンテナーのバインド先は 0.0.0.0:8080 のままで、ホスト側のマッピングには PAPER_CHASER_PUBLISHED_HOST／PAPER_CHASER_PUBLISHED_PORT を使用します。
• paper-chaser-mcp deployment-http は、Compose と Azure で使用されるデプロイ用ラッパーを実行します。MCP エンドポイントの前段に /healthz を追加し、オプションで認証と Origin の適用を行います。

直接ローカルで HTTP を実行する例：

PAPER_CHASER_TRANSPORT=streamable-http \
PAPER_CHASER_HTTP_HOST=127.0.0.1 \
PAPER_CHASER_HTTP_PORT=8000 \
python -m paper_chaser_mcp

bootstrap モードと full ワークフローモードを含む Azure デプロイの全体像については、docs/azure-deployment.md、docs/azure-architecture.md、docs/azure-security-model.md を参照してください。

Docker MCP パッケージ（stdio）

サーバーをサブプロセスとして起動するローカル MCP クライアントでは、イメージを stdio モードで使用してください。公開前のローカルでの反復作業には、paper-chaser-mcp:local をビルドして実行してください。 再利用可能な公開パッケージには、公開済みの GHCR タグを使用してください：

docker run --rm -i ghcr.io/joshuasundance-swca/paper-chaser-mcp:latest

ローカルでビルドしたイメージの場合：

docker run --rm -i paper-chaser-mcp:local

Docker を利用する MCP クライアントのエントリーは、通常次のようになります：

{
  "mcpServers": {
    "paper-chaser": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "ghcr.io/joshuasundance-swca/paper-chaser-mcp:latest"]
    }
  }
}

このモードは、ホストがサーバープロセスのライフサイクルを起動して管理するため、ローカルのデスクトップ MCP での利用に最適です。

リポジトリには server.json も含まれており、公開 OCI イメージと MCP パッケージのメタデータを、レジストリ／検出ツールと同期させています。公開パッケージのワークフローは、GHCR への公開をタグ駆動で行います。v* タグを付けると、再利用可能なコンテナーイメージが ghcr.io/joshuasundance-swca/paper-chaser-mcp に公開されます。MCP Registry への公開は別個の手動ワークフローに意図的に切り離されているため、GHCR への公開がレジストリの可用性に左右されることはありません。

Python パッケージの公開は、別途 .github/workflows/publish-pypi.yml で準備されています。プルリクエストではディストリビューションをビルドし、twine check を実行します。実際の公開ジョブは、リポジトリ変数 ENABLE_PYPI_PUBLISHING が true に設定されるまで実行されません。PyPI／TestPyPI へのアクセスが復旧し、Trusted Publisher が登録された後は、手動ディスパッチで TestPyPI に公開でき、v* タグで PyPI に公開できます。

GitHub Release のアセットは、別途 .github/workflows/publish-github-release.yml で処理されます。v* タグまたは手動ディスパッチにより、wheel と sdist の成果物をビルドし、twine check で検証して、SHA256SUMS を生成します。これらはドラフトの GitHub Release ページにアップロードされるため、Python 成果物を広く公開する前に確認できます。

Docker Compose（HTTP ラッパーモード）

ローカル HTTP テスト、MCP Inspector、またはブリッジ形式の統合向けに、このリポジトリには localhost のみを対象とするデフォルト設定の docker-compose.yaml が含まれています。Compose は deployment-http サブコマンドを明示的に起動するため、HTTP ラッパーの動作はイメージのデフォルトのトランスポートに依存しません。

Compose はコンテナのバインドホストと内部ポートを 0.0.0.0:8080 に固定し、アプリのデフォルトのトランスポートを streamable-http に上書きします。そのため、ブラウザーツールやブリッジ形式のクライアントは、シェルのフラグを追加せずに http://127.0.0.1:8000/mcp 経由で接続できます。Compose ファイルでは、トランスポート、MCP パス、プロバイダーキー、プロバイダーの切り替え、認証、および公開するホストポートのマッピングを設定できます。

1. .env.example を .env にコピーします。
2. 使用する任意のプロバイダーキーを入力します。
3. サービスを起動します。

docker compose -f docker-compose.yaml up --build

サービスはデフォルトで http://127.0.0.1:8000 をリッスンし、プローブ用に /healthz を提供して、http://127.0.0.1:8000/mcp 経由で MCP を公開します。

curl http://127.0.0.1:8000/healthz

PAPER_CHASER_HTTP_AUTH_TOKEN を設定し、PAPER_CHASER_HTTP_AUTH_HEADER=authorization のままにすると、デプロイメントラッパーは /mcp へのアクセスに Authorization: Bearer <token> を要求します。チェックイン済みの Azure 用ひな形ではヘッダー名が x-backend-auth に上書きされ、API Management がバックエンド専用トラフィック用にそのヘッダーを挿入します。公開ホストのデフォルトは 127.0.0.1 です。コンテナをローカルマシンの外部から意図的に利用可能にする場合にのみ、PAPER_CHASER_PUBLISHED_HOST を変更してください。

プロバイダーキーのフィールドを空欄のままにしても、ローカルクライアントは引き続き動作します。サーバーは、対応している場合は無料またはデフォルトのプロバイダーパスにフォールバックし、SerpApi はデフォルトで無効のままです。

Docker Compose Inspector サイドカー

Node をローカルにインストールせずにブラウザーでデバッグするには、専用の Inspector スタックを使用します。

docker compose -f compose.inspector.yaml up --build

このスタックでは Inspector を MCP サーバーのイメージから分離し、UI とプロキシを localhost のみにバインドします。

• Inspector UI：http://127.0.0.1:6274
• Inspector プロキシ：http://127.0.0.1:6277

Inspector のプロキシ認証はデフォルトで有効のままです。docker compose -f compose.inspector.yaml logs mcp-inspector を使用すると、Inspector の起動時に出力されるセッショントークンを確認できます。

Inspector 内で Streamable HTTP を使用して接続し、次のように設定します。

• URL：http://paper-chaser-mcp:8080/mcp
• トランスポート：streamable-http

compose.inspector.yaml では IMAGE の上書きを指定できるため、ファイルを編集せずに特定のタグをテストできます。

IMAGE=ghcr.io/joshuasundance-swca/paper-chaser-mcp:latest docker compose -f compose.inspector.yaml up

ツール

ツールの完全なリファレンスです。どこから始めるかについては、上記のクイックツール選択ガイドを参照してください。

ガイド付きのデフォルトツール

ツール	説明
research	発見、既知アイテムの再取得、引用の修正、規制関連のルーティングに対応する、信頼度評価付きのデフォルトのエントリーポイントです。
follow_up_research	保存済みの searchSessionId に基づいた追加調査を行います。必要に応じて、明示的な回答保留／証拠不十分の状態を返します。
resolve_reference	引用のような入力（引用、DOI、arXiv、URL、タイトルの一部、規制関連の参照）を、安全性の高い次の参照先に解決します。
inspect_source	ガイド付きの結果セットから 1 つの sourceId を調べ、来歴、信頼状態、直接読み取りの後続処理を確認します。
get_runtime_status	アクティブなプロファイル、トランスポート、スマートプロバイダーの状態、警告を含む、ガイド付きのランタイム概要を返します。

エキスパート向けスマートリサーチレイヤー

これらのツールは、より高度なオーケストレーションとプロバイダー制御を行うための、エキスパート向けプロファイルパスです。

ツール	説明
search_papers_smart	クエリ拡張、複数プロバイダーの統合、再ランキング、再利用可能な searchSessionId、およびエビデンス優先のエキスパート向け契約（resultStatus、answerability、routingSummary、evidence、leads、evidenceGaps、structuredSources、coverageSummary、failureSummary）を用いた、概念レベルの探索です。従来の信頼性フィールドも、互換性ビューとして引き続き利用できます。auto モードでは、規制関連の明確な問い合わせを一次資料の時系列へ振り分けることもできます。latencyProfile は最高品質のエキスパート向け処理を行うため、デフォルトで deep です。レイテンシーを下げるには balanced を使用し、fast はスモークテスト用にしてください。上級クライアント向けに、オプションの providerBudget も引き続き利用できます。
ask_result_set	保存済みの searchSessionId を使った、根拠に基づく質疑応答、主張の検証、比較です。
map_research_landscape	保存済みの結果セットを、テーマ、ギャップ、意見の相違、次の検索候補に分類します。
expand_research_graph	論文のアンカーまたは保存済みのセッションを、フロンティアのランキング付きで、引用・参考文献・著者のグラフに展開します。

論文検索

ツール	説明
search_papers	ブローカーを介した単一ページ検索（デフォルト：Semantic Scholar → arXiv → CORE → SerpApi）です。brokerMetadata.nextStepHint を確認してください。ScholarAPI も、明示的なオプトインによるブローカー対象として利用できます。
search_papers_bulk	ブール検索構文に対応した、最大 1,000 件の論文を取得できるページネーション付き一括検索（Semantic Scholar）です。
search_papers_semantic_scholar	フィルターを完全にサポートする、Semantic Scholar のみを対象とした単一ページ検索です。
search_papers_arxiv	arXiv のみを対象とした単一ページ検索です。
search_papers_core	CORE のみを対象とした単一ページ検索です。
search_papers_serpapi	SerpApi の Google Scholar を対象とした単一ページ検索です。SerpApi が必要です。
search_papers_scholarapi	ScholarAPI の関連度順検索を行う単一ページ検索です。ScholarAPI が必要です。
search_papers_openalex	OpenAlex のみを対象とした単一ページ検索です。
search_papers_openalex_bulk	カーソルページネーション付きの OpenAlex 検索です。
list_papers_scholarapi	indexed_at 順に並べ替える、カーソルページネーション付きの ScholarAPI モニタリング／リスト取得フローです。
search_papers_openalex_by_entity	1 つのソース、機関、またはトピックのエンティティ ID に絞り込んだ OpenAlex の論文検索です。

既知の項目の検索と引用の修正

ツール	説明
resolve_citation	不完全または不正な形式の参考文献を修正するワークフローです。規制関連の参考文献には回答を差し控えます。
search_papers_match	複数のプロバイダーで照合する、曖昧または部分的なタイトルを用いた既知の項目の検索です。
get_paper_details	DOI、arXiv ID、Semantic Scholar ID、または URL による検索です。includeEnrichment はオプションです。
get_paper_details_openalex	抄録を再構成する、W-ID、URL、または DOI による OpenAlex の論文検索です。
paper_autocomplete	論文タイトルの入力補完候補です。
paper_autocomplete_openalex	既知の項目の曖昧さを解消する、OpenAlex の論文入力補完機能です。

引用、参考文献、著者

ツール	説明
get_paper_citations	指定した論文を引用している論文（Semantic Scholar）。カーソル方式でページネーションします。
get_paper_citations_openalex	OpenAlex の被引用論文を展開します。カーソル方式でページネーションします。
get_paper_references	指定した論文の参考文献（Semantic Scholar）。カーソル方式でページネーションします。
get_paper_references_openalex	OpenAlex の後方参考文献を展開します。カーソル方式でページネーションします。
get_paper_authors	指定した論文の著者（Semantic Scholar）。
search_authors	著者名で検索します（Semantic Scholar）。
search_authors_openalex	OpenAlex の著者を名前で検索します。
get_author_info	Semantic Scholar の著者 ID で著者プロフィールを取得します。
get_author_info_openalex	A-id または URL で OpenAlex の著者プロフィールを取得します。
get_author_papers	Semantic Scholar の著者による論文。カーソル方式でページネーションします。
get_author_papers_openalex	OpenAlex の著者による論文を、year フィルターとカーソル方式のページネーションで取得します。
batch_get_papers	1 回の呼び出しで最大 500 件の論文 ID の詳細を取得します。
batch_get_authors	1 回の呼び出しで最大 1,000 件の著者 ID の詳細を取得します。
get_paper_recommendations	1 件のシード論文に基づく類似論文（GET）。
get_paper_recommendations_post	正例／負例のシードセットに基づく類似論文（POST）。

論文情報の補完と OA の検索

ツール	説明
enrich_paper	既知の論文または DOI について、Crossref、Unpaywall、OpenAlex の情報を統合して補完します。アンカーを指定せずにクエリのみで呼び出した場合、論文の特定は行わず、処理を見送ります。
get_paper_metadata_crossref	既知の論文または DOI の情報を Crossref から明示的に補完します。
get_paper_open_access_unpaywall	DOI から Unpaywall の OA ステータス、PDF URL、ライセンスを検索します。UNPAYWALL_EMAIL が必要です。

ScholarAPI によるテキストと PDF の取得

ツール	説明
get_paper_text_scholarapi	ScholarAPI の論文 ID を指定して、ScholarAPI のプレーンテキスト全文書を 1 件取得します。
get_paper_texts_scholarapi	ScholarAPI の論文 ID を最大 100 件指定して全文を一括取得します。順序を維持し、null のプレースホルダーも保持します。
get_paper_pdf_scholarapi	ScholarAPI の PDF を 1 件取得し、構造化メタデータと Base64 エンコードされたコンテンツを返します。

OpenAlex エンティティ

ツール	説明
search_entities_openalex	ピボット型ワークフローで使用する OpenAlex の情報源、機関、トピックのエンティティを検索します。

ECOS の種別資料

ツール	説明
search_species_ecos	一般名または学名で ECOS の種を検索します。
get_species_profile_ecos	掲載情報、文書、保全計画を含む ECOS の種別資料一式を取得します。
list_species_documents_ecos	1 件の種別資料一式を、ソート済みの文書一覧に展開します。
get_document_text_ecos	ECOS の文書（PDF／HTML／テキスト）を取得し、Markdown に変換します。

Federal Register と CFR

ツール	説明
search_federal_register	キーなしで、告示、規則、規則案を Federal Register から検索します。
get_federal_register_document	番号、FR 引用、または GovInfo リンクで Federal Register の文書を 1 件取得します。
get_cfr_text	GovInfo から CFR の編または条文のテキストを取得します。GOVINFO_API_KEY が必要です。

SerpApi の追加機能 (オプトイン、有料)

ツール	説明
search_papers_serpapi_cited_by	SerpApi 経由で Google Scholar の被引用論文を展開します。
search_papers_serpapi_versions	SerpApi のクラスタ ID を使って Google Scholar の全バージョンを展開します。
get_author_profile_serpapi	SerpApi 経由で Google Scholar の著者プロフィールを取得します。
get_author_articles_serpapi	SerpApi 経由で Google Scholar の著者論文をページネーションして取得します。
get_paper_citation_formats	Google Scholar から引用情報をエクスポートします（MLA、APA、BibTeX など）。SerpApi が必要です。
get_serpapi_account_status	SerpApi のクォータとスループットのスナップショットを取得します。

復旧と診断

ツール	説明
search_snippets	タイトルやキーワードでの検索がうまくいかない場合に、引用やフレーズを手がかりに復旧します。最後の手段として使用するツールです。
get_provider_diagnostics	プロバイダーの稼働状況、スロットリングの状態、再試行、フォールバックの理由をリアルタイムで確認します。

ECOS の使用例

カリフォルニアコアジサシは、ECOS の代表的なエンドツーエンドのワークフローです。

1. query="California least tern" を指定して search_species_ecos を呼び出し、ECOS の種 ID 8104 を取得します。
2. species_id="8104" を指定して get_species_profile_ecos を呼び出し、種の概要資料、分類された復旧関連文書、生物学的意見書、保全計画へのリンクを確認します。
3. species_id="8104" と、たとえば documentKinds=["recovery_plan","five_year_review","biological_opinion"] を指定して list_species_documents_ecos を呼び出し、文書一覧をまとめて取得します。
4. 2025 年の 5 年レビュー PDF または改訂版の復旧計画 PDF に対して get_document_text_ecos を呼び出し、ソース文書を後続の分析に使える Markdown に変換します。

リソースとプロンプト

• リソース：guide://paper-chaser/agent-workflows - ツールの選択とページネーションを安全に進めるための簡潔な導入ガイド
• リソース：paper://{paper_id} - 解決済み論文の簡潔な Markdown と構造化ペイロード
• リソース：author://{author_id} - 解決済み著者の簡潔な Markdown と構造化ペイロード
• リソース：search://{searchSessionId} - ツールの出力から提示される保存済み検索結果
• リソース：trail://paper/{paper_id}?direction=citations|references - 簡潔な引用／参考文献の関連リソース
• プロンプト：plan_paper_chaser_search - ガイド付き検索をデフォルトとし、専門家向けの明示的なフォールバックを備えた再利用可能な計画用プロンプト
• プロンプト：plan_smart_paper_chaser_search - 専門家向けスマートモードを意図的に使うワークフローの計画用プロンプト
• プロンプト：triage_literature - 信頼性を考慮したテーマのマッピングと次のステップの選択を行うガイド付きトリアージワークフロー
• プロンプト：plan_citation_chase - 引用をたどって拡張するための計画用プロンプト
• プロンプト：refine_query - 範囲が広すぎる検索やノイズの多い検索に向けた、制約付きのクエリ改善プロンプト

主要な読み取りツールの応答には、次の情報も含まれます。

• agentHints - 推奨される次のツール、再試行のガイダンス、警告
• clarification - サーバーが単独で安全に曖昧さを解消できない場合の、範囲を限定した確認事項
• resourceUris - 互換性のあるクライアントが直接開ける、次の処理に使うリソース
• searchSessionId - スマートなフォローアップワークフローや、キャッシュされた検索の展開／検索履歴に再利用できる結果セットの識別子

Microsoft 向けパッケージング資産

このリポジトリでは、統一された MCP サーバーインターフェースを維持しながら、Microsoft 向けクライアント用に追加のパッケージング資産を提供しています。

• mcp-tools.core.json - 低コンテキスト向けのガイド付きデフォルトインターフェース（research、follow_up_research、resolve_reference、inspect_source、get_runtime_status）
• mcp-tools.full.json - PAPER_CHASER_TOOL_PROFILE=expert を明示的に設定して実行する環境向けの、ガイド付き＋専門家向けパッケージ
• microsoft-plugin.sample.json - 宣言型エージェント／プラグイン向けメタデータのサンプル

これらの資産は Streamable HTTP と簡潔なツール出力を対象としています。独立したランタイムビルドではなく、パッケージングに関するガイダンスです。

MCP Inspector でのテスト

ローカルでの推奨手順は、Docker サイドカーのワークフローです。

docker compose -f compose.inspector.yaml up --build

これにより、Inspector を本番環境の MCP イメージから分離し、Inspector のポートを localhost のみにバインドできます。

ホストにインストールした Inspector を使う場合は、次のコマンドも実行できます。

npm install -g @modelcontextprotocol/inspector
mcp-inspector python -m paper_chaser_mcp

開発

開発用の追加パッケージとともにパッケージをインストールします：

pip install -e ".[dev]"

追加の AI レイヤーと、ホスト型プロバイダーとのすべての統合も同じ環境で使用する場合：

pip install -e ".[all]"

all は ai,openai,huggingface,nvidia,anthropic,google,mistral,dev に展開されます。そのため、Azure OpenAI でも同じ openai エクストラを使用します。一方、Hugging Face はチャット専用の OpenAI 互換インストール対象として分かれています。

FAISS のオプションのバックエンドもローカルで使用する場合：

pip install -e ".[all,ai-faiss]"

プロジェクトの依存関係は pyproject.toml で宣言されています。同期を保つための別個のランタイム用 requirements.txt はありません。

ローカルのテストスイートを実行します：

pytest

設定済みの pre-commit フックをインストールして実行します：

pre-commit install
pre-commit run --all-files

pre-commit install は、.pre-commit-config.yaml で設定された高速な pre-commit フックと、より時間のかかる pre-push ゲートの両方をインストールします。手動ステージのフックは自動では実行されません。ローカルのゲートをすべて実行する場合は、pre-commit run --hook-stage manual --all-files（または上記の直接コマンド）を実行してください。

開発用の追加パッケージには、pytest、pytest-asyncio、pytest-cov、 ruff、mypy、bandit、build、bumpver、pip-audit、 shellcheck-py、types-defusedxml、pre-commit が含まれています。Dependabot により、Python パッケージと GitHub Actions の両方で GitHub の依存関係自動更新が設定されており、プルリクエストは依存関係レビューのワークフローでチェックされます。

GitHub ワークフローファイルで CI と同等の結果をローカルで得るには、pre-commit の実行前に PATH で shellcheck を使用できるようにしてください。アクティブなリポジトリの仮想環境に shellcheck-py をインストールすれば、多くの環境でこの条件を満たせます。ワークフロー内の bash がローカルで lint されていると思い込まず、shellcheck --version で確認してください。

バージョンの更新

バージョンメタデータは pyproject.toml の bumpver で管理されています。チェックイン済みのパッケージバージョンは 0.2.0 のような通常の PEP 440 形式で維持されます。一方、既存の公開ワークフローのトリガーに合わせ、リリースタグは引き続き v0.2.0 形式です。

PR ブランチで安全にレビューするため、git の状態に変更を加えずにパッチバージョンの更新をドライランします：

bumpver update --patch --dry --no-fetch --no-commit --no-tag-commit --no-push

実際のリリース準備ブランチでは、チェックイン済みのバージョン要件を更新しつつ、コミット、タグ付け、プッシュは明示的にメンテナーが管理する状態にしておきます：

bumpver update --patch --no-commit --no-tag-commit --no-push

ローカルでの完全な検証

このリポジトリの CI 相当のローカルゲートは、pytest だけよりも広範囲です。ローカルで入念に検証するには、次を実行します：

python -m pip check
pre-commit run --all-files
python -m pytest --cov=paper_chaser_mcp --cov-report=term-missing --cov-fail-under=87
python -m mypy --config-file pyproject.toml
python -m ruff check .
python -m bandit -c pyproject.toml -r paper_chaser_mcp
python -m build
python -m pip_audit . --progress-spinner off

時間のかかるチェックを pre-commit 経由で実行する場合は、pre-commit run --hook-stage manual --all-files により、.pre-commit-config.yaml で定義された手動ステージの pip check、カバレッジ、ビルド、pip-audit フックが実行されます。

Azure IaC、デプロイのドキュメント、Dockerfile、APIM ポリシー、または Azure デプロイのワークフローを変更した場合は、次も実行します：

python scripts/validate_psrule_azure.py
python scripts/validate_deployment.py --skip-docker

Deploy Azure ワークフローの完全なデプロイ検証手順と同等にするには、次を実行します：

python scripts/validate_deployment.py --require-az --require-docker --image-tag paper-chaser-mcp:ci-validate

GitHub エージェント型ワークフローのスモークテスト

このリポジトリには、エージェント型の回帰ワークフローが含まれています。 .github/workflows/test-paper-chaser.md（ソース）と .github/workflows/test-paper-chaser.lock.yml（コンパイル済みロックファイル）です。このワークフローは GitHub Actions 内でローカル MCP サーバーに対してエージェントを実行し、 主なゴールデンパスをテストし、エージェントの UX 品質を評価し、後続作業のための 具体的な課題を作成できます。

Markdown ワークフローを編集した後、再コンパイルして検証します。

gh aw compile test-paper-chaser --dir .github/workflows
pre-commit run --all-files

.md ソースと .lock.yml 出力の両方をまとめてコミットし、GitHub Actions の UI から Test Paper Chaser MCP を実行します。

ワークフロー入力： mode（smoke、comprehensive、または feature_probe）、 tool_profile（デフォルトは guided、raw/provider 固有のカバレッジが必要な場合は expert）、および任意の focus_prompt です。workflow_dispatch 入力から選択します。

必須シークレット： COPILOT_GITHUB_TOKEN が必須です。 GH_AW_MODEL_AGENT_COPILOT（Actions 変数、任意）でエージェントのモデルを指定します。 CORE_API_KEY と SEMANTIC_SCHOLAR_API_KEY は任意です。

このリポジトリには .github/workflows/agentic-assign.yml も含まれており、 agentic と needs-copilot のラベルが付いた課題に GitHub Copilot を自動で割り当てます （needs-human、blocked、no-agent のいずれかのラベルも付いている場合を除きます）。 Validate ワークフローは CI で test-paper-chaser.md を再コンパイルし、 ロックファイルが古くなっている場合は失敗するため、プルリクエストで同期が 気付かないうちにずれることはありません。GitHub Actions が、実行対象のブランチに コミット済みの .lock.yml を認識すると、ワークフローは「デプロイ」された状態になります。

公開リポジトリのセキュリティ方針と、脆弱性を非公開で報告するための推奨方法については SECURITY.md を参照してください。

モジュール分割後にメンテナーとして把握しておくべき情報は、まず docs/agent-handoff.md を 確認してください。公開 MCP インターフェースは paper_chaser_mcp/server.py にあります。 実装は paper_chaser_mcp/dispatch.py、paper_chaser_mcp/search.py、paper_chaser_mcp/tools.py、 paper_chaser_mcp/runtime.py、paper_chaser_mcp/models/、および paper_chaser_mcp/clients/ 以下のプロバイダーサブパッケージにあります。

ガイド

• GitHub Copilot の指示 - ワークフローのデフォルト設定や継続的な計画立案の要件など、GitHub Copilot と GitHub クラウドコーディングエージェント向けのリポジトリ固有のガイダンスです。
• エージェント引き継ぎ - 現在のリポジトリの状態、検証コマンド、後続のエージェントに推奨する次の作業です。
• LLM 選定ガイド - プランナーと合成処理の役割、現在のスマートレイヤーのモデルデフォルト、generate_eval_topics.py と run_eval_autopilot.py を中心とした eval-bootstrap のファネル、およびこのリポジトリで LLM を選定する基準です。
• LLM 評価プログラム計画 - このリポジトリで LLM の性能を厳密に測定するための、役割ベースの評価戦略、データセット生成計画、評価スタック、段階的な展開計画です。
• LLM 評価データセットスキーマ - 役割ベースの評価シードセットと今後のベンチマーク拡張に向けた JSONL スキーマ、フィールドの規則、ガバナンスの慣例、保存レイアウトです。
• LLM 評価プラットフォーム戦略 - 移植性を損なわずに、リポジトリ内の評価を Azure AI Foundry、Hugging Face、ライブトレースのアクティブラーニングループと組み合わせる方法です。
• LLM 評価トレースの昇格 - レビュー済みのライブトレースを永続的な評価行に昇格するワークフローとヘルパー形式です。

任意のライブ評価候補の取得は、PAPER_CHASER_ENABLE_EVAL_TRACE_CAPTURE=true と PAPER_CHASER_EVAL_TRACE_PATH=... で有効にできます。その後、 昇格前に scripts/build_eval_review_queue.py でレビューキューに変換します。

下流の評価システムやトレーニングシステム向けの移植可能なエクスポートは、 scripts/export_eval_assets.py で利用できます。Foundry 対応の評価用 JSONL、 Hugging Face データセット用 JSONL、レビュー承認済みトレースから作成する チャット形式のトレーニング用 JSONL が含まれます。 レビュー済みのエクスポートを Foundry プロジェクトのデータセット、Hugging Face のデータセットリポジトリ、または Hugging Face のバケットに公開するためのサービス固有のヘルパーを、scripts/upload_foundry_eval_dataset.py と scripts/upload_hf_eval_assets.py から利用できます。

エキスパートによるバッチキュレーションの実行では、生レポート、収集したイベント、レビューキューに加えて、batch-summary.json と batch-ledger.csv も出力できるようになりました。これにより、オフラインでのドリフトやスループットの確認に、JSONL アーティファクト全体を再生する必要がなくなります。

リポジトリ内で評価をブートストラップする際の、現在のトップレベルワークフローは次のとおりです。

• scripts/generate_eval_topics.py は、プランナー主導のトピック生成、分類体系への割り当て、ランキング、絞り込み、バランス調整、シナリオの出力を行います
• scripts/run_eval_autopilot.py は、プロファイル主導の生成、不変の実行バンドル、ホールドアウトチェック、ガード付きのワークフロー引き継ぎを行います
• scripts/run_eval_workflow.py は、エキスパートによるバッチの取得、レビューまたは昇格、データセットの分割、プロバイダーのライブマトリックス評価を行います

リポジトリに含まれるオートパイロットのサンプルプロファイルには、バランスの取れた科学向けのデフォルトに加え、single-seed-exploratory-review、single-seed-exploratory-safe、single-seed-diagnostic-force などの小規模実行向けプロファイルも含まれています。これらの小規模実行向けプロファイルでは、単一シードの多様化を有効にできます。これにより、1 シードの実行でも、緩やかなワークフローしきい値だけに頼らず、プランナーに追加のレビュー、規制、手法に関するバリエーションを求められます。 現在の Foundry および Hugging Face との連携方針と、共有キャプチャシンクに hf-mount が適しているケースについては、docs/llm-evaluation-integrations.md を参照してください。

• リリースと公開の計画 - GHCR、GitHub Release アセット、手動での MCP Registry 公開、および休止中の PyPI に関する現在のリリース手順です。
• ガイド付きリセットへの移行に関する注記 - デフォルトのサーフェスに対する互換性を破る変更、ガイド付きとエキスパート向けの分割、およびクライアントの移行チェックリストです。
• Paper Chaser のゴールデンパス - 主なペルソナ、ワークフローのデフォルト、成功の指標、および今後のワークフロー指向のフォローアップ作業です。
• Azure のデプロイ - 非公開の Azure ロールアウトにおけるデプロイモード、必要なシークレットと変数、検証手順です。
• Azure アーキテクチャ - Azure の足場における信頼境界、ランタイムトポロジー、認証情報の分離です。
• Azure セキュリティモデル - Azure ロールアウトにおける認証情報の分類、Key Vault の使用、バックエンド認証の分離です。
• プロバイダーのアップグレードプログラム - 信頼性を優先するプロバイダーのアップグレードにおけるプロバイダーの役割、レイテンシプロファイル、診断、ベンチマークコーパス、受け入れ基準です。
• OpenRouter プロバイダーガイド - チャット専用のスマートレイヤープロバイダーとして OpenRouter を追加・運用するための実装重視のガイダンスです。現在の Trinity の立ち上げ計画も含まれます。
• ScholarAPI 連携ガイド - 現在のグラフ指向のプロバイダー契約を弱めることなく、明示的な検索、モニタリング、全文、PDF プロバイダーとして ScholarAPI を追加するための計画ガイドです。
• OpenAlex API ガイド - 認証、クレジットベースの制限、ページネーション、/works のセマンティクス、正規化に関する注意点など、リポジトリの明示的な OpenAlex MCP サーフェスに関する実装重視のガイダンスです。
• Semantic Scholar API ガイド - 非同期レート制限、再試行、.env を使ったローカル開発により、Semantic Scholar API を適切かつ効果的に利用するための実践的なガイダンスです。
• SerpApi Google Scholar ガイド - SerpApi の機能、トレードオフ、コストおよびコンプライアンスに関する詳細な調査メモです。リポジトリには、ここで説明されている被引用、バージョン、著者、アカウント、引用形式の各フローが明示的に実装されています。
• FastMCP 移行計画 - FastMCP への移行と互換性サーフェスに関する、過去のアーキテクチャ上の根拠です。

ライセンス

MIT

リンク

プロトコルとランタイム

• Model Context Protocol
• FastMCP
• SerpApi の料金

学術情報プロバイダー

• Semantic Scholar API
• arXiv API ユーザーマニュアル
• CORE API v3 ドキュメント
• OpenAlex API ドキュメント
• ScholarAPI ドキュメント
• SerpApi Google Scholar API
• Crossref REST API
• Unpaywall API

規制および種に関する情報源

• ECOS
• FederalRegister.gov API
• GovInfo API