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

pip install -r requirements.txt

MCP Sunucusunun Çalıştırılması

Sunucuyu doğrudan çalıştırmak için:

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:

{
  "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ı):

  {
    "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):

  {
    "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ı:

  {
    "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:

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.