AST MCP SERVER

ast-mcp-server

ast-mcp-server proporciona a los agentes de codificación acceso compacto y consciente de tipos a proyectos TypeScript y JavaScript. Utiliza el modelo de proyecto real del compilador a través de ts-morph, de modo que las declaraciones, referencias, ubicaciones de renombrado y diagnósticos provienen del AST en lugar de conjeturas basadas en búsqueda de texto.

Las lecturas son acotadas y estructuradas. Las escrituras siguen un protocolo explícito prepare → review → apply con hashes inmutables, comprobaciones de frescura del espacio de trabajo, protecciones de diagnóstico y recibos idempotentes.

El problema

Los agentes de codificación a menudo recurren a dos operaciones genéricas: leer archivos como texto plano y escribir parches de texto. Eso funciona, pero tiene tres costos predecibles:

1. Demasiado contexto. El agente puede cargar cientos de líneas cuando solo necesita una firma o el cuerpo de un método. Eso consume contexto del modelo y tokens sin mejorar la respuesta.
2. Ediciones frágiles. Los parches de texto no entienden inherentemente declaraciones, ámbitos, sobrecargas o diagnósticos de TypeScript. Una edición de apariencia plausible puede apuntar a la construcción incorrecta o introducir un nuevo error del compilador.
3. Razonamiento débil entre archivos. La búsqueda de texto puede encontrar palabras coincidentes, pero no puede distinguir de manera confiable dos símbolos no relacionados con el mismo nombre. Las referencias y renombrados a nivel de proyecto necesitan la comprensión del programa por parte del compilador.

Qué hace esta herramienta en su lugar

Este servidor MCP proporciona al agente herramientas de código estructurales además de las lecturas y escrituras genéricas de archivos. Internamente, ts-morph utiliza el modelo de proyecto del compilador TypeScript, de modo que el servidor puede razonar sobre declaraciones y referencias como código en lugar de texto indiferenciado.

Necesidad	Operación estructural	Alcance devuelto
Leer un archivo acotado	ast_get_file	Líneas de origen seleccionadas exactas, hashes y frescura acotada
Explorar contexto acotado	ast_explore	Selectores clasificados más origen y referencias opcionales
Comprender un archivo	ast_get_outline	Firmas sin cuerpos de implementación
Inspeccionar una declaración	ast_get_symbol_source	Origen exacto para una función, método, clase o tipo
Encontrar usos en todo el proyecto	ast_find_references	Ubicaciones de referencia resueltas por el compilador
Comprender el impacto de un símbolo	ast_get_impact	Relaciones acotadas directas/transitivas respaldadas por el compilador
Renombrar un símbolo en todas partes	ast_rename_symbol	Un plan de renombrado revisado a nivel de proyecto
Cambiar una implementación	ast_replace_symbol_body	Un plan solo de cuerpo que preserva la declaración

Las lecturas pueden comenzar con un fragmento de archivo acotado, un esquema compacto u origen exacto solo para la declaración que necesita inspección. Las mutaciones se preparan primero en memoria, se comparan con los diagnósticos de referencia y se devuelven como planes inmutables vinculados a hash. Nada se escribe hasta que el llamador revisa y aplica explícitamente el plan.

Elegir una herramienta de lectura

• Use ast_get_file cuando la ruta del archivo es conocida y el agente necesita líneas de origen exactas. Es de solo lectura, usa offset basado en cero y limit acotado, devuelve registros de línea basados en uno, un hash de bytes SHA-256, snapshot_state a nivel de archivo y metadatos de freshness del proyecto acotados (fresh, pending, stale, rebuilding o degraded).
• Use ast_get_file con symbols_only: true cuando solo se necesiten selectores y firmas sin cuerpo de un archivo conocido.
• Use ast_explore cuando la pregunta abarque descubrimiento y evidencia. Su resumen predeterminado es acotado; use detail: "context" para origen seleccionado y detail: "full" para origen más referencias del compilador.
• Use ast_get_outline para una vista compacta sin cuerpo de un archivo conocido sin líneas de origen.
• Use ast_get_symbol_source cuando una declaración o implementación sea la evidencia requerida.
• Use ast_get_impact cuando el símbolo exacto sea conocido y se necesiten relaciones directas/transitivas acotadas respaldadas por el compilador; es evidencia de solo lectura, no un plan de mutación.

snapshot_state: "fresh" significa que los bytes del archivo devueltos coinciden con la instantánea del compilador sincronizada. El objeto freshness separado describe el estado del proyecto/sesión y preserva causas como cambios de origen o fallo del observador. Ninguno de los campos significa que el proyecto tenga cero diagnósticos de TypeScript; use ast_get_diagnostics para errores y advertencias del compilador.

Confianza, frescura y completitud

El servidor expone etiquetas de evidencia en lugar de colapsar cada resultado en una puntuación de confianza sin calificar:

Etiqueta	Significado	Uso seguro
provenance: "compiler", confidence: "exact", resolution: "resolved", freshness.state: "fresh"	Una relación resuelta por la instantánea activa del compilador TypeScript. Esta es la única combinación que establece compiler_authoritative: true.	Puede respaldar evidencia de impacto acotada y candidatos de prueba respaldados por el compilador.
provenance: "syntax"	Sintaxis o estructura AST sin resolución semántica de símbolos.	Solo navegación y contexto estructural; no es prueba de que dos símbolos estén relacionados.
provenance: "heuristic"	Una sugerencia basada en convención o nombre.	Solo pistas de descubrimiento; nunca autoridad de mutación ni candidato de prueba respaldado por el compilador.
evidencia de índice	Un acelerador de consultas derivado, no autoridad del compilador. El estado de producción actual informa que el índice está deshabilitado; cualquier índice futuro listo aún requiere validación de selector del compilador y un respaldo del compilador.	Solo enrutamiento más rápido; las entradas obsoletas, faltantes o no coincidentes deben fallar de forma cerrada o recurrir al compilador.

La frescura es ortogonal a los diagnósticos de TypeScript. fresh significa que la evidencia coincide con la instantánea sincronizada; pending, rebuilding, stale o degraded significa que la respuesta no debe presentarse como evidencia actual del compilador. Las herramientas de lectura exponen el estado, las causas (source_change, config_change, index_failure, watcher_failure o compiler_rebuild) y la marca de tiempo checked_at acotada. ast_get_impact rechaza relaciones del compilador no frescas. ast_explore devuelve el estado junto con metadatos completeness, unresolved, budget y truncation en lugar de descartar evidencia silenciosamente.

Todas las lecturas tienen presupuesto. Los llamadores controlan la paginación y, cuando corresponde, max_bytes, reference_limit, max_depth, max_nodes y max_edges; las respuestas informan los límites efectivos y si un límite de registro, byte, profundidad, borde, invocación o serialización truncó el resultado. Un resultado truncado o no resuelto es evidencia incompleta, no un resultado negativo vacío. El resolvedor interno de candidatos de prueba sigue la misma regla: solo acepta impacto fresco y exacto respaldado por el compilador, emite evidencia directa/transitiva e IDs de relación acotados, y nunca ejecuta pruebas ni adivina solo a partir de nombres de archivo.

Por qué esto ayuda

• Menos contexto: el agente recupera la unidad estructural más pequeña que responde la pregunta en lugar de cargar el archivo completo por defecto.
• Cambios más seguros: selección exacta de símbolos, deltas de diagnóstico, comprobaciones de frescura del espacio de trabajo y prepare → review → apply reducen los modos de fallo de la edición de texto ad hoc.
• Operaciones precisas a nivel de proyecto: las referencias y renombrados usan resolución del compilador en lugar de hacer coincidir texto de identificadores con grep.

La edición consciente del AST no es una prueba de que un cambio sea semánticamente correcto. La seguridad proviene de combinar selección estructural con diagnósticos, vistas previas exactas, hashes revisados, comprobaciones de frescura y semántica de aplicación de fallo cerrado.

El benchmark por lotes incluido registra una reducción del 50% en los viajes de ida y vuelta del modelo y una reducción del 94.67% en el contexto serializado para su escenario de búsqueda a origen. El corpus de modelado de resultados registra una reducción del 68.80% en los tokens TOON agregados orientados al modelo mientras preserva los selectores/coordenadas de referencia declarados con las mismas seis llamadas lógicas. El benchmark de formato separado registra un 25.87% en su corpus de colección elegible. El benchmark de flujo de trabajo de contexto verifica la preservación de evidencia y los límites de llamadas para flujos de trabajo de archivo completo, primitivo y ast_explore. Estas son estimaciones locales reproducibles de o200k_base, no afirmaciones universales de tokens, facturación, caché o latencia.

Requisitos

• Node.js 22.13.0 o más reciente
• Corepack con Yarn 4.15.0 (fijado por packageManager)
• Un proyecto objetivo con un tsconfig.json

Entorno compatible y límite de confianza

El candidato de lanzamiento local 0.9.2 requiere Node.js >=22.13.0; su matriz de evidencia apunta a Node.js 22.13.0 exacto y a la línea actual de Node.js 24. La v0.8.1 publicada conserva su evidencia histórica inmutable de Node.js 22.5.0/24. La publicación de archivos de configuración gestionados además requiere GNU coreutils 9.7 mv que admita --update=none-fail, --exchange, --no-copy y --no-target-directory, GNU coreutils ln -L -T, rutas de descriptores procfs en /proc/self/fd y O_DIRECTORY/O_NOFOLLOW. Otras arquitecturas Linux o sistemas sin esos primitivos de sistema de archivos, macOS y Windows siguen sin verificar.

Este es un servidor stdio local. Se ejecuta con los permisos del sistema de archivos del usuario invocador, y los clientes pueden solicitar cualquier project_root al que ese usuario pueda acceder. No proporciona autenticación HTTP, sandboxing, aislamiento de inquilinos ni un límite de seguridad de servicio remoto. La operación remota, no confiable y multiinquilino no es compatible.

En el candidato de lanzamiento local 0.9.2, un AST_SYMBOL_INDEX_PERSISTENCE ausente o un enabled explícito selecciona la caché privada de índice de símbolos SQLite. disabled es la reversión inmediata solo en memoria. canary requiere un AST_SYMBOL_INDEX_CACHE_ROOT normalizado absoluto explícito. Una política o almacenamiento inválido falla de forma cerrada a lecturas de memoria autoritativas del compilador con estado acotado sin rutas.

La raíz de caché predeterminada se selecciona de AST_SYMBOL_INDEX_CACHE_ROOT, luego XDG_CACHE_HOME, luego HOME. Inspeccione o borre solo los artefactos de caché derivados a través del CLI acotado:

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

El borrado requiere confirmación exacta, rechaza artefactos SQLite no seguros o activos y preserva archivos regulares desconocidos. No hay GC automático de caché habilitado. See Support policy para conocer el contrato completo de plataforma, runtime, persistencia y operación. Reporta problemas de seguridad a través de SECURITY.md.

Instalación

Instala el CLI publicado globalmente mientras se mantienen deshabilitados los scripts de ciclo de vida de dependencias:

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

--ignore-scripts evita que las dependencias ejecuten los hooks preinstall, install o postinstall. El paquete y sus dependencias de runtime actuales no requieren esos hooks.

Instalar desde el código fuente

Para compilar el código fuente actual en su lugar:

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

El repositorio fija Yarn 4 y confirma enableScripts: false en .yarnrc.yml. Por lo tanto, los scripts de ciclo de vida de dependencias están deshabilitados durante la instalación; cambiar desde npm sin esta configuración solo cambiaría los logotipos mientras se preserva el riesgo.

El paquete expone dos ejecutables cuando se instala:

• ast-mcp-server: servidor MCP stdio.
• ast-tool: CLI de lote, instalación de habilidades y configuración de agentes.

Configuración guiada del agente

El paquete instalado abre el asistente interactivo con:

ast-tool setup

Desde un checkout del código fuente, usa el script de Yarn; primero compila y luego abre el mismo asistente:

yarn setup

El asistente admite exactamente seis clientes CLI en este orden: Claude Code, Hermes, OpenCode, Codex CLI, Gemini CLI y GitHub Copilot CLI. Cursor, Windsurf, Cline y otros clientes integrados en editores están excluidos intencionalmente. Los clientes compatibles detectados comienzan marcados; los clientes no disponibles o incompatibles están deshabilitados con una razón. Usa Arriba/Abajo para moverte, Espacio para alternar, Enter para enviar o Escape/Ctrl-C para cancelar.

1. verifica previamente el registro MCP ast existente de cada cliente seleccionado, el destino de la habilidad y el destino efectivo de guía gestionada;
2. instala o actualiza de forma segura la habilidad structural-code-editing incluida;
3. agrega un bloque de activación propiedad del marcador a cada superficie de instrucción global verificada mientras preserva todos los bytes propiedad del usuario;
4. registra el servidor MCP de este paquete a través del CLI oficial del agente;
5. reconecta y verifica las herramientas esperadas.

Los registros coincidentes existentes, los archivos de habilidades y los bloques gestionados no se modifican. Los registros MCP conflictivos o la guía gestionada malformada/desconocida fallan antes de cualquier escritura; resuélvelos explícitamente en lugar de dejar que un script de configuración adivine. Las actualizaciones de habilidades son automáticas solo cuando los bytes instalados coinciden con un SHA-256 exacto admitido desde un tarball npm publicado. Los bytes de habilidades desconocidos o personalizados fallan de forma cerrada a menos que --force-skill sea explícito. Ese indicador se aplica solo a la habilidad y no puede anular conflictos de guía, rutas inseguras o carreras de sistema de archivos.

La guía usa el contrato de instrucción global verificado de cada cliente en lugar de un nombre de archivo universal:

Cliente	Destino de guía gestionada
Claude	$CLAUDE_CONFIG_DIR/CLAUDE.md, o ~/.claude/CLAUDE.md
OpenCode	AGENTS.md nativo efectivo; un fallback existente de Claude puede compartirse o preservarse cuando OpenCode no tiene archivo nativo
Codex	$CODEX_HOME/AGENTS.override.md no vacío, de lo contrario $CODEX_HOME/AGENTS.md; CODEX_HOME por defecto es ~/.codex
Gemini	El único context.fileName seguro admitido de ~/.gemini/settings.json, de lo contrario ~/.gemini/GEMINI.md
Hermes	skill_only; la configuración no modifica SOUL.md ni inventa un destino de instrucción global
Copilot	skill_only; la configuración no inventa un destino de instrucción global personal

El rango gestionado está delimitado por los marcadores de inicio/fin ast-tool:structural-code-editing guidance v1. La configuración actualiza solo ese rango, preserva el BOM UTF-8 del archivo, el estilo de nueva línea, el modo y todo el contenido fuera del rango, y rechaza destinos duplicados, parciales, reordenados, desconocidos, con enlaces simbólicos o no regulares. Las escrituras fijan la cadena principal, la preimagen, el inodo temporal retenido y el destino. Los archivos nuevos usan publicación sin clobber vinculada al descriptor; los reemplazos usan un intercambio atómico en el mismo directorio, validan ambas identidades intercambiadas más los bytes y el modo de la preimagen fijada, y revierten el par exacto cuando se detecta una sustitución dentro de la llamada o una edición en el mismo inodo. Cada postimagen completada se reautentica antes de la mutación posterior de activos o MCP. La configuración entre clientes es convergente en lugar de transaccional globalmente.

La salida de configuración exitosa usa el esquema version: 2. Cada agente informa mcp, skill y guidance; las escrituras físicas incluyen un asset de skill, guidance o mcp_config. Una reproducción completa devuelve cada elemento aplicable como unchanged/skill_only y un array physical_writes vacío. Una publicación gestionada fallida separa completed_writes, possibly_committed, rolled_back, rollback_failed y pending; una confirmación incierta o una reversión fallida nunca se informa como intacta y requiere inspección y una nueva planificación.

Para automatización, haz explícitos el conjunto de objetivos y la confirmación:

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

Desde un checkout del código fuente, reemplaza ast-tool con yarn setup en esos comandos.

--agents all se resuelve solo después de la detección y significa cada cliente compatible detectado. Si algún cliente detectado tiene salida desconocida o incompatible, la configuración falla antes de las escrituras. Los IDs explícitos son estrictos y rechazan clientes no disponibles. La configuración no interactiva requiere tanto --agents como --yes.

Se requiere OpenCode 1.18.18 o más reciente. Debido a que opencode mcp add ignora el enrutamiento de configuración personalizado, la configuración actualiza solo mcp.ast en OPENCODE_CONFIG, luego OPENCODE_CONFIG_DIR/opencode.json, luego ~/.config/opencode/opencode.json. Los comentarios JSONC, las claves no relacionadas y el modo de archivo se preservan. El comando de configuración nominalmente diagnóstico de OpenCode normaliza ambos archivos de configuración enrutados, por lo que la configuración ejecuta descubrimiento y verificación contra copias desechables mientras retiene los bytes de configuración seleccionados y falla de forma cerrada si el destino real planificado cambia. La configuración de Gemini puede requerir confiar en la carpeta actual antes del registro. Los diagnósticos usan un ID de correlación y omiten argumentos de comando, entorno, credenciales y salida sin procesar del proveedor; los fallos de configuración pueden incluir una ruta de destino limitada para que el operador pueda inspeccionar una escritura incierta o pendiente.

Instalar la habilidad del agente

El paquete incluye una habilidad structural-code-editing que enseña a un agente cuándo usar las herramientas AST, cómo minimizar el contexto y cómo revisar mutaciones de forma segura. Instálala para Claude Code y Hermes con un comando:

ast-tool install-skill all

O instala un objetivo a la vez:

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

El valor predeterminado es el ámbito de usuario. Escribe en el directorio de habilidades personales de Claude Code y en el HERMES_HOME activo:

Objetivo	Destino
Claude Code	$CLAUDE_CONFIG_DIR/skills/structural-code-editing/SKILL.md, o ~/.claude/skills/... por defecto
Hermes	$HERMES_HOME/skills/software-development/structural-code-editing/SKILL.md, o ~/.hermes/... por defecto
OpenCode, Codex, Gemini, Copilot	~/.agents/skills/structural-code-editing/SKILL.md (una escritura física, cuatro resultados lógicos)

Para confirmar la habilidad en un proyecto para Claude Code, usa el ámbito de proyecto:

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

Esto escribe .claude/skills/structural-code-editing/SKILL.md debajo de ese proyecto. El ámbito de proyecto se rechaza intencionalmente para Hermes porque las habilidades de Hermes pertenecen a un perfil, no a un repositorio fuente.

La instalación es idempotente. Los bytes actuales existentes se dejan intactos; los bytes predecesores exactos admitidos por el manifiesto de procedencia npm incluido se actualizan de forma segura. Los bytes desconocidos o personalizados fallan de forma cerrada a menos que --force sea explícito. install-skill nunca escribe guía global ni configura MCP. Desde un checkout fuente no vinculado, reemplaza ast-tool con yarn node /absolute/path/to/ast-mcp-server/dist/cli.js.

Claude Code detecta cambios en un directorio de habilidades existente en vivo; reinícialo si el directorio de habilidades de nivel superior no existía cuando comenzó la sesión. En Hermes, ejecuta /reload-skills o inicia una nueva sesión, luego verifica con hermes skills list.

install-skill solo instala la habilidad; no configura el transporte MCP. Usa el comando guiado setup para hacer ambos, o completa la configuración MCP específica del cliente a continuación—las instrucciones son útiles, pero aún no han aprendido a abrir un socket stdio mediante pensamiento positivo.

Uso con Claude Code

Claude Code admite servidores MCP stdio locales. Después de compilar este repositorio, registra el servidor con un punto de entrada absoluto:

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

claude mcp get ast debería informar Status: ✔ Connected. El separador -- es obligatorio: todo lo que sigue es el comando del servidor, no una opción de Claude Code.

El ejemplo usa --scope user, que hace que el servidor esté disponible en todos tus proyectos. Usa --scope local en su lugar para registrarlo solo para el proyecto desde el que ejecutas el comando. Evita confirmar un .mcp.json con ámbito de proyecto que contenga la ruta absoluta de checkout de otro desarrollador.

Inicia Claude Code dentro de cualquier proyecto TypeScript con un tsconfig.json:

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

Luego pide a Claude que use las herramientas ast. Por ejemplo:

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

Para un cambio de nombre revisado:

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.

Después de revisar la vista previa:

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

Las herramientas de lectura y preparación con ámbito de proyecto requieren project_root. Claude debe pasar el directorio del proyecto actual o su ruta tsconfig.json explícita. Las llamadas de vista previa y aplicación usan en su lugar las coordenadas de operación preparadas; el servidor MCP en sí no contiene rutas específicas del repositorio.

¿MCP o CLI de lote?

Flujo de trabajo	Interfaz recomendada
Exploración interactiva o una mutación revisada	Herramientas MCP de Claude Code
Un pipeline de lectura de múltiples pasos conocido	ast-tool run pipeline.json a través de Bash
Preparar ahora y aplicar en un proceso posterior	ast-tool run, luego ast-tool apply

Usa /mcp dentro de Claude Code para inspeccionar el estado del servidor y las herramientas. Fuera de la sesión, usa claude mcp list, claude mcp get ast o claude mcp remove ast -s user.

Otros clientes MCP

Hermes Agent:

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

Las herramientas con ámbito de proyecto aceptan project_root, ya sea el directorio del proyecto o una ruta tsconfig.json explícita. El servidor no contiene rutas específicas del repositorio.

Herramientas MCP

Herramienta	Propósito	¿Modifica archivos?
ast_list_files	Inventario paginado de archivos fuente relativo al proyecto	No
ast_get_project_status	Estado de solo lectura del compilador, frescura, índice y operación	No
ast_explore	Selectores compuestos acotados, evidencia de fuente y referencias	No
ast_get_file	Líneas de fuente exactas acotadas, hash de bytes y estado de instantánea	No
ast_get_outline	Firmas de declaración sin cuerpo; metadatos detallados de símbolos opcionales	No
ast_get_symbol_source	Fuente exacta para una declaración	No
ast_search_symbols	Descubrimiento estructural de símbolos paginado	No
ast_find_references	Referencias resueltas por el compilador con contexto acotado	No
ast_get_impact	Evidencia de impacto entrante/saliente acotada respaldada por el compilador	No
ast_get_diagnostics	Diagnósticos de TypeScript a nivel de proyecto o archivo	No
ast_rename_symbol	Preparar un renombrado a nivel de proyecto	No
ast_replace_symbol_body	Preparar un reemplazo solo de cuerpo preservando la firma	No
ast_scaffold_class	Preparar un nuevo archivo de clase con métodos marcadores explícitos	No
ast_get_operation_preview	Recuperar el diff retenido completo para un plan preparado	No
ast_apply_operation	Aplicar un plan revisado y vinculado por hash	Sí

Los resultados de lectura usan rutas relativas al proyecto, orden determinista, salida MCP estructurada y paginación cuando los conjuntos de resultados pueden crecer con el proyecto.

ast_explore admite rutas de consulta, archivo exacto y símbolo exacto. Su perfil summary predeterminado devuelve selectores reutilizables acotados; context agrega fuente seleccionada y full agrega referencias del compilador. Cada respuesta informa frescura, completitud, truncamiento, selectores no resueltos, límites de registros y un presupuesto de bytes serializados. Use las herramientas primitivas cuando una sola operación exacta sea más clara o al preparar una mutación.

La búsqueda de símbolos está ordenada por relevancia y por defecto devuelve como máximo 20 registros summary que contienen file, un selector directamente reutilizable, kind y signature sin cuerpo. Solicite detail: "selectors" solo para coordenadas de enrutamiento, o detail: "full", limit: 100 para los campos/página v0.4.0. Las referencias por defecto son detail: "locations"; solicite detail: "context" solo cuando se necesite la línea de fuente acotada.

Resultados TOON opcionales

ast_search_symbols, ast_find_references, ast_get_impact y ast_get_diagnostics aceptan output_format: "toon" para resultados con muchas colecciones consumidos directamente por un modelo. JSON sigue siendo el predeterminado y preserva el objeto estructurado canónico.

MCP TOON se devuelve una vez como contenido estructurado con la forma de { "format": "toon", "data": "..." }; data es el documento TOON sin pérdidas. El resultado JSON completo no se duplica. Estas cuatro herramientas validan su resultado Zod canónico y verifican un viaje de ida y vuelta de igualdad profunda de codificación/decodificación antes de la presentación, pero no anuncian un único outputSchema de MCP porque su contenido estructurado exitoso tiene dos representaciones.

No solicite TOON para fuente, esquemas, listas de archivos, vistas previas o resultados de mutación. Los controles negativos verificados muestran que el envoltorio MCP hace esas formas más grandes. TOON es una optimización explícita específica de forma, no un nuevo dialecto para cada objeto a la vista.

CLI por lotes

ast-tool permite que Claude Code y otros clientes con capacidad Bash colapsen un pipeline estructural conocido en una sola llamada 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 -

Ejemplo de pipeline de búsqueda a fuente:

{
  "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" }
}

Un $ref es un puntero JSON RFC 6901 enraizado en los resultados de pasos anteriores. Las referencias no pueden apuntar hacia adelante. Si emit se omite, solo se devuelve el resultado del paso final; los resultados intermedios permanecen dentro del proceso.

Foreach acotado

{
  "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 acepta un puntero vacío para el elemento completo o /field para un campo. Foreach es de solo lectura, preserva el orden, falla rápido y tiene concurrencia acotada.

Límites del lote

• Documento de entrada: 1 MiB.
• Pasos: 50.
• Invocaciones totales de herramientas: 500.
• Elementos foreach por paso: 200.
• Concurrencia de lectura: 4 por defecto, máximo 16.
• Cada resultado de paso retenido y salida serializada final: 10 MiB.
• Contexto intermedio total retenido: 50 MiB.
• Una raíz de proyecto por pipeline.
• Sin ramas, eval, JavaScript incrustado, bucles while o transformaciones arbitrarias.

El éxito es un valor JSON compacto en stdout por defecto. ast-tool run --output-format toon escribe un documento TOON plano para un lote de solo lectura; los pasos internos permanecen como JSON estructurado, y los lotes de preparación rechazan TOON antes de la ejecución. Los fallos de codificación y límite de salida no escriben stdout parcial y usan códigos ENCODING_ERROR o OUTPUT_LIMIT estables. Los errores son siempre JSON estructurado en stderr. El código de salida 0 es éxito, 1 es fallo de ejecución/aplicación y 2 es fallo de uso o esquema.

Mutaciones revisadas

Proceso MCP

El renombrado, el reemplazo de cuerpo y el andamiaje de clase nunca escriben directamente durante la preparación:

1. Llame a ast_rename_symbol, ast_replace_symbol_body o ast_scaffold_class.
2. Revise el delta de diagnóstico, los archivos afectados, blocked y plan_hash.
3. Obtenga los diffs completos con ast_get_operation_preview cuando sea necesario.
4. Llame a ast_apply_operation con ambos operation_id y plan_hash.

Los planes MCP viven en un almacén en memoria acotado y no sobreviven a un reinicio del servidor.

ast_scaffold_class acepta importaciones estructuradas, herencia, decoradores, propiedades de parámetros de constructor, propiedades inicializadas y una o más firmas de método. Crea una vista previa en memoria para un objetivo .ts/.tsx ausente relativo al proyecto. Cada método generado contiene inicialmente solo throw new Error("Not implemented: Class.method"). Revise el diff de creación y los diagnósticos de /dev/null, aplique el andamiaje y luego reemplace cada cuerpo de método pendiente con ast_replace_symbol_body. Los objetivos existentes y los padres simbólicos/transversales fallan de forma cerrada.

Límite del proceso CLI

Un lote puede contener como máximo una operación de preparación. Debe ser el paso final y no puede usar foreach. ast_apply_operation y las llamadas de vista previa arbitrarias están prohibidas dentro de los documentos de lote.

Una preparación CLI escribe un plan privado exacto y devuelve operation_id, plan_hash y plan_file de nivel superior incluso cuando emit los omite:

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

El directorio de planes predeterminado es:

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

Establezca AST_TOOL_STATE_DIR para aislarlo. Los directorios tienen modo 0700; los planes tienen modo 0600, se reemplazan atómicamente, tienen tamaño acotado, versionado y expiran con la operación preparada. Los archivos de plan contienen bytes de fuente propuestos exactos y deben tratarse como código privado.

Aplicar carga las postimágenes retenidas exactas, requiere el hash revisado suministrado por separado, valida los hashes de bytes serializados y las rutas contenidas, vuelve a verificar el espacio de trabajo completo de fuente/configuración, organiza las escrituras, verifica las postimágenes y persiste un recibo de aplicación dentro del mismo bloqueo de espacio de trabajo cooperativo. Una invocación CLI posterior puede reproducir ese recibo de forma idempotente, incluso después del TTL de preparación.

Límite de garantía

El servidor no reclama una transacción a nivel de sistema de archivos:

• El reemplazo es atómico por archivo donde el sistema de archivos local proporciona renombrado atómico.
• Una aplicación de múltiples archivos tiene un intervalo corto en el que algunos reemplazos ya pueden ser visibles.
• La reversión es de mejor esfuerzo y se niega a sobrescribir un archivo cambiado por otro escritor después del reemplazo.
• La aplicación MCP y CLI comparten un bloqueo de sistema de archivos de fallo cerrado claveado por tsconfig.json canónico cuando usan el mismo directorio de estado. No coordina editores, escritores NFS o procesos externos hostiles.
• La persistencia del recibo se ejecuta antes de que se libere ese bloqueo. Si el almacenamiento del recibo falla después del reemplazo de fuente, la aplicación sale con código distinto de cero e informa que las postimágenes verificadas pueden estar presentes; el reintento recupera el recibo solo cuando el espacio de trabajo completo coincide exactamente con la huella posterior al trabajo revisada.
• Un bloqueo duro del proceso puede dejar un bloqueo obsoleto. Elimínelo solo después de inspeccionar sus metadatos y demostrar que no hay ninguna aplicación en ejecución; las postimágenes completas exactas pueden entonces recuperar el recibo, mientras que el estado parcial o divergente sigue siendo un conflicto.
• El soporte de codificación de fuente es UTF-8, con o sin BOM. Las codificaciones no compatibles se rechazan.

Puertas de desarrollo

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 ejercita el servidor stdio construido. test:cli ejecuta un pipeline de lectura y un flujo de trabajo de preparar/aplicar/reproducir en procesos Node separados. test:installed-agents es una puerta manual dependiente del host: primero construye, detecta clientes compatibles instalados localmente, usa solo hogares/raíces de configuración desechables, verifica el descubrimiento efectivo determinista sin llamadas de modelo, informa clientes no disponibles y elimina el estado desechable. No es un requisito de CI portátil porque CI no instala cada cliente externo.

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

El benchmark de lotes compara dos llamadas de cliente separadas con una invocación de lote en procesos Node nuevos, registrando viajes de ida y vuelta del modelo, invocaciones reales de herramientas, tiempo de pared, RSS máximo y recuentos de caracteres serializados. Los recuentos de caracteres no son estimaciones de tokens específicas del modelo.

El benchmark de formato ejecuta herramientas reales contra este repositorio más accesorios de referencia/diagnóstico deterministas. Verifica la igualdad JSON→TOON→valor, bytes UTF-8, estimaciones gpt-tokenizer o200k_base, latencia de codificación/decodificación, el envoltorio MCP real, metadatos de herramientas y controles negativos. Su resultado verificado es benchmark/results/self-formats.json; las estimaciones locales del tokenizador no establecen facturación del proveedor ni ahorros de caché. Consulte benchmark/README.md para metodología y limitaciones.

El benchmark de modelado de resultados compara los perfiles full/100/context compatibles con v0.4.0 con los nuevos valores predeterminados públicos en tareas de nombre exacto, ruta exacta, prefijo, subcadena amplia y referencia de múltiples archivos. Falla en evidencia faltante, llamadas requeridas adicionales, menos de la superficie de herramienta mínima requerida por el benchmark o menos del 35% de reducción agregada de tokens TOON. Su resultado verificado es benchmark/results/self-result-shapes.json.

Alcance

• Proyectos TypeScript y JavaScript entendidos por el compilador de TypeScript.
• Renombrado estructural, reemplazo de cuerpo invocable y creación revisada de un andamiaje de clase.
• Pipelines declarativos tipo DAG con referencias a resultados anteriores y foreach acotado.
• Sin migración arbitraria de firmas, creación/eliminación general de archivos, refactorizaciones entre lenguajes o lenguaje de scripting de propósito general.