ast-mcp-server 0.3.0 → 0.5.0

package/dist/tools/find_references.js

@@ -3,7 +3,8 @@ import { Node } from "ts-morph";
 import { z } from "zod";
 import { PaginationInputSchema, PaginationOutputSchema, paginate } from "../services/pagination.js";
 import { findDeclarationByName, getSourceFileOrThrow, withProject } from "../services/project.js";
-import { errorResult, structuredResult } from "./result.js";
+import { errorResult, formattedResult, ToolOutputFormatInputSchema } from "./result.js";
+const ReferenceDetailSchema = z.enum(["locations", "context"]).default("locations");
 const AstFindReferencesInputSchema = z.object({
     project_root: z
         .string()
@@ -11,9 +12,11 @@ const AstFindReferencesInputSchema = z.object({
     file_path: z.string().describe("File containing the declaration."),
     symbol_path: z.string().describe("Exact symbol path returned by an outline or symbol search."),
     include_declaration: z.boolean().default(true),
+    detail: ReferenceDetailSchema.describe("Result detail: locations omits source lines; context adds bounded source-line text."),
+    ...ToolOutputFormatInputSchema,
     ...PaginationInputSchema,
 });
-const ReferenceSchema = z.object({
+const ContextReferenceSchema = z.object({
     file: z.string(),
     line: z.number().int().positive(),
     column: z.number().int().positive(),
@@ -21,27 +24,37 @@ const ReferenceSchema = z.object({
     is_declaration: z.boolean(),
     context: z.string(),
 });
-const AstFindReferencesOutputSchema = z.object({
+const LocationReferenceSchema = ContextReferenceSchema.omit({ context: true });
+const ReferenceOutputBase = {
     symbol: z.string(),
+    include_declaration: z.boolean(),
     declaration_count: z.number().int().min(0),
     reference_count: z.number().int().min(0),
     affected_files: z.array(z.string()),
-    references: z.array(ReferenceSchema),
     ...PaginationOutputSchema,
-});
+};
+const ReferenceOutputSchemas = {
+    locations: z.object({
+        ...ReferenceOutputBase,
+        references: z.array(LocationReferenceSchema),
+    }),
+    context: z.object({
+        ...ReferenceOutputBase,
+        references: z.array(ContextReferenceSchema),
+    }),
+};
 export function registerFindReferences(server) {
     server.registerTool("ast_find_references", {
         title: "Find semantic symbol references",
         description: "Finds type-resolved references and returns bounded project-relative locations, including declaration impact by default.",
         inputSchema: AstFindReferencesInputSchema,
-        outputSchema: AstFindReferencesOutputSchema,
         annotations: {
             readOnlyHint: true,
             destructiveHint: false,
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async ({ project_root, file_path, symbol_path, include_declaration, offset, limit }) => {
+    }, async ({ project_root, file_path, symbol_path, include_declaration, detail, output_format, offset, limit, }) => {
         try {
             const structuredContent = await withProject(project_root, ({ project, projectRoot }) => {
                 const sourceFile = getSourceFileOrThrow(project, file_path);
@@ -81,14 +94,24 @@ export function registerFindReferences(server) {
                 const { items, ...metadata } = page;
                 return {
                     symbol: symbol_path,
+                    include_declaration,
                     declaration_count: 1,
                     reference_count: references.length,
                     affected_files: affectedFiles,
-                    references: items,
+                    references: detail === "context"
+                        ? items
+                        : items.map(({ file, line, column, kind, is_declaration }) => ({
+                            file,
+                            line,
+                            column,
+                            kind,
+                            is_declaration,
+                        })),
                     ...metadata,
                 };
             });
-            return structuredResult(structuredContent);
+            const outputSchema = ReferenceOutputSchemas[detail];
+            return formattedResult(outputSchema, structuredContent, output_format);
         }
         catch (error) {
             return errorResult(error);

package/dist/tools/get_diagnostics.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { normalizeDiagnostic } from "../services/diagnostics.js";
 import { PaginationInputSchema, PaginationOutputSchema, paginate } from "../services/pagination.js";
 import { getSourceFileOrThrow, withProject } from "../services/project.js";
-import { errorResult, structuredResult } from "./result.js";
+import { errorResult, formattedResult, ToolOutputFormatInputSchema } from "./result.js";
 const DiagnosticSchema = z.object({
     code: z.number().int(),
     category: z.string(),
@@ -19,6 +19,7 @@ const AstGetDiagnosticsInputSchema = z.object({
         .string()
         .optional()
         .describe("Optional project-relative or absolute file path. Omit for project diagnostics."),
+    ...ToolOutputFormatInputSchema,
     ...PaginationInputSchema,
 });
 const AstGetDiagnosticsOutputSchema = z.object({
@@ -33,14 +34,13 @@ export function registerGetDiagnostics(server) {
         title: "Get TypeScript diagnostics",
         description: "Returns bounded normalized TypeScript diagnostics for a project or one source file. Existing errors are preserved as evidence for write-operation delta checks.",
         inputSchema: AstGetDiagnosticsInputSchema,
-        outputSchema: AstGetDiagnosticsOutputSchema,
         annotations: {
             readOnlyHint: true,
             destructiveHint: false,
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async ({ project_root, file_path, offset, limit }) => {
+    }, async ({ project_root, file_path, output_format, offset, limit }) => {
         try {
             const structuredContent = await withProject(project_root, ({ project, projectRoot }) => {
                 const startedAt = performance.now();
@@ -61,7 +61,7 @@ export function registerGetDiagnostics(server) {
                     ...metadata,
                 };
             });
-            return structuredResult(structuredContent);
+            return formattedResult(AstGetDiagnosticsOutputSchema, structuredContent, output_format);
         }
         catch (error) {
             return errorResult(error);

package/dist/tools/operation-schema.js

@@ -10,7 +10,7 @@ export const NormalizedDiagnosticSchema = z.object({
 export const PreparedOperationOutputSchema = z.object({
     operation_id: z.string().uuid(),
     plan_hash: z.string().length(64),
-    kind: z.enum(["rename_symbol", "replace_symbol_body"]),
+    kind: z.enum(["rename_symbol", "replace_symbol_body", "scaffold_class"]),
     status: z.literal("prepared"),
     project_root: z.string(),
     created_at: z.string(),

package/dist/tools/result.js

@@ -1,12 +1,56 @@
+import { Buffer } from "node:buffer";
+import { isDeepStrictEqual } from "node:util";
+import { decode, encode } from "@toon-format/toon";
+import { z } from "zod";
+export const MAX_TOOL_ERROR_BYTES = 64 * 1024;
+export const MAX_TOON_RESULT_BYTES = 10 * 1024 * 1024;
+export const ToolOutputFormatSchema = z.enum(["json", "toon"]).default("json");
+export const ToolOutputFormatInputSchema = {
+    output_format: ToolOutputFormatSchema.describe("Result representation. TOON wraps one compact encoded value in structuredContent."),
+};
+export const ToonResultSchema = z.object({
+    format: z.literal("toon"),
+    data: z.string(),
+});
 export function structuredResult(structuredContent) {
     return { content: [], structuredContent };
 }
+export function formattedResult(outputSchema, candidate, outputFormat, maxToonBytes = MAX_TOON_RESULT_BYTES) {
+    const validated = outputSchema.parse(candidate);
+    if (outputFormat === "json") {
+        return structuredResult(validated);
+    }
+    const text = encode(validated);
+    const byteLength = Buffer.byteLength(text, "utf8");
+    if (byteLength > maxToonBytes) {
+        throw new Error(`TOON result exceeds the ${maxToonBytes}-byte limit (${byteLength} bytes encoded).`);
+    }
+    if (!isDeepStrictEqual(decode(text), validated)) {
+        throw new Error("TOON result cannot represent the validated value losslessly.");
+    }
+    return structuredResult({ format: "toon", data: text });
+}
+function truncateUtf8(value, maxBytes) {
+    if (Buffer.byteLength(value, "utf8") <= maxBytes)
+        return value;
+    const suffix = "... [truncated]";
+    const source = Buffer.from(value, "utf8");
+    let end = Math.max(0, maxBytes - Buffer.byteLength(suffix, "utf8"));
+    while (end > 0 && (source[end] & 0xc0) === 0x80)
+        end -= 1;
+    let prefix = source.subarray(0, end).toString("utf8");
+    while (Buffer.byteLength(prefix + suffix, "utf8") > maxBytes) {
+        prefix = prefix.slice(0, -1);
+    }
+    return prefix + suffix;
+}
 export function errorResult(error) {
+    const message = error instanceof Error ? error.message : String(error);
     return {
         content: [
             {
                 type: "text",
-                text: error instanceof Error ? error.message : String(error),
+                text: truncateUtf8(message, MAX_TOOL_ERROR_BYTES),
             },
         ],
         isError: true,

package/dist/tools/scaffold_class.js

@@ -0,0 +1,145 @@
+import { z } from "zod";
+import { prepareScaffoldClass } from "../services/operations.js";
+import { errorResult, structuredResult } from "./result.js";
+import { PreparedOperationOutputSchema, serializePreparedOperation } from "./operation-schema.js";
+const IdentifierSchema = z.string().min(1).max(200);
+const TypeTextSchema = z.string().min(1).max(10_000);
+const AccessSchema = z.enum(["public", "protected", "private"]);
+const ConstructorAccessSchema = z.enum([
+    "public",
+    "protected",
+    "private",
+    "public readonly",
+    "protected readonly",
+    "private readonly",
+]);
+const ImportSchema = z
+    .object({
+    from: z.string().min(1).max(500),
+    named: z.array(IdentifierSchema).max(100).default([]),
+    default: IdentifierSchema.optional(),
+})
+    .strict();
+const ParameterSchema = z
+    .object({
+    name: IdentifierSchema,
+    type: TypeTextSchema,
+})
+    .strict();
+const ConstructorParameterSchema = ParameterSchema.extend({
+    access_modifier: ConstructorAccessSchema,
+}).strict();
+const PropertySchema = z
+    .object({
+    name: IdentifierSchema,
+    type: TypeTextSchema,
+    access: AccessSchema.default("private"),
+    initializer: z.string().max(10_000).optional(),
+})
+    .strict();
+const MethodSchema = z
+    .object({
+    name: IdentifierSchema,
+    is_async: z.boolean().default(false),
+    return_type: TypeTextSchema,
+    access: AccessSchema.default("public"),
+    parameters: z.array(ParameterSchema).max(100).default([]),
+    decorators: z.array(z.string().min(1).max(10_000)).max(50).default([]),
+    docs: z.array(z.string().min(1).max(10_000)).max(50).default([]),
+})
+    .strict();
+export const ScaffoldClassInputSchema = z
+    .object({
+    project_root: z.string().min(1),
+    file_path: z.string().min(1).max(1_000),
+    class_name: IdentifierSchema,
+    extends: TypeTextSchema.optional(),
+    implements: z.array(TypeTextSchema).max(50).default([]),
+    decorators: z.array(z.string().min(1).max(10_000)).max(50).default([]),
+    imports: z.array(ImportSchema).max(100).default([]),
+    constructor_params: z.array(ConstructorParameterSchema).max(100).default([]),
+    properties: z.array(PropertySchema).max(200).default([]),
+    methods: z.array(MethodSchema).min(1).max(200),
+    dry_run: z.literal(true).default(true),
+    allow_new_errors: z.boolean().default(false),
+})
+    .strict();
+const ScaffoldClassOutputSchema = PreparedOperationOutputSchema.extend({
+    file: z.string(),
+    class_name: z.string(),
+    outline: z.string(),
+    pending_methods: z.array(z.string()),
+});
+function toSpec(args) {
+    return {
+        className: args.class_name,
+        ...(args.extends ? { extends: args.extends } : {}),
+        implements: args.implements,
+        decorators: args.decorators,
+        imports: args.imports.map((item) => ({
+            from: item.from,
+            named: item.named,
+            ...(item.default ? { default: item.default } : {}),
+        })),
+        constructorParams: args.constructor_params.map((parameter) => ({
+            name: parameter.name,
+            type: parameter.type,
+            accessModifier: parameter.access_modifier,
+        })),
+        properties: args.properties.map((property) => ({
+            name: property.name,
+            type: property.type,
+            accessModifier: property.access,
+            ...(property.initializer !== undefined ? { initializer: property.initializer } : {}),
+        })),
+        methods: args.methods.map((method) => ({
+            name: method.name,
+            isAsync: method.is_async,
+            returnType: method.return_type,
+            accessModifier: method.access,
+            params: method.parameters.map((parameter) => ({
+                name: parameter.name,
+                type: parameter.type,
+            })),
+            decorators: method.decorators,
+            docs: method.docs,
+        })),
+    };
+}
+export function registerScaffoldClass(server) {
+    // The SDK compatibility overload exceeds TypeScript's instantiation depth for this schema.
+    // Keep the complete runtime schema and isolate only the registrar type.
+    const registerTool = server.registerTool.bind(server);
+    registerTool("ast_scaffold_class", {
+        title: "Prepare Class Scaffold",
+        description: "Prepares a hash-bound new TypeScript class file without writing it. Each method body throws an explicit not-implemented error. Review the diff, then apply the returned operation_id and plan_hash with ast_apply_operation.",
+        inputSchema: ScaffoldClassInputSchema,
+        outputSchema: ScaffoldClassOutputSchema.shape,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, async (args) => {
+        try {
+            const prepared = await prepareScaffoldClass({
+                projectRoot: args.project_root,
+                filePath: args.file_path,
+                spec: toSpec(args),
+                allowNewErrors: args.allow_new_errors,
+            });
+            const structuredContent = {
+                ...serializePreparedOperation(prepared.operation),
+                file: prepared.file,
+                class_name: prepared.className,
+                outline: prepared.outline,
+                pending_methods: prepared.pendingMethods,
+            };
+            return structuredResult(structuredContent);
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+}

package/dist/tools/search_symbols.js

@@ -1,10 +1,12 @@
 import path from "node:path";
 import { z } from "zod";
 import { buildFileOutline } from "../services/outline.js";
-import { PaginationInputSchema, PaginationOutputSchema, paginate } from "../services/pagination.js";
+import { createPaginationInputSchema, PaginationOutputSchema, paginate, } from "../services/pagination.js";
 import { withProject } from "../services/project.js";
-import { collectSymbols } from "../services/symbols.js";
-import { errorResult, structuredResult } from "./result.js";
+import { collectSymbols, symbolMatchRank } from "../services/symbols.js";
+import { errorResult, formattedResult, ToolOutputFormatInputSchema } from "./result.js";
+const SEARCH_DEFAULT_LIMIT = 20;
+const SearchDetailSchema = z.enum(["selectors", "summary", "full"]).default("summary");
 const AstSearchSymbolsInputSchema = z.object({
     project_root: z
         .string()
@@ -21,9 +23,11 @@ const AstSearchSymbolsInputSchema = z.object({
         .string()
         .optional()
         .describe("Optional case-insensitive substring matched against project-relative file paths."),
-    ...PaginationInputSchema,
+    detail: SearchDetailSchema.describe("Result detail: selectors for routing, summary adds signatures, full adds redundant declaration fields."),
+    ...ToolOutputFormatInputSchema,
+    ...createPaginationInputSchema(SEARCH_DEFAULT_LIMIT),
 });
-const SearchSymbolSchema = z.object({
+const FullSearchSymbolSchema = z.object({
     file: z.string(),
     symbol_path: z.string(),
     selector: z.string(),
@@ -32,24 +36,59 @@ const SearchSymbolSchema = z.object({
     line: z.number().int().positive(),
     signature: z.string(),
 });
-const AstSearchSymbolsOutputSchema = z.object({
-    symbols: z.array(SearchSymbolSchema),
-    duration_ms: z.number().min(0),
-    ...PaginationOutputSchema,
+const SelectorSearchSymbolSchema = FullSearchSymbolSchema.pick({
+    file: true,
+    selector: true,
+    kind: true,
 });
+const SummarySearchSymbolSchema = FullSearchSymbolSchema.pick({
+    file: true,
+    selector: true,
+    kind: true,
+    signature: true,
+});
+const SearchOutputSchemas = {
+    selectors: z.object({
+        symbols: z.array(SelectorSearchSymbolSchema),
+        duration_ms: z.number().min(0),
+        ...PaginationOutputSchema,
+    }),
+    summary: z.object({
+        symbols: z.array(SummarySearchSymbolSchema),
+        duration_ms: z.number().min(0),
+        ...PaginationOutputSchema,
+    }),
+    full: z.object({
+        symbols: z.array(FullSearchSymbolSchema),
+        duration_ms: z.number().min(0),
+        ...PaginationOutputSchema,
+    }),
+};
+function projectSymbols(detail, symbols) {
+    if (detail === "full")
+        return symbols;
+    if (detail === "summary") {
+        return symbols.map(({ file, selector, kind, signature }) => ({
+            file,
+            selector,
+            kind,
+            signature,
+        }));
+    }
+    return symbols.map(({ file, selector, kind }) => ({ file, selector, kind }));
+}
 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.",
+        description: "Ranks structural declarations and returns exact file/symbol selectors for downstream AST tools.",
         inputSchema: AstSearchSymbolsInputSchema,
-        outputSchema: AstSearchSymbolsOutputSchema,
         annotations: {
             readOnlyHint: true,
             destructiveHint: false,
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async ({ project_root, query, kinds, file_filter, offset, limit }) => {
+    }, async ({ project_root, query, kinds, file_filter, detail, output_format, offset, limit }) => {
         try {
             const structuredContent = await withProject(project_root, ({ project, projectRoot }) => {
                 const startedAt = performance.now();
@@ -62,9 +101,13 @@ export function registerSearchSymbols(server) {
                     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)));
+                    const matchingSymbols = collectSymbols(sourceFile).filter((symbol) => {
+                        const selector = `${symbol.symbolPath}@${symbol.line}`.toLowerCase();
+                        return ((!kindSet || kindSet.has(symbol.kind)) &&
+                            (symbol.name.toLowerCase().includes(normalizedQuery) ||
+                                symbol.symbolPath.toLowerCase().includes(normalizedQuery) ||
+                                selector.includes(normalizedQuery)));
+                    });
                     if (matchingSymbols.length === 0)
                         continue;
                     const signatures = new Map(buildFileOutline(sourceFile).symbols.map((symbol) => [
@@ -83,16 +126,34 @@ export function registerSearchSymbols(server) {
                         });
                     }
                 }
-                matches.sort((left, right) => `${left.file}:${left.line}:${left.symbol_path}`.localeCompare(`${right.file}:${right.line}:${right.symbol_path}`));
+                matches.sort((left, right) => {
+                    const rank = symbolMatchRank(query, {
+                        symbolPath: left.symbol_path,
+                        name: left.name,
+                        line: left.line,
+                    }) -
+                        symbolMatchRank(query, {
+                            symbolPath: right.symbol_path,
+                            name: right.name,
+                            line: right.line,
+                        });
+                    if (rank !== 0)
+                        return rank;
+                    return (left.file.localeCompare(right.file) ||
+                        left.line - right.line ||
+                        left.symbol_path.localeCompare(right.symbol_path) ||
+                        left.kind.localeCompare(right.kind));
+                });
                 const page = paginate(matches, offset, limit);
                 const { items, ...metadata } = page;
                 return {
-                    symbols: items,
+                    symbols: projectSymbols(detail, items),
                     duration_ms: performance.now() - startedAt,
                     ...metadata,
                 };
             });
-            return structuredResult(structuredContent);
+            const outputSchema = SearchOutputSchemas[detail];
+            return formattedResult(outputSchema, structuredContent, output_format);
         }
         catch (error) {
             return errorResult(error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ast-mcp-server",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Structural code MCP server and batch CLI for compact TypeScript/JavaScript reads and hash-bound AST edits.",
   "keywords": [
     "mcp",
@@ -40,6 +40,9 @@
   "engines": {
     "node": ">=20.19"
   },
+  "resolutions": {
+    "hono": "4.12.34"
+  },
   "scripts": {
     "build": "tsc",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json",
@@ -51,6 +54,8 @@
     "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",
+    "benchmark:formats": "yarn build && node scripts/benchmark-formats.mjs",
+    "benchmark:shapes": "yarn build && node scripts/benchmark-result-shapes.mjs",
     "lint": "eslint src test scripts vitest.config.ts eslint.config.js",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
@@ -62,6 +67,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
+    "@toon-format/toon": "4.1.0",
     "diff": "^9.0.0",
     "ts-morph": "24.0.0",
     "zod": "^3.23.8"
@@ -70,9 +76,10 @@
     "@eslint/js": "^10.0.1",
     "@types/node": "^22.5.0",
     "eslint": "^10.8.0",
+    "gpt-tokenizer": "3.4.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

@@ -1,7 +1,7 @@
 ---
 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"
+version: "4.0.0"
 author: "yail"
 license: "ISC"
 metadata:
@@ -21,6 +21,7 @@ Usar las tools del servidor MCP `ast` en proyectos TypeScript/JavaScript con `ts
 - 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;
+- crear un archivo de clase nuevo mediante un scaffold estructurado y revisado;
 - 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í.
@@ -45,10 +46,26 @@ El setup falla cerrado ante un registro `ast` conflictivo. No eliminar ni reempl
 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.
 
+`ast_search_symbols` devuelve por default hasta 20 records `summary` rankeados. Su campo `selector` es el valor que se pasa como `symbol_path` a la siguiente tool; pedir `detail: "selectors"` para routing puro o `detail: "full", limit: 100` para el perfil v0.4.0. `ast_find_references` devuelve `detail: "locations"` por default; expandir a `detail: "context"` únicamente cuando la línea fuente aporte evidencia necesaria.
+
 `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.
 
+## Formato de resultado para el modelo
+
+`ast_search_symbols`, `ast_find_references` y `ast_get_diagnostics` aceptan `output_format: "toon"`. Usarlo cuando la respuesta vaya directo al modelo y se espere una colección uniforme con varios registros. Omitirlo, o usar `json`, para automatización que dependa del objeto canónico.
+
+En MCP, TOON llega como un único envelope estructurado `{ "format": "toon", "data": "..." }`; `data` contiene el documento TOON lossless. No hay una copia JSON completa en paralelo. Las tres tools validan primero el valor canónico con Zod, pero no publican un `outputSchema` MCP único porque tienen dos representaciones de éxito.
+
+No pedir TOON para `ast_list_files`, outlines, source, previews ni mutaciones: los benchmarks muestran que el envelope empeora esas formas pequeñas, multiline o diff-heavy. Para un pipeline read-only conocido, se puede compactar únicamente el resultado final con:
+
+```text
+ast-tool run pipeline.json --output-format toon
+```
+
+Los pasos internos del batch siempre son JSON estructurado. TOON dentro de `step.input` y TOON final para un batch de preparación se rechazan antes de ejecutar la operación.
+
 ## 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.
@@ -59,13 +76,13 @@ Cuando un pipeline conocido requiere varias llamadas MCP dependientes y el clien
 - 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.
+`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. Los errores del CLI permanecen como JSON en stderr aunque el output exitoso solicitado sea TOON.
 
 ## Flujo obligatorio de mutación
 
-Las tools de rename y reemplazo **solo preparan**. `dry_run: false` directo está deshabilitado.
+Las tools de rename, reemplazo y scaffold **solo preparan**. `dry_run: false` directo está deshabilitado.
 
-1. Llamar `ast_rename_symbol` o `ast_replace_symbol_body` con `dry_run: true`.
+1. Llamar `ast_rename_symbol`, `ast_replace_symbol_body` o `ast_scaffold_class` con `dry_run: true`.
 2. Revisar:
    - `affected_files`;
    - summaries y previews;
@@ -79,6 +96,12 @@ Las tools de rename y reemplazo **solo preparan**. `dry_run: false` directo est
 
 Nunca reconstruir el contenido a aplicar a partir del diff. Apply escribe los postimages exactos retenidos en el plan.
 
+### Scaffold de clase
+
+Usar `ast_scaffold_class` solo para crear un `.ts`/`.tsx` ausente con una clase estructurada. Pasar imports, heritage, decorators, constructor params, properties inicializadas y métodos mediante el schema; no inyectar un archivo completo como string. Debe haber al menos un método.
+
+Cada método generado contiene exclusivamente `throw new Error("Not implemented: Class.method")`. Preparar el scaffold, revisar el diff desde `/dev/null`, diagnostics, `pending_methods`, `blocked` y `plan_hash`, aplicar y luego reemplazar cada selector pendiente con `ast_replace_symbol_body`. Un target existente, path fuera del proyecto o parent simbólico debe fallar; no buscar un fallback textual.
+
 ### 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:
@@ -96,7 +119,8 @@ Los planes CLI sobreviven al proceso bajo `${XDG_STATE_HOME:-~/.local/state}/ast
 - 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;
+- staging, flush, rename para reemplazos y creación no-clobber para targets nuevos, con verificación de hash y rollback conservador;
+- scaffold create-only con target ausente, parent real, postimage incluida en el fingerprint y diff contra `/dev/null`;
 - retry idempotente de un operation ya aplicado;
 - preservación de modo y UTF-8 BOM.
 
@@ -111,7 +135,7 @@ La edición AST no demuestra que un cambio sea semánticamente correcto ni vuelv
 - 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.
+- No implementa migración arbitraria de firmas, creación/eliminación general de archivos ni lenguajes fuera de TS/JS; la única creación admitida es el scaffold de una clase.
 - `allow_new_errors: true` evita el bloqueo del plan; no convierte código roto en código sano.
 
 ## Verificación