FileScopeMCP

AI'nız zaten kod yazmasını biliyor. Artık kod tabanınızı da tanıyor.

FileScopeMCP kodunuzu izler, her dosyayı öneme göre sıralar, tüm bağımlılıkları haritalandırır ve AI tarafından oluşturulan özetleri arka planda güncel tutar. LLM'niz "bu dosya ne yapar?" diye sorduğunda — kaynağı okumadan gerçek bir cevap alır.

Claude Code, Hermes Agent, Codex, OpenClaw, Cursor AI ile veya bağımsız bir daemon olarak çalışır. TypeScript, JavaScript, Python, C, C++, Rust, Go, Ruby, Lua, Zig, PHP, C# ve Java'yı destekler.

Temel Özellikler

Önem sıralaması — her dosya 0-10 arasında puanlandırılır; kaç şeyin bağlı olduğu, ne export ettiği ve nerede bulunduğuna göre. LLM'niz kritik dosyaları ilk önce görür.

Bağımlılık haritası — desteklenen tüm dillerde çift yönlü import takibi. AST seviyesi çıkarım (tree-sitter) TS/JS, Python, C, C++ ve Rust için; regex tabanlı Go, Ruby, Lua, Zig, PHP, C# ve Java için. Döngüsel bağımlılıkları da bulur.

Symbol zekası — tree-sitter aracılığıyla TypeScript, JavaScript, Python, Go ve Ruby için fonksiyonları, sınıfları, interface'leri, tipleri, enum'ları, const'ları, modülleri ve struct'ları çıkarır. find_symbol adları dosya + satır aralığına çözer. find_callers ve find_callees TS/JS için call graph'i haritalandırır, böylece AI'nız refactor'lamadan önce "bu fonksiyonu kim çağırıyor?" sorusuna cevap verebilir.

Daima güncel — dosya izleyici + anlamsal değişim algılaması metadata'yı otomatik olarak günceller. TS/JS için AST seviyesi diffing, diğer her şey için LLM tabanlı analiz. Yalnızca gerçekten değişen şeyler yeniden işlenir.

LLM broker — arka plan süreci tüm AI işini llama.cpp'nin llama-server'ı aracılığıyla (veya OpenAI uyumlu herhangi bir HTTP API) koordine eder. Öncelik kuyruğu interaktif sorguların arka plan işlemesini geride bırakmasını sağlar. Tek bir GPU'da çalışır.

Nexus dashboard — localhost:1234 konumundaki bir web UI, tüm depoları arasında kod tabanınızı görsel olarak keşfetmenizi sağlar. İnteraktif bağımlılık grafikleri, dosya ayrıntı panelleri, canlı broker aktivitesi ve depo başına sağlık izleme.

Ön Koşullar

• Node.js >= 22 ve npm (indir)
• Build araçları native modüller için (better-sqlite3, tree-sitter):
  • Linux: sudo apt install build-essential python3
  • macOS: xcode-select --install
  • Windows: Visual Studio Build Tools (C++ workload ile)

Hızlı Başlangıç

git clone https://github.com/admica/FileScopeMCP.git
cd FileScopeMCP
./build.sh          # deps kurar, derler, Claude Code'a kaydeder

./build.sh FileScopeMCP'yi claude mcp add --scope user aracılığıyla global olarak kaydeder (idempotent; npm run register-mcp ile yeniden çalıştırın). claude CLI eksikse, build yine de başarılı olur — diğer MCP istemcileri için docs/mcp-clients.md bölümüne bakın.

Herhangi bir projede Claude Code oturumu açın ve FileScopeMCP otomatik olarak başlatılır. MCP araçları otomatik olarak görünür — AI'nız konuşma sırasında doğrudan çağırabilir:

find_important_files(limit: 5)
status()

Fikir sahibi Claude Code yüklemesi (önerilen)

Proje primer CLAUDE.md ekleyen ve isteğe bağlı hook şablonlarına işaret eden daha zengin bir yükleme için:

npm run install-claude-code   # veya: npx filescope-install --claude-code

Komut katmanlıdır, invazif değildir — asla .claude/settings.json dosyasına otomatik yazma yapmaz. Hook şablonları docs/claude-code-hooks.md konumunda belgelenmiştir; istediğiniz zaman ayarlarınıza yapıştırın. CLAUDE.md primer <!-- BEGIN filescope --> / <!-- END filescope --> işaretleriyle sarılıdır, böylece çevre içeriğine dokunmadan temiz bir şekilde eklenebilir, değiştirilebilir veya kaldırılabilir. Tasarım gerekçesi için ROADMAP.md Aşama 1'e bakın.

Agent Runtimes (Hermes, Codex, OpenClaw)

Agent runtimes FileScopeMCP'yi repo'nun AGENTS.md aracılığıyla keşfeder; bu dosya MCP kaydı config'i, broker/LLM kurulumu ve skills/filescope-mcp/SKILL.md konumundaki taşınabilir skill dosyasına işaret içerir.

Hermes — ~/.hermes/config.yaml dosyasına ekleyin:

mcp_servers:
  filescope:
    command: "node"
    args: ["/path/to/FileScopeMCP/dist/mcp-server.js"]
    timeout: 120

Zaten çalışan bir yerel LLM var mı? Broker'ı ona yönlendirin — ~/.filescope/broker.json düzenleyin ve baseURL'i LLM'nizin endpoint'ine ayarlayın. Ayrıntılar için AGENTS.md'ye bakın.

LLM Özetleri (İsteğe Bağlı)

Platform spesifik bir rehber için ./setup-llm.sh çalıştırın; ayrıntılar için docs/llm-setup.md konumuna bakın. Linux'ta sudo ./setup-llm.sh --install-service aracılığıyla llama-server'ı systemd birimi olarak kaydedebilirsiniz (loglar journalctl'e akar, OOM korumalı, boot'ta otomatik yeniden başla). Flag, llama-server Windows host'u üzerinde çalışır olduğundan WSL2 altında bir no-op'tur. Tamamen llama-server olmadan, her şey çalışır (dosya izleme, bağımlılıklar, semboller, call grafikler — yalnızca LLM tarafından oluşturulan özet yok). Agent runtime'ınızın zaten yerel bir LLM'si varsa, broker'ı bunun yerine yeniden kullanmak için yapılandırın.

Projenizin .gitignore dosyasına ekleyin:

.filescope/
.filescope-daemon.log

LLM İzleme (İsteğe Bağlı)

llama-server yerel olarak çalışıyorsa, isteğe bağlı bir VictoriaMetrics + vmui stack'i VRAM, RAM, swap, throughput ve kümülatif çalışma için tek çift dashboard sağlar. Toplam resident footprint ~120 MB, systemd cgroups aracılığıyla sınırlandırılmış, böylece başarısız bir exporter llama-server'ı OOM-kill yapamaz.

sudo ./monitoring/install.sh

http://<host>:8881/vmui/#/dashboards konumundaki dashboard'a göz atın. Layout ve uninstall script'i için monitoring/ konumuna bakın.

MCP Araçları

Araç	Ne yapar
status	Broker bağlantısı, kuyruk derinliği, LLM ilerleme, izleyici durumu
find_important_files	Önem puanı ve bağımlılık sayılarına göre en üstteki dosyalar
get_file_summary	Bir dosya hakkında her şey: özet, konseptler, değişiklik etkisi, export'lar, deps, eski
list_files	Tam dosya ağacı (arg yok) veya önem sırasına göre düz top-N (maxItems ile)
find_symbol	Bir sembol adını dosya + satır aralığına çözün; son * aracılığıyla prefix match'i destekler
find_callers	Adlandırılmış bir sembolü çağıran tüm sembolleri bulun (TS/JS call graph)
find_callees	Adlandırılmış bir sembolün çağırdığı tüm sembolleri bulun (TS/JS call graph)
search	Semboller, özetler, amaç ve yollar arasında dosya metadata'sında ara
list_changed_since	Bir timestamp veya git SHA'dan bu yana değişen dosyalar
get_communities	Louvain kümelenmiş dosya grupları (import coupling'e göre)
detect_cycles	Döngüsel bağımlılık zincirlerini bulun
get_cycles_for_file	Belirli bir dosyayı içeren döngüler
scan_all	Dosyaları broker aracılığıyla LLM özetleme için sıraya alın
set_base_directory	Farklı bir projeyi gösterin
set_file_summary	Bir dosyanın LLM özetini manuel olarak ayarlayın veya geçersiz kılın
set_file_importance	Bir dosyanın önem puanını manuel olarak ayarlayın (0-10)
exclude_and_remove	Dosyaları/şablonları izlemeden çıkar (yıkıcı)

Nexus Dashboard

npm run build:nexus  # tek seferlik build (API + UI)
npm run nexus        # http://localhost:1234 konumunda başlar

Makinenizde her FileScopeMCP repo'su ile bağlanan salt okunur web dashboard:

• Proje görünümü — önem ısı renkleri ve eski göstergeleri ile dosya ağacı, tam metadata için herhangi bir dosyaya tıklayın
• Bağımlılık grafiği — interaktif Cytoscape.js visualizasyonu, dizine göre filtreleyin, düğümleri incelemek için tıklayın
• Sistem görünümü — canlı broker durumu, depo başına token kullanımı, streaming aktivite günlüğü
• Ayarlar — hangi depoların görünüp görünmediğini yönetin, blacklist'ten kaldırın veya geri yükleyin

.filescope/data.db dizinlerini arayarak depoları otomatik olarak keşfeder. Yapılandırma gerekli değildir.

Multi-Repo İzleyicileri (systemd, yalnızca Linux)

~/.filescope/nexus.json içindeki her repo'yu — MCP istemcisi açık olmadığında bile — sürekli olarak izlemek isteyen kullanıcılar için, depo başına izleyici user unit'ini kurun:

./scripts/nexus.sh install-watchers     # unit'i yazıp, etkinleştirip, başlatır
systemctl --user status filescope-watchers.service
./scripts/nexus.sh uninstall-watchers   # simetrik kaldırma

Unit scripts/watchers.mjs'yi başlatır; kayıtlı repo başına bir dist/mcp-server.js --base-dir=<repo> child'ı başlatır ve denetler (çıkışta otomatik yeniden başla, SIGTERM temiz shutdown). Unit Requires=filescope-broker.service — broker user unit'ini kendiniz kurun; bu komut biri sevk etmez.

Loglar: ~/.filescope/watchers.log (supervisor) ve ~/.filescope/watcher-logs/*.log (depo başına children).

Nasıl Çalışır

Kodunuz değişir
    → dosya izleyici bunu yakalar
    → AST diff değişimi sınıflandırır (export'lar? tipler? sadece body?)
    → semboller çıkarılır (fonksiyonlar, sınıflar, tipler, vb.)
    → call-site kenarları çözümlenir (TS/JS: kim neyi çağırır)
    → önem puanları yeniden hesaplanır
    → eski durum bağımlılara kaskad yapılır (sadece export'lar/tipler değişmişse)
    → LLM broker özet, konsept ve değişiklik etkisini yeniden oluşturur
    → AI'nızın sonraki sorgusu güncel cevaplar alır

Her şey proje başına .filescope/data.db (SQLite, WAL modu) içinde yaşar. Broker, Unix socket aracılığıyla tüm repo'larınız arasında LLM işini ~/.filescope/broker.sock konumunda koordine eder.

Belgeler

Belge	İçerikte ne var
AGENTS.md	Cross-agent context dosyası — MCP kaydı, broker config'i, mimari (Hermes, Codex, OpenClaw tarafından okunur)
FileScopeMCP Skill	Taşınabilir skill dosyası — araç referansı, iş akışları, FileScopeMCP kullanan agentler için ipuçları
LLM Setup	llama.cpp / llama-server yüklemesi — Linux/macOS native (varsayılan), WSL2+Windows veya remote LAN
Configuration	Depo başına config, broker config'i, görmezden gelme şablonları
MCP Clients	Claude Code, Cursor AI, daemon modu kurulumu
Troubleshooting	Yaygın sorunlar ve çözümleri
Internals	Bağımlılık algılaması, önem formülü, sembol çıkarması, call-site kenarları, depolama
LLM Monitoring	Yerel llama-server için isteğe bağlı VictoriaMetrics + vmui dashboard

Lisans

Copyright (c) 2026 admica. Tüm hakları saklıdır. LICENSE dosyasına bakın.