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

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

Response Format

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

Error Format

{
  "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:

{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 1
}

Response:

{
  "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:

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

Response:

{
  "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:

{
  "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
• MCP Concepts
• JSON-RPC 2.0
• MCP 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)