# MCP Araçları

> Her projenin yayınladığı üç salt okunur araç — search_docs, list_topics ve read_document — argümanları, limitleri ve yapamadıkları.

- Güncelleme: 2026-09-21
- Kaynak: https://contextator.com/tr/docs/mcp-tools/
- Dil: tr-TR
- Yazar: Muhammet Şafak

---
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ı.

| Argüman | Tür | Varsayılan |
|----------|------|---------|
| `query` | string (1–2000 karakter) | zorunlu |
| `limit` | integer 1–20 | 5 |
| `source` | string — tek bir kaynak adı, `list_topics`'in gösterdiği yolların ilk segmenti | her kaynak |
| `path_prefix` | string — ör. `handbook/operations` | projenin tamamı |
| `version` | string — projenin verdiği hâliyle tam bir sürüm etiketi, ör. `v3` | her sürüm |

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](/tr/docs/configuration/).

**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](/tr/docs/embedding-models/).

## `list_topics`

| Argüman | Tür | Varsayılan |
|----------|------|---------|
| `cursor` | string — önceki bir çağrının bittiği `next_cursor` | listenin başı |
| `limit` | integer 1–1000 | 200 |

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`

| Argüman | Tür | Varsayılan |
|----------|------|---------|
| `path` | string — tam olarak `search_docs` ya da `list_topics`'in gösterdiği gibi | zorunlu |
| `heading` | string — bir arama sonucundan alınmış başlık kırıntısı, ör. `Guide > Install > Docker` | belgenin tamamı |
| `from`, `to` | integer — bir parça aralığı, 0 tabanlı ve dahil | belgenin tamamı |
| `max_tokens` | integer 200–20000 | 4000 |

İ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ı](/tr/docs/document-sources/).

## 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](https://github.com/anthropics/claude-code/issues/55677),
[#79944](https://github.com/anthropics/claude-code/issues/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](/tr/docs/configuration/).

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.