Tidewave Rails

Tidewave Rails

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

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

• 在运行中的应用上下文中执行代码（就像供 Agent 使用的 Rails 控制台）
• 读取应用的实时日志
• 查询开发数据库
• 获取类和方法的源代码位置
• 阅读与你的应用所依赖的 gem 版本完全对应的文档

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

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

安装

1. 将 Tidewave gem 添加到你的应用

你可以运行以下命令，将 Tidewave Rails 添加到应用中：

bundle add tidewave --group development

也可以手动将 tidewave gem 添加到 Gemfile 的 development 组中：

gem "tidewave", group: :development

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

将 Tidewave MCP 服务添加到编辑器或 MCP 客户端配置中，类型设为“http”（可流式传输），并指向 /tidewave/mcp 路径以及 Web 应用正在使用的端口。例如，http://localhost:3000/tidewave/mcp。

我们还提供了以下工具的专门说明：

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

用法

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

可用的 MCP 工具

project_eval

在运行中的应用上下文内执行 Ruby 代码，可访问其运行时、已加载的依赖项和内存中的数据，并返回结果以及所有打印到标准输出的内容。这就像供 Agent 使用的 Rails 控制台。

当 Agent 想要运行代码而不是臆测行为时，可以使用此工具，让后续步骤以运行中应用的实际行为为依据。例如，调用某个方法查看返回结果，或针对实时应用状态重现失败的代码路径，以便调试。

execute_sql_query

对应用的开发数据库运行 SQL 查询，并将查询结果返回给 Agent。

Agent 可以使用此工具对开发数据库运行任意 SQL。例如，让它插入一些测试记录，看看页面在真实数据下的显示效果。或者，在执行创建操作后，让 Agent 验证记录是否已按预期值保存。

get_docs

查询类、方法或常量的文档，文档取自应用 Gemfile.lock 中锁定的确切 gem 版本。

当 Agent 不确定某个类或方法的工作方式时，可以使用此工具。这样，它生成的代码就能以与你的应用所用 gem 的确切版本相对应的文档为依据，而不是可能已经过时的训练数据，或无法保证与应用所依赖版本一致的通用文档查询结果。

get_source_location

返回类、模块或方法在文件中的定义位置和行号，涵盖应用及其依赖项。

Agent 可以使用它直接跳转到类或方法的定义位置（文件和行号），而不必用 grep 搜索；即使定义位于 gem 依赖项中也可以。

此外，由于它会从正在运行的应用中解析位置，而不是解析源文本，因此也能处理元编程场景：方法在运行时生成，grep 找不到字面的 def 定义。

说明

为什么没有用于路由、关联等的工具？

Tidewave 不提供列出路由、关联等内容的工具，因为 让 Agent 阅读相应的源文件效果更好，这能为 Agent 提供更多 上下文，并让它们无需额外调用工具即可进行必要的编辑。

相反，Tidewave 致力于弥补缺失的功能，例如在 Rails 应用内执行代码（无需启动新实例）以及查找源代码位置。由于元编程以及 Bundler 可能安装依赖项的不同位置，这些操作即使用 grep 也可能 很棘手。

故障排除

Tidewave 工具栏未显示

如果在 Tidewave 中间件运行后压缩了响应（gzip、brotli 等），就可能出现这种情况。使用 bin/rails middleware，确保 Tidewave 位于 Rack::Deflater 或类似中间件之后。还要查看浏览器和终端日志中是否有错误。

使用多个主机／子域名

如果开发期间使用多个主机／子域名，必须使用 *.localhost，因为浏览器会将此类域名视为安全域名。此外，将以下内容添加到 config/initializers/development.rb：

config.session_store :cookie_store,
  key: "__your_app_session",
  same_site: :none,
  secure: true,
  assume_ssl: true

并确保使用 rack-session 版本 2.1.0 或更高版本。

只要使用安全上下文（例如 admin.localhost、www.foobar.localhost 等），上述配置就能让应用在多个子域名下嵌入 Tidewave 运行。

内容安全策略

如果启用了 Content-Security-Policy，Tidewave 会自动在 script-src 中启用 "unsafe-eval"，以确保上下文浏览器测试正常运行。它还会禁用 frame-ancestors 指令。这只会在加载了 Tidewave 的环境中执行（默认是 development）。

生产环境

Tidewave 是一款强大的工具，可帮助你更快、更高效地开发 Web 应用。不过请注意，Tidewave 并非为生产环境设计。

如果在禁用了代码重载的环境中使用 Tidewave（通常包括生产环境），它会报错。

配置

你可以使用以下语法配置 tidewave：

  config.tidewave.team = { id: "my-company" }

可用的配置项如下：

• allow_remote_access - 出于安全考虑，Tidewave 默认只允许来自 localhost 的请求，即使你的服务监听其他网络接口也是如此。请阅读我们的安全指南，了解更多信息以及何时允许远程访问（前提是你清楚自己在做什么）。

• logger_middleware - Tidewave 应当包装哪个 logger 中间件，以便屏蔽自身日志

• preferred_orm - 使用哪个 ORM，可以是 :active_record（默认）或 :sequel

• team - 设置 Tidewave Team 配置，例如 config.tidewave.team = { id: "my-company" }

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

致谢

感谢 Yorick Jacquin 提供本项目的初始版本。

开发

使用以下命令运行 Minitest 测试套件：

bundle exec ruby -Itest test/all_test.rb

许可证

版权所有（c）2025 Dashbit

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

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