# MCP Server Integration Guide
This document describes how the robotics webapp integrates with various MCP servers.
## Architecture
The webapp uses a three-layer architecture:
1. **MCP Servers** - External FastMCP servers (Unity3D, VRChat, Avatar, OSC, VRoid, Resonite, Local LLM)
2. **Backend API** - FastAPI backend (`backend/main.py`) that proxies MCP tool calls
3. **Frontend Service** - React service (`src/services/mcpService.ts`) for calling MCP tools
## MCP Servers
| Server | Port | Purpose |
|--------|------|---------|
| Unity3D | 8001 | Unity Editor automation, scene management, builds |
| VRChat | 8002 | VRChat avatar control, OSC communication |
| Avatar | 8003 | VRM avatar management, animation, rigging |
| OSC | 8004 | Open Sound Control for audio/visual applications |
| VRoid | 8005 | VRoid Studio automation, character creation |
| Resonite | 8006 | Resonite metaverse integration, world management |
| Local LLM | 8007 | AI/LLM management (Ollama, LM Studio, cloud LLMs) |
## Backend Integration
The backend (`backend/mcp_client.py`) provides:
- `MCPClient` class for HTTP communication with MCP servers
- Health checking for all servers
- Tool calling with error handling
- Tool listing for discovery
### API Endpoints
- `GET /api/mcp/servers` - Get status of all MCP servers
- `GET /api/mcp/servers/{server_name}/health` - Check server health
- `GET /api/mcp/servers/{server_name}/tools` - List available tools
- `POST /api/mcp/servers/{server_name}/tools/{tool_name}` - Call an MCP tool
## Frontend Integration
The frontend service (`src/services/mcpService.ts`) provides:
- Typed interfaces for MCP tool calls
- Server-specific helper methods
- Error handling and logging
### Usage Example
```typescript
import mcpService from '../../services/mcpService'
// Check server health
const healthy = await mcpService.checkHealth('unity3d')
// Call a tool
const result = await mcpService.unity3dCallTool('build_project', {
platform: 'Windows',
target: 'x86_64'
})
if (result.success) {
console.log('Build successful:', result.data)
} else {
console.error('Build failed:', result.error)
}
```
## Page Integration
Each page integrates MCP tools as follows:
1. **Check connection** on component mount
2. **Call MCP tools** when user interacts with UI
3. **Fallback to mock data** if MCP server unavailable
4. **Display connection status** in UI
### Example: Unity3D Page
```typescript
const [mcpConnected, setMcpConnected] = useState(false)
useEffect(() => {
const checkConnection = async () => {
const healthy = await mcpService.checkHealth('unity3d')
setMcpConnected(healthy)
}
checkConnection()
}, [])
const buildProject = useCallback(async () => {
if (mcpConnected) {
const result = await mcpService.unity3dCallTool('build_project', {
platform: unity.buildSettings.platform
})
// Handle result...
} else {
// Fallback to mock...
}
}, [mcpConnected])
```
## Configuration
MCP server URLs are configured via environment variables:
- `UNITY3D_MCP_URL` (default: `http://localhost:8001`)
- `VRCHAT_MCP_URL` (default: `http://localhost:8002`)
- `AVATAR_MCP_URL` (default: `http://localhost:8003`)
- `OSC_MCP_URL` (default: `http://localhost:8004`)
- `VROID_MCP_URL` (default: `http://localhost:8005`)
- `RESONITE_MCP_URL` (default: `http://localhost:8006`)
## Error Handling
All MCP calls include error handling:
- Connection failures fall back to mock data
- Tool call errors are logged and displayed to user
- Health checks run periodically to update connection status
## Future Enhancements
- WebSocket support for real-time MCP updates
- Tool discovery and auto-completion
- Batch tool calls for efficiency
- Caching of tool responses
