Cocos MCP Server 0.0.1-dev.0 (версия для разработки)

Текущая ветка: develop · Текущий статус: в разработке · Официального релиза в настоящее время нет

Версия пакета — 0.0.1-dev.0; версия протокола и контрактов Tool по-прежнему — 0.0.1.

Локальное многопроектное MCP-расширение для Cocos Creator 3.8.8. 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: без аутентификации; разрешены только loopback-адреса, допустимые Host/Origin

• Запуск проектов: пользовательские проекты запускаются только через Cocos Dashboard; только Direct Creator Live запускает и завершает собственный временный Fixture Runner и никогда не затрагивает пользовательские проекты

• Многопроектность: один Manager маршрутизирует несколько запущенных Worker; когда последний Worker отключается и нет ожидающих запусков, 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 применим только к одноразовым временным Fixture, принадлежащим Runner.

Подключение 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 — обнаружение Tool и Schema, зарегистрированных в Manager;

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 только для созданной копии и отправляет SIGTERM только отслеживаемому им временному дочернему процессу Creator. Он не запускает, не сохраняет, не закрывает и не завершает ни один пользовательский проект.

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 также готовит только собственный временный Fixture Runner, но не запускает и не закрывает Creator напрямую; Runner выводит manifest и абсолютный путь к проекту, а оператор импортирует, запускает и завершает эти временные проекты в Cocos Dashboard.

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

Режим Attach

Attach подключается только к временным Fixture, запущенным через Dashboard и явно зарегистрированным в manifest Runner; это режим приёмки только для чтения.

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

Чтобы подключиться к текущему запуску Dashboard, необходимо явно указать 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, остаётся в сети. Manager не работает как постоянный менеджер проектов; при отсутствии Worker и ожидающих запусков он завершает работу автоматически.

Проект не отображается

• Убедитесь, что версия Creator — 3.8.8;

• Убедитесь, что проект содержит собранное расширение;

• Проверьте, что projectId в settings/cocos-mcp.json соответствует идентичности текущего проекта;

• Не открывайте одновременно два проекта с одинаковым projectId, но разными путями.

Изменение порта не вступает в силу немедленно

Пока Manager работает, обновляется только желаемый порт (desired port), без перезапуска в реальном времени. Завершите все проекты через видимый GUI Cocos, дождитесь отмены регистрации последнего Worker и автоматического завершения Manager; после повторного запуска проекта из Dashboard новый Manager будет использовать новый порт.

Сбой операции записи

В первую очередь проверьте:

• Корректен ли projectId;

• Разрешена ли категория разрешений;

• Находится ли путь в пределах проекта;

• Не устарели ли expectedRevisions;

• Не является ли текущая Scene/Prefab грязной (Dirty);

• Готовы ли AssetDB Creator, Scene или состояние компиляции.

Восстановление обеспечивают 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.