shacraft-core/docs/MCP.md

Shacraft MCP

shacraft-mcp — отдельный процесс с настоящим MCP поверх stdio и JSON-RPC 2.0. Он обращается к авторизованному Control API работающего сервера и не открывает файлы миров напрямую. Сервер хранит и проверяет ревизии, лимиты и долговечность операций.

cargo run -p shacraft-mcp -- --server http://127.0.0.1:4000 --data data

По умолчанию токен читается из data/control.token. Параметр --token-file /absolute/path/control.token переопределяет путь. Токен читается при управляющем вызове, поэтому MCP можно запустить раньше сервера. В стандартный вывод пишутся только JSON-RPC-сообщения, одна строка на сообщение; диагностика и CLI-ошибки идут в stderr. Не запускайте через командную обёртку, которая печатает посторонний текст в stdout.

Пример записи в конфигурации MCP-клиента (пути заменяются своими абсолютными):

{
  "mcpServers": {
    "shacraft": {
      "command": "/absolute/path/shacraft-core/target/release/shacraft-mcp",
      "args": ["--server", "http://127.0.0.1:4000", "--data", "/absolute/path/shacraft-data"]
    }
  }
}

Протокол

Поддерживаются версии 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05. Сервер возвращает запрошенную поддерживаемую версию или новейшую поддерживаемую. Клиент начинает с initialize, затем посылает notifications/initialized. До этого доступны только initialize и ping. Уведомления не вызывают ответов; неизвестные методы запросов получают JSON-RPC-ошибку. Ошибки аргументов и выполнения известных инструментов возвращаются в result.content с isError: true.

Реализованы tools/list, tools/call, resources/list, resources/read, resources/templates/list, prompts/list, prompts/get и ping. Списки небольшие и возвращаются целиком. Подписки, асинхронные задачи и уведомления о смене списков не объявляются. Выполнение последовательное; уведомление об отмене не прерывает уже выполняющийся HTTP-запрос. Сетевой тайм-аут ограничен 20 секундами (установление соединения — 3 секунды).

Строка запроса и HTTP-ответ ограничены 8 МиБ. Слишком длинная входная строка отбрасывается до перевода строки, после чего поток продолжает разбираться. HTTP-редиректы отключены: bearer-токен не передаётся перенаправленному адресу.

Инструменты и рабочий процесс

• world_list, world_create, world_read: осмотр миров и создание пустого мира или экземпляра закреплённого шаблона.
• catalog_search: точные состояния, runtime ID, формы и сведения о покрытии реализации.
• world_edit, world_undo, world_reset: атомарные правки, консервативная отмена последней операции и возврат к базе.
• build_plan, build_commit: предварительный расчёт ограниченной постройки из box/line/cylinder и последующая фиксация плана.
• entity_list, entity_spawn, entity_update, entity_delete: сохранённые сущности мира и их свойства.
• arena_configure, arena_start: сохраняемые правила Spleef (время, минимум игроков, высота выбывания, точки появления, материал пола) и запуск матча. Правила нельзя менять во время начавшегося раунда; материал пола задаёт разрешённые для разрушения блоки, но не перестраивает карту.
• metrics: измеренный RSS и отдельные оценки полезных данных кэша.
• camera_capture: изометрическое изображение мира в формате MCP image plus metadata. Это диагностическая проекция сервера, не снимок WebGL-камеры игрока.

Полные JSON Schema доступны через tools/list. Имена инструментов соответствуют Control API с заменой первого _ на точку, например world_edit → world.edit.

Для строительства сначала прочитайте ревизию и площадку через world_list/world_read, найдите точные материалы через catalog_search, сформируйте build_plan, оцените границы и объём, затем выполните build_commit с уникальным operation_id в пределах авторизованного запроса. После фиксации проверьте camera_capture. При конфликте перечитайте мир и сформируйте новый план. Тот же ключ операции используйте только при повторе идентичного запроса.

Отмена требует текущую ревизию и target_operation исходной правки. Последующие изменения и reset могут сделать отмену недоступной; инструмент не должен перезаписывать их молча.

Ресурсы и prompt

Ресурсы shacraft://server/status, shacraft://catalog/blocks, shacraft://catalog/entities, shacraft://packages читают публичные сведения сервера. Ресурс блоков даёт начальную ограниченную страницу; полный каталог доступен поиском и пагинацией инструмента.

Prompt construct принимает строки world и request и описывает последовательность осмотра, планирования, правки и визуальной проверки. Он не расширяет пользовательское разрешение на действие.

Проверки: cargo test -p shacraft-mcp. Unit-тесты проверяют переходы жизненного цикла, согласование версии, отсутствие ответов на уведомления, ошибки аргументов и токена, недопустимые JSON-RPC ID, восстановление после слишком большой строки и схемы строительных операций. Сквозные тесты с настоящим сервером выполняются дополнительно.

Основание протокола: официальные lifecycle, stdio transport и tools.

Проверка настоящим MCP SDK

После запуска отдельного тестового сервера:

node crates/shacraft-mcp/tests/sdk-smoke.mjs --data /absolute/path/test-server-data

Скрипт использует @modelcontextprotocol/sdk (проверен с 1.30.0), выполняет согласование протокола, читает все ресурсы, вызывает prompt, делает правку/повтор/конфликт/отмену, план/фиксацию, получает PNG, проверяет CRUD сущностей и reset. Он создаёт отдельный мир с префиксом mcp_sdk_. Путь к установленному SDK задаётся через SHACRAFT_MCP_SDK; в локальной среде поддерживается соседний minecraft-builder-mcp/bridge/node_modules. Это независимая проверка протокола, не зависимость исполняемого MCP от Minecraft Builder.

Для воспроизводимой проверки с автоматически запущенным отдельным сервером:

node scripts/check_mcp.mjs --binary target/release/shacraft-server --mcp-binary target/release/shacraft-mcp --port 4002 --output artifacts/mcp-sdk.json

Обёртка создаёт временный каталог данных, использует настоящий SDK и закрывает тестовый сервер. Рабочий сервер на порту 4000 не затрагивается. --sdk или SHACRAFT_MCP_SDK задают путь к уже установленному SDK; результат записывается JSON-файлом, включая ошибку при неуспешной проверке.

Связанный сквозной тест scripts/check_server.mjs проверяет HTTP/WebSocket-клиенты, действия, экземпляры миров, полный матч и восстановление после реального SIGKILL: подтверждённые блоки, сущности и правила арены должны пережить перезапуск того же каталога данных. Временные тестовые данные сохраняются для разбора.