cocos-mcp: Instructions file for Codex

AGENTS.md

本文是 cocos-mcp 的 agent 使用规则。只写插件级规则；项目自己的预览参数、业务本地服地址、测试账号和验证步骤写在项目文档里。

允许入口

使用本插件时，只允许从下面这些入口进入：

入口	用途
当前项目 MCP 实例	scene / asset-db / preview / local 域操作
当前项目 HTTP MCP endpoint	当前 agent 没注入 MCP tool 时的等价入口
cocos-mcp-cli offline 命令	.prefab 查询和修改、.anim 查询
Playwright / Chrome	浏览器里真实游戏页面的交互验证
.dev/refresh 的 restart-package	重启本扩展代码

其它入口不作为本插件使用路径。项目文档可以补充项目自己的只读兜底信息，但不能覆盖本文件的入口规则。

绑定当前项目 MCP

同机可能同时打开多个 Cocos 项目。agent 必须先按项目根目录绑定 MCP 实例，再执行后续操作。

实例注册文件：

~/.cocos-mcp/editors/*.json

绑定规则：

1. 扫描 ~/.cocos-mcp/editors/*.json。
2. 只保留 projectPath 与当前项目根目录一致的记录。
3. 校验 pid 仍存活。
4. 多个匹配时取 updatedAt 最新的记录。
5. 后续所有 HTTP MCP 请求都使用该记录的 url。
6. 验证扩展代码变化时同时核对 runtimeBuildId、toolSchemaHash 和 loadedAt；工作树当前 HEAD/dirty 不能证明进程已加载新代码。

快速确认脚本：

python3 - <<'PY'
import glob
import json
import os
from pathlib import Path

def find_project_root(start):
    cur = Path(start).resolve()
    for item in [cur, *cur.parents]:
        if (item / 'assets').is_dir() and (item / 'settings').is_dir() and (item / 'extensions').is_dir():
            return str(item)
    return str(cur)

PROJECT = os.environ.get('PROJECT_ROOT') or find_project_root(os.getcwd())
items = []

for path in glob.glob(os.path.expanduser('~/.cocos-mcp/editors/*.json')):
    try:
        with open(path, 'r', encoding='utf-8') as f:
            data = json.load(f)
        if os.path.realpath(data.get('projectPath', '')) != os.path.realpath(PROJECT):
            continue
        os.kill(int(data['pid']), 0)
        items.append((data.get('updatedAt', ''), path, data))
    except Exception:
        pass

for _, path, data in sorted(items)[-3:]:
    print(path, data.get('url'), data.get('previewUrl') or '')
PY

Tool 与 HTTP MCP

如果当前 agent 已注入 router 暴露的 MCP tool，使用带项目名前缀的 tool：

forest__preview_query_url
forest__asset_reimport
forest__preview_refresh_and_reload

如果当前 agent 没注入这些 tool，按上节解析当前项目 MCP，再直接调用 HTTP endpoint。