MCPモジュールコード標準

なぜコード標準が重要なのか

私たちが出荷するすべてのコネクタは同じに見えます。それは偶然ではなく、規律です。2番目の統合が到着したとき、各MCPモジュールが同じ構造、命名、エラー契約に従うため、エージェントのケーパビリティはテスト、監査、スワップしやすくなります。

このドキュメントは、IdeaBosqueオーケストレーションバックボーン内のすべてのMCPモジュールの標準を定義します。ディレクトリレイアウト、ツール登録、入出力スキーマ、エラー処理、レート制限、監査ログ、PII境界処理をカバーします。

ディレクトリ構造

各MCPモジュールは、一貫したレイアウトで app/mcp_modules/ 配下の独自ディレクトリに存在します：

app/mcp_modules/<slug>/
  __init__.py
  module.py          # ツール登録 + ハンドラ
  schemas.py         # 入出力Pydanticモデル
  tests/
    test_module.py
  README.md

ツール登録

各モジュールは標準インターフェースを通じてツールを登録します。オーケストレーションバックボーンは register_tools() エントリポイントをスキャンしてツールを発見します — 手動ワイヤリングは不要です。

def register_tools(registrar):
    """このモジュールが提供するすべてのツールを登録する。"""
    registrar.tool(
        name="search_catalog",
        description="SKUまたは名前でサプライヤーカタログを検索",
        input_schema=SearchCatalogInput,
        output_schema=SearchCatalogOutput,
        rate_limit=120,  # 1分あたりの呼び出し数
    )

エラー処理

モジュールは生の文字列ではなく、型付き例外を発生させる必要があります。バックボーンは MCPToolError サブクラスをキャッチし、エージェントが推論できる構造化レスポンスに変換します：

• MCPAuthError — 認証情報の欠落または期限切れ
• MCPRateLimitError — アップストリームレート制限に到達
• MCPTimeoutError — アップストリーム呼び出しが設定されたタイムアウトを超過
• MCPValidationError — 入力がスキーマ検証を通過しなかった
• MCPUpstreamError — アップストリームがエラーステータスを返した

レート制限

各ツールは登録呼び出しで独自のレート制限を宣言します。バックボーンはエージェントごと、ツールごと、ウィンドウごとにこれらを適用します。制限に到達すると、エージェントは Retry-After ヘッダー付きの 429 レスポンスを受け取ります — クラッシュしたり盲目的にリトライしたりしません。

監査ログ

各ツール呼び出しは以下と共にログに記録されます：タイムスタンプ、エージェントID、ツール名、入力ハッシュ（生の入力ではなく — PII境界）、出力ステータス、期間、アップストリームシステム。ログは構造化JSONで書き込まれ、オブザーバビリティパイプラインに送信されます。

「すべてのツール呼び出しがログに記録され監査可能」は、後から追加する機能ではありません。標準が最初に要求するものです。

PII境界処理

モジュールはどの入力フィールドにPIIが含まれるかを宣言する必要があります。バックボーンはログに記録する前にこれらのフィールドをハッシュ化し、生のPIIを監査パイプラインに送信しません。PIIフィールドはスキーマでマークされます：

class SearchCatalogInput(BaseModel):
    sku: str
    customer_name: str = Field(..., pii=True)
    region: str

pii=True が設定されている場合、監査ロガーは値をSHA-256ハッシュに置き換えます。ツールハンドラは引き続き生の値を受け取ります — PII処理はログ境界で強制され、ビジネスロジックの内部ではありません。