# jmanhype/mcphoenix architecture

> Architecture diagram of the GitHub repository jmanhype/mcphoenix, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jmanhype/mcphoenix
- Repository: https://github.com/jmanhype/mcphoenix

## Overview

##### Project Overview and Main Purpose
- MCPheonix is a server implementation of the Model Context Protocol using Elixir’s Phoenix Framework.
- It is designed as a distributed, self-healing event system that leverages Cloudflare Durable Objects and Workers for resilience.
- It exposes endpoints for Server-Sent Events (SSE) and JSON-RPC, enabling real-time notifications and remote procedure calls from client-side AI models or other services.

##### Analyzing the File Structure
- Notice the separation of concerns across directories:
- “assets”: Contains front-end assets (e.g., CSS) needed to render and style the user interface.
- “config”: Holds environment-specific configuration files (dev, test, runtime) as well as JSON configuration for MCP servers.
- “docs”: Provides detailed documentation such as integration with Cloudflare, Dart, and Flux.
- “examples” and “test”: Demonstrates usage examples and unit tests for various components.
- “lib”: The main application logic is split into logical namespaces:
- “mcpheonix”: Contains core components of the MCP server, including events, resources, and the management of MCP processes.
- “mcpheonix_web”: Manages the web layer (controllers, plugs, router, endpoint, telemetry) for handling HTTP requests.
- “cloudflare_durable”: Specific integration with Cloudflare’s durable objects and WebSocket connection handling.

##### Key Components
a. Client/External Systems
- Clients that connect to the system via SSE (for real-time notifications) and JSON-RPC endpoints.
- External integrations such as Flux (for image generation) and Dart (for task management).

b. Web Frontend & API Layer
- “mcpheonix_web”: Represent the HTTP server components (controllers, router, endpoint) responsible for exposing the `/mcp/stream` (SSE) and `/mcp/rpc` endpoints.
- A plug layer that handles request modifications and logging (e.g., “raw_body_logger”, “mcp_rpc_plug”).

c. MCP Server Core
- How the configuration is loaded from JSON files (e.g., in priv/config/mcp_servers.json and config/mcp_servers.json) and used to manage custom MCP servers.

d. Event System and Resource Management
- “mcpheonix/events” and “mcpheonix/resources”: Show how different events are published and subscribed to, and how resources (like users and messages) are managed.
- Event-driven architecture with publish/subscribe flows and notifications relayed to connected clients.

e. Cloudflare Durable Objects & Edge Integration
- Real-time coordination using WebSockets for state synchronization and automatic recovery across distributed nodes.

##### Relationships and Interactions
- Demonstrate how MCP events trigger actions in the resources subsystem.
- Bi-directional communication between the MCP server and Cloudflare Durable Objects (for self-healing and real-time state updates).
- Interplay where configuration files in “config” and “priv/config” dictate the behavior and orchestration of MCP servers.

##### Architectural Patterns and Principles
- The system follows a modular design with clear separation between the web interface, business logic (MCP core), and infrastructure integrations.
- It adopts an event-driven architecture and leverages Supervisor trees (inherent in Elixir/OTP) for fault tolerance and recovery.
- The distributed architecture with Cloudflare integration further reinforces resiliency and the self-healing concept.

##### Relevant Technologies and Frameworks
- Elixir and Phoenix Framework: Serve as the backbone of the application logic and the web server.
- OTP Supervisors: Ensure reliable process management and automatic recovery.
- JSON-RPC and SSE: Provide API endpoints for client interactions.
- Cloudflare Durable Objects & Workers: Power the edge-driven distributed, resilient system.
- Integration tools like Flux and Dart: Handle additional functionalities like image generation and task management.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Client / External Systems
    subgraph "Client & External Systems"
        Client["Clients (SSE & JSON-RPC)"]:::external
        Integrations["Integrations (Flux & Dart)"]:::external
    end

    %% Web Frontend & API Layer
    subgraph "Web Frontend & API Layer"
        Controller["MCP Controller"]:::webLayer
        RPCPlug["MCP RPC Plug"]:::webLayer
        Router["Router & Endpoint"]:::webLayer
    end

    %% MCP Server Core
    subgraph "MCP Server Core"
        Server["Server (server.ex)"]:::mcpCore
        Manager["Server Manager (server_manager.ex)"]:::mcpCore
        Supervisor["Supervisor (supervisor.ex)"]:::mcpCore
        Config1["MCP Config (config/mcp_servers.json)"]:::mcpCore
        Config2["MCP Config (priv/config/mcp_servers.json)"]:::mcpCore
    end

    %% Event System & Resource Management
    subgraph "Event & Resource Management"
        EventBroker["Event Broker (broker.ex)"]:::eventSystem
        Resources["Resources (users, messages, registry)"]:::resources
    end

    %% Cloudflare Durable Objects & Edge Integration
    subgraph "Cloudflare Durable Objects"
        CFDurable["CF Durable Core"]:::external
        CFWebSocket["CF WebSocket Connection (connection.ex)"]:::external
        MCPDurable["MCP Durable Client (client.ex)"]:::external
    end

    %% Connections / Flows
    Client -->|"connects"| Controller
    Client -->|"connects"| RPCPlug
    Integrations -->|"triggers"| Controller

    Controller -->|"routes to"| Router
    RPCPlug -->|"processes"| Router

    Router -->|"forwards request"| Server
    Server -->|"delegates to"| Manager
    Manager -->|"monitors"| Supervisor

    Config1 -->|"configures"| Server
    Config2 -->|"configures"| Server

    Server -->|"triggers"| EventBroker
    Server -->|"updates"| Resources

    Supervisor -->|"oversees"| Manager

    Server <-->|"syncs state"| CFDurable
    Manager <-->|"syncs state"| MCPDurable
    CFDurable -->|"handles"| CFWebSocket

    %% Click Events for Web Frontend & API Layer
    click Controller "https://github.com/jmanhype/mcphoenix/blob/main/lib/mcpheonix_web/controllers/mcp_controller.ex"
    click RPCPlug "https://github.com/jmanhype/mcphoenix/blob/main/lib/mcpheonix_web/plugs/mcp_rpc_plug.ex"
    click Router "https://github.com/jmanhype/mcphoenix/tree/main/lib/mcpheonix_web"

    %% Click Events for MCP Server Core
    click Server "https://github.com/jmanhype/mcphoenix/blob/main/lib/mcpheonix/mcp/server.ex"
    click Manager "https://github.com/jmanhype/mcphoenix/blob/main/lib/mcpheonix/mcp/server_manager.ex"
    click Supervisor "https://github.com/jmanhype/mcphoenix/blob/main/lib/mcpheonix/mcp/supervisor.ex"

    %% Click Event for Configuration Files
    click Config1 "https://github.com/jmanhype/mcphoenix/blob/main/config/mcp_servers.json"
    click Config2 "https://github.com/jmanhype/mcphoenix/blob/main/priv/config/mcp_servers.json"

    %% Click Events for Event System & Resource Management
    click EventBroker "https://github.com/jmanhype/mcphoenix/blob/main/lib/mcpheonix/events/broker.ex"
    click Resources "https://github.com/jmanhype/mcphoenix/tree/main/lib/mcpheonix/resources"

    %% Click Events for Cloudflare Durable Objects & Edge Integration
    click CFDurable "https://github.com/jmanhype/mcphoenix/tree/main/lib/cloudflare_durable"
    click CFWebSocket "https://github.com/jmanhype/mcphoenix/blob/main/lib/cloudflare_durable/websocket/connection.ex"
    click MCPDurable "https://github.com/jmanhype/mcphoenix/blob/main/lib/mcpheonix/cloud/durable_objects/client.ex"

    %% Styles
    classDef webLayer fill:#E0F7FA,stroke:#006064,stroke-width:2px;
    classDef mcpCore fill:#E8F5E9,stroke:#2E7D32,stroke-width:2px;
    classDef eventSystem fill:#FFF3E0,stroke:#E65100,stroke-width:2px;
    classDef resources fill:#F1F8E9,stroke:#33691E,stroke-width:2px;
    classDef external fill:#FCE4EC,stroke:#C2185B,stroke-width:2px;
```
