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

1. Clone the repository

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

2. Install dependencies

mix deps.get

3. 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 DO permissions

4. Configure the Flux integration (if using image generation)

   • Set up the Flux CLI environment as described in the Flux Integration section

5. Configure the Dart integration (if using task management)

   • Set up the Dart MCP server as described in the Dart Integration section

6. Start the server

mix phx.server

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

Adding Custom MCP Servers

MCPheonix is designed to work with multiple MCP servers. This system includes a flexible infrastructure for integrating custom MCP servers through:

1. 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" }
          ]
        }
      }
    }
  }
}

2. 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

Built-in Capabilities

Resources