Scalable CTags

Servidor MCP para permitir navegação de código usando um arquivo de tags. Tem como objetivo lidar com arquivos de tags grandes com sobrecarga mínima.

load_tags_file called o.watcher.Add(path) with the user-supplied path,
which can be relative. fsnotify reports events for that file under a
different key (the path the kernel gives back), so a relative-path load
could silently drop watcher events.
Use the absolute path returned by ParseTagsFile (pf.Path), which the
index and discovery layer already canonicalise to. Add tests covering
both plain and non-canonical (./tags) relative inputs.
AI-Assisted: written with opencode and MiniMax-M3

Servidor MCP Scalable CTags

Um servidor de busca de símbolos ctags com mapeamento de memória que expõe uma interface MCP (Model Context Protocol) para agentes de IDE e ferramentas de LLM. Projetado para lidar com múltiplos e grandes arquivos de tags em vários subprojetos.

Recursos

• Suporte a múltiplos arquivos: Carregue e pesquise em vários arquivos de tags simultaneamente
• Atualização automática: Observa arquivos carregados e atualiza automaticamente
• Campos estendidos: Extrai kind, language e filePath do formato estendido v2 do ctags

Compilação

Requer Go 1.26+ e um ambiente Nix (ou toolchain Go padrão).

# With Nix (recommended)
nix develop --command go build -o ctags-mcp ./cmd/ctags-mcp

# Without Nix
go build -o ctags-mcp ./cmd/ctags-mcp

Arquivo de tags

Gere um arquivo de tags para o seu projeto antes de executar o servidor:

ctags -n -R .

A flag -n (--excmd=number) é obrigatória — ela instrui o ctags a armazenar números de linha em vez de padrões regex como comandos de busca. Sem ela, o servidor retorna line: 0 para todas as buscas de símbolos.

Execução

O servidor se comunica via stdio (JSON-RPC).

./ctags-mcp

Na inicialização, o servidor descobre automaticamente arquivos tags e tags.in do diretório de trabalho atual (até 8 níveis de profundidade) e os analisa em um pool de goroutines em segundo plano — o handshake do MCP responde imediatamente, não importa o tamanho dos arquivos de tags. As ferramentas de busca (lookup_symbol, get_symbol_info) bloqueiam até que o carregamento inicial seja concluído; list_tags_files responde imediatamente e relata status por arquivo (loading / ready) além de uma flag loadingComplete de nível superior. Diretórios ocultos (prefixados com ponto) são sempre ignorados. Use --auto-discover=false para desabilitar a descoberta automática completamente.

Por padrão, diretórios adicionais que correspondem à flag --skip-dirs (nomes de diretórios separados por vírgula) são excluídos (por exemplo, vendor, node_modules).

Configure a descoberta:

Uso no opencode

Adicione o servidor ao seu opencode.json sob a chave mcp:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "ctags": {
      "type": "local",
      "command": ["./ctags-mcp"],
      "enabled": true
    }
  }
}

Após editar opencode.json, saia e reinicie o opencode para que as alterações tenham efeito.

Ferramentas disponíveis

A resposta de load_tags_file inclui um campo preloaded definido como true quando o arquivo foi descoberto automaticamente na inicialização.

Recursos disponíveis

Exemplo de uso

Depois que o servidor estiver configurado no opencode, você pode fazer perguntas em linguagem natural e o agente usará as ferramentas:

"Find all references to AddTagsFile in the codebase"
"Show me detailed info about the EntryRef struct"
"What tags files are currently loaded?"
"Look up the Lookup function, filtering by fileID 0"

O agente chamará list_tags_files para verificar o que já está carregado e, em seguida, usará lookup_symbol ou get_symbol_info para responder. Para projetos sem um arquivo de tags no disco, ele chamará load_tags_file primeiro.

Arquitetura

internal/
  parser/       Streaming line-by-line ctags parser
  indexer/      In-memory index (map[string][]Entry); lock-free single-pass
                parsing (ParseTagsFile) with deferred merge (InstallParsed)
  server/       MCP protocol layer (Server) + index lifecycle
                (IndexOrchestrator: discovery, background load, watch/rebuild)
  cmd/ctags-mcp/  Entry point (stdio transport)