ResearchTwin MCP Server

ResearchTwin MCP Server は、長期的な研究プロジェクトエージェントである ResearchTwin の永続的なアクション層です。OpenTrek でホストされるエージェントに、研究作業の記録、プロジェクト状態とアドバイザー要件の保持、エビデンスに基づく進捗レポートの作成を行うための本格的な MCP ツールを提供します。

このリポジトリは、競技品質のリファレンス実装として設計されています。RAG は研究資料から質問に回答し、MCP はプロジェクト記録に対する明示的で監査可能な変更を実行します。

コミットされているすべての例は架空のものであり、匿名化されています。運用データは runtime_data/ に属し、意図的に Git から除外されています。

概要

リサーチアシスタントは、単一の質問に答えるだけでは不十分です。ResearchTwin は、進行中のプロジェクトで何が起こったかの永続的な記録を保持します:

• 具体的な活動、成果、障害、次のステップ;

• 現在のプロジェクト段階、タスク、リスク、決定事項;

• 構造化されたアドバイザー要件;

• 永続化されたエビデンスから組み立てられた週次、ミーティング、またはステージレポート。

このサーバーは、OpenTrek 内の ResearchTwin Agent から呼び出されることを想定しています。エージェント、LLM、または既存の ResearchTwin_Docs ナレッジベースを置き換えるものではありません。

Related MCP server: AgentBase

MCP を採用する理由

RAG と MCP には明確に異なる役割があります:

この分離により、プロジェクト記録は決定的でレビュー可能なものになります。MCP サーバーは、構造化された活動を保存したり、保存された事実からレポートを作成したりするために、別の LLM を実行する必要はありません。

アーキテクチャ

flowchart LR
    U[Researcher] --> A[OpenTrek ResearchTwin Agent]
    A -->|retrieve and reason| R[ResearchTwin_Docs RAG]
    R --> K[Research papers and technical material]
    A -->|MCP function calls| M[ResearchTwin MCP Server]
    M --> T[Six research-management tools]
    T --> S[JSON persistence layer]
    S --> D[Runtime research records and reports]

コンポーネントの境界、永続化ルール、拡張ポイントについては、docs/architecture.md を参照してください。

機能

• 公式 Python MCP SDK との統合。

• /mcp におけるプライマリ MCP トランスポートとしての Streamable HTTP。

• 起動時に選択した場合の、オプションのコマンドライン SSE 互換トランスポート。

• モノリシックなサーバースクリプトではなく、6 つの焦点を絞ったツール。

• アトミック置換とプロセス内ロックを備えた UTF-8 JSON 永続化。

• UUID レコード識別子とタイムゾーン対応の ISO 8601 タイムスタンプ。

• エージェントのツール処理に適した構造化された成功およびエラーレスポンス。

• Windows PowerShell の起動、テスト、スモークテスト、OpenTrek 統合ガイダンス。

MCP ツール

完全な入力、出力、エラー契約は docs/mcp_tools.md にあります。

プロジェクト構造

ResearchTwin-MCP-Server/
├── server.py                         # Repository-root launch entry point
├── src/researchtwin_mcp/
│   ├── config.py                     # RESEARCHTWIN_* settings validation
│   ├── server.py                     # MCP server and transport startup
│   ├── models/                       # Validation helpers and schemas
│   ├── storage/                      # Shared JSON persistence layer
│   └── tools/                        # Activity, status, advisor, and report tools
├── scripts/
│   ├── start_server.ps1
│   └── smoke_test.py
├── tests/
├── docs/
├── examples/sample_data/             # Fictional, commit-safe demo data
└── runtime_data/                     # Local operational data; ignored by Git

要件

• Windows PowerShell(文書化されたワークフロー)

• Python 3.11 以降。Python 3.11.x が推奨される競技環境です

• OpenTrek が LAN 上の別のデバイスから実行される場合のみネットワークアクセスが必要

インストール

新しい Windows PowerShell セッションから:

Set-Location C:\work\OpenTrek\ResearchTwin-MCP-Server
python --version
where.exe python

python -m venv .venv
.\.venv\Scripts\Activate.ps1

python --version
where.exe python
python -m pip install --upgrade pip setuptools wheel
python -m pip install -e ".[dev]"

アクティベーション後、where.exe python の最初の結果は仮想環境のインタープリターである必要があります。PowerShell が現在のセッションのアクティベーションをブロックする場合は、文書化されたプロセススコープの実行ポリシー手順を使用し、その後環境を再度アクティベーションしてください。システム全体のポリシーを不必要に弱めないでください。

設定

サーバーはプロセス環境から次の環境変数を読み取ります:

.env.example は参照用/テンプレートのみです。サーバーは .env ファイルを自動的に読み込みません。PowerShell セッションで値を設定するか、デプロイメントに既存の外部環境ローダーがある場合はそれを使用してください:

$env:RESEARCHTWIN_HOST = "0.0.0.0"
$env:RESEARCHTWIN_PORT = "8000"
$env:RESEARCHTWIN_DATA_DIR = "runtime_data"
$env:RESEARCHTWIN_LOG_LEVEL = "INFO"

キー、個人識別子、またはユーザー固有の IP アドレスをソースコードやコミットされた設定に置かないでください。

実行

仮想環境をアクティベートした状態で:

python server.py

デフォルトのプライマリエンドポイントは次のとおりです:

http://<LAN_IPV4>:8000/mcp

ローカルマシンのみの場合は、<LAN_IPV4> を 127.0.0.1 に置き換えます。別の信頼できる LAN デバイス上の OpenTrek の場合は、Windows ホストの該当する IPv4 アドレスを使用します。ヘルパースクリプトも利用可能です:

.\scripts\start_server.ps1

Streamable HTTP が通常のモードです。明示的な SSE 互換性のためには、python server.py --transport sse を実行し、結果の /sse エンドポイントを OpenTrek 統合ガイダンス に記載されているように登録します。SSE は個別に選択されるトランスポートモードであり、/mcp と並べて登録する代替 URL ではありません。

テスト

リポジトリルートからユニットテストを実行します:

pytest -v

依存関係のインストール後にローカル MCP Streamable HTTP スモークテストを実行します:

python scripts\smoke_test.py

スモークテストは、実際のプロトコル接続、ツール検出、および活動の記録/一覧のラウンドトリップを検証します。runtime_data/ ディレクトリではなく、分離された一時データを使用します。

OpenTrek 統合

OpenTrek の登録では、UI の STREAMABLE オプションと次の URL 形式を使用する必要があります:

http://<LAN_IPV4>:8000/mcp

transportType の JSON 値を手動で発明しないでください。OpenTrek の MCP 登録ページで STREAMABLE を選択し、URL を入力して保存し、6 つのツールすべてが検出されることを確認してください。LAN IPv4 の検出、SSE 互換性、VPN チェック、安全なファイアウォールトラブルシューティングプロセスについては、docs/open_trek_integration.md を参照してください。

デモシナリオ

エンドツーエンドのデモンストレーションは、知識検索と永続的なアクションの違いを示すことができます:

1. エージェントは RAG を使用して、架空の RNN-PPO 論文またはメソッドノートを説明します。

2. 研究者は、RNN-PPO 実験が完了したが、トレーニングはまだ不安定であると言います。

3. エージェントは record_research_activity を結果、問題、次のステップとともに呼び出します。

4. 一般化に焦点を当てるという架空のアドバイザー要件が record_advisor_instruction で記録されます。

5. エージェントはプロジェクトの状態を確認し、グループミーティングのために generate_research_report を呼び出します。

結果の Markdown レポートは、一回限りの回答ではなく、永続化されたレコードに基づいています。ナレーション付きのランブックは docs/demo_flow.md にあります。

プライバシーと Git の安全性

リポジトリの .gitignore は、.venv/、pycache/、Python バイトコード、.env、pytest および Ruff キャッシュ、runtime_data/、ログファイルを除外します。これらのパスには、ローカルの研究活動、アドバイザーコンテキスト、レポート、資格情報、またはマシン固有のデータが含まれる可能性があります。

コミットしても安全なのは、examples/sample_data/ 内の架空の匿名フィクスチャのみです。コミットまたはプッシュの前に、以下を検査してください:

git status
git diff --check

実際のアドバイザーメッセージ、実際の論文コンテンツ、チャットの書き起こし、キー、VPN の詳細、または個人を特定できる情報をコミットしないでください。

ロードマップ

• 必要に応じて JSON ファイルから耐久性のあるマルチユーザーストレージバックエンドに移行する。

• ResearchTwin Memory および ResearchTwin_Core 統合ポイントを追加する。

• 既存の RAG レイヤーの周りに論文インテリジェンスと引用ワークフローを追加する。

• プロジェクト履歴とレポートをレビューするための保護されたダッシュボードを追加する。

• 実際の研究データを公開せずに競技デモのストーリーを改善する。

ドキュメント

• アーキテクチャ

• MCP ツールリファレンス

• OpenTrek 統合

• デモフロー

• 架空のサンプルデータ