---
name: tidewave-integration
description: Tidewave MCP runtime tools — debugging, smoke testing, live state inspection,
  SQL queries, hex docs. Use when evaluating code in a running Phoenix app.
---

# 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

```bash
# 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

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

### Verify Migration

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

### Debug LiveView (with PID from browser)

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

## Setup Requirements

```elixir
# 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

**Query runtime state at workflow checkpoints** without waiting
to be asked:

- **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