Integracja MCP

Integracja MCP Locus pozwala zgodnemu klientowi MCP pracować z obsługiwanymi Notatkami, Dokumentami, Pinezkami i stanem Locus, gdy Unreal Editor jest uruchomiony. Jest opcjonalna i domyślnie wyłączona.

Locus nie zawiera autonomicznego asystenta AI. Podłączony klient MCP wykonuje przepływ pracy AI i decyduje, kiedy użyć obsługiwanych narzędzi Locus.

Przed połączeniem

Potrzebujesz:

otwartego Unreal Editor z włączonym Locus dla projektu
włączonej Integracji MCP w ustawieniach Locus
zgodnego klienta MCP działającego na tym samym komputerze

Punkt końcowy Locus jest lokalny dla komputera. Locus nie deklaruje zgodności z każdym klientem MCP ani każdą przyszłą wersją klienta. Locus udostępnia ustawienia początkowe dla OpenAI Codex, Claude Code i Gemini CLI, a także opcję ogólną dla innych zgodnych klientów MCP Streamable HTTP. Te ustawienia konfiguruje ten sam serwer MCP Locus i te same 18 narzędzi; nie są osobnymi integracjami AI.

Walidacja wydania z rzeczywistymi klientami użyła Codex CLI 0.147.0, Claude Code 2.1.228 i Gemini CLI 0.55.1. Traktuj je jako wersje przetestowane, a nie stałą gwarancję zgodności.

Łączenie klienta

W Unreal Editor otwórz Editor Preferences > Plugins > Locus, a następnie MCP Integration.
Włącz Enable MCP i zaczekaj, aż stan pokaże Running - waiting for client.
W sekcji Connection wybierz odpowiedni Client Format: OpenAI Codex, Claude Code, Gemini CLI albo Generic Streamable HTTP MCP.
Wybierz Kopiuj konfigurację.
Wklej skopiowaną konfigurację do zwykłej lokalizacji konfiguracji klienta MCP lub jego procesu konfiguracji, a następnie połącz klienta.
Wróć do Locus i potwierdź, że stan pokazuje Client connected.

Skopiowana konfiguracja jest źródłem prawdy dla bieżącego punktu końcowego i poświadczenia. Nie twórz konfiguracji połączenia ręcznie, chyba że klient wymaga formatu, którego Locus nie oferuje.

OpenAI Codex

W przypadku Codex wybierz OpenAI Codex i użyj Kopiuj konfigurację. Dodaj skopiowany TOML do Codex za pomocą zwykłego procesu konfiguracji MCP, a następnie przeładuj lub uruchom ponownie Codex, jeśli wymaga tego przed połączeniem. Potwierdź serwer Locus na liście serwerów MCP Codex. W przypadku Unreal Engine 5.8 zobacz sekcję Używanie Locus z Unreal MCP w Unreal Engine 5.8.

Claude Code

W przypadku Claude Code Locus kopiuje oficjalne polecenie rejestracji HTTP MCP z zakresem lokalnym dla projektu i prywatnym dla użytkownika. Uruchom skopiowane polecenie w zwykłym terminalu. Nie tworzy ono współdzielonego pliku projektu .mcp.json zawierającego poświadczenie.

Gemini CLI

W przypadku Gemini CLI Locus kopiuje oficjalne polecenie rejestracji HTTP MCP z --scope user. Zapisuje to wpis serwera i lokalne poświadczenie w prywatnej konfiguracji Gemini użytkownika, zamiast generować projektowy plik .gemini/settings.json, który mógłby trafić do kontroli wersji. Wadą jest dostępność wpisu Locus dla tego użytkownika w wielu projektach, dlatego przy przełączaniu się na projekt z innym aktywnym punktem końcowym lub poświadczeniem skopiuj świeżą konfigurację.

Locus nie dodaje opcji Gemini --trust. Zwykła polityka potwierdzania narzędzi Gemini pozostaje aktywna.

Ogólny MCP Streamable HTTP

Wybierz Generic Streamable HTTP MCP, gdy zgodny klient potrzebuje punktu końcowego i nagłówka Authorization, a nie jednego z obsługiwanych formatów właściwych dla klienta. Postępuj zgodnie z prywatnymi wskazówkami konfiguracji tego klienta i używaj symboli zastępczych, takich jak Bearer <LOCAL_LOCUS_CREDENTIAL>, w zachowywanych notatkach lub przykładach.

Używanie Locus z Unreal MCP w Unreal Engine 5.8

Wbudowane Unreal MCP w Unreal Engine 5.8 i Locus MCP mogą działać równolegle jako niezależne serwery MCP. Locus nie zależy od Unreal MCP.

Zweryfikowana konfiguracja poniżej używa Codex. To przykład specyficzny dla klienta, a nie stwierdzenie, że ta funkcja niezależnych serwerów jest dostępna wyłącznie dla Codex.

Przykład Codex

Konfigurowanie obu serwerów

W Unreal Engine 5.8 włącz Unreal MCP, All Toolsets, Terminal i Locus. Upewnij się, że serwer Unreal MCP jest włączony i skonfigurowany do automatycznego uruchamiania.

W konsoli Unreal uruchom:

ModelContextProtocol.GenerateClientConfig Codex

Unreal generuje konfigurację Codex w lokalizacji:

<Project>/.codex/config.toml

W Unreal otwórz Editor Preferences > Plugins > Locus > MCP Integration. Włącz serwer MCP Locus, a następnie wybierz Copy Connection Configuration > OpenAI Codex (config.toml).
Wklej wygenerowany blok MCP Locus poniżej konfiguracji MCP wygenerowanej przez Unreal w <Project>/.codex/config.toml. Nie odtwarzaj ręcznie adresów URL, nagłówków ani poświadczeń Locus; skopiowany blok jest bieżącą konfiguracją połączenia.

Plik powinien zawierać oba wpisy serwerów MCP:

unreal-mcp
locus

Uruchamianie Codex i sprawdzanie połączenia

Otwórz terminal Unreal Engine w katalogu głównym projektu i uruchom:

codex

Poproś Codex o sprawdzenie dostępnych serwerów MCP:

Check which MCP servers are available to you.

Powinny zostać wyświetlone unreal-mcp i locus. Następnie przetestuj każdą integrację osobno:

Use Unreal MCP to inspect my currently selected actor.

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

Utrzymuj lokalne i prywatne połączenie

Locus nasłuchuje wyłącznie na lokalnym interfejsie loopback, dlatego punkt końcowy MCP jest dostępny tylko na tym samym komputerze. Wygenerowane lokalne dla użytkownika poświadczenie bearer uwierzytelnia klienta.

Kopiuj konfigurację jest jawną akcją, która tworzy tekst zawierający poświadczenie. Traktuj skopiowaną konfigurację jako poufną: wklejaj ją tylko do zaufanego klienta. Nie umieszczaj jej w dokumentacji, zgłoszeniach, zrzutach ekranu, wiadomościach ani konfiguracji kontrolowanej przez wersję. Locus nie wyświetla celowo poświadczenia w Ustawieniach ani nie emituje go w logach. Jeśli uważasz, że zostało ujawnione, użyj Advanced > Regenerate Credential…, a następnie skopiuj świeżą konfigurację do klienta.

Wyłączenie Enable MCP zatrzymuje dostęp MCP Locus. Zamknięcie Unreal Editor również kończy aktywny punkt końcowy MCP Locus. Szerszą granicę prywatności lokalnej zawartości i zewnętrznego klienta opisuje Prywatność i opinie.

Wybieraj uprawnienia świadomie

Ustawienie	Co umożliwia
Tylko do odczytu	Wartość domyślna. Klienci mogą używać obsługiwanych operacji odczytu, ale obsługiwane operacje zmiany są odrzucane. Podsumowanie stanu pokazuje `ReadOnly`, gdy Zezwalaj na zmiany jest wyłączone.
Zezwalaj na zmiany	Włącza obsługiwane operacje tworzenia, aktualizacji, archiwizowania i komentowania. Włącz je tylko wtedy, gdy chcesz, aby podłączony klient modyfikował zawartość Locus. Nie daje ono dowolnego dostępu do modyfikowania projektu Unreal.

Zawartość Prywatna jest chroniona osobno. Zezwalaj na Prywatne notatki i Pinezki jest domyślnie wyłączone i ani włączenie MCP, ani Zezwalaj na zmiany nie nadaje go automatycznie. Włącz je tylko wtedy, gdy podłączony klient powinien mieć dostęp do lokalnych dla użytkownika Prywatnych Notatek i Pinezek. Dokumenty zawsze należą do projektu i nie mają zakresu Prywatne.

Co mogą robić klienci

Locus udostępnia 18 narzędzi MCP. Są pogrupowane według rodzaju obsługiwanej pracy, a nie szczegółów protokołu MCP.

Grupa	Narzędzia	Obsługiwana praca
Infrastructure (2)	`locus.get_status`, `locus.get_capabilities`	Sprawdzanie stanu Locus, uprawnień i dostępnych możliwości.
Notes (6)	`locus.list_notes`, `locus.get_note`, `locus.search_notes`, `locus.create_note`, `locus.update_note`, `locus.archive_note`	Znajdowanie, odczytywanie, tworzenie, aktualizowanie i archiwizowanie Notatek.
Documents (5)	`locus.list_documents`, `locus.get_document`, `locus.search_documents`, `locus.create_document`, `locus.update_document`	Znajdowanie, odczytywanie, tworzenie i aktualizowanie należących do projektu Dokumentów Markdown. Zmiana nazwy, przenoszenie i usuwanie nie są dostępne przez MCP.
Pins (5)	`locus.list_pins`, `locus.get_pin`, `locus.create_pin`, `locus.update_pin`, `locus.add_pin_comment`	Znajdowanie, odczytywanie, tworzenie, aktualizowanie i komentowanie Pinezek. Usuwanie i archiwizowanie Pinezek nie są dostępne przez MCP.

Narzędzia odczytu pozostają dostępne w trybie Tylko do odczytu. Obsługiwane narzędzia tworzenia, aktualizacji, archiwizowania i komentowania wymagają Zezwalaj na zmiany. Nadal obowiązują istniejące zabezpieczenia Locus, w tym zasady kontroli wersji i walidacji zawartości.

Dokumenty utworzone przez MCP korzystają z tej samej odroczonej ścieżki dodawania co Dokumenty utworzone w edytorze: zaczynają lokalnie i jako Nieśledzone. Organizuj je, zmieniaj nazwę, przenoś lub edytuj w Locus, a następnie jawnie użyj Oznacz do dodania, gdy ostateczna ścieżka będzie gotowa. MCP nie udostępnia narzędzi zmiany nazwy, przenoszenia, usuwania ani oznaczania Dokumentu do dodania.

Korzenie prezentacji Dokumentów

MCP rozumie te same dwa korzenie prezentacji, które pokazuje obszar roboczy Dokumentów. Oba są widokami jednego repozytorium <Project>/ProjectDocuments/:

Dokumenty Locus zawierają zwykłe Dokumenty poza zarezerwowanym odwzorowaniem Content/.... Ścieżka prezentacji taka jak Design/Combat.md ma tę samą autorytatywną ścieżkę: Design/Combat.md.
Przeglądarka zawartości zawiera Dokumenty Markdown odwzorowane w kontekście Przeglądarki zawartości Unreal. Ścieżka prezentacji taka jak Characters/Hero.md ma autorytatywną ścieżkę Dokumentu Content/Characters/Hero.md i odwzorowuje się na odpowiadający kontekst /Game/Characters.

Dokumenty Przeglądarki zawartości pozostają zewnętrznymi plikami Markdown. Nie są UAssetami, a /Game/... jest kontekstem prezentacji, a nie tożsamością Dokumentu. Znormalizowana ścieżka Markdown względem ProjectDocuments pozostaje autorytatywna.

locus.list_documents i locus.search_documents przyjmują opcjonalną wartość presentationRoot równą all, locusDocuments lub contentBrowser; pominięcie wartości domyślnie wybiera all. Filtrowanie pozostaje częścią indeksowanej operacji listowania/wyszukiwania i zachowuje istniejące zasady kolejności i stronicowania.

locus.create_document przyjmuje locusDocuments lub contentBrowser, gdy wywołujący chce jawnie wybrać widoczny korzeń. W tym trybie relativePath jest względna względem wybranego korzenia prezentacji:

`presentationRoot`	Podana wartość `relativePath`	Utworzona ścieżka autorytatywna
`locusDocuments`	`Design/Combat.md`	`Design/Combat.md`
`contentBrowser`	`Characters/Hero.md`	`Content/Characters/Hero.md`

Podczas jawnego tworzenia pod contentBrowser nie dodawaj prefiksu Content/; Locus stosuje zarezerwowane odwzorowanie raz. Istniejący wywołujący, który pomija presentationRoot, zachowuje wcześniejszą umowę autorytatywnej ścieżki, więc dane Content/Characters/Hero.md zachowują dotychczasowe znaczenie.

Wyniki Dokumentów rozróżniają:

relativePath: autorytatywna znormalizowana tożsamość pod ProjectDocuments
presentationRoot: locusDocuments lub contentBrowser
presentationPath: ścieżka widoczna pod tym korzeniem prezentacji

Pola korzenia zapewniają kontekst; nie wprowadzają innego repozytorium ani identyfikatora Dokumentu.

locus.archive_note zmienia stan cyklu życia Notatki na Archived; nie przenosi Notatki do osobnego panelu Archived Notes. Locus 1.0 pozostawia zarchiwizowane Notatki widoczne w zwykłym obszarze roboczym Notatek i nie ma dedykowanego edytorowego przepływu Archive/Restore ani narzędzia locus.restore_note. Aby przywrócić Notatkę do stanu Open przez MCP, użyj locus.update_note z bieżącą rewizją i status: "open".

Obsługa świata Pinezek

Obsługiwaną podstawą Pinezek jest zapisany należący do projektu świat /Game/... z jawną tożsamością świata i położeniem w przestrzeni świata Unreal. Obsługiwana jest podstawowa praca z zapisanym należącym do projektu World Partition.

Nie polegaj na Pinezkach MCP dla map zamontowanych przez wtyczki; niezapisanych, tymczasowych, podglądowych lub PIE/uruchomieniowych światów; wyspecjalizowanych wyładowanych regionów World Partition; kotwic śledzących aktora lub zewnętrznego aktora; zachowania zależnego od Data Layer; Level Instances; tradycyjnych podpoziomów strumieniowania ani odzyskiwania zmiany nazwy/przekierowania świata. Te konteksty są poza bieżącą obsługiwaną podstawą.

Jeden klient naraz

Locus dopuszcza jedną aktywną autoryzowaną sesję klienta i wykonuje wywołania narzędzi pojedynczo. Jeśli inny klient posiada sesję, drugi klient może zostać odrzucony lub otrzymać stan zajętości, dopóki aktywna sesja się nie zakończy lub nie wygaśnie.

Najpierw zamknij lub odłącz poprzedniego klienta, krótko odczekaj, jeśli został przerwany, a następnie spróbuj ponownie. Jeśli to nie zwolni sesji, użyj Troubleshooting > Reset Active Client w Integracji MCP. Wyłączaj i włączaj MCP ponownie tylko wtedy, gdy jest to konieczne do odzyskania lokalnego serwera.

Odłączanie lub wyłączanie MCP

Odłącz klienta po zakończeniu pracy. Aby całkowicie zatrzymać dostęp MCP Locus, wyłącz Enable MCP. Wyłączenie MCP nie usuwa zawartości Locus ani lokalnego poświadczenia; zatrzymuje tylko lokalny punkt końcowy do czasu ponownego włączenia.

Rozwiązywanie problemów z połączeniem

Objaw	Działanie
MCP jest wyłączony lub nie ma punktu końcowego	Pozostaw Unreal Editor otwarty, otwórz MCP Integration, włącz Enable MCP i zaczekaj na stan działania.
Klient odrzuca połączenie lub poświadczenie	Skopiuj świeżą konfigurację. Zrób to po zmianie lokalnego portu lub ponownym wygenerowaniu poświadczenia; starsze skopiowane konfiguracje przestają działać.
Inny klient jest aktywny lub Locus jest zajęty	Zamknij innego klienta, krótko odczekaj i spróbuj ponownie. Użyj Reset Active Client tylko wtedy, gdy klient nie jest już używany. Przed ponowieniem wywołania narzędzia poczekaj na zakończenie trwającej operacji Locus.
Klient nie może zmieniać zawartości	Zezwalaj na zmiany jest wyłączone. Włącz je tylko dla zamierzonych obsługiwanych zmian Locus.
Odmowa dostępu do Prywatnych Notatek lub Pinezek	Włącz osobno Zezwalaj na Prywatne notatki i Pinezki. Samo Zezwalaj na zmiany nie daje dostępu Prywatnego.
Żądanie Pinezki zgłasza nieobsługiwany kontekst świata	Użyj zapisanego należącego do projektu świata `/Game/...` albo przenieś zadanie do przepływu pracy Locus Editor. Zobacz Pinezki dla zwykłych wymagań viewportu.
Unreal Editor został uruchomiony ponownie	Otwórz ponownie projekt i połącz klienta. Skopiuj świeżą konfigurację, jeśli stan pokazuje inny punkt końcowy lub poświadczenie.

Ogólne problemy Locus opisuje strona Rozwiązywanie problemów. Pozostałą powierzchnię ustawień Locus opisuje Ustawienia.