🧲 Magg - MCP Aggregatörü

LLM'lerin kendi yeteneklerini dinamik olarak genişletmelerine olanak tanıyan, diğer MCP serverlarını yöneten, toplayan ve proxy'leyen bir Model Context Protocol sunucusu.

Magg Nedir?

Magg, birden fazla MCP sunucusunu yönetmek için merkezi bir hub görevi gören meta-MCP sunucusudur. LLM'lerin aşağıdakileri yapmalarını sağlayan araçlar sağlar:

Yeni MCP sunucularını arayabilir ve kurulum talimatlarını keşfedebilir
MCP sunucularını dinamik olarak ekleyebilir ve yapılandırabilir
Sunucuları isteğe bağlı olarak etkinleştirebilir/devre dışı bırakabilir
Birden fazla sunucudan gelen araçları birleştirilmiş ön ekler altında toplayabilir
Konfigürasyonları oturumlar arasında kalıcı hale getirebilir

Magg'i "LLM araçları için paket yöneticisi" olarak düşünün - AI asistanlarının çalışma zamanında kendi yeteneklerini yükleyip yönetmelerine izin verir.

Özellikler

Self-Service Araç Yönetimi: LLM'ler insan müdahalesi olmadan yeni MCP sunucularını arayabilir ve ekleyebilir.
Dinamik Konfigürasyon Yeniden Yükleme: Sunucuyu yeniden başlatmadan yapılandırma değişikliklerini otomatik olarak algılar ve uygular.
Otomatik Araç Proxy'lemesi: Eklenen sunuculardan gelen araçlar, yapılandırılabilir ön eklerle otomatik olarak kullanıma sunulur.
ProxyMCP Aracı: Bildirimler veya dinamik araç güncellemeleri desteklemeyen istemciler için (çoğu şu anda böyledir) MCP protokolünü kendisine proxy'leyen yerleşik araç.
Akıllı Konfigürasyon: Yalnızca bir URL'den sunucuları akıllıca yapılandırmak için MCP sampling kullanır.
Kalıcı Konfigürasyon: Sunucu konfigürasyonlarını .magg/config.json içinde tutar.
Çoklu Transport Desteği: stdio, HTTP ve bellek içi taşıyıcılarla çalışır.
Bearer Token Kimlik Doğrulaması: Güvenli HTTP erişimi için opsiyonel RSA tabanlı JWT kimlik doğrulaması.
Docker Desteği: Üretim, hazırlık ve geliştirme iş akışları için önceden oluşturulmuş görüntüler.
Sağlık Monitörü: Sunucu sağlığı kontrolleri için yerleşik magg_status ve magg_check araçları.
Gerçek Zamanlı Mesajlaşma: Backend sunucularından araç/kaynak güncellemeleri ve ilerleme bildirimleri almak için MCP bildirimler ve mesajlara tam destek.
Python 3.12+ Desteği: Python 3.12 ve 3.13 ile tamamen uyumlu.
Kit Yönetimi: İlişkili MCP sunucularını grup olarak kolayca yüklemek/boşaltmak için kit'ler halinde paketleyin.
MBro CLI: Dahil edilen MCP Browser ile MCP sunucularının etkileşimli keşfi ve yönetimi, otomasyon için script desteği.

Kurulum

Ön Koşullar

Python 3.12 veya daha yüksek (3.13+ önerilir)
uv (önerilir) - astral.sh/uv adresinden yükleyin

Hızlı Kurulum (Önerilir)

Magg'i kurmak için en kolay yol, uv kullanarak bir araç olarak yüklemektir:

# Magg'i araç olarak yükle
uv tool install magg

# stdio taşıyıcısıyla çalıştır (Claude Desktop, Cline, vb. için)
magg serve

# HTTP taşıyıcısıyla çalıştır (sistem genelinde erişim için)
magg serve --http

Alternatif: GitHub'dan Doğrudan Çalıştır

Yüklemeden GitHub'dan doğrudan Magg'i çalıştırabilirsiniz:

# stdio taşıyıcısıyla çalıştır
uvx --from git+https://github.com/sitbon/magg.git magg

# HTTP taşıyıcısıyla çalıştır
uvx --from git+https://github.com/sitbon/magg.git magg serve --http

Yerel Geliştirme

Geliştirme için depoyu klonlayın ve düzenlenebilir modda yükleyin:

# Depoyu klonla
git clone https://github.com/sitbon/magg.git
cd magg

# Geliştirme bağımlılıklarıyla geliştirme modunda yükle
uv sync --dev

# Veya poetry ile
poetry install --with dev

# CLI'yi çalıştır
magg --help

Docker

Magg, GitHub Container Registry'den önceden oluşturulmuş Docker görüntüleri olarak mevcuttur:

# Üretim görüntüsünü çalıştır (WARNING log seviyesi)
docker run -p 8000:8000 ghcr.io/sitbon/magg:latest

# Kimlik doğrulamayla çalıştır (özel anahtarı monte edin veya ayarlayın)
docker run -p 8000:8000 \
  -v ~/.ssh/magg:/home/magg/.ssh/magg:ro \
  ghcr.io/sitbon/magg:latest

# Veya ortam değişkeniyle
docker run -p 8000:8000 \
  -e MAGG_PRIVATE_KEY="$(cat ~/.ssh/magg/magg.key)" \
  ghcr.io/sitbon/magg:latest

# Beta görüntüsünü çalıştır (INFO log seviyesi)
docker run -p 8000:8000 ghcr.io/sitbon/magg:beta

# Özel config diziniyle çalıştır
docker run -p 8000:8000 \
  -v /path/to/config:/home/magg/.magg \
  ghcr.io/sitbon/magg:latest

Docker Görüntü Stratejisi

Magg, üç hedef aşamalı multi-stage Docker derlemesi kullanır:

pro (Üretim): WARNING log seviyesiyle minimal görüntü, üretim dağıtımları için uygundur
pre (Üretim Öncesi): Üretimle aynı fakat hazırlık/test için INFO log seviyesiyle (yayınlanmaz ancak mevcuttur)
dev (Geliştirme): Sorun giderme için geliştirme bağımlılıkları ve DEBUG günlüğünü içerir

Görüntüler GitHub Container Registry'ye aşağıdaki etiketlerle otomatik olarak yayınlanır:

Sürüm etiketleri (main branch'ten): 1.2.3, 1.2, dev, 1.2-dev, 1.2-dev-py3.12, vb.
Branch etiketleri (beta branch'ten): beta, beta-dev
Python'a özgü dev etiketleri: beta-dev-py3.12, beta-dev-py3.13, vb.

Docker Compose

Daha kolay yönetim için Docker Compose kullanın:

# Depoyu klonla
git clone https://github.com/sitbon/magg.git
cd magg

# Üretim sürümünü çalıştır
docker compose up magg

# Hazırlık sürümünü çalıştır (port 8001'de)
docker compose up magg-beta

# Geliştirme sürümünü çalıştır (port 8008'de)
# Bu ./.magg/config.json kullanır
docker compose up magg-dev

# Özel kayıt defteri ile derle ve yayınla
REGISTRY=my.registry.com docker compose build
REGISTRY=my.registry.com docker compose push

Yapılandırma seçenekleri için compose.yaml ve .env.example dosyalarına bakın.

Kullanım

Magg'i Çalıştırma

Magg üç modda çalışabilir:

Stdio Modu (varsayılan) - Claude Desktop, Cline, Cursor, vb. ile entegrasyon için:
```
magg serve
```
HTTP Modu - Sistem genelinde erişim veya web entegrasyonları için:
```
magg serve --http --port 8000
```

Hibrit Mod - stdio ve HTTP aynı anda:

magg serve --hybrid
magg serve --hybrid --port 8080  # Özel port

Bu, Magg'i bir MCP istemcisi aracılığıyla kullanmak ve aynı zamanda HTTP erişimine izin vermek istediğinizde özellikle faydalıdır. Örneğin:

Claude Code ile:

# Claude Code'u Magg'i hibrit modda kullanacak şekilde yapılandır
claude mcp add magg -- magg serve --hybrid --port 42000

mbro ile:

# mbro Magg'i barındırır ve stdio üzerinden bağlanır
mbro connect magg "magg serve --hybrid --port 8080"

# Diğer mbro örnekleri HTTP üzerinden bağlanabilir
mbro connect magg http://localhost:8080

Mevcut Araçlar

Magg çalıştırılırken, LLM'lere aşağıdaki araçları sunur:

magg_list_servers - Yapılandırılmış tüm MCP sunucularını listele
magg_add_server - Yeni MCP sunucusu ekle
magg_remove_server - Sunucu sil
magg_enable_server / magg_disable_server - Sunucu kullanılabilirliğini aç/kapat
magg_search_servers - Çevrimiçi MCP sunucularını ara
magg_list_tools - Tüm sunuculardan tüm kullanılabilir araçları listele
magg_smart_configure - Bir URL'den sunucuyu akıllıca yapılandır
magg_analyze_servers - Yapılandırılmış sunucuları analiz et ve iyileştirmeler öner
magg_status - Sunucu ve araç istatistiklerini al
magg_check - Sunucu sağlığı kontrol et ve onarım eylemleri (rapor/yeniden monte/kaldır/devre dışı bırak)
magg_reload_config - Yapılandırmayı diskten yeniden yükle ve değişiklikleri uygula
magg_load_kit - Kit ve sunucularını yapılandırmaya yükle
magg_unload_kit - Kit'i yapılandırmadan kaldır ve isteğe bağlı olarak sunucularını kaldır
magg_list_kits - Durumlarıyla birlikte tüm mevcut kit'leri listele
magg_kit_info - Belirli bir kit hakkında detaylı bilgi al

MBro ile Hızlı İnceleme

Magg, etkileşimli keşif için mbro (MCP Browser) CLI aracını içerir. Benzersiz bir özellik, stdio modunda Magg örneğine bağlanabilme yeteneğidir:

# mbro'yu Magg örneğine stdio üzerinden bağla (HTTP sunucusu gerekmez)
mbro connect local-magg magg serve

# Artık MCP istemcisi perspektifinden Magg kurulumunuzu inceleyin
mbro:local-magg> call magg_status
mbro:local-magg> call magg_list_servers

MBro ayrıca şunları destekler:

Scriptler: Otomasyon için .mbro dosyalarıyla komutlar oluştur
Shell tarzı argumentler: JSON yerine key=value söz dizimini kullan
Tab tamamlama: Bağlandıktan sonra zengin parametre ipuçları

Detaylar için MBro Belgelendirmesi bölümüne bakın.

Kimlik Doğrulama

Magg, erişimi güvenli hale getirmek için opsiyonel bearer token kimlik doğrulamasını destekler:

Hızlı Başlangıç

Kimlik doğrulamayı başlat (RSA anahtar çifti oluşturur):
```
magg auth init
```

İstemciler için JWT token oluştur:

# Token oluştur (ekranda görüntüle)
magg auth token

# Ortam değişkeni olarak dışa aktar
export MAGG_JWT=$(magg auth token -q)

Kimlik doğrulamayla bağlan:

MaggClient kullanarak (MAGG_JWT'den otomatik yükler):

from magg.client import MaggClient

async def main():
    async with MaggClient("http://localhost:8000/mcp") as client:
        tools = await client.list_tools()

FastMCP'yi açık token ile kullanarak:

from fastmcp import Client
from fastmcp.client import BearerAuth

jwt_token = "your-jwt-token-here"
async with Client("http://localhost:8000/mcp", auth=BearerAuth(jwt_token)) as client:
    tools = await client.list_tools()

Anahtar Yönetimi

Anahtarlar varsayılan olarak ~/.ssh/magg/ adresinde saklanır
Özel anahtar, MAGG_PRIVATE_KEY ortam değişkeniyle ayarlanabilir
Kimlik doğrulamayı devre dışı bırakmak için anahtarları kaldırın veya .magg/auth.json adresinde varolmayan key_path ayarlayın

Kimlik Doğrulama Komutları

magg auth init - Kimlik doğrulamayı başlat (RSA anahtar çifti oluşturur)
magg auth status - Kimlik doğrulama yapılandırmasını kontrol et
magg auth token - JWT token oluştur
magg auth public-key - Genel anahtarı görüntüle (doğrulama için)
magg auth private-key - Özel anahtarı görüntüle (yedekleme için)

Daha fazla kullanım örneği için examples/authentication.py dosyasına bakın.

Yapılandırma

Magg, konfigürasyonunu geçerli çalışma dizininde .magg/config.json dosyasında saklar. Bu, projeye özgü araç konfigürasyonlarına izin verir.

Dinamik Konfigürasyon Yeniden Yükleme

Magg, yeniden başlatma gerektirmeden otomatik konfigürasyon yeniden yüklemeyi destekler:

Otomatik dosya izleme: config.json değişikliklerini algılar ve otomatik olarak yeniden yükler (mevcut olduğunda watchdog kullanır)
SIGHUP sinyali: Acil yeniden yüklemesi tetiklemek için kill -HUP <pid> gönder (Unix benzeri sistemler)
MCP aracı: Herhangi bir MCP istemcisinden magg_reload_config aracını kullan
Akıllı geçişler: Yeniden yükleme sırasında yalnızca etkilenen sunucular yeniden başlatılır

Konfigürasyon yeniden yükleme varsayılan olarak etkindir. Bunu kontrol edebilirsiniz:

MAGG_AUTO_RELOAD=false - Otomatik yeniden yüklemeyi devre dışı bırak
MAGG_RELOAD_POLL_INTERVAL=5.0 - Saniye cinsinden polling aralığını ayarla (watchdog mevcut olmadığında)

Detaylı bilgi için Konfigürasyon Yeniden Yükleme Belgelendirmesi bölümüne bakın.

Ortam Değişkenleri

Magg, yapılandırma için çeşitli ortam değişkenlerini destekler:

MAGG_CONFIG_PATH - Config dosya yolu (varsayılan: .magg/config.json)
MAGG_LOG_LEVEL - Günlük seviyesi: DEBUG, INFO, WARNING, ERROR, CRITICAL (varsayılan: INFO)
MAGG_STDERR_SHOW=1 - Subprocess MCP sunucularından stderr çıktısını göster (varsayılan: gizlenir)
MAGG_AUTO_RELOAD - Config auto-reload'u etkinleştir/devre dışı bırak (varsayılan: true)
MAGG_RELOAD_POLL_INTERVAL - Config polling aralığı saniye cinsinden (varsayılan: 1.0)
MAGG_READ_ONLY=true - Salt okunur modda çalıştır
MAGG_SELF_PREFIX - Magg araçları için ön ek (varsayılan: "magg"). Araçlar {prefix}{sep}{tool} olarak adlandırılır (örn. magg_list_servers)
MAGG_PREFIX_SEP - Ön ek ve araç adı arasındaki ayırıcı (varsayılan: "_")

Örnek yapılandırma:

{
  "servers": {
    "calculator": {
      "name": "calculator",
      "source": "https://github.com/executeautomation/calculator-mcp",
      "command": "npx @executeautomation/calculator-mcp",
      "prefix": "calc",
      "enabled": true
    }
  }
}

Sunucu Ekleme

Sunucular çeşitli yollarla eklenebilir:

LLM'yi kullanarak (önerilir):

"Playwright MCP sunucusunu ekle"
"Bir hesap makinesi aracı ara ve ekle"

magg_add_server üzerinden manuel yapılandırma:

name: playwright
url: https://github.com/microsoft/playwright-mcp
command: npx @playwright/mcp@latest
prefix: pw

Doğrudan config düzenleme: .magg/config.json dosyasını doğrudan düzenle

MaggClient ile Gerçek Zamanlı Bildirimler

MaggClient artık backend MCP sunucularından gerçek zamanlı bildirimleri destekler:

from magg import MaggClient, MaggMessageHandler

# Callback'ler kullanarak
handler = MaggMessageHandler(
    on_tool_list_changed=lambda n: print("Tools changed!"),
    on_progress=lambda n: print(f"Progress: {n.params.progress}")
)

async with MaggClient("http://localhost:8000/mcp", message_handler=handler) as client:
    # İstemci bağlıyken bildirimleri alacaktır
    tools = await client.list_tools()

Özel mesaj işleyicileri de dahil olmak üzere gelişmiş kullanım için Mesajlaşma Belgelendirmesi bölümüne bakın.

Kit Yönetimi

Magg, ilişkili MCP sunucularını grup olarak yüklenip boşaltılabilecek "kit'ler" halinde düzenlenmeyi destekler:

# Mevcut kit'leri listele
magg kit list

# Bir kit yükle (tüm sunucularını ekle)
magg kit load web-tools

# Bir kit'i boşalt (yalnızca o kit'teki sunucuları kaldır)
magg kit unload web-tools

# Bir kit hakkında bilgi al
magg kit info web-tools

Magg'e bir MCP istemcisi aracılığıyla bağlıyken kit'leri programlı olarak da yönetebilirsiniz:

magg_list_kits - Tüm mevcut kit'leri listele
magg_load_kit - Bir kit ve sunucularını yükle
magg_unload_kit - Bir kit'i boşalt
magg_kit_info - Detaylı kit bilgisi al

Kit'ler, ~/.magg/kit.d/ veya .magg/kit.d/ adresinde depolanan ve ilişkili sunucu koleksiyonunu tanımlayan JSON dosyalarıdır. Kit'leri oluşturma ve yönetme hakkında detaylı bilgi için Kit Belgelendirmesi bölümüne bakın.

MBro Script'leri

MBro script'leriyle yaygın iş akışlarını otomatikleştirin:

# Kurulum script'i oluştur
cat > setup.mbro <<EOF
# Magg'e bağlan ve durumu kontrol et
connect magg magg serve
call magg_status
call magg_list_servers

# Gerekirse yeni sunucu ekle
call magg_add_server name=calculator source="npx -y @modelcontextprotocol/server-calculator"
EOF

# Script'i çalıştır
mbro -x setup.mbro

Belgelendirme

Daha fazla belgelendirme için docs/ bölümüne bakın.

Görünümler

Magg birden fazla yerde görünür. Lütfen aşağıdaki bölüme alfabetik sırayla daha fazla görünüm eklemek için PR göndermekten çekinmeyin.

Listeleme, İndeks ve Diğer MCP Siteleri

DeepWiki - AI tarafından üretilen belgelendirme
[Glama.ai](https://glama.ai/mcp/servers/@

sitbon/magg

Bu MCP sunucusu hakkında