atlas/docs/MCP_ARCHITECTURE.md

# Model Context Protocol (MCP) Architecture

## Overview

This document describes the Model Context Protocol (MCP) architecture for the Atlas voice agent system. MCP enables LLMs to interact with external tools and services through a standardized protocol.

## MCP Concepts

### Core Components

#### 1. **Hosts**
- **Definition**: LLM servers that process requests and make tool calls
- **In Atlas**: 
  - Work Agent (4080) - Llama 3.1 70B Q4
  - Family Agent (1050) - Phi-3 Mini 3.8B Q4
- **Role**: Receives user requests, decides when to call tools, processes tool responses

#### 2. **Clients**
- **Definition**: Applications that use LLMs and need tool capabilities
- **In Atlas**:
  - Phone PWA
  - Web Dashboard
  - Voice interface (via routing layer)
- **Role**: Send requests to hosts, receive responses with tool calls

#### 3. **Servers**
- **Definition**: Tool providers that expose capabilities via MCP
- **In Atlas**: MCP Server (single service with multiple tools)
- **Role**: Expose tools, execute tool calls, return results

#### 4. **Tools**
- **Definition**: Individual capabilities exposed by MCP servers
- **In Atlas**: Weather, Time, Tasks, Timers, Reminders, Notes, etc.
- **Role**: Perform specific actions or retrieve information

## Protocol: JSON-RPC 2.0

MCP uses JSON-RPC 2.0 for communication between components.

### Request Format

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "weather",
    "arguments": {
      "location": "San Francisco, CA"
    }
  },
  "id": 1
}
```

### Response Format

```json
{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "The weather in San Francisco is 72°F and sunny."
      }
    ]
  },
  "id": 1
}
```

### Error Format

```json
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32603,
    "message": "Internal error",
    "data": "Tool execution failed: Invalid location"
  },
  "id": 1
}
```

## MCP Methods

### 1. `tools/list`
List all available tools from a server.

**Request:**
```json
{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 1
}
```

**Response:**
```json
{
  "jsonrpc": "2.0",
  "result": {
    "tools": [
      {
        "name": "weather",
        "description": "Get current weather for a location",
        "inputSchema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "City name or address"
            }
          },
          "required": ["location"]
        }
      }
    ]
  },
  "id": 1
}
```

### 2. `tools/call`
Execute a tool with provided arguments.

**Request:**
```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "weather",
    "arguments": {
      "location": "San Francisco, CA"
    }
  },
  "id": 2
}
```

**Response:**
```json
{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "The weather in San Francisco is 72°F and sunny."
      }
    ]
  },
  "id": 2
}
```

## Architecture Integration

### Component Flow

```
┌─────────────┐
│   Client    │ (Phone PWA, Web Dashboard)
│  (Request)  │
└──────┬──────┘
       │
       │ HTTP/WebSocket
       │
┌──────▼──────────┐
│ Routing Layer  │ (Routes to appropriate agent)
└──────┬─────────┘
       │
       ├──────────────┐
       │              │
┌──────▼──────┐  ┌────▼──────┐
│ Work Agent  │  │Family Agent│
│  (4080)     │  │  (1050)   │
└──────┬──────┘  └────┬──────┘
       │              │
       │ Function Call│
       │              │
┌──────▼──────────────▼──────┐
│   MCP Adapter              │ (Converts LLM function calls to MCP)
└──────┬─────────────────────┘
       │
       │ JSON-RPC 2.0
       │
┌──────▼──────────┐
│  MCP Server    │ (Tool provider)
│  ┌──────────┐  │
│  │ Weather  │  │
│  │ Tasks    │  │
│  │ Timers   │  │
│  │ Notes    │  │
│  └──────────┘  │
└────────────────┘
```

### MCP Adapter

The MCP Adapter is a critical component that:
1. Receives function calls from LLM hosts
2. Converts them to MCP `tools/call` requests
3. Sends requests to MCP server
4. Receives responses and converts back to LLM format
5. Returns results to LLM for final response generation

**Implementation:**
- Standalone service or library
- Handles protocol translation
- Manages tool discovery
- Handles errors and retries

### MCP Server

Single service exposing all tools:
- **Protocol**: JSON-RPC 2.0 over HTTP or stdio
- **Transport**: HTTP (for network) or stdio (for local)
- **Tools**: Weather, Time, Tasks, Timers, Reminders, Notes, etc.
- **Security**: Path whitelists, permission checks

## Tool Definition Schema

Each tool must define:
- **name**: Unique identifier
- **description**: What the tool does
- **inputSchema**: JSON Schema for arguments
- **outputSchema**: JSON Schema for results (optional)

**Example:**
```json
{
  "name": "add_task",
  "description": "Add a new task to the home Kanban board",
  "inputSchema": {
    "type": "object",
    "properties": {
      "title": {
        "type": "string",
        "description": "Task title"
      },
      "description": {
        "type": "string",
        "description": "Task description"
      },
      "priority": {
        "type": "string",
        "enum": ["high", "medium", "low"],
        "default": "medium"
      }
    },
    "required": ["title"]
  }
}
```

## Security Considerations

### Path Whitelists
- Tools that access files must only access whitelisted directories
- Family agent tools: Only `family-agent-config/tasks/home/`
- Work agent tools: Only work-related paths (if any)

### Permission Checks
- Tools check permissions before execution
- High-risk tools require confirmation tokens
- Audit logging for all tool calls

### Network Isolation
- MCP server runs in isolated network namespace
- Firewall rules prevent unauthorized access
- Only localhost connections allowed (or authenticated)

## Integration Points

### 1. LLM Host Integration
- LLM hosts must support function calling
- Both selected models (Llama 3.1 70B, Phi-3 Mini 3.8B) support this
- Function definitions provided in system prompts

### 2. Client Integration
- Clients send requests to routing layer
- Routing layer directs to appropriate agent
- Agents make tool calls via MCP adapter
- Results returned to clients

### 3. Tool Registration
- Tools registered at MCP server startup
- Tool definitions loaded from configuration
- Dynamic tool discovery via `tools/list`

## Implementation Plan

### Phase 1: Minimal MCP Server (TICKET-029)
- Basic JSON-RPC 2.0 server
- Two example tools (weather, echo)
- HTTP transport
- Basic error handling

### Phase 2: Core Tools (TICKET-031, TICKET-032, TICKET-033, TICKET-034)
- Weather tool
- Time/date tools
- Timers and reminders
- Home tasks (Kanban)

### Phase 3: MCP-LLM Integration (TICKET-030)
- MCP adapter implementation
- Function call → MCP call conversion
- Response handling
- Error propagation

### Phase 4: Advanced Tools (TICKET-035, TICKET-036, TICKET-037, TICKET-038)
- Notes and files
- Email (optional)
- Calendar (optional)
- Smart home (optional)

## References

- [MCP Specification](https://modelcontextprotocol.io/specification)
- [MCP Concepts](https://modelcontextprotocol.info/docs/concepts/tools/)
- [JSON-RPC 2.0](https://www.jsonrpc.org/specification)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)

## Next Steps

1. ✅ MCP concepts understood and documented
2. ✅ Architecture integration points identified
3. Implement minimal MCP server (TICKET-029)
4. Implement MCP-LLM adapter (TICKET-030)
5. Add core tools (TICKET-031, TICKET-032, TICKET-033, TICKET-034)

---

**Last Updated**: 2024-01-XX
**Status**: Architecture Complete - Ready for Implementation (TICKET-029)