MCPheonix

MCPhoenix

基于 Phoenix Framework（Elixir）构建的 MCP 服务。为 MCP 客户端提供 Server-Sent Events 和 JSON-RPC 端点，并支持通过 JSON 配置管理多个子 MCP 服务。

注意：代码库中的模块和目录名称始终拼写为“MCPheonix”（不含字母“o”）。

功能

在端口 4001 上运行 Phoenix Web 服务器，以便：

1. 在 POST /mcp/rpc 接收 MCP JSON-RPC 请求
2. 在 GET /mcp/stream 通过 SSE 向客户端传输事件
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 application, supervision tree
    mcp/
      server.ex            — Core MCP server logic
      server_manager.ex    — Manages child MCP server processes
      server_process.ex    — GenServer wrapping a child stdio process
      supervisor.ex        — Supervisor for MCP server processes
      config.ex            — Reads mcp_servers.json
      connection.ex        — Client connection state
      json_rpc_protocol.ex — JSON-RPC 2.0 parsing
      jsonrpc_client.ex    — Client for calling child servers
      flux_server.ex       — Flux-specific server config
      features/
        resources.ex       — Resource listing
        tools.ex           — Tool listing and dispatch
    events/
      broker.ex            — Pub/sub event broker
    cloud/
      durable_objects/
        client.ex          — Cloudflare Durable Objects HTTP client
    resources/
      message.ex, registry.ex, user.ex — Domain resources (Ash framework)
  mcpheonix_web/
    endpoint.ex            — Phoenix endpoint
    router.ex              — Routes: /mcp/stream (SSE), /mcp/rpc (JSON-RPC)
    controllers/
      mcp_controller.ex    — SSE stream and RPC handler
      page_controller.ex   — Default page
    plugs/
      mcp_rpc_plug.ex      — Parses JSON-RPC body
      raw_body_*.ex        — Raw body reading for RPC

添加 MCP 服务

编辑 priv/config/mcp_servers.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 监督下的子进程启动，并在失败时重启。

设置

git clone https://github.com/jmanhype/MCPhoenix.git
cd MCPhoenix       # note: the repo name uses correct spelling
mix deps.get
mix phx.server     # starts on port 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	Worker 部署、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	Web 框架
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 框架资源（User、Message、Registry）似乎只是脚手架，尚未完全集成
• LiveView 和 LiveDashboard 已包含，但未用于 MCP 接口
• 日志文件（dev.log、phoenix_server.log）和临时文件已提交到代码库

许可证

MIT