内容
# MCPhoenix
MCP 服务器构建于 Phoenix 框架（Elixir）。通过 JSON 配置为 MCP 客户端公开服务器发送事件和 JSON-RPC 端点，并支持管理多个子 MCP 服务器。
注意：模块和目录名称在整个代码库中使用拼写“MCPheonix”（不带'o'）。
## 功能
在端口 4001 上运行一个 Phoenix 网络服务器：
1. 在 `POST /mcp/rpc` 处接受 MCP JSON-RPC 请求
2. 通过 SSE 在 `GET /mcp/stream` 处向客户端流式传输事件
3. 将子 MCP 服务器（Flux 图像生成，Dart 任务管理等）作为受监视的进程进行管理
4. 通过 stdio 将工具调用路由到适当的子服务器
子服务器在 `priv/config/mcp_servers.json` 中定义，并在启动时自动启动。
## 状态
| 区域 | 状态 |
|------|-------|
| 传输 | HTTP（SSE + JSON-RPC） |
| 框架 | Phoenix 1.7，Elixir >= 1.14，Erlang >= 25 |
| 子 MCP 服务器 | Flux（图像生成），Dart（任务管理） |
| OTP 监督 | 是 — 子服务器是受监视的进程 |
| Cloudflare 集成 | Durable Objects 客户端（实验性，使用自定义 hex 包） |
| 事件系统 | Broadway + GenStage 用于处理管道 |
| 测试 | ExUnit，2 个测试文件（Cloudflare DO 客户端，模拟 WebSocket） |
| 许可证 | MIT |
## 架构
```
lib/
mcpheonix/
application.ex — OTP 应用程序，监督树
mcp/
server.ex — 核心 MCP 服务器逻辑
server_manager.ex — 管理子 MCP 服务器进程
server_process.ex — GenServer 包装子 stdio 进程
supervisor.ex — MCP 服务器进程的监督器
config.ex — 读取 mcp_servers.json
connection.ex — 客户端连接状态
json_rpc_protocol.ex — JSON-RPC 2.0 解析
jsonrpc_client.ex — 调用子服务器的客户端
flux_server.ex — Flux 特定服务器配置
features/
resources.ex — 资源列表
tools.ex — 工具列表和调度
events/
broker.ex — 发布/订阅事件代理
cloud/
durable_objects/
client.ex — Cloudflare Durable Objects HTTP 客户端
resources/
message.ex, registry.ex, user.ex — 域资源（Ash 框架）
mcpheonix_web/
endpoint.ex — Phoenix 端点
router.ex — 路由：/mcp/stream（SSE），/mcp/rpc（JSON-RPC）
controllers/
mcp_controller.ex — SSE 流和 RPC 处理程序
page_controller.ex — 默认页面
plugs/
mcp_rpc_plug.ex — 解析 JSON-RPC 正文
raw_body_*.ex — RPC 原始正文读取
```
## 添加 MCP 服务器
编辑 `priv/config/mcp_servers.json`：
```json
{
"mcpServers": {
"your_server": {
"command": "/path/to/executable",
"args": ["arg1"],
"env": { "API_KEY": "value" },
"tools": {
"tool_name": {
"description": "What it does",
"parameters": [
{ "name": "param1", "type": "string", "description": "..." }
]
}
}
}
}
}
```
服务器作为子进程在 OTP 监督下启动，并在失败时重新启动。
## 设置
```bash
git clone https://github.com/jmanhype/MCPhoenix.git
cd MCPhoenix # 注意：存储库名称使用正确的拼写
mix deps.get
mix phx.server # 在端口 4001 上启动
```
### 要求
| 依赖 | 版本 |
|-----------|---------|
| Elixir | >= 1.14 |
| Erlang/OTP | >= 25 |
| Phoenix | ~> 1.7.0 |
| Node.js | >= 18（用于子 MCP 服务器） |
| Python | >= 3.9（用于 Flux/Dart 集成） |
### 可选集成
| 集成 | 需要 |
|------------|---------------|
| Flux 图像生成 | Python 3.9+，Flux CLI，`BFL_API_KEY` |
| Dart 任务管理 | Node.js 18+，`DART_TOKEN` |
| Cloudflare Durable Objects | 工作部署，`CLOUDFLARE_WORKER_URL`，`CLOUDFLARE_ACCOUNT_ID`，`CLOUDFLARE_API_TOKEN` |
## MCP 端点
| 端点 | 方法 | 目的 |
|----------|--------|---------|
| `/mcp/stream` | GET | SSE 流；返回 `x-mcp-client-id` 头部 |
| `/mcp/rpc` | POST | JSON-RPC 2.0；传递 `x-mcp-client-id` 头部 |
## 关键依赖
| 包 | 版本 | 目的 |
|---------|---------|---------|
| `phoenix` | ~> 1.7.0 | 网络框架 |
| `phoenix_live_view` | ~> 0.19.0 | LiveView（包含但不是主要接口） |
| `ash` | ~> 2.9 | 资源框架 |
| `broadway` | ~> 1.0 | 事件处理 |
| `gen_stage` | ~> 1.2 | 事件流 |
| `finch` | ~> 0.16 | HTTP 客户端 |
| `mint_web_socket` | ~> 1.0 | WebSocket 支持 |
| `jason` | ~> 1.4 | JSON 编码 |
## 限制
- Cloudflare Durable Objects 集成依赖于自定义 GitHub hex 包（`cloudflare_durable_ex`），可能不公开可用
- MCP 端点上没有身份验证
- SSE 连接在服务器重启时不保留
- Ash 框架资源（用户、消息、注册表）似乎已脚手架但未完全集成
- LiveView 和 LiveDashboard 包含但未用于 MCP 接口
- 日志文件（`dev.log`、`phoenix_server.log`）和临时文件已提交到存储库
## 许可证
MIT
MCP 市场
