Versatile

Versatile-Mcp, modern AI ajanları için tasarlanmış tek girişli, yüksek performanslı ve modüler bir "Agentic OS" (Ajan İşletim Sistemi) katmanıdır. Bu suite; ajanların bilişsel zekasını, semantik hafızasını ve local/remote erişim gücünü maksimize ederken karmaşıklığı minimize eden bütünleşik bir MCP (Model Context Protocol) ekosistemidir.

Bilişsel İlke (0.95^10): "Her ek karar adımında hata olasılığı katlanarak artar. %95 başarı oranı, 10 adımda %60'a düşer. Bu yüzden güvenilirlik ve tutarlılık otonomiden önce gelir. Bilişsel gürültüyü azalt, kararları yapılandır."

---

🏛️ Bilişsel Mimari ve Katmanlar

Sistem, 3 ana uzmanlık katmanından (Brain, Master, Remote) oluşur ve tek bir FastMCP orkestratörü (main.py) üzerinden ayağa kalkar. Brain katmanı, relative importlar aracılığıyla local OS yetenekleriyle çakışma (namespace collision) yaşanmadan tamamen izole edilmiş gelişmiş bir bilişsel mimariye sahiptir.

graph TD
    %% Styling Class Definitions
    classDef client fill:#f9f9fb,stroke:#4f46e5,stroke-width:2px,color:#1f2937,rx:8px,ry:8px;
    classDef main fill:#e0e7ff,stroke:#4f46e5,stroke-width:3px,color:#312e81,font-weight:bold,rx:10px,ry:10px;
    classDef layer fill:#f5f3ff,stroke:#7c3aed,stroke-width:2px,color:#4c1d95,font-weight:bold,rx:8px,ry:8px;
    classDef brain fill:#ecfdf5,stroke:#10b981,stroke-width:1px,color:#064e3b,rx:6px,ry:6px;
    classDef master fill:#fffbeb,stroke:#d97706,stroke-width:1px,color:#78350f,rx:6px,ry:6px;
    classDef remote fill:#fdf2f8,stroke:#db2777,stroke-width:1px,color:#831843,rx:6px,ry:6px;

    %% Nodes
    User((Kullanıcı / AI Ajanı)):::client
    Main[main.py - FastMCP Orkestratörü]:::main
    
    Brain[🧠 Brain - Bilişsel Merkez]:::layer
    Master[🛠️ Master - Yerel OS]:::layer
    Remote[🌐 Remote - Uzak OS]:::layer

    %% Connections
    User -->|JSON-RPC| Main
    Main --> Brain
    Main --> Master
    Main --> Remote

    %% Brain Subgraph
    subgraph BrainLayer ["🧠 Brain Layer (SQLite + ChromaDB Hybrid Store)"]
        Memory[Memory Service<br/>6 Namespace]:::brain
        Graph[Graph Service<br/>BFS Expansion]:::brain
        Reasoning[Reasoning Service<br/>Loop/Contradiction Avoidance]:::brain
        Pipeline[5-Stage Retrieval Pipeline<br/>Vector + Re-ranker]:::brain
    end
    Brain --> Memory
    Brain --> Graph
    Brain --> Reasoning
    Brain --> Pipeline

    %% Master Subgraph
    subgraph MasterLayer ["🛠️ Master Layer (Yerel Sistem & Doküman)"]
        Files[FileSystem &<br/>Security Guardrails]:::master
        RichDocs[Rich Document Reader<br/>PDF, Docx, MD]:::master
        Analysis[Workspace Analyzer<br/>Scanner & Summary]:::master
    end
    Master --> Files
    Master --> RichDocs
    Master --> Analysis

    %% Remote Subgraph
    subgraph RemoteLayer ["🌐 Remote Layer (Güvenli Uzak Erişim)"]
        SSH[AsyncSSH Operations<br/>Multi-Host Execution]:::remote
        Jobs[Async Background Job Tracking<br/>History Logging]:::remote
    end
    Remote --> SSH
    Remote --> Jobs

    %% Link Styling
    linkStyle default stroke:#6366f1,stroke-width:2px;

---

🧠 1. Brain Katmanı: Gelişmiş Bilişsel ve Hafıza Mimarisi

Brain katmanı, basit metin saklama yapılarından sıyrılarak ChromaDB + SQLite Hibrit Depolama (HybridStore) mimarisine geçiş yapmıştır.

6 Namespace Hafıza Düzeni

Tüm bellekler ve ilişkiler, scope kısıtlaması (project_root) ve bağlamsal doğruluk için 6 uzmanlık alanına bölünmüştür:

1. code: Proje yapısı, fonksiyonlar, API kontratları ve codebase indeksleri.
2. user: Kullanıcı davranışları, tercihleri ve projeye özgü doğrudan geri bildirimler.
3. project: Mimari kararlar (ADRs), sistem tasarımları, teknik gereksinimler.
4. runtime: Aktif görev veya session sırasında kullanılan geçici bağlamlar.
5. incident: Hata geçmişleri, postmortem analizleri ve çözülen kritik buglar.
6. reasoning: Düşünce zincirleri, hipotezler ve problem çözme adımları.

5-Aşamalı Retrieval Pipeline (Semantik Getirme)

Bilgi getirme, sıradan bir arama motoru gibi değil, 5 katmanlı bir bilişsel boru hattından geçerek temizlenir:

1. Vector Search: ChromaDB üzerinden cosine similarity ile en yakın aday adayları çekilir.
2. Graph Expansion: BFS (Breadth-First Search) ile ilişkili komşu düğümler grafik üzerinden eklenir (BFS komşu genişletme).
3. Metadata Filtering: Güven düzeyi (confidence) ve güncellik derecesine (recency) göre filtreleme uygulanır.
4. Re-ranking (ZORUNLU): Cross-encoder joint scoring ile sorgu ve metin birlikte değerlendirilerek final skorlar hesaplanır.
5. Context Packing: Token bütçesi (max_tokens) ve kaynak kısıtlamalarına göre tekilleştirme yapılarak en yoğun bağlam paketi oluşturulur.

Kendini Denetleyen Sequential Thinking & Distillation

• Döngü ve Çelişki Algılama (Loop Prevention): sequentialthinking_add_thought aracı, ajanın aynı düşünceleri tekrarlamasını (loop_detected) veya daha önce kalıcı hale getirilmiş sistemsel gerçeklerle çelişmesini engeller.
• Damıtma (Distillation): Bir reasoning oturumu başarıyla tamamlandığında, ajanın ulaştığı kararlar reasoning_distill aracıyla kalıcı Ground Truth Memory (Sistemsel Gerçekler) katmanına terfi ettirilir ve izlenebilirlik (traceability) grafikleri kurulur.

---

🛠️ Detaylı Araç Referansı (30+ Unified Tools)

🧠 Bilişsel ve Hafıza Araçları (Brain Layer)

Modül (Namespace)	Araç Adı	Görev	Önemli Parametreler
Memory	memory_write	Yeni semantik hafıza yazar (duplicate kontrollü)	content, project_root, namespace, category
	memory_update	Bir hafızayı üst versiyona taşır (supersedes ilişkisi)	target_id, new_content, project_root
	memory_get	Tekil bellek ve onun versiyon geçmişini getirir	node_id, include_history
	memory_query	Semantik hafızada gelişmiş arama yapar	query, project_root, namespace
	memory_index	Belirli bir dokümanı parçalayıp hafızaya ekler	file_path, project_root, namespace
Reasoning	sequentialthinking_add_thought	Döngü kontrollü, grafik destekli akıl yürütme adımı	thought, thought_number, total_thoughts
	reasoning_trace_write	Manuel akıl yürütme izi yazar	thought, project_root, data_class
	reasoning_trace_query	Geçmiş akıl yürütme izlerinde semantik arama	query, project_root
	reasoning_distill	Düşünce oturumunu kalıcı belleğe terfi ettirir	session_id, project_root, confidence
Graph	graph_expand	BFS ile ilişkisel grafik genişletmesi yapar	start_id, depth, project_root
	graph_get_neighbors	Bir düğümün doğrudan komşularını getirir	node_id
	graph_link	İki hafıza veya düşünce arasına grafik kenarı (edge) ekler	source_id, target_id, relation_type
Workspace	workspace_summary	Çalışma alanının anlık mimari özetini üretir	project_root, max_depth

Not: User, Project ve Codebase modülleri (user_memory_get, project_memory_set vb.) ilgili namespace sınırları altında doğrudan atomik bellek erişimi sağlar.

🛠️ Yerel Sistem ve Doküman Araçları (Master Layer)

Araç Adı	Görev	Önemli Parametreler
read_rich_document	PDF, Word, Markdown, Kod dosyalarını bağlamı koruyarak okur	file_path, start_line, end_line
directory_tree	.gitignore kurallarına duyarlı dosya ağacı üretir	directory, max_depth
grep_search	Ripgrep ile yüksek hızlı desen ve içerik araması yapar	query, includes, search_path
validate_syntax	Python, JS vb. kodların derleme ve sözdizimi doğruluğunu denetler	file_path

🌐 Güvenli Uzak Erişim ve Asenkron İşler (Remote Layer)

Araç Adı	Görev	Önemli Parametreler
ssh_execute	Uzak sunucuda güvenli komut çalıştırır (arka plan desteğiyle)	host, command, run_in_background
check_job_status	Uzun süren SSH arka plan işlerinin durumunu sorgular	job_id
get_ssh_history	Geçmiş SSH oturumlarının ve komutlarının listesini getirir	host

---

🛡️ Güvenlik Korumaları ve Kurallar (Guardrails)

Ajanlarımızın otonom hareket ederken sisteme zarar vermesini engellemek için tasarlanmış sıkı güvenlik kuralları:

• İnsan Onayı (Human-in-the-loop): Kritik, yıkıcı ve geri döndürülemez tüm işlemler (delete_*, ssh_execute) için kullanıcı onayı zorunludur ve sistem tarafından onay müzakere edilemez.
• Sessiz Bozulma Yerine Dur: Sistemde bir hata algılandığında (örn. çelişkili durum veya Foreign Key hatası) sessizce devam etmek yerine, durur, raporlar ve güvenli geri alma (rollback) işlemini başlatır.
• Güven Eşiği Sınırı (Distillation Threshold): reasoning_distill aracıyla Ground Truth Memory'ye bilgi terfi ettirmek için confidence (güven oranı) en az 0.85 olmalıdır. Ajanın kendinden emin olmadığı kararlar sistemsel gerçek olamaz.
• Dosya Erişim Güvenliği: Yerel dosya işlemleri master katmanındaki ALLOWED_ROOTS ve IgnoreService tarafından sıkıca sınırlandırılmıştır; yetkisiz dizin okuma ve yazmaları tamamen engellenir.

---

🚀 Kurulum ve Yapılandırma

1. Gereksinimlerin Yüklenmesi

pip install -r requirements.txt

2. Ortam Değişkenleri (.env)

Aşağıdaki değişkenleri projenin kök dizinindeki .env dosyasında tanımlayın:

# Global
MCP_DATA_DIR=.data
MCP_DB_TIMEOUT=30

# Brain (Hibrit RAG & Embedding)
EMBEDDING_MODEL_PATH=resources/models/embedding_model.gguf
RAG_CHUNK_SIZE=512
RAG_CHUNK_OVERLAP=64
RAG_TOP_K=5
RAG_N_GPU_LAYERS=0
RAG_N_THREADS=4
RAG_N_CTX=2048

# Master & Remote
REMOTE_LOG_DIR=./logs/remote

3. Claude Desktop / IDE Yapılandırması

Versatile-Mcp'yi bir MCP istemcisine (örn: Claude Desktop) kaydetmek için mcp_config.json dosyanıza aşağıdaki yapılandırmayı ekleyin.

Dikkat: args ve env altındaki yolları kendi sisteminize göre absolute (mutlak) olarak güncelleyin.

{
  "mcpServers": {
    "versatile-mcp": {
      "command": "python",
      "args": [
        "/absolute/path/to/Versatile-Mcp/main.py"
      ],
      "env": {
        "MCP_DATA_DIR": "/absolute/path/to/Versatile-Mcp/.data",
        "EMBEDDING_MODEL_PATH": "/absolute/path/to/Versatile-Mcp/resources/models/embedding_model.gguf"
      },
      "disabled": false
    }
  }
}

---

🔄 Ajan Çalışma Desenleri (Agent Patterns)

Sunucudan maksimum bilişsel verim elde etmek için ajanların şu desenleri uygulaması beklenir:

1. ReAct Döngüsü

Ajan, karmaşık bir problemi çözerken önce sequentialthinking_add_thought aracıyla plan yapar (Thought), ardından yerel veya uzak OS araçlarıyla eyleme geçer (Action) ve son olarak eylemin sonucunu gözlemleyerek (Observation) yeni adımlar planlar.

2. Akıl Yürütme ve Damıtma Akışı

Ajan, karmaşık codebase veya sistem mimarisi üzerinde çalışırken:

1. sequentialthinking_add_thought ile adımları ilerletir.
2. Karar anında reasoning_trace_write ile karar hipotezini yazar.
3. Sonuç doğrulandıktan sonra reasoning_distill ile ulaştığı ADR (Architectural Decision Record) veya codebase bilgisini confidence=0.95 ile kalıcı Ground Truth belleğine aktarır.

---

👨‍💻 Geliştirici Rehberi

Yeni bir araç veya sunucu katmanı eklemek için:

1. Dahili Dosya İçi Importlar: servers/brain altındaki herhangi bir dosyada diğer brain bileşenlerini import ederken, relative import (from .memory_service import MemoryService, from ..storage.hybrid_store import HybridStore) kullanın. Bu, yerel OS modülleriyle çakışmayı önler.
2. FastMCP Araç Tanımı: servers/brain/tools/ altındaki ilgili modüle @mcp.tool() dekoratörüyle fonksiyonunuzu ekleyin. Fonksiyon parametrelerinin ve geri dönüş tiplerinin tip tanımlamalarını (Type Hints) ve detaylı docstring açıklamalarını eksiksiz yapın.
3. ** main.py Kaydı:** Yeni araç setinizin register fonksiyonunu main.py başlangıcında çağırarak orkestrasyona dahil edin.

---

🔗 İlişkili Projeler ve Entegrasyonlar

Bu "Agentic OS" ekosistemini zenginleştiren diğer temel bileşenler:

• Versatile-Skills: Ajanların yeteneklerini ve dinamik becerilerini (skills) yönetmesini sağlayan, Versatile-Mcp ile entegre çalışacak şekilde tasarlanmış gelişmiş yetenek ve otomasyon kütüphanesidir.

---

Geliştirilen Her Karar, Güvenilir Bir Gelecek İçin.