# MCP Frontend Analyzer

Google Lighthouse analizi, kod kalite kontrolü, SEO metadata denetimi, erişilebilirlik analizi ve bundle optimizasyonu sunan kapsamlı bir MCP (Model Context Protocol) server'ı. React ve Next.js projelerinde AI agent'ına frontend uzmanlığı kazandırır.

## Mimari

```
┌──────────────┐     stdio      ┌────────────────────────────────────┐
│  Cursor IDE  │ ◄────────────► │  MCP Server (8 Tool)               │
│  (AI Agent)  │   JSON-RPC     │                                    │
└──────────────┘                │  ┌──────────────────────────────┐  │
                                │  │ lighthouse.ts                │  │
                                │  │ Chrome + Lighthouse analiz   │  │
                                │  └──────────────────────────────┘  │
                                │  ┌──────────────────────────┐      │
                                │  │ recommendations.ts       │      │
                                │  │ SEO/React/Next önerileri │      │
                                │  └──────────────────────────┘      │
                                │  ┌──────────────────────────────┐  │
                                │  │ tools/                       │  │
                                │  │ ├─ check-component-quality   │  │
                                │  │ ├─ check-metadata            │  │
                                │  │ ├─ check-accessibility       │  │
                                │  │ ├─ check-bundle              │  │
                                │  │ └─ compare-lighthouse        │  │
                                │  └──────────────────────────────┘  │
                                └────────────────────────────────────┘
```

## Kurulum

```bash
# 1. Proje klasörüne git
cd ~/Desktop/MCP-Frontend-Analyzer

# 2. Bağımlılıkları kur
npm install

# 3. TypeScript'i derle
npm run build
```

## MCP Araçları (8 Tool)

### 1. `lighthouse_analyze`
Belirtilen URL üzerinde Google Lighthouse analizi çalıştırır.

**Parametreler:**
- `url` (zorunlu): Analiz edilecek URL (`https://...`)
- `categories` (opsiyonel): `["performance", "seo", "accessibility", "best-practices"]`
- `device` (opsiyonel): `"mobile"` veya `"desktop"` (varsayılan: mobile)

**Örnek kullanım:**
> "https://example.com sitesinin SEO puanını analiz et"

---

### 2. `get_seo_recommendations`
React/Next.js projeleri için SEO, performans ve erişilebilirlik önerileri döner.

**Parametreler:**
- `category` (opsiyonel): `"seo"`, `"performance"`, `"accessibility"`, `"best-practices"`

**Örnek kullanım:**
> "Next.js'te SEO için best practice'ler neler?"

---

### 3. `nextjs_code_review`
Verilen React/Next.js kodunu SEO ve performans açısından analiz eder.

**Parametreler:**
- `code` (zorunlu): Analiz edilecek kod
- `filename` (opsiyonel): Dosya adı (bağlamsal analiz için)

**Örnek kullanım:**
> "Bu page.tsx dosyamı SEO açısından incele"

---

### 4. `check_component_quality`
Component dosyasının kod kalitesini analiz edip 0-100 arası skor verir.

**Kontrol ettikleri:**
- Page/Layout default export zorunluluğu
- Layout `children` prop zorunluluğu
- Satır sayısı limiti (150/250 eşik)
- Hook yoğunluğu (SOLID - Single Responsibility)
- `any` tipi kullanımı
- `console.log` tespiti
- Relative import tespiti
- Import sıralaması
- Gereksiz `'use client'`
- Class component tespiti
- Props type/interface eksikliği
- Manuel `useMemo`/`useCallback`
- Inline style kullanımı
- İç içe ternary operatör
- Boş catch bloğu (silent catch)

**Parametreler:**
- `code` (zorunlu): Component kodu
- `filename` (opsiyonel): Dosya adı

**Örnek kullanım:**
> "Bu component'in kalitesini kontrol et"

---

### 5. `check_metadata`
Next.js page/layout dosyasının SEO metadata eksiksizliğini kontrol eder.

**Kontrol ettikleri:**
- `metadata` / `generateMetadata` export
- Static/Dynamic sayfa türüne göre doğru metadata yöntemi kontrolü
- title, description tanımları
- OpenGraph (title, description, images, type, locale, siteName)
- Twitter card
- Canonical URL
- Robots direktifi
- HTML lang attribute (layout)
- Viewport export (layout)
- JSON-LD yapılandırılmış veri

**Parametreler:**
- `code` (zorunlu): Sayfa/layout kodu
- `filename` (opsiyonel): Dosya adı
- `pageType` (opsiyonel): `"static"` veya `"dynamic"`

**Örnek kullanım:**
> "Bu sayfanın metadata'sı eksiksiz mi?"

---

### 6. `check_accessibility`
Component'i erişilebilirlik (a11y) açısından WCAG standartlarına göre analiz eder.

**Kontrol ettikleri:**
- Layout'ta `lang` attribute zorunluluğu (WCAG 3.1.1)
- Page'de `<h1>` zorunluluğu (WCAG 1.3.1)
- Layout'ta skip navigation kontrolü (WCAG 2.4.1)
- Semantic HTML vs div soup
- Heading hiyerarşisi (tek h1, ardışık seviyeler)
- Image alt text (eksik, boş, anlamsız)
- İkon butonlarda aria-label
- `<div onClick>` anti-pattern (klavye erişilemez)
- Link güvenliği (`target="_blank"` + `rel`)
- Link title attribute
- Form input label/aria-label
- Nav aria-label (çoklu nav)
- autoFocus anti-pattern
- Renk kontrast ipuçları

**Parametreler:**
- `code` (zorunlu): Component kodu
- `filename` (opsiyonel): Dosya adı

**Örnek kullanım:**
> "Bu component erişilebilir mi?"

---

### 7. `check_bundle`
Dosyanın JavaScript bundle boyutuna etkisini analiz eder.

**Kontrol ettikleri:**
- Layout'ta `'use client'` riski (tüm sayfa ağacı etkilenir)
- Page'de ağır client bundle tespiti
- Ağır kütüphane import'ları (moment, lodash, axios, MUI, antd, Chart.js)
- Barrel export anti-pattern (tree-shaking kırılması)
- Dynamic import adayları (Modal, Chart, Editor, Map, PDF vb.)
- Gereksiz `'use client'` (bundle etkisi)
- Büyük client component (import sayısı)
- Third-party script stratejisi (`<script>` vs `next/script`)
- Wildcard re-export (`export * from`)
- package.json bağımlılık analizi

**Parametreler:**
- `code` (zorunlu): Dosya kodu
- `filename` (opsiyonel): Dosya adı
- `packageJsonContent` (opsiyonel): package.json içeriği

**Örnek kullanım:**
> "Bu dosyanın bundle etkisini analiz et"

---

### 8. `compare_lighthouse`
İki URL'yi Lighthouse ile analiz edip karşılaştırma raporu çıkarır.

**Parametreler:**
- `url1` (zorunlu): İlk URL (mevcut/production)
- `url2` (zorunlu): İkinci URL (yeni/staging)
- `categories` (opsiyonel): Karşılaştırılacak kategoriler
- `device` (opsiyonel): `"mobile"` veya `"desktop"`

**Örnek kullanım:**
> "Staging ve production'ı karşılaştır"

## Cursor Yapılandırması

`~/.cursor/mcp.json` dosyasında:

```json
{
  "mcpServers": {
    "mcp-frontend-analyzer": {
      "command": "node",
      "args": ["/Users/KULLANICI_ADI/Desktop/MCP-Frontend-Analyzer/dist/index.js"]
    }
  }
}
```

## Dosya Yapısı

```
MCP-Frontend-Analyzer/
├── src/
│   ├── index.ts                          # MCP Server giriş noktası (tool kayıtları)
│   ├── lighthouse.ts                     # Lighthouse analiz motoru (Chrome + headless)
│   ├── recommendations.ts               # SEO/React/Next.js öneri veritabanı
│   └── tools/
│       ├── code-review.ts              # Next.js kod inceleme (SEO, performans, a11y)
│       ├── check-component-quality.ts   # Kod kalite analizi (SOLID, satır limiti, any, hook)
│       ├── check-metadata.ts            # SEO metadata kontrolü (OG, Twitter, canonical)
│       ├── check-accessibility.ts       # Erişilebilirlik analizi (WCAG referanslı)
│       ├── check-bundle.ts             # Bundle boyut analizi (ağır lib, tree-shake)
│       └── compare-lighthouse.ts       # İki URL Lighthouse karşılaştırması
├── dist/                                # Derlenmiş JS çıktısı
├── package.json
├── tsconfig.json
└── README.md
```

## Nasıl Çalışır?

1. Cursor IDE, `mcp.json`'daki yapılandırmaya göre server'ı child process olarak başlatır
2. İletişim stdio (stdin/stdout) üzerinden JSON-RPC formatında yapılır
3. AI agent, tanımlanan 8 tool'u çağırabilir
4. Kod analiz tool'ları (quality, metadata, a11y, bundle) regex ve string analizi ile çalışır — harici bağımlılık gerektirmez
5. Lighthouse tool'ları Chrome'u headless modda başlatıp web sayfası analizi yapar
6. Sonuçlar AI agent'a gönderilir, agent kullanıcıya özetler ve öneriler sunar

## Öğrenme Kaynakları

- [MCP Protokolü Dokümantasyonu](https://modelcontextprotocol.io)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- [Google Lighthouse](https://developer.chrome.com/docs/lighthouse)
- [Next.js SEO](https://nextjs.org/docs/app/building-your-application/optimizing/metadata)
- [Web Core Vitals](https://web.dev/vitals/)
- [WCAG Standartları](https://www.w3.org/WAI/standards-guidelines/wcag/)