19. MCP アーキテクチャと外部エージェント統合仕様

1. 概要

BluePeriod は、外部の AI エージェント（Claude Code、Cursor、その他の MCP クライアント）からアプリケーションを直接操作・参照できる MCP (Model Context Protocol) 統合をサポートしています。このドキュメントでは、外部エージェントが BluePeriod の機能にアクセスするためのプロトコル、通信アーキテクチャ、および実装設計について説明します。

2. アーキテクチャ構成 (Hono Server & WebView Bridge)

Tauri + React + Next.js (App Router) という複雑な環境において、Web版とDesktop版の差異を吸収しつつ、CORS 制約や Node.js 依存を回避するために、BluePeriod の MCP 統合は独自の「WebView Bridge Pattern」を採用しています。

2.1. 構成要素の役割

MCP STDIO Server (mcp-stdio-server.ts):
- ユーザーのシェル（コマンドライン）から起動される軽量な Node.js プロセス。
- Claude Code などの標準出力 (stdio) を解釈し、Hono Broker (Next.js) に対して HTTP リクエストへ変換して中継します。
Hono Broker (/api/mcp/*):
- リクエストの受信用キューを保持し、WebView (クライアント側) がポーリングしてくるのを待機します。
- Web版・デスクトップ版の両方で共通の API インターフェースを提供します。（Hono RPC）
WebView Bridge (useMcpBridge.ts):
- アプリケーションがブラウザや Tauri ウィンドウで起動している間、バックグラウンドで Hono Broker に「ロングポーリング」を行い、ツール実行リクエストを受け取ります。
- ツール名に応じて内部の Service レイヤー (Jotai Store) を叩き、実際の処理（プロジェクトリスト取得、原稿の取得・編集など）を実行し、その結果を再度 Hono Broker に返します。

2.2. WebView Bridge Pattern のメリット

Local-First データへの唯一のアクセスパス: BluePeriod はブラウザの IndexedDB にプロジェクトデータを持っているため、外部の Node.js プロセス（STDIO Server）は直接 DB ファイルを読み取れません。ブラウザのコンテキスト（WebView）内から操作する必要があります。
HITL (Human in the Loop) の統合: Agent がデータを破壊的に書き換える前に、UI が起動しているブラウザコンテキスト内で、ユーザーに対して「本当に処理を続行するか？」のポップアップ（承認ダイアログ）を出すことができます。

3. コンテキストバインディングとスコープ管理

外部エージェントは非常に強力ですが、アプリの暗黙のコンテキスト（「今ユーザーがどのプロジェクトを開いているか」）を知りません。そのため、MCP ツール層の実装において以下の強力な制約を課しています。

(Writing作業時等では)すべての操作ツールは基本的には projectId を引数として要求する
- 以前は「アクティブなプロジェクト」を前提にツールを作成していましたが、エージェントが「どのプロジェクトを操作しているか」を見失う事故があり、API スキーマで明示的に必須化しました。
- ただし、listProjects 等のプロジェクト一覧を取得するツールは projectId を要求しません。
- 重要なのは、外部エージェントに対しては、操作対象への明示的な宣言を要求するということです。
自動コンテキストロード (loadProjectAtom)
- Hono 側のツール定義において projectId を必須化し、WebView Bridge 側でその ID に該当するプロジェクトを直ちに Jotai にロードすることで、データ整合性と Service レイヤーへのアクセスの安全性を保証しています。

4. MCP エラーハンドリングとライフサイクル

React の Strict Mode や、エージェント特有の予測不能な非同期処理に起因して、ロングポーリングがタイムアウト（500エラー）を引き起こす問題の対策が行われています。

多重ポーリングの抑止: useMcpBridge.ts における厳密なマウント/アンマウントのライフサイクル管理。
Fail-Safe Response: 呼び出されたツールが存在しなくても、引数が不正でも、WebView Bridge は絶対にタイムアウトせず、Hono Broker へエラー文字列付きの /respond を投げ返します。これにより Claude 側は「何が失敗したのか」を正確に学習してリトライに繋げることができます。

5. Deep MCP と三層の整合性 (Three-Layer Consistency)

BluePeriod は、単に外部からツールを呼べるだけでなく、アプリ内部の AI エージェント（内製エージェント）と外部の MCP エージェントが全く同じツール定義とビジネスロジックを共有する「Deep MCP」アーキテクチャを採用しています。

5.1. 三層の整合性原則

以下の 3 つのインターフェースにおいて、提供される機能とデータ品質が完全に一致することを保証します：

GUI (User Interface): ユーザーがボタンやエディタで直接操作する。
Internal Agent (LangChain): アプリ内のチャット欄で動作する自律エージェント。
External Agent (MCP): Claude Code や Cursor 等、外部のツールから操作する。

5.2. 機能拡張（Feature-Root Architecture）

これを実現するため、すべてのエージェントツールは src/lib/features/ 配下の各機能ディレクトリ（projects/, editorial/ 等）に集約されています。

標準化された命名: すべてのプロジェクト関連ツールは blueperiod_ プレフィックスを持ち、内部・外部で共通の名称を使用します。
軽量データ取得: AI コンテキストの肥大化を防ぐため、blueperiod_get_project などのツールは原稿本文を除いた軽量なデータを返すように最適化されています。
Adit 編集の統合: 外部エージェントも内製エージェントと同様に、blueperiod_apply_adit_edits を使用して、SEARCH/REPLACE 形式や構造化された差分による高度な原稿編集が可能です。

関連ドキュメント:

12_ai_agent_architecture - 内製エージェントの構成
18_agent_tool_integration_guide - 詳細なツール実装ガイド
20_ai_agent_tool_architecture_overview - ツールアーキテクチャ概要

MCP アーキテクチャと外部エージェント統合仕様

On this page