MCP Entegrasyonu

Locus MCP Entegrasyonu, Unreal Editor çalışırken uyumlu bir MCP istemcisinin desteklenen Locus Notları, Belgeleri, Pinleri ve Locus durumuyla çalışmasını sağlar. İsteğe bağlıdır ve varsayılan olarak devre dışıdır.

Locus otonom bir yapay zekâ asistanı içermez. Yapay zekâ iş akışını bağlı MCP istemciniz gerçekleştirir ve desteklenen Locus araçlarını ne zaman kullanacağına karar verir.

Bağlanmadan önce

Gerekenler:

Proje için Locus etkinleştirilmiş ve Unreal Editor açık
Locus ayarlarında MCP Entegrasyonu etkin
aynı makinede çalışan uyumlu bir MCP istemcisi

Locus uç noktası bilgisayarınızda yereldir. Locus her MCP istemcisiyle veya gelecekteki her istemci sürümüyle uyumluluk iddiasında bulunmaz. OpenAI Codex, Claude Code ve Gemini CLI için başlangıç ön ayarlarının yanı sıra diğer uyumlu Streamable HTTP MCP istemcileri için genel bir seçenek sunar. Bu ön ayarlar aynı Locus MCP sunucusunu ve aynı 18 aracı yapılandırır; ayrı yapay zekâ entegrasyonları değildir.

Gerçek istemcilerle sürüm doğrulamasında Codex CLI 0.147.0, Claude Code 2.1.228 ve Gemini CLI 0.55.1 kullanılmıştır. Bunları kalıcı uyumluluk garantileri değil, test edilmiş sürümler olarak değerlendirin.

İstemci bağlama

Unreal Editor’da Editor Tercihleri > Eklentiler > Locus yolunu, ardından MCP Entegrasyonu bölümünü açın.
MCP’yi Etkinleştir seçeneğini açın ve durumun Çalışıyor - istemci bekleniyor göstermesini bekleyin.
Bağlantı altında uygun İstemci Biçimini seçin: OpenAI Codex, Claude Code, Gemini CLI veya Genel Streamable HTTP MCP.
Yapılandırmayı Kopyala’yı seçin.
Kopyalanan yapılandırmayı MCP istemcinizin normal yapılandırma konumuna veya kurulum akışına yapıştırıp bağlanın.
Locus’a dönüp durumun İstemci bağlandı gösterdiğini doğrulayın.

Kopyalanan yapılandırma geçerli uç nokta ve kimlik bilgisi için doğruluk kaynağıdır. İstemciniz Locus’un sunmadığı bir biçim gerektirmedikçe bağlantı yapılandırmasını elle yazmayın.

OpenAI Codex

Codex için OpenAI Codex ve Yapılandırmayı Kopyala’yı seçin. Kopyalanan TOML’yi normal MCP kurulum akışıyla Codex’e ekleyin; bağlanmadan önce gerekiyorsa Codex’i yeniden yükleyin veya başlatın. Codex’in MCP sunucusu listesinden Locus sunucusunu doğrulayın. Unreal Engine 5.8 için Unreal Engine 5.8’de Locus’u Unreal MCP ile kullanma bölümüne bakın.

Claude Code

Claude Code için Locus, projeye ait yerel ve kullanıcıya özel kapsamla resmî HTTP MCP kayıt komutunu kopyalar. Kopyalanan komutu normal bir terminalde çalıştırın. Kimlik bilgisi içeren, paylaşılan proje .mcp.json dosyası oluşturmaz.

Gemini CLI

Gemini CLI için Locus, resmî HTTP MCP kayıt komutunu --scope user ile kopyalar. Bu, kaynak denetimine girebilecek bir proje .gemini/settings.json dosyası üretmek yerine sunucu girdisini ve yerel kimlik bilgisini kullanıcının özel Gemini yapılandırmasında saklar. Bunun karşılığında Locus girdisi bu kullanıcı için projeler arasında kullanılabilir olur; dolayısıyla farklı etkin uç noktası veya kimlik bilgisi olan bir projeye geçerken yeni bir yapılandırma kopyalayın.

Locus, Gemini’nin --trust seçeneğini eklemez. Gemini’nin normal araç onay politikası yürürlükte kalır.

Genel Streamable HTTP MCP

Uyumlu istemci, desteklenen istemciye özgü biçimlerden biri yerine uç nokta ve Authorization başlığı gerektiriyorsa Genel Streamable HTTP MCP’yi seçin. İstemcinin özel yapılandırma rehberini izleyin; sakladığınız not veya örneklerde Bearer <LOCAL_LOCUS_CREDENTIAL> gibi yer tutucular kullanın.

Unreal Engine 5.8’de Locus’u Unreal MCP ile kullanma

Unreal Engine 5.8’in yerleşik Unreal MCP’si ile Locus MCP, bağımsız MCP sunucuları olarak yan yana çalışabilir. Locus, Unreal MCP’ye bağlı değildir.

Aşağıdaki doğrulanmış kurulum Codex kullanır. Bu, istemciye özgü bir örnektir; bağımsız sunucu özelliğinin yalnızca Codex’e ait olduğu anlamına gelmez.

Codex örneği

Her iki sunucuyu yapılandırma

Unreal Engine 5.8’de Unreal MCP, All Toolsets, Terminal ve Locus eklentilerini etkinleştirin. Unreal MCP sunucusunun etkin olduğundan ve otomatik başlayacak şekilde ayarlandığından emin olun.
Unreal konsolunda şunu çalıştırın:
```
ModelContextProtocol.GenerateClientConfig Codex
```
Unreal, Codex yapılandırmasını şu konumda oluşturur:
```
<Project>/.codex/config.toml
```
Unreal’da Editor Preferences > Plugins > Locus > MCP Integration bölümünü açın. Locus MCP sunucusunu etkinleştirin, ardından Copy Connection Configuration > OpenAI Codex (config.toml) seçeneğini seçin.
Oluşturulan Locus MCP bloğunu <Project>/.codex/config.toml içindeki Unreal tarafından oluşturulan MCP yapılandırmasının altına yapıştırın. Locus URL’lerini, üst bilgilerini veya kimlik bilgilerini elle yeniden oluşturmayın; kopyalanan blok geçerli bağlantı yapılandırmasıdır.

Dosyada her iki MCP sunucusu girdisi de bulunmalıdır:

unreal-mcp
locus

Codex’i başlatma ve bağlantıyı doğrulama

Proje kökünde Unreal Engine Terminal’i açın ve şunu çalıştırın:

codex

Codex’ten kullanılabilir MCP sunucularını denetlemesini isteyin:

Check which MCP servers are available to you.

Listede unreal-mcp ve locus görünmelidir. Ardından her entegrasyonu ayrı ayrı test edin:

Use Unreal MCP to inspect my currently selected actor.

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

Bağlantıyı yerel ve özel tutun

Locus yalnızca yerel loopback arabirimini dinler; bu nedenle MCP uç noktasına yalnızca aynı makineden erişilebilir. Oluşturulan, kullanıcıya ait yerel bearer kimlik bilgisi istemcinin kimliğini doğrular.

Yapılandırmayı Kopyala, kimlik bilgisi içeren metni üreten açık eylemdir. Kopyalanan yapılandırmayı hassas kabul edin ve yalnızca güvendiğiniz istemciye yapıştırın. Dokümantasyona, sorun raporlarına, ekran görüntülerine, sohbet mesajlarına veya kaynak denetimindeki yapılandırmaya dahil etmeyin. Locus kimlik bilgisini Ayarlar’da bilerek göstermez veya günlüklere yazmaz. Açığa çıktığını düşünüyorsanız Gelişmiş > Kimlik Bilgisini Yeniden Oluştur… seçeneğini kullanın, ardından istemciye yeni bir yapılandırma kopyalayın.

MCP’yi Etkinleştir seçeneğini kapatmak Locus MCP erişimini durdurur. Unreal Editor’ı kapatmak da etkin Locus MCP uç noktasını sonlandırır. Daha geniş yerel içerik ve harici istemci gizlilik sınırı için Gizlilik ve Geri Bildirim sayfasına bakın.

İzinleri bilinçli seçin

Ayar	İzin verdiği işlemler
Salt Okunur	Varsayılan. İstemciler desteklenen okuma işlemlerini kullanabilir ancak desteklenen değişiklik işlemleri reddedilir. Değişikliklere İzin Ver kapalıyken durum özeti bunu `ReadOnly` olarak gösterir.
Değişikliklere İzin Ver	Desteklenen oluşturma, güncelleme, arşivleme ve yorum işlemlerini etkinleştirir. Yalnızca bağlı istemcinin Locus içeriğini değiştirmesini istediğinizde açın. Unreal projesinde keyfî değişiklik yapma izni vermez.

Özel içerik ayrıca korunur. Özel Notlara ve Pinlere İzin Ver varsayılan olarak kapalıdır; MCP’yi veya Değişikliklere İzin Ver’i etkinleştirmek bunu otomatik olarak açmaz. Yalnızca bağlı istemcinin kullanıcıya ait yerel Özel Notlara ve Pinlere erişmesi gerektiğinde açın. Belgeler her zaman projeye aittir ve Özel kapsamı yoktur.

İstemcilerin yapabilecekleri

Locus 18 MCP aracı sunar. Araçlar MCP protokol ayrıntısına göre değil, destekledikleri iş türüne göre gruplandırılır.

Grup	Araçlar	Desteklenen iş
Altyapı (2)	`locus.get_status`, `locus.get_capabilities`	Locus durumunu, izinleri ve kullanılabilir yetenekleri kontrol etme.
Notlar (6)	`locus.list_notes`, `locus.get_note`, `locus.search_notes`, `locus.create_note`, `locus.update_note`, `locus.archive_note`	Notları bulma, okuma, oluşturma, güncelleme ve arşivleme.
Belgeler (5)	`locus.list_documents`, `locus.get_document`, `locus.search_documents`, `locus.create_document`, `locus.update_document`	Projeye ait Markdown Belgelerini bulma, okuma, oluşturma ve güncelleme. MCP üzerinden yeniden adlandırma, taşıma ve silme kullanılamaz.
Pinler (5)	`locus.list_pins`, `locus.get_pin`, `locus.create_pin`, `locus.update_pin`, `locus.add_pin_comment`	Pinleri bulma, okuma, oluşturma, güncelleme ve Pinlere yorum ekleme. MCP üzerinden Pin silme ve arşivleme kullanılamaz.

Okuma araçları Salt Okunur durumda kullanılabilir. Desteklenen oluşturma, güncelleme, arşivleme ve yorum araçları Değişikliklere İzin Ver gerektirir. Kaynak denetimi ve içerik doğrulama kuralları dahil mevcut Locus önlemleri uygulanmaya devam eder.

MCP ile oluşturulan Belgeler, Editor’da oluşturulan Belgelerle aynı ertelenmiş ekleme iş akışını izler: yerel ve İzlenmiyor olarak başlar. Locus’ta düzenleyin, yeniden adlandırın, taşıyın veya içeriklerini değiştirin; son yol hazır olduğunda açıkça Ekleme İçin İşaretle’yi kullanın. MCP, Belge yeniden adlandırma, taşıma, silme veya Ekleme İçin İşaretle araçları sunmaz.

Belgeler sunum kökleri

MCP, Belgeler çalışma alanındaki iki sunum kökünü de anlar. Her ikisi tek <Project>/ProjectDocuments/ deposunun görünümleridir:

Locus Belgeleri, ayrılmış Content/... eşlemesinin dışındaki normal Belgeleri içerir. Design/Combat.md gibi bir sunum yolunda Belge kimliği de Design/Combat.md olur.
Content Browser, Unreal Content Browser bağlamına yansıtılan Markdown Belgelerini içerir. Characters/Hero.md sunum yolunda Belge kimliği Content/Characters/Hero.md olur ve karşılık gelen /Game/Characters bağlamına eşlenir.

Content Browser Belgeleri harici Markdown dosyaları olarak kalır. UAsset değildir ve /Game/..., Belge kimliği değil sunum bağlamıdır. Belge kimliği, ProjectDocuments köküne göre normalleştirilmiş Markdown yoludur.

locus.list_documents ve locus.search_documents, isteğe bağlı all, locusDocuments veya contentBrowser presentationRoot değerini kabul eder; belirtilmezse varsayılan all olur. Filtreleme dizinlenmiş liste/arama işleminin parçası olarak kalır ve mevcut sıralama ile sayfalama davranışını korur.

Görünür kökü açıkça seçmek için locus.create_document çağrısında locusDocuments veya contentBrowser kullanılabilir. Bu modda relativePath, seçili sunum köküne göredir:

`presentationRoot`	Verilen `relativePath`	Oluşan Belge kimliği
`locusDocuments`	`Design/Combat.md`	`Design/Combat.md`
`contentBrowser`	`Characters/Hero.md`	`Content/Characters/Hero.md`

contentBrowser altında açıkça oluştururken yolun başına Content/ eklemeyin; Locus ayrılmış eşlemeyi bir kez uygular. presentationRoot belirtmeyen mevcut çağrılar önceki yol sözleşmesine göre çalışmaya devam eder; dolayısıyla eski bir Content/Characters/Hero.md girdisi mevcut anlamını korur.

Belge sonuçları şunları ayırır:

relativePath: ProjectDocuments altındaki normalleştirilmiş Belge kimliği
presentationRoot: locusDocuments veya contentBrowser
presentationPath: ilgili sunum kökü altında görünen yol

Kök alanları bağlam sağlar; başka bir depo veya Belge tanımlayıcısı oluşturmaz.

locus.archive_note, Notun yaşam döngüsü durumunu Archived olarak değiştirir; Notu ayrı bir Arşivlenmiş Notlar paneline taşımaz. Locus 1.0 arşivlenmiş Notları normal Notlar çalışma alanında görünür tutar ve özel bir Editor Arşivle/Geri Yükle iş akışı ya da locus.restore_note aracı içermez. Notu MCP üzerinden Open durumuna döndürmek için geçerli revizyon ve status: "open" ile locus.update_note kullanın.

Pin dünya desteği

Desteklenen Pin temeli, açık dünya kimliği ve Unreal dünya uzayı konumu olan, projeye ait kayıtlı bir /Game/... dünyasıdır. Projeye ait kayıtlı World Partition dünyalarındaki temel Pin çalışmaları desteklenir.

Eklenti üzerinden bağlanan haritalar; kaydedilmemiş, geçici, önizleme veya PIE/çalışma zamanı dünyaları; özelleştirilmiş yüklenmemiş World Partition bölgeleri; Actor izleyen veya external actor çapaları; Data Layer’a özgü davranış; Level Instance’lar; geleneksel streaming alt seviyeleri ya da dünya yeniden adlandırma/yönlendirme kurtarması için MCP Pinleri desteklenmez. Bu bağlamlar geçerli destek temelinin dışındadır.

Aynı anda bir istemci

Locus aynı anda yalnızca bir etkin istemci oturumuna izin verir ve araç çağrılarını sırayla tamamlar. Oturum başka bir istemciye aitse, etkin oturum sona erene veya zaman aşımına uğrayana kadar ikinci istemci reddedilebilir ya da meşgul gösterilebilir.

Önce önceki istemciyi kapatın veya bağlantısını kesin; kesintiye uğradıysa kısa süre bekleyip yeniden deneyin. Bu işlem oturumu bırakmazsa MCP Entegrasyonunda Sorun Giderme > Etkin İstemciyi Sıfırla seçeneğini kullanın. MCP’yi yalnızca yerel sunucuyu kurtarmak gerektiğinde devre dışı bırakıp yeniden etkinleştirin.

MCP bağlantısını kesme veya devre dışı bırakma

Kullanımınız bittiğinde istemcinin bağlantısını kesin. Locus MCP erişimini tamamen durdurmak için MCP’yi Etkinleştir seçeneğini kapatın. MCP’yi devre dışı bırakmak Locus içeriğinizi veya yerel kimlik bilgisini silmez; yalnızca yeniden etkinleştirene kadar yerel uç noktayı durdurur.

Bağlantı sorunlarını giderme

Belirti	Yapılacak işlem
MCP devre dışı veya uç nokta yok	Unreal Editor’ı açık tutun, MCP Entegrasyonu’nu açın, MCP’yi Etkinleştir’i açın ve çalışan durumu bekleyin.
İstemci bağlantıyı veya kimlik bilgisini reddediyor	Yeni bir yapılandırma kopyalayın. Yerel portu değiştirdikten veya kimlik bilgisini yeniden oluşturduktan sonra bunu yapın; daha önce kopyalanan yapılandırmalar artık çalışmaz.
Başka bir istemci etkin veya Locus meşgul	Diğer istemciyi kapatın, kısa süre bekleyip yeniden deneyin. Etkin İstemciyi Sıfırla’yı yalnızca o istemci artık kullanımda değilse kullanın. Araç çağrısını yeniden denemeden önce devam eden Locus işleminin bitmesini bekleyin.
İstemci içeriği değiştiremiyor	Değişikliklere İzin Ver kapalıdır. Yalnızca izin vermek istediğiniz desteklenen Locus değişiklikleri için etkinleştirin.
Özel Notlar veya Pinler reddediliyor	Özel Notlara ve Pinlere İzin Ver’i ayrıca etkinleştirin. Yalnızca Değişikliklere İzin Ver, Özel erişim sağlamaz.
Pin isteği desteklenmeyen dünya bağlamı bildiriyor	Projeye ait kayıtlı bir `/Game/...` dünyası kullanın veya görevi Locus Editor iş akışına geri taşıyın. Normal Viewport gereksinimleri için Pinler sayfasına bakın.
Unreal Editor yeniden başladı	Projeyi yeniden açıp istemciyi tekrar bağlayın. Durum farklı bir uç nokta veya kimlik bilgisi gösteriyorsa yeni bir yapılandırma kopyalayın.

Genel Locus sorunları için Sorun Giderme, Locus ayarlarının geri kalanı için Ayarlar sayfasına bakın.