tidewave-integration

Tidewave MCP 集成

通过 MCP 为 Phoenix 应用提供运行时洞察。条件允许时，优先使用 Tidewave 工具，而非 Bash。

不可违背的铁律

1. 仅限开发环境 — 绝不要在生产环境中使用 Tidewave 工具。避免在包含生产数据副本的共享开发服务器上使用。
2. 优先使用 TIDEWAVE，而非 BASH — mcp__tidewave__get_docs > web_fetch，execute_sql_query > psql
3. 先检查是否可用 — 只有存在相匹配的 mcp__tidewave__* 工具时，才调用 Tidewave
4. SQL 以读取为主 — 使用 execute_sql_query 执行 SELECT，谨慎进行数据修改
5. 版本必须精确 — get_docs 返回的是与你的 mix.lock 版本相对应的文档，而非最新文档

快速参考

任务	Tidewave 工具	后备方案
获取文档	mcp__tidewave__get_docs Module.func/3	web_fetch hexdocs.pm/...
运行代码	mcp__tidewave__project_eval	mix run -e "code"
SQL 查询	mcp__tidewave__execute_sql_query	psql $DATABASE_URL
查找源代码	mcp__tidewave__get_source_location	grep -rn "defmodule"
检查 DOM	mcp__Tidewave-Web__browser_eval	手动检查浏览器
列出架构	mcp__tidewave__get_ecto_schemas	阅读 lib/*/schemas/
读取日志	mcp__tidewave__get_logs level: :error	tail -f log/dev.log

检测

# Check endpoint
curl -s http://localhost:4000/tidewave/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"ping"}'

或者在 Claude Code 中使用 /mcp 查看已连接的服务。

核心模式

立即测试函数

# mcp__tidewave__project_eval
MyApp.Accounts.create_user(%{email: "[email protected]"})

验证迁移

-- mcp__tidewave__execute_sql_query
SELECT column_name, data_type FROM information_schema.columns
WHERE table_name = 'users';

调试 LiveView（使用从浏览器获取的 PID）

# mcp__tidewave__project_eval
pid = pid("0.1234.0")
:sys.get_state(pid) |> Map.get(:socket) |> Map.get(:assigns) |> Map.keys()

设置要求

# mix.exs
{:tidewave, "~> 0.6", only: :dev}

# endpoint.ex (in dev block)
plug Tidewave

# config/dev.exs (for LiveView source mapping)
config :phoenix_live_view,
  debug_heex_annotations: true,
  debug_attributes: true

该依赖项和端点 plug 会公开 Tidewave 的可流式 HTTP 服务，但不会将其注册到 MCP 客户端。请单独配置当前运行时，使用 http://localhost:<port>/tidewave/mcp，然后确认 Tidewave 工具可用，再依赖此技能。

可靠性防护

工作树／端口检查（多工作树环境下优先执行）：多个工作树 = 多个使用不同端口的开发服务器。在信任任何 Tidewave 结果之前，请确认端点属于本次检出的代码库：检查 config/dev.exs 中配置的端口，并通过 project_eval File.cwd!() 验证——如果返回的是不同的工作树路径，说明你正在调试错误的服务器。

先检查架构，再执行 SQL：绝不要猜列名。针对本会话中尚未检查过的表编写 SQL 前，先运行 get_ecto_schemas（或查询 information_schema.columns）。猜错列名导致的错误，比先检查架构代价更高。

输出大小防护：运行时输出没有上限。务必限制输出——SQL 使用 LIMIT 20，求值时使用 Enum.take(20)，大型结构体使用 inspect(x, limit: 50, printable_limit: 500)。应缩小范围重新查询，而不是倾倒大量数据。

browser_eval 后备方案：如果 mcp__Tidewave-Web__browser_eval 不存在或报错，不要停滞不前——在服务端检查相同状态：通过 project_eval 中的 :sys.get_state(pid) 查看 LiveView assigns，通过 Phoenix.LiveViewTest 查看渲染后的 HTML，或直接阅读模板源代码。

QA 演练模式：功能完成后，通过 project_eval／browser_eval 执行简短检查清单：创建记录、取回记录、触发主要事件，并确认 get_logs level: :error 没有错误。逐项报告通过／失败情况，而不只是说“冒烟测试通过”。

主动运行时检查

不要只在需要时才使用 Tidewave。请在工作流检查点自动查询运行时状态：

• 代码编辑后：运行 get_logs level: :error（捕获运行时崩溃）
• 功能完成后：运行 project_eval 冒烟测试（检查行为）
• 规划前：运行 get_ecto_schemas 和路由求值（了解具体上下文）
• 调查问题时：询问用户前自动捕获错误
• LiveView UI 问题：编辑组件前使用 browser_eval 检查 DOM 状态

完整集成点请参阅 ${CLAUDE_SKILL_DIR}/references/proactive-patterns.md。

参考资料

如需了解详细模式，请参阅：

• ${CLAUDE_SKILL_DIR}/references/proactive-patterns.md - 工作流检查点处的推送式运行时模式
• ${CLAUDE_SKILL_DIR}/references/tool-examples.md - 完整的工具使用示例
• ${CLAUDE_SKILL_DIR}/references/validation-checklist.md - 运行时验证模式