ast-mcp-server 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-08-03
+
+### Added
+
+- Opt-in TOON envelopes for symbol search, semantic references, and diagnostics through `output_format: "toon"`.
+- Plain TOON output for final read-only batch results through `ast-tool run --output-format toon`.
+- Reproducible JSON/TOON benchmark with lossless round trips, UTF-8 bytes, `o200k_base` token estimates, encoding latency, static tool-metadata accounting, and negative controls.
+
+### Changed
+
+- Collection-heavy tools validate their canonical Zod outputs explicitly before returning JSON or TOON. They no longer advertise one MCP `outputSchema` because their structured result can be either the canonical object or a TOON envelope.
+- The bundled structural-code-editing skill now selects TOON only for measured collection shapes and keeps JSON for source, outline, file-list, and mutation workflows.
+
+### Security
+
+- Batch steps reject statically declared and dynamically resolved TOON intermediates before the affected invocation.
+- TOON output is capped at 10 MiB after UTF-8 encoding, and mutation preparation remains JSON-only so review coordinates are never compacted.
+- Successful MCP TOON output is decode-checked against the validated value, and MCP error text is capped at 64 KiB of UTF-8.
+- The transitive Hono runtime is resolved to `4.12.34`, closing GHSA-8j4g-w8fx-2239 from the MCP SDK dependency tree.
+
 ## [0.3.0] - 2026-08-03
 
 Initial public release.
@@ -24,4 +44,5 @@ Initial public release.
 - Apply rejects stale workspaces, changed configs/sources, mismatched plan hashes, unsafe plan files, conflicting MCP registrations, and conflicting skill content.
 - Inputs, outputs, operation stores, subprocesses, batch fan-out, plan lifetime, and filesystem access are bounded.
 
+[0.4.0]: https://github.com/yailPeralta/ast-mcp-server/releases/tag/v0.4.0
 [0.3.0]: https://github.com/yailPeralta/ast-mcp-server/releases/tag/v0.3.0

package/README.md

@@ -39,7 +39,7 @@ Reads can start with a compact outline and fetch exact source only when needed.
 
 AST-aware editing is not a proof that a change is semantically correct. The safety comes from combining structural selection with diagnostics, exact previews, reviewed hashes, freshness checks, and fail-closed apply semantics.
 
-The included batch benchmark records a 50% reduction in model round-trips and a 95.21% reduction in serialized context for its search-to-source scenario. These are reproducible scenario measurements, not universal token or latency claims.
+The included batch benchmark records a 50% reduction in model round-trips and a 95.21% reduction in serialized context for its search-to-source scenario. The format benchmark records an `o200k_base` estimate of 25.72% fewer model-facing tokens for a 100-row symbol search and 26.56% across the eligible collection corpus. These are reproducible scenario measurements, not universal token, billing, cache, or latency claims.
 
 ## Requirements
 
@@ -229,6 +229,14 @@ Project-scoped tools accept `project_root`, either the project directory or an e
 
 Read results use project-relative paths, deterministic ordering, structured MCP output, and pagination where result sets can grow with the project.
 
+### Optional TOON results
+
+`ast_search_symbols`, `ast_find_references`, and `ast_get_diagnostics` accept `output_format: "toon"` for collection-heavy results consumed directly by a model. JSON remains the default and preserves the canonical structured object.
+
+MCP TOON is returned once as structured content shaped like `{ "format": "toon", "data": "..." }`; `data` is the lossless TOON document. The complete JSON result is not duplicated. These three tools validate their canonical Zod result and verify an encode/decode deep-equality round trip before presentation, but do not advertise a single MCP `outputSchema` because their successful structured content has two representations.
+
+Do not request TOON for source, outlines, file lists, previews, or mutation results. Checked negative controls show that the MCP envelope makes those shapes larger. TOON is an explicit shape-specific optimization, not a new dialect for every object in sight.
+
 ## Batch CLI
 
 `ast-tool` lets Claude Code and other Bash-capable clients collapse a known structural pipeline into one shell call:
@@ -236,6 +244,7 @@ Read results use project-relative paths, deterministic ordering, structured MCP
 ```bash
 ast-tool validate pipeline.json
 ast-tool run pipeline.json
+ast-tool run pipeline.json --output-format toon
 cat pipeline.json | ast-tool run -
 ```
 
@@ -299,7 +308,7 @@ A `$ref` is an RFC 6901 JSON Pointer rooted at prior step results. References ca
 - One project root per pipeline.
 - No branches, eval, embedded JavaScript, while loops, or arbitrary transformations.
 
-Success is one JSON value on stdout. Errors are structured JSON on stderr. Exit code 0 is success, 1 is execution/apply failure, and 2 is usage or schema failure.
+Success is one compact JSON value on stdout by default. `ast-tool run --output-format toon` writes one plain TOON document for a read-only batch; internal steps remain structured JSON, and prepare batches reject TOON before execution. Encoding and output-limit failures write no partial stdout and use stable `ENCODING_ERROR` or `OUTPUT_LIMIT` codes. Errors are always structured JSON on stderr. Exit code 0 is success, 1 is execution/apply failure, and 2 is usage or schema failure.
 
 ## Reviewed mutations
 
@@ -370,9 +379,12 @@ yarn pack --dry-run
 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
 ```
 
-The batch benchmark compares two separate client calls with one batch invocation in fresh Node processes, recording model round-trips, actual tool invocations, wall time, maximum RSS, and serialized character counts. Character counts are not model-specific token estimates. See `benchmark/README.md` for methodology and limitations.
+The batch benchmark compares two separate client calls with one batch invocation in fresh Node processes, recording model round-trips, actual tool invocations, wall time, maximum RSS, and serialized character counts. Character counts are not model-specific token estimates.
+
+The format benchmark runs real tools against this repository plus deterministic reference/diagnostic fixtures. It checks JSON→TOON→value equality, UTF-8 bytes, `gpt-tokenizer` `o200k_base` estimates, encode/decode latency, the actual MCP envelope, tool metadata, and negative controls. Its checked result is `benchmark/results/self-formats.json`; local tokenizer estimates do not establish provider-side billing or cache savings. See `benchmark/README.md` for methodology and limitations.
 
 ## Scope
 

package/benchmark/README.md

@@ -1,6 +1,6 @@
 # Benchmark methodology
 
-The benchmark suite measures two separate properties. It deliberately avoids converting characters into tokens because tokenizer choice changes the answer.
+The benchmark suite measures structural payload reduction, batch orchestration, and model-facing result formats. The first two benchmarks deliberately avoid converting characters into tokens. The format benchmark pins and names one tokenizer so its estimates are reproducible rather than universal.
 
 ## Project payload and latency
 
@@ -64,6 +64,27 @@ yarn benchmark:batch --iterations 5 --output benchmark/results/self-batch.json
 
 The report records logical model round-trips, actual tool invocations, median wall time, process maximum RSS, final-result characters, and total characters exposed to the model. It does not include model inference latency, so the practical wall-time benefit of removing a model round-trip will be larger than this local process-only comparison. Maximum RSS includes the Node runtime and TypeScript project in each fresh worker.
 
+## Model-facing JSON and TOON
+
+`scripts/benchmark-formats.mjs` compares compact JSON with TOON for actual MCP logical results. It uses this repository for broad symbol search and deterministic temporary TypeScript fixtures for repeated references and non-empty diagnostics. File lists, outlines, exact source, and a prepared rename are retained as negative controls.
+
+For each payload it records:
+
+- exact JSON→TOON→value round-trip equality;
+- UTF-8 bytes;
+- `gpt-tokenizer@3.4.0` `o200k_base` token estimates;
+- plain TOON for CLI output and the real MCP `{format,data}` envelope;
+- median encode/decode time over 50 local iterations;
+- serialized `tools/list` metadata against the checked v0.3.0 baseline.
+
+Run:
+
+```bash
+yarn benchmark:formats
+```
+
+The script fails unless every round trip is exact, the broad-search MCP envelope reduces estimated tokens by at least 20%, and the aggregate eligible corpus reduces them by at least 15%. Tokenizer estimates are not provider usage records and do not establish billed-token or prompt-cache savings.
+
 ## Checked results
 
 Results generated on 2026-08-03 with Node.js v24.16.0:
@@ -84,3 +105,14 @@ The checked broad search-to-source batch result used five fresh-process samples:
 | Batch    |                 1 |                2 |           552 |        535.24 ms |      378.35 MB |
 
 That run reduced model round-trips by 50% and serialized context by 95.21%. Local execution latency decreased by 0.18% and RSS increased by 0.21%, both small enough to treat as noise rather than a performance claim. The batch value is orchestration/context reduction; it does not make TypeScript analysis free.
+
+The checked model-facing format corpus used the complete MCP envelope for TOON:
+
+| Payload             | Records | JSON tokens | MCP TOON tokens | Reduction |
+| ------------------- | ------: | ----------: | --------------: | --------: |
+| Broad symbol search |     100 |       5,225 |           3,881 |    25.72% |
+| References          |      71 |       3,086 |           2,150 |    30.33% |
+| Diagnostics         |      30 |       1,309 |           1,034 |    21.01% |
+| Eligible aggregate  |     201 |       9,620 |           7,065 |    26.56% |
+
+All seven positive and negative payloads round-tripped exactly. File list, outline, source, and prepare envelopes ranged from 5.50% to 23.40% worse in estimated tokens, which is why they remain JSON-only. Current serialized tool metadata is 2,451 characters smaller than the v0.3.0 baseline despite the three new input fields, because multi-shape tools no longer advertise a single incompatible output schema.

package/dist/batch/runner.js

@@ -65,6 +65,9 @@ function injectProjectRoot(resolved, projectRoot, step) {
         throw new BatchExecutionError(`Step "${step.id}" input must resolve to an object.`, "INVALID_STEP_INPUT", step.id);
     }
     const input = resolved;
+    if (input.output_format === "toon") {
+        throw new BatchExecutionError(`Step "${step.id}" cannot resolve TOON for an intermediate batch result.`, "TOON_INTERMEDIATE_FORBIDDEN", step.id);
+    }
     if (Object.prototype.hasOwnProperty.call(input, "project_root") &&
         input.project_root !== projectRoot) {
         throw new BatchExecutionError(`Step "${step.id}" resolves a conflicting project_root.`, "PROJECT_ROOT_CONFLICT", step.id);
@@ -170,6 +173,11 @@ export async function runBatchDocument(document, options = {}) {
                 if (items.length > MAX_FOREACH_ITEMS) {
                     throw new BatchExecutionError(`Step "${step.id}" expands to ${items.length} items; maximum is ${MAX_FOREACH_ITEMS}.`, "FOREACH_LIMIT", step.id);
                 }
+                // Resolve once up front so one forbidden item cannot race valid sibling invocations.
+                // Resolve again inside mapLimit to avoid retaining up to 200 cloned input payloads.
+                for (const item of items) {
+                    injectProjectRoot(resolveTemplate(step.input, context, item), document.project_root, step);
+                }
                 reserveInvocations(items.length, step);
                 const results = await mapLimit(items, document.limits.concurrency, async (item) => {
                     const resolved = resolveTemplate(step.input, context, item);

package/dist/batch/schema.js

@@ -112,6 +112,9 @@ export function parseBatchDocument(input) {
     for (const [index, step] of parsed.steps.entries()) {
         if (ids.has(step.id))
             throw new Error(`Duplicate batch step id "${step.id}".`);
+        if (step.input.output_format === "toon") {
+            throw new Error(`Step "${step.id}" cannot request TOON for an intermediate batch result. Use CLI --output-format toon for the final output.`);
+        }
         if (Object.hasOwn(step.input, "project_root")) {
             if (step.input.project_root !== parsed.project_root) {
                 throw new Error(`Step "${step.id}" project_root conflicts with the pipeline project_root.`);

package/dist/cli-output.js

@@ -0,0 +1,28 @@
+import { Buffer } from "node:buffer";
+import { encode } from "@toon-format/toon";
+import { MAX_BATCH_OUTPUT_BYTES } from "./batch/schema.js";
+export class CliOutputError extends Error {
+    code;
+    constructor(message, code, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "CliOutputError";
+    }
+}
+export function serializeCliSuccess(value, outputFormat, maxBytes = MAX_BATCH_OUTPUT_BYTES) {
+    let serialized;
+    try {
+        serialized = outputFormat === "toon" ? encode(value) : JSON.stringify(value);
+    }
+    catch (error) {
+        throw new CliOutputError(`Failed to encode ${outputFormat.toUpperCase()} output.`, "ENCODING_ERROR", { cause: error });
+    }
+    if (serialized === undefined) {
+        throw new CliOutputError(`${outputFormat.toUpperCase()} output did not produce a document.`, "ENCODING_ERROR");
+    }
+    const bytes = Buffer.byteLength(serialized, "utf8");
+    if (bytes > maxBytes) {
+        throw new CliOutputError(`${outputFormat === "toon" ? "TOON" : "JSON"} output exceeds the ${maxBytes}-byte limit (${bytes} bytes encoded).`, "OUTPUT_LIMIT");
+    }
+    return serialized;
+}

package/dist/cli.js

@@ -4,7 +4,8 @@ import process from "node:process";
 import { createInterface } from "node:readline/promises";
 import { ZodError } from "zod";
 import { BatchExecutionError, parseBatchDocument, runBatchDocument } from "./batch/runner.js";
-import { MAX_BATCH_INPUT_BYTES } from "./batch/schema.js";
+import { MAX_BATCH_INPUT_BYTES, isPrepareBatchTool } from "./batch/schema.js";
+import { CliOutputError, serializeCliSuccess } from "./cli-output.js";
 import { applyPersistedOperation, persistOperationPlan } from "./services/operation-plan-file.js";
 import { AgentSetupError, detectInstalledAgents, resolveServerEntryPath, runAgentSetup, } from "./services/agent-setup.js";
 import { installBundledSkill, resolveBundledSkillPath, } from "./services/skill-installer.js";
@@ -28,7 +29,7 @@ class CliError extends Error {
 function usage() {
     return [
         "Usage:",
-        "  ast-tool run <pipeline.json|->",
+        "  ast-tool run <pipeline.json|-> [--output-format json|toon]",
         "  ast-tool validate <pipeline.json|->",
         "  ast-tool apply <plan.astplan> --plan-hash <sha256>",
         "  ast-tool install-skill [claude|hermes|all] [--scope user|project] [--project-root <path>] [--force]",
@@ -68,6 +69,32 @@ function parseApplyArgs(args) {
     }
     return { planFile: args[0], planHash: args[2] };
 }
+function parseRunArgs(args) {
+    let source;
+    let outputFormat = "json";
+    let outputFormatSeen = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === "--output-format") {
+            const value = args[index + 1];
+            if (outputFormatSeen || (value !== "json" && value !== "toon")) {
+                throw new CliError(usage(), "USAGE", 2, "run");
+            }
+            outputFormat = value;
+            outputFormatSeen = true;
+            index += 1;
+            continue;
+        }
+        if (source === undefined && !argument.startsWith("--")) {
+            source = argument;
+            continue;
+        }
+        throw new CliError(usage(), "USAGE", 2, "run");
+    }
+    if (!source)
+        throw new CliError(usage(), "USAGE", 2, "run");
+    return { source, outputFormat };
+}
 function parseInstallSkillArgs(args) {
     let target = "all";
     let targetSeen = false;
@@ -168,10 +195,14 @@ async function parseDocumentForCommand(source, command) {
 export async function runCli(args) {
     const [command, ...commandArgs] = args;
     if (command === "run" || command === "validate") {
-        if (commandArgs.length !== 1 || !commandArgs[0]) {
+        const runArgs = command === "run"
+            ? parseRunArgs(commandArgs)
+            : commandArgs.length === 1 && commandArgs[0]
+                ? { source: commandArgs[0], outputFormat: "json" }
+                : undefined;
+        if (!runArgs)
             throw new CliError(usage(), "USAGE", 2, command);
-        }
-        const document = await parseDocumentForCommand(commandArgs[0], command);
+        const document = await parseDocumentForCommand(runArgs.source, command);
         if (command === "validate") {
             return {
                 version: 1,
@@ -179,6 +210,10 @@ export async function runCli(args) {
                 step_count: document.steps.length,
             };
         }
+        if (runArgs.outputFormat === "toon" &&
+            document.steps.some((step) => isPrepareBatchTool(step.tool))) {
+            throw new CliError("TOON output is available only for read-only batches; prepare results require JSON review coordinates.", "INVALID_BATCH", 2, command);
+        }
         try {
             return await runBatchDocument(document, {
                 persistPreparedOperation: (operationId) => persistOperationPlan(operationId),
@@ -262,7 +297,7 @@ export async function runCli(args) {
     }
     throw new CliError(usage(), "USAGE", 2, command ?? null);
 }
-function failure(error) {
+function failure(error, command = null) {
     if (error instanceof CliError) {
         return {
             value: {
@@ -276,6 +311,17 @@ function failure(error) {
             exitCode: error.exitCode,
         };
     }
+    if (error instanceof CliOutputError) {
+        return {
+            value: {
+                status: "error",
+                command,
+                code: error.code,
+                message: error.message,
+            },
+            exitCode: 1,
+        };
+    }
     return {
         value: {
             status: "error",
@@ -287,12 +333,14 @@ function failure(error) {
     };
 }
 async function main() {
+    const args = process.argv.slice(2);
     try {
-        const result = await runCli(process.argv.slice(2));
-        process.stdout.write(`${JSON.stringify(result)}\n`);
+        const result = await runCli(args);
+        const outputFormat = args[0] === "run" ? parseRunArgs(args.slice(1)).outputFormat : "json";
+        process.stdout.write(`${serializeCliSuccess(result, outputFormat)}\n`);
     }
     catch (error) {
-        const failed = failure(error);
+        const failed = failure(error, args[0] ?? null);
         process.stderr.write(`${JSON.stringify(failed.value)}\n`);
         process.exitCode = failed.exitCode;
     }

package/dist/tools/find_references.js

@@ -3,7 +3,7 @@ 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 AstFindReferencesInputSchema = z.object({
     project_root: z
         .string()
@@ -11,6 +11,7 @@ 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),
+    ...ToolOutputFormatInputSchema,
     ...PaginationInputSchema,
 });
 const ReferenceSchema = z.object({
@@ -34,14 +35,13 @@ export function registerFindReferences(server) {
         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, output_format, offset, limit, }) => {
         try {
             const structuredContent = await withProject(project_root, ({ project, projectRoot }) => {
                 const sourceFile = getSourceFileOrThrow(project, file_path);
@@ -88,7 +88,7 @@ export function registerFindReferences(server) {
                     ...metadata,
                 };
             });
-            return structuredResult(structuredContent);
+            return formattedResult(AstFindReferencesOutputSchema, 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/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/search_symbols.js

@@ -4,7 +4,7 @@ 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";
+import { errorResult, formattedResult, ToolOutputFormatInputSchema } from "./result.js";
 const AstSearchSymbolsInputSchema = z.object({
     project_root: z
         .string()
@@ -21,6 +21,7 @@ const AstSearchSymbolsInputSchema = z.object({
         .string()
         .optional()
         .describe("Optional case-insensitive substring matched against project-relative file paths."),
+    ...ToolOutputFormatInputSchema,
     ...PaginationInputSchema,
 });
 const SearchSymbolSchema = z.object({
@@ -42,14 +43,13 @@ export function registerSearchSymbols(server) {
         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 }) => {
+    }, async ({ project_root, query, kinds, file_filter, output_format, offset, limit }) => {
         try {
             const structuredContent = await withProject(project_root, ({ project, projectRoot }) => {
                 const startedAt = performance.now();
@@ -92,7 +92,7 @@ export function registerSearchSymbols(server) {
                     ...metadata,
                 };
             });
-            return structuredResult(structuredContent);
+            return formattedResult(AstSearchSymbolsOutputSchema, 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.4.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,7 @@
     "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",
     "lint": "eslint src test scripts vitest.config.ts eslint.config.js",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
@@ -62,6 +66,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,6 +75,7 @@
     "@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",

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: "3.4.0"
 author: "yail"
 license: "ISC"
 metadata:
@@ -49,6 +49,20 @@ El setup falla cerrado ante un registro `ast` conflictivo. No eliminar ni reempl
 
 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,7 +73,7 @@ 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