Интеграция MCP

Интеграция MCP Locus позволяет совместимому клиенту MCP работать с поддерживаемыми заметками, документами, метками и состоянием Locus, пока запущен Unreal Editor. Она необязательна и по умолчанию отключена.

Locus не включает автономного AI-помощника. Подключённый клиент MCP выполняет AI-сценарий и решает, когда использовать поддерживаемые инструменты Locus.

Перед подключением

Вам нужны:

• открытый Unreal Editor с включённым для проекта Locus
• включённая Интеграция MCP в настройках Locus
• совместимый клиент MCP, работающий на том же компьютере

Конечная точка Locus локальна для компьютера. Locus не заявляет совместимость с каждым клиентом MCP и каждой будущей версией клиента. Locus предоставляет варианты начальной настройки для OpenAI Codex, Claude Code и Gemini CLI, а также общий вариант для других совместимых клиентов Streamable HTTP MCP. Эти варианты настраивают один и тот же сервер MCP Locus и те же 18 инструментов; это не отдельные AI-интеграции.

Проверка выпуска на реальных клиентах использовала Codex CLI 0.147.0, Claude Code 2.1.228 и Gemini CLI 0.55.1. Считайте их протестированными версиями, а не постоянной гарантией совместимости.

Подключение клиента

1. В Unreal Editor откройте Editor Preferences > Plugins > Locus, затем MCP Integration.
2. Включите Enable MCP и дождитесь состояния Running - waiting for client.
3. В разделе Connection выберите подходящий Client Format: OpenAI Codex, Claude Code, Gemini CLI или Generic Streamable HTTP MCP.
4. Выберите Скопировать конфигурацию.
5. Вставьте скопированную конфигурацию в обычное место конфигурации MCP-клиента или его процедуру настройки, затем подключите его.
6. Вернитесь в Locus и убедитесь, что состояние показывает Client connected.

Скопированная конфигурация является источником истины для текущей конечной точки и учётного параметра. Не создавайте конфигурацию подключения вручную, если только клиент не требует формата, которого нет в Locus.

OpenAI Codex

Для Codex выберите OpenAI Codex и используйте Скопировать конфигурацию. Добавьте скопированный TOML в Codex обычным способом настройки MCP, затем перезагрузите или перезапустите Codex, если перед подключением это необходимо. Проверьте сервер Locus в списке MCP-серверов Codex. Для Unreal Engine 5.8 см. раздел Использование Locus с Unreal MCP в Unreal Engine 5.8.

Claude Code

Для Claude Code Locus копирует официальную команду регистрации HTTP MCP с локальной областью проекта и личной областью пользователя. Запустите скопированную команду в обычном терминале. Общий файл проекта .mcp.json с учётными данными не создаётся.

Gemini CLI

Для Gemini CLI Locus копирует официальную команду регистрации HTTP MCP с --scope user. Сервер и локальный учётный параметр сохраняются в личной конфигурации Gemini пользователя, а не в проектном .gemini/settings.json, который мог бы попасть в систему контроля версий. Компромисс в том, что запись Locus доступна этому пользователю в разных проектах, поэтому при переходе в проект с другой активной конечной точкой или учётным параметром копируйте свежую конфигурацию.

Locus не добавляет опцию Gemini --trust. Обычная политика подтверждения инструментов Gemini продолжает действовать.

Общий Streamable HTTP MCP

Выберите Generic Streamable HTTP MCP, когда совместимому клиенту нужны конечная точка и заголовок Authorization, а не формат одного из поддерживаемых клиентов. Следуйте личным рекомендациям этого клиента по конфигурации и используйте в сохраняемых заметках или примерах заполнители вроде Bearer <LOCAL_LOCUS_CREDENTIAL>.

Использование Locus с Unreal MCP в Unreal Engine 5.8

Встроенный Unreal MCP в Unreal Engine 5.8 и Locus MCP могут работать параллельно как независимые MCP-серверы. Locus не зависит от Unreal MCP.

В приведённой ниже проверенной настройке используется Codex. Это пример для конкретного клиента, а не утверждение, что возможность независимых серверов доступна только для Codex.

Пример Codex

Настройка обоих серверов

1. В Unreal Engine 5.8 включите Unreal MCP, All Toolsets, Terminal и Locus. Убедитесь, что сервер Unreal MCP включён и настроен на автоматический запуск.

2. В консоли Unreal выполните:

   ModelContextProtocol.GenerateClientConfig Codex

   Unreal создаёт конфигурацию Codex по адресу:

   <Project>/.codex/config.toml

3. В Unreal откройте Editor Preferences > Plugins > Locus > MCP Integration. Включите сервер MCP Locus, затем выберите Copy Connection Configuration > OpenAI Codex (config.toml).

4. Вставьте сгенерированный блок MCP Locus ниже MCP-конфигурации, сгенерированной Unreal, в <Project>/.codex/config.toml. Не создавайте URL, заголовки или учётные данные Locus вручную; скопированный блок является текущей конфигурацией подключения.

В файле должны присутствовать обе записи MCP-серверов:

unreal-mcp
locus

Не публикуйте конфигурацию Codex

Сгенерированный блок Locus может содержать локальные учётные данные Bearer. Не отправляйте <Project>/.codex/config.toml в систему контроля версий, если он содержит учётные данные.

Запуск Codex и проверка подключения

Откройте терминал Unreal Engine в корне проекта и выполните:

codex

Попросите Codex проверить доступные MCP-серверы:

Check which MCP servers are available to you.

В списке должны быть unreal-mcp и locus. Затем проверьте каждую интеграцию отдельно:

Use Unreal MCP to inspect my currently selected actor.

Use Locus to get its current status and list my Notes. Do not modify anything.

Сохраняйте подключение локальным и личным

Locus слушает только локальный loopback-интерфейс, поэтому конечная точка MCP доступна только на том же компьютере. Сгенерированный личный bearer-учётный параметр аутентифицирует клиента.

Скопировать конфигурацию — явное действие, создающее текст с учётным параметром. Считайте скопированную конфигурацию конфиденциальной и вставляйте её только в доверенный клиент. Не включайте её в документацию, отчёты о проблемах, снимки экрана, сообщения чата или конфигурацию под контролем версий. Locus намеренно не показывает учётный параметр в настройках и не выводит его в журналы. Если вы считаете, что параметр раскрыт, используйте Advanced > Regenerate Credential…, затем скопируйте в клиент свежую конфигурацию.

Отключение Enable MCP прекращает доступ Locus MCP. Закрытие Unreal Editor также завершает активную конечную точку Locus MCP. Более широкая граница конфиденциальности локального содержимого и внешнего клиента описана в разделе Конфиденциальность и отзывы.

Осознанно выбирайте разрешения

Настройка	Что она разрешает
Только для чтения	Значение по умолчанию. Клиенты могут использовать поддерживаемые операции чтения, но поддерживаемые операции изменения отклоняются. В сводке состояния отображается ReadOnly, когда Разрешить изменения отключено.
Разрешить изменения	Включает поддерживаемые операции создания, обновления, архивирования и добавления комментариев. Включайте только когда хотите разрешить подключённому клиенту изменять содержимое Locus. Произвольное изменение проекта Unreal не разрешается.

Личное содержимое защищено отдельно. Разрешить личные заметки и метки по умолчанию отключено; ни включение MCP, ни Разрешить изменения автоматически не дают это разрешение. Включайте его только если подключённому клиенту нужен доступ к локальным Личным заметкам и меткам. Документы всегда принадлежат проекту и не имеют Личной области.

Что могут делать клиенты

Locus предоставляет 18 инструментов MCP. Они сгруппированы по виду поддерживаемой работы, а не по деталям протокола MCP.

Группа	Инструменты	Поддерживаемая работа
Infrastructure (2)	locus.get_status, locus.get_capabilities	Проверка состояния Locus, разрешений и доступных возможностей.
Notes (6)	locus.list_notes, locus.get_note, locus.search_notes, locus.create_note, locus.update_note, locus.archive_note	Поиск, чтение, создание, обновление и архивирование заметок.
Documents (5)	locus.list_documents, locus.get_document, locus.search_documents, locus.create_document, locus.update_document	Поиск, чтение, создание и обновление принадлежащих проекту документов Markdown. Переименование, перемещение и удаление через MCP недоступны.
Pins (5)	locus.list_pins, locus.get_pin, locus.create_pin, locus.update_pin, locus.add_pin_comment	Поиск, чтение, создание, обновление и комментирование меток. Удаление и архивирование меток через MCP недоступны.

Инструменты чтения доступны в режиме Только для чтения. Поддерживаемые инструменты создания, обновления, архивирования и добавления комментариев требуют Разрешить изменения. Действующие меры защиты Locus, включая правила системы контроля версий и проверки содержимого, продолжают применяться.

Документы, созданные через MCP, используют тот же отложенный рабочий процесс добавления, что и документы, созданные в редакторе: сначала они локальные и Неотслеживаемые. Организуйте, переименуйте, переместите или измените их в Locus, затем явно используйте Пометить для добавления, когда окончательный путь готов. MCP не предоставляет инструментов переименования, перемещения, удаления или пометки документа для добавления.

Корни представления документов

MCP понимает те же два корня представления, которые показаны в рабочей области документов. Оба являются видами одного репозитория <Project>/ProjectDocuments/:

• Документы Locus содержат обычные документы вне зарезервированного отображения Content/.... Путь представления Design/Combat.md имеет тот же авторитетный путь: Design/Combat.md.
• Браузер контента содержит документы Markdown, проецируемые в контекст Браузера контента Unreal. Путь представления Characters/Hero.md имеет авторитетный путь документа Content/Characters/Hero.md и отображается в соответствующем контексте /Game/Characters.

Документы Браузера контента остаются внешними файлами Markdown. Они не являются UAsset, а /Game/... — это контекст представления, а не идентичность документа. Нормализованный путь Markdown относительно ProjectDocuments остаётся авторитетным.

locus.list_documents и locus.search_documents принимают необязательное значение presentationRoot: all, locusDocuments или contentBrowser; без него используется all. Фильтрация остаётся частью индексированной операции списка или поиска и сохраняет существующие порядок и пагинацию.

locus.create_document принимает locusDocuments или contentBrowser, если вызывающий хочет явно выбрать видимый корень. В этом режиме relativePath задаётся относительно выбранного корня представления:

presentationRoot	Переданный relativePath	Созданный авторитетный путь
locusDocuments	Design/Combat.md	Design/Combat.md
contentBrowser	Characters/Hero.md	Content/Characters/Hero.md

При явном создании под contentBrowser не добавляйте Content/: Locus применяет зарезервированное отображение один раз. Существующие вызывающие стороны без presentationRoot сохраняют прежний контракт авторитетного пути, поэтому ввод Content/Characters/Hero.md сохраняет прежний смысл.

Результаты документов различают:

• relativePath: авторитетная нормализованная идентичность под ProjectDocuments
• presentationRoot: locusDocuments или contentBrowser
• presentationPath: путь, видимый под этим корнем представления

Поля корня дают контекст; они не создают другое хранилище или идентификатор документа.

locus.archive_note переводит состояние жизненного цикла заметки в Archived; он не перемещает заметку в отдельную панель Archived Notes. Locus 1.0 оставляет архивированные заметки видимыми в обычной рабочей области заметок и не имеет отдельного редакторского процесса Archive/Restore или инструмента locus.restore_note. Чтобы вернуть заметку в состояние Open через MCP, используйте locus.update_note с текущей ревизией и status: "open".

Поддержка мира для меток

Поддерживаемая основа меток — сохранённый принадлежащий проекту мир /Game/... с явной идентичностью мира и положением в мировом пространстве Unreal. Поддерживается базовая работа с сохранённым принадлежащим проекту World Partition.

Не полагайтесь на метки MCP для карт, смонтированных плагином; несохранённых, временных, демонстрационных или PIE/runtime миров; специализированных выгруженных регионов World Partition; якорей, следующих за Actor или внешним Actor; поведения, связанного с Data Layer; Level Instances; обычных потоковых подуровней; или восстановления переименования и перенаправления мира. Эти контексты не входят в текущую поддерживаемую основу.

Только один клиент

Locus разрешает одну активную авторизованную сессию клиента и выполняет вызовы инструментов по одному. Если сессией владеет другой клиент, второй клиент может быть отклонён или считаться занятым, пока активная сессия не завершится или не истечёт.

Сначала закройте или отключите прежний клиент, если он был прерван — немного подождите, затем повторите. Если сессия не освободилась, используйте Troubleshooting > Reset Active Client в интеграции MCP. Отключайте и снова включайте MCP только при необходимости восстановить локальный сервер.

Отключение или выключение MCP

Отключите клиент после завершения работы. Чтобы полностью прекратить доступ Locus MCP, выключите Enable MCP. Отключение MCP не удаляет содержимое Locus или локальный учётный параметр; оно только останавливает локальную конечную точку до повторного включения.

Устранение неполадок подключения

Симптом	Действие
MCP отключён или конечная точка недоступна	Оставьте Unreal Editor открытым, откройте MCP Integration, включите Enable MCP и дождитесь рабочего состояния.
Клиент отклоняет подключение или учётный параметр	Скопируйте свежую конфигурацию после изменения локального порта или генерации нового учётного параметра; старые скопированные конфигурации больше не работают.
Активен другой клиент или Locus занят	Закройте другого клиента, немного подождите и повторите. Используйте Reset Active Client, только если клиент больше не используется. Перед повтором вызова инструмента дождитесь завершения текущей операции Locus.
Клиент не может изменять содержимое	Разрешить изменения отключено. Включайте его только для нужных поддерживаемых изменений Locus.
Доступ к Личным заметкам или меткам отклонён	Отдельно включите Разрешить личные заметки и метки. Одно Разрешить изменения не даёт Личного доступа.
Запрос метки сообщает неподдерживаемый контекст мира	Используйте сохранённый принадлежащий проекту мир /Game/... или верните задачу в рабочий процесс Locus Editor. См. раздел Метки с обычными требованиями viewport.
Unreal Editor перезапущен	Снова откройте проект и подключите клиента. Скопируйте свежую конфигурацию, если состояние показывает другую конечную точку или учётный параметр.

Общие проблемы Locus описаны в разделе Устранение неполадок. Остальная поверхность настроек Locus описана в разделе Настройки.