📌Overview

Purpose: MCPheonix aims to simplify the implementation of a distributed AI event system via the Model Context Protocol (MCP) while leveraging Elixir's Phoenix Framework.

Overview: MCPheonix is a robust server framework that facilitates intelligent interactions between AI models and application data, utilizing the Model Context Protocol to provide a cohesive interface for managing events and resources. The framework is designed for resilience and real-time communication, taking advantage of Cloudflare's capabilities to ensure a self-healing distributed architecture.

Key Features:

Real-Time Notifications: Server-Sent Events (SSE) stream enables instantaneous event notifications to clients, enhancing responsiveness.
Client Interaction via JSON-RPC: Offers a dedicated JSON-RPC endpoint for clients to submit requests easily, facilitating seamless integration.
Event Mechanism: Implements a publish/subscribe architecture to allow components to dynamically respond to state changes, aiding in self-healing.
Extensible Architecture: Supports the integration of custom MCP servers, ensuring adaptability to various use cases and environments.
Self-Healing Capabilities: Uses Cloudflare Durable Objects to maintain state consistency and auto-recovery, ensuring continuous operation even during failures.
Edge Computing Features: Harnesses Cloudflare Workers for high availability and performance by distributing application state globally.

MCPheonix

A simplified implementation of the Model Context Protocol (MCP) server using Elixir's Phoenix Framework.

Overview

MCPheonix is an intelligent, self-healing, distributed AI event system using Model Context Protocol and Elixir's Phoenix Framework. It provides a server that implements the Model Context Protocol, allowing AI models to interact with your application data and functionality through a unified interface.

Features

Server-Sent Events (SSE) stream for real-time notifications
JSON-RPC endpoint for client requests
Simple resource system
Event publish/subscribe mechanism
Basic tool invocation
Flux image generation integration
Dart task management integration
Extensible MCP server architecture
Self-healing distributed architecture via Cloudflare Durable Objects
Edge computing capabilities through Cloudflare Workers

Self-Healing Distributed Architecture

MCPheonix implements a sophisticated self-healing system through its integration with Cloudflare Durable Objects and Workers, creating a distributed, resilient architecture that can withstand failures and ensure continuous operation.

Key Components

Durable Objects: Stateful serverless components running on Cloudflare's global edge network that maintain consistency even across failures.
Edge Distribution: Critical application state is replicated across Cloudflare's global network, ensuring availability even during regional outages.
Automatic Recovery: If an instance becomes unavailable, the system automatically recreates it with consistent state from durable storage.
Real-time Communication: WebSocket support enables instant recovery coordination and state synchronization across the distributed system.
Event-Driven Architecture: Components react to state changes through a publish/subscribe model, allowing the system to self-heal and adapt to failures.

For detailed information on the implementation, see the Cloudflare Integration documentation.

Getting Started

Prerequisites

Elixir 1.14 or higher
Erlang 25 or higher
Phoenix 1.7.0 or higher
Python 3.9+ (for Flux and Dart integration)
Node.js 18+ (for Dart MCP server)
Cloudflare account (for Durable Objects integration)

Installation

Clone the repository

git clone https://github.com/yourusername/mcpheonix.git
cd mcpheonix

Install dependencies
```
mix deps.get
```
Configure the Cloudflare integration
- Create a Cloudflare Worker using the template in cloudflare/durable-objects-worker.js
- Deploy it to your Cloudflare account
- Set the environment variables:
  - CLOUDFLARE_WORKER_URL: URL of your deployed worker
  - CLOUDFLARE_ACCOUNT_ID: Your Cloudflare account ID
  - CLOUDFLARE_API_TOKEN: API token with Workers and Durable Objects permissions
Configure the Flux integration (if using image generation)
- Set up the Flux CLI environment as described in the Flux Integration section
Configure the Dart integration (if using task management)
- Set up the Dart MCP server as described in the Dart Integration section
Start the server
```
mix phx.server
```

The server will be available at http://localhost:4001.

Adding Custom MCP Servers

MCPheonix supports multiple MCP servers with a flexible infrastructure to integrate custom MCP servers.

Simple JSON Configuration: Define your server settings in priv/config/mcp_servers.json:

{
  "mcpServers": {
    "your_server_id": {
      "command": "/path/to/executable",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR1": "value1",
        "ENV_VAR2": "value2"
      },
      "tools": {
        "your_tool": {
          "description": "Description of your tool",
          "parameters": [
            { "name": "param1", "type": "string", "description": "Parameter description" }
          ]
        }
      }
    }
  }
}

Automatic Server Management: Servers are automatically loaded and managed during application startup.

For comprehensive implementation details, including the Elixir architecture, server lifecycle management, and protocol handling, see the Adding MCP Servers documentation.

MCP Endpoints

SSE Stream: GET /mcp/stream
- Establishes a Server-Sent Events stream for receiving real-time notifications
- Returns a client ID in the response headers
JSON-RPC: POST /mcp/rpc
- Accepts JSON-RPC 2.0 requests
- Client ID can be provided in the x-mcp-client-id header or will be generated if missing

MCPhoenix