MCPheonix

# 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](docs/cloudflare_integration.md) 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 ```bash git clone https://github.com/yourusername/mcpheonix.git cd mcpheonix ``` 2. Install dependencies ```bash 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](docs/flux_integration.md) section 5. Configure the Dart integration (if using task management) - Set up the Dart MCP server as described in the [Dart Integration](docs/dart_integration.md) section 6. Start the server ```bash 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`: ```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](docs/adding_mcp_servers.md) 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