MCP Araçları

Her proje, kendi belgeleriyle sınırlı olarak aynı üç aracı yayınlar. Salt okunurdurlar: bir ajan arayabilir ve okuyabilir, asla yazamaz.

Bir istemci bağlandığında, sunucu ayrıca projenin adını, kaç belge ve parça tuttuğunu ve hangi aracın ne zaman kullanılacağını anlatan instructions gönderir — ajana hangi aracı çağıracağını söylemeniz yerine yalnızca bir soru sorabilmenizin nedeni budur.

---

search_docs

Projenin parçaları üzerinde hibrit arama: anlam ve birebir sözcük aynı anda aranır ve sıralarıyla birleştirilir; böylece HALYARD_DISPATCH_TIMEOUT da en az bir soru kadar kolay bulur sayfasını.

Son üçü aramayı daraltır ve hepsi isteğe bağlıdır; verilmediklerinde her zaman olduğu gibi her şey aranır. Bilinmeyen bir source ya da version, boş bir sayfayla değil, bu projenin gerçekten sahip olduklarıyla yanıtlanır — bir sıralama ve bir latest yoktur.

Her biri dosya yolu, başlık kırıntısı ve benzerlik skoruyla birlikte sıralı alıntılar döndürür:

Found 3 results for "how do I rotate the signing key" in project "handbook":

### 1. runbooks/keys.md — Runbooks > Signing keys > Rotation (score 0.871)
Rotate the signing key by generating a new pair with `keytool`, publishing the public
half to the JWKS endpoint, and keeping the previous key active for 24 hours…

### 2. security/policy.md — Security > Key material (score 0.842)
…

Kırıntı gömülen şeyin bir parçası olduğu için, bir başlık gibi ifade edilmiş bir soru genelde doğru bölümü doğrudan bulur.

Her alıntı, kendinden önceki ve sonraki parçayla birlikte, başında ve sonunda bir … işaretlenerek render edilir, bu yüzden bir agent bir parça sınırının ortadan böldüğü cümleyi görmek için genelde bir read_document çağrısı harcamak zorunda kalmaz. Tek bir belgeden en fazla iki alıntı gelir, çünkü bir sayfanın beş ardışık parçası olan beş sonuç soruyu bir kez cevaplar ve dört başka sayfanın yerini kapatır. Tüm yanıt SEARCH_MAX_RESULT_CHARS ile sınırlıdır ve kestiğinde bunu söyler — bkz. Yapılandırma.

Sonuç yerine gelen özel yanıtlar:

• Projede henüz hiçbir şey indekslenmemiş → bunu söyleyen ve onu indekslemenizi isteyen bir mesaj.
• Proje farklı bir embedding modeliyle indekslenmiş → kendinden emin ama yanlış eşleşmeler yerine, yeniden indekslemenizi isteyen bir hata.
• Hiçbir şey ilgi eşiğini geçmiyor, varsayılan olarak 0.82 cosine similarity → bulduğu en az kötü sonuç yerine iyi eşleşme yok ve list_topics’e bir yönlendirme. Sayıların ne anlama geldiği için bkz. Gömme Modelleri.

list_topics

Bir çağrı limit kadar belge döndürür (aksi belirtilmedikçe 200, en fazla 1000). Sayfayı dizine göre gruplayarak döndürür:

Project "handbook": 84 documents, 412 chunks
Sources (the first path segment): policies (local), api (git: API reference), notion (notion)

policies/ — 12 documents, 61 chunks
  • policies/onboarding.md — Onboarding (9 chunks)
  • policies/travel.md — Travel policy (4 chunks)

api/reference/ — 31 documents, 180 chunks
  • api/reference/auth.md — Authentication (12 chunks)
  …

Aramadan önce neyin var olduğunu bilmek isteyen bir ajan için, ve gerçekten neyin indekslendiğini kontrol etmek istediğinizde sizin için kullanışlıdır. Sayfadan sonra daha fazla belge kaldığında, yanıt bir next_cursor değeriyle ve ajana bu değeri cursor olarak vererek list_topics’i tekrar çağırmasını söyleyen bir satırla biter.

read_document

İndekslenmiş tek bir dosyanın Markdown’ını döndürür:

File: api/reference/auth.md
Title: Authentication

---

# Authentication
…

Bir arama sonucundan aldığınız bir kırıntıyı heading olarak verirseniz yalnız o bölümü ve altındaki alt bölümleri, from/to verirseniz bir parça aralığını okur — ikisi de bütün bir sayfadan çok daha ucuzdur.

Yalnızca o proje için indekslenmiş yollar sunulur — asla keyfi bir dosya sistemi yolu değil. Çıktı max_tokens ile sınırlıdır, embedding modelinin kendi tokenizer’ıyla sayılır, ve nerede kestiğini, kalanını nasıl isteyeceğinizi söyler.

Bir belgeyi okumak bir dosyayı okumakla aynı şey değildir. read_document, bu sunucunun indekslediği, parçaların yanında saklanan metni sunar ve dosya sistemine hiç dokunmaz. Bu yüzden bir belge, dosyası yeniden adlandırıldıktan, git checkout’u yeniden klonlandıktan ya da tüm kaynak dizini unmount edildikten sonra bile okunabilir kalır, ve hiç indekslenmemiş bir sayfa yanlışlıkla asla sunulamaz. Metin, indeksleyicinin dönüştürdüğü haliyle saklanır, ki read_document ile search_docs’un bir sayfanın ne dediği konusunda hiçbir zaman anlaşmazlığa düşmemesini sağlayan da budur; bedeli, bir Obsidian notunun özgün [[wikilink]] sözdiziminin MCP üzerinden okunamaması, yalnızca dönüştüğü Markdown bağlantısının okunabilmesidir. Daha eski bir sürümle indekslenmiş belgeler hiçbir saklanmış metin taşımaz ve bir sonraki indeksleme çalıştırmasına kadar diskten okunur — eksik bir dosyanın hâlâ bir hata sayıldığı tek durum budur.

---

Yollar ve kaynaklar

Her yol, geldiği kaynağın adıyla başlar:

handbook/install.md      ← source "handbook"
api-repo/install.md      ← source "api-repo"

Bir yanıtın nereden geldiğini size söyleyen ve iki kaynağın aynı dosya adını taşımasına izin veren şey budur. Bkz. Belge Kaynakları.

Daha iyi yanıtlar almak

• Soru sorun, ama tanımlayıcılar da işe yarar. Arama hibrittir; bir ortam değişkeni, bir header ya da bir hata kodu sayfasını birebir sözcükle bulur. Geri kalan her şey içinse tam bir soru, anlam yarısına iki kelimeden daha fazla sinyal taşır.
• Soruyu sayfanın yazıldığı dilde sorun. Varsayılan model Türkçe dahil 100 dili kapsar ama getirme diller arasında geçiş yapmaz — bu, ölçülmüş bir model sınırıdır, açılıp kapanan bir ayar değil.
• Cevabın nerede olduğunu biliyorsanız daraltın. source ve path_prefix aramayı tek bir kaynağa ya da tek bir dizine, version ise tek bir sürüme indirir; böylece aynı dokümantasyonun v2 ve v3 sürümleri birbirinin yerine cevap vermez.
• limit’i yükseltin bir konu birçok dosyaya yayılmışsa — bir ajan 20’ye kadar alıntı isteyebilir.
• Dokümantasyonunuzu başlıklarla yapılandırın. Parçalar başlıklarda kesilir ve kırıntılarını taşır, bu yüzden iyi başlıklar getirmeyi doğrudan iyileştirir.
• İlgisiz bilgi kümelerini ayrı projelerde tutun. Bir endpoint bir el kitabını, bir API referansını ve bir günlüğü karıştırdığında hassasiyet düşer.
• Ajana dosya yolunu belirtmesini söyleyin. Sunucu zaten bunu istiyor; kendi prompt’unuzda pekiştirmeye değer.

Yapılandırılmış çıktı

MCP_STRUCTURED_OUTPUT=1 ayarlandığında her araç aynı metnin yanında bir outputSchema da yayınlar ve structuredContent döndürür (MCP 2025-06-18). Bu varsayılan olarak kapalıdır: yapılandırılmış içeriği okuyan bir istemci metni okumayı bırakabilir, ve Claude Code bir sonuç structuredContent taşıdığı anda tam olarak bunu yapar (anthropics/claude-code#55677, #79944), bu yüzden modele alıntıların nasıl okunacağını anlatan düz metin ona yalnızca bir JSON alanı olarak ulaşır. Bayrak kapalıyken, her araç tanımı ve her yanıt, yapılandırılmış çıktı var olmadan önceki haliyle byte byte aynıdır. Bkz. Yapılandırma.

Bu ayardan bağımsız olarak, her projenin indekslenmiş belgeleri aynı zamanda MCP resource’larıdır (contextator://<project>/<source>/<path>), aynı yetkilendirmenin arkasında listelenir ve okunur, ve hiçbir zaman read_document’ın kendisinin ulaşabileceğinin ötesine geçmez.

Araçların yapamadıkları

• Herhangi bir şeyi yazmak, düzenlemek ya da silmek.
• Başka bir projenin belgelerini görmek.
• İndekslenmemiş dosyaları okumak.
• Bir indeksleme çalışması tetiklemek. İndeksleme bir operatör eylemidir — pano, API ya da webhook.