| # Director.AI - Integration Guide (Workspace MCP) | |
| ## Overview | |
| This document explains how the **Google Antigravity CLI** (or any autonomous agent script) should connect to the Director.AI webapp environment to control it autonomously. | |
| Unlike a standard web app where a human clicks buttons, **Director.AI acts as a Host Workspace**. The AI Agent connects as a client and can read state, create projects, and force the human's browser viewport to navigate to specific pages so the human can watch the AI work in real time. | |
| ## Connection Details | |
| - **Protocol**: WebSocket (Socket.IO v4) | |
| - **Host**: `ws://localhost:5000/mcp` | |
| - **Method**: The agent must connect using a standard Socket.IO client pointing to the `/mcp` namespace. | |
| ### Sample Node.js Agent Code | |
| If you are writing an agent to control this workspace, here is how you connect: | |
| ```javascript | |
| import { io } from 'socket.io-client'; | |
| const socket = io('http://localhost:5000/mcp'); | |
| socket.on('connect', () => { | |
| console.log('Agent connected to Workspace Hub!'); | |
| // Example: Read current projects | |
| socket.emit('mcp:read_state', (response) => { | |
| console.log('Current projects:', response.data.projects); | |
| }); | |
| }); | |
| ``` | |
| ## Available Tools (Socket.IO Events) | |
| The following tools are exposed by the MCP server for the agent to use: | |
| ### 1. `mcp:read_state` | |
| Reads the current high-level state of the application. | |
| - **Payload**: None required. | |
| - **Callback Returns**: `{ status: 'success', data: { projects: Project[] } }` | |
| ### 2. `mcp:navigate` | |
| Forces all connected human browsers to instantly navigate to a specific React Router path. Use this to guide the user's attention. | |
| - **Payload**: `{ path: string }` | |
| - Example: `{ path: '/dashboard' }` or `{ path: '/project/12345/create' }` | |
| - **Callback Returns**: `{ status: 'success' }` | |
| ### 3. `mcp:create_project` | |
| Autonomously creates a new project in the database. The webapp will automatically refresh its project list, and force navigation to the newly created project's URL. | |
| - **Payload**: `{ name: string, defaultPlatform: 'TikTok'|'YouTube', defaultFormat: '9:16'|'16:9' }` | |
| - **Callback Returns**: `{ status: 'success', data: Project }` | |
| ### 4. `mcp:update_video_draft` | |
| Used when the agent is iteratively drafting a video script. It streams updates directly to the human's screen. | |
| - **Payload**: `{ projectId: string, script?: string, voiceType?: string }` | |
| - **Callback Returns**: `{ status: 'success' }` | |
| ### 5. `mcp:activity_log` | |
| Sends a log message to the "Agent Activity Log" panel visible on the human's screen. Use this constantly to tell the human what you are doing (e.g. "I am researching competitors to write a better script..."). | |
| - **Payload**: `{ message: string, type: 'info' | 'success' | 'warning' | 'error' }` | |
| - **Callback Returns**: None | |
| ## Example Workflow for the Agent | |
| 1. **Connect**: Agent connects to `/mcp`. | |
| 2. **Log**: emit `mcp:activity_log` -> "Agent initialized. Analyzing workspace..." | |
| 3. **Navigate**: emit `mcp:navigate` (`{ path: '/dashboard' }`) -> Forces human browser to dashboard. | |
| 4. **Create**: emit `mcp:create_project` (`{ name: 'Viral Story', defaultPlatform: 'TikTok', defaultFormat: '9:16' }`). | |
| 5. **Log**: emit `mcp:activity_log` -> "Project created. Script drafting initiated." | |
| 6. **Navigate**: emit `mcp:navigate` -> Agent navigates browser to `/project/[id]/create` so human sees the creation wizard. | |
| 7. **Complete**: Agent continues to build the video via tools. | |
| ## Development Note for Antigravity Engine | |
| If you are running the `antigravity` CLI, you will need to map these Socket.IO standard emissions into your internal tool calling schema. The webapp is completely passive and trusts the AI to orchestrate the flow. | |