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