mcp-github-advanced 0.1.0__tar.gz

mcp_github_advanced-0.1.0/.agent/rules/github-api-rules.md

@@ -0,0 +1,66 @@
+---
+description: mcp-github-advanced için GitHub API kuralları ve konvansiyonları
+---
+
+# GitHub API Kuralları
+
+## Versiyonlu Header'lar (ZORUNLU)
+
+Her GitHub API isteğinde şu header'lar **mutlaka** bulunmalıdır:
+
+```python
+headers = {
+    "Authorization": f"Bearer {token}",
+    "Accept": "application/vnd.github+json",
+    "X-GitHub-Api-Version": "2022-11-28",
+}
+```
+
+Bu header'lar olmadan **asla** GitHub API isteği gönderilmez.
+
+## Rate Limit (İstek Sınırı)
+
+- Kimlik doğrulamalı: 5000 istek/saat (REST), 5000 puan/saat (GraphQL)
+- Her yanıttan sonra `X-RateLimit-Remaining` kontrol edilir
+- Kalan < 10 olduğunda: `X-RateLimit-Reset` zamanına kadar beklenir
+- 429/403 yanıtları için `tenacity` ile üstel geri çekilme (exponential backoff) uygulanır
+
+```python
+remaining = int(resp.headers.get("X-RateLimit-Remaining", 1))
+if remaining < 10:
+    reset_time = int(resp.headers.get("X-RateLimit-Reset", 0))
+    wait = reset_time - time.time()
+    await asyncio.sleep(max(wait, 0))
+```
+
+## Çıktı Sınırları
+
+- MCP araç çıktıları **8192 token'ı (~30.000 karakter) aşmamalıdır**
+- Büyük diff'ler (>1MB) chunk'lara bölünmelidir
+- Kısaltma için `_chunk_text()` yardımcı fonksiyonu kullanılır
+
+## REST API Kalıpları
+
+- Temel URL: `https://api.github.com`
+- Zaman aşımı: 30 saniye
+- Sayfalama: `per_page` parametresi kullanılır (maks. 100)
+- Hata yanıtları: `httpx.HTTPStatusError` fırlatılır
+
+## GraphQL API
+
+- Uç nokta: `https://api.github.com/graphql`
+- Şu durumlarda kullanılır: katkıda bulunan istatistikleri, karmaşık sorgular
+- Yanıtta `data.errors` kontrol edilir
+
+## Token İzinleri (Scopes)
+
+- `repo`: Özel (private) repolar için gerekli
+- `read:user`: Kullanıcı profili için gerekli
+- PAT: Yalnızca kendi repoları için çalışır
+- OAuth: Başka kullanıcıların repolarına da erişebilir (izin ile)
+
+## Önbellekleme (Caching)
+
+- Önbellek anahtar formatı: `github:{owner}:{repo}:{tool_name}`
+- Yazma işlemleri **asla** önbelleğe alınmaz (create_issue, create_pr_review)
+- TTL değerleri `cache.py` içinde tanımlıdır

mcp_github_advanced-0.1.0/.agent/rules/mcp-protocol.md

@@ -0,0 +1,61 @@
+---
+description: mcp-github-advanced için MCP protokol kuralları ve konvansiyonları
+---
+
+# MCP Protokol Kuralları
+
+## Sunucu Uygulaması
+
+- Low-level `mcp.server.Server` kullanılır — `FastMCP` **KULLANILMAZ**
+- Transport: `stdio` — `mcp.server.stdio.stdio_server` ile
+- Araçlar `@app.list_tools()` ve `@app.call_tool()` dekoratörleri ile kaydedilir
+
+## Araç Kaydı
+
+- Tüm araçlar `server.py` içindeki `TOOLS` listesinde tanımlanır
+- Her araçta şunlar gereklidir: `name`, `description`, `inputSchema`
+- Giriş şeması JSON Schema formatını takip eder
+- Zorunlu parametreler `"required"` dizisinde listelenir
+
+## Araç Yanıt Formatı
+
+- Her zaman `list[TextContent]` döndürülür
+- Veri JSON olarak serileştirilir: `json.dumps(result, indent=2, ensure_ascii=False)`
+- Hata durumunda: hata mesajı ile `TextContent` döndürülür (istisna fırlatılmaz)
+- Çıktı 8192 token'ın altında tutulmak için kesilir
+
+## Giriş Noktası
+
+```python
+# pyproject.toml
+[project.scripts]
+mcp-github-advanced = "mcp_github_advanced.server:main"
+```
+
+```python
+# server.py
+def main() -> None:
+    asyncio.run(_run())
+```
+
+## Yaşam Döngüsü
+
+1. `AuthManager`, `RedisCache`, `GitHubClient` başlatılır
+2. `github_client.start()` ile HTTP bağlantıları açılır
+3. `stdio_server()` bağlamı → `app.run()` çalıştırılır
+4. Kapanışta: `github_client.close()` çağrılır
+
+## Yeni Araç Ekleme
+
+1. `github.py` içindeki `GitHubClient`'a yeni metod ekle
+2. `server.py`'daki `TOOLS` listesine `Tool(...)` tanımı ekle
+3. `_dispatch()` fonksiyonuna yeni `case` dalı ekle
+4. Önbelleğe alınabilirse `cache.py`'ye TTL girişi ekle
+5. `test_github.py` ve `test_server.py`'ye testler ekle
+
+## LLM Entegrasyonu
+
+- Model: `gemini-2.0-flash` — `langchain-google-genai` paketi ile
+- `temperature=0` — tutarlı kod analizi için
+- `max_tokens=8192` çıktı limiti
+- Araç çıktıları bu limitin içinde kalmalıdır

mcp_github_advanced-0.1.0/.agent/rules/python-style.md

@@ -0,0 +1,46 @@
+---
+description: mcp-github-advanced için Python stil ve formatlama kuralları
+---
+
+# Python Stil Kuralları
+
+## Genel
+- Python 3.10+ ile `from __future__ import annotations` kullanılır
+- Satır uzunluğu: en fazla 100 karakter (`pyproject.toml`'de yapılandırılır)
+- Lint için `ruff` kullanılır: `ruff check src/ tests/`
+
+## Formatlama
+- Girintileme: 4 boşluk (tab yok)
+- String'ler için çift tırnak kullanılır
+- Çok satırlı yapılarda sondaki virgül yazılır
+- `.format()` veya `%` yerine f-string tercih edilir
+
+## Tür İpuçları (Type Hints)
+- Tüm fonksiyon imzalarında tür ipucu kullanılır
+- Nullable türler için `Optional[T]` veya `T | None` kullanılır
+- Büyük harfli jenerikler yerine küçük harfli kullanılır: `dict[str, Any]` (`Dict[str, Any]` değil)
+
+## İçe Aktarmalar (Imports)
+- Gruplandırma sırası: stdlib → üçüncü parti → yerel
+- `ruff` ile otomatik sıralama yapılır (`select = ["I"]` pyproject.toml'de)
+- Mutlak import tercih edilir
+
+## İsimlendirme
+- `snake_case` → fonksiyonlar, değişkenler, modüller
+- `PascalCase` → sınıflar
+- `UPPER_SNAKE_CASE` → sabitler
+- Özel (private) metod ve nitelikler `_` ile başlar
+
+## Asenkron (Async)
+- Tüm GitHub API etkileşimleri async olmalıdır (`async def`)
+- `requests` yerine `httpx.AsyncClient` kullanılır
+- `asyncio.run()` yalnızca giriş noktalarında kullanılır
+
+## Docstring'ler
+- Tüm public fonksiyon ve sınıflar için Google-stil docstring yazılır
+- Gerektiğinde `Args:`, `Returns:`, `Raises:` bölümleri eklenir
+
+## Hata Yönetimi
+- İstisnalar sessizce yutulmaz
+- Kritik olmayan hatalar için uyarı loglanır (örn: önbellek ıskalamaları)
+- Genel `Exception` yerine spesifik istisnalar fırlatılır

mcp_github_advanced-0.1.0/.agent/skills/github-mcp/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: github-mcp
+description: mcp-github-advanced MCP sunucu kod tabanı ile çalışma becerisi
+---
+
+# GitHub MCP Becerisi
+
+Bu beceri, `mcp-github-advanced` MCP sunucu kod tabanı ile çalışmak için talimatlar sağlar.
+
+## Genel Bakış
+
+`mcp-github-advanced`, Model Context Protocol üzerinden 14 GitHub API aracını sunan bir MCP sunucusudur. Desteklediği özellikler:
+
+- **GitHub REST API v3** — repolar, commit'ler, PR'lar, issue'lar, actions
+- **GitHub GraphQL v4** — katkıda bulunan istatistikleri, karmaşık sorgular
+- **Redis önbellekleme** — akıllı TTL stratejisi ile
+- **PAT + OAuth 2.0** — çift kimlik doğrulama desteği
+- **LLM entegrasyonu** — `gemini-2.0-flash` ve `langchain-google-genai` ile
+
+## Mimari
+
+```
+server.py  →  14 MCP aracı (list_tools + call_tool)
+  ├── github.py  →  REST + GraphQL istemcisi (httpx async)
+  ├── auth.py    →  PAT + OAuth 2.0 kimlik doğrulama
+  └── cache.py   →  TTL stratejili Redis önbellekleme
+```
+
+## Temel Konvansiyonlar
+
+### 1. Versiyonlu API Header'ları
+
+**Her** GitHub API isteğinde şunlar bulunmalıdır:
+```python
+{
+    "Authorization": f"Bearer {token}",
+    "Accept": "application/vnd.github+json",
+    "X-GitHub-Api-Version": "2022-11-28",
+}
+```
+
+### 2. Rate Limit (İstek Sınırı)
+
+- Her yanıttan sonra `X-RateLimit-Remaining` kontrol edilir
+- Kalan < 10 olduğunda bekle
+- 429/403 için `tenacity` retry kullan
+
+### 3. Çıktı Kesme (Chunking)
+
+- Maksimum çıktı ≈ 30.000 karakter (~8192 token)
+- Kısaltma için `_chunk_text()` kullanılır
+- Tek dosya yama (patch) çıktısı 5000 karakterle sınırlıdır
+
+### 4. Önbellek TTL Stratejisi
+
+| Araç | TTL |
+|------|-----|
+| `get_repo_info` | 1 saat |
+| `list_commits` | 5 dk |
+| `get_pr_diff` | 10 dk |
+| `get_workflow_logs` | 1 dk |
+| `get_file_content` | 30 dk |
+| Yazma işlemleri | Önbellek yok |
+
+### 5. Test Etme
+
+- HTTP mocklama için **her zaman** `respx` kullanılır
+- Testlerde **asla** gerçek GitHub API'ye istek gönderilmez
+- Test senaryoları: başarılı, 404, 401, rate limit
+
+### 6. LLM
+
+- Model: `gemini-2.0-flash`
+- `temperature=0` — tutarlı kod analizi için
+- `max_tokens=8192`
+- Paket: `langchain-google-genai`
+
+## Sık Yapılan İşlemler
+
+- **Araç ekle**: Bkz. `.agent/workflows/add-tool.md`
+- **Yayınla**: Bkz. `.agent/workflows/publish-to-pypi.md`
+- **Test çalıştır**: `pytest` (`asyncio_mode = "auto"` ile)
+- **Lint**: `ruff check src/ tests/`
+
+## Dosya Haritası
+
+| Dosya | Amacı |
+|-------|-------|
+| `server.py` | MCP sunucusu, 14 araç tanımı, yönlendirici |
+| `github.py` | GitHub API istemcisi (REST + GraphQL) |
+| `auth.py` | PAT + OAuth 2.0 kimlik doğrulama |
+| `cache.py` | TTL'li Redis önbellekleme |
+| `__init__.py` | Versiyon bilgisi |
+| `__main__.py` | `python -m` giriş noktası |

mcp_github_advanced-0.1.0/.agent/workflows/add-tool.md

@@ -0,0 +1,115 @@
+---
+description: Sunucuya yeni bir MCP aracı nasıl eklenir
+---
+
+# Yeni MCP Aracı Ekleme
+
+`mcp-github-advanced` sunucusuna yeni bir araç eklemek için şu adımları izleyin.
+
+## 1. GitHub İstemci Metodunu Uygula
+
+`src/mcp_github_advanced/github.py` dosyasında `GitHubClient`'a yeni bir async metod ekleyin:
+
+```python
+async def yeni_arac_adi(self, owner: str, repo: str, ...) -> dict:
+    """Bu aracın ne yaptığını açıklayan docstring."""
+    # Önbellekten kontrol et
+    if self.cache:
+        cached = await self.cache.get(owner, repo, "yeni_arac_adi")
+        if cached:
+            return cached
+
+    # Versiyonlu header'lar ile API isteği gönder (self.headers ile otomatik)
+    resp = await self._get(f"{GITHUB_API}/repos/{owner}/{repo}/endpoint")
+    data = resp.json()
+
+    # Yanıtı dönüştür
+    result = { ... }
+
+    # Büyük çıktıları kes
+    if "content" in result:
+        result["content"] = _chunk_text(result["content"])
+
+    # Sonucu önbelleğe al
+    if self.cache:
+        await self.cache.set(owner, repo, "yeni_arac_adi", result)
+    return result
+```
+
+## 2. Önbellek TTL'si Ekle
+
+`src/mcp_github_advanced/cache.py` dosyasına TTL girişi ekleyin:
+
+```python
+TTL = {
+    ...
+    "yeni_arac_adi": 300,  # 5 dakika (veya uygun TTL değeri)
+}
+```
+
+## 3. Aracı Kaydet
+
+`src/mcp_github_advanced/server.py` dosyasındaki `TOOLS` listesine ekleyin:
+
+```python
+Tool(
+    name="yeni_arac_adi",
+    description="Aracın ne yaptığının açıklaması",
+    inputSchema={
+        "type": "object",
+        "properties": {
+            "owner": {"type": "string", "description": "Repo sahibi"},
+            "repo": {"type": "string", "description": "Repo adı"},
+            # ... ek parametreler
+        },
+        "required": ["owner", "repo"],
+    },
+),
+```
+
+## 4. Yönlendirme Dalı Ekle
+
+`server.py`'deki `_dispatch()` fonksiyonuna:
+
+```python
+case "yeni_arac_adi":
+    return await gh.yeni_arac_adi(owner, repo, ...)
+```
+
+## 5. Testleri Yaz
+
+`tests/test_github.py` dosyasına:
+
+```python
+class TestYeniAracAdi:
+    @respx.mock
+    async def test_basarili(self, github_client):
+        respx.get("https://api.github.com/repos/owner/repo/endpoint").mock(
+            return_value=httpx.Response(200, json={...})
+        )
+        result = await github_client.yeni_arac_adi("owner", "repo")
+        assert result[...] == beklenen_deger
+
+    @respx.mock
+    async def test_404_bulunamadi(self, github_client):
+        # 404 senaryosunu test et
+        ...
+
+    @respx.mock
+    async def test_401_yetkisiz(self, github_client):
+        # Yetkisiz erişim senaryosunu test et
+        ...
+```
+
+## 6. Dokümantasyonu Güncelle
+
+- `AGENTS.md` içindeki araç tablosuna ekle
+- `README.md` özellikler tablosuna ekle
+- Gerekirse `__init__.py`'deki versiyonu artır
+
+## 7. Commit At
+
+```bash
+git add .
+git commit -m "feat: yeni_arac_adi araci eklendi"
+```

mcp_github_advanced-0.1.0/.agent/workflows/publish-to-pypi.md

@@ -0,0 +1,105 @@
+---
+description: mcp-github-advanced paketini PyPI'ye nasıl yayınlanır
+---
+
+# PyPI'ye Yayınlama
+
+## Ön Koşullar
+
+- API token'ı olan bir PyPI hesabı
+- `build` ve `twine` paketlerinin kurulu olması
+
+## Adımlar
+
+### 1. Versiyonu Güncelle
+
+`src/mcp_github_advanced/__init__.py` dosyasını düzenleyin:
+
+```python
+__version__ = "0.1.1"  # versiyonu artır
+```
+
+### 2. Önceki Derleme Dosyalarını Temizle
+
+```bash
+rm -rf dist/ build/ *.egg-info
+```
+
+### 3. Paketi Derle
+
+```bash
+pip install build
+python -m build
+```
+
+Bu şunları oluşturur:
+- `dist/mcp_github_advanced-0.1.1.tar.gz`
+- `dist/mcp_github_advanced-0.1.1-py3-none-any.whl`
+
+### 4. Paketi Kontrol Et
+
+```bash
+pip install twine
+twine check dist/*
+```
+
+### 5. Test PyPI'ye Yükle (Opsiyonel)
+
+```bash
+twine upload --repository testpypi dist/*
+```
+
+Doğrulama: `pip install -i https://test.pypi.org/simple/ mcp-github-advanced`
+
+### 6. PyPI'ye Yükle
+
+```bash
+twine upload dist/*
+```
+
+Şunlar sorulacaktır:
+- Kullanıcı adı: `__token__`
+- Şifre: PyPI API token'ınız (`pypi-...`)
+
+### 7. Kurulumu Doğrula
+
+```bash
+pip install mcp-github-advanced
+uvx mcp-github-advanced --help
+```
+
+### 8. Git Etiketi Oluştur
+
+```bash
+git tag -a v0.1.1 -m "Sürüm v0.1.1"
+git push origin v0.1.1
+```
+
+### 9. GitHub Sürümü Oluştur
+
+Etiketten bir GitHub sürümü oluşturun ve değişiklik günlüğünü ekleyin.
+
+## CI/CD Otomasyonu (Opsiyonel)
+
+Etiket push'unda otomatik yayınlama için `.github/workflows/publish.yml` ekleyin:
+
+```yaml
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine upload dist/*
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
+```

mcp_github_advanced-0.1.0/.env.example

@@ -0,0 +1,18 @@
+# ─────────────────────────────────────────────
+# mcp-github-advanced — Ortam Değişkenleri
+# ─────────────────────────────────────────────
+
+# GitHub Kimlik Doğrulama
+GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx      # PAT (Kişisel Erişim Token'ı)
+GITHUB_CLIENT_ID=Ov23xxxxxxxxxxxxx         # OAuth Uygulama İstemci ID'si
+GITHUB_CLIENT_SECRET=xxxxxxxxxxxxxxxx      # OAuth Uygulama İstemci Gizli Anahtarı
+
+# Redis Önbellek
+REDIS_URL=redis://localhost:6379/0
+
+# Sunucu Ayarları
+MCP_SERVER_NAME=mcp-github-advanced
+LOG_LEVEL=INFO
+
+# Google Gemini (LLM)
+GOOGLE_API_KEY=AIzaSyXXXXXXXXXXXXXXXXXXX

mcp_github_advanced-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Ortam
+.env
+.venv/
+venv/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Test
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Gemini
+.gemini/