tidewave-ai/tidewave_phoenix

Tidewave Phoenix – an MCP server that lets AI coding agents talk to a running Phoenix app

What it is

An open‑source MCP (Machine‑Code‑Protocol) server written in Elixir that plugs into a Phoenix web application.
It exposes a handful of remote‑procedure‑call style tools that an AI‑powered coding assistant (Claude, Codex, Cursor, etc.) can invoke while the app is running in development.

Why it matters

Modern AI‑assisted development tools need a way to inspect and act on a live codebase – run code, read logs, query the DB, fetch docs, locate source files, etc. Tidewave Phoenix provides that bridge for the Phoenix (and, via the broader Tidewave product, Rails) ecosystem.
By treating the running Phoenix server as an interactive REPL that an LLM can call, developers can get more precise, context‑aware suggestions and automated debugging without leaving their editor.

Core capabilities (the “MCP tools”)

Tool	What it does	Typical AI‑agent use case
`project_eval`	Executes arbitrary Elixir code inside the live app (like an IEx session).	Verify a function’s output, reproduce a failing request, explore in‑memory state.
`execute_sql_query`	Runs a raw SQL statement against the development database.	Check the result of a mutation, inspect data after a request, generate test fixtures.
`get_docs`	Returns the documentation for a module/function from the exact hex version locked in `mix.lock`.	Provide accurate doc snippets to the developer, avoid stale or mismatched docs.
`get_logs`	Streams the server’s log output.	Diagnose why a request failed, surface back‑traces, monitor side‑effects.
`get_source_location`	Gives the file path and line number where a module/function is defined, even inside dependencies.	Jump straight to the implementation, help the agent suggest precise code edits.

How to add it to a Phoenix project

Add the tidewave hex package (dev only) to mix.exs.
Plug it into the endpoint – wrap the plug in a if Mix.env() == :dev guard so it only runs during development.
(Optional) Enable LiveView debug flags for richer context (debug_heex_annotations, debug_attributes).
Configure the MCP client in your editor/agent to point at http://localhost:4000/tidewave/mcp (or the appropriate host/port).
For rapid setup you can also use the igniter archive: mix igniter.install tidewave.

Configuration knobs you may need

:allow_remote_access – disables the default localhost‑only restriction (use with care).
:allowed_origins – whitelist origins to protect against DNS‑rebinding attacks.
:toolbar – injects a small UI toolbar into HTML pages (useful for manual debugging).
:tmp_dir – where screenshots/recordings are stored if you use those extra features.

Typical workflow

Start your Phoenix app in development.
Run an AI‑assistant (e.g., Claude Code, Cursor, VS Code extension) that is configured to use the Tidewave MCP endpoint.
The assistant calls a tool (e.g., project_eval) when it needs concrete information.
The MCP server executes the request inside the running app and returns the result.
The assistant uses the result to generate a suggestion, a patch, or a follow‑up query.

Who would use this?

Phoenix developers who want AI‑driven code completion, automated debugging, or documentation lookup that is aware of the exact runtime state.
Tool builders creating LLM‑based IDE extensions for Elixir/Phoenix; they can plug into the MCP instead of building a custom REPL bridge.
Teams using the broader Tidewave platform who need the same agentic capabilities for Rails apps (the same MCP concept applies there).

License

Apache 2.0 – free for commercial and non‑commercial use, with the usual disclaimer of warranty.

TL;DR

Tidewave Phoenix is a lightweight Elixir plug that turns a running Phoenix server into a remote, streamable API for AI coding agents. It lets those agents evaluate code, run SQL, fetch docs, read logs, and locate source files, enabling much tighter, context‑aware assistance during development.