# Araçlar

> Solk MCP sunucusunun okuma ve yazma araçları, parametreleri ve örnek istemleri.

Araçlar REST API'nin üzerinde çalışır: her araç çağrısı ilgili API ucunu sizin hesabınızla çağırır ve aynı kurallar (yetki, görünürlük, aşama kapıları, mükerrer koruması) geçerlidir. İstemciye yalnız sizin kullanabildiğiniz araçlar listelenir:

- `crm.read` kapsamı yoksa okuma, `crm.write` yoksa yazma araçları listede görünmez.
- Lisansta ya da kullanıcınızda kapalı modüllerin araçları (ör. Fuar leadleri modülü kapalıysa ilgili araçlar) listelenmez.

Araçların adları ve açıklamaları modellerin daha iyi anlaması için İngilizcedir; asistanla Türkçe konuşabilirsiniz.

## Okuma araçları

Okuma araçları istemciye `readOnlyHint: true` olarak bildirilir — Claude bunlar için "her zaman izin ver" seçeneği sunar.

| Araç | Açıklama | Parametreler | Örnek istem |
|---|---|---|---|
| `search` | Ad, şehir, telefon ya da e-postayla firma, kişi, fırsat ve fuar leadi arar (en az 2 karakter); 15 karakterlik kayıt kimliğini de çözer. | `query`* | *Kumsal Plastik'i bul* |
| `list_companies` | Firmaları süzgeçlerle listeler: durum (AC / Prospect), sorumlu, şehir, ziyaret durumu ve sayaçlar. | `page`, `query`, `scope` (mine · all), `sort` (name · visit · priority), `status` (AC · Prospect), `visit` (overdue · soon · ok · none) | *Ziyareti geciken aktif müşterilerimi listele* |
| `get_company` | Firma kartının tamamı: kişiler, fırsatlar, son ziyaret ve denemeler, açık aksiyonlar, teklifler, notlar ve e-posta yazışmaları. | `company_id`* | *Alize Paketleme'nin kartını özetle* |
| `list_contacts` | Firmalardaki kişileri listeler. | `query`, `scope` (mine · all) | *Satın alma müdürü unvanlı kişileri göster* |
| `list_opportunities` | Fırsatları listeler: açık (varsayılan), kapalı, müşteri takibi ya da bir aşama; güncelleme, sağlık, değer ya da SLA'ya göre sıralı. | `page`, `query`, `scope` (mine · all), `sort` (update · health · value · sla), `stage` | *Negotiation'daki fırsatları değere göre sırala* |
| `get_opportunity` | Fırsatın tamamı: aşama, değer, olasılık, sağlık, kontrol listesi, BANT, kapı sorunları, ziyaretler, denemeler, teklifler, aşama geçmişi. | `opportunity_id`* | *Streç film fırsatı bir sonraki aşama için neyi bekliyor?* |
| `list_actions` | Açık işler: görevler, ziyaret ve denemelerin sonraki aksiyonları, tarihli proje adımları; her satırda tür + kimlik. | `company_id`, `scope` (mine · all), `state` (today · overdue · soon · open · week) | *Bu hafta geciken aksiyonlarım neler?* |
| `get_action` | Tek aksiyon ya da görev, bağlamıyla (firma, proje, geçmiş). | `id`*, `kind`* (visit · demo · task · step) | *Fiyat listesi görevinin ayrıntısını aç* |
| `list_calendar` | Tarih aralığındaki toplantılar ve aksiyonlardan türeyen takvim girişleri. | `from`, `to` | *Gelecek hafta takvimimde neler var?* |
| `list_email_threads` | Kullanıcıların posta kutularından eşitlenen yazışmalar: bir kaydınkiler ya da gelen kutusu. | `filter` (all · waiting · replied · mine), `query`, `record_id`, `record_type` (customer · opp · visit · demo · task · offer · ticket · contract) | *Yanıt bekleyen müşteri e-postalarını göster* |
| `get_email_thread` | Bir yazışmanın iletileri (görme izni yoksa gizli) ve bağlı kayıtları. | `thread_id`* | *Kuzey Plastik'le son yazışmayı özetle* |
| `get_dashboard` | Pano: aşamalara göre sayı ve değer (ana dövizde), haftalık ziyaret hedefleri, SLA aşımları, sıradaki adımlar. | `scope` | *Satış hattının özetini çıkar* |
| `get_today` | Günüm: bugünün toplantıları ve işleri, gecikenler, son açılan kayıtlar ve bu haftanın aktivitesi. | — | *Bugün ne yapmam gerekiyor?* |
| `list_team` | Etkin kullanıcılar (kimlik, ad, rol, departman) — atama ve sorumlu alanları için. | — | *Ekipte kimler var?* |

`*` zorunlu parametre.

## Yazma araçları

Yazma araçları kayıt oluşturur ya da değiştirir; hiçbiri kayıt silmez (`destructiveHint: false`). Claude her yazma çağrısından önce onay ister.

| Araç | Açıklama | Parametreler | Örnek istem |
|---|---|---|---|
| `create_company` | Firma açar (verilmezse Prospect). Aynı ad varsa reddedilir; benzer adlarda confirm_new gerekir. İsteğe bağlı ilk kişi. | `address`, `city`, `confirm_new`, `contact_email`, `contact_name`, `contact_phone`, `contact_title`, `name`*, `note`, `owner_id`, `phone`, `sector`, `status` (AC · Prospect), `website` | *Anadolu Gıda Ambalaj adında Konya'da yeni bir aday firma aç* |
| `update_company` | Firma alanlarını günceller (yalnız verilenler değişir). | `address`, `city`, `company_id`*, `name`, `note`, `owner_id`, `phone`, `sector`, `status` (AC · Prospect), `visit_period_days`, `website` | *Kuzey Plastik'i aktif müşteri yap ve 30 günde bir ziyaret ayarla* |
| `create_contact` | Firmaya kişi ekler. | `company_id`*, `department`, `email`, `is_main`, `name`*, `note`, `phone`, `title` | *Kuzey Plastik'e Emre Yıldız'ı üretim şefi olarak ekle* |
| `create_opportunity` | Firma için yeni satış projesi açar (ilk aşamadan başlar). | `company_id`*, `competitor`, `name`, `note`, `type`, `value` | *Kuzey Plastik için 'Streç film tedariki' fırsatı aç* |
| `change_opportunity_stage` | Fırsatı başka aşamaya taşır; aşama kapıları uygulanır, reddedilirse nedenleri döner. | `note`, `opportunity_id`*, `reason`, `stage`* (Qualify · Viable · Present Solution · Negotiation · Expect to Close · Win · Lost · Cancel) | *Streç film fırsatını Viable'a taşı* |
| `create_task` | Görev açar (verilmezse bana atanır). Firma bağlamak isteğe bağlı; kendiliğinden proje açılmaz. | `assigned_to`, `company_id`, `company_name`, `detail`, `due_date`, `due_time`, `opportunity_id`, `priority` (Düşük · Normal · Yüksek · Acil), `title`* | *Yarın 10:30'a Kuzey Plastik'i arama görevi oluştur* |
| `complete_action` | Aksiyonu tamamlar (görev, ziyaret / deneme aksiyonu, proje adımı); done_on tamamlanma günü. | `done_on`, `id`*, `kind`* (visit · demo · task · step), `result` | *Fiyat listesi görevini tamamlandı yap* |
| `log_activity` | Telefon görüşmesi ya da yüz yüze ziyaret kaydeder (Hızlı Giriş): not, sonuç, sonraki aksiyon ve tarihi; uygun açık aksiyonları kapatır. | `action_date`, `company`*, `confirm_new`, `contact`, `next_action`, `note`, `opportunity_id`, `result`, `topic`, `visit_date`, `visit_type`* (F2F · Call) | *Kuzey Plastik'le az önceki telefon görüşmesini kaydet, perşembeye teklif aksiyonu aç* |
| `add_note` | Firma, fırsat, destek talebi ya da sözleşmeye not ekler. | `body`*, `record_id`*, `record_type`* (customer · opp · ticket · contract) | *Alize Paketleme'ye 'fiyat revizyonu istendi' notu düş* |

`*` zorunlu parametre.

## Yanıt biçimi

Araçlar sonucu hem metin (`content[0].text`, JSON) hem yapısal içerik (`structuredContent`) olarak döndürür. İş kuralı hatalarında (ör. aşama kapısı, benzer firma adı) `isError: true` ve nedeni açıklayan metin gelir; asistan bunu kullanıcıya aktarır ya da düzeltip yeniden dener.

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{ "type": "text", "text": "{\"counts\": {\"overdue\": 8, \"soon\": 0, \"today\": 0}, \"rows\": [ … ]}" }],
    "structuredContent": { "counts": { "overdue": 8, "soon": 0, "today": 0 }, "rows": [ "…" ] },
    "isError": false
  }
}
```