FileScopeMCP

FileScopeMCP

Sua IA já sabe programar. Agora ela conhece seu código.

O FileScopeMCP monitora seu código, classifica cada arquivo por importância, mapeia todas as dependências e mantém resumos gerados por IA atualizados em segundo plano. Quando seu LLM pergunta "o que este arquivo faz?" — ele obtém uma resposta real sem ler o código-fonte.

Funciona com Claude Code, Hermes Agent, Codex, OpenClaw, Cursor AI ou como um daemon independente. Suporta TypeScript, JavaScript, Python, C, C++, Rust, Go, Ruby, Lua, Zig, PHP, C# e Java.

Principais Recursos

Classificação por importância — cada arquivo recebe uma pontuação de 0 a 10 com base em quantas coisas dependem dele, o que ele exporta e onde está localizado. Seu LLM vê os arquivos críticos primeiro.

Mapeamento de dependências — rastreamento bidirecional de imports em todas as linguagens suportadas. Extração em nível de AST (tree-sitter) para TS/JS, Python, C, C++ e Rust; baseada em regex para Go, Ruby, Lua, Zig, PHP, C# e Java. Também detecta dependências circulares.

Inteligência de símbolos — extrai funções, classes, interfaces, tipos, enums, consts, módulos e structs via tree-sitter para TypeScript, JavaScript, Python, Go e Ruby. find_symbol resolve nomes para arquivo + intervalo de linhas. find_callers e find_callees mapeiam o grafo de chamadas para TS/JS, permitindo que sua IA responda "quem chama esta função?" antes de refatorar.

Sempre atualizado — o observador de arquivos + detecção semântica de mudanças garante atualização automática dos metadados. Diff em nível de AST para TS/JS, análise assistida por LLM para todo o resto. Apenas o que realmente mudou é reprocessado.

Broker de LLM — um processo em segundo plano coordena todo o trabalho de IA através do llama-server do llama.cpp (ou qualquer API HTTP compatível com OpenAI). A fila de prioridade garante que consultas interativas superem o processamento em segundo plano. Executa em uma única GPU.

Painel Nexus — uma interface web em localhost:1234 que permite explorar visualmente seu código em todos os seus repositórios. Grafos de dependência interativos, painéis de detalhes de arquivos, atividade do broker em tempo real e monitoramento de saúde por repositório.

Pré-requisitos

• Node.js >= 22 e npm (download)
• Ferramentas de build para módulos nativos (better-sqlite3, tree-sitter):
  • Linux: sudo apt install build-essential python3
  • macOS: xcode-select --install
  • Windows: Visual Studio Build Tools com carga de trabalho C++

Início Rápido

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

./build.sh registra o FileScopeMCP globalmente via claude mcp add --scope user (idempotente; execute novamente com npm run register-mcp). Se o CLI claude estiver ausente, o build ainda é concluído — consulte docs/mcp-clients.md para outros clientes MCP.

Abra uma sessão do Claude Code em qualquer projeto e o FileScopeMCP inicializa automaticamente. As ferramentas MCP aparecem automaticamente — sua IA pode chamá-las diretamente durante a conversa:

find_important_files(limit: 5)
status()

Instalação opinativa do Claude Code (recomendada)

Para uma instalação mais completa que adiciona um primer de projeto CLAUDE.md e aponta para modelos de hooks opcionais:

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

O comando é em camadas, não invasivo — ele nunca grava automaticamente no seu .claude/settings.json. Os modelos de hooks estão documentados em docs/claude-code-hooks.md; cole-os nas suas configurações se e quando quiser. O primer CLAUDE.md é envolvido em marcadores <!-- BEGIN filescope --> / <!-- END filescope --> para que possa ser adicionado, substituído ou removido de forma limpa, sem tocar no conteúdo ao redor. Consulte ROADMAP.md Fase 1 para a justificativa do design.

Runtimes de Agentes (Hermes, Codex, OpenClaw)

Os runtimes de agentes descobrem o FileScopeMCP via AGENTS.md do repositório, que inclui configuração de registro MCP, configuração do broker/LLM e um ponteiro para o arquivo de skill portátil em skills/filescope-mcp/SKILL.md.

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

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

Já tem um LLM local em execução? Aponte o broker para ele — edite ~/.filescope/broker.json e defina baseURL para o endpoint do seu LLM. Consulte AGENTS.md para detalhes.

Resumos de LLM (Opcional)

Execute ./setup-llm.sh para um guia específico da plataforma sobre como configurar o llama-server do llama.cpp — consulte docs/llm-setup.md para detalhes. No Linux, você também pode sudo ./setup-llm.sh --install-service para registrar o llama-server como uma unit do systemd (logs fluem para o journalctl, protegido contra OOM, reinício automático na inicialização). A flag é um no-op sob WSL2, pois o llama-server roda no host Windows nesse caso. Sem o llama-server, todo o resto continua funcionando (rastreamento de arquivos, dependências, símbolos, grafos de chamadas — apenas sem resumos gerados por LLM). Se o runtime do seu agente já tem um LLM local, configure o broker para reutilizá-lo.

Adicione ao .gitignore do seu projeto:

.filescope/
.filescope-daemon.log

Monitoramento de LLM (Opcional)

Se o llama-server estiver rodando localmente, uma stack opcional de VictoriaMetrics + vmui oferece um painel unificado para VRAM, RAM, swap, throughput e trabalho acumulado. Pegada residente total de ~120 MB, limitada via cgroups do systemd para que um exporter com mau comportamento não possa matar o llama-server por OOM.

sudo ./monitoring/install.sh

Navegue pelo painel em http://<host>:8881/vmui/#/dashboards. Consulte monitoring/ para a estrutura e o script de desinstalação.

Ferramentas MCP

Ferramenta	O que faz
status	Conexão do broker, profundidade da fila, progresso do LLM, estado do observador
find_important_files	Principais arquivos por pontuação de importância com contagens de dependências
get_file_summary	Tudo sobre um arquivo: resumo, conceitos, impacto de mudanças, exports, dependências, desatualização
list_files	Árvore de arquivos completa (sem argumentos) ou top-N plano por importância (com maxItems)
find_symbol	Resolve um nome de símbolo para arquivo + intervalo de linhas; suporta correspondência por prefixo via * final
find_callers	Encontra todos os símbolos que chamam um símbolo nomeado (grafo de chamadas TS/JS)
find_callees	Encontra todos os símbolos que um símbolo nomeado chama (grafo de chamadas TS/JS)
search	Pesquisa metadados de arquivos em símbolos, resumos, propósito e caminhos
list_changed_since	Arquivos alterados desde um timestamp ou SHA do git
get_communities	Grupos de arquivos agrupados por Louvain com base no acoplamento de imports
detect_cycles	Encontra cadeias de dependências circulares
get_cycles_for_file	Ciclos envolvendo um arquivo específico
scan_all	Coloca arquivos na fila para sumarização por LLM via broker
set_base_directory	Aponta para um projeto diferente
set_file_summary	Define ou substitui manualmente o resumo LLM de um arquivo
set_file_importance	Define manualmente a pontuação de importância de um arquivo (0-10)
exclude_and_remove	Remove arquivos/padrões do rastreamento (destrutivo)

Painel Nexus

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

Um painel web somente leitura que se conecta a todos os repositórios FileScopeMCP na sua máquina:

• Visão do projeto — árvore de arquivos com cores de calor por importância e indicadores de desatualização; clique em qualquer arquivo para metadados completos
• Grafo de dependências — visualização interativa com Cytoscape.js, filtre por diretório, clique em nós para inspecionar
• Visão do sistema — status do broker em tempo real, uso de tokens por repositório, log de atividade em streaming
• Configurações — gerencie quais repositórios aparecem, remova ou restaure da lista negra

Descobre repositórios automaticamente ao escanear por diretórios .filescope/data.db. Nenhuma configuração necessária.

Observadores Multi-Repositório (systemd, somente Linux)

Para usuários que desejam que todos os repositórios em ~/.filescope/nexus.json sejam monitorados continuamente — não apenas quando um cliente MCP está aberto — instale a unit de usuário dos observadores por repositório:

./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

A unit inicia scripts/watchers.mjs, que gera um filho dist/mcp-server.js --base-dir=<repo> por repositório registrado e os supervisiona (reinício automático em caso de saída, encerramento limpo via SIGTERM). A unit Requires=filescope-broker.service — instale a unit do broker você mesmo; este comando não inclui uma.

Logs: ~/.filescope/watchers.log (supervisor) e ~/.filescope/watcher-logs/*.log (filhos por repositório).

Como 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

Tudo fica em .filescope/data.db (SQLite, modo WAL) por projeto. O broker coordena o trabalho de LLM em todos os seus repositórios via um socket Unix em ~/.filescope/broker.sock.

Documentação

Documento	O que contém
AGENTS.md	Arquivo de contexto entre agentes — registro MCP, configuração do broker, arquitetura (lido por Hermes, Codex, OpenClaw)
Skill FileScopeMCP	Arquivo de skill portátil — referência de ferramentas, fluxos de trabalho, dicas para agentes que usam FileScopeMCP
Configuração de LLM	Instalação do llama.cpp / llama-server — Linux/macOS nativo (padrão), WSL2+Windows ou LAN remota
Configuração	Configuração por projeto, configuração do broker, padrões de ignorar
Clientes MCP	Configuração para Claude Code, Cursor AI, modo daemon
Solução de Problemas	Problemas comuns e correções
Internos	Detecção de dependências, fórmula de importância, extração de símbolos, arestas de call-site, armazenamento
Monitoramento de LLM	Painel opcional de VictoriaMetrics + vmui para o llama-server local

Licença

Copyright (c) 2026 admica. Todos os direitos reservados. Consulte LICENSE.