# ⚡ Tamga AI — Model Context Protocol (MCP) Server

[![MCP Spec v1.0](https://img.shields.io/badge/MCP-v1.0-blue.svg)](https://modelcontextprotocol.io)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Agentic Workflows](https://img.shields.io/badge/Agentic_Workflows-Supported-brightgreen.svg)]()

> **Proje İlan Kanıtı (Direct Evidence Document):**  
> Bu depo, **"agentic workflows / AI-powered developer tools"** alanındaki yetkinliğin **doğrudan teknik kanıtı** olarak sunulmaktadır. Anthropic Model Context Protocol (MCP) spec v1.0 standardına %100 uyumlu, 5 adet autonom yapay zeka aracını (AI Agent Tools) `stdio` ve `streamable-http` taşıma katmanlarında sunar.

---

## 🏛️ Mimari Şema (Agentic Workflow Architecture)

```mermaid
graph TD
    Client[LLM Client / Agentic IDE<br/>Claude Desktop / Cursor / Antigravity] -->|JSON-RPC 2.0 / stdio / HTTP| MCPServer[Tamga MCP Server<br/>mcp_server.py]
    
    subgraph MCP Tool Suite
        MCPServer --> T1[1. gokturkce_translate]
        MCPServer --> T2[2. gokturkce_decode_text]
        MCPServer --> T3[3. gokturkce_verify_image]
        MCPServer --> T4[4. gokturkce_render_image]
        MCPServer --> T5[5. gokturkce_render_video]
    end

    T1 --> RuleEngine[Orthography & Vowel Harmony Engine]
    T2 --> EDPT[EDPT Etymological Dictionary Index]
    T3 --> VisionAI[MobileNetV2 OCR & Line Segmentation]
    T4 --> Render3D[Pillow 3D Lighting & Composite Engine]
    T5 --> VideoAI[Depth Anything V2 3D Parallax Video Engine]
```

---

## 📋 5 MCP Aracının Detaylı Listesi (Tool Specifications)

Sunucu, LLM Ajanlarının (Claude, GPT-4o, Gemini) harici araç olarak doğrudan çağırabileceği **5 adet tip-güvenli (type-safe) fonksiyon** sunar:

### 1. `gokturkce_translate`
* **Tanım:** Latin harfli Türkçe metni Göktürkçe (Orhun) yazısına çevirir ve Orhun ünlü uyumunu doğrular.
* **Girdiler:**
  * `text` (*string*, zorunlu): Çevrilecek metin (ör. `"bodun"`, `"tengri"`, `"turk"`)
  * `mode` (*string*, varsayılan `"geleneksel"`): `"geleneksel"` (ünlü düşürme, ligatür ve kalınlık-incelik uyumu kuralları) veya `"modern"` (birebir harf harf)
* **Dönüş:** Göktürkçe Unicode dizisi, harf kırılımları, kod noktaları ve ünlü uyumu doğrulama nesnesi.
* **Anotasyon:** `readOnlyHint=True`, `idempotentHint=True`

### 2. `gokturkce_decode_text`
* **Tanım:** Göktürkçe Unicode metni (`𐰉𐰆𐰑𐰣`) deşifre eder ve Sir Gerard Clauson EDPT (1972) & Vildan Koçoğlu (2006) etimolojik sözlük dizininde sorgular.
* **Girdiler:**
  * `text` (*string*, zorunlu): Göktürkçe Unicode metin
  * `mode` (*string*, varsayılan `"auto"`): `"geleneksel"`, `"modern"`, `"auto"`
* **Dönüş:** Eşleşen etimolojik kelime adayları, Türkçe karşılıkları ve sözlük referansları.
* **Anotasyon:** `readOnlyHint=True`, `idempotentHint=True`

### 3. `gokturkce_verify_image`
* **Tanım:** Görseldeki Göktürkçe harfleri otomatik çizgi/harf segmentasyonu ve MobileNetV2 yapay zeka sınıflandırıcısı ile doğrular.
* **Girdiler:**
  * `image_path_or_base64` (*string*, zorunlu): Yerel dosya yolu (ör. `"outputs/sample.png"`) veya Data URI / Base64 dizesi
* **Dönüş:** Okuma yönü (`rtl`), kelime ve harf kutuları (bounding boxes), tahmin olasılıkları, ünlü uyumu geçerlilik durumu (`overall_valid`).
* **Anotasyon:** `readOnlyHint=True`, `idempotentHint=True`

### 4. `gokturkce_render_image`
* **Tanım:** Göktürkçe metni seçilen doku ve stil üzerinde taşa kazınmış, parşömen, altın varak, neon vb. 3D kompozit efektlerle PNG olarak üretir.
* **Girdiler:**
  * `text` (*string*, zorunlu): Görselleştirilecek metin
  * `style` (*string*, varsayılan `"plain"`): `"carved"`, `"fircha"`, `"ink_bleed"`, `"stamp"`, `"chalk"`, `"ember"`, `"ash"`, `"stencil"`, `"neon"`, `"parchment"`, `"plain"`
  * `texture` (*string*, opsiyonel): `"stone.png"`, `"gold.png"`, `"wood.png"`, `"paper.png"`, `"leather.png"`, `"parchment.png"`, `"neon.png"`
  * `size` (*integer*, varsayılan `512`): Piksel çözünürlük
  * `degradation` (*float*, varsayılan `0.0`): Yıpranma/eskime oranı (0.0 - 1.0)
  * `text_color` (*string*, opsiyonel): Hex renk kodu (ör. `"#FF0000"`)
  * `transparent_bg` (*boolean*, varsayılan `false`): Saydam arka plan
  * `output_path` (*string*, varsayılan `"rendered_image.png"`): Hedef dosya yolu
* **Dönüş:** Üretilen dosya yolu, boyutlar, renk modu ve başarı mesajı.
* **Anotasyon:** `readOnlyHint=False`, `idempotentHint=False`

### 5. `gokturkce_render_video`
* **Tanım:** Göktürkçe metni seçilen doku stili üzerinde Depth Anything V2 derinlik kestirimi ile 3D Parallax veya kamera hareketli sinematik MP4 videosuna dönüştürür.
* **Girdiler:**
  * `text` (*string*, zorunlu): Metin
  * `style` (*string*, varsayılan `"plain"`): Stiller
  * `texture` (*string*, opsiyonel): Doku görseli
  * `motion` (*string*, varsayılan `"parallax"`): `"parallax"`, `"zoom"`, `"pan"`, `"fade"`
  * `duration` (*integer*, varsayılan `5`): Saniye cinsinden video süresi (3-10 sn)
  * `size` (*integer*, varsayılan `512`): Çözünürlük
  * `output_path` (*string*, varsayılan `"rendered_video.mp4"`): MP4 dosya yolu
* **Dönüş:** Video dosya yolu, hareket tipi, süre ve çözünürlük bilgileri.
* **Anotasyon:** `readOnlyHint=False`, `idempotentHint=False`

---

## 💻 İstemci Konfigürasyonu (Claude Desktop & Agentic IDEs)

### Claude Desktop (`claude_desktop_config.json`)
Windows platformunda `%APPDATA%\Claude\claude_desktop_config.json` dosyasına ekleyin:

```json
{
  "mcpServers": {
    "tamga-gokturkce-assistant": {
      "command": "python",
      "args": [
        "C:\\Users\\pc\\gokturk_studio\\tamga-mcp-server\\mcp_server.py",
        "--transport",
        "stdio"
      ]
    }
  }
}
```

---

## 🌐 Çift Taşıma Protokolü (Dual Transport Modes)

1. **`stdio` Modu (Yerel Ajanlar):**
   ```bash
   python mcp_server.py --transport stdio
   ```
2. **`streamable-http` / `sse` Modu (Uzaktan / Cloud API):**
   ```bash
   python mcp_server.py --transport streamable-http --host 127.0.0.1 --port 8001
   ```
   > HTTP modunda `X-API-Key` başlığı (`api_keys.json` doğrulaması) ile yetkilendirme sağlanır.

---

## 🧪 Örnek Ajan İstekleri & İstemler (Agent Prompts)

Claude veya Cursor sohbet penceresinden doğrudan verilebilecek örnek komutlar:
- 💬 *"‘bodun’ kelimesini Göktürkçeye çevir, harf analizini yap ve ünlü uyumunu doğrula."*
- 💬 *"‘tengri’ kelimesini taşa kazınmış 3D Parallax efektiyle 'outputs/tengri.mp4' olarak videoya dönüştür."*
- 💬 *"Görseldeki Göktürkçe metni MobileNetV2 ile OCR analizinden geçir ve okunuşunu ver."*

---

## 📄 Lisans
Bu proje **MIT** lisansı ile sunulmaktadır.