CodeSteer Atlas

O Model Context Protocol (MCP) é um protocolo aberto de comunicação bidirecional criado para padronizar a forma como Modelos de Linguagem (LLMs), rodando em clientes como editores de código (Cursor, VS Code, Claude Desktop, Cline), interagem de forma segura com fontes de dados e ferramentas locais ou remotas.

Em vez de cada LLM ou IDE escrever integrações proprietárias para ler arquivos, pesquisar em bancos de dados ou executar comandos, eles atuam como Clientes MCP genéricos que se conectam a um ou mais Servidores MCP por canais estruturados.

Para responder a buscas semânticas instantâneas sem gastar tokens, o CodeSteer Atlas constrói um índice vetorial e textual local chamado .code-index. O processo de indexação segue 6 etapas factuais e lineares executadas pelo indexer.py:

Onde fica o .code-index?

O servidor MCP precisa localizar a pasta .code-index do projeto antes de buscar ou indexar. A resolução segue uma cadeia de prioridade fixa (DECISAO-002). O campo index_resolution retornado por atlas_status indica qual mecanismo foi usado — útil para diagnosticar plugins globais iniciados com CWD diferente da raiz do projeto (ex.: HOME).

1. --index-dir — argumento de linha de comando do servidor (index_resolution: "cli-arg").
2. ATLAS_INDEX_DIR — variável de ambiente explícita ("env").
3. Discovery ascendente a partir do CWD — sobe diretórios procurando uma pasta .code-index existente, estilo .git ("discovery").
4. Raiz informada pelo editor — CLAUDE_PROJECT_DIR (Claude Code) ou WORKSPACE_FOLDER_PATHS (Cursor/VS Code), quando o CWD do plugin não é a raiz do projeto ("editor-project-dir" ou "editor-project-dir-fallback").
5. MCP roots (upgrade na 1ª tool call) — se a resolução de startup caiu em fallback, a primeira chamada a uma tool consulta roots/list do cliente MCP, localiza ou aponta o índice para a raiz real do workspace ("roots" ou "roots-fallback"). Cobre plugins globais (Copilot, Cursor, Kiro) sem configuração por projeto.
6. Fallback final — .code-index relativo ao CWD ou à raiz do editor ("cwd-fallback").

Reindex automático em background

Ao iniciar o servidor MCP (atlas-serve), se já existir um índice local, o Atlas dispara uma reindexação incremental em subprocesso — sem bloquear o canal stdio JSON-RPC. Operações pesadas (LanceDB, Tantivy FTS, ONNX) rodam fora do processo do servidor para não congelar chamadas MCP.

• Lock de reindex: apenas um processo reindexa por vez; atlas_status expõe reindexing: true enquanto o lock estiver ativo.
• Log: saída em .code-index/background_reindex.log, com cabeçalhos timestamped por execução.
• atlas_index assíncrono: indexação do workspace inteiro ou com full=true também roda em background e retorna imediatamente com status, pid e log_path. Indexação de subpastas específicas (paths não vazio, full=false) permanece síncrona.

Diferente de sistemas ingênuos de busca que quebram o código baseados em números de linhas fixas (o que pode cortar uma função ao meio e quebrar sua coerência lógica), o CodeSteer Atlas utiliza um analisador sintático completo: o Tree-sitter.

O analisador lê o código-fonte de linguagens como Python, JavaScript, TypeScript, Go, Java, C#, C++, Rust, Kotlin, etc., e monta uma Árvore Sintática Abstrata (AST).

Arquivos de documentação (como Markdown ou arquivos de texto puro) ou scripts sem estrutura orientada a objetos (como arquivos SQL ou JSON) não possuem uma hierarquia clássica de classes e métodos. Por isso, o ASTChunker adota estratégias específicas e otimizadas para cada tipo de formato:

Estratégias de Chunking por Formato

Referências cruzadas em Markdown (busca enriquecida)

Além de indexar seções Markdown por cabeçalhos, o atlas_search enriquece resultados language=="markdown" com o campo opcional markdown_references — sem reindexar nem alterar o schema LanceDB. O enriquecimento é feito em tempo de busca a partir do conteúdo do chunk.

• Links padrão: [texto](destino.md) e [texto](destino.md#secao)
• Wikilinks Obsidian: [[destino]], [[destino|alias]], [[destino#Secao]], ![[embed]]
• Resolução de wikilinks "bare": nomes sem path (ex.: [[mcp-server]]) são resolvidos globalmente contra o mapa de arquivos .md do manifest.json; ambiguidade retorna lista de candidates.
• Âncoras: quando o destino está indexado, o campo resolved_section pode mapear #secao ao nome da seção correspondente.

{
  "file_path": "docs/architecture.md",
  "language": "markdown",
  "symbol": "Pipeline de Indexação",
  "score": 0.041,
  "markdown_references": [
    {
      "file_path": "docs/mcp-overview.md",
      "anchor": "stdio-transport",
      "resolved_section": "Transporte stdio"
    },
    {
      "file_path": "docs/obsidian-vault/note.md",
      "anchor": null,
      "resolved_section": null
    }
  ]
}

O servidor MCP do Atlas expõe quatro ações principais que a IA consome automaticamente para gerenciar o contexto do projeto:

Início rápido (sem clonar o repositório)

Para usar o Atlas em qualquer projeto, basta registrar o servidor MCP no seu cliente e indexar o workspace uma vez. O pacote roda via uvx, direto do GitHub — 100% local após o download inicial das dependências.

uvx --from git+https://github.com/LuisCarlosLopes/codesteer-atlas.git \
  atlas-index --workspace .