MCP ツール統合ポリシー

NENE2 の MCP ツールは、隠れたデータベースやファイルシステムのショートカットではなく、文書化された境界を通じてアプリケーション機能を公開する必要があります。

ポジション

MCP 統合は API 対応の統合レイヤーです。

NENE2 の LLM 支援デリバリー方向は docs/integrations/llm-delivery-starter.md に文書化されています。

デフォルトの方向性:

実用的な場合は OpenAPI からツールの形を導出する
read-only 検査ツールから始める
ローカル開発ツールと本番ツールを分離する
mutation ツールの前に明示的な認可と監査ポリシーを要求する
デフォルトでは MCP ツールからの直接データベースアクセスを避ける

ツールのソース

ツール定義の推奨ソース:

パブリック JSON API の OpenAPI オペレーション
HTTP を使用しない内部ツールの文書化されたアプリケーションサービス
ローカル専用ワークフローの明示的なメンテナンスコマンド

通常のアプリケーション境界で実行・検証できない MCP 専用の動作の作成を避けてください。

カタログ

最初の機械可読 MCP ツールカタログは docs/mcp/tools.json にあります。

出荷された OpenAPI オペレーションに対応した read-only ツールメタデータが含まれています。カタログは以下で検証されます:

bash

docker compose run --rm app composer mcp

composer check にはこの検証が含まれます。

生成されたカタログの方向性は docs/integrations/openapi-to-mcp-catalog.md に文書化されています。

安全レベル

各 MCP ツールは実装前に分類する必要があります:

read: アプリケーション状態を変更せずに返す
write: アプリケーション状態を変更する
admin: 設定・権限・データ保持・運用状態を変更する
destructive: データを削除するか不可逆な操作を実行する

最初の MCP ツールは read ツールであるべきです。

write・admin・destructive ツールには以下が必要です:

文書化された認証と認可の動作
監査/ロギングフィールド
request id の伝播
destructive アクションの明示的な確認動作
失敗と権限境界をカバーするテスト

API キーとトークンの境界は docs/development/authentication-boundary.md で定義されています。

ローカル開発ツール

ローカル専用の MCP ツールはエージェントが開発アプリを検査するのに役立ちますが、スコープを明確に限定する必要があります。

ローカル MCP サーバー統合ガイダンスは docs/integrations/local-mcp-server.md にあります。安全なローカルコマンドは docs/integrations/local-ai-commands.md に文書化されています。

ローカルツールで許可される操作:

ローカル HTTP API を呼び出す
コミットされたドキュメントを読み取る
文書化された安全な検証コマンドを実行する

ローカルツールで禁止される操作:

.env のシークレットを読み取る
本番動作に似た方法でアプリケーション認可をバイパスする
文書化されたテストまたはマイグレーションコマンド以外でデータベースを変更する
開発者の非公開ファイルシステムレイアウトに依存する

本番ツール

本番 MCP ツールは、デバッグのショートカットではなく、プロダクト機能として設計する必要があります。

本番ツールを有効にする前に、以下を文書化してください:

所有者と目的
必要な認証情報またはスコープ
許可される環境
レート制限または不正利用対策
監査フィールド
失敗した mutation のロールバックまたは修復パス

OpenAPI との整合性

ツールが HTTP API オペレーションにマッピングされる場合:

OpenAPI オペレーションの summary とスキーマを出発点として使用する
パラメーター名を API コントラクトと一致させる
Problem Details エラーの動作を保持する
有用な場合はログと返されるメタデータに request id を含める

request id 処理の AI 支援デバッグガイダンスは docs/integrations/ai-debugging.md にあります。

ツールが現在の API に合わない形を必要とする場合は、先に API コントラクトを更新するか、なぜ内部サービス境界の方が良いかを文書化してください。

パスパラメーターの型

OpenAPI パスパラメーターが integer 型（例: {year}・{id}）の場合、ツールの inputSchema はその型を反映する必要があります:

json

"inputSchema": {
  "type": "object",
  "properties": {
    "year": { "type": "integer" }
  },
  "required": ["year"]
}

LLM クライアントは整数パスパラメーターを文字列ではなく JSON 数値として送信する必要があります:

json

{"name": "getItemsByYear", "arguments": {"year": 2026}}

文字列（"2026"）を送信すると、スキーマが "type": "integer" を指定している場合にアダプターバリデーションで拒否されます。これは OpenAPI スキーマで type: integer または type: number を使用する任意のパスパラメーターに適用されます。

非目標

最初の MCP マイルストーンとして直接本番データベースツールを提供する。
HTTP/API テストをバイパスする MCP 専用のビジネス動作。
リポジトリに MCP 認証情報を保存する。
認証・認可・監査ポリシーが存在する前に destructive ツールを公開する。

MCP ツール統合ポリシー ​

ポジション ​

ツールのソース ​

カタログ ​

安全レベル ​

ローカル開発ツール ​

本番ツール ​

OpenAPI との整合性 ​

パスパラメーターの型 ​

非目標 ​