ast-mcp-server 0.5.0 → 0.6.0

package/dist/tools/find_references.js

@@ -1,8 +1,7 @@
-import path from "node:path";
-import { Node } from "ts-morph";
 import { z } from "zod";
-import { PaginationInputSchema, PaginationOutputSchema, paginate } from "../services/pagination.js";
+import { PaginationInputSchema, PaginationOutputSchema } from "../services/pagination.js";
 import { findDeclarationByName, getSourceFileOrThrow, withProject } from "../services/project.js";
+import { collectSymbolReferences } from "../services/references.js";
 import { errorResult, formattedResult, ToolOutputFormatInputSchema } from "./result.js";
 const ReferenceDetailSchema = z.enum(["locations", "context"]).default("locations");
 const AstFindReferencesInputSchema = z.object({
@@ -59,55 +58,19 @@ export function registerFindReferences(server) {
             const structuredContent = await withProject(project_root, ({ project, projectRoot }) => {
                 const sourceFile = getSourceFileOrThrow(project, file_path);
                 const node = findDeclarationByName(sourceFile, symbol_path);
-                if (!Node.isReferenceFindable(node)) {
-                    throw new Error(`Symbol "${symbol_path}" (${node.getKindName()}) does not support semantic reference search.`);
-                }
-                const lineCache = new Map();
-                const location = (referenceNode, isDeclaration) => {
-                    const referenceSource = referenceNode.getSourceFile();
-                    const absoluteFile = referenceSource.getFilePath();
-                    let lines = lineCache.get(absoluteFile);
-                    if (!lines) {
-                        lines = referenceSource.getFullText().split(/\r?\n/);
-                        lineCache.set(absoluteFile, lines);
-                    }
-                    const position = referenceSource.getLineAndColumnAtPos(referenceNode.getStart());
-                    return {
-                        file: path.relative(projectRoot, absoluteFile),
-                        line: position.line,
-                        column: position.column,
-                        kind: referenceNode.getParent()?.getKindName() ?? referenceNode.getKindName(),
-                        is_declaration: isDeclaration,
-                        context: (lines[position.line - 1] ?? "").trim().slice(0, 500),
-                    };
-                };
-                const references = node
-                    .findReferencesAsNodes()
-                    .map((reference) => location(reference, false));
-                const declaration = location(node, true);
-                const allLocations = include_declaration ? [declaration, ...references] : references;
-                allLocations.sort((left, right) => `${left.file}:${left.line}:${left.column}:${left.is_declaration ? 0 : 1}`.localeCompare(`${right.file}:${right.line}:${right.column}:${right.is_declaration ? 0 : 1}`));
-                const affectedFiles = [
-                    ...new Set([declaration, ...references].map((item) => item.file)),
-                ].sort();
-                const page = paginate(allLocations, offset, limit);
-                const { items, ...metadata } = page;
+                const collected = collectSymbolReferences(node, projectRoot, symbol_path, include_declaration, detail, offset, limit);
+                const { references, ...metadata } = collected;
                 return {
-                    symbol: symbol_path,
-                    include_declaration,
-                    declaration_count: 1,
-                    reference_count: references.length,
-                    affected_files: affectedFiles,
+                    ...metadata,
                     references: detail === "context"
-                        ? items
-                        : items.map(({ file, line, column, kind, is_declaration }) => ({
+                        ? references
+                        : references.map(({ file, line, column, kind, is_declaration }) => ({
                             file,
                             line,
                             column,
                             kind,
                             is_declaration,
                         })),
-                    ...metadata,
                 };
             });
             const outputSchema = ReferenceOutputSchemas[detail];

package/dist/tools/get_file.js

@@ -0,0 +1,95 @@
+import { z } from "zod";
+import { DEFAULT_FILE_LINE_LIMIT, MAX_FILE_LINE_LIMIT, readFileSnapshot, } from "../services/file-snapshot.js";
+import { buildFileOutline } from "../services/outline.js";
+import { getSourceFileOrThrow, withProject } from "../services/project.js";
+import { errorResult, structuredResult } from "./result.js";
+const AstGetFileInputSchema = z.object({
+    project_root: z
+        .string()
+        .describe("Absolute project directory containing tsconfig.json, or the config path."),
+    file_path: z
+        .string()
+        .describe("Project-relative or unambiguous source file path included by the active tsconfig."),
+    offset: z.number().int().min(0).default(0).describe("Zero-based line offset for source mode."),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_FILE_LINE_LIMIT)
+        .default(DEFAULT_FILE_LINE_LIMIT)
+        .describe(`Maximum source lines to return, capped at ${MAX_FILE_LINE_LIMIT}.`),
+    symbols_only: z
+        .boolean()
+        .default(false)
+        .describe("Return body-free symbol selectors and signatures instead of source lines."),
+});
+const FileRangeSchema = z.object({
+    offset: z.number().int().min(0),
+    limit: z.number().int().min(1).max(MAX_FILE_LINE_LIMIT),
+    total_lines: z.number().int().min(0),
+});
+const FileLineSchema = z.object({
+    line: z.number().int().positive(),
+    text: z.string(),
+});
+const OutlineSymbolSchema = z.object({
+    symbolPath: z.string(),
+    name: z.string(),
+    kind: z.string(),
+    signature: z.string(),
+    startLine: z.number().int().positive(),
+    endLine: z.number().int().positive(),
+});
+const FileSnapshotBaseSchema = {
+    file: z.string(),
+    file_hash: z.string().regex(/^[0-9a-f]{64}$/),
+    snapshot_state: z.enum(["fresh", "stale"]),
+};
+const AstGetFileOutputSchema = z.object({
+    mode: z.enum(["source", "symbols_only"]),
+    ...FileSnapshotBaseSchema,
+    range: FileRangeSchema.optional(),
+    lines: z.array(FileLineSchema).optional(),
+    symbols: z.array(OutlineSymbolSchema).optional(),
+});
+export function registerGetFile(server) {
+    server.registerTool("ast_get_file", {
+        title: "Get bounded source file",
+        description: "Returns exact bounded source lines for one TypeScript/JavaScript file, or body-free symbols when symbols_only is true. Read-only; freshness is reported separately from compiler diagnostics.",
+        inputSchema: AstGetFileInputSchema,
+        outputSchema: AstGetFileOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ project_root, file_path, offset, limit, symbols_only }) => {
+        try {
+            const structuredContent = await withProject(project_root, async ({ project, projectRoot }) => {
+                const snapshot = await readFileSnapshot(project, projectRoot, file_path, {
+                    offset,
+                    limit,
+                });
+                if (!symbols_only) {
+                    return {
+                        mode: "source",
+                        ...snapshot,
+                    };
+                }
+                const sourceFile = getSourceFileOrThrow(project, file_path);
+                return {
+                    mode: "symbols_only",
+                    file: snapshot.file,
+                    file_hash: snapshot.file_hash,
+                    snapshot_state: snapshot.snapshot_state,
+                    symbols: buildFileOutline(sourceFile).symbols,
+                };
+            });
+            return structuredResult(structuredContent);
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+}

package/dist/tools/get_project_status.js

@@ -0,0 +1,68 @@
+import { z } from "zod";
+import { FRESHNESS_CAUSES, SNAPSHOT_STATES, TRUNCATION_REASONS, } from "../services/read-contracts.js";
+import { getProjectStatus } from "../services/project.js";
+import { errorResult, structuredResult } from "./result.js";
+const AstGetProjectStatusInputSchema = z.object({
+    project_root: z
+        .string()
+        .describe("Absolute project directory containing tsconfig.json, or the config path."),
+});
+const TruncationMetadataSchema = z.object({
+    truncated: z.boolean(),
+    reason: z.enum(TRUNCATION_REASONS).nullable(),
+});
+const ProjectStatusOutputSchema = z.object({
+    project: z.object({
+        project_id: z.string().regex(/^project_[0-9a-f]{20}$/),
+        config_id: z
+            .string()
+            .regex(/^config_[0-9a-f]{20}$/)
+            .nullable(),
+    }),
+    state: z.enum(SNAPSHOT_STATES),
+    causes: z.array(z.enum(FRESHNESS_CAUSES)),
+    source_count: z.number().int().min(0),
+    indexed_count: z.number().int().min(0),
+    pending_files: z.array(z.string()),
+    pending_files_truncated: z.boolean(),
+    pending_files_truncation: TruncationMetadataSchema,
+    pending_files_filename_truncation: TruncationMetadataSchema,
+    compiler: z.object({ state: z.enum(["ready", "rebuilding", "failed"]) }),
+    index: z.object({ state: z.literal("disabled") }),
+    operation_queue: z.object({
+        state: z.enum(["idle", "queued", "running"]),
+        active_operations: z.number().int().min(0),
+        queued_operations: z.number().int().min(0),
+    }),
+    watcher: z.object({ state: z.enum(["disabled", "ready", "failed"]) }),
+    last_successful_sync_at: z.string().nullable(),
+    last_successful_index_at: z.null(),
+    source_snapshot_fingerprint: z.string().nullable(),
+    config_snapshot_fingerprint: z.string().nullable(),
+    canonical_snapshot_fingerprint: z.string().nullable(),
+    degraded_errors: z.array(z.string()),
+    degraded_errors_truncation: TruncationMetadataSchema,
+    degraded_errors_text_truncation: TruncationMetadataSchema,
+});
+export function registerGetProjectStatus(server) {
+    server.registerTool("ast_get_project_status", {
+        title: "Get project freshness status",
+        description: "Returns bounded, read-only compiler freshness and project status without exposing filesystem identities or credentials.",
+        inputSchema: AstGetProjectStatusInputSchema,
+        outputSchema: ProjectStatusOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ project_root }) => {
+        try {
+            const output = await getProjectStatus(project_root);
+            return structuredResult({ ...output });
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+}

package/dist/tools/search_symbols.js

@@ -1,9 +1,7 @@
-import path from "node:path";
 import { z } from "zod";
-import { buildFileOutline } from "../services/outline.js";
 import { createPaginationInputSchema, PaginationOutputSchema, paginate, } from "../services/pagination.js";
 import { withProject } from "../services/project.js";
-import { collectSymbols, symbolMatchRank } from "../services/symbols.js";
+import { searchProjectSymbols } 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");
@@ -92,57 +90,10 @@ export function registerSearchSymbols(server) {
         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) => {
-                        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) => [
-                        `${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) => {
-                    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 matches = searchProjectSymbols(project, projectRoot, {
+                    query,
+                    kinds,
+                    fileFilter: file_filter,
                 });
                 const page = paginate(matches, offset, limit);
                 const { items, ...metadata } = page;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ast-mcp-server",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Structural code MCP server and batch CLI for compact TypeScript/JavaScript reads and hash-bound AST edits.",
   "keywords": [
     "mcp",
@@ -56,6 +56,7 @@
     "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",
+    "benchmark:agent-workflows": "yarn build && node scripts/benchmark-agent-workflows.mjs",
     "lint": "eslint src test scripts vitest.config.ts eslint.config.js",
     "format": "prettier --write .",
     "format:check": "prettier --check .",

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

@@ -17,6 +17,7 @@ metadata:
 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;
+- leer rangos acotados del source exacto de un archivo conocido;
 - encontrar declaraciones o referencias reales;
 - medir el radio de impacto de un rename;
 - renombrar un símbolo en varios archivos;
@@ -40,16 +41,22 @@ El setup falla cerrado ante un registro `ast` conflictivo. No eliminar ni reempl
 ## 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.
+2. `ast_explore` para una pregunta de lectura que combine descubrimiento y evidencia. Usar `summary` por defecto, `context` para source seleccionado y `full` para source más referencias.
+3. `ast_get_file` si ya se conoce el archivo y hace falta source exacto. Usar `offset`/`limit`; no cargar el archivo completo por defecto.
+4. `ast_search_symbols` si todavía no se conoce el archivo o el selector exacto.
+5. `ast_get_outline` para ver contratos sin cuerpos. No pedir `include_symbols` salvo que haga falta la metadata detallada.
+6. `ast_get_symbol_source` solo para las declaraciones cuya implementación haya que inspeccionar.
+7. `ast_find_references` antes de renames o cambios con impacto cross-file.
+8. `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.
 
+`ast_get_file` es read-only y solo acepta archivos incluidos por el tsconfig activo. Su modo normal devuelve líneas exactas, paginadas y numeradas desde 1, junto con el hash SHA-256 de los bytes actuales. `symbols_only: true` devuelve selectors y signatures sin cuerpos. `snapshot_state: "fresh"` describe sincronización con el snapshot del compilador, no ausencia de diagnostics; consultar `ast_get_diagnostics` por separado.
+
+`ast_explore` es read-only y no prepara ni aplica operaciones. Sus selectors son directamente reutilizables por las tools primitivas y de mutación. La respuesta declara `freshness`, `completeness`, `truncation`, `unresolved` y `budget`; si el límite de bytes impide incluir todo el contexto, el resultado queda marcado como incompleto.
+
 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