Dokümanlar

Bir Next.js projesini yerelde indeksleyen ve onun hakkındaki yapısal soruları yanıtlayan stdio MCP sunucusu. Node 20 veya üzeri. Native bağımlılık yok.

Kurulum

Bunu MCP istemcinizin yapılandırmasına ekleyin — Claude Code için .mcp.json, Cursor için .cursor/mcp.json, VS Code için .vscode/mcp.json. Blok her yerde birebir aynı.

{
  "mcpServers": {
    "nextjs-mcp-architecture": {
      "command": "npx",
      "args": ["-y", "nextjs-mcp-architecture@latest"]
    }
  }
}

Bilinçli olarak ne cwd var ne env. Sunucu, hangi projeye baktığını istemcinin zaten verdiği sinyallerden kendisi çıkarır.

Projenizi nasıl buluyor

Güven sırasına göre dokuz sinyal: bir araç argümanındaki mutlak yol, sabitlenmiş bir kök, açık bir ortam değişkeni, MCP istemcisinin kökleri, npm’in kendi çözümlediği ön ek, çalışma dizini, INIT_CWD, PWD ve son olarak agent’ınızın kendi MCP kaydı.

Her aday olduğu gibi kabul edilmek yerine gerçek bir Next.js uygulaması kanıtına karşı puanlanır; böylece güveni yüksek ama yanlış bir sinyal, güveni düşük ama doğrulanmış bir sinyale kaybeder. Monorepo’da andığınız yolu içeren uygulamaya çözülür; birden çok uygulama eşit derecede olasıysa tahmin etmek yerine bunu söyler ve hepsini listeler.

Yine de yanlış projeyi çözerse, herhangi bir araca projectRoot geçin ya da bir kez set_project_root çağırın.

Agent’ınızın buna uzanmasını sağlayın

Sunucuyu kurmak bir agent’ın alışkanlıklarını değiştirmez. grep yapmayı zaten bilen bir agent, talimatları ona daha iyi bir yol olduğunu söylemedikçe grep yapmaya devam eder — keşif maliyetini bir kez ödemekle her prompt’ta ödemek arasındaki fark budur.

Şunu AGENTS.md, CLAUDE.md ya da .github/copilot-instructions.md dosyanıza yapıştırın. Bilerek kısa: bu dosyalar her prompt’ta yüklenir, dolayısıyla buraya konacak bir sayfa dolusu metin sunucunun kazandırdığından fazlasını harcardı.

## Kodu bulma

Herhangi bir şey okumadan ya da aramadan **önce** `resolve_task_context` aracını
görevi sade bir dille yazarak çağır. Görevi sahiplenen dosyaları, onlara uygulanan
kuralları ve değişikliği doğrulayan komutu döndürür.

- Bir özelliği bulmak için glob ya da grep kullanma. Bu sunucunun ortadan
  kaldırmak için var olduğu maliyet tam olarak budur.
- Bir şeyin nerede tanımlandığını bulmak için dosya açmak yerine
  `find_symbol` kullan.
- URL ile adreslenen her şey için `get_route_context` kullan.
- İşi bitirdim demeden önce değiştirdiğin dosyalarda `check_conventions` çağır.

grep'e yalnızca bir aracın cevabında indeksin kısmi olduğunu söyleyen
`degradations` alanı varsa ya da dosyayı zaten kesin olarak biliyorsan dön.

Araçlar

Her pakette mevcut:

resolve_task_context

Görevi sade bir dille verin. Görevi sahiplenen birkaç dosyayı, geçerli kuralları ve doğrulayan komutları döndürür. Her türlü geliştirme, hata düzeltme ya da refactor için ilk çağrı bu olmalı.

find_symbol

Bir bileşenin, hook’un, fonksiyonun ya da tipin nerede tanımlandığı ve hangi dosyaların onu kullandığı — dosyaların tamamını okumadan.

get_route_context

Bir URL yolu için: onu sunan sayfa, onu saran layout, loading ve error dosyaları ve hangi kısımların client bileşeni olduğu.

get_project_profile

Gerçek teknoloji yığını — Next sürümü, router, yol takma adları, stil, UI kiti, veri ve form kütüphaneleri, ORM, i18n, test koşucuları.

get_project_conventions

Bu projenin uyduğu kurallar, her biri arkasındaki kanıtla birlikte; ayrıca projenin kendi talimat dosyalarının beyan ettikleri.

check_conventions

Değiştirdiğiniz dosyaları framework hataları ve kural sapması açısından denetler. İşi bitirdim demeden önce çağırın.

get_project_context

Hangi projenin, hangi sinyalle çözüldüğü ve hangi uygulamaları içerdiği.

list_projects

Bu makinede görünen her aday proje kökü, her biri için kanıtıyla.

set_project_root

Oturumun geri kalanı için projeyi sabitler.

Basic veya Pro lisansıyla nextjs-mcp-architecture-pro tarafından eklenir. Lisans yoksa hiç kaydedilmezler, dolayısıyla context’te hiçbir maliyetleri olmaz:

impact_analysis

Hangi dosya ve modüllerin tek bir dosyaya bağlı olduğu, etkinin nereye kadar uzandığı, hangi route’lara dokunduğu ve değişikliğin ne kadar riskli olduğu.

audit_architecture

Modül boyutları ve bağlılık, bağımlılık döngüleri, hiçbir yerden import edilmeyen dosyalar, en çok bağımlı olunan dosyalar, bekleyen framework hataları.

find_duplicates

Import’ları, yorumları ve string içeriklerini yok sayarak birbirinin neredeyse kopyası olan dosyalar.

Ücretli paketler

Ek paket sıradan bir npm paketi. Herkes indirebilir; lisans anahtarı olmadan hiçbir araç kaydetmez, dolayısıyla dosyalara sahip olmanın bir getirisi yok.

Projeye kurun ve lisans anahtarınızı tanımlayın:

npm install --save-dev nextjs-mcp-architecture-pro
export NEXTJS_MCP_LICENSE="your-key"

Anahtar ~/.config/nextjs-mcp/license dosyasında da durabilir; dizüstü bilgisayar için genelde daha iyisi budur. Pakete gömülü bir anahtara karşı çevrimdışı doğrulanır, yani ağ olmadan da çalışır. MCP yapılandırmanızda hiçbir şey değişmez.

Her şeyi tek dosyada tutmayı tercih ediyorsanız, doğrudan MCP yapılandırmasına da koyabilirsiniz:

{
  "mcpServers": {
    "nextjs-mcp-architecture": {
      "command": "npx",
      "args": ["-y", "nextjs-mcp-architecture@latest"],
      "env": { "NEXTJS_MCP_LICENSE": "your-key" }
    }
  }
}

Tek kimlik bilginiz lisans anahtarı. Yukarıdaki yapılandırma dosyası çoğu zaman depoya işlenir — kendi dosyanızın işlenmediğinden emin değilseniz ~/.config/nextjs-mcp/license tercih edin.

Pano

npx nextjs-mcp-dashboard

Yalnızca 127.0.0.1 üzerine bağlanır, Host başlığı bir loopback adı olmayan her isteği reddeder, GET dışında hiçbir şeye yanıt vermez ve projenize asla yazmaz. Bayraklar: --project, --port, --host, --no-open.

Makinenizden ne çıkıyor

Hiçbir şey. İndeksleme, kural öğrenme ve denetim tamamen yerelde çalışır. Türetilen veriler, proje yolunun hash’iyle anahtarlanarak işletim sisteminizin önbellek dizinine yazılır — deponuzun içine asla, çalışma dizinine asla. Lisans doğrulaması çevrimdışı bir imza kontrolüdür.

Sorun giderme

Yanlış proje hakkında cevap verdi

Hangi projeyi hangi sinyalle çözdüğünü görmek için get_project_context çağırın, sonra doğrusunu sabitlemek için set_project_root kullanın.

Bir araç yalnızca bazı dosyaların okunduğunu söylüyor

Her dosya, her pakette adı ve yolu ile indekstedir. Paketin sınırladığı şey kaç dosyanın içeriğinin okunduğudur — ücretsiz pakette 500 dosya, ağacın tamamına yayılarak. Bir dosyanın içinde yazana bağlı bir eşleşme kaçabilir; ama bir dosya görünmez olamaz.

Ücretli araçlar görünmüyor

Yalnızca geçerli bir lisansla kaydedilirler. Sunucuyu başlatıp stderr’a bakın: lisansı olmayan kurulu bir ek paket bunu tek satırda söyler.

Bir kural yanlış görünüyor

Her kural örneklem büyüklüğünü ve bir karşı örneği taşır. Sayılar deponuzla uyuşmuyorsa muhtemelen dosya sınıflandırması hatalıdır — rol, içerikten çıkarıldığı için alışılmadık bir iş yapan dosya yanlış rol altında sayılabilir.