# SSH MCP Tool Suite

SSH MCP Tool Suite, Kubernetes pod logları, veritabanı hataları ve sistem çıktılarının SSH üzerinden güvenli bir şekilde çalıştırılmasını, yerel LLM (Ollama/phi3/gemma) entegrasyonu ile akıllıca özetlenmesini sağlayan ve Model Context Protocol (MCP) standartlarına tam uyumlu geliştirilmiş **production-ready** bir araç setidir.

Bu suite, büyük komut çıktılarının LLM context penceresini şişirmesini önlemek amacıyla **"Consistency Contract"** ve **"Authority Tagging"** mimari prensipleri doğrultusunda optimize edilmiştir.

---

## 🚀 Öne Çıkan Özellikler

- **Hafif Context Tasarımı (Zero-Bloat):** `ssh_execute` ve `check_job_status` araçları varsayılan olarak ham `stdout` ve `stderr` alanlarını döndürmez. Böylece model context'i şişmez.
- **Ham Çıktı Ayrımı (Separate Data Plane):** Komut loglarının tamamını çekmek için bağımsız bir `get_job_output` aracı kullanılır.
- **Consistency Contract (Tutarlılık Sözleşmesi):** Modelin akıl yürütmesini ("reasoning") stabilize etmek için her veri çıktısı kendi kaynağını (`source`) ve veri güncelliği/otorite rolünü (`authority`) etiketler:
  - Canlı veriler: `authority: "primary"`
  - Durum kopyası verileri: `authority: "replica"`
  - Sabit statik çıktılar: `authority: "snapshot"`
- **Otomatik Hata Yolu (Tail on Error):** Komut veya bağlantı hatası oluştuğunda son 50 karakterlik log çıktısı (`tail`) çıktıya otomatik olarak eklenir. Başarılı çıktılarda bu yük oluşmaz.
- **İki Aşamalı Akıllı Log Özetleme (Two-Stage Log Summarization Pipeline):**
  - **Aşama 1: Deterministik Temizleme ve Sıkıştırma (Basic - Ollama Bağımsız):** Tüm süreçlerde ilk adım olarak çalışır. Loglardaki kronik restart döngülerini tespit eder, zaman damgalarını sadeleştirir ve kritik log kalıplarını regex ile deterministik olarak gruplayıp sıkıştırır. Ollama gerektirmez ve sunucu her koşulda bu seviyeyi çalıştırır.
  - **Aşama 2: Semantik Analiz ve LLM Özetleme (Extreme - Ollama Opsiyonel):** İlk aşamadan geçen sıkıştırılmış ve temizlenmiş log verisi, eğer Ollama sunucusu aktifse yerel LLM modellerine (`gemma:2b`, `phi3:mini`) girdi olarak verilir ve semantik bir özet analiz raporu üretilir. Ollama erişilemez durumdaysa bu aşama pas geçilerek Aşama 1 çıktısı korunur.
- **Asenkron Çalışma Desteği:** Uzun süren işler (background=True) asenkron başlatılıp daha sonra sorgulanabilir.
- **Güvenlik (Password Masking):** request_log kayıtlarında şifreler otomatik olarak maskelenir (`***`).

---

## 📂 Dizin Yapısı

```
SshTool/
├── app/
│   ├── core/         — Temel yapılandırma ve Pydantic veri modelleri
│   ├── db/           — SQLite veritabanı bağlantısı ve Repository katmanı
│   ├── jobs/         — SSH çalıştırma motoru ve JobManager servisi
│   ├── mcp/          — MCP araçlarının (ssh_execute, job_status, ssh_history) tanımları
│   ├── ssh/          — Paramiko tabanlı SSH Client katmanı
│   ├── summarizer/   — Ollama entegrasyonu ve log özetleme servisi
│   └── main.py       — FastMCP sunucusu başlangıç noktası
├── tests/
│   └── smoke_test.py — Otomatik API ve senaryo doğrulama testleri
└── requirements.txt  — Bağımlılık listesi
```

---

## 🛠️ Kurulum ve Çalıştırma

### Gereksinimler
- Python 3.10+
- SQLite3
- Yerel Ollama Çalışma Ortamı (Opsiyonel, özetleme için `phi3:mini` veya `gemma:2b` gereklidir)

### Bağımlılıkların Yüklenmesi
```bash
pip install -r requirements.txt
```

### MCP Sunucusunun Çalıştırılması
Sunucuyu doğrudan çalıştırmak için:
```bash
python app/main.py
```

Claude Desktop veya diğer MCP istemcilerine entegre etmek için `mcp_config.json` veya benzeri yapılandırma dosyasına şu satırı ekleyebilirsiniz:
```json
{
  "mcpServers": {
    "ssh-tool": {
      "command": "python",
      "args": ["C:\\path\\to\\SshTool\\app\\main.py"]
    }
  }
}
```

---

## 🔌 MCP Araçları (MCP Tools Contract)

### 1. `ssh_execute`
Uzak sunucuda SSH üzerinden komut çalıştırır.

*   **Parametreler:**
    - `host` (str): Sunucu adresi.
    - `username` (str): SSH kullanıcı adı.
    - `password` (str): SSH şifresi.
    - `command` (str): Çalıştırılacak shell komutu.
    - `timeout` (Optional[int]): Zaman aşımı (saniye).
    - `background` (bool): Arka planda (asenkron) çalıştırma seçeneği.
    - `summary` (SummaryOptions): Özetleme seçenekleri.

*   **Çıktı (Başarılı):**
    ```json
    {
      "job_id": "5e01f600-...",
      "status": "success",
      "exit_code": 0,
      "summary": "Komut başarıyla tamamlandı.",
      "details_available": true,
      "source": "execution",
      "authority": "primary"
    }
    ```

---

### 2. `check_job_status`
Bir işin durumunu ve veritabanı güncelliğini sorgular.

*   **Parametreler:**
    - `job_id` (str)
    - `summary` (SummaryOptions)

*   **Çıktı (Başarısız/Hata Durumu - Otomatik Tail):**
    ```json
    {
      "job_id": "5e01f600-...",
      "status": "failed",
      "exit_code": 127,
      "summary": "...",
      "tail": "sh: docker-compose: command not found",
      "details_available": true,
      "source": "status",
      "authority": "replica",
      "created_at": "...",
      "started_at": "...",
      "finished_at": "..."
    }
    ```

---

### 3. `get_job_output`
Belirtilen işin ürettiği tam `stdout` ve `stderr` çıktı loglarını getirir.

*   **Parametreler:**
    - `job_id` (str)

*   **Çıktı:**
    ```json
    {
      "job_id": "5e01f600-...",
      "stdout": "Ham çıktı logları...",
      "stderr": "Ham hata logları...",
      "source": "output",
      "authority": "snapshot"
    }
    ```

---

### 4. `get_ssh_history`
Belirtilen host/kullanıcı ikilisine ait geçmiş iş kayıtlarını listeler.

---

## 🧪 Testler

Uygulanan tüm girdi/çıktı davranışlarını ve API sözleşmelerini doğrulamak için smoke testleri çalıştırabilirsiniz:

```bash
python tests/smoke_test.py
```

Test suite şu doğrulamaları kapsar:
1. Şifrelerin `request_log` içerisinde maskelenerek güvenli şekilde kaydedilmesi.
2. `ssh_execute` ve `check_job_status` çıktılarında `stdout`/`stderr` alanlarının dönmediğinin doğrulanması.
3. Hata durumlarında `tail` alanının otomatik olarak eklendiğinin kontrolü.
4. `source` ve `authority` etiketlerinin tutarlılığı.
5. Asenkron iş akışları ve çıktı alma araçlarının (`get_job_output`) entegrasyonu.

---

## 🚀 Ollama Başlangıç Kontrolü & Fallback

MCP sunucusu başlatılırken (lifespan startup), yerel Ollama sunucusu ve hedeflenen LLM modelinin varlığı otomatik olarak test edilir:
- **Model ve Bağlantı Doğrulama:** Ollama `/api/tags` endpoint'i üzerinden tüm yüklü modeller çekilir ve yapılandırılan modelin (örn. `gemma:2b` veya `phi3:mini`) indirilmiş olup olmadığı denetlenir.
- **Hata Toleransı (Resilient Startup):** Eğer Ollama sunucusu kapalıysa ya da yapılandırılan model yüklü değilse, sunucu **çökmez**. Terminale/stderr konsoluna detaylı bir `WARNING` uyarısı basılır ve sunucu başarıyla ayağa kalkar.
- **Otomatik Basic Fallback:** Ollama'ya erişilemediği durumlarda, `extreme` özetleme istekleri geldiğinde sistem otomatik olarak regex/kod tabanlı `basic` özetleyiciye fallback yapar. Çıktıdaki `summary_mode` alanı `"basic"` olarak işaretlenir.