Tidewave Phoenix

Tidewave Phoenix

Tidewave Phoenix 是一个 MCP 服务，为编码 Agent 开发 Phoenix 应用提供运行时级别的工具。

你的 Agent 可以使用此 MCP 服务与正在开发环境中运行的 Phoenix 应用交互，以便：

• 在运行中的应用上下文中执行代码（就像供 Agent 使用的 IEx 会话）
• 读取应用的实时日志
• 查询开发数据库
• 获取模块和函数的源代码位置
• 阅读与你的项目所依赖的 hex 包版本精确匹配的文档

此 MCP 服务是 Tidewave 的开源组件。Tidewave 是面向 Phoenix 和 Rails 的 Agent 开发环境。

你可以将此项目用作独立的 MCP 服务，也可以按照下方的安装说明，将其集成到 Tidewave 产品中。

安装

1. 将 Tidewave hex 包添加到应用中

选项 1：手动安装

将 tidewave 包添加到你的 mix.exs 中：

def deps do
  [
    {:tidewave, "~> 0.9", only: :dev},
    {:phoenix, ...},
  ]
end

然后，对于 Phoenix 应用，打开 lib/my_app_web/endpoint.ex，并在 if code_reloading? do 代码块正上方添加：

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

   if code_reloading? do

提示

Tidewave 与 Phoenix LiveView v1.1 或更高版本配合效果最佳。升级后， 请确保在你的 config/dev.exs 中启用以下选项：

config :phoenix_live_view,
  debug_heex_annotations: true,
  debug_attributes: true

对于 Phoenix v1.8+ 应用，这些选项默认已启用。

选项 2：使用 Igniter

或者，你可以使用 igniter 将 Tidewave MCP 自动安装到现有的 Phoenix 应用中：

# install igniter_new if you haven't already
mix archive.install hex igniter_new

# install tidewave
mix igniter.install tidewave

Umbrella 项目

对于 Umbrella 项目，你可以在定义 Phoenix endpoint 的应用中按照上述手动步骤操作（通常是 apps/your_app_web）。

2. 将 Tidewave MCP 添加到你的 Agent/编辑器中

将 Tidewave MCP 服务添加到编辑器或 MCP 客户端配置中，类型设为 "http"（streamable），并指向 Web 应用运行所在的端口和 /tidewave/mcp 路径。例如，http://localhost:4000/tidewave/mcp。

我们还提供了以下工具的具体配置说明：

• Claude Code
• Codex
• Cursor
• Neovim
• OpenCode
• VS Code
• 其他

提示

如果你使用 worktree，很可能会在不同端口上运行 Web 服务器， 因此无法使用同一组主机和端口。

在这种情况下，你可以改用 STDIO MCP 添加 mix tidewave.proxy， 它会为所有工具定义添加一个 "port" 参数，并负责将请求分发到正确的应用。

用法

与其他 MCP 服务一样，你的 Agent 会在认为合适时调用 Tidewave MCP 提供的工具。你也可以提示它显式调用这些工具。

可用的 MCP 工具

project_eval

在运行中的应用内执行 Elixir 代码，让 Agent 能访问运行时、依赖项和内存中的数据。这就像供 Agent 使用的 IEx。

当 Agent 更适合通过运行代码而不是假设行为来解决问题时，它可以使用此工具，以运行中的应用的实际行为作为下一步操作的依据。例如，调用函数查看返回结果，或针对实时应用状态重现失败的代码路径以进行调试。

execute_sql_query

在应用的开发数据库中执行 SQL 查询。

Agent 可以使用此工具对开发数据库运行任意 SQL，验证操作结果时尤其有用。

get_docs

获取给定模块/函数的文档。它会查阅项目 mix.lock 中锁定的确切版本，确保提供的信息准确。

get_logs

读取服务写入的日志。

你的 Agent 可以用它查看请求之后发生了什么。例如，出现异常时读取请求日志和回溯信息。

get_source_location

获取给定模块/函数在应用及其依赖项中的源代码位置。

你的 Agent 可以用它直接跳转到模块/函数的定义位置（包括文件和行号），而不必搜索代码；即使定义位于 hex 依赖项中也可以。

故障排除

使用多个主机/子域名

如果你在开发期间使用多个主机/子域名，则必须使用 *.localhost，因为浏览器会将此类域名视为安全域名。此外，请在 lib/your_app_web/endpoint.ex 中的 @session_options 定义之后立即添加以下内容：

@session_options [
  # ... your configuration
]

if code_reloading? do
  @session_options Keyword.merge(@session_options, same_site: "None", secure: true)
end

只要使用安全上下文（例如 admin.localhost、www.foobar.localhost 等），以上设置就能让你的应用通过多个子域名嵌入 Tidewave 中运行。

内容安全策略

如果你启用了 Content-Security-Policy，Tidewave 会自动在 script-src 下启用 "unsafe-eval"，以确保上下文浏览器测试正常运行。同时，它也会禁用 frame-ancestors 指令。此设置仅会应用于已加载 Tidewave 的环境（默认情况下为开发环境）。

配置

你可以使用以下语法配置 Tidewave 插件：

  plug Tidewave, options

可用选项如下：

• :allow_remote_access - 出于安全考虑，Tidewave 默认只允许来自 localhost 的请求，即使你的服务正在其他网络接口上监听也一样。请阅读我们的安全指南，了解详情以及何时允许远程访问。请谨慎使用此选项；启用后，请确保在应用前配置身份验证代理。

• :allowed_origins - 用于与 Origin 和 Host 请求头进行匹配的值列表，可防止跨源攻击和 DNS 重绑定攻击。每个值都必须是 [scheme:]//host[:port] 格式的字符串，其中 scheme 和 port 均为可选项。host 也可以以 "*" 开头。只有 host 会与 Host 请求头进行比较。IP 地址、localhost 和 *.localhost 始终会被允许作为主机。如果未设置，则默认为 Phoenix 端点 URL 的主机。例如：["//localhost:8000", "//*.test"]

• :inspect_opts - 调用 Kernel.inspect/2 格式化部分工具结果时传入的自定义选项。默认为：[charlists: :as_lists, limit: 50, pretty: true]

• :team - 设置 Tidewave Team 配置，例如 team: [id: "my-company"]

• :toolbar - 控制是否将 Tidewave 工具栏注入 HTML 页面。默认为 true

• tmp_dir - Tidewave 用于存放截图和录制内容的临时目录。必须是相对于当前应用根目录的目录。默认为 tmp，文件存放在 tmp/tidewave/screenshots 和 tmp/tidewave/recordings 下

许可证

版权所有（c）2025 Dashbit

本项目采用 Apache License 2.0 版（以下简称“许可证”）授权； 除非遵守许可证，否则不得使用此文件。 你可以通过 http://www.apache.org/licenses/LICENSE-2.0 获取许可证副本。

除非适用法律要求或书面同意，否则根据许可证分发的软件均按“原样”提供， 不附带任何明示或暗示的保证或条件。 有关许可证规定的权限和限制，请参阅许可证。