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, textual e um grafo de conectividade na pasta local .code-index. O processo é orquestrado por index_workspace() em indexer.py e segue 6 fases ponderadas:

O que fica em .code-index/

Workspace com várias pastas ou repos

Você pode indexar subpastas específicas com --paths repetido ou via MCP paths=["frontend", "backend"]. Para workspaces com múltiplos repositórios git aninhados, a abordagem recomendada é um único .code-index na pasta pai.

uv run atlas-index --workspace . --paths src --paths docs --paths cognitive-base

# Via MCP (síncrono quando paths está definido)
atlas_index(paths=["src", "docs"])

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
    }
  ]
}

Rationale refs em código (grafo + busca)

Comentários estruturados no código viram metadados persistidos no índice e arestas no grafo. Resultados de atlas_search podem incluir rationale_refs apontando para notas de decisão.

• Cites: DECISAO-005, DEC-002, ADR-001, RFC-012
• Anotações: # WHY:, # NOTE: (ou //, --)
• Wikilinks em comentários: resolvidos contra arquivos .md do manifest

# DECISAO-005: embeddings locais com fastembed
# WHY: manter indexação 100% offline — nenhum código sai da máquina
def encode(self, texts: list[str]) -> list[list[float]]:
    ...

Além da busca semântica, o Atlas deriva um grafo de conectividade a cada indexação. Ele mapeia relações explícitas entre código, documentação, imports e rationale — não substitui atlas_search, mas responde perguntas do tipo "como A se conecta a B?".

Tipos de nó e aresta

Tool atlas_graph — três modos

Lê o graph.json já gerado — não reconstrói o grafo. Reindexe com atlas_index se o grafo estiver ausente (índices < 2.1.0).

atlas_graph(mode="hubs", top_n=10)

atlas_graph(mode="explain",
  target="index_workspace")

atlas_graph(mode="path",
  source="index_workspace",
  target="dec-002")

Visualizador graph.html

Após indexar, abra o HTML autocontido em .code-index/graph.html. O caminho absoluto aparece em atlas_status → graph_viewer_path.

• Busca por label ou id de nó
• Clique em nó para focar subgrafo local
• Filtros por tipo de nó e aresta
• Grafos grandes (> 3000 nós): modo hubs-only com opção “Expandir tudo”
• Debug: adicione ?debug=1 na URL

O servidor MCP expõe cinco ações principais. Use atlas_search para localizar código, atlas_graph para conectividade, e atlas_status apenas para diagnóstico explícito.

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 .