client/public/INTEGRATION_GUIDE.md

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:

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.