tidewave-integration

Tidewave MCP Integration

Runtime intelligence for Phoenix apps via MCP. Prefer Tidewave tools over Bash when available.

Iron Laws — Never Violate These

1. DEV ONLY — Never use Tidewave tools in production contexts. Avoid on shared dev servers with production data copies
2. PREFER TIDEWAVE OVER BASH — mcp__tidewave__get_docs > web_fetch, execute_sql_query > psql
3. CHECK AVAILABILITY FIRST — Call Tidewave only when matching mcp__tidewave__* tools are present
4. SQL IS READ-HEAVY — Use execute_sql_query for SELECT, be careful with mutations
5. EXACT VERSIONS — get_docs returns docs for YOUR mix.lock versions, not latest

Quick Reference

| Task | Tidewave Tool | Fallback |

|------|---------------|----------|

| Get docs | mcp__tidewave__get_docs Module.func/3 | web_fetch hexdocs.pm/... |

| Run code | mcp__tidewave__project_eval | mix run -e "code" |

| SQL query | mcp__tidewave__execute_sql_query | psql $DATABASE_URL |

| Find source | mcp__tidewave__get_source_location | grep -rn "defmodule" |

| Inspect DOM | mcp__Tidewave-Web__browser_eval | Manual browser inspection |

| List schemas | mcp__tidewave__get_ecto_schemas | Read lib/*/schemas/ |

| Read logs | mcp__tidewave__get_logs level: :error | tail -f log/dev.log |

Detection

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

Or use /mcp in Claude Code to see connected servers.

Essential Patterns

Test Function Immediately

# mcp__tidewave__project_eval
MyApp.Accounts.create_user(%{email: "test@example.com"})

Verify Migration

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

Debug LiveView (with PID from browser)

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

Setup Requirements

# 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

The dependency and endpoint plug expose Tidewave's streamable HTTP server; they

do not register it with an MCP client. Configure the current runtime separately

with http://localhost:<port>/tidewave/mcp, then verify that Tidewave tools are

available before relying on this skill.

Reliability Guards

Worktree/port check (FIRST, in multi-worktree setups): multiple

worktrees = multiple dev servers on different ports. Before trusting any

Tidewave result, confirm the endpoint belongs to THIS checkout: grep

config/dev.exs for the configured port, and verify with

project_eval File.cwd!() — if it returns a different worktree path,

you're debugging the wrong server.

Schema introspection BEFORE SQL: never guess column names. Run

get_ecto_schemas (or query information_schema.columns) before writing

SQL against a table you haven't already introspected this session. A

guessed-column error costs more than the introspection.

Output-size guard: runtime output is unbounded. Always cap it —

LIMIT 20 in SQL, Enum.take(20) in evals, `inspect(x, limit: 50,

printable_limit: 500)` for large structs. Re-query narrower rather than

dumping wide.

browser_eval fallback: if mcp__Tidewave-Web__browser_eval is absent

or errors, don't stall — inspect the same state server-side: LiveView

assigns via :sys.get_state(pid) in project_eval, rendered HTML via

Phoenix.LiveViewTest, or read the template source directly.

QA walkthrough pattern: after a feature completes, run a short

checklist through project_eval/browser_eval: create the record, fetch

it back, exercise the main event, check get_logs level: :error is clean.

Report each step's pass/fail — not just "smoke test passed".

Proactive Runtime Checks

Don't just use Tidewave reactively. **Query runtime state at

workflow checkpoints** automatically:

• After code edits: get_logs level: :error (catch runtime crashes)
• After features complete: project_eval smoke test (behavioral check)
• Before planning: get_ecto_schemas + routes eval (concrete context)
• When investigating: Auto-capture errors before asking user
• LiveView UI bugs: browser_eval to inspect DOM state before editing components

See references/proactive-patterns.md for full integration points.

References

For detailed patterns, see:

• references/proactive-patterns.md - Push-like runtime patterns at workflow checkpoints
• references/tool-examples.md - Complete tool usage examples
• references/validation-checklist.md - Runtime validation patterns