Tidewave Phoenix：让 AI 真正读懂你的 Phoenix 应用

从盲人摸象到透视眼：AI 编程助手的根本困境

想象一下，你给 AI 一个任务：帮我修改这个 Phoenix 项目的用户认证模块，让它支持 OAuth2 登录。AI 信誓旦旦地开始写代码，但当你把代码跑起来时，发现它调用了一个根本不存在的函数，参数类型对不上，甚至连模块名都拼错了。

这背后的原因很残酷：AI 在编写代码时，看到的只是静态的文本——源代码、文档、GitHub 仓库。但它完全看不到应用在运行时的真实状态。它不知道数据库里有什么数据，不知道某个函数实际返回了什么，不知道日志里藏着什么错误提示，更不知道 Phoenix LiveView 的组件树长什么样。

这就是传统 AI 编程助手的盲区问题。而 Tidewave Phoenix 正是为解决这一痛点而生。

---

什么是 Tidewave Phoenix？

Tidewave Phoenix 是一个专为 Elixir/Phoenix 框架打造的 MCP（Model Context Protocol）服务器。它的核心理念是：让 AI 在运行时与 Phoenix 应用对话，而非仅凭静态代码猜行为。

Tidewave 将 Phoenix 应用变成一个可观测、可交互的智能体运行环境。AI 通过 MCP 协议连接后，可以：

• 执行代码：在真实运行时上下文中运行 Elixir 代码，查看返回结果
• 查询数据库：直接对开发数据库执行 SQL，验证数据状态
• 读取日志：获取应用运行日志，包括请求记录和错误堆栈
• 定位源码：找到任意模块/函数的定义位置（包括 Hex 依赖中的代码）
• 获取文档：查询精确版本的依赖文档（基于 mix.lock 中锁定的版本）

project_eval：AI 在真实运行时上下文中执行代码，如同拥有了一个 IEx 会话

execute_sql_query：AI 直接查询开发数据库，验证数据变更

---

技术实现：MCP 协议与 Phoenix 的深度融合

架构设计

Tidewave 的架构分为两层：

第一层：MCP 服务器（lib/mcp.ex、lib/handler.ex）负责处理 MCP 协议的通信，解析来自 AI 客户端（如 Claude Code、Codex、Cursor）的请求，并路由到对应的工具模块。

第二层：工具层（lib/tools/ 目录）提供具体的操作能力：

工具名	功能	应用场景
project_eval	在运行时执行 Elixir 代码	AI 想验证某个函数的行为，直接跑一遍看结果
execute_sql_query	执行 SQL 查询	验证数据变更、检查数据库状态
get_logs	读取应用日志	追踪请求处理、分析错误原因
get_source_location	定位模块/函数的源码文件路径	跳转到第三方依赖的源码中查看实现
get_docs	获取精确版本的依赖文档	确保 AI 看的文档与实际使用的版本一致
get_ecto_schemas	列出所有 Ecto schema 模块	帮助 AI 理解数据模型
get_ash_resources	列出 Ash 框架的资源定义	如项目使用 Ash，则额外提供框架信息

核心依赖

Tidewave 依赖精简，主要包括：

• Plug（~> 1.18）：Web 服务器接口，接收 MCP 请求
• Jason（~> 1.4）：JSON 序列化（MCP 协议基于 JSON-RPC）
• Bandit（~> 1.10，仅 dev/test）：本地开发用 HTTP 服务器
• WebSock Adapter（~> 0.5）：支持流式 MCP 连接
• Igniter（~> 0.6，可选）：自动化安装工具

值得注意的是，Tidewave 对 Phoenix LiveView v1.1+ 有良好支持，自动开启 HEEX 注解和属性调试功能。

---

安装与配置：三种方式，总有一款适合你

方式一：手动添加（推荐给 Hex 熟悉者）

在 mix.exs 的 deps 中添加：

{:tidewave, "~> 0.6", only: :dev}

然后在 lib/my_app_web/endpoint.ex 中注册 Plug：

if Mix.env() == :dev do
  plug Tidewave
end

方式二：Igniter 自动安装（一键搞定）

mix archive.install hex igniter_new
mix igniter.install tidewave

Igniter 会自动修改必要的文件，无需手动编辑。

方式三：非 Phoenix 项目

任何 Elixir 项目都可以使用：

{:tidewave, "~> 0.6", only: :dev},
{:bandit, "~> 1.0", only: :dev}

然后运行 mix tidewave 启动 MCP 服务器。

---

与主流 AI 工具的无缝集成

Tidewave 支持多种 AI 编程工具的 MCP 客户端配置，包括：

• Claude Code（官方集成文档）
• OpenAI Codex
• Cursor
• Neovim（通过 nvim-mcp）
• VS Code（通过 MCP 扩展）
• OpenCode

连接方式统一：通过 HTTP Streamable 类型的 MCP 连接，地址为 http://localhost:4000/tidewave/mcp。

get_docs：AI 获取精确版本的依赖文档

get_logs：AI 读取应用运行日志，追踪请求处理流程

---

局限与注意事项

1. 仅开发环境可用：Tidewave 明确标注 only: :dev，生产环境不会加载。
2. 安全边界：默认仅允许 localhost 访问。如需远程访问，必须显式配置 allow_remote_access: true，但需仔细评估安全风险。
3. Content-Security-Policy 调整：为支持浏览器自动化测试，Tidewave 会自动修改 CSP 策略（unsafe-eval），仅限开发环境。
4. Elixir/Phoenix 生态锁定：项目专为 Elixir 生态设计，不支持 Ruby/Rails、Python/Django 等其他框架。

---

行业意义：AI 原生开发工具的新范式

Tidewave 的出现反映了一个更大的趋势：AI 编程助手正在从代码补全工具进化为代码加运行时智能体。

传统的 AI 编程助手（如 GitHub Copilot）只能处理静态代码。而 Tidewave 代表的路线是：让 AI 接入真实的运行时环境，获得上下文感知能力。这条路线的成功，会让 AI 修改代码后直接报错的情况大幅减少。

目前，Tidewave 已经将这一能力成功带入了 Phoenix/Elixir 生态（Dashbit 团队背书），这对于 Elixir 社区的 AI 辅助开发具有标志性意义。

---

快速上手

# 1. 添加依赖
# 在 mix.exs deps 中添加 {:tidewave, "~> 0.6", only: :dev}

# 2. 安装依赖
mix deps.get

# 3. 配置 endpoint（见上文安装部分）

# 4. 启动应用
mix phx.server

# 5. 在 AI 工具中配置 MCP 连接
# http://localhost:4000/tidewave/mcp

Tidewave Phoenix 为 Phoenix 开发者打开了一扇通向 AI 原生开发的大门——让 AI 不再是门外汉，而是真正理解你代码的搭档。