技術概要：HarnessAPI – 統合ストリーミング API と MCP ツール向けのスキルファーストフレームワーク

1. 問題定義

本論文は、大規模言語モデル（LLM）ツールの展開における重要なアーキテクチャ上の摩擦を特定しています。現在、開発者は LLM ツールとして意図されたすべての Python 関数について、2 つの並行した表現を維持する必要があります。

1. HTTP エンドポイント: 人間向けクライアント、Web ダッシュボード、CI パイプライン向け。通常、FastAPI などのフレームワークを使用して実装されます。
2. MCP ツール: Claude Desktop や Cursor などのエージェントランタイム向け。モデルコンテキストプロトコル（MCP）を使用し、通常は FastMCP などのフレームワークを使用して実装されます。

これら 2 つのインターフェースは同じ基盤となるビジネスロジックを共有していますが、ルーティング、バリデーション、シリアライゼーション、ストリーミング、スキーマ維持といった周辺機構において乖離しています。この「デュアルスタック」アプローチは、開発者に 2 つの別々のスキーマ定義（1 つは HTTP/Pydantic 用、もう 1 つは MCP 用）の維持を強います。コードが進化するにつれて、これらの定義は互いに乖離し、スキーマの陳腐化を招きます。本論文は Patil ら [9] を引用し、型スキーマが欠落しているか陳腐化している場合、LLM が API 呼び出しを幻覚（ハルシネーション）させることを指摘しており、この乖離は信頼性のリスク要因となっています。さらに、Mastouri ら [10] は実証的に、MCP サーバーの 88.6% が既存の REST サービスによって裏付けられていることを発見しました。つまり、展開の大多数はすでにこの二重維持の負担を背負っていることになります。

既存のフレームワークは、ルート（FastAPI）またはツール（FastMCP）のいずれかを主たる実体として扱い、他方については別途登録行為を要求します。これにより、開発者は 2 つの間で同期レイヤーとして機能することを強いられます。

2. 手法：スキルファーストアーキテクチャ

HarnessAPI は、依存関係を逆転させる「スキルファースト」アーキテクチャを提案します。開発者がルート、次にツール（またはその逆）を宣言するのではなく、スキルフォルダが単一の真実源（Single Source of Truth）となります。

中核設計原則

• 単一の真実源: スキルは、型付けされた handler.py と Pydantic の models.py を含むディレクトリとして定義されます。
• 導出された表現: フレームワークは、この単一のディレクトリ構造から、HTTP エンドポイントと MCP ツール登録の両方を自動的に導出します。
• 構造的不変性: 両方のトランスポートが実行時に同じ Pydantic モデルに解決されるため、スキーマの一貫性は開発者の規律によるものではなく、構築によって強制されます。

主要な技術メカニズム

1. スキル発見と分離:

   • フレームワークはスキルディレクトリをスキャンし、handler.py と models.py を含むサブフォルダを識別します。
   • 名前空間の衝突（例：複数のスキルが Input という名前のクラスを定義する）を防ぐため、HarnessAPI は各スキルに対して types.ModuleType を使用した合成パッケージ名前空間を作成します。これにより、複数のスキルが互いのクラスをシャドウイングすることなく共存できます。

2. デュアルモードコンテンツネゴシエーション:

   • フレームワークは、単一のハンドラからストリーミングおよび非ストリーミングの両方のレスポンスをサポートします。
   • ストリーミング（SSE）: クライアントが application/json を要求しない場合、フレームワークはサーバーサイドイベント（SSE）ストリームを開きます。chunk、result、done、または error イベントを emit しながら、チャンクを逐次的に生成します。
   • バッチ（JSON）: クライアントが Accept: application/json を送信する場合、フレームワークはハンドラの出力をバッファリングし、単一の JSON レスポンスを返します。
   • これにより、同じハンドラがコード変更なしに、インタラクティブなエージェントセッション（ストリーミング）とバッチパイプライン（JSON）の両方を提供できます。

3. 動的 MCP ラッパー生成:

   • 対処された重要な技術的課題は、FastMCP のスキーマインテロスペクションです。これは関数の __annotations__ を読み取り、__globals__ に対して型を解決することに依存しています。単純なクロージャは、Pydantic モデルが関数のグローバルスコープに存在しないため失敗します。
   • 解決策: HarnessAPI は、Pydantic モデルを明示的に含む名前空間内で exec を使用してラッパー関数を動的にコンパイルします。これにより、型が FastMCP のインスペクション層によって解決可能となり、手動でのスキーマ重複なしに正しいツール登録が可能になります。

4. ライフサイクル管理:

   • HarnessAPI は FastAPI をサブクラス化し、FastMCP アプリケーションを ASGI サブアプリケーションとしてマウントします。
   • ユーザーのアプリケーション（例：データベース接続）と FastMCP サーバーの両方の起動/シャットダウンフックを組み合わせたマージされたライフスパンコンテキストマネージャを実装し、単一プロセス展開を可能にします。

5. ホットスワップ機能（開発専用）:

   • オプションのエンドポイントにより、コード文字列を提出してハンドラロジックを動的に置き換えることができます。これは、本番環境でのリモートコード実行を防ぐため、ループバックアドレス（localhost）に厳密に制限されています。

3. 主要な貢献

本論文は、以下の貢献を定義します。

1. スキルファーストアーキテクチャパターン: ルートファースト（FastAPI）およびツールファースト（FastMCP）のパターンと対照的に、スキルディレクトリが権威ある定義となる形式的なパターン。
2. 実装メカニズム:
   • 動的ルート生成とデュアルモードコンテンツネゴシエーション。
   • Pydantic アノテーションを FastMCP のインスペクション層に伝播させるためのコード生成技術。
   • 単一プロセス運用のためのライフスパンマージ戦略。
3. ボイラープレート削減: フレームワーク向けのコードが大幅に削減されたことを示す実証的評価。
4. オープンソースリリース: PyPI と GitHub で利用可能な HarnessAPI v0.1.4 のリリース。

4. 評価結果

著者は、Echo、Greet、Summarize、VectorNorm、Classify、Translate という 6 つの代表的なスキルを使用して、HarnessAPI を手動で維持されたデュアルスタック実装（個別の FastAPI および FastMCP サーバー）と比較評価しました。

• ボイラープレート削減: cloc を使用して、ビジネスロジックを除くフレームワーク向けのコード（空行およびコメント行を除く）の行数を数えたところ、HarnessAPI は 6 つのスキル全体で合計44 行を要したのに対し、手動実装では170 行でした。これはボイラープレートが74% 削減されたことを意味します。
• スケーリング挙動: 手動アプローチは $O(n)$ のスケーリングを示し、フレームワークコードはスキルの数に比例して増加します（それぞれに新しいデコレーターと登録が必要）。一方、HarnessAPI はエントリーポイントがスキル数に関係なく固定されるため、フレームワークコードに関して $O(1)$ のスケーリングを示します。
• 機能同等性: HarnessAPI は、SSE ストリーミング、OpenAPI/Swagger UI、スキルごとのタイムアウトなど、スタンドアロンの FastAPI および FastMCP のすべての機能を追加ライブラリの統合なしに提供します。
• 互換性: このフレームワークは、ソースコードの変更なしに agentskills.io リポジトリから 12 の既存スキルを正常にインポートおよび登録し、既存のスキルセットに対する摩擦のない展開を実証しました。

5. 意義と主張

本論文は、HarnessAPI が LLM ツール展開における「二重維持」という居心地の悪い答えを解決すると主張しています。その意義は、スキーマの一貫性をエラーや乖離を起こしやすい開発者の規律から、フレームワークによって強制される構造的な不変性へと変容させる点にあります。

著者は、74% のボイラープレート削減はこの不変性の結果であると強調していますが、より永続的な結果はスケーリング特性です。エージェントエコシステムが成熟し、開発者が数十から数百のスキルを展開するにつれ、手動によるデュアルスタック登録の累積的な維持負担は耐えられなくなります。HarnessAPI は、2 つの登録を維持するためのより良いツールではなく、2 つ目の登録そのものを排除することが解決策であると示唆しています。

本論文はその範囲について謙虚に述べています。

• 基盤となる FastAPI/Uvicorn スタックの既知のパフォーマンス特性に譲る形で、エンドツーエンドのレイテンシや並行性のベンチマークの解決を主張していません。
• MCP ラッパー生成のための exec の使用（FastMCP の現在のresolverに対する一時的な回避策）や、MCP レイヤーにおけるツールごとの認証の欠如など、制限事項を認めています。
• ホットスワップエンドポイントのネットワークアクセス可能な展開での使用を明確に警告し、ローカル開発ループに限定しています。

結論として、HarnessAPI は、スキーマの一貫性を確保し、維持管理のオーバーヘッドを削減し、現代の LLM エージェント向けにストリーミングおよびバッチの両方のインタラクションをサポートする、統合されたスキルファースト展開レイヤーを提供します。