AST MCP SERVER

ast-mcp-server

ast-mcp-server brinda a los agentes de codificación acceso consciente de tipos y compacto a proyectos de TypeScript y JavaScript. Utiliza el modelo de proyecto real del compilador a través de ts-morph, por lo 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 están acotadas y estructuradas. Las escrituras siguen un protocolo explícito de prepare → review → apply con hashes inmutables, verificaciones 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 brinda al agente herramientas de código estructural además de lecturas y escrituras genéricas de archivos. Internamente, ts-morph utiliza el modelo de proyecto del compilador de TypeScript, por lo 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 código fuente seleccionadas exactas, hashes y frescura acotada
Explorar contexto acotado	ast_explore	Selectores clasificados más código fuente y referencias opcionales
Entender un archivo	ast_get_outline	Firmas sin cuerpos de implementación
Inspeccionar una declaración	ast_get_symbol_source	Código fuente exacto para una función, método, clase o tipo
Encontrar usos en todo el proyecto	ast_find_references	Ubicaciones de referencias resueltas por el compilador
Entender el impacto de un símbolo	ast_get_impact	Relaciones acotadas directas/transitivas respaldadas por el compilador
Seleccionar pruebas afectadas	ast_find_test_candidates	Pruebas candidatas completas a partir de relaciones entrantes del 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 o código fuente 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 se conoce la ruta del archivo y el agente necesita líneas de código fuente exactas. Es de solo lectura, usa offset de base cero y limit acotado, devuelve registros de líneas de base 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 está acotado; use detail: "context" para código fuente seleccionado y detail: "full" para código fuente más referencias del compilador.
• Use ast_get_outline para una vista compacta sin cuerpo de un archivo conocido sin líneas de código fuente.
• Use ast_get_symbol_source cuando una declaración o implementación sea la evidencia requerida.
• Use ast_get_impact cuando se conozca el símbolo exacto y se necesiten relaciones directas/transitivas acotadas del compilador. Verifique coverage, work, truncation, incomplete y proven_empty; esto es evidencia de solo lectura, no un plan de mutación.
• Use ast_find_test_candidates cuando un símbolo exacto deba mapearse a pruebas conservadoras. Solo admite evidencia entrante completa de reference, import, export, extends, implements y call, devuelve rutas completas y nunca ejecuta pruebas.

snapshot_state: "fresh" significa que los bytes del archivo devuelto coinciden con la instantánea sincronizada del compilador. El objeto separado freshness describe el estado del proyecto/sesión y preserva causas como cambios en el código fuente o falla 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 de 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 sugerencias 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 valor predeterminado de producción usa SQLite nativo cuando no hay persistencia o enabled; cada selector indexado aún requiere validación del compilador y un respaldo del compilador.	Solo enrutamiento más rápido; las entradas obsoletas, faltantes o no coincidentes deben fallar de manera 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 acotada de checked_at. ast_get_impact rechaza relaciones del compilador no frescas. ast_explore devuelve el estado junto con metadatos de 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. Una detención acotada es evidencia incompleta, no un resultado negativo vacío.

El impacto tiene dos canales de completitud independientes:

Canal	Evidencia	Incompleto cuando
Cobertura semántica	Una celda canónica por tipo solicitado, dirección y clase de punto final: not_applicable, completed, unsupported o unfinished	Cualquier celda aplicable es unsupported o unfinished
Recorrido/trabajo	truncation más work.work_limit_reached y sus contadores	Un límite de profundidad/nodo/borde/trabajo impide la finalización

incomplete es verdadero cuando cualquiera de los canales está incompleto. proven_empty es verdadero solo cuando hay cero bordes, cada celda aplicable se completó y no se agotó ningún límite. La solicitud pública de impacto de siete tipos/predeterminada incluye contains; como no existe un productor de contains con ámbito, la contención predeterminada o explícita aplicable es unsupported, por lo que el resultado es incompleto incluso cuando el recorrido no se truncó.

ast_find_test_candidates excluye deliberadamente contains y fija el ámbito de admisión a seis tipos entrantes: reference, import, export, extends, implements y call. Devuelve INCOMPLETE_EVIDENCE antes de la paginación para evidencia obsoleta, inexacta, no resuelta, truncada, con trabajo agotado, no admitida o no terminada. Solo la autoridad completa de seis tipos puede devolver candidates: [] con completeness.proven_empty: true; la paginación divide candidatos deterministas mientras cada prueba y los metadatos de coverage, work y recorrido sin paginar permanecen completos.

Estos campos son aditivos: las formas de borde existentes, las cadenas de tipo, los valores predeterminados y los errores públicos permanecen estables. El JSON de MCP ast_get_impact y TOON representan el mismo resultado lógico de cobertura/trabajo; la salida candidata de MCP sigue siendo JSON canónico, mientras que la salida por lotes de solo lectura puede codificar ese mismo resultado candidato como TOON. El despacho de propiedades, elementos, dinámicos, claves computadas y alternativas externas permanece sin bordes y sin terminar: este contrato no certifica los clasificadores diferidos #219 o #220.

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, verificaciones de frescura del espacio de trabajo y prepare → review → apply reducen los modos de falla 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 la selección estructural con diagnósticos, vistas previas exactas, hashes revisados, comprobaciones de frescura y semántica de aplicación con cierre ante fallos.

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 fuente. El corpus de modelado de resultados registra una reducción del 68.80% en los tokens TOON agregados orientados al modelo, preservando 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 del flujo de trabajo de contexto verifica la preservación de evidencia y los límites de llamadas para flujos de trabajo de archivo completo, primitivos y ast_explore. Estas son estimaciones locales reproducibles de o200k_base, no afirmaciones universales sobre 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

La versión publicada v0.12.0 requiere Node.js >=22.13.0; su matriz de evidencia inmutable apunta a Node.js 22.13.0 exacto y a la línea actual de Node.js 24. La aplicación estructural y la publicación administrada de archivos de configuración se verifican solo en Linux x64 con GNU coreutils 9.7 mv compatible con --update=none-fail, --exchange, --no-copy y --no-target-directory, GNU coreutils ln -L -T, rutas de descriptores procfs en /proc/self/fd, O_DIRECTORY/O_NOFOLLOW, y un sistema de archivos de destino que pase la sonda de identidad de enlace/intercambio propiedad. Una primitiva denegada o fallida bloquea la mutación antes de los efectos en la fuente; no hay respaldo de renombrado, copia/eliminación o solo nombre de ruta. Otras arquitecturas Linux o sistemas sin esta matriz completa, macOS y Windows permanecen sin verificar.

Este es un servidor stdio local. Se ejecuta con los permisos del sistema de archivos del usuario que lo invoca, 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.

Trabajador compilador supervisado opcional

El compilador se ejecuta en proceso por defecto. Los operadores de Linux pueden mantener explícitamente conectado el padre stdio mientras permiten que un hijo compilador inactivo salga y se reactive de forma diferida:

AST_COMPILER_WORKER_MODE=supervised ast-mcp-server

El padre espera la preparación del hijo antes de reproducir el estado de inicialización limitado. Las solicitudes y cancelaciones permanecen afines a la generación; el historial de mutaciones, los arrendamientos de operaciones en vivo y el trabajo de aplicación crítico para la finalización evitan el reciclaje inseguro. Establezca AST_COMPILER_WORKER_MODE=in_process para la reversión completa, o establezca AST_COMPILER_WORKER_IDLE_TTL_MS=0 para conservar el relé mientras se desactiva el reciclaje inactivo.

El canario Linux limitado pasó en Node.js 22.13.0 exacto y Node.js 24 con recuperación de PSS repetible, huellas digitales de compilador estables, reutilización de SQLite sin cambios, diagnósticos redactados limitados y sin huérfanos después de la muerte del padre. Esto es un hijo por conexión, no un demonio compartido, un grupo o un nuevo valor predeterminado. Consulte ADR 0014.

En la versión publicada v0.12.0, 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 se cierra ante fallos a lecturas de memoria autoritativas del compilador con estado limitado sin rutas.

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

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

La limpieza requiere confirmación exacta, rechaza artefactos SQLite inseguros o activos y preserva archivos regulares desconocidos. No hay GC automático de caché habilitado.

Consulte Política de soporte para el contrato completo de plataforma, tiempo de ejecución, persistencia y operación. Reporte problemas de seguridad a través de SECURITY.md.

Instalación

Instale la CLI publicada globalmente mientras mantiene 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 hooks de preinstall, install o postinstall. El paquete y sus dependencias de tiempo de ejecución actuales no requieren esos hooks.

Instalar desde la fuente

Para compilar la 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 de 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 stdio MCP.
• ast-tool: CLI de lote, instalación de habilidades y configuración de agente.

Diagnosticar la instalación activa

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

Doctor reutiliza el descubrimiento de proyectos CLI y las autoridades de tiempo de ejecución existentes sin cambiar el estado del proyecto, agente, paquete o habilidad. Imprime JSON limitado; la salida 0 es saludable, 1 degradada y 2 fallida. Un compilador saludable sigue siendo utilizable cuando solo el índice SQLite derivado está degradado. El diagnóstico independiente marca la evidencia de índice y cola solo de sesión registrada como not_run en lugar de fabricar un estado saludable.

Actualizar un paquete instalado

Inspeccione la instalación global activa sin escribir, o actualícela inmediatamente:

ast-tool upgrade --check
ast-tool upgrade

La actualización admite solo un paquete directo que se demuestre que pertenece al prefijo global npm activo o a Volta. Rechaza instalaciones vinculadas/fuente y ambiguas, nunca usa sudo, adivina desde PATH o acepta --yes. npm ejecuta su npm-cli.js probado a través del Node activo con scripts de ciclo de vida deshabilitados y una copia desechable de caché/configuración; la limpieza se verifica y bloquea el éxito si no se puede probar la ausencia. Volta usa su integración nativa. La CLI actualizada luego reconcilia la configuración administrada a través de ese Node. Los bytes de habilidades personalizados permanecen intactos y producen ast-tool setup --agents all --yes --force-skill. Reinicie los clientes MCP después de cualquier actualización de paquete; un servidor ya en ejecución no cambia en su lugar.

Configuración guiada del agente

El paquete instalado abre el asistente interactivo con:

ast-tool setup

Desde un checkout de la fuente, use el script de Yarn; compila primero 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. Use Arriba/Abajo para moverse, Espacio para alternar, Enter para enviar, o Escape/Ctrl-C para cancelar.

1. preverifica el registro MCP ast existente de cada cliente seleccionado, el destino de habilidades y el destino efectivo de guía administrada;
2. instala o actualiza de forma segura la habilidad structural-code-editing incluida;
3. agrega un bloque de activación propiedad de 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 de la CLI oficial del agente;
5. reconecta y verifica las herramientas esperadas.

Los registros coincidentes existentes, archivos de habilidades y bloques administrados no se modifican. Los registros MCP conflictivos o la guía administrada malformada/desconocida fallan antes de cualquier escritura; resuélvalos 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 de un tarball npm publicado. Los bytes de habilidades desconocidos o personalizados se cierran ante fallos a menos que --force-skill sea explícito. Esa bandera se aplica solo a la habilidad y no puede anular conflictos de guía, rutas inseguras o carreras del 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 administrada
Claude	$CLAUDE_CONFIG_DIR/CLAUDE.md, o ~/.claude/CLAUDE.md
OpenCode	AGENTS.md nativo efectivo; un respaldo 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 a ~/.codex
Gemini	El único context.fileName seguro compatible 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 administrado está delimitado por 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 enlace simbólico 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 a descriptores; los reemplazos usan un intercambio atómico en el mismo directorio, validan ambas identidades intercambiadas más los bytes de preimagen y el modo fijados, y revierten el par exacto cuando se detecta una sustitución dentro de la llamada o una edición del 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 una matriz physical_writes vacía. Una publicación administrada 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 un nuevo replan.

Para automatización, haga explícito el conjunto objetivo y la confirmación:

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

Desde un checkout de la fuente, reemplace 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 cualquier 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 de 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 se cierra ante fallos 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; las fallas 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 las mutaciones de forma segura. Instálela 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 personal de habilidades 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/... de forma predeterminada
Hermes	$HERMES_HOME/skills/software-development/structural-code-editing/SKILL.md, o ~/.hermes/... de forma predeterminada
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 orientación global ni configura MCP. Desde una copia de trabajo fuente no vinculada, 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 ambas cosas, 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 --env AST_MCP_APPLY_GUARD=allow --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, lo 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 copia de trabajo 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 renombrado 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 actual del proyecto o su ruta explícita tsconfig.json. 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 por lotes?

Flujo de trabajo	Interfaz recomendada
Exploración interactiva o una mutación revisada	Herramientas MCP de Claude Code
Un pipeline de lectura de varios 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

Agente Hermes:

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

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

Arnés DeepSeek (Vista previa para desarrolladores)

Un adaptador delgado se incluye dentro de este paquete: cordis.patch.yml monta el comando stdio empaquetado ast-mcp-server a través del puente oficial @deepseek-ai/dsh-mcp-client, declarado a través de exactamente "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }. Esta es una vista previa para desarrolladores contra una revisión del Arnés fijada, compilada desde fuente (dsh-v0.1.2-alpha.1 en cd5ef8148158c3a752a658978873241fdf8e2bbc). El paquete publicado ast-mcp-server@0.13.0 es la línea base de compatibilidad:

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

Para un candidato local, empaqueta e instala su tarball en su lugar:

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

La primera superficie compatible es lecturas + preparación + vista previa. Cada ruta de aplicación está denegada por una protección de fallo cerrado: ast_apply_operation no está registrado a menos que AST_MCP_APPLY_GUARD=allow esté establecido explícitamente (el parche incluido en su lugar fija deny, por lo que la superficie del Arnés permanece denegada por defecto; un valor no establecido o inválido también deniega). El adaptador también establece AST_MCP_TEXT_PROJECTION=canonical_json: los resultados estructurados exitosos conservan su structuredContent sin pérdida y ganan texto JSON canónico solo cuando el texto MCP ordinario está vacío, porque el presentador nativo fijado de otro modo expone solo un marcador de resultado vacío no útil. La proyección es específica del adaptador, nunca reemplaza el texto existente, e informa un marcador explícito de límite de tamaño cuando el marco supervisado completo tiene espacio. Si incluso el resultado solo estructurado sin cambios excede el marco de trabajo del trabajador existente, el modo supervisado falla de forma cerrada en lugar de truncarlo o corromperlo. Las brechas ascendentes conocidas siguen siendo no autoritativas: el puente oficial elimina las anotaciones de herramientas MCP (readOnlyHint/destructiveHint) y lanza el hijo stdio fuera del sandbox del Arnés.

yarn test:dsh-adapter es la verificación obligatoria. Vincula la integridad pública de npm 0.13.0, empaqueta el candidato, compila el Arnés y el puente fijados desde fuente, y prueba tools.mode: native, el catálogo con ámbito de 15 herramientas, esquemas de entrada ejecutables completos, lectura/preparación/vista previa, las tres combinaciones inválidas de ast_explore, ausencia de aplicación y aplicación directa rechazada. La puerta de esquema congela el contrato público vacío de ast_explore como ROJO, requiere que el candidato las definiciones de registro/nativas coincidan, y hashea los 14 esquemas de modelo no afectados. Un modelo determinista de dos pasos luego invoca mcp__ast__ast_get_project_status a través de un Agente/Sesión headless real: la línea base pública debe reproducir el marcador de resultado vacío, mientras que el candidato corregido debe entregar JSON canónico sin pérdida a la siguiente solicitud del modelo, el tool/result duradero, y una reanudación/reproducción de Agente en frío reconstruida desde la persistencia. El smoke elimina y lee de nuevo su estado de perfil/espacio de trabajo desechable y falla (nunca omite) en una discrepancia de identidad, requisito previo faltante, fuga de ciclo de vida o brecha de evidencia.

Herramientas MCP

Herramienta	Propósito	Muta archivos
ast_list_files	Inventario de archivos fuente relativo al proyecto paginado	No
ast_get_project_status	Estado de compilador, frescura, índice y operación de solo lectura	No
ast_explore	Selectores compuestos acotados, evidencia fuente y referencias	No
ast_get_file	Líneas fuente exactas acotadas, hash de bytes y estado de instantánea	No
ast_get_outline	Firmas de declaración sin cuerpo; metadatos de símbolo detallados son opcionales	No
ast_get_symbol_source	Fuente exacta para una declaración	No
ast_search_symbols	Descubrimiento de símbolos estructurales paginado	No
ast_find_references	Referencias resueltas por compilador con contexto acotado	No
ast_get_impact	Evidencia de impacto entrante/saliente acotada respaldada por compilador	No
ast_find_test_candidates	Pruebas afectadas paginadas con pruebas de relación atómica de compilador	No
ast_get_diagnostics	Diagnósticos TypeScript con ámbito de proyecto o archivo	No
ast_rename_symbol	Preparar un renombrado en todo el 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 de marcador de posición 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 donde los conjuntos de resultados pueden crecer con el proyecto.

Agregados de diagnóstico

Establece include_aggregates: true en ast_get_diagnostics para resumir la instantánea de diagnóstico normalizada completa independientemente de la página cruda seleccionada. La opción predeterminada es false; las respuestas deshabilitadas omiten aggregates y mantienen la forma existente.

Cada dimensión de código y archivo devuelve como máximo 20 grupos clasificados. groups.length + omitted_group_count = total_group_count, y sum(groups[*].count) = covered_diagnostic_count. La cobertura de código más omitted_diagnostic_count equivale al total de diagnóstico; la cobertura de archivos también agrega unfiled_diagnostic_count. Los grupos de archivos contienen solo rutas normalizadas relativas al proyecto, pero pueden revelar una ruta ausente de la página cruda seleccionada.

ast_explore admite rutas de consulta, archivo exacto y símbolo exacto. Su perfil predeterminado summary devuelve selectores reutilizables acotados; context agrega fuente seleccionada y full agrega referencias de compilador. Los clústeres de símbolos completos se admiten bajo el techo max_bytes del llamador, por lo que la fuente, los registros de referencia y las rutas de llamada nunca se dividen. omissions clasifica los componentes retenidos como budget, incomplete o untrusted, y cualquier omisión solicitada mantiene la completitud falsa.

Exacto file_path más symbol_path las solicitudes pueden optar por call_spines estático acotado. Solo los sitios de invocación frescos, exactos y resueltos por compilador califican; las referencias genéricas, el despacho dinámico y el comportamiento en tiempo de ejecución no se infieren. La ausencia de call_spines no realiza recorrido de llamadas. Cada respuesta aún informa frescura, completitud, truncamiento, selectores no resueltos, límites de registros y contabilidad canónica de bytes serializados. Usa las herramientas primitivas cuando una sola operación exacta es más clara o al preparar una mutación. Consulta ADR 0013.

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

Resultados TOON opcionales

ast_search_symbols, ast_find_references, ast_get_impact y ast_get_diagnostics aceptan output_format: "toon" para resultados de recopilación intensiva 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 forma de { "format": "toon", "data": "..." }; data es el documento TOON sin pérdida. 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 solo outputSchema MCP porque su contenido estructurado exitoso tiene dos representaciones. No solicites TOON para fuente, esquemas, listas de archivos, vistas previas o resultados de mutación. Los controles negativos verificados muestran que el envoltorio MCP hace que esas formas sean 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 JSON Pointer RFC 6901 enraizado en los resultados de pasos anteriores. Las referencias no pueden apuntar hacia adelante. Si se omite emit, solo se devuelve el resultado del paso final; los resultados intermedios permanecen dentro del proceso.

Solo para lotes CLI, omita project_root o proporcione un directorio para seleccionar el tsconfig.json o jsconfig.json más cercano desde el directorio de invocación hacia arriba. Un archivo de configuración explícito siempre gana. El descubrimiento se detiene en un .git o límite del sistema de archivos y rechaza ambigüedad de mismo nivel o identidades con enlaces simbólicos; las llamadas a herramientas MCP aún requieren un project_root explícito.

ast_find_test_candidates y ast_explore se admiten como pasos de lectura. El ejecutor de lotes inyecta el project_root del pipeline, rechaza una raíz de paso conflictiva e invoca la misma implementación MCP registrada. Las pruebas de relaciones candidatas y los clústeres de exploración permanecen intactos; el JSON final y TOON difieren solo en serialización, no en evidencia lógica.

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 de lote

• Documento de entrada: 1 MiB.
• Pasos: 50.
• Invocaciones totales de herramientas: 500.
• Elementos foreach por paso: 200.
• Concurrencia de lectura: predeterminada 4, máxima 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 ni 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 estables ENCODING_ERROR o OUTPUT_LIMIT. 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

Renombrado, reemplazo de cuerpo y 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 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 llamadas de vista previa arbitrarias están prohibidas dentro de 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 plan 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 escrituras por etapas, verifica las postimágenes y persiste un recibo de aplicación dentro del mismo bloqueo cooperativo del espacio de trabajo. 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 ni seguridad contra un escritor que muta continuamente:

• Cada reemplazo intercambia y autentica un par escenificado/destino. La aplicación de múltiples archivos sigue siendo secuencial, por lo que las postimágenes anteriores pueden ser visibles antes de que se confirmen archivos posteriores.
• El rollback inverso restaura solo un par exacto propiedad de la operación. La pérdida de propiedad preserva las entradas observables y devuelve AMBIGUOUS_APPLY; nunca recurre al reemplazo por nombre de ruta.
• La creación es sin sobrescritura. Una vez que un inodo creado se publica, un fallo posterior no puede inferir de manera segura la propiedad de desvinculación, por lo que el destino y la etapa oculta se preservan y el rollback falla de forma cerrada como ambiguo.
• MCP y CLI apply 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, escritores que usan otra configuración ni procesos externos hostiles.
• Las barreras de promesa deterministas prueban las intercalaciones de publicación/rollback probadas. Son una costura de prueba de límite de amenaza, no una garantía de atomicidad global o escritor continuo.
• 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, apply sale con código no 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 post-espacio de trabajo revisada.
• Un bloqueo duro del proceso puede dejar un bloqueo obsoleto. Elimínelo solo después de inspeccionar sus metadatos y probar que no se está ejecutando ningún apply; 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

Agregar o cambiar una herramienta MCP

Mantenga esquemas, metadatos, anotaciones, manejadores, errores y serialización en el módulo de la herramienta. Exporte un descriptor congelado, agréguelo al orden intencional en src/tools/catalog.ts y declare solo hechos de efecto estático, lote, compatibilidad y formato directo. No agregue estado de solicitud, descubrimiento dinámico, invocación por nombre o un ejecutor genérico al catálogo.

Actualice los inventarios independientes de tools/list solo después de revisar los metadatos de cable completos; no deben importar ni derivar expectativas del catálogo. Luego ejecute el catálogo enfocado y las pruebas de integración MCP más las puertas de tiempo de ejecución, paquete y habilidad gestionada a continuación.

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 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: construye primero, 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 idas y vueltas de 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 fixtures de referencia/diagnóstico deterministas. Verifica igualdad JSON→TOON→valor, bytes UTF-8, estimaciones de 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 de 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 mínima de herramientas 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 comprendidos por el compilador 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 ni lenguaje de scripting de propósito general.