AST MCP SERVER

ast-mcp-server

ast-mcp-server dá aos agentes de codificação acesso compacto e ciente de tipos a projetos TypeScript e JavaScript. Ele usa o modelo de projeto real do compilador por meio de ts-morph, então declarações, referências, locais de renomeação e diagnósticos vêm da AST em vez de suposições de busca por texto.

As leituras são limitadas e estruturadas. As escritas seguem um protocolo explícito de prepare → review → apply com hashes imutáveis, verificações de atualização do workspace, proteções de diagnóstico e recibos idempotentes.

O problema

Agentes de codificação frequentemente recorrem a duas operações genéricas: ler arquivos como texto simples e escrever patches de texto. Isso funciona, mas tem três custos previsíveis:

1. Contexto demais. O agente pode carregar centenas de linhas quando só precisa de uma assinatura ou corpo de método. Isso consome contexto do modelo e tokens sem melhorar a resposta.
2. Edições frágeis. Patches de texto não entendem inerentemente declarações, escopos, sobrecargas ou diagnósticos do TypeScript. Uma edição de aparência plausível pode atingir a construção errada ou introduzir um novo erro do compilador.
3. Raciocínio entre arquivos fraco. A busca por texto pode encontrar palavras correspondentes, mas não consegue distinguir de forma confiável dois símbolos não relacionados com o mesmo nome. Referências e renomeações em todo o projeto precisam do entendimento do programa pelo compilador.

O que esta ferramenta faz em vez disso

Este servidor MCP dá ao agente ferramentas de código estruturais além de leituras e escritas genéricas de arquivos. Internamente, ts-morph usa o modelo de projeto do compilador TypeScript, então o servidor pode raciocinar sobre declarações e referências como código em vez de texto indiferenciado.

Necessidade	Operação estrutural	Escopo retornado
Ler um arquivo limitado	ast_get_file	Linhas de origem selecionadas exatas, hashes e atualização limitada
Explorar contexto limitado	ast_explore	Seletores classificados mais origem e referências opcionais
Entender um arquivo	ast_get_outline	Assinaturas sem corpos de implementação
Inspecionar uma declaração	ast_get_symbol_source	Origem exata para uma função, método, classe ou tipo
Encontrar usos em todo o projeto	ast_find_references	Locais de referência resolvidos pelo compilador
Entender o impacto de um símbolo	ast_get_impact	Relações diretas/transitivas limitadas respaldadas pelo compilador
Selecionar testes afetados	ast_find_test_candidates	Provas candidatas completas de relações de entrada do compilador
Renomear um símbolo em todos os lugares	ast_rename_symbol	Um plano de renomeação revisado em todo o projeto
Alterar uma implementação	ast_replace_symbol_body	Um plano somente de corpo que preserva a declaração

As leituras podem começar com uma fatia de arquivo limitada, um esboço compacto ou origem exata apenas para a declaração que precisa de inspeção. Mutações são preparadas em memória primeiro, comparadas com diagnósticos de linha de base e retornadas como planos imutáveis vinculados a hash. Nada é gravado até que o chamador revise e aplique explicitamente o plano.

Escolhendo uma ferramenta de leitura

• Use ast_get_file quando o caminho do arquivo é conhecido e o agente precisa de linhas de origem exatas. É somente leitura, usa offset baseado em zero e limit limitado, retorna registros de linha baseados em um, um hash de bytes SHA-256, snapshot_state no nível do arquivo e metadados limitados de freshness do projeto (fresh, pending, stale, rebuilding ou degraded).
• Use ast_get_file com symbols_only: true quando apenas seletores e assinaturas sem corpo são necessários de um arquivo conhecido.
• Use ast_explore quando a pergunta abrange descoberta e evidência. Seu resumo padrão é limitado; use detail: "context" para origem selecionada e detail: "full" para origem mais referências do compilador.
• Use ast_get_outline para uma visão compacta sem corpo de um arquivo conhecido sem linhas de origem.
• Use ast_get_symbol_source quando uma declaração ou implementação é a evidência necessária.
• Use ast_get_impact quando o símbolo exato é conhecido e relações diretas/transitivas limitadas do compilador são necessárias. Verifique coverage, work, truncation, incomplete e proven_empty; isso é evidência somente leitura, não um plano de mutação.
• Use ast_find_test_candidates quando um símbolo exato deve mapear para testes conservadores. Ele admite apenas evidências completas de entrada de reference, import, export, extends, implements e call, retorna caminhos completos e nunca executa testes.

snapshot_state: "fresh" significa que os bytes do arquivo retornado correspondem ao instantâneo sincronizado do compilador. O objeto separado freshness descreve o estado do projeto/sessão e preserva causas como alterações de origem ou falha do observador. Nenhum campo significa que o projeto tem zero diagnósticos do TypeScript; use ast_get_diagnostics para erros e avisos do compilador.

Confiança, atualização e completude

O servidor expõe rótulos de evidência em vez de colapsar cada resultado em uma pontuação de confiança não qualificada:

Rótulo	Significado	Uso seguro
provenance: "compiler", confidence: "exact", resolution: "resolved", freshness.state: "fresh"	Uma relação resolvida pelo instantâneo ativo do compilador TypeScript. Esta é a única combinação que define compiler_authoritative: true.	Pode apoiar evidência de impacto limitado e candidatos a teste respaldados pelo compilador.
provenance: "syntax"	Sintaxe ou estrutura da AST sem resolução semântica de símbolos.	Navegação e contexto estrutural apenas; não é prova de que dois símbolos estão relacionados.
provenance: "heuristic"	Uma sugestão baseada em convenção ou nome.	Apenas dicas de descoberta; nunca autoridade de mutação ou candidato a teste respaldado pelo compilador.
evidência de índice	Um acelerador de consulta derivado, não autoridade do compilador. O padrão de produção usa SQLite nativo quando a persistência está ausente ou enabled; todo seletor indexado ainda requer validação do compilador e um fallback do compilador.	Roteamento mais rápido apenas; entradas desatualizadas, ausentes ou incompatíveis devem falhar de forma fechada ou recorrer ao compilador.

A atualização é ortogonal aos diagnósticos do TypeScript. fresh significa que a evidência corresponde ao instantâneo sincronizado; pending, rebuilding, stale ou degraded significa que a resposta não deve ser apresentada como evidência atual do compilador. As ferramentas de leitura expõem o estado, causas (source_change, config_change, index_failure, watcher_failure ou compiler_rebuild) e o carimbo de data/hora limitado de checked_at. ast_get_impact recusa relações de compilador não atualizadas. ast_explore retorna o estado junto com metadados de completeness, unresolved, budget e truncation em vez de descartar evidências silenciosamente.

Todas as leituras são orçadas. Os chamadores controlam a paginação e, quando aplicável, max_bytes, reference_limit, max_depth, max_nodes e max_edges; as respostas relatam limites efetivos. Uma parada limitada é evidência incompleta, não um resultado negativo vazio.

O impacto tem dois canais independentes de completude:

Canal	Evidência	Incompleto quando
Cobertura semântica	Uma célula canônica por tipo solicitado, direção e classe de ponto final: not_applicable, completed, unsupported ou unfinished	Qualquer célula aplicável é unsupported ou unfinished
Travessia/trabalho	truncation mais work.work_limit_reached e seus contadores	Um limite de profundidade/nó/aresta/trabalho impede a conclusão

incomplete é verdadeiro quando qualquer canal está incompleto. proven_empty é verdadeiro apenas quando há zero arestas, toda célula aplicável foi concluída e nenhum limite foi esgotado. A solicitação pública de impacto de sete tipos/padrão inclui contains; como não existe produtor de contains com escopo, a contenção padrão ou explícita aplicável é unsupported, então o resultado é incompleto mesmo quando a travessia não foi truncada.

ast_find_test_candidates exclui deliberadamente contains e fixa o escopo de admissão a seis tipos de entrada: reference, import, export, extends, implements e call. Ele retorna INCOMPLETE_EVIDENCE antes da paginação para evidência desatualizada, inexata, não resolvida, truncada, com trabalho esgotado, não suportada ou inacabada. Apenas autoridade completa de seis tipos pode retornar candidates: [] com completeness.proven_empty: true; a paginação fatia candidatos determinísticos enquanto cada prova e os metadados de travessia não paginados de coverage, work permanecem inteiros.

Esses campos são aditivos: formas de aresta existentes, strings de tipo, padrões e erros públicos permanecem estáveis. JSON de ast_get_impact do MCP e TOON representam o mesmo resultado lógico de cobertura/trabalho; a saída canônica do candidato permanece JSON, enquanto a saída em lote somente leitura pode codificar esse mesmo resultado de candidato como TOON. O despacho de propriedade, elemento, dinâmico, chave computada e alternativa externa permanece sem arestas e inacabado—este contrato não certifica os classificadores adiados #219 ou #220.

Por que isso ajuda

• Menos contexto: o agente recupera a menor unidade estrutural que responde à pergunta em vez de carregar o arquivo completo por padrão.
• Alterações mais seguras: seleção exata de símbolos, deltas de diagnóstico, verificações de atualização do workspace e prepare → review → apply reduzem os modos de falha da edição de texto ad hoc.
• Operações precisas em todo o projeto: referências e renomeações usam resolução do compilador em vez de corresponder texto de identificador com grep. AST-aware editing não é uma prova de que uma alteração é semanticamente correta. A segurança vem da combinação de seleção estrutural com diagnósticos, pré-visualizações exatas, hashes revisados, verificações de atualização e semântica de aplicação com falha fechada.

O benchmark em lote incluído registra uma redução de 50% nas idas e voltas do modelo e uma redução de 94,67% no contexto serializado para seu cenário de busca até a fonte. O corpus de modelagem de resultados registra uma redução de 68,80% nos tokens agregados TOON voltados ao modelo, preservando seletores/coordenadas de referência declarados com as mesmas seis chamadas lógicas. O benchmark de formato separado registra 25,87% em seu corpus de coleção elegível. O benchmark de fluxo de trabalho de contexto verifica a preservação de evidências e os limites de chamadas para fluxos de trabalho de arquivo completo, primitivo e ast_explore. Estas são estimativas locais reproduzíveis de o200k_base, não alegações universais de tokens, cobrança, cache ou latência.

Requisitos

• Node.js 22.13.0 ou mais recente
• Corepack com Yarn 4.15.0 (fixado por packageManager)
• Um projeto de destino com um tsconfig.json

Ambiente suportado e limite de confiança

A v0.12.0 publicada requer Node.js >=22.13.0; sua matriz de evidências imutáveis tem como alvo o Node.js 22.13.0 exato e a linha atual do Node.js 24. A aplicação estrutural e a publicação gerenciada de arquivos de configuração são verificadas apenas em Linux x64 com GNU coreutils 9.7 mv suportando --update=none-fail, --exchange, --no-copy e --no-target-directory, GNU coreutils ln -L -T, caminhos de descritores procfs em /proc/self/fd, O_DIRECTORY/O_NOFOLLOW e um sistema de arquivos de destino que passa na sonda de identidade de link/exchange de propriedade. Uma primitiva negada ou com falha bloqueia mutações antes dos efeitos de origem; não há fallback de renomear, copiar/excluir ou apenas nome de caminho. Outras arquiteturas Linux ou sistemas sem essa matriz completa, macOS e Windows permanecem não verificados.

Este é um servidor stdio local. Ele é executado com as permissões do sistema de arquivos do usuário invocador, e os clientes podem solicitar qualquer project_root que esse usuário possa acessar. Ele não fornece autenticação HTTP, sandboxing, isolamento de locatário ou limite de segurança de serviço remoto. Operação remota, não confiável e multi-locatário não é suportada.

Trabalhador de compilador supervisionado opcional

O compilador é executado no processo por padrão. Operadores Linux podem manter explicitamente o pai stdio conectado enquanto permitem que um filho compilador ocioso saia e seja reativado lentamente:

AST_COMPILER_WORKER_MODE=supervised ast-mcp-server

O pai aguarda a prontidão do filho antes de reproduzir o estado de inicialização limitado. Solicitações e cancelamentos permanecem afins à geração; histórico de mutação, leases de operação ativa e trabalho de aplicação crítico para conclusão impedem reciclagem insegura. Defina AST_COMPILER_WORKER_MODE=in_process para o rollback completo, ou defina AST_COMPILER_WORKER_IDLE_TTL_MS=0 para manter o relay enquanto desabilita a reciclagem ociosa.

O canário Linux limitado passou no Node.js 22.13.0 exato e no Node.js 24 com recuperação PSS repetível, impressões digitais estáveis do compilador, reutilização inalterada do SQLite, diagnósticos redigidos limitados e sem órfãos após a morte do pai. Isso é um filho por conexão, não um daemon compartilhado, pool ou novo padrão. Veja ADR 0014.

Na v0.12.0 publicada, um AST_SYMBOL_INDEX_PERSISTENCE ausente ou enabled explícito seleciona o cache privado de índice de símbolos SQLite. disabled é o rollback imediato apenas em memória. canary requer um AST_SYMBOL_INDEX_CACHE_ROOT normalizado absoluto explícito. Política ou armazenamento inválido falha fechado para leituras de memória autoritativas do compilador com status limitado sem caminho.

A raiz de cache padrão é selecionada de AST_SYMBOL_INDEX_CACHE_ROOT, depois XDG_CACHE_HOME, depois HOME. Inspecione ou limpe apenas artefatos de cache derivados através do CLI limitado:

ast-tool cache inspect
ast-tool cache clear --yes

Limpar requer confirmação exata, recusa artefatos SQLite inseguros ou ativos e preserva arquivos regulares desconhecidos. Nenhum GC automático de cache está habilitado.

Veja Política de suporte para o contrato completo de plataforma, runtime, persistência e operacional. Relate problemas de segurança através de SECURITY.md.

Instalação

Instale o CLI publicado globalmente enquanto mantém os scripts de ciclo de vida de dependências desabilitados:

npm install --global ast-mcp-server --ignore-scripts
ast-tool setup

--ignore-scripts impede que dependências executem hooks preinstall, install ou postinstall. O pacote e suas dependências de runtime atuais não exigem esses hooks.

Instalar a partir da fonte

Para compilar a fonte atual em vez disso:

git clone https://github.com/yailPeralta/ast-mcp-server.git
cd ast-mcp-server
corepack enable
yarn install --immutable
yarn build

O repositório fixa o Yarn 4 e confirma enableScripts: false em .yarnrc.yml. Os scripts de ciclo de vida de dependências são, portanto, desabilitados durante a instalação; mudar do npm sem essa configuração apenas trocaria logotipos enquanto preservaria o risco.

O pacote expõe dois executáveis quando instalado:

• ast-mcp-server: servidor stdio MCP.
• ast-tool: CLI de lote, instalação de habilidades e configuração de agente.

Diagnosticar a instalação ativa

ast-tool doctor [--project <config-or-dir>]

O Doctor reutiliza a descoberta de projeto do CLI e as autoridades de runtime existentes sem alterar o estado do projeto, agente, pacote ou habilidade. Ele imprime JSON limitado; saída 0 é saudável, 1 degradada e 2 falhou. Um compilador saudável permanece utilizável quando apenas o índice SQLite derivado está degradado. O diagnóstico autônomo marca evidências de índice e fila apenas de sessão registrada como not_run em vez de fabricar estado saudável.

Atualizar um pacote instalado

Inspecione a instalação global ativa sem escrever, ou atualize-a imediatamente:

ast-tool upgrade --check
ast-tool upgrade

A atualização suporta apenas um pacote direto comprovadamente pertencente ao prefixo global npm ativo ou ao Volta. Ela rejeita instalações vinculadas/fonte e ambíguas, nunca usa sudo, adivinha de PATH ou aceita --yes. O npm executa seu npm-cli.js comprovado através do Node ativo com scripts de ciclo de vida desabilitados e uma cópia descartável de cache/config; a limpeza é verificada e bloqueia o sucesso se a ausência não puder ser comprovada. O Volta usa sua integração nativa. O CLI atualizado então reconcilia a configuração gerenciada através desse Node. Bytes de habilidades personalizados permanecem intocados e produzem ast-tool setup --agents all --yes --force-skill. Reinicie os clientes MCP após qualquer atualização de pacote; um servidor já em execução não muda no lugar.

Configuração guiada do agente

O pacote instalado abre o assistente interativo com:

ast-tool setup

A partir de um checkout da fonte, use o script Yarn; ele compila primeiro e depois abre o mesmo assistente:

yarn setup

O assistente suporta exatamente seis clientes CLI nesta ordem: Claude Code, Hermes, OpenCode, Codex CLI, Gemini CLI e GitHub Copilot CLI. Cursor, Windsurf, Cline e outros clientes integrados a editores são intencionalmente excluídos. Clientes compatíveis detectados começam marcados; clientes indisponíveis ou incompatíveis são desabilitados com um motivo. Use Up/Down para mover, Space para alternar, Enter para enviar, ou Escape/Ctrl-C para cancelar.

1. pré-verifica o registro MCP ast existente de cada cliente selecionado, destino da habilidade e destino efetivo de orientação gerenciada;
2. instala ou atualiza com segurança a habilidade structural-code-editing incluída;
3. adiciona um bloco de ativação de propriedade de marcador a cada superfície de instrução global verificada, preservando todos os bytes de propriedade do usuário;
4. registra o servidor MCP deste pacote através do CLI oficial do agente;
5. reconecta e verifica as ferramentas esperadas.

Registros MCP correspondentes existentes, arquivos de habilidade e blocos gerenciados permanecem inalterados. Registros MCP conflitantes ou orientação gerenciada malformada/desconhecida falham antes de qualquer escrita; resolva-os explicitamente em vez de deixar um script de configuração adivinhar. Atualizações de habilidade são automáticas apenas quando os bytes instalados correspondem a um SHA-256 exato admitido de um tarball npm publicado. Bytes de habilidade desconhecidos ou personalizados falham fechado, a menos que --force-skill seja explícito. Essa flag se aplica apenas à habilidade e não pode substituir conflitos de orientação, rotas inseguras ou corridas de sistema de arquivos.

A orientação usa o contrato de instrução global verificado de cada cliente em vez de um nome de arquivo universal:

Cliente	Destino de orientação gerenciada
Claude	$CLAUDE_CONFIG_DIR/CLAUDE.md, ou ~/.claude/CLAUDE.md
OpenCode	AGENTS.md nativo efetivo; um fallback Claude existente pode ser compartilhado ou preservado quando o OpenCode não tem arquivo nativo
Codex	$CODEX_HOME/AGENTS.override.md não vazio, caso contrário $CODEX_HOME/AGENTS.md; CODEX_HOME padrão para ~/.codex
Gemini	O único context.fileName seguro suportado de ~/.gemini/settings.json, caso contrário ~/.gemini/GEMINI.md
Hermes	skill_only; a configuração não modifica SOUL.md nem inventa um destino de instrução global
Copilot	skill_only; a configuração não inventa um destino de instrução global pessoal

O intervalo gerenciado é delimitado por marcadores de início/fim ast-tool:structural-code-editing guidance v1. A configuração atualiza apenas esse intervalo, preserva o BOM UTF-8 do arquivo, estilo de nova linha, modo e todo o conteúdo fora do intervalo, e rejeita destinos duplicados, parciais, reordenados, desconhecidos, symlinked ou não regulares. As escritas fixam a cadeia pai, pré-imagem, inode temporário mantido e destino. Novos arquivos usam publicação sem clobber vinculada a descritor; substituições usam uma troca atômica no mesmo diretório, validam ambas as identidades trocadas mais os bytes e modo da pré-imagem fixada, e revertem o par exato quando uma substituição em chamada ou edição de mesmo inode é detectada. Cada pós-imagem concluída é reautenticada antes de mutação posterior de ativo ou MCP. A configuração entre clientes é convergente em vez de globalmente transacional.

A saída de configuração bem-sucedida usa o esquema version: 2. Cada agente relata mcp, skill e guidance; escritas físicas incluem um asset de skill, guidance ou mcp_config. Uma reprodução completa retorna cada item aplicável como unchanged/skill_only e um array physical_writes vazio. Uma publicação gerenciada com falha separa completed_writes, possibly_committed, rolled_back, rollback_failed e pending; um commit incerto ou rollback com falha nunca é relatado como intocado e requer inspeção e um novo replanejamento.

Para automação, torne o conjunto de destino e a confirmação explícitos:

ast-tool setup --agents all --yes
ast-tool setup --agents claude,codex --yes

A partir de um checkout da fonte, substitua ast-tool por yarn setup nesses comandos.

--agents all é resolvido apenas após a detecção e significa cada cliente compatível detectado. Se qualquer cliente detectado tiver saída desconhecida ou incompatível, a configuração falha antes das escritas. IDs explícitos são estritos e rejeitam clientes indisponíveis. A configuração não interativa requer tanto --agents quanto --yes.

OpenCode 1.18.18 ou mais recente é necessário. Como opencode mcp add ignora o roteamento de configuração personalizado, a configuração atualiza apenas mcp.ast em OPENCODE_CONFIG, depois OPENCODE_CONFIG_DIR/opencode.json, depois ~/.config/opencode/opencode.json. Comentários JSONC, chaves não relacionadas e modo de arquivo são preservados. O comando de configuração nominalmente diagnóstico do OpenCode normaliza ambos os arquivos de configuração roteados, então a configuração executa descoberta e verificação contra cópias descartáveis enquanto retém os bytes de configuração selecionados e falha fechado se o destino real planejado mudar. A configuração do Gemini pode exigir confiar na pasta atual antes do registro. Diagnósticos usam um ID de correlação e omitem argumentos de comando, ambiente, credenciais e saída bruta do provedor; falhas de configuração podem incluir um caminho de destino limitado para que o operador possa inspecionar uma escrita incerta ou pendente.

Instalar a habilidade do agente

O pacote inclui uma habilidade structural-code-editing que ensina um agente quando usar as ferramentas AST, como minimizar contexto e como revisar mutações com segurança. Instale-a para Claude Code e Hermes com um comando:

ast-tool install-skill all

Ou instale um alvo por vez:

ast-tool install-skill claude
ast-tool install-skill hermes

O padrão é o escopo de usuário. Ele grava no diretório pessoal de skills do Claude Code e no HERMES_HOME ativo:

Alvo	Destino
Claude Code	$CLAUDE_CONFIG_DIR/skills/structural-code-editing/SKILL.md, ou ~/.claude/skills/... por padrão
Hermes	$HERMES_HOME/skills/software-development/structural-code-editing/SKILL.md, ou ~/.hermes/... por padrão
OpenCode, Codex, Gemini, Copilot	~/.agents/skills/structural-code-editing/SKILL.md (uma gravação física, quatro resultados lógicos)

Para confirmar a skill em um projeto para Claude Code, use o escopo de projeto:

ast-tool install-skill claude --scope project --project-root /absolute/project

Isso grava .claude/skills/structural-code-editing/SKILL.md abaixo desse projeto. O escopo de projeto é rejeitado intencionalmente para Hermes porque as skills do Hermes pertencem a um perfil, não a um repositório de origem.

A instalação é idempotente. Os bytes atuais existentes são deixados intactos; os bytes exatos do predecessor admitidos pelo manifesto de proveniência npm empacotado são atualizados com segurança. Bytes desconhecidos ou personalizados falham de forma fechada, a menos que --force seja explícito. install-skill nunca grava orientação global nem configura MCP. A partir de um checkout de origem não vinculado, substitua ast-tool por yarn node /absolute/path/to/ast-mcp-server/dist/cli.js.

O Claude Code detecta alterações em um diretório de skills existente ao vivo; reinicie-o se o diretório de skills de nível superior não existia quando a sessão começou. No Hermes, execute /reload-skills ou inicie uma nova sessão e verifique com hermes skills list.

install-skill apenas instala a skill; não configura o transporte MCP. Use o comando guiado setup para fazer ambos, ou conclua a configuração MCP específica do cliente abaixo—as instruções são úteis, mas ainda não aprenderam a abrir um socket stdio através de pensamento positivo.

Uso com Claude Code

O Claude Code suporta servidores MCP stdio locais. Após compilar este repositório, registre o servidor com um ponto de entrada absoluto:

AST_MCP_DIR="$(pwd)"
claude mcp add --scope user --env AST_MCP_APPLY_GUARD=allow --transport stdio ast -- \
  node "$AST_MCP_DIR/dist/index.js"
claude mcp get ast

claude mcp get ast deve relatar Status: ✔ Connected. O separador -- é obrigatório: tudo depois dele é o comando do servidor, não uma opção do Claude Code.

O exemplo usa --scope user, o que torna o servidor disponível em todos os seus projetos. Use --scope local para registrá-lo apenas para o projeto a partir do qual você executa o comando. Evite confirmar um .mcp.json com escopo de projeto que contenha o caminho absoluto de checkout de outro desenvolvedor.

Inicie o Claude Code dentro de qualquer projeto TypeScript com um tsconfig.json:

cd /absolute/path/to/your-typescript-project
claude

Em seguida, peça ao Claude para usar as ferramentas ast. Por exemplo:

Use the ast MCP server to inspect this project.
First search for UserService, then fetch only the exact source of its create method.

Para uma renomeação revisada:

Use ast_rename_symbol to prepare renaming UserService.create to createUser.
Do not apply it yet. Show me the affected files, diagnostic delta, plan hash,
and the complete operation preview.

Após revisar a pré-visualização:

Apply that operation with ast_apply_operation using the exact operation_id and
plan_hash returned by the prepare step.

As ferramentas de leitura e preparação com escopo de projeto exigem project_root. O Claude deve passar o diretório atual do projeto ou seu caminho explícito tsconfig.json. Chamadas de pré-visualização e aplicação usam as coordenadas de operação preparadas; o próprio servidor MCP não contém caminhos específicos do repositório.

MCP ou CLI em lote?

Fluxo de trabalho	Interface recomendada
Exploração interativa ou uma mutação revisada	Ferramentas MCP do Claude Code
Um pipeline de leitura de várias etapas conhecido	ast-tool run pipeline.json via Bash
Preparar agora e aplicar em um processo posterior	ast-tool run, depois ast-tool apply

Use /mcp dentro do Claude Code para inspecionar o status e as ferramentas do servidor. Fora da sessão, use claude mcp list, claude mcp get ast ou claude mcp remove ast -s user.

Outros clientes MCP

Hermes Agent:

hermes mcp add ast --command node --env AST_MCP_APPLY_GUARD=allow --args /absolute/path/to/ast-mcp-server/dist/index.js
hermes mcp test ast

As ferramentas com escopo de projeto aceitam project_root, seja o diretório do projeto ou um caminho explícito tsconfig.json. O servidor não contém caminhos específicos do repositório.

DeepSeek Harness (Pré-visualização para Desenvolvedores)

Um adaptador fino acompanha este pacote: cordis.patch.yml monta o comando stdio empacotado ast-mcp-server através da ponte oficial @deepseek-ai/dsh-mcp-client, declarado através de exatamente "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }. Esta é uma Pré-visualização para Desenvolvedores contra uma revisão fixada do Harness, compilada a partir da fonte (dsh-v0.1.2-alpha.1 em cd5ef8148158c3a752a658978873241fdf8e2bbc). O pacote publicado ast-mcp-server@0.13.0 é a linha de base de compatibilidade:

dsh plugin --profile web add ast-mcp-server@0.13.0

Para um candidato local, empacote e instale seu tarball:

yarn pack --out ast-mcp-server-%v.tgz
dsh plugin --profile web add ./ast-mcp-server-0.13.1.tgz

A primeira superfície suportada é leituras + preparação + pré-visualização. Todo caminho de aplicação é negado por uma proteção de falha fechada: ast_apply_operation não é registrado a menos que AST_MCP_APPLY_GUARD=allow seja definido explicitamente (o patch enviado em vez disso fixa deny, então a superfície do Harness permanece negada por padrão; um valor não definido ou inválido também nega). O adaptador também define AST_MCP_TEXT_PROJECTION=canonical_json: resultados estruturados bem-sucedidos mantêm seu structuredContent sem perdas e ganham texto JSON canônico apenas quando o texto MCP comum está vazio, porque o apresentador nativo fixado expõe apenas um marcador de resultado vazio não útil. A projeção é específica do adaptador, nunca substitui texto existente, e relata um marcador explícito de limite de tamanho quando o quadro supervisionado completo tem espaço. Se até mesmo o resultado estruturado inalterado exceder o quadro do worker existente, o modo supervisionado falha de forma fechada em vez de truncar ou corromper. Lacunas conhecidas a montante permanecem não autoritativas: a ponte oficial descarta anotações de ferramentas MCP (readOnlyHint/destructiveHint) e lança o filho stdio fora do sandbox do Harness.

yarn test:dsh-adapter é a verificação obrigatória. Ele vincula a integridade pública do npm 0.13.0, empacota o candidato, compila o Harness e a ponte fixados a partir da fonte e prova tools.mode: native, o catálogo com escopo de 15 ferramentas, esquemas de entrada executáveis completos, leitura/preparação/pré-visualização, todas as três combinações inválidas de ast_explore, ausência de aplicação e aplicação direta rejeitada. O portão de esquema congela o contrato público vazio de ast_explore como RED, exige que o candidato as definições de registro/nativas correspondam e faz hash de todos os 14 esquemas de modelo não afetados. Um modelo determinístico de duas etapas então invoca mcp__ast__ast_get_project_status através de uma Sessão/Agente headless real: a linha de base pública deve reproduzir o marcador de resultado vazio, enquanto o candidato corrigido deve entregar JSON canônico sem perdas para a próxima solicitação de modelo, o tool/result durável e um resumo/replay de Agente frio reconstruído a partir da persistência. O smoke remove e relê seu estado descartável de perfil/workspace e falha (nunca pula) em uma incompatibilidade de identidade, pré-requisito ausente, vazamento de ciclo de vida ou lacuna de evidência.

Ferramentas MCP

Ferramenta	Propósito	Muta arquivos
ast_list_files	Inventário paginado de arquivos de origem relativos ao projeto	Não
ast_get_project_status	Compilador somente leitura, frescor, índice e status de operação	Não
ast_explore	Seletores compostos limitados, evidência de origem e referências	Não
ast_get_file	Linhas de origem exatas limitadas, hash de bytes e estado de snapshot	Não
ast_get_outline	Assinaturas de declaração sem corpo; metadados de símbolo detalhados são opcionais	Não
ast_get_symbol_source	Origem exata para uma declaração	Não
ast_search_symbols	Descoberta estrutural paginada de símbolos	Não
ast_find_references	Referências resolvidas pelo compilador com contexto limitado	Não
ast_get_impact	Evidência de impacto limitada de entrada/saída apoiada pelo compilador	Não
ast_find_test_candidates	Testes afetados paginados com provas de relacionamento atômicas do compilador	Não
ast_get_diagnostics	Diagnósticos TypeScript com escopo de projeto ou arquivo	Não
ast_rename_symbol	Preparar uma renomeação em todo o projeto	Não
ast_replace_symbol_body	Preparar uma substituição apenas de corpo preservando a assinatura	Não
ast_scaffold_class	Preparar um novo arquivo de classe com métodos de espaço reservado explícitos	Não
ast_get_operation_preview	Recuperar o diff retido completo para um plano preparado	Não
ast_apply_operation	Aplicar um plano revisado e vinculado a hash	Sim

Os resultados de leitura usam caminhos relativos ao projeto, ordenação determinística, saída MCP estruturada e paginação onde os conjuntos de resultados podem crescer com o projeto.

Agregados de diagnóstico

Defina include_aggregates: true em ast_get_diagnostics para resumir o snapshot de diagnóstico normalizado completo independentemente da página bruta selecionada. A opção padrão é false; respostas desabilitadas omitem aggregates e mantêm a forma existente.

Cada dimensão de código e arquivo retorna no máximo 20 grupos classificados. groups.length + omitted_group_count = total_group_count, e sum(groups[*].count) = covered_diagnostic_count. Cobertura de código mais omitted_diagnostic_count é igual ao total de diagnóstico; a cobertura de arquivo também adiciona unfiled_diagnostic_count. Os grupos de arquivos contêm apenas caminhos normalizados relativos ao projeto, mas podem divulgar um caminho ausente da página bruta selecionada.

ast_explore suporta rotas de consulta, arquivo exato e símbolo exato. Seu perfil padrão summary retorna seletores reutilizáveis limitados; context adiciona origem selecionada e full adiciona referências do compilador. Clusters de símbolos inteiros são admitidos sob o teto max_bytes do chamador, então origem, registros de referência e caminhos de chamada nunca são fatiados. omissions classifica componentes retidos como budget, incomplete ou untrusted, e qualquer omissão solicitada mantém a completude falsa.

Exato file_path mais solicitações symbol_path podem optar por call_spines estático limitado. Apenas sites de invocação frescos, exatos e resolvidos pelo compilador se qualificam; referências genéricas, despacho dinâmico e comportamento em tempo de execução não são inferidos. Ausência de call_spines não realiza travessia de chamadas. Cada resposta ainda relata frescor, completude, truncamento, seletores não resolvidos, limites de registro e contabilidade canônica de bytes serializados. Use as ferramentas primitivas quando uma única operação exata é mais clara ou ao preparar uma mutação. Veja ADR 0013.

A pesquisa de símbolos é classificada por relevância e padrão para no máximo 20 registros summary contendo file, um selector diretamente reutilizável, kind e signature sem corpo. Solicite detail: "selectors" apenas para coordenadas de roteamento, ou detail: "full", limit: 100 para os campos/página v0.4.0. As referências padrão são detail: "locations"; solicite detail: "context" apenas quando a linha de origem limitada for necessária.

Resultados TOON opcionais

ast_search_symbols, ast_find_references, ast_get_impact e ast_get_diagnostics aceitam output_format: "toon" para resultados pesados de coleção consumidos diretamente por um modelo. JSON permanece o padrão e preserva o objeto estruturado canônico.

MCP TOON é retornado uma vez como conteúdo estruturado moldado como { "format": "toon", "data": "..." }; data é o documento TOON sem perdas. O resultado JSON completo não é duplicado. Essas quatro ferramentas validam seu resultado Zod canônico e verificam um round-trip de igualdade profunda de codificação/decodificação antes da apresentação, mas não anunciam um único outputSchema MCP porque seu conteúdo estruturado bem-sucedido tem duas representações. Não solicite TOON para fonte, esboços, listas de arquivos, pré-visualizações ou resultados de mutação. Controles negativos verificados mostram que o envelope MCP torna essas formas maiores. TOON é uma otimização explícita específica de forma, não um novo dialeto para cada objeto à vista.

CLI em lote

ast-tool permite que o Claude Code e outros clientes com capacidade Bash reduzam um pipeline estrutural conhecido a uma única chamada de shell:

ast-tool validate pipeline.json
ast-tool run pipeline.json
ast-tool run pipeline.json --output-format toon
cat pipeline.json | ast-tool run -

Exemplo de pipeline de pesquisa para fonte:

{
  "version": 1,
  "project_root": "/absolute/project",
  "steps": [
    {
      "id": "search",
      "tool": "ast_search_symbols",
      "input": { "query": "UserService", "limit": 20 }
    },
    {
      "id": "source",
      "tool": "ast_get_symbol_source",
      "input": {
        "file_path": { "$ref": "#/steps/search/symbols/0/file" },
        "symbol_path": { "$ref": "#/steps/search/symbols/0/selector" }
      }
    }
  ],
  "emit": { "$ref": "#/steps/source" }
}

Um $ref é um JSON Pointer RFC 6901 enraizado nos resultados de etapas anteriores. Referências não podem apontar para frente. Se emit for omitido, apenas o resultado da etapa final é retornado; resultados intermediários permanecem dentro do processo.

Somente para lotes CLI, omita project_root ou forneça um diretório para selecionar o tsconfig.json ou jsconfig.json mais próximo a partir do diretório de invocação para cima. Um arquivo de configuração explícito sempre vence. A descoberta para em um .git ou limite de sistema de arquivos e rejeita ambiguidade no mesmo nível ou identidades via symlink; chamadas de ferramentas MCP ainda exigem um project_root explícito.

ast_find_test_candidates e ast_explore são admitidos como etapas de leitura. O executor de lote injeta o project_root do pipeline, rejeita uma raiz de etapa conflitante e invoca a mesma implementação MCP registrada. Provas de relacionamento candidatas e clusters de exploração permanecem intactos; JSON final e TOON diferem apenas na serialização, não na evidência lógica.

foreach limitado

{
  "version": 1,
  "project_root": "/absolute/project",
  "limits": { "concurrency": 4 },
  "steps": [
    { "id": "files", "tool": "ast_list_files", "input": { "limit": 20 } },
    {
      "id": "outlines",
      "tool": "ast_get_outline",
      "foreach": { "$ref": "#/steps/files/files" },
      "input": { "file_path": { "$item": "" } }
    }
  ]
}

$item aceita um ponteiro vazio para o item completo ou /field para um campo. Foreach é somente leitura, preserva a ordem, falha rapidamente e tem concorrência limitada.

Limites de lote

• Documento de entrada: 1 MiB.
• Etapas: 50.
• Invocações totais de ferramentas: 500.
• Itens foreach por etapa: 200.
• Concorrência de leitura: padrão 4, máximo 16.
• Cada resultado de etapa retido e saída serializada final: 10 MiB.
• Contexto intermediário total retido: 50 MiB.
• Uma raiz de projeto por pipeline.
• Sem ramificações, eval, JavaScript embutido, loops while ou transformações arbitrárias.

O sucesso é um valor JSON compacto no stdout por padrão. ast-tool run --output-format toon grava um documento TOON simples para um lote somente leitura; etapas internas permanecem JSON estruturado, e lotes de preparação rejeitam TOON antes da execução. Falhas de codificação e limite de saída não gravam stdout parcial e usam códigos estáveis ENCODING_ERROR ou OUTPUT_LIMIT. Erros são sempre JSON estruturado no stderr. Código de saída 0 é sucesso, 1 é falha de execução/aplicação e 2 é falha de uso ou esquema.

Mutações revisadas

Processo MCP

Renomeação, substituição de corpo e scaffold de classe nunca gravam diretamente durante a preparação:

1. Chame ast_rename_symbol, ast_replace_symbol_body ou ast_scaffold_class.
2. Revise o delta de diagnóstico, arquivos afetados, blocked e plan_hash.
3. Busque diffs completos com ast_get_operation_preview quando necessário.
4. Chame ast_apply_operation com ambos operation_id e plan_hash.

Planos MCP vivem em um armazenamento em memória limitado e não sobrevivem a um reinício do servidor.

ast_scaffold_class aceita imports estruturados, herança, decoradores, propriedades de parâmetros de construtor, propriedades inicializadas e uma ou mais assinaturas de método. Ele cria uma pré-visualização em memória para um alvo ausente .ts/.tsx relativo ao projeto. Cada método gerado contém inicialmente apenas throw new Error("Not implemented: Class.method"). Revise o diff de criação /dev/null e os diagnósticos, aplique o scaffold e substitua cada corpo de método pendente por ast_replace_symbol_body. Alvos existentes e pais simbólicos/de travessia falham fechados.

Limite de processo CLI

Um lote pode conter no máximo uma operação de preparação. Ela deve ser a etapa final e não pode usar foreach. ast_apply_operation e chamadas de pré-visualização arbitrárias são proibidas dentro de documentos de lote.

Uma preparação CLI grava um plano privado exato e retorna operation_id, plan_hash e plan_file de nível superior mesmo quando emit os omite:

ast-tool run prepare-rename.json
ast-tool apply /path/from/plan_file.astplan --plan-hash <reviewed-sha256>

O diretório de plano padrão é:

${XDG_STATE_HOME:-~/.local/state}/ast-tool/plans

Defina AST_TOOL_STATE_DIR para isolá-lo. Diretórios têm modo 0700; planos têm modo 0600, substituídos atomicamente, com tamanho limitado, versionados e expiram com a operação preparada. Arquivos de plano contêm bytes exatos de código-fonte proposto e devem ser tratados como código privado.

A aplicação carrega as pós-imagens exatas retidas, exige o hash revisado fornecido separadamente, valida hashes de bytes serializados e caminhos contidos, reverifica o workspace completo de código/configuração, encena gravações, verifica pós-imagens e persiste um recibo de aplicação dentro do mesmo bloqueio cooperativo de workspace. Uma invocação CLI posterior pode reproduzir esse recibo de forma idempotente, inclusive após o TTL de preparação.

Limite de garantia

O servidor não reivindica uma transação em todo o sistema de arquivos ou segurança contra um escritor em mutação contínua:

• Cada substituição troca e autentica um par encenado/destino. A aplicação de vários arquivos permanece sequencial, então pós-imagens anteriores podem ser visíveis antes que arquivos posteriores sejam confirmados.
• A reversão reversa restaura apenas um par exato de propriedade da operação. A perda de propriedade preserva as entradas observáveis e retorna AMBIGUOUS_APPLY; nunca recorre à substituição por nome de caminho.
• A criação é sem sobrescrita. Uma vez que um inode criado é publicado, uma falha posterior não pode inferir com segurança a propriedade de unlink, então o destino e o estágio oculto são preservados e a reversão falha fechada como ambígua.
• A aplicação MCP e CLI compartilham um bloqueio de sistema de arquivos com falha fechada, chaveado por tsconfig.json canônico quando usam o mesmo diretório de estado. Ele não coordena editores, escritores NFS, escritores usando outra configuração ou processos externos hostis.
• Barreiras de promessa determinísticas provam os intercalamentos de publicação/reversão testados. Elas são uma costura de teste de limite de ameaça, não uma garantia de atomicidade global ou escritor contínuo.
• A persistência de recibos ocorre antes que o bloqueio seja liberado. Se o armazenamento de recibos falhar após a substituição da fonte, a aplicação sai com código não zero e relata que pós-imagens verificadas podem estar presentes; a nova tentativa recupera o recibo somente quando o workspace completo corresponde exatamente à impressão digital pós-workspace revisada.
• Uma falha grave do processo pode deixar um bloqueio obsoleto. Remova-o somente após inspecionar seus metadados e provar que nenhuma aplicação está em execução; pós-imagens completas exatas podem então recuperar o recibo, enquanto estado parcial ou divergente permanece um conflito.
• O suporte de codificação de fonte é UTF-8, com ou sem BOM. Codificações não suportadas são rejeitadas.

Portões de desenvolvimento

Adicionar ou alterar uma ferramenta MCP

Mantenha esquemas, metadados, anotações, manipuladores, erros e serialização no módulo da ferramenta. Exporte um descritor congelado, adicione-o à ordem intencional em src/tools/catalog.ts e declare apenas fatos estáticos de efeito, lote, compatibilidade e formato direto. Não adicione estado de solicitação, descoberta dinâmica, invocação por nome ou um executor genérico ao catálogo.

Atualize os inventários independentes tools/list somente após revisar os metadados de fio completos; eles não devem importar ou derivar expectativas do catálogo. Em seguida, execute o catálogo focado e os testes de integração MCP, além dos portões de runtime, pacote e habilidade gerenciada abaixo.

yarn vitest run test/tool-catalog.test.ts test/mcp.integration.test.ts
yarn format:check
yarn lint
yarn typecheck
yarn test
yarn build
yarn test:mcp
yarn test:cli
yarn test:package
yarn test:installed-agents
yarn npm audit --all --recursive
yarn pack --dry-run

test:mcp exercita o servidor stdio construído. test:cli executa um pipeline de leitura e um fluxo de trabalho de preparação/aplicação/reprodução em processos Node separados. test:installed-agents é um portão manual dependente do host: ele compila primeiro, detecta clientes suportados instalados localmente, usa apenas homes/raízes de configuração descartáveis, verifica descoberta efetiva determinística sem chamadas de modelo, relata clientes indisponíveis e remove o estado descartável. Não é um requisito de CI portátil porque CI não instala todos os clientes externos.

Benchmarks

yarn benchmark /absolute/project --sample 20 --output benchmark/results/project.json
yarn benchmark:corpus benchmark/task-corpus.json --output benchmark/results/self-corpus.json
yarn benchmark:batch --iterations 5 --output benchmark/results/self-batch.json
yarn benchmark:formats
yarn benchmark:shapes

O benchmark de lote compara duas chamadas de cliente separadas com uma invocação de lote em processos Node novos, registrando idas e voltas de modelo, invocações reais de ferramentas, tempo de parede, RSS máximo e contagens de caracteres serializados. Contagens de caracteres não são estimativas de tokens específicas de modelo.

O benchmark de formato executa ferramentas reais contra este repositório, além de fixtures determinísticas de referência/diagnóstico. Ele verifica igualdade de valor JSON→TOON→, bytes UTF-8, estimativas gpt-tokenizer o200k_base, latência de codificação/decodificação, o envelope MCP real, metadados de ferramentas e controles negativos. Seu resultado verificado é benchmark/results/self-formats.json; estimativas locais de tokenizador não estabelecem cobrança do lado do provedor ou economia de cache. Veja benchmark/README.md para metodologia e limitações.

O benchmark de modelagem de resultados compara os perfis full/100/context compatíveis com v0.4.0 com os novos padrões públicos em tarefas de nome exato, caminho exato, prefixo, substring ampla e referência de vários arquivos. Ele falha em evidência ausente, chamadas obrigatórias extras, menos superfície de ferramentas do que o mínimo exigido pelo benchmark ou menos de 35% de redução agregada de tokens TOON. Seu resultado verificado é benchmark/results/self-result-shapes.json.

Escopo

• Projetos TypeScript e JavaScript compreendidos pelo compilador TypeScript.
• Renomeação estrutural, substituição de corpo de chamável e criação revisada de um scaffold de classe.
• Pipelines declarativos semelhantes a DAG com referências a resultados anteriores e foreach limitado.
• Sem migração arbitrária de assinaturas, criação/exclusão geral de arquivos, refatorações entre linguagens ou linguagem de script de propósito geral.