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

# 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:

{
  "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
• MCP TypeScript SDK
• Google Lighthouse
• Next.js SEO
• Web Core Vitals
• WCAG Standartları