MCP Infrastructure Architecture

Version: 1.1 Status: Implemented (Phase Q) Standard: Model Context Protocol (Anthropic/Google) Source: src/modules/mcp/

---

1. Overview

Jorvis implements the Model Context Protocol (MCP) to provide a standardized, secure, and discoverable way for AI agents to interact with external tools and data. This module serves as both an Host (running tools) and a Client (connecting to external MCP servers).

2. Architecture

2.1 McpModule (src/modules/mcp/mcp.module.ts)

The central module that:

1. Scans and registers all available Tool providers.
2. Exposes the MCP Protocol endpoints (SSE/Stdio).
3. Manages connection state.

2.2 Tools Registry

• Service: ToolsRegistryService
• Function: Maintains a dynamic map of available tools.
• Discovery: Tools decorators @McpTool('name') automatically register services.

2.3 Execution Flow

1. Discovery: LLM requests list_tools.
2. Selection: LLM chooses weather_tool with params { city: "London" }.
3. Routing: GraphOrchestrator -> ToolExecutionNode -> McpService.
4. Execution: McpService invokes the registered handler with validation.
5. Result: JSON result returned to LLM context.

3. Tool Implementation Guide

Tools reside in src/modules/mcp/tools/.

Example: Weather Tool

@Injectable()
export class WeatherTool implements McpToolInterface {
  public name = 'get_weather';
  public description = 'Get current weather for a city';
  public schema = z.object({
    city: z.string(),
    unit: z.enum(['C', 'F']).optional(),
  });

  async execute(params: any): Promise<any> {
    // API Call logic
    return { temp: 20, condition: 'Sunny' };
  }
}

4. Security Model

• Sandboxing: Tools run in the main Node.js process but are logical units.
• Authorization: Tools inherit the user's permission scope.
• Validation: STRICT Zod schema validation for all inputs.
• Timeout: 30s hard timeout per tool execution.

5. Current Toolset (Phase Q)

6. Future Roadmap

• External MCP Connection: Allow Jorvis to connect to other MCP servers (e.g., Brave Research, Slack).
• Remote Execution: Run potentially unsafe tools in isolated Docker containers (Firecracker microVMs).