Academic Research Plugin

このリポジトリは、プライベート/開発者モードのAcademic Research Plugin向けの、再利用可能なオープンソースのリファレンス実装です。stdio MCPサーバーとCodexスキルを通じて、トレーサブルな学術検索とエビデンスのワークフローを提供します。

これは公開のOpenAI Plugin Directoryへのデプロイではありません。開発者は自身でOpenAI Platformトンネル、ランタイム認証情報、ChatGPT開発者モードのMCP接続、ローカルの.app.json配線を作成する必要があります。これらの値はこのリポジトリには意図的に含まれていません。

V0.1.0ステータス

リリースされたV0.1.0プラグイン機能は凍結されています。この実装は、設計ドキュメントのプロバイダー契約、スキーマ、検索とランキングのルール、エビデンスレベル、来歴要件、セキュリティ境界、MCPプロトコル動作、スキルのワークフローを保持しています。

運用者承認済みのV0.1.0修正により、ScholarReadの直接比較は任意かつ延期となりました。リリース検証は非比較のままで、ユニット、プロバイダー契約、統合、セキュリティ、決定論的リプレイ、MCPプロトコル、スキル起動/出力のカバレッジに加えて、スタンドアロンの正確性、識別子、エビデンス、来歴、劣化、セキュリティの各保護を含みます。docs/SPEC_AMENDMENT_V0.1.0.mdを参照してください。

Related MCP server: Academic Paper MCP HTTP/SSE Server

プラグインの機能

• 決定論的なリクエストと融合ルールを使用して、サポートされている学術プロバイダーを検索します。

• 識別子を捏造したり、暗黙に曖昧なマージを行ったりせずに、学術識別子を保守的に正規化および解決します。

• 制限付きでサポートされている全文を取得し、エビデンスレベルと利用不可/非サポートのコンテンツを明示的に報告します。

• 来歴を保持する結果で引用関係をトラバースします。

• ビルトインサーバーdist/src/server.jsを通じて凍結されたMCPツールを公開します。

• 監査可能な研究ワークフローのために、エビデンスに基づく文献レビュースキルを起動します。

リポジトリの内容

• ACADEMIC_RESEARCH_PLUGIN_DESIGN.md — 規範的な実装仕様。

• SOURCE_AUDIT.md — 履歴検証エビデンス。代替の設計権威ではありません。

• src/ — TypeScript MCPサーバー、プロバイダー、検索、全文、来歴、セキュリティコード。

• skills/ — パッケージ化された学術文献レビュースキル。

• .codex-plugin/plugin.json — 凍結されたV0.1.0プラグインマニフェスト。

• .app.json.example — 安全なローカル配線テンプレート。実際の.app.jsonは無視されます。

• docs/PUBLIC_SETUP.md — 独立した複製手順。

• tests/ — ユニット、契約、セキュリティ、統合、ベンチマークのフィクスチャ。

公式のOpenAI tunnel-clientソースとバイナリはベンダリングされていません。プライベートMCP接続が必要な場合は、現在のOpenAI Platformトンネル設定または公式のopenai/tunnel-clientリポジトリから入手してください。

前提条件

• Git。

• 設計で固定されているNode.js 24.19.0とnpm 11.17.0。

• ChatGPT開発者モードとプライベートテスト用の関連Platformトンネル権限にアクセスできるOpenAIアカウント。

• 使用予定のプロバイダーについてのみプロバイダー認証情報。決定論的テストはフィクスチャを使用し、ライブのプロバイダーキーは不要です。

• プライベートなChatGPT/Codex MCP接続のための公式tunnel-clientのみ。ローカルのユニットテストや契約テストには不要です。

OpenAIの現在のドキュメントによると、Secure MCP TunnelはMCPサーバーをプライベートに保ち、アウトバウンド接続を使用し、開発者モードのテストをサポートしますが、公開プラグインの提出はサポートしません。Secure MCP Tunnel

新規クローンからのインストール

クリーンなクローンから:

git clone <your-repository-url>
cd academic-research-plugin
npm ci
cp .env.example .env

Windows PowerShellでは、cpの代わりにCopy-Item .env.example .envを使用してください。.envはローカルに保持してください。Gitによって無視されます。

環境変数

.env.exampleには名前のみが含まれています。有効にするプロバイダーとローカル統合に必要な値のみを設定してください:

アプリケーションは一般的な公開HTTPリスナーを必要としません。MCPサーバーはstdioのみで、トンネルクライアントはリクエストを正確なビルド成果物dist/src/server.jsに転送します。

ビルドとテスト

設計はランタイムと依存関係のバージョンを固定しています。リポジトリルートから該当するチェックを実行してください:

npm run verify:env
npm run verify:contracts
npm run build
npm run test:unit
npm run test:contract
npm run test:security
npm run test:integration
npm run verify:plugin

設計で必要なビルド成果物は:

dist/src/server.js

npm run benchmarkはリリース後の任意評価です。延期されたScholarRead比較が必要な場合、V0.1.0リリースゲートとして扱ってはならず、比較結果を合成してはなりません。

プライベートSecure MCP Tunnelを作成する

1. OpenAI Platformトンネル設定で、トンネルを作成または選択し、自身のtunnel_idをコピーします。

2. tunnel-clientが必要とするランタイムAPIキーを作成または取得します。公式のシークレット/環境メカニズムを通じてCONTROL_PLANE_API_KEYとしてローカルに保存します。issue、チャット、リポジトリファイル、.env.example、.app.json、または履歴に記録されるコマンドに貼り付けないでください。

3. このリポジトリをビルドし、dist/src/server.jsが存在することを確認します。

4. 公式のSecure MCP Tunnelガイドに従って、現在の公式tunnel-clientをダウンロード/ビルドします。公開用にバイナリやソースをこのリポジトリにコピーしないでください。

5. 公式の名前付きstdioプロファイルを設定します。以下のコマンドとターゲットは設計の必須パスに従っています。プレースホルダーのみを自分のマシンで作成した値に置き換えてください:

export CONTROL_PLANE_API_KEY="<set-locally-through-your-secret-mechanism>"

tunnel-client init \
  --sample sample_mcp_stdio_local \
  --profile academic-research-local \
  --tunnel-id "<YOUR_TUNNEL_ID>" \
  --mcp-command "node /ABSOLUTE/PATH/TO/academic-research-plugin/dist/src/server.js"

tunnel-client doctor --profile academic-research-local --explain
tunnel-client run --profile academic-research-local

Windows PowerShellでは、実行可能ファイルのPowerShellコマンドライン構文と同じ引数を使用してください。ChatGPT接続の作成またはテスト中はプロファイルを実行したままにしてください。公式ガイドはローカルのヘルスサーフェス/healthz、/readyz、/metrics、/uiを文書化しています。テスト前にhealthyおよびreadyステータスを確認してください。

長期稼働のデプロイでは、この公式プロファイルをホストに適したサービス/スーパーバイザーメカニズムの下で実行し、同じアウトバウンド専用境界を維持してください。公式トンネルフローをアドホックな公開リスナーに置き換えないでください。

独自のChatGPT開発者モード接続を登録する

OpenAI開発者モードのワークフローはPlatformトンネル権限とは別です。現在の文書化されたフローは次のとおりです:

1. ChatGPTで、設定 → セキュリティとログインを開き、アカウント/ワークスペースポリシーで許可されている場合は開発者モードを有効にします。

2. ChatGPTのPlugins/開発者モード接続画面を開き、**+**ボタンを選択します。

3. 自分自身のユーザー向けの名前と説明を入力します。

4. 接続でトンネルを選択し、自分の利用可能なトンネルを選択するか、自分のtunnel_idを入力します。

5. 接続を作成し、検出されたツールとメタデータを確認します。

これはプライベート/開発者モードの接続であり、公開Plugin Directoryへの提出ではありません。公式の接続ガイドは同じ開発者モードとTunnelの手順を文書化しています: Connect and test your plugin。

設計のパッケージング契約では、接続ワークフローによって返される技術IDがplugin_asdk_appで始まる必要があります。自分の接続/パッケージングワークフローで表示された正確なIDをコピーしてください。決して捏造しないでください。次に、無視されるローカル配線ファイルを作成します:

cp .app.json.example .app.json

plugin_asdk_app_REPLACE_WITH_YOUR_REGISTERED_TECHNICAL_IDのみを自分の登録済み技術IDに置き換えてください。Gitに公開せずにローカルで検証してください:

node scripts/verify-plugin.mjs --expected-app-id "<YOUR_PLUGIN_ASDK_APP_ID>"

公開クローンは、.app.jsonなしのテンプレートモードでnpm run verify:pluginをパスします。--expected-app-idを指定することは、実際のローカル.app.jsonを意図的に必要とします。.app.jsonファイルは無視され、ユーザーローカルのままでなければなりません。

プライベート/開発者モードでの使用

トンネルがhealthy/readyを報告し、ChatGPTがMCPツールを検出した後、新しい会話を開始し、ツールメニューからプライベート接続を追加し、代表的な学術リクエストを実行してください。プロバイダー劣化、エビデンスレベル、来歴、識別子の動作、非サポートコンテンツの報告、ツール結果を設計と照合して確認してください。

ローカルCodexまたは別のstdio MCPクライアントでは、正確なビルドコマンドを使用してください:

node /ABSOLUTE/PATH/TO/academic-research-plugin/dist/src/server.js

統合テストはMCP初期化と凍結されたツールリストを検証します。このstdioサーバーを独立して到達可能な公開HTTPサービスとして公開しないでください。

公開リリースの境界

このリポジトリは、オープンソースのGitHubリファレンス/テンプレートとして公開されることを意図しています。GitHubで公開しても、OpenAIアプリが公開されたり、公開プラグインが登録されたり、トンネルが作成されたり、他の誰かにアクセスが許可されたりすることはありません。各開発者は自身のOpenAIリソースを作成して保護し、プライベート/開発者モードを使用する必要があります。

公開前に、docs/PUBLIC_SETUP.mdに記載されているリポジトリのシークレットと履歴チェックを実行し、完全なdiffを確認し、ローカルの.app.json、.env、トンネル資料、生成されたビルド出力、マシン固有のファイルが追跡されていないことを確認してください。

参照

• 規範的なリポジトリ仕様: ACADEMIC_RESEARCH_PLUGIN_DESIGN.md。

• 履歴契約エビデンス: SOURCE_AUDIT.md。

• OpenAI Secure MCP Tunnel: https://developers.openai.com/api/docs/guides/secure-mcp-tunnels。

• OpenAIプラグイン接続/テスト: https://developers.openai.com/plugins/deploy/connect-chatgpt。

• 公式tunnel-clientソース: https://github.com/openai/tunnel-client。