tidewave-integration
Tidewave MCP runtime tools — debugging, smoke testing, live state inspection, SQL queries, hex docs. Use when evaluating code in a running Phoenix app.
Install
npx skills add https://github.com/oliver-kriska/claude-elixir-phoenix/tree/main/plugins/elixir-phoenix/skills/tidewave-integration
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install oliver-kriska-claude-elixir-phoenix@llmmart
git clone https://github.com/oliver-kriska/claude-elixir-phoenix.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole oliver-kriska/claude-elixir-phoenix collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Tidewave MCP Integration
Runtime intelligence for Phoenix apps via MCP. Prefer Tidewave tools over Bash when available.
Iron Laws — Never Violate These
- DEV ONLY — Never use Tidewave tools in production contexts. Avoid on shared dev servers with production data copies
- PREFER TIDEWAVE OVER BASH —
mcp__tidewave__get_docs>web_fetch,execute_sql_query>psql - CHECK AVAILABILITY FIRST — Call Tidewave only when matching
mcp__tidewave__*tools are present - SQL IS READ-HEAVY — Use
execute_sql_queryfor SELECT, be careful with mutations - EXACT VERSIONS —
get_docsreturns 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
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_evalsmoke test (behavioral check) - Before planning:
get_ecto_schemas+ routes eval (concrete context) - When investigating: Auto-capture errors before asking user
- LiveView UI bugs:
browser_evalto inspect DOM state before editing components
See ${CLAUDE_SKILL_DIR}/references/proactive-patterns.md for full integration points.
References
For detailed patterns, see:
${CLAUDE_SKILL_DIR}/references/proactive-patterns.md- Push-like runtime patterns at workflow checkpoints${CLAUDE_SKILL_DIR}/references/tool-examples.md- Complete tool usage examples${CLAUDE_SKILL_DIR}/references/validation-checklist.md- Runtime validation patterns
Files (claude-elixir-phoenix)
-
references
-
proactive-patterns.md 3.8 KB
Loading… -
tool-examples.md 3.9 KB
Loading… -
validation-checklist.md 3.4 KB
Loading…
-
-
SKILL.md 5.1 KB
--- 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." effort: low user-invocable: false --- # 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 `${CLAUDE_SKILL_DIR}/references/proactive-patterns.md` for full integration points. ## References For detailed patterns, see: - `${CLAUDE_SKILL_DIR}/references/proactive-patterns.md` - Push-like runtime patterns at workflow checkpoints - `${CLAUDE_SKILL_DIR}/references/tool-examples.md` - Complete tool usage examples - `${CLAUDE_SKILL_DIR}/references/validation-checklist.md` - Runtime validation patterns
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.