Cocos MCP Server 0.0.1-dev.0（開発版）

現在のブランチ：develop ・ 現在のステータス：開発中 ・ 現在正式リリース版はありません

パッケージバージョンは 0.0.1-dev.0。プロトコルと Tool 契約バージョンは引き続き 0.0.1 です。

Cocos Creator 3.8.8 向けのローカルマルチプロジェクト MCP 拡張です。Cocos Dashboard がプロジェクトの作成・インポート・Creator バージョン選択・起動を担当します。拡張内の Worker はスタンドアロンの Manager に登録し、Agent は Manager にのみ接続し、プロジェクト単位の呼び出しのたびに projectId を明示的に指定します。

開発ステータス

• コードと検証作業は develop ブランチを基準とします。main は現在の開発作業ブランチではありません。

• 現在のパッケージは開発版であり、正式リリースパッケージとして直接配布することはできません。

• パッケージバージョン 0.0.1-dev.0 は現在の開発プレリリース状態を示します。プロトコル、Schema、Tool 契約は引き続き 0.0.1 を使用します。

• verify:release、build:release などのコマンドは、開発段階のリリースゲートおよび候補パッケージ検証ツールです。これらを通過しても正式リリース済みを意味するものではありません。

• 正式リリース前には、クリーンな候補バージョン、Direct Creator Live、Dashboard Creator Live、リリース証跡のクローズループを完了する必要があります。

Related MCP server: mcp-bridge

コア境界

• バージョン：パッケージ 0.0.1-dev.0。プロトコル/契約 0.0.1。リリースステータス development

• 接続：http://127.0.0.1:38488/mcp

• トランスポート：MCP Streamable HTTP

• Agent 接続：認証なし。ループバックアドレス、正当な Host/Origin のみ許可

• プロジェクト起動：ユーザープロジェクトは Cocos Dashboard 経由でのみ起動可能。Direct Creator Live のみが Runner 自身の一時 Fixture を起動・終了し、ユーザープロジェクトには一切操作しない

• マルチプロジェクト：1 つの Manager が複数の起動済み Worker をルーティング。最後の Worker がオフラインになり、pending 起動がない場合、Manager は自動終了

• 書き込み操作：事前チェック、revision 比較、実行、読み戻し検証、部分変更レポート

• 提供しないもの：トランザクション、自動ロールバック、ファイルバックアップ、MCP 操作履歴、監査ログ

開発インストール

npm install
npm run build

拡張ディレクトリを対象プロジェクトに配置します：

<project>/extensions/cocos-mcp-server

その後、Cocos Dashboard から：

1. プロジェクトをインポートまたは選択します。

2. Cocos Creator 3.8.8 を選択します。

3. プロジェクトを起動します。

4. 拡張 Worker が Manager に登録されるのを待ちます。

CocosCreator 実行ファイルを直接実行してユーザープロジェクトを起動しないでください。Dashboard のバージョンとログインコンテキストをバイパスすることになります。Direct Creator Live は Runner 自前の破棄可能な一時 Fixture にのみ適用されます。

Agent 接続

MCP クライアント接続：

http://127.0.0.1:38488/mcp

設定例：

{
  "mcpServers": {
    "cocos": {
      "url": "http://127.0.0.1:38488/mcp"
    }
  }
}

接続後の推奨フロー：

1. MCP initialize。

2. MCP tools/list で Manager が登録した Tool と Schema を確認。

3. system_control.list_projects を呼び出し。

4. 対象の projectId を選択。

5. 実行計画を生成する前に、Agent は Action メタデータに基づき、プレイヤー確認が必要な範囲と影響を提示します。

6. プロジェクトごとに書き込み操作を直列実行し、返された revision、verification、ChangeManifest を確認します。

Cocos パネルは承認を行わず、MCP も承認トークンを発行しません。承認のプロンプトは Agent コンテキストにのみ残します。

Dirty シナリオ

サポート対象：

reject
save

デフォルトは reject です。discard はサポートされず、未保存の変更を黙って破棄することはありません。

よく使うコマンド

npm run build
npm test
npm run test:unit
npm run test:integration
npm run test:e2e
npm run test:live:matrix
npm run build:release
npm run scan:release

Creator Live

Creator Live は開発段階の検証用であり、正式リリースに必要な完全な証拠に代わるものではありません。

Direct 一時 Fixture モード（デフォルト）

npm run test:live のデフォルトモードは Direct です。Runner は読み取り専用 Fixture をコピーした後、今回作成したコピーに対してのみ Creator -nologin を直接実行し、自身が追跡する一時 Creator 子プロセスにのみ SIGTERM を送信します。ユーザープロジェクトの起動・保存・終了は一切行いません。

npm run test:live
npm run test:live:direct
npm run test:live:action -- LIVE-SYS-001
npm run test:live:action:direct -- LIVE-SYS-001

Dashboard 一時 Fixture モード

Dashboard モードも Runner 自前の一時 Fixture のみを準備しますが、Creator の直接起動・終了は行いません。Runner は manifest と絶対プロジェクトパスを出力し、操作者は Cocos Dashboard でこれらの一時プロジェクトをインポート・起動・終了します。

npm run test:live:dashboard
npm run test:live:action:dashboard -- LIVE-SYS-001

Attach モード

Attach は、Dashboard 経由で起動され、Runner manifest が明示的に登録した一時 Fixture にのみ接続します。読み取り専用の受け入れモードです。

npm run test:live:attach
npm run test:live:action:attach -- LIVE-SYS-001

現在の Dashboard run に attach するには、その run で生成された manifest を明示的に指定する必要があります。Runner はディレクトリをスキャンしたり、暗黙的に「最新」の manifest を選択したりしません：

COCOS_MCP_LIVE_DASHBOARD_MANIFEST=/absolute/path/cocos-mcp-live-dashboard-XXXXXX/dashboard-fixtures.json \
npm run test:live:attach

COCOS_MCP_LIVE_DASHBOARD_MANIFEST=/absolute/path/cocos-mcp-live-dashboard-XXXXXX/dashboard-fixtures.json \
npm run test:live:action:attach -- LIVE-SYS-001

リポジトリドキュメント

• 現在の契約サマリー

• 開発ステータスとブランチ規約

• 変更履歴

• セキュリティノート

契約スナップショット、テストフィクスチャ、実装コードはすべてこのリポジトリ内に保存されます。Cocos 親プロジェクト内の相対パスドキュメントには依存しません。

トラブルシューティング

Manager が利用できない

Cocos Dashboard で起動したプロジェクトが少なくとも 1 つオンラインであることを確認します。Manager は常駐プロジェクトマネージャーとして実行されません。Worker がなく、pending 起動もない場合は自動終了します。

プロジェクトが表示されない

• Creator バージョンが 3.8.8 であることを確認します。

• プロジェクトにビルド済み拡張が含まれていることを確認します。

• settings/cocos-mcp.json の projectId が現在のプロジェクト ID と一致していることを確認します。

• 同じ projectId を使用するがパスが異なる 2 つのプロジェクトを同時に開かないでください。

ポート変更がすぐに反映されない

Manager 実行中は desired port のみ更新され、オンライン再起動は行われません。表示されている Cocos GUI からすべてのプロジェクトを終了し、最後の Worker の登録解除と Manager の自動終了を待ちます。再度 Dashboard からプロジェクトを起動すると、新しい Manager が新しいポートを使用します。

書き込み操作の失敗

優先的に確認：

• projectId が正しいか。

• 権限カテゴリが許可されているか。

• パスがプロジェクト範囲内か。

• expectedRevisions が古くないか。

• 現在の Scene/Prefab が Dirty か。

• Creator AssetDB、Scene、コンパイル状態が ready か。

復旧は Agent Session と Git が担います。MCP はトランザクションや自動ロールバックを実装しません。

開発段階のリリース検証

以下のコマンドは開発候補パッケージの検証用であり、正式リリースを意味しません：

# 普通 CI：干净安装、构建、测试、契约、扫描和高危依赖审计
npm run verify:release:ci

# 开发候选包的完整验证步骤
npm run test:live:release
npm run test:live:dashboard:release
npm run release:evidence
npm run verify:release

正式リリース前には、クリーンでコミット済みの候補バージョンで Direct Creator Live、Dashboard Creator Live、SBOM、チェックサム、provenance を完了し、メンテナーが明示的にリリースを承認する必要があります。dist/release/ と dist/release/release/ は生成物であり、Git には含まれません。