How jmanhype/mcphoenix works
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.