README - MCPheonix by jmanhype

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 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 DO permissions
Configure the Flux integration (if using image generation)
- Set up the Flux CLI environment as described in the section
Configure the Dart integration (if using task management)
- Set up the Dart MCP server as described in the section
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:

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