FileScopeMCP

FileScopeMCP

Tu IA ya sabe programar. Ahora conoce tu base de código.

FileScopeMCP observa tu código, clasifica cada archivo por importancia, mapea todas las dependencias y mantiene resúmenes generados por IA actualizados en segundo plano. Cuando tu LLM pregunta "¿qué hace este archivo?" — obtiene una respuesta real sin leer el código fuente.

Funciona con Claude Code, Hermes Agent, Codex, OpenClaw, Cursor AI, o como demonio independiente. Soporta TypeScript, JavaScript, Python, C, C++, Rust, Go, Ruby, Lua, Zig, PHP, C# y Java.

Características Clave

Clasificación por importancia — cada archivo recibe una puntuación de 0-10 según cuántas cosas dependen de él, qué exporta y dónde se encuentra. Tu LLM ve primero los archivos críticos.

Mapeo de dependencias — seguimiento bidireccional de importaciones en todos los lenguajes soportados. Extracción a nivel de AST (tree-sitter) para TS/JS, Python, C, C++ y Rust; basada en regex para Go, Ruby, Lua, Zig, PHP, C# y Java. También detecta dependencias circulares.

Inteligencia de símbolos — extrae funciones, clases, interfaces, tipos, enums, constantes, módulos y estructuras mediante tree-sitter para TypeScript, JavaScript, Python, Go y Ruby. find_symbol resuelve nombres a archivo + rango de líneas. find_callers y find_callees mapean el grafo de llamadas para TS/JS para que tu IA pueda responder "¿quién llama a esta función?" antes de refactorizar.

Siempre actualizado — el observador de archivos + la detección de cambios semánticos garantizan que los metadatos se actualicen automáticamente. Diffing a nivel de AST para TS/JS, análisis impulsado por LLM para todo lo demás. Solo reprocesa lo que realmente cambió.

Broker LLM — un proceso en segundo plano coordina todo el trabajo de IA a través de llama.cpp's llama-server (o cualquier API HTTP compatible con OpenAI). La cola de prioridad garantiza que las consultas interactivas superen al procesamiento en segundo plano. Se ejecuta en una sola GPU.

Panel Nexus — una interfaz web en localhost:1234 que te permite explorar visualmente tu base de código en todos tus repositorios. Grafos de dependencias interactivos, paneles de detalles de archivos, actividad del broker en vivo y monitoreo de salud por repositorio.

Requisitos Previos

• Node.js >= 22 y npm (descargar)
• Herramientas de compilación para módulos nativos (better-sqlite3, tree-sitter):
  • Linux: sudo apt install build-essential python3
  • macOS: xcode-select --install
  • Windows: Visual Studio Build Tools con carga de trabajo C++

Inicio Rápido

git clone https://github.com/admica/FileScopeMCP.git
cd FileScopeMCP
./build.sh          # installs deps, compiles, registers with Claude Code

./build.sh registra FileScopeMCP globalmente mediante claude mcp add --scope user (idempotente; vuelve a ejecutarlo con npm run register-mcp). Si la CLI de claude falta, la compilación aún se completa — consulta docs/mcp-clients.md para otros clientes MCP.

Abre una sesión de Claude Code en cualquier proyecto y FileScopeMCP se inicializa automáticamente. Las herramientas MCP aparecen automáticamente — tu IA puede llamarlas directamente durante la conversación:

find_important_files(limit: 5)
status()

Instalación opinada de Claude Code (recomendada)

Para una instalación más completa que agrega un CLAUDE.md de preparación del proyecto y apunta a plantillas de hooks opcionales:

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

El comando es en capas, no invasivo — nunca escribe automáticamente en tu .claude/settings.json. Las plantillas de hooks están documentadas en docs/claude-code-hooks.md; pégalas en tu configuración si y cuando las quieras. El primer de CLAUDE.md está envuelto en marcadores <!-- BEGIN filescope --> / <!-- END filescope --> para que pueda agregarse, reemplazarse o eliminarse limpiamente sin tocar el contenido circundante. Consulta ROADMAP.md Fase 1 para la justificación del diseño.

Entornos de Ejecución de Agentes (Hermes, Codex, OpenClaw)

Los entornos de ejecución de agentes descubren FileScopeMCP a través del AGENTS.md del repositorio, que incluye configuración de registro MCP, configuración del broker/LLM y un puntero al archivo de habilidad portátil en skills/filescope-mcp/SKILL.md.

Hermes — agrega a ~/.hermes/config.yaml:

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

¿Ya tienes un LLM local en ejecución? Apunta el broker hacia él — edita ~/.filescope/broker.json y establece baseURL al endpoint de tu LLM. Consulta AGENTS.md para más detalles.

Resúmenes LLM (Opcional)

Ejecuta ./setup-llm.sh para obtener una guía específica de plataforma sobre cómo configurar llama-server de llama.cpp — consulta docs/llm-setup.md para más detalles. En Linux también puedes sudo ./setup-llm.sh --install-service para registrar llama-server como una unidad systemd (los registros fluyen a journalctl, protegido contra OOM, reinicio automático al arrancar). La bandera es un no-op bajo WSL2 ya que llama-server se ejecuta en el host de Windows allí. Sin llama-server por completo, todo lo demás sigue funcionando (seguimiento de archivos, dependencias, símbolos, grafos de llamadas — solo sin resúmenes generados por LLM). Si tu entorno de ejecución de agente ya tiene un LLM local, configura el broker para reutilizarlo en su lugar.

Agrega al .gitignore de tu proyecto:

.filescope/
.filescope-daemon.log

Monitoreo LLM (Opcional)

Si llama-server se está ejecutando localmente, una pila opcional de VictoriaMetrics + vmui te brinda un panel unificado para VRAM, RAM, swap, rendimiento y trabajo acumulado. Huella residente total de ~120 MB, limitada mediante cgroups de systemd para que un exportador con mal comportamiento no pueda matar llama-server por OOM.

sudo ./monitoring/install.sh

Explora el panel en http://<host>:8881/vmui/#/dashboards. Consulta monitoring/ para la estructura y el script de desinstalación.

Herramientas MCP

Herramienta	Qué hace
status	Conexión del broker, profundidad de cola, progreso del LLM, estado del observador
find_important_files	Archivos principales por puntuación de importancia con conteos de dependencias
get_file_summary	Todo sobre un archivo: resumen, conceptos, impacto de cambios, exportaciones, dependencias, desactualización
list_files	Árbol de archivos completo (sin argumentos) o top-N plano por importancia (con maxItems)
find_symbol	Resuelve un nombre de símbolo a archivo + rango de líneas; soporta coincidencia de prefijo mediante * final
find_callers	Encuentra todos los símbolos que llaman a un símbolo nombrado (grafo de llamadas TS/JS)
find_callees	Encuentra todos los símbolos que un símbolo nombrado llama (grafo de llamadas TS/JS)
search	Busca metadatos de archivos entre símbolos, resúmenes, propósito y rutas
list_changed_since	Archivos modificados desde una marca de tiempo o SHA de git
get_communities	Grupos de archivos agrupados por Louvain según acoplamiento de importaciones
detect_cycles	Encuentra cadenas de dependencias circulares
get_cycles_for_file	Ciclos que involucran un archivo específico
scan_all	Pone archivos en cola para resumen LLM mediante el broker
set_base_directory	Apunta a un proyecto diferente
set_file_summary	Establece o anula manualmente el resumen LLM de un archivo
set_file_importance	Establece manualmente la puntuación de importancia de un archivo (0-10)
exclude_and_remove	Elimina archivos/patrones del seguimiento (destructivo)

Panel Nexus

npm run build:nexus  # one-time build (API + UI)
npm run nexus        # starts at http://localhost:1234

Un panel web de solo lectura que se conecta a cada repositorio de FileScopeMCP en tu máquina:

• Vista de proyecto — árbol de archivos con colores de calor por importancia e indicadores de desactualización, haz clic en cualquier archivo para ver metadatos completos
• Grafo de dependencias — visualización interactiva de Cytoscape.js, filtra por directorio, haz clic en nodos para inspeccionar
• Vista del sistema — estado del broker en vivo, uso de tokens por repositorio, registro de actividad en streaming
• Configuración — gestiona qué repositorios aparecen, elimina o restaura desde lista negra

Descubre automáticamente repositorios escaneando directorios .filescope/data.db. No se necesita configuración.

Observadores Multi-Repositorio (systemd, solo Linux)

Para usuarios que quieren que cada repositorio en ~/.filescope/nexus.json se observe continuamente — no solo cuando un cliente MCP está abierto — instala la unidad de usuario de observadores por repositorio:

./scripts/nexus.sh install-watchers     # writes the unit, enables it, starts it
systemctl --user status filescope-watchers.service
./scripts/nexus.sh uninstall-watchers   # symmetric removal

La unidad lanza scripts/watchers.mjs, que genera un hijo dist/mcp-server.js --base-dir=<repo> por repositorio registrado y los supervisa (reinicio automático al salir, apagado limpio con SIGTERM). La unidad Requires=filescope-broker.service — instala la unidad de usuario del broker tú mismo; este comando no incluye una.

Registros: ~/.filescope/watchers.log (supervisor) y ~/.filescope/watcher-logs/*.log (hijos por repositorio).

Cómo Funciona

Your code changes
    → file watcher picks it up
    → AST diff classifies the change (exports? types? body only?)
    → symbols extracted (functions, classes, types, etc.)
    → call-site edges resolved (TS/JS: who calls what)
    → importance scores recalculated
    → staleness cascades to dependents (only if exports/types changed)
    → LLM broker regenerates summaries, concepts, change impact
    → your AI's next query gets fresh answers

Todo vive en .filescope/data.db (SQLite, modo WAL) por proyecto. El broker coordina el trabajo del LLM en todos tus repositorios mediante un socket Unix en ~/.filescope/broker.sock.

Documentación

Documento	Qué contiene
AGENTS.md	Archivo de contexto entre agentes — registro MCP, configuración del broker, arquitectura (leído por Hermes, Codex, OpenClaw)
Habilidad FileScopeMCP	Archivo de habilidad portátil — referencia de herramientas, flujos de trabajo, consejos para agentes que usan FileScopeMCP
Configuración LLM	Instalación de llama.cpp / llama-server — Linux/macOS nativo (predeterminado), WSL2+Windows, o LAN remota
Configuración	Configuración por proyecto, configuración del broker, patrones de ignorar
Clientes MCP	Configuración para Claude Code, Cursor AI, modo demonio
Solución de Problemas	Problemas comunes y soluciones
Internos	Detección de dependencias, fórmula de importancia, extracción de símbolos, bordes de sitios de llamada, almacenamiento
Monitoreo LLM	Panel opcional de VictoriaMetrics + vmui para el llama-server local

Licencia

Copyright (c) 2026 admica. Todos los derechos reservados. Consulta LICENSE.