Srclight

Indexação profunda de código para agentes de IA — 25 ferramentas MCP: busca híbrida FTS5 + embeddings, grafos de chamada, git blame/hotspots, análise de sistema de build. Workspaces multi-repositório, busca semântica acelerada por GPU, 10 linguagens. Totalmente local, zero dependências de nuvem.

GitHub
54
Experimente este MCPPatrocinado

Documentação

Srclight

PyPI License Python

Indexação profunda de código para agentes de IA. SQLite FTS5 + tree-sitter + embeddings + MCP.

O Srclight constrói um índice rico e pesquisável do seu código que agentes de codificação com IA podem consultar instantaneamente — substituindo dezenas de chamadas grep/glob por buscas precisas e estruturadas. É o servidor MCP de inteligência de código mais abrangente disponível: 42 ferramentas que cobrem busca de símbolos, grafos de relacionamento, detecção de comunidades, análise de impacto, inteligência de mudanças git, busca semântica, conhecimento do sistema de build e extração de documentos — capacidades que nenhum outro servidor MCP combina. Totalmente local e privado: seu código nunca sai da sua máquina.

Por quê?

Agentes de codificação com IA (Claude Code, Cursor, etc.) gastam 40-60% dos seus tokens em orientação — procurando arquivos, lendo código para entender a estrutura, caçando chamadores e chamados. O Srclight elimina esse desperdício.

Sem SrclightCom Srclight
8-12 rodadas de grep para encontrar chamadoresget_callers("lookup") — uma chamada
Ler 5 arquivos para entender o módulocodebase_map() — visão geral instantânea
"Encontrar código que faz X" → 20 grepssemantic_search("dictionary lookup") — uma chamada
Editar uma função, quebrar 47 chamadoresdetect_changes() — mostra o raio de impacto antes de você commitar
15-25 chamadas de ferramentas por correção de bug5-8 chamadas de ferramentas por correção de bug

Recursos

  • Dependências mínimas — um único arquivo SQLite por repositório, sem Docker/Redis/banco vetorial
  • Totalmente offline — sem chamadas de API, funciona em ambiente isolado (embeddings locais com Ollama)
  • Incremental — reindexa apenas arquivos alterados (detecção por hash de conteúdo)
  • 11 linguagens — Python, C, C++, C#, JavaScript, TypeScript, PHP, Dart, Swift, Kotlin, Java, Go
  • 10 formatos de documento — PDF, DOCX, XLSX, HTML, CSV/TSV, e-mail (.eml), imagens (PNG/JPG/SVG/etc.), texto puro, RST, Markdown
  • OCR opcional — PaddleOCR para páginas de PDF escaneadas/somente imagem; pytesseract para imagens
  • 4 modos de busca — nomes de símbolos, código-fonte (trigrama), documentação (stemming), semântica (embeddings)
  • Busca híbrida — fusão RRF de resultados de palavras-chave + semânticos para máxima precisão
  • Workspaces multi-repositório — busque em todos os seus repositórios simultaneamente via SQLite ATTACH+UNION
  • Servidor MCP — funciona com Claude Code, Cursor e qualquer cliente MCP
  • CLI — indexe, busque e inspecione pelo terminal
  • Reindexação automática — hooks git pós-commit/pós-checkout mantêm os índices atualizados

Requisitos

  • Python 3.11+
  • Git (para inteligência de mudanças e hooks de reindexação automática)
  • Ollama (opcional, para busca semântica / embeddings) — ollama.com
  • GPU NVIDIA + cupy (opcional, para busca vetorial acelerada por GPU)
  • Poppler (opcional, para suporte a PDF escaneado com PaddleOCR) — apt install poppler-utils / brew install poppler

Início Rápido

# Install from PyPI
pip install srclight

# Install from source
git clone https://github.com/srclight/srclight.git
cd srclight
pip install -e .

# Optional: document format support (PDF, DOCX, XLSX, HTML, images)
pip install 'srclight[docs,pdf]'

# Optional: OCR for scanned PDFs (also needs poppler-utils on your system)
pip install 'srclight[pdf,paddleocr]'

# Optional: OCR for images (needs tesseract on your system)
pip install 'srclight[docs,ocr]'

# Optional: GPU-accelerated vector search (requires CUDA 12.x)
pip install 'srclight[gpu]'

# Everything (docs + pdf + ocr + paddleocr + gpu)
pip install 'srclight[all]'

# Index your project
cd /path/to/your/project
srclight index

# Index with embeddings (requires Ollama running)
srclight index --embed qwen3-embedding

# Search
srclight search "lookup"
srclight search --kind function "parse"
srclight symbols src/main.py

# Start MCP server (for Claude Code / Cursor)
srclight serve

Nota: srclight index adiciona automaticamente .srclight/ ao seu .gitignore. Bancos de dados de índice e arquivos de embedding podem ser grandes e nunca devem ser commitados.

Busca Semântica (Embeddings)

O Srclight suporta busca semântica baseada em embeddings para consultas em linguagem natural como "encontre código que lida com autenticação" ou "onde está o pool de conexões do banco de dados".

Configuração

# Install Ollama (https://ollama.com)
# Pull an embedding model
ollama pull qwen3-embedding       # Best quality (8B params, needs ~6GB VRAM)
ollama pull nomic-embed-text      # Lighter alternative (137M params)

# Index with embeddings
srclight index --embed qwen3-embedding

# Or index workspace with embeddings
srclight workspace index -w myworkspace --embed qwen3-embedding

Como Funciona

  1. O nome + assinatura + docstring + conteúdo de cada símbolo é incorporado como um vetor de ponto flutuante
  2. Os vetores são armazenados como BLOBs na tabela symbol_embeddings (SQLite)
  3. Após a indexação, um snapshot sidecar .npy é construído e carregado na VRAM da GPU (cupy) ou RAM da CPU (numpy) para busca rápida
  4. semantic_search(query) incorpora a consulta e executa similaridade de cosseno contra a matriz residente na GPU (~3ms para 27K vetores em uma GPU moderna)
  5. hybrid_search(query) combina resultados de palavras-chave FTS5 + resultados de embeddings via Fusão de Rank Recíproco (RRF)

Provedores de Embedding

ProvedorModeloQualidadeLocal?Notas
Ollama (padrão)qwen3-embeddingMelhor localSimPrecisa de ~6GB de VRAM
Ollamanomic-embed-textBoaSimMais leve, funciona com 8GB de VRAM
Voyage AI (API)voyage-code-3Melhor no geralNãoRequer VOYAGE_API_KEY
# Use Voyage Code 3 (API, highest quality)
VOYAGE_API_KEY=your-key srclight index --embed voyage-code-3

Armazenamento

Os embeddings são armazenados na tabela symbol_embeddings em .srclight/index.db. Após a indexação, um snapshot sidecar .npy é construído para carregamento rápido na GPU:

ArquivoPropósito
index.dbCaminho de escrita — CRUD por símbolo durante a indexação
embeddings.npyCaminho de leitura — matriz float32 contígua para busca na GPU/CPU
embeddings_norms.npyNormas de linha pré-computadas (evita recomputação por consulta)
embeddings_meta.jsonMapeamento de ID de símbolo, informações do modelo, versão para invalidação de cache

Para ~27K símbolos com 4096 dimensões (qwen3-embedding), isso é ~428 MB em disco, ~450 MB em VRAM. Incremental: apenas reincorpora símbolos cujo conteúdo mudou; o sidecar é reconstruído após cada execução de indexação.

Workspaces Multi-Repositório

Busque em múltiplos repositórios simultaneamente. Cada repositório mantém seu próprio .srclight/index.db; no momento da consulta, o srclight os ATTACHa todos e faz UNION entre os esquemas.

# Create a workspace
srclight workspace init myworkspace

# Add repos
srclight workspace add /path/to/repo1 -w myworkspace
srclight workspace add /path/to/repo2 -w myworkspace -n custom-name

# Index all repos (with optional embeddings)
srclight workspace index -w myworkspace
srclight workspace index -w myworkspace --embed qwen3-embedding

# Search across all repos
srclight workspace search "Dictionary" -w myworkspace
srclight workspace search "Dictionary" -w myworkspace --project repo1

# Status
srclight workspace status -w myworkspace
srclight workspace list

# Start MCP server in workspace mode
srclight serve --workspace myworkspace

Submódulos Git não são indexados automaticamente — git ls-files não recursa neles. Para indexar um submódulo, clone-o separadamente e adicione-o como um projeto próprio do workspace. Veja docs/usage-guide.md para detalhes.

Integração MCP

O Srclight suporta dois modos de transporte: stdio (um servidor por sessão) e SSE (servidor persistente, múltiplas sessões). SSE é recomendado para workspaces.

Claude Code

Stdio (mais simples — um servidor por sessão):

# Single repo
claude mcp add srclight -- srclight serve

# Workspace mode
claude mcp add srclight -- srclight serve --workspace myworkspace

# Make it available in all projects (user scope)
claude mcp add --scope user srclight -- srclight serve --workspace myworkspace

SSE (servidor persistente — recomendado para workspaces):

Execute o srclight como um servidor de longa duração e aponte o Claude Code para ele:

# Start the server (default: http://127.0.0.1:8742/sse)
srclight serve --workspace myworkspace &

# Or install as a systemd user service (Linux/WSL)
# See docs/usage-guide.md for the service file

# Connect Claude Code to the running server
claude mcp add --transport sse srclight http://127.0.0.1:8742/sse

O modo SSE suporta múltiplas sessões concorrentes e sobrevive a reinicializações do Claude Code.

Cursor

SSE (recomendado): Execute o srclight uma vez e conecte o Cursor a ele. Melhor para responsividade e sem cold-start por sessão.

Inicie o servidor: srclight serve --workspace myworkspace (SSE padrão na porta 8742).

  • UI: Configurações → Tools & MCP → Adicionar novo servidor MCP → Tipo: streamableHttp, URL: http://127.0.0.1:8742/sse.
  • JSON (projeto .cursor/mcp.json ou global ~/.cursor/mcp.json):
"srclight": {
  "url": "http://127.0.0.1:8742/sse"
}

Stdio (alternativa): Um processo de servidor por sessão do Cursor.

  • UI: Tipo: command, Comando: srclight, Argumentos: serve --workspace myworkspace (ou serve para repositório único).
  • JSON:
"srclight": {
  "command": "srclight",
  "args": ["serve", "--workspace", "myworkspace"]
}

Para repositório único: "args": ["serve"]. Reinicie o Cursor completamente após adicionar o servidor.

Verificação: No chat do Cursor, pergunte "Quais projetos estão no workspace do srclight?" ou "Liste as ferramentas do srclight" — o agente deve chamar list_projects() ou mostrar as ferramentas do srclight.

OpenClaw

O OpenClaw conecta-se ao srclight via mcporter, seu CLI de ferramentas de servidor MCP integrado.

# 1. Add srclight to mcporter's home config
mcporter config add srclight http://127.0.0.1:8742/sse \
  --transport sse --scope home \
  --description "Srclight deep code indexing"

# 2. Verify the connection
mcporter call srclight.list_projects

# 3. Restart the OpenClaw gateway to pick up the new server
systemctl --user restart openclaw-gateway  # if using systemd
# or: openclaw daemon restart

O agente OpenClaw pode então usar as ferramentas do srclight via a skill mcporter:

mcporter call srclight.search_symbols query="my_function"
mcporter call srclight.get_callers symbol_name="MyClass" project="my-repo"
mcporter call srclight.hybrid_search query="authentication logic"

Pré-requisito: O Srclight deve estar rodando como servidor SSE (veja acima). O mcporter do OpenClaw conecta-se via HTTP — o modo stdio não é suportado.

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "srclight": {
      "command": "srclight",
      "args": ["serve", "--workspace", "myworkspace"]
    }
  }
}

Qualquer Cliente MCP (SSE)

Qualquer cliente compatível com MCP pode conectar-se ao endpoint SSE:

http://127.0.0.1:8742/sse

Ferramentas MCP (42)

O Srclight expõe 42 ferramentas MCP organizadas em sete níveis. O servidor MCP inclui instruções integradas que guiam agentes de IA sobre qual ferramenta usar e quando — os agentes recebem um protocolo de sessão, guia de seleção de ferramentas e documentação de parâmetros project automaticamente na conexão.

Nível 1: Orientação Instantânea

FerramentaO que faz
codebase_map()Visão geral completa do projeto — chame primeiro em toda sessão
search_symbols(query)Busca em nomes de símbolos, código e documentação
get_symbol(name)Código-fonte completo + metadados de um símbolo
get_signature(name)Apenas a assinatura (leve)
symbols_in_file(path)Sumário de um arquivo
list_projects()Todos os projetos no workspace com estatísticas

Nível 2: Grafo de Relacionamento

FerramentaO que faz
get_callers(name)Quem chama este símbolo?
get_callees(name)O que este símbolo chama?
get_dependents(name, transitive)Raio de impacto — o que quebra se eu mudar isto?
get_implementors(interface)Todas as classes que implementam uma interface
get_tests_for(name)Funções de teste que cobrem um símbolo
get_type_hierarchy(name)Árvore de herança (classes base + subclasses)

Nível 2b: Análise de Comunidade e Impacto

FerramentaO que faz
get_communities(project)Clusters de módulos funcionais auto-detectados (algoritmo de Louvain)
get_community(name, project)A qual comunidade um símbolo pertence, com todos os co-membros
get_execution_flows(project)Caminhos de execução rastreados de pontos de entrada através do grafo de chamadas
get_impact(name, project)Raio de impacto + nível de risco (BAIXO / MÉDIO / ALTO / CRÍTICO)
detect_changes(project, ref?)Mapeia git diff para símbolos afetados — raio de impacto agregado das suas edições

Nível 3: Inteligência de Mudanças Git

FerramentaO que faz
blame_symbol(name)Quem mudou isto, quando e por quê
recent_changes(n)Feed de commits (entre projetos no workspace)
git_hotspots(n, since)Arquivos mais frequentemente alterados (ímãs de bugs)
whats_changed()Trabalho não commitado em andamento
changes_to(name)Histórico de commits do arquivo de um símbolo

Nível 4: Build e Configuração

FerramentaO que faz
get_build_targets()Alvos CMake/.csproj/npm com dependências
get_platform_variants(name)Guards de plataforma #ifdef ao redor de um símbolo
platform_conditionals()Todos os blocos de código condicionais por plataforma

Nível 5: Busca Semântica (Embeddings)

FerramentaO que faz
semantic_search(query)Encontre código por significado (linguagem natural)
hybrid_search(query)O melhor dos dois: palavras-chave + semântico com fusão RRF
embedding_status()Cobertura de embeddings e informações do modelo

Nível 6: Meta e Servidor

FerramentaO que faz
index_status()Atualidade do índice e estatísticas
reindex()Aciona reindexação incremental
embedding_health()Verifica se o provedor de embeddings (Ollama, etc.) está acessível
setup_guide()Instruções de configuração estruturadas para agentes e usuários
server_stats()Tempo de atividade do servidor e informações do processo
restart_server()Solicita reinicialização do servidor (apenas SSE)

No modo workspace, search_symbols, get_symbol, codebase_map e hybrid_search aceitam um filtro opcional project. Ferramentas de grafo/git/build/comunidade exigem project no modo workspace.

Guia de Implantação

Veja docs/usage-guide.md para o guia completo de implantação e uso, incluindo:

  • Configurando o srclight como servidor MCP global para Claude Code
  • Adicionando/removendo repositórios de workspaces
  • O que acontece em commits e trocas de branch
  • Fluxos de re-embedding
  • Solução de problemas

Reindexação Automática (Hook Git)

Mantenha os índices atualizados automaticamente:

# Install post-commit + post-checkout hooks in current repo
srclight hook install

# Install across all repos in a workspace
srclight hook install --workspace myworkspace

# Remove hooks
srclight hook uninstall

Os hooks executam srclight index em segundo plano após cada commit e troca de branch.

Como Funciona

  1. tree-sitter analisa cada arquivo de código-fonte em uma AST
  2. Extratores de documentos lidam com arquivos não-código (PDF, DOCX, XLSX, HTML, CSV, imagens, e-mail, texto) — extraindo títulos, tabelas, páginas e metadados como símbolos pesquisáveis. Páginas de PDF escaneadas são opcionalmente submetidas a OCR via PaddleOCR.
  3. Símbolos (funções, classes, métodos, structs, etc.) são extraídos com metadados completos
  4. Três índices SQLite FTS5 são construídos com diferentes estratégias de tokenização:
    • Nomes: tokenização ciente de código (divide camelCase, lida com ::, ->)
    • Conteúdo: índice trigrama para correspondência de substrings
    • Docs: Stemming de Porter para linguagem natural em docstrings
  5. Detecção de comunidades agrupa símbolos em módulos funcionais via algoritmo de Louvain nas arestas do grafo de chamadas, com rotulagem automática TF-IDF
  6. Fluxos de execução são rastreados via BFS a partir de pontos de entrada, e a análise de impacto pontua o raio de explosão de cada símbolo (BAIXO/MÉDIO/ALTO/CRÍTICO)
  7. Opcional: vetores de incorporação são gerados via API Ollama ou Voyage e armazenados como BLOBs
  8. Um .npy snapshot sidecar é construído e carregado na VRAM da GPU (cupy) ou RAM da CPU (numpy) para busca rápida
  9. O servidor MCP expõe ferramentas de consulta estruturada que agentes de IA chamam em vez de grep
  10. Busca híbrida mescla resultados de palavras-chave (FTS5) e semânticos (incorporação) via RRF

Arquitetura (Modo Workspace)

repo1/.srclight/index.db  ──┐
repo2/.srclight/index.db  ──┼── ATTACH ──→ :memory: ──→ UNION ALL queries
repo3/.srclight/index.db  ──┘

Cada repositório é indexado de forma independente. No momento da consulta, o mecanismo ATTACH do SQLite os une em um único namespace pesquisável. Lida com mais de 10 repositórios via agrupamento automático (limite de ATTACH do SQLite).

Como o Srclight se Compara

Uma pesquisa com mais de 50 servidores de inteligência de código MCP em todos os principais registros (Official MCP Registry, Smithery, Glama, mcp.so, awesome-mcp-servers) descobriu que nenhum outro servidor único combina todos os recursos do srclight:

Capacidadesrclightgrep/glob (padrão)CodeMCP (SCIP)Claude Context (Zilliz)
Busca de símbolos (FTS5)3 índices (nome, conteúdo, docs)NenhumBaseado em SCIPBM25
Busca semântica (incorporações)Acelerada por GPU, ~3msNenhumNenhumAPI OpenAI + Milvus
Busca híbrida (palavras-chave + semântica)Fusão RRFNenhumNenhumBM25 + vetor
Grafo de relacionamentos (chamadores, chamados)Arestas tree-sitterNenhumArestas SCIPNenhum
Detecção de comunidades (agrupamentos de módulos)Louvain no grafo de chamadasNenhumNenhumNenhum
Análise de impacto (raio de explosão + risco)Por símbolo + nível de diffNenhumNenhumNenhum
Inteligência de mudanças Gitblame, hotspots, WIP, detect_changesNenhumNenhumNenhum
Consciência do sistema de buildCMake, .csproj, #ifdefNenhumNenhumNenhum
Workspace multi-repositórioATTACH+UNIONNenhumNenhumNenhum
Infraestrutura necessáriapip install, SQLiteNenhumIndexador SCIPDocker, Milvus, API OpenAI
Totalmente local / privadoSim, zero chamadas de APISimSimNão (precisa de OpenAI)
Linguagens11Qualquer (regex)5 (SCIP)Qualquer (chunking)
Ferramentas MCP422 (grep, glob)80+~10

Ao contrário de ferramentas baseadas em grep, o srclight constrói um índice persistente com consultas estruturadas. Ao contrário de soluções baseadas em nuvem, tudo roda localmente — seu código nunca sai da sua máquina. Ao contrário de plugins de IDE, o srclight funciona com qualquer cliente MCP.

Roadmap

Concluído

  • Inteligência de símbolos + 3x busca FTS5
  • Grafo de relacionamentos: chamadores, chamados, hierarquia
  • Raio de explosão, descoberta de testes, implementadores
  • Inteligência de mudanças Git: blame, hotspots, mudanças recentes
  • Consciência do sistema de build: CMake, .csproj, condicionais de plataforma
  • Busca semântica: incorporações via Ollama/Voyage, RRF híbrido
  • Busca vetorial acelerada por GPU: .npy sidecar, matemática vetorizada cupy/numpy
  • Workspaces multi-repositório (ATTACH+UNION)
  • Hooks Git de reindexação automática (post-commit + post-checkout)
  • Extração de documentos: PDF, DOCX, XLSX, HTML, CSV, e-mail, imagens, texto (detecção de títulos, tabelas, metadados)
  • OCR opcional: PaddleOCR para PDFs escaneados, pytesseract para imagens
  • Orientação do agente MCP: instruções abrangentes, guia de seleção de ferramentas, protocolo de sessão
  • Recarga a quente da configuração do workspace (sem reiniciar o servidor para adicionar repositórios)
  • Redescoberta do sidecar VectorCache (sem reiniciar após incorporação)
  • Sugestões de nome de projeto em mensagens de erro
  • Detecção de comunidades: agrupamento Louvain nas arestas do grafo de chamadas com rotulagem automática TF-IDF
  • Rastreamento de fluxo de execução: BFS a partir de pontos de entrada através de fronteiras de comunidades
  • Análise de impacto: raio de explosão por símbolo com pontuação de risco (BAIXO/MÉDIO/ALTO/CRÍTICO)
  • detect_changes: mapear git diff para símbolos afetados e agregar raio de explosão

Próximos

  • Mapeamento de conceitos entre linguagens (arestas explícitas entre símbolos equivalentes entre linguagens)
  • Inteligência de padrões (detecção de convenções, extração de padrões de código)
  • Pré-computação de IA (resumos de símbolos via LLM barato)

Licença

MIT — Gig8 LLC