O contexto,
por dentro.

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:

Depois do Graph, fases opt-in ou sempre-locais podem complementar o índice: SCIP (ATLAS_SCIP=1) emite arestas calls; a camada semântica (ATLAS_SEMANTIC=1) grava semantic.json; a história de Git (sem flag) publica history.json na janela de 100 commits / 24 meses.

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 — quatro 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")

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

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 Jev é o modelo System One da TypeSafe. Recebe a consulta e os candidatos recuperados pelo Atlas e devolve uma avaliação de relevância com score e confiança para cada candidato. A chamada usa a API System One do OpenRouter.

Jev vem desligado. A busca híbrida e o rerank lexical continuam locais por padrão. ATLAS_RELEVANCE=1 habilita o Jev; ATLAS_CONTEXT_OPTIMIZATION=1 ativa o perfil compacto por padrão. As duas flags são independentes. Configurar uma chave ou ligar a camada semântica não habilita o Jev.

Rubrica v2: quatro níveis de evidência

A rubrica padrão é v2, com escala de 0 a 3. Cada nível tem critérios e exemplos; cada candidato inclui tipo (kind) e linguagem (language). A avaliação aceita perguntas em português, nomes exatos e identificadores parciais.

ATLAS_RELEVANCE_RUBRIC=v1 volta à rubrica anterior, com três níveis e escala de 0 a 2. Os limiares são proporcionais à escala. O campo score publicado em cada resultado da busca continua sendo o RRF; ele não é substituído pelo score Jev.

Corte padrão e seleção conservadora

ATLAS_RELEVANCE_CUT ausente ou 1 habilita o corte padrão quando Jev e perfil compacto estão ativos. As vagas cortadas não são repostas nem cedidas a commits; commits só ocupam vagas que o pool já não preenchia. omitted.relevance conta os descartes. Sem avaliação válida, não há corte.

Com ATLAS_RELEVANCE_CUT=0, vale a seleção conservadora: remove apenas score ≤ 1/8 da escala (0,375 na v2 ou 0,25 na v1) com confiança ≥ 0,90, permitindo repor a vaga pelo pool. Nos dois modos, se tudo sair, volta o primeiro candidato do ranking local com relevance_unconfirmed_fallback.

Entrega compacta (independente do Jev)

ATLAS_CONTEXT_OPTIMIZATION=1 faz response_profile=default resolver para compact em atlas_search e atlas_context: projeção enxuta, deduplicação por cobertura verificável, orçamento a 70% do teto e referências para expansão. O bloco budget só aparece quando algo foi cortado para caber. response_profile=full mantém a resposta completa.

Em atlas_expand, classes acima de aproximadamente 1.500 tokens, com métodos indexados, abrem como cabeçalho e outline dos métodos com suas referências. Expanda apenas os métodos necessários. ATLAS_EXPAND_OUTLINE=0 volta à classe inteira paginada.

Quando dispensar a chamada ao Jev

O gate fica desligado por padrão. ATLAS_RELEVANCE_GATE=1 dispensa a chamada quando a consulta é o nome exato de uma única função, método ou classe no pool recuperado. Isso não garante unicidade no repositório inteiro.

ATLAS_RELEVANCE_GATE=identifier dispensa o Jev para toda consulta-identificador, inclusive nomes parciais ou com pontos. Essas consultas mantêm a ordem lexical e a promoção do exato, mas perdem a reordenação Jev e o corte por relevância. O gate economiza chamadas; pode entregar mais contexto e reduzir a precisão.

"env": {
  "ATLAS_INDEX_DIR": "${workspaceFolder}/.code-index",
  "ATLAS_RELEVANCE": "1",
  "ATLAS_RELEVANCE_API_URL": "https://openrouter.ai/api/v1/systemone",
  "ATLAS_RELEVANCE_API_KEY": "sua-chave-openrouter",
  "ATLAS_CONTEXT_OPTIMIZATION": "1"
}

Mescle estas propriedades no env existente. A rubrica v2 e o corte já são os padrões; não é preciso declará-los. Guarde a chave em configuração local e não a versione no Git.

Para conferir a configuração, consulte atlas_status.relevance, incluindo rubric, cut, gate e egress. Esse status é estático: ele declara a configuração, sem testar a API. Consulte a referência do operador para medições e contratos detalhados.

O servidor MCP expõe sete ações. Use atlas_brief para se orientar, atlas_context quando o símbolo já é conhecido, atlas_search para localizar código, atlas_expand para abrir trechos de um resultado compacto, 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 .