Agent Communication MCP Server

# Rooms Feature API Documentation Agent Communication MCP Server - エージェントB担当のルーム・プレゼンス機能の完全実装 ## 概要 ルーム・プレゼンス機能は、複数のエージェントがルームベースでコミュニケーションを行うための基盤機能です。Slackのようなチャンネル機能を提供し、エージェントの入退室管理、プレゼンス追跡、ルーム統計情報の管理を行います。 ## 機能一覧 ### ルーム管理 - ルームの作成・削除 - ルーム一覧の取得 - ルーム存在確認 - ルーム統計情報の管理 ### プレゼンス管理 - エージェントの入退室 - オンライン/オフライン状態管理 - ルーム内ユーザー一覧 - プロフィール情報管理 ## データ構造 ### rooms.json ```json { "rooms": { "general": { "description": "General discussion", "createdAt": "2024-01-20T09:00:00Z", "messageCount": 0, "userCount": 2 }, "dev-team": { "description": "Development team discussions", "createdAt": "2024-01-20T10:00:00Z", "messageCount": 15, "userCount": 3 } } } ``` ### presence.json (ルームごと) ```json { "roomName": "general", "users": { "agent1": { "status": "online", "messageCount": 5, "joinedAt": "2024-01-20T10:00:00Z", "profile": { "role": "coordinator", "description": "Task coordination agent", "capabilities": ["task_planning", "resource_management"], "metadata": { "version": "1.0.0", "specialization": "project_management" } } }, "agent2": { "status": "offline", "messageCount": 2, "joinedAt": "2024-01-20T11:00:00Z", "profile": { "role": "analyzer", "description": "Data analysis agent", "capabilities": ["data_analysis", "reporting"] } } } } ``` ## API Reference ### RoomsAPI Class メインのAPI実装クラス。ルーム管理とプレゼンス管理の統合インターフェースを提供します。 ```typescript import { RoomsAPI } from './src/features/rooms'; const api = new RoomsAPI('./data'); ``` #### コンストラクタ ```typescript constructor(dataDir: string = './data') ``` - `dataDir`: データファイルを保存するディレクトリパス（デフォルト: './data'） ### ルーム管理メソッド #### createRoom() 新しいルームを作成します。 ```typescript async createRoom(name: string, description?: string): Promise<CreateRoomResult> ``` **パラメータ:** - `name`: ルーム名（英数字、ハイフン、アンダースコアのみ、1-50文字） - `description`: ルームの説明（省略可、最大200文字） **戻り値:** ```typescript { success: boolean; roomName: string; message: string; } ``` **例:** ```typescript const result = await api.createRoom('dev-team', 'Development team discussions'); // { success: true, roomName: 'dev-team', message: "Room 'dev-team' created successfully" } ``` **エラー:** - `RoomAlreadyExistsError`: 同名のルームが既に存在 - `ValidationError`: 名前や説明の形式が不正 #### listRooms() ルーム一覧を取得します。 ```typescript async listRooms(agentName?: string): Promise<ListRoomsResult> ``` **パラメータ:** - `agentName`: エージェント名（省略可、指定時は参加状況も含める） **戻り値:** ```typescript { rooms: Array<{ name: string; description?: string; userCount: number; messageCount: number; isJoined?: boolean; // agentName指定時のみ }>; } ``` **例:** ```typescript const result = await api.listRooms(); // { rooms: [{ name: 'general', description: '...', userCount: 3, messageCount: 10 }] } const filteredResult = await api.listRooms('my-agent'); // { rooms: [{ ..., isJoined: true }] } ``` #### roomExists() ルームの存在を確認します。 ```typescript async roomExists(name: string): Promise<boolean> ``` #### getRoomData() ルームの詳細データを取得します。 ```typescript async getRoomData(name: string): Promise<RoomData | null> ``` **戻り値:** ```typescript { description?: string; createdAt: string; messageCount: number; userCount: number; } | null ``` ### プレゼンス管理メソッド #### enterRoom() エージェントをルームに入室させます。 ```typescript async enterRoom(agentName: string, roomName: string, profile?: AgentProfile): Promise<EnterRoomResult> ``` **パラメータ:** - `agentName`: エージェント名（英数字、ハイフン、アンダースコア、1-50文字） - `roomName`: ルーム名 - `profile`: エージェントプロフィール（省略可） **プロフィール形式:** ```typescript { role?: string; // 役割（例: 'coordinator', 'analyzer'） description?: string; // 説明 capabilities?: string[]; // 能力リスト metadata?: Record<string, any>; // カスタムメタデータ } ``` **戻り値:** ```typescript { success: boolean; roomName: string; message: string; } ``` **例:** ```typescript const result = await api.enterRoom('agent1', 'dev-team', { role: 'coordinator', description: 'Team coordination agent', capabilities: ['planning', 'scheduling'], metadata: { version: '2.0.0' } }); ``` **エラー:** - `RoomNotFoundError`: ルームが存在しない - `ValidationError`: パラメータの形式が不正 #### leaveRoom() エージェントをルームから退室させます。 ```typescript async leaveRoom(agentName: string, roomName: string): Promise<LeaveRoomResult> ``` **エラー:** - `RoomNotFoundError`: ルームが存在しない - `AgentNotInRoomError`: エージェントがそのルームにいない #### getRoomUsers() ルーム内のユーザー一覧を取得します。 ```typescript async getRoomUsers(roomName: string): Promise<ListRoomUsersResult> ``` **戻り値:** ```typescript { roomName: string; users: Array<{ name: string; status: 'online' | 'offline'; messageCount?: number; profile?: AgentProfile; }>; onlineCount: number; } ``` ### 統計・管理メソッド #### getRoomCount() 総ルーム数を取得します。 ```typescript async getRoomCount(): Promise<number> ``` #### getAllRoomNames() すべてのルーム名を取得します。 ```typescript async getAllRoomNames(): Promise<string[]> ``` #### getOnlineUsersCount() 指定ルームのオンラインユーザー数を取得します。 ```typescript async getOnlineUsersCount(roomName: string): Promise<number> ``` #### cleanupOfflineUsers() 長時間オフラインのユーザーを削除します。 ```typescript async cleanupOfflineUsers(roomName: string, thresholdHours?: number): Promise<number> ``` **パラメータ:** - `thresholdHours`: オフライン時間の閾値（デフォルト: 24時間） **戻り値:** 削除されたユーザー数 ## MCP Tools 以下の5つのMCPツールが実装されています： ### 1. agent_communication/create_room 新しいルームを作成します。 **パラメータ:** ```json { "roomName": "dev-team", "description": "Development team discussions" } ``` ### 2. agent_communication/list_rooms ルーム一覧を取得します。 **パラメータ:** ```json { "agentName": "my-agent" // 省略可 } ``` ### 3. agent_communication/enter_room ルームに入室します。 **パラメータ:** ```json { "agentName": "agent1", "roomName": "dev-team", "profile": { "role": "coordinator", "description": "Task coordination", "capabilities": ["planning"], "metadata": {} } } ``` ### 4. agent_communication/leave_room ルームから退室します。 **パラメータ:** ```json { "agentName": "agent1", "roomName": "dev-team" } ``` ### 5. agent_communication/list_room_users ルーム内のユーザー一覧を取得します。 **パラメータ:** ```json { "roomName": "dev-team" } ``` ## バリデーション ### ルーム名 - 必須、空文字不可 - 1-50文字 - 英数字、ハイフン（-）、アンダースコア（_）のみ ### エージェント名 - 必須、空文字不可 - 1-50文字 - 英数字、ハイフン（-）、アンダースコア（_）のみ ### 説明 - 省略可 - 最大200文字 ### プロフィール - `role`: 最大50文字 - `description`: 最大200文字 - `capabilities`: 最大20個、各項目最大50文字 ## エラーハンドリング ### カスタムエラークラス - `RoomAlreadyExistsError`: ルーム作成時に同名ルームが存在 - `RoomNotFoundError`: 存在しないルームに対する操作 - `AgentNotInRoomError`: ルームにいないエージェントに対する操作 - `AgentAlreadyInRoomError`: 既に入室済みのエージェントの入室（通常は発生しない） - `ValidationError`: 入力値の形式エラー - `StorageError`: ファイル操作エラー ### エラーハンドリング例 ```typescript try { await api.createRoom('invalid room name'); } catch (error) { if (error instanceof ValidationError) { console.error('入力値が不正です:', error.message); } else if (error instanceof RoomAlreadyExistsError) { console.error('ルームが既に存在します:', error.message); } else { console.error('予期しないエラー:', error); } } ``` ## パフォーマンス ### 負荷テスト結果 - ✅ 100ルーム作成: 平均 < 100ms/ルーム - ✅ 50エージェント×10ルーム入室: 平均 < 50ms/操作 - ✅ 同時操作: 20ルーム作成 + 5回一覧取得 < 30秒 - ✅ データ整合性: 5ルーム×10エージェント並行入退室 - ✅ メモリ効率: 50ルーム×20エージェントでクエリ < 1秒 ### 最適化ポイント 1. **ファイルI/O最小化**: 必要時のみファイル読み書き 2. **バッチ処理**: 複数操作の並行実行 3. **データ構造最適化**: 効率的なJSON形式 4. **エラー処理**: 適切な例外処理でパフォーマンス影響を最小化 ## 使用例 ### 基本的な使用フロー ```typescript import { RoomsAPI } from './src/features/rooms'; const api = new RoomsAPI('./data'); // 1. ルーム作成 await api.createRoom('project-alpha', 'Project Alpha discussions'); // 2. エージェント入室 await api.enterRoom('coordinator-agent', 'project-alpha', { role: 'coordinator', description: 'Project coordination agent', capabilities: ['planning', 'resource-management'] }); await api.enterRoom('dev-agent', 'project-alpha', { role: 'developer', capabilities: ['coding', 'testing'] }); // 3. ルーム一覧確認 const rooms = await api.listRooms(); console.log(rooms); // [{ name: 'project-alpha', userCount: 2, ... }] // 4. ユーザー一覧確認 const users = await api.getRoomUsers('project-alpha'); console.log(users); // { roomName: 'project-alpha', users: [...], onlineCount: 2 } // 5. エージェント退室 await api.leaveRoom('dev-agent', 'project-alpha'); // 6. 統計情報確認 const onlineCount = await api.getOnlineUsersCount('project-alpha'); console.log(onlineCount); // 1 ``` ### チーム管理の例 ```typescript // 複数チームの管理 const teams = ['frontend', 'backend', 'qa', 'devops']; // チームルーム作成 for (const team of teams) { await api.createRoom(`team-${team}`, `${team} team discussions`); } // チームメンバー配置 const members = { 'frontend': ['ui-agent', 'ux-agent'], 'backend': ['api-agent', 'db-agent'], 'qa': ['test-agent'], 'devops': ['deploy-agent'] }; for (const [team, agents] of Object.entries(members)) { for (const agent of agents) { await api.enterRoom(agent, `team-${team}`, { role: 'team-member', description: `${team} team member`, capabilities: [team] }); } } // 全体統計 const totalRooms = await api.getRoomCount(); const roomNames = await api.getAllRoomNames(); console.log(`Total rooms: ${totalRooms}, Rooms: ${roomNames.join(', ')}`); ``` ## 拡張性 ### 将来の拡張予定 1. **ファイルロック**: エージェントDによる同時アクセス制御 2. **メッセージ連携**: エージェントAによるメッセージ数自動更新 3. **管理機能**: エージェントCによる統計レポート 4. **通知機能**: 入退室イベント通知 5. **ルーム設定**: プライベートルーム、参加制限等 ### カスタマイズ ```typescript // カスタムデータディレクトリ const api = new RoomsAPI('/custom/data/path'); // 環境変数による設定 const dataDir = process.env.AGENT_COMM_DATA_DIR || './data'; const api = new RoomsAPI(dataDir); ``` ## トラブルシューティング ### よくある問題 1. **ファイル権限エラー** - データディレクトリの読み書き権限を確認 - 必要に応じて`chmod 755 ./data`を実行 2. **JSON形式エラー** - 既存のJSONファイルが破損している可能性 - バックアップから復元するか、ファイルを削除して再作成 3. **パフォーマンス問題** - 大量データ時はクリーンアップ機能を定期実行 - データディレクトリをSSD上に配置 4. **メモリ使用量** - 長時間実行時は定期的にオフラインユーザーをクリーンアップ - 必要に応じてプロセス再起動 ### デバッグ ```typescript // デバッグ用メソッド await api.clearAllRooms(); // 全ルーム削除 await api.clearRoomPresence('room-name'); // 特定ルームのプレゼンス削除 ``` ## 仕様準拠 本実装は以下の仕様に完全準拠しています： - ✅ spec.md 行29-108: 全5つのMCPツールの完全実装 - ✅ implementation-policy.md: エラーハンドリング、バリデーション方針 - ✅ parallel-implementation-plan.md: エージェントB担当範囲の完全実装 - ✅ agent-prompts/agent-b-rooms.md: 全完了条件の達成 ### 実装完了項目 - [x] RoomService.createRoom() - spec.md行46-56の仕様完全実装 - [x] RoomService.listRooms() - spec.md行31-44の仕様完全実装 - [x] PresenceService.enterRoom() - spec.md行58-74の仕様完全実装 - [x] PresenceService.leaveRoom() - spec.md行76-86の仕様完全実装 - [x] PresenceService.listRoomUsers() - spec.md行88-107の仕様完全実装 - [x] rooms.jsonデータ構造 - 仕様通りの実装 - [x] presence.jsonデータ構造 - 仕様通りの実装 - [x] 5つのMCPツール完全実装 - [x] Zodバリデーション実装 - [x] カスタムエラークラス実装 - [x] 単体テスト実装（90%以上カバレッジ対応） - [x] 負荷テスト実装（100ルーム×50ユーザー対応） - [x] 公開API (IRoomsAPI) 実装