ast-mcp-server 0.3.0

package/dist/tools/list_files.js

@@ -0,0 +1,51 @@
+import path from "node:path";
+import { z } from "zod";
+import { PaginationInputSchema, PaginationOutputSchema, paginate } from "../services/pagination.js";
+import { withProject } from "../services/project.js";
+import { errorResult, structuredResult } from "./result.js";
+const AstListFilesInputSchema = z.object({
+    project_root: z
+        .string()
+        .describe("Absolute project directory containing tsconfig.json, or the config path."),
+    glob_filter: z
+        .string()
+        .optional()
+        .describe("Optional case-insensitive substring used to filter project-relative paths."),
+    ...PaginationInputSchema,
+});
+const AstListFilesOutputSchema = z.object({
+    files: z.array(z.string()),
+    ...PaginationOutputSchema,
+});
+export function registerListFiles(server) {
+    server.registerTool("ast_list_files", {
+        title: "List TypeScript/JavaScript project files",
+        description: "Lists source files included by the project's tsconfig in deterministic, project-relative, paginated form.",
+        inputSchema: AstListFilesInputSchema,
+        outputSchema: AstListFilesOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ project_root, glob_filter, offset, limit }) => {
+        try {
+            const output = await withProject(project_root, ({ project, projectRoot }) => {
+                const filter = glob_filter?.toLowerCase();
+                const files = project
+                    .getSourceFiles()
+                    .map((sourceFile) => path.relative(projectRoot, sourceFile.getFilePath()))
+                    .filter((file) => !filter || file.toLowerCase().includes(filter))
+                    .sort((left, right) => left.localeCompare(right));
+                const page = paginate(files, offset, limit);
+                const { items, ...metadata } = page;
+                return { files: items, ...metadata };
+            });
+            return structuredResult(output);
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+}

package/dist/tools/operation-schema.js

@@ -0,0 +1,64 @@
+import { z } from "zod";
+export const NormalizedDiagnosticSchema = z.object({
+    code: z.number().int(),
+    category: z.string(),
+    file: z.string().nullable(),
+    line: z.number().int().positive().nullable(),
+    column: z.number().int().positive().nullable(),
+    message: z.string(),
+});
+export const PreparedOperationOutputSchema = z.object({
+    operation_id: z.string().uuid(),
+    plan_hash: z.string().length(64),
+    kind: z.enum(["rename_symbol", "replace_symbol_body"]),
+    status: z.literal("prepared"),
+    project_root: z.string(),
+    created_at: z.string(),
+    expires_at: z.string(),
+    affected_files: z.array(z.object({
+        file: z.string(),
+        original_hash: z.string(),
+        updated_hash: z.string(),
+    })),
+    reference_count: z.number().int().min(0),
+    workspace_hash: z.string().length(64),
+    workspace_file_count: z.number().int().positive(),
+    diagnostics: z.object({
+        added: z.array(NormalizedDiagnosticSchema),
+        removed: z.array(NormalizedDiagnosticSchema),
+        added_errors: z.array(NormalizedDiagnosticSchema),
+    }),
+    allow_new_errors: z.boolean(),
+    blocked: z.boolean(),
+    block_reason: z.string().nullable(),
+    preview: z.string().nullable(),
+    preview_truncated: z.boolean(),
+});
+export function serializePreparedOperation(operation) {
+    if (operation.status !== "prepared") {
+        throw new Error(`Operation ${operation.operation_id} is not in prepared state.`);
+    }
+    return {
+        operation_id: operation.operation_id,
+        plan_hash: operation.plan_hash,
+        kind: operation.kind,
+        status: "prepared",
+        project_root: operation.project_root,
+        created_at: operation.created_at,
+        expires_at: operation.expires_at,
+        affected_files: operation.affected_files,
+        reference_count: operation.reference_count,
+        workspace_hash: operation.workspace_hash,
+        workspace_file_count: operation.workspace_file_count,
+        diagnostics: {
+            added: operation.diagnostics.added,
+            removed: operation.diagnostics.removed,
+            added_errors: operation.diagnostics.addedErrors,
+        },
+        allow_new_errors: operation.allow_new_errors,
+        blocked: operation.blocked,
+        block_reason: operation.block_reason,
+        preview: operation.preview,
+        preview_truncated: operation.preview_truncated,
+    };
+}

package/dist/tools/rename_symbol.js

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import { prepareRename } from "../services/operations.js";
+import { PreparedOperationOutputSchema, serializePreparedOperation } from "./operation-schema.js";
+import { errorResult, structuredResult } from "./result.js";
+const AstRenameSymbolInputSchema = z.object({
+    project_root: z.string(),
+    file_path: z.string(),
+    symbol_path: z.string(),
+    new_name: z.string().min(1).describe("New identifier only, without a container prefix."),
+    dry_run: z
+        .boolean()
+        .default(true)
+        .describe("Compatibility field. Direct application is disabled; this tool always prepares."),
+    allow_new_errors: z
+        .boolean()
+        .default(false)
+        .describe("Permit a plan with new TypeScript errors after explicit review."),
+});
+export function registerRenameSymbol(server) {
+    server.registerTool("ast_rename_symbol", {
+        title: "Prepare a project-wide structural rename",
+        description: "Prepares an exact hash-bound rename plan without writing. Review the preview and apply its operation_id with ast_apply_operation.",
+        inputSchema: AstRenameSymbolInputSchema,
+        outputSchema: PreparedOperationOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, async ({ project_root, file_path, symbol_path, new_name, dry_run, allow_new_errors }) => {
+        try {
+            if (!dry_run) {
+                throw new Error("Direct rename application is disabled. Prepare with dry_run=true, then call ast_apply_operation with the returned operation_id.");
+            }
+            const operation = await prepareRename({
+                projectRoot: project_root,
+                filePath: file_path,
+                symbolPath: symbol_path,
+                newName: new_name,
+                allowNewErrors: allow_new_errors,
+            });
+            return structuredResult(serializePreparedOperation(operation));
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+}

package/dist/tools/replace_symbol_body.js

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import { prepareReplaceBody } from "../services/operations.js";
+import { PreparedOperationOutputSchema, serializePreparedOperation } from "./operation-schema.js";
+import { errorResult, structuredResult } from "./result.js";
+const AstReplaceSymbolBodyInputSchema = z.object({
+    project_root: z.string(),
+    file_path: z.string(),
+    symbol_path: z.string(),
+    new_body: z.string().describe("New body text without the enclosing braces."),
+    dry_run: z
+        .boolean()
+        .default(true)
+        .describe("Compatibility field. Direct application is disabled; this tool always prepares."),
+    allow_new_errors: z
+        .boolean()
+        .default(false)
+        .describe("Permit a plan with new TypeScript errors after explicit review."),
+});
+export function registerReplaceSymbolBody(server) {
+    server.registerTool("ast_replace_symbol_body", {
+        title: "Prepare an exact function-body replacement",
+        description: "Prepares a hash-bound body replacement while preserving the signature. Supports declarations, methods, accessors and function-valued variables/properties.",
+        inputSchema: AstReplaceSymbolBodyInputSchema,
+        outputSchema: PreparedOperationOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, async ({ project_root, file_path, symbol_path, new_body, dry_run, allow_new_errors }) => {
+        try {
+            if (!dry_run) {
+                throw new Error("Direct body replacement is disabled. Prepare with dry_run=true, then call ast_apply_operation with the returned operation_id.");
+            }
+            const operation = await prepareReplaceBody({
+                projectRoot: project_root,
+                filePath: file_path,
+                symbolPath: symbol_path,
+                newBody: new_body,
+                allowNewErrors: allow_new_errors,
+            });
+            return structuredResult(serializePreparedOperation(operation));
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+}

package/dist/tools/result.js

@@ -0,0 +1,14 @@
+export function structuredResult(structuredContent) {
+    return { content: [], structuredContent };
+}
+export function errorResult(error) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: error instanceof Error ? error.message : String(error),
+            },
+        ],
+        isError: true,
+    };
+}

package/dist/tools/search_symbols.js

@@ -0,0 +1,101 @@
+import path from "node:path";
+import { z } from "zod";
+import { buildFileOutline } from "../services/outline.js";
+import { PaginationInputSchema, PaginationOutputSchema, paginate } from "../services/pagination.js";
+import { withProject } from "../services/project.js";
+import { collectSymbols } from "../services/symbols.js";
+import { errorResult, structuredResult } from "./result.js";
+const AstSearchSymbolsInputSchema = z.object({
+    project_root: z
+        .string()
+        .describe("Absolute project directory containing tsconfig.json, or the config path."),
+    query: z
+        .string()
+        .min(1)
+        .describe("Case-insensitive substring matched against name and symbol path."),
+    kinds: z
+        .array(z.string())
+        .optional()
+        .describe("Optional exact ts-morph syntax kinds, such as ClassDeclaration or MethodDeclaration."),
+    file_filter: z
+        .string()
+        .optional()
+        .describe("Optional case-insensitive substring matched against project-relative file paths."),
+    ...PaginationInputSchema,
+});
+const SearchSymbolSchema = z.object({
+    file: z.string(),
+    symbol_path: z.string(),
+    selector: z.string(),
+    name: z.string(),
+    kind: z.string(),
+    line: z.number().int().positive(),
+    signature: z.string(),
+});
+const AstSearchSymbolsOutputSchema = z.object({
+    symbols: z.array(SearchSymbolSchema),
+    duration_ms: z.number().min(0),
+    ...PaginationOutputSchema,
+});
+export function registerSearchSymbols(server) {
+    server.registerTool("ast_search_symbols", {
+        title: "Search project symbols",
+        description: "Searches declarations structurally and returns exact file/symbol selectors that can be passed to the other AST tools.",
+        inputSchema: AstSearchSymbolsInputSchema,
+        outputSchema: AstSearchSymbolsOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ project_root, query, kinds, file_filter, offset, limit }) => {
+        try {
+            const structuredContent = await withProject(project_root, ({ project, projectRoot }) => {
+                const startedAt = performance.now();
+                const normalizedQuery = query.toLowerCase();
+                const normalizedFileFilter = file_filter?.toLowerCase();
+                const kindSet = kinds ? new Set(kinds) : undefined;
+                const matches = [];
+                for (const sourceFile of project.getSourceFiles()) {
+                    const file = path.relative(projectRoot, sourceFile.getFilePath());
+                    if (normalizedFileFilter && !file.toLowerCase().includes(normalizedFileFilter)) {
+                        continue;
+                    }
+                    const matchingSymbols = collectSymbols(sourceFile).filter((symbol) => (!kindSet || kindSet.has(symbol.kind)) &&
+                        (symbol.name.toLowerCase().includes(normalizedQuery) ||
+                            symbol.symbolPath.toLowerCase().includes(normalizedQuery)));
+                    if (matchingSymbols.length === 0)
+                        continue;
+                    const signatures = new Map(buildFileOutline(sourceFile).symbols.map((symbol) => [
+                        `${symbol.symbolPath}@${symbol.startLine}`,
+                        symbol.signature,
+                    ]));
+                    for (const symbol of matchingSymbols) {
+                        matches.push({
+                            file,
+                            symbol_path: symbol.symbolPath,
+                            selector: `${symbol.symbolPath}@${symbol.line}`,
+                            name: symbol.name,
+                            kind: symbol.kind,
+                            line: symbol.line,
+                            signature: signatures.get(`${symbol.symbolPath}@${symbol.line}`) ?? symbol.node.getText(),
+                        });
+                    }
+                }
+                matches.sort((left, right) => `${left.file}:${left.line}:${left.symbol_path}`.localeCompare(`${right.file}:${right.line}:${right.symbol_path}`));
+                const page = paginate(matches, offset, limit);
+                const { items, ...metadata } = page;
+                return {
+                    symbols: items,
+                    duration_ms: performance.now() - startedAt,
+                    ...metadata,
+                };
+            });
+            return structuredResult(structuredContent);
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "ast-mcp-server",
+  "version": "0.3.0",
+  "description": "Structural code MCP server and batch CLI for compact TypeScript/JavaScript reads and hash-bound AST edits.",
+  "keywords": [
+    "mcp",
+    "typescript",
+    "javascript",
+    "ast",
+    "ts-morph",
+    "coding-agent",
+    "refactoring"
+  ],
+  "license": "ISC",
+  "author": "Yail Peralta",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yailPeralta/ast-mcp-server.git"
+  },
+  "homepage": "https://github.com/yailPeralta/ast-mcp-server#readme",
+  "bugs": {
+    "url": "https://github.com/yailPeralta/ast-mcp-server/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "packageManager": "yarn@4.15.0",
+  "main": "dist/index.js",
+  "bin": {
+    "ast-mcp-server": "dist/index.js",
+    "ast-tool": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=20.19"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:mcp": "yarn build && node scripts/mcp-smoke.mjs",
+    "test:cli": "yarn build && node scripts/cli-smoke.mjs",
+    "test:package": "node scripts/package-smoke.mjs",
+    "benchmark": "yarn build && node scripts/benchmark.mjs",
+    "benchmark:corpus": "yarn build && node scripts/benchmark-corpus.mjs",
+    "benchmark:batch": "yarn build && node scripts/benchmark-batch.mjs",
+    "lint": "eslint src test scripts vitest.config.ts eslint.config.js",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "prepack": "yarn build",
+    "audit": "yarn npm audit --all --recursive",
+    "setup": "yarn build && node dist/cli.js setup",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "diff": "^9.0.0",
+    "ts-morph": "24.0.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^22.5.0",
+    "eslint": "^10.8.0",
+    "prettier": "^3.9.6",
+    "typescript": "^5.6.0",
+    "typescript-eslint": "^8.65.0",
+    "vitest": "^4.1.10"
+  }
+}

package/skills/structural-code-editing/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: structural-code-editing
+description: Leer, navegar y editar proyectos TypeScript/JavaScript mediante el resolver real del compilador y operaciones AST preparadas, revisadas y vinculadas por hash.
+version: "3.3.0"
+author: "yail"
+license: "ISC"
+metadata:
+  hermes:
+    tags: ["typescript", "javascript", "ast", "refactoring", "mcp"]
+    homepage: "https://github.com/yailPeralta/ast-mcp-server"
+---
+
+# Edición estructural con el servidor MCP `ast`
+
+## Cuándo usarlo
+
+Usar las tools del servidor MCP `ast` en proyectos TypeScript/JavaScript con `tsconfig.json` cuando haya que:
+
+- orientarse en archivos o módulos grandes/desconocidos;
+- encontrar declaraciones o referencias reales;
+- medir el radio de impacto de un rename;
+- renombrar un símbolo en varios archivos;
+- reemplazar solo el cuerpo de una función, método, accessor o callable property;
+- obtener diagnostics sin cargar el proyecto como texto en el contexto.
+
+Para configs, Markdown, comentarios o una edición textual trivial en un archivo ya conocido, usar las tools normales de archivos. El AST no cobra alquiler, pero cada roundtrip sí.
+
+## Preflight de disponibilidad
+
+La presencia de este skill no demuestra que el transporte MCP esté configurado. Si las tools `ast_*` no aparecen, no simularlas con búsquedas textuales mientras se afirma que son estructurales:
+
+- desde el checkout del servidor, ejecutar `yarn setup` para detectar agentes, registrar el MCP e instalar el skill;
+- desde un paquete instalado, ejecutar `ast-tool setup`;
+- verificar Claude Code con `/mcp` o `claude mcp get ast`;
+- verificar Hermes con `hermes mcp test ast` y recargar la sesión si acaba de cambiar la configuración.
+
+El setup falla cerrado ante un registro `ast` conflictivo. No eliminar ni reemplazar una configuración existente sin revisión explícita.
+
+## Flujo compacto de lectura
+
+1. `ast_list_files` para descubrir archivos. Paginar; no pedir todo un monorepo si alcanza con un filtro.
+2. `ast_search_symbols` si todavía no se conoce el archivo o el selector exacto.
+3. `ast_get_outline` para ver contratos sin cuerpos. No pedir `include_symbols` salvo que haga falta la metadata detallada.
+4. `ast_get_symbol_source` solo para las declaraciones cuya implementación haya que inspeccionar.
+5. `ast_find_references` antes de renames o cambios con impacto cross-file.
+6. `ast_get_diagnostics` para establecer y verificar el estado del proyecto.
+
+`file_path` debe ser preferentemente relativo al proyecto. Si un suffix coincide con varios archivos, la tool falla y devuelve candidatos en vez de elegir uno silenciosamente.
+
+Los clientes pueden prefijar los nombres publicados (`ast_*`) según su convención MCP; elegir por el nombre base y el schema, no adivinar el prefijo.
+
+## Batch CLI para clientes con Bash
+
+Cuando un pipeline conocido requiere varias llamadas MCP dependientes y el cliente tiene Bash, usar `ast-tool run pipeline.json` para colapsar los roundtrips del modelo. No usar batch para exploración abierta ni asumir que reduce el trabajo interno del compilador.
+
+- Encadenar outputs previos con objetos `{ "$ref": "#/steps/id/campo" }`.
+- Usar `foreach` más `{ "$item": "/campo" }` solamente para lecturas acotadas.
+- Definir `emit` para que los resultados intermedios no entren al contexto.
+- Mantener paginación y filtros: batch elimina roundtrips, no vuelve razonable leer un monorepo entero.
+- No generar JavaScript/eval dentro del documento; el contrato es declarativo y limitado.
+
+`ast-tool validate pipeline.json` valida schema, orden de referencias y política sin cargar el proyecto. Límites por defecto: 50 steps, 500 invocaciones, 200 items por foreach, concurrencia 4 (máximo 16), input 1 MiB, 10 MiB por resultado retenido/output y 50 MiB de contexto intermedio acumulado.
+
+## Flujo obligatorio de mutación
+
+Las tools de rename y reemplazo **solo preparan**. `dry_run: false` directo está deshabilitado.
+
+1. Llamar `ast_rename_symbol` o `ast_replace_symbol_body` con `dry_run: true`.
+2. Revisar:
+   - `affected_files`;
+   - summaries y previews;
+   - diagnostics agregados/removidos;
+   - `blocked` y el valor visible de `allow_new_errors`.
+3. Si el preview inline está truncado o hay varios archivos, pedir diffs completos con `ast_get_operation_preview`.
+4. Aplicar con `ast_apply_operation`, pasando **ambos**:
+   - `operation_id`;
+   - `plan_hash`.
+5. Ejecutar el typecheck/build/test canónico del proyecto después del apply.
+
+Nunca reconstruir el contenido a aplicar a partir del diff. Apply escribe los postimages exactos retenidos en el plan.
+
+### Mutaciones desde el CLI
+
+Un batch puede terminar en una sola preparación, pero nunca puede incluir `ast_apply_operation`. El resultado expone `operation_id`, `plan_hash` y `plan_file` en el nivel superior aunque `emit` los omita; revisar preview, diagnostics y affected files, y aplicar en otra llamada:
+
+```text
+ast-tool apply <plan_file> --plan-hash <reviewed_sha256>
+```
+
+Los planes CLI sobreviven al proceso bajo `${XDG_STATE_HOME:-~/.local/state}/ast-tool/plans` (o `AST_TOOL_STATE_DIR`), contienen bytes de código exactos y son privados. No copiar su contenido al chat si el repo es sensible.
+
+## Seguridad que sí ofrece
+
+- proyecto fresco al preparar mutaciones;
+- diagnostics pre/post y bloqueo de errores nuevos por default;
+- plan vinculado por hash al workspace completo, configs extendidos/referenciados y postimages;
+- rechazo si cambió cualquier source/config antes de apply;
+- lock filesystem cooperativo por config/workspace canónico compartido por MCP y CLI;
+- staging, flush, rename, verificación de hash y rollback conservador;
+- retry idempotente de un operation ya aplicado;
+- preservación de modo y UTF-8 BOM.
+
+La edición AST no demuestra que un cambio sea semánticamente correcto ni vuelve imposible romper código. La garantía práctica surge de combinar selección estructural, diagnostics, preview exacto, hash revisado, freshness checks y apply fail-closed.
+
+## Límites
+
+- No es una transacción global multiarchivo: la atomicidad depende del rename por archivo.
+- El rollback es best effort y no pisa cambios de otro writer.
+- El lock coordina superficies de apply que usan el mismo state directory; no coordina editores, NFS ni writers hostiles.
+- Los planes MCP son in-memory y se pierden al reiniciar el servidor; los planes CLI son archivos privados, versionados y con el mismo TTL.
+- El receipt se persiste dentro de la sección crítica. Si esa persistencia falla después de reemplazar sources, apply sale no-cero y el retry recupera sólo si el workspace completo coincide exactamente con el fingerprint post-apply revisado.
+- Un crash duro puede dejar un lock stale: retirarlo requiere inspeccionar metadata y confirmar que no hay apply activo. Un estado parcial o divergente sigue fallando cerrado.
+- Solo admite sources UTF-8 con o sin BOM.
+- No implementa migración arbitraria de firmas, creación/eliminación de archivos ni lenguajes fuera de TS/JS.
+- `allow_new_errors: true` evita el bloqueo del plan; no convierte código roto en código sano.
+
+## Verificación
+
+Después de aplicar, correr el gate canónico del repo. Como mínimo, un typecheck/build. Para cambios cross-file o con dinero/producción en juego, también la suite focalizada y la completa que corresponda.