Tidewave Phoenix

Tidewave Phoenix

Tidewave Phoenix は、コーディングエージェントを使った Phoenix アプリの開発向けに、ランタイムレベルのツールを提供する MCP サーバーです。

エージェントはこの MCP サーバーを使って、開発環境で実行中の Phoenix アプリと通信し、次のことができます。

• 実行中のアプリのコンテキストでコードを実行する（エージェント向けの IEx セッションのようなものです）
• アプリのライブログを読む
• 開発データベースにクエリを実行する
• モジュールや関数のソースコードの場所を取得する
• プロジェクトが依存する正確な hex パッケージのバージョンに対応したドキュメントを読む

この MCP サーバーは、Phoenix と Rails 向けのエージェント型開発環境である Tidewave のオープンソースコンポーネントです。

このプロジェクトは単体の MCP サーバーとしても、以下のインストール手順に従って Tidewave product と統合しても利用できます。

インストール

1. Tidewave hex パッケージをアプリに追加する

オプション 1：手動で追加する

mix.exs に tidewave パッケージを追加します。

def deps do
  [
    {:tidewave, "~> 0.9", only: :dev},
    {:phoenix, ...},
  ]
end

次に、Phoenix アプリケーションの場合は lib/my_app_web/endpoint.ex を開き、if code_reloading? do ブロックのすぐ上に追加します。

+  if Mix.env() == :dev do
+    plug Tidewave
+  end

   if code_reloading? do

ヒント

Tidewave は Phoenix LiveView v1.1 以降で最もよく動作します。更新したら、 config/dev.exs で次のオプションを有効にしてください。

config :phoenix_live_view,
  debug_heex_annotations: true,
  debug_attributes: true

これらは Phoenix v1.8 以降のアプリではデフォルトで有効になっています。

オプション 2：Igniter を使用する

または、igniter を使って、既存の Phoenix アプリケーションに Tidewave MCP を自動的にインストールできます。

# install igniter_new if you haven't already
mix archive.install hex igniter_new

# install tidewave
mix igniter.install tidewave

Umbrella プロジェクト

Umbrella プロジェクトの場合は、Phoenix エンドポイントを定義しているアプリケーション（通常は apps/your_app_web）で、上記の手順を手動で実行してください。

2. エージェント／エディターに Tidewave MCP を追加する

Tidewave MCP サーバーを、エディターまたは MCP クライアントの設定に「http」（ストリーマブル）タイプとして追加し、Web アプリケーションが実行されているポートの /tidewave/mcp パスを指定します。例：http://localhost:4000/tidewave/mcp。

以下のツールについては、個別の手順も用意しています。

• Claude Code
• Codex
• Cursor
• Neovim
• OpenCode
• VS Code
• その他

ヒント

worktree を使用している場合、Web サーバーを異なるポートで実行している可能性が高いため、 共通して使えるホストとポートの組み合わせはありません。

その場合は、代わりに mix tidewave.proxy を STDIO MCP として追加するとよいでしょう。 これによりすべてのツール定義に「port」パラメーターが追加され、 正しいアプリケーションへのディスパッチが行われます。

使用方法

他の MCP サーバーと同様に、エージェントは必要に応じて Tidewave MCP が公開するツールを呼び出します。明示的に呼び出すようプロンプトで指示することもできます。

利用可能な MCP ツール

project_eval

実行中のアプリケーション内で Elixir コードを評価し、エージェントがランタイム、依存関係、メモリ内データにアクセスできるようにします。エージェント向けの IEx のようなものです。

エージェントは、動作を推測するよりもコードを実行したい場合に、このツールを使用できます。実行中のアプリが実際にどのように動作するかを確認して、次の手順の根拠にできます。たとえば、関数を呼び出して結果を確認したり、実行中のアプリの状態に対して失敗するコードパスを再現してデバッグしたりできます。

execute_sql_query

アプリの開発データベース内で SQL クエリを実行します。

エージェントは、開発データベースに対して任意の SQL を実行できます。エージェントがアクションの結果を検証する際に役立ちます。

get_docs

指定したモジュール／関数のドキュメントを取得します。プロジェクトの mix.lock に固定された正確なバージョンを参照するため、正確な情報を取得できます。

get_logs

サーバーが書き込んだログを読み取ります。

エージェントはこれを使って、リクエスト後に何が起きたかを確認できます。たとえば、問題が発生したときに、リクエストログやバックトレースを読み取れます。

get_source_location

アプリとその依存関係の両方を対象に、指定したモジュール／関数のソース位置を取得します。

エージェントはこれを使って、grep で検索する代わりに、ファイルと行番号をもとにモジュール／関数の定義場所へ直接移動できます。定義が hex の依存関係にある場合も同様です。

トラブルシューティング

複数のホスト／サブドメインを使用する

開発中に複数のホスト／サブドメインを使用する場合は、ブラウザーでセキュアと見なされる *.localhost を使用する必要があります。また、lib/your_app_web/endpoint.ex の @session_options 定義の直後に、次の内容を追加してください。

@session_options [
  # ... your configuration
]

if code_reloading? do
  @session_options Keyword.merge(@session_options, same_site: "None", secure: true)
end

これにより、セキュアなコンテキスト（admin.localhost や www.foobar.localhost など）を使用している限り、アプリケーションを複数のサブドメインにわたって Tidewave 内に埋め込んで実行できます。

コンテンツセキュリティポリシー

Content-Security-Policy を有効にしている場合、コンテキストに応じたブラウザーテストが正しく機能するように、Tidewave は script-src の「unsafe-eval」を自動的に有効にします。また、frame-ancestors ディレクティブも無効にします。この設定は、Tidewave が読み込まれる環境（デフォルトでは開発環境）でのみ適用されます。

設定

次の構文を使って Tidewave プラグを設定できます。

  plug Tidewave, options

使用できるオプションは次のとおりです。

• :allow_remote_access - セキュリティ上の理由から、サーバーがほかのインターフェースで待ち受けている場合でも、Tidewave はデフォルトで localhost からのリクエストのみを許可します。詳細とリモートアクセスを許可する条件については、セキュリティガイドラインをご覧ください。このオプションは十分に注意して使用し、有効にした場合は、アプリの前段に認証プロキシを必ず配置してください。

• :allowed_origins - クロスオリジン攻撃や DNS リバインディング攻撃を防ぐため、Origin ヘッダーと Host ヘッダーに照合する値のリストです。各値は [scheme:]//host[:port] 形式の文字列で、scheme と port はどちらも省略できます。host の先頭には「*」を付けることもできます。Host ヘッダーとの照合対象は host のみです。IP アドレス、localhost、*.localhost は、常にホストとして許可されます。設定されていない場合は、Phoenix エンドポイント URL のホストがデフォルト値になります。例：["//localhost:8000", "//*.test"]

• :inspect_opts - 一部のツールの結果を整形する際に Kernel.inspect/2 に渡すカスタムオプションです。デフォルト値：[charlists: :as_lists, limit: 50, pretty: true]

• :team - team: [id: "my-company"] のように、Tidewave Team の設定を指定します。

• :toolbar - HTML ページに Tidewave ツールバーを挿入するかどうかを制御します。デフォルトは true です。

• tmp_dir - Tidewave がスクリーンショットや録画に使用する一時ディレクトリです。現在のアプリケーションのルートからの相対パスで指定する必要があります。デフォルトは tmp で、ファイルは tmp/tidewave/screenshots と tmp/tidewave/recordings に保存されます。

ライセンス

Copyright (c) 2025 Dashbit

このファイルは、Apache License, Version 2.0（以下「ライセンス」）に基づいてライセンスされています。 ライセンスに従わない限り、このファイルを使用することはできません。 ライセンスのコピーは、http://www.apache.org/licenses/LICENSE-2.0 から入手できます。

適用される法律で要求される場合、または書面で合意されている場合を除き、 ライセンスに基づいて配布されるソフトウェアは、「現状のまま」で提供され、 明示的か黙示的かを問わず、いかなる保証も条件もありません。 ライセンスに基づく権利および制限については、ライセンスをご確認ください。