> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP 経由で Base44 アプリをリモート開発する
> base44-dev/apper PR #11608 から取り込み
このページは AI コーディングエージェントスキルの一部で、人間ではなくエージェント向けに書かれています。人間向けの Base44 ドキュメントは [デベロッパードキュメント](/developers) を参照してください。
# MCP 経由で Base44 アプリをリモート開発する
独自のコーディングエージェントを Base44 アプリのサンドボックスに接続して、そこで直接開発できます — コマンドの実行、ファイルの読み書き、grep、ディレクトリの一覧表示など — Base44 はサンドボックスを提供し、あなたはエージェントと LLM を提供します。
これはあらゆる MCP 対応クライアントで動作します。例では Claude Code を使用します。
> **最も簡単な開始方法:** Base44 アプリエディターで **Send to Coding Agent** をクリックします。ローカルエージェント用には、貼り付けるだけで使えるプロンプトを提供します (README を取得し、MCP または `base44 sandbox` CLI 経由でサンドボックスを操作 — セクション 10);
> Web 用には、**claude.ai** チャット (Base44 MCP コネクタ付き) に貼り付けるプロンプトと、**Open Claude** ボタンを提供します。ボタンは発見のためのサーフェスであり、このスキルの残りの部分はリファレンスです。
> **2 つのトランスポート:** Web エージェントは Base44 **MCP コネクタ** を持つ **claude.ai** を使用 (セクション 1–9) — これは通常の claude.ai チャットであり、独自のリポジトリ支援サンドボックスで動作する Web 上の Claude Code (`claude.ai/code`) では *ありません*。ローカルエージェントは同じ MCP サーバーに接続するか、**`base44 sandbox` CLI** (Base44 CLI トークン、セクション 10) でサンドボックスを操作できます — 同じツール、同じ動作、同じエラーコード。CLI は単にそれらを短いコマンド名 (`sandbox read`、`sandbox ls`、…) で公開するだけです。
***
## 1. MCP サーバーに接続する
Base44 MCP エンドポイントは以下:
```
https://app.base44.com/mcp
```
Claude Code に登録します (どのフォルダーからも実行可能):
```bash theme={null}
claude mcp add --transport http base44 https://app.base44.com/mcp
```
現在のフォルダーだけでなくすべてのプロジェクトで使用可能にする場合は `--scope user` を追加します。
`claude mcp add` は設定を書き込むだけで、まだ認証は行いません。
## 2. 認証する
Claude Code を起動し、MCP メニューを開きます:
```bash theme={null}
claude
```
その後、Claude Code 内で:
```
/mcp
```
**base44** → **Authenticate** を選択します。Base44 OAuth フロー (PKCE) 用のブラウザーが開きます — ログインして承認します。成功すると、`/mcp` は **base44** を connected として表示し、そのツールを一覧表示します。
**ブラウザーを開けない純粋な CLI / ヘッドレスクライアント** は代わりに OAuth デバイスフロー (`/oauth/device/code`) を使用します — コードを要求し、別のデバイスのブラウザーで承認すると、クライアントがトークンを受け取ります。
### スコープ
| ツール | 必要なスコープ |
| ------------------------------------------------------------------------------------------------ | ---------------------- |
| `read_file`, `grep`, `list_directory`, `get_app_preview_url`, `get_app_status`, `list_user_apps` | `apps:read` (デフォルトで付与) |
| `write_file`, `edit_file`, `run_command`, `create_checkpoint` | `sandbox:write` |
`sandbox:write` はデフォルトでは **付与されません** — シェルとファイル変更には明示的な付与が必要です。読み取りツールは動作するが変更ツールが `NOT_AUTHORIZED` を返す場合、トークンに `sandbox:write` が欠落しています。再接続してサンドボックスアクセスを付与してください (デバイスフローは明示的にリクエストできます)。
***
## 3. アプリを選択して方向を定める
すべてのツールには必須の `appId` が必要です。`list_user_apps` でアプリを見つけ、リクエストに ID を固定して、エージェントが毎回呼び出しで渡すようにします。
何かを変更する前にメンタルモデルを構築するために **読み取り専用** で開始します:
```
Using the base44 tools on appId :
1. list_directory on the app root (recursive, depth 2)
2. read_file src/App.jsx and src/pages.config.js
3. grep for the component I want to change
Summarize the structure before editing.
```
> **コールドスタート:** アプリに実行中のサンドボックスがない場合、最初のツール呼び出しは最後のコミットからサンドボックスを透過的に立ち上げます — 少し時間がかかるだけです。以降の呼び出しは高速です。
> **CLI 名:** `base44 sandbox` CLI (セクション 10) では、これらの読み取りツールは `list_directory` → `sandbox ls`、`read_file` → `sandbox read`、`grep` → `sandbox grep` です。
***
## 4. 変更を加える
* **`edit_file`** (CLI では `sandbox edit`) — 既存ファイルの変更に推奨。正確な `old_text`→`new_text` の編集を提供します。`replace_all` を設定しない限り、各 `old_text` はファイル内で一意である必要があります。1 回の呼び出しでのすべての編集はアトミックに適用され (all-or-nothing)、unified diff が返されます。書き込みなしで diff をプレビューするには `dry_run: true` を渡します。
* **`write_file`** (CLI では `sandbox write`) — 新しいファイルの作成用。既存ファイルを上書きするには `overwrite: true` を渡す必要があります (静かに上書きすることはありません)。
* **`run_command`** (CLI では `sandbox run`) — サンドボックスで任意の bash コマンドを実行 (ビルド、インストール、スキャフォールディング、コード変更)。作業ディレクトリはデフォルトでアプリルート。`cd` は呼び出し間で永続化されないため、`cwd` パラメーターを使うかコマンドをチェーン (`cd sub && cmd`) してください。タイムアウトはデフォルトで 120 秒 (最大 600 秒)、出力は約 1 MB でキャップされます。
* **`create_checkpoint`** (CLI では `sandbox checkpoint`) — 名前付きの復元ポイントを保存し、ユーザーが後でロールバックできるようにします。オプションの `name` (メッセージ/タイトル、省略時は自動生成) を取ります。保留中の変更はまず **フラッシュされコミットされ**、チェックポイントが最新コードに固定されます。次に、チェックポイント ID、名前、git コミットハッシュを返します。編集のチャンクの前後で既知の良好な状態をマークするために使用します。(最近の自動コミットがまだ耐久性を確認できない場合、古い状態をチェックポイントするのではなく、再試行可能な `COMMIT_FLUSH_PENDING` で拒否します — 少し待って再試行してください。)
例:
```
On appId , use edit_file to change the homepage heading in
src/pages/Home.jsx from "Welcome" to "Welcome back". Show me the diff first
with dry_run, then apply it.
```
***
## 5. プレビューと検証 (編集 → チェックループ)
ライブログストリーミングツールはありませんが、フィードバックループを閉じることができます:
* **ライブで確認:** `get_app_preview_url` は dev サーバーを起動してプレビュー URL を返します。Vite HMR が編集をリアルタイムで反映します。
* **ビルドステータス:** `get_app_status` は `ready` / `processing` / `error` を返します。
* **オンデマンドでビルド/型/lint エラーを表示** するには `run_command` を使用:
```bash theme={null}
npm run build # bundler/compile errors
npx tsc --noEmit # type errors
npm run lint # lint errors
```
* **dev サーバー (Vite) ログを読む** — 管理された dev サーバーは `/tmp/vite.log` に書き込みます。`run_command` で tail して HMR/コンパイルエラーを確認:
```bash theme={null}
tail -c 32000 /tmp/vite.log
```
(これはアプリツリーの外にあるため、ファイルツールでは到達できず、`run_command` 経由のみです — したがって `sandbox:write` が必要です。)
堅実なループ: `edit_file` → `npm run build` (または `/tmp/vite.log` を tail) → エラーを修正 → `get_app_preview_url` で目視確認。
> **ブラウザーランタイムエラー** (コンパイルはできるがレンダー時にスローするコンポーネント、失敗するクライアント API 呼び出し) はブラウザーコンソールに表示され、`/tmp/vite.log` には表示されません。それらを捕捉するにはプレビュー URL を開いてください。
***
## 6. 変更の永続化
「保存」は不要です。すべての変更呼び出しは **デバウンスされた自動コミット** (\~5 秒) をスケジュールします: 変更はコミットされ、Base44 のコードストレージにプッシュされるため、以下のようになります:
* サンドボックスの死亡から生き残る (サンドボックスは最後のコミットから再作成される)
* ビルダーのライブラリ/データタブに表示される
* バックエンド関数のデプロイと整合性を保つ
* アプリを公開するときに含まれる
実用的な影響:
* 小さな損失ウィンドウ (\~5 秒) があります — 最後の編集の直後にセッションを終了しないでください。コミットするための少しの時間を与えてください。
* エンティティ、エージェント、ワークフロー、バックエンド関数、ページルーティングへの編集は、コミット後に自動的に Base44 に同期されます。通常のページ/コンポーネント/CSS の編集は git に存在し、追加のものは必要ありません。
***
## 7. 並行性: あなた vs. Base44 ビルダー
あなたとアプリ内の Base44 ビルダーは同時に同じアプリを変更できません:
* **サンドボックスツールをアクティブに使用している間**、Base44 ビルダーチャットはブロックされます ("An external agent is currently working on this app")。セッションは暗黙的です — 最近のツール呼び出し *が* セッションであり、短いアイドル期間 (\~10 分) 後に終了します。
* **Base44 ビルダーがビルド中の場合**、変更ツールは `BUILDER_BUSY` を返します。`get_app_status` をポーリングし、`ready` になったら再試行してください。ビルド中も読み取り専用ツールは動作します。
***
## 8. ガードレールと制限
* **パスはアプリに限定されます。** ファイルツールはアプリディレクトリ内でのみ動作します。トラバーサル/絶対パスは拒否されます (`PATH_OUTSIDE_SANDBOX`)。
* **`.agents/` はファイルツールから禁止されています** (`PROTECTED_PATH`) — エージェント管理の構成とシークレット (`.agents/.env`) を保持しています。ファイルツールでそれを読み取ったり編集したりしないでください。
* **レート制限** はアプリごとに適用されます: 読み取り \~120/分、変更 \~60/分、コマンド \~30/分。`RATE_LIMITED` に達したら速度を落としてください。
* **`delete_file` は専用ツールではありません** — `run_command rm` で削除します。
### 表示される可能性のあるエラーコード
`NOT_AUTHORIZED` (スコープ/フラグ欠落) · `APP_NOT_FOUND` (ID が誤りかアクセスなし)
· `PATH_OUTSIDE_SANDBOX` · `PROTECTED_PATH` · `NOT_FOUND` · `BINARY_FILE` ·
`EDIT_TEXT_NOT_FOUND` · `EDIT_TEXT_NOT_UNIQUE` (`old_text` を一意にするか `replace_all` を使用) · `OVERWRITE_NOT_ALLOWED` (`overwrite: true` を渡す) · `TIMEOUT` ·
`OUTPUT_TRUNCATED` · `BUILDER_BUSY` ·
`COMMIT_FLUSH_PENDING` (保留中の自動コミットがまだ耐久性を持たない、少し待って再試行 — 例: `create_checkpoint` で) · `RATE_LIMITED` · `BACKEND_ERROR`。
メッセージはエージェントが自己修正できるように書かれています — それらを読んで調整してください。
***
## 9. ヒントとテクニック
* **書き込む前に読む。** すばやい `list_directory` + `read_file` (または `grep`) のパスはコストが少なく、編集の正確性を劇的に向上させます。
* **`edit_file` で `dry_run` を使用** して、特に複数編集の呼び出しで、変更にコミットする前に diff を確認します。
* **既存ファイルでは `write_file` よりも `edit_file` を優先** — 外科的な編集で上書きを避け、レビュー可能な diff を生成します。
* **大きなファイルでは `read_file` の `offset`/`limit` で行範囲を読む** — コンテキストにファイル全体を引き込むのではなく。
* **何かが「壊れて見える」場合、推測する前に `/tmp/vite.log` を tail** — 通常は正確なファイルと行を名指しします。
* **コミットさせる。** 最終編集の後、自動コミットが着地する前に切断または公開する前に数秒間一時停止します。
* **既知の良好な状態をチェックポイント。** リスクのある編集チャンクの前後に復元ポイントをマークするには `create_checkpoint` (`sandbox checkpoint`) を使用 — 保留中の変更をまずフラッシュするため、ユーザーは常にそのポイントにロールバックできます。
* **エージェントは一度に 1 つ。** この機能はアプリごとに単一の外部エージェント用に設計されています。同じアプリに対して並行セッションを実行しないでください。
***
## 10. `base44 sandbox` CLI 経由のローカルエージェント
エージェントがマシン上で実行される場合、MCP の代わりに Base44 CLI を通じて同じサンドボックスを操作でき、OAuth の代わりに Base44 CLI で認証します。同じツール、同じ動作、同じエラーコード (セクション 8) — サーフェスと認証だけが異なります。
**認証。** Base44 CLI (`base44 login`) でログインします — `base44 functions deploy` と同じ資格情報。プロジェクトレスの `base44 connectors` コマンドと同様、sandbox サブコマンドは `--app-id`、次に `BASE44_APP_ID`、次にローカルの `.app.jsonc` からアプリ ID を解決します。`config.jsonc` は不要です。
**コマンド名。** CLI は各サンドボックスツールをより短い名前で公開します:
| MCP ツール | CLI コマンド |
| ------------------- | --------------------------- |
| `list_directory` | `base44 sandbox ls` |
| `read_file` | `base44 sandbox read` |
| `write_file` | `base44 sandbox write` |
| `edit_file` | `base44 sandbox edit` |
| `run_command` | `base44 sandbox run` |
| `grep` | `base44 sandbox grep` |
| `create_checkpoint` | `base44 sandbox checkpoint` |
```bash theme={null}
npx base44 sandbox read --app-id src/App.jsx
```
`base44 sandbox checkpoint` はオプションの `--name` (メッセージ/タイトル) を取り、復元ポイントを保存します:
```bash theme={null}
npx base44 sandbox checkpoint --app-id --name "before refactor"
```
**特定のアプリの完全なリファレンスをエージェントに渡す** (指示、公開、取得に認証不要):
```
https://app.base44.com/api/sandbox//local-agent/readme.md
```
(クラウド/MCP に相当するのは `.../api/sandbox//claude-web/readme.md` です。)
このスキルの他のすべて — 編集→プレビュー→検証ループ (セクション 5)、永続化 (セクション 6)、並行性 (セクション 7)、ガードレール (セクション 8) — は同一に適用されます。サーフェスと認証だけが異なります。
***
## 11. コネクタ (OAuth インテグレーション)
サンドボックスのファイル/シェルツールに加えて、Base44 MCP サーバーはアプリの第三者 OAuth コネクタ (Google Calendar、Gmail、Slack、…) を管理する 2 つのツールを公開します。これらはサンドボックスファイルシステムには触れず、アプリのコネクタ状態を直接操作します。両方とも `appId` を取ります。
| ツール | スコープ | 目的 |
| ------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_connectors` | `apps:read` | アプリのコネクタを一覧表示。`integrationTypes` なしで、完全なカタログ (name、description、connected?、接続されている場合はステータスと付与されたスコープ) を返します。特定のもののの詳細には `integrationTypes` を渡してください。 |
| `initiate_connector_connection` | `apps:write` | コネクタを接続 (または再スコープ) します。入力: `appId`, `integrationType`, `scopes`, オプション `connectionConfig`。 |
正しく理解すべき 2 つのセマンティクス:
* **宣言的スコープ (マージではなく置換)。** `initiate_connector_connection` はコネクタを渡した `scopes` に **完全に** 設定します。省略されたスコープは削除され、ユーザーは再度同意を求められます。**必ず先に `list_connectors` を呼び出し**、次に完全な希望セット (保持したい既存スコープ **と** 新しいスコープ) を渡してください。
* **OAuth には人間が必要。** ツールは `already_authorized: true` (やることなし) または **ユーザー** がサインインして同意するためにブラウザーで開く必要がある `redirect_url` を返します — あなた自身では完了できません。彼らが終了したら、`list_connectors` を再度呼び出して確認し、**付与された** スコープを読み取ります (プロバイダーが要求されたよりも少ないスコープを付与する場合があります)。
これらは `apps:read` / `apps:write` のみ必要で、`sandbox:write` は **不要** です。CLI サーフェス (セクション 10) では、プロジェクトレスの `base44 connectors` コマンド (`list-available`、`initiate --integration-type --scopes --app-id `、`pull`) に相当し、同じ認可 URL を出力します。
このページは AI を使用して翻訳されました。最も正確で最新の情報については、[英語版](/) を参照してください。