serverpod-overview

Serverpod の概要

Serverpod は、Dart で記述された Flutter 向けのオープンソースバックエンドフレームワークです。Serverpod プロジェクトは通常、次の 3 つのパッケージで構成されます。

my_project_server - サーバーコードです。 my_project_client - 生成されたクライアントコードです。 my_project_flutter - Flutter アプリ（クライアントをインポートします）です。

コードを共有するパッケージ（例：my_project_shared）が含まれることもあります。

サーバーは lib/server.dart から起動します。このファイルでは、final pod = Serverpod(args); によって src/generated/serverpod.dart の生成済み Serverpod クラス（プロジェクトのプロトコルとエンドポイントがあらかじめ組み込まれています）を作成し、続いて await pod.start(); を実行します。

サーバーはエンドポイントクラスを公開し、クライアントは生成された RPC クライアントを介してこれを呼び出します。エンドポイントにメソッドを追加すると、コード生成によってクライアント側にも反映されます。モデルは YAML で定義し、サーバーとクライアントの両方で使用する Dart クラスを生成します。

Serverpod プロジェクトでは、永続化に PostgreSQL データベースを使用します（SQLite もサポートされています）。また、ORM、キャッシュ、リアルタイムストリーミング（Dart ストリームを使用）、ファイルアップロード、スケジューリング（future calls と呼ばれます）、ロギング、組み込みウェブサーバー（Relic）が備わっています。

これらの機能分野には、それぞれ専用の serverpod-* スキルがあります。タスクに合ったものを使用してください。Insights コンパニオンアプリはスキルの対象外で、https://docs.serverpod.dev にドキュメントがあります。

サーバーの実行

開発スタックは Serverpod ランナーによって実行されます。サーバーパッケージごとに、バックグラウンドプロセスが 1 つ起動します。コードを生成し、ホットリロードに対応した状態でサーバーをコンパイルし、コンパニオン Flutter アプリを起動して、serverpod MCP を提供します。実行中はファイルの変更を監視し、インクリメンタルなコード生成と、サーバーのホットリロード（プロジェクトに Flutter アプリがある場合はそのアプリも）を行います。

• serverpod start はランナーが実行中であることを確認し、実行中でなければ起動して接続します。ターミナルでは対話型のターミナル UI を表示し、それ以外の場合、または --no-tui を指定した場合は、プレーンなログストリームを表示します。ユーザーが終了するまで処理をブロックします。ランナーを起動した start を終了するとランナーも停止しますが、すでに実行中のランナーに接続した start を終了しても、ランナーは実行を続けます。ユーザーが実行するのはこのコマンドです。serverpod start --no-attach は serverpod runner start と同じ動作をします。
• serverpod runner start は同じ方法でランナーが実行中であることを確認し、アドレスを表示して終了します。ランナーはバックグラウンドで実行を続けます。これがランナーの起動に使うコマンドです。初回起動ではプロジェクト全体をコンパイルするため、数分かかることがあります。auto_launch が設定されたコンパニオン Flutter アプリは、UI が接続されると起動します。それより前にアプリを起動するには、MCP ツール spawn_flutter_app を使用してください。
• serverpod runner attach は serverpod start と同じように、すでに実行中のランナーに UI を接続します。ランナーを起動することはありません。終了してもランナーは実行を続けます。
• serverpod runner status は、ランナーが起動中、実行中、停止中、またはビルドに失敗したプロジェクトを伴って起動しているかどうかを表示します。また、API、Insights、ウェブの URL とログのパスも表示します。
• serverpod runner stop はランナーを停止します。

どのコマンドも、現在のディレクトリからサーバーパッケージを特定します。または、--directory <server package>（-d）を指定できます。

操作を行う前に、サーバーが実行中かどうかを確認しないでください。変更を加え、serverpod MCP ツールを呼び出してください。何も実行されていない場合、MCP は「the server is not running」という明示的なエラーを返します。その場合は、次の手順に従ってください。

1. tail_runner_logs を呼び出し、ランナーがまだ起動中か、または停止した理由を確認します。
2. 実行中のランナーがない場合は、サーバーパッケージ内で serverpod runner start を実行します。サーバーが起動すると、終了コード 0 を返します。プロジェクトをビルドできない場合（ランナーは起動したままで、デフォルトの watch が有効な状態では、変更によってビルド可能になるとサーバーを起動します）、設定されたポートが Serverpod ランナー以外のものに使用されている場合、または Docker が起動を拒否した場合は、0 以外の終了コードを返します。原因を修正し、再試行しないでください。例外は、シェルがタイムアウトで終了し、serverpod runner start の実行結果が返る前にコマンドを強制終了した場合です。この場合、ランナーはバックグラウンドで起動を続けるため、コマンドを再度実行すると起動を待機します。
3. MCP ツールをもう一度呼び出します。MCP は自動的に再接続します。 作業が完了してもランナーは起動したままにしてください。ユーザーは serverpod start でランナーに接続します。指示があった場合にのみ serverpod runner stop を実行してください。--watch、--target、--flutter、--docker、または起動中のランナーとは異なるサーバー引数を指定してスタックを起動すると失敗し、相違点が表示されます。その場合は、まずランナーを停止してください。

以下のタスクでは、必ずコマンドラインではなく MCP サーバーを使用してください。例外は、スタック自体を管理する serverpod runner コマンドです。起動中のランナーでは、次の操作ができます。

• データベース用の create_migration と apply_migrations（データモデルを変更した後に使用します）。
• データベースとマイグレーションの同期がずれた場合の create_repair_migration。修復ファイルを書き込むだけなので、その後に apply_migrations を実行してください。
• サーバーのログを読み取る tail_server_logs。
• ランナー自体の出力（コード生成、コンパイル、Docker、サーバーの生出力）を読み取る tail_runner_logs。サーバーの起動中や停止後にも使用できる唯一のツールです。
• Flutter アプリの標準出力／標準エラーの生出力を読み取る tail_flutter_logs。
• インメモリ状態を保持したまま、サーバーと Flutter アプリを再読み込みする hot_reload。--no-watch の場合のみ必要です。通常、ランナーはファイルの変更時に再読み込みします。
• サーバーと Flutter アプリを再起動し、インメモリ状態を破棄する hot_restart。自動適用される通常のホットリロードでは反映されない可能性がある Flutter アプリの変更を行った後は、必ず呼び出してください。
• サーバーの pubspec.yaml にある serverpod: flutter_apps: の下で宣言された Flutter アプリを起動する spawn_flutter_app。
• 起動中の Flutter アプリの Dart Tooling Daemon URI を取得する get_flutter_app_dtd。アプリを操作するには、この URI を dart MCP に渡してください。

Flutter アプリを対象とするツールでは、appId を省略できます。これは serverpod: flutter_apps: の下にあるマップキーです。プロジェクトで複数のアプリが宣言されている場合にのみ必須です。

複数のサーバーを同時に実行する

各サーバーパッケージには、パッケージディレクトリをキーとするランナーがちょうど1つあります。マニフェスト、ロックファイル、ログ、ソケットは <server package>/.dart_tool/serverpod/ に置かれ、各ランナーは ~/.serverpod/runners/ に自身を登録します。そのため、複数のサーバーパッケージがあるワークスペースや、同じプロジェクトの複数のチェックアウトまたはワークツリーでは、それぞれが独自のランナーを実行します。それぞれを serverpod runner start --directory <server package> で起動します。MCP ブリッジは1つのサーバーパッケージを提供するため、エージェントの設定にはサーバーごとに serverpod mcp-server --server-dir <server package> のエントリが必要です。ブリッジが提供するのは、現在いるディレクトリではなく、--server-dir で指定したパッケージです。また、そのパッケージを指示やエラーで示します。別のチェックアウトまたはワークツリーからマイグレーションを適用したり再起動したりする前に、これを確認してください。

通常、パッケージは同じポート（8080、8081、8082）を指定した config/development.yaml を共有します。最初のランナーがそれらのポートをバインドします。別のランナーが使用中だと検知した場合、そのランナーはすべてのリスナーをまとめてエフェメラルポートに移し、それらのポートが空いている限り、再起動後も同じポートを使い続けます。localhost:8080 を前提にしないでください。serverpod runner status または serverpod runner start の出力に表示されたアドレスを確認してください。ランナーが起動する Flutter アプリには、--dart-define=SERVER_URL=... を通じて正しい URL が渡されます。手動で起動したアプリ、ブラウザーのタブ、curl では、status に表示されたアドレスを使用してください。

dart run bin/main.dart で手動起動したサーバーなど、Serverpod ランナー以外のプロセスが設定済みポートを使用している場合はエラーになります。そのプロセスを停止するか、config/development.yaml のポートを変更してください。

埋め込み PostgreSQL（database.dataPath）はチェックアウトごとに個別です。Unix ソケットと、実行モードでデータベースパスワードが設定されている場合はループバック TCP の database.port でリッスンします。このポートは4つ目のリスナーです。サーバーポートとともに移動し、データベースのアドレスは status に表示されます。このチェックアウトですでに serverpod database start によって起動しているデータベースは、移動せずに接続されます。ホストポートを共有するのは Docker Compose データベースを使用するプロジェクトだけです。Compose プロジェクト名はサーバーディレクトリ名に基づくため、そのようなプロジェクトの2つのチェックアウトは、同じコンテナー群を共有します。この共有 Compose スタックを使うチェックアウトを起動するのは、他のチェックアウトが使用していない場合に限ってください。それ以外の場合は、既存のスタックを起動したままにし、ユーザーからチェックアウトを切り替えるよう明示的に依頼されない限り、このチェックアウトのランナーを起動しないでください。

実行中のインスタンスがない状態でプロジェクトを操作する

• MCP が利用可能な間は、serverpod generate または serverpod create-migration を絶対に実行しないでください。ランナーは保存時にコードを生成し、MCP はマイグレーションを作成します。serverpod runner コマンドはスタック自体を管理するため、常に実行できます。
• MCP が利用できない場合、または serverpod runner start でサーバーを起動できなかった場合に限り、serverpod generate を呼び出してコードを生成してください。
• 生成されたコードは次の生成時に上書きされるため、絶対に編集しないでください。ただし、作成済みマイグレーションの SQL は編集できます。詳細は Serverpod Migrations スキルを参照してください。

コードを生成した後、serverpod create-migration を呼び出してデータベースマイグレーションを作成できます。MCP を使用できない場合に限り使用してください。

# Use `--force` to create migrations with destructive changes
# Use the `--tag` flag to name the migration
serverpod create-migration [--force] [--tag <tag>]

詳細は Serverpod Migrations スキルを参照してください。

変更後のチェックリスト：

1. dart analyze（CLI または dart MCP サーバー）
2. dart format（CLI または dart MCP サーバー）
3. 必要に応じて serverpod MCP の hot_restart を実行します（ホットリロードは自動的に行われます）。Flutter アプリもホットリスタートされます。
4. serverpod MCP の tail_server_logs（Flutter アプリの場合は tail_flutter_logs も）を確認し、問題がないか確認します。