ast-mcp-server 0.5.0 → 0.6.0

package/dist/services/project.js

@@ -2,7 +2,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { Project } from "ts-morph";
 import { findDeclaration } from "./symbols.js";
-import { createConfigSnapshot } from "./workspace.js";
+import { createConfigSnapshot, createWorkspaceSnapshot } from "./workspace.js";
+import { createInitialProjectStatus, createProjectIdentity, projectStatusToProjection, transitionProjectStatus, } from "./project-status.js";
 const MAX_PROJECT_SESSIONS = 8;
 const projectSessions = new Map();
 const projectRoots = new WeakMap();
@@ -25,7 +26,8 @@ function buildProjectContext(tsConfigFilePath) {
     });
     const projectRoot = path.dirname(tsConfigFilePath);
     projectRoots.set(project, projectRoot);
-    return { project, projectRoot, tsConfigFilePath };
+    const status = createInitialProjectStatus(createProjectIdentity({ projectRoot, configPath: tsConfigFilePath }), { sourceCount: project.getSourceFiles().length });
+    return { project, projectRoot, tsConfigFilePath, status };
 }
 export function createFreshProject(projectRoot) {
     return buildProjectContext(resolveTsConfigPath(projectRoot));
@@ -50,41 +52,113 @@ function getOrCreateSession(projectRoot) {
         configDigest: createConfigSnapshot(tsConfigFilePath).digest,
         queue: Promise.resolve(),
         activeOperations: 0,
+        runningOperations: 0,
+        queuedOperations: 0,
         lastAccessedAt: Date.now(),
     };
     projectSessions.set(tsConfigFilePath, session);
     return session;
 }
+function getQueueStatus(session) {
+    return {
+        state: session.runningOperations > 0 ? "running" : session.queuedOperations > 0 ? "queued" : "idle",
+        active_operations: session.runningOperations,
+        queued_operations: session.queuedOperations,
+    };
+}
 async function synchronizeSession(session) {
-    const currentConfigDigest = createConfigSnapshot(session.context.tsConfigFilePath).digest;
-    if (currentConfigDigest !== session.configDigest) {
-        session.context = buildProjectContext(session.context.tsConfigFilePath);
-        session.configDigest = currentConfigDigest;
-        return;
+    let syncFailureCause = "compiler_rebuild";
+    let currentConfigDigest;
+    try {
+        currentConfigDigest = createConfigSnapshot(session.context.tsConfigFilePath).digest;
+        if (currentConfigDigest !== session.configDigest) {
+            let status = transitionProjectStatus(session.context.status, { type: "config_changed" });
+            status = transitionProjectStatus(status, { type: "compiler_rebuild_started" });
+            const rebuilt = buildProjectContext(session.context.tsConfigFilePath);
+            session.context = { ...rebuilt, status };
+        }
+        const { project, tsConfigFilePath } = session.context;
+        syncFailureCause = "source_change";
+        const refreshSourceFiles = async () => {
+            project.addSourceFilesFromTsConfig(tsConfigFilePath);
+            await Promise.all(project.getSourceFiles().map((sourceFile) => sourceFile.refreshFromFileSystem()));
+        };
+        await refreshSourceFiles();
+        const snapshot = createWorkspaceSnapshot(session.context);
+        if (snapshot.configDigest !== currentConfigDigest) {
+            syncFailureCause = "config_change";
+            throw new Error("Project configuration changed during synchronization. Retry the operation.");
+        }
+        await refreshSourceFiles();
+        const verificationSnapshot = createWorkspaceSnapshot(session.context);
+        if (verificationSnapshot.configDigest !== currentConfigDigest) {
+            syncFailureCause = "config_change";
+            throw new Error("Project configuration changed during synchronization. Retry the operation.");
+        }
+        if (verificationSnapshot.sourceDigest !== snapshot.sourceDigest) {
+            syncFailureCause = "source_change";
+            throw new Error("Project source changed during synchronization. Retry the operation.");
+        }
+        const status = transitionProjectStatus(session.context.status, {
+            type: "sync_succeeded",
+            sourceCount: verificationSnapshot.sourceFileCount,
+            indexedCount: 0,
+            sourceSnapshotFingerprint: `source_${verificationSnapshot.sourceDigest}`,
+            configSnapshotFingerprint: `config_${verificationSnapshot.configDigest}`,
+            canonicalSnapshotFingerprint: `snapshot_${verificationSnapshot.digest}`,
+            at: new Date().toISOString(),
+        });
+        session.context = { ...session.context, status };
+        session.configDigest = verificationSnapshot.configDigest;
+    }
+    catch (error) {
+        const status = transitionProjectStatus(session.context.status, {
+            type: "sync_failed",
+            cause: syncFailureCause,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        session.context = { ...session.context, status };
+        throw error;
     }
-    const { project, tsConfigFilePath } = session.context;
-    project.addSourceFilesFromTsConfig(tsConfigFilePath);
-    await Promise.all(project.getSourceFiles().map((sourceFile) => sourceFile.refreshFromFileSystem()));
 }
-export async function withProject(projectRoot, operation) {
-    const session = getOrCreateSession(projectRoot);
+async function runSessionWithSyncPolicy(session, operation, allowSynchronizationFailure) {
     session.activeOperations += 1;
+    session.queuedOperations += 1;
     let release;
     const previous = session.queue;
     session.queue = new Promise((resolve) => {
         release = resolve;
     });
     await previous;
+    session.queuedOperations -= 1;
+    session.runningOperations += 1;
     try {
-        await synchronizeSession(session);
+        try {
+            await synchronizeSession(session);
+        }
+        catch (error) {
+            if (!allowSynchronizationFailure)
+                throw error;
+        }
         session.lastAccessedAt = Date.now();
         return await operation(session.context);
     }
     finally {
+        session.runningOperations -= 1;
         session.activeOperations -= 1;
         release?.();
     }
 }
+export async function withProject(projectRoot, operation) {
+    return runSessionWithSyncPolicy(getOrCreateSession(projectRoot), operation, false);
+}
+export async function getProjectStatus(projectRoot) {
+    const session = getOrCreateSession(projectRoot);
+    return runSessionWithSyncPolicy(session, (context) => ({
+        ...projectStatusToProjection(context.status),
+        operation_queue: getQueueStatus(session),
+    }), true);
+}
 // Compatibility API for internal scripts. MCP tools should use withProject().
 export function getProject(projectRoot) {
     return createFreshProject(projectRoot).project;

package/dist/services/read-contracts.js

@@ -0,0 +1,159 @@
+export const SNAPSHOT_STATES = Object.freeze([
+    "fresh",
+    "pending",
+    "stale",
+    "rebuilding",
+    "degraded",
+]);
+export function isSnapshotState(value) {
+    return SNAPSHOT_STATES.some((state) => state === value);
+}
+export const FRESHNESS_CAUSES = Object.freeze([
+    "source_change",
+    "config_change",
+    "index_failure",
+    "watcher_failure",
+    "compiler_rebuild",
+]);
+export function isFreshnessCause(value) {
+    return FRESHNESS_CAUSES.some((cause) => cause === value);
+}
+function assertIntegerAtLeast(value, minimum, name) {
+    if (!Number.isInteger(value) || value < minimum) {
+        throw new Error(`${name} must be an integer greater than or equal to ${minimum}.`);
+    }
+}
+export function createFileRange(offset, limit, totalLines) {
+    assertIntegerAtLeast(offset, 0, "File range offset");
+    assertIntegerAtLeast(limit, 1, "File range limit");
+    assertIntegerAtLeast(totalLines, 0, "File range total_lines");
+    return { offset, limit, total_lines: totalLines };
+}
+function projectRelativePath(file) {
+    let unquoted = file.trim();
+    const quote = unquoted[0];
+    if (unquoted.length >= 2 &&
+        (quote === '"' || quote === "'" || quote === "`") &&
+        unquoted.endsWith(quote)) {
+        unquoted = unquoted.slice(1, -1).trim();
+    }
+    const normalized = unquoted.replaceAll("\\", "/");
+    const relative = normalized.startsWith("./") ? normalized.slice(2) : normalized;
+    const segments = relative.split("/");
+    const isWindowsAbsolute = /^[A-Za-z]:/.test(relative);
+    if (relative.length === 0 ||
+        relative.startsWith("/") ||
+        isWindowsAbsolute ||
+        segments.some((segment) => segment.length === 0 || segment === ".." || segment === ".")) {
+        throw new Error("Source location file must be project-relative.");
+    }
+    return relative;
+}
+export function createSourceLocation(file, range) {
+    if (typeof file !== "string" || typeof range !== "object" || range === null) {
+        throw new Error("Source location input is invalid.");
+    }
+    assertIntegerAtLeast(range.start_line, 1, "Source location start_line");
+    if (range.start_column !== undefined) {
+        assertIntegerAtLeast(range.start_column, 1, "Source location start_column");
+    }
+    if (range.end_line !== undefined) {
+        assertIntegerAtLeast(range.end_line, range.start_line, "Source location end_line");
+    }
+    if (range.end_column !== undefined) {
+        assertIntegerAtLeast(range.end_column, 1, "Source location end_column");
+    }
+    if (range.end_line === range.start_line &&
+        range.start_column !== undefined &&
+        range.end_column !== undefined &&
+        range.end_column < range.start_column) {
+        throw new Error("Source location end_column must not precede start_column.");
+    }
+    return {
+        file: projectRelativePath(file),
+        start_line: range.start_line,
+        ...(range.start_column === undefined ? {} : { start_column: range.start_column }),
+        ...(range.end_line === undefined ? {} : { end_line: range.end_line }),
+        ...(range.end_column === undefined ? {} : { end_column: range.end_column }),
+    };
+}
+export const TRUNCATION_REASONS = Object.freeze([
+    "record_limit",
+    "byte_limit",
+    "depth_limit",
+    "edge_limit",
+    "invocation_limit",
+    "serialization_limit",
+]);
+export function isTruncationReason(value) {
+    return TRUNCATION_REASONS.some((reason) => reason === value);
+}
+export function createTruncationMetadata(truncated, reason = null) {
+    if (reason !== null && !isTruncationReason(reason)) {
+        throw new Error(`Unknown truncation reason: ${String(reason)}.`);
+    }
+    if (truncated !== (reason !== null)) {
+        throw new Error("A truncated result requires a machine-readable reason, and a complete result does not.");
+    }
+    return { truncated, reason };
+}
+export function isJsonValue(value) {
+    const ancestors = new Set();
+    function visit(candidate) {
+        if (candidate === null)
+            return true;
+        if (typeof candidate === "string" || typeof candidate === "boolean")
+            return true;
+        if (typeof candidate === "number") {
+            return Number.isFinite(candidate) && !Object.is(candidate, -0);
+        }
+        if (typeof candidate !== "object")
+            return false;
+        if (ancestors.has(candidate))
+            return false;
+        ancestors.add(candidate);
+        try {
+            if ("toJSON" in candidate)
+                return false;
+            if (Array.isArray(candidate)) {
+                if (Object.getPrototypeOf(candidate) !== Array.prototype)
+                    return false;
+                if (Object.getOwnPropertySymbols(candidate).length > 0)
+                    return false;
+                for (let index = 0; index < candidate.length; index += 1) {
+                    if (!Object.hasOwn(candidate, index))
+                        return false;
+                    const descriptor = Object.getOwnPropertyDescriptor(candidate, String(index));
+                    if (descriptor === undefined || !("value" in descriptor) || !visit(descriptor.value)) {
+                        return false;
+                    }
+                }
+                return Object.getOwnPropertyNames(candidate).every((key) => {
+                    if (key === "length")
+                        return true;
+                    const index = Number(key);
+                    return (Number.isInteger(index) &&
+                        index >= 0 &&
+                        index < candidate.length &&
+                        String(index) === key);
+                });
+            }
+            const prototype = Object.getPrototypeOf(candidate);
+            if (prototype !== Object.prototype && prototype !== null)
+                return false;
+            if (Object.getOwnPropertySymbols(candidate).length > 0)
+                return false;
+            return Object.getOwnPropertyNames(candidate).every((key) => {
+                const descriptor = Object.getOwnPropertyDescriptor(candidate, key);
+                return (descriptor !== undefined &&
+                    descriptor.enumerable &&
+                    "value" in descriptor &&
+                    visit(descriptor.value));
+            });
+        }
+        finally {
+            ancestors.delete(candidate);
+        }
+    }
+    return visit(value);
+}

package/dist/services/references.js

@@ -0,0 +1,48 @@
+import path from "node:path";
+import { Node } from "ts-morph";
+import { paginate } from "./pagination.js";
+export function collectSymbolReferences(node, projectRoot, symbolPath, includeDeclaration, detail, offset, limit) {
+    if (!Node.isReferenceFindable(node)) {
+        throw new Error(`Symbol "${symbolPath}" (${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,
+            ...(detail === "context"
+                ? { 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 = includeDeclaration ? [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);
+    return {
+        symbol: symbolPath,
+        include_declaration: includeDeclaration,
+        declaration_count: 1,
+        reference_count: references.length,
+        affected_files: affectedFiles,
+        references: page.items,
+        offset: page.offset,
+        limit: page.limit,
+        total: page.total,
+        has_more: page.has_more,
+        next_offset: page.next_offset,
+    };
+}

package/dist/services/symbols.js

@@ -1,4 +1,22 @@
+import path from "node:path";
 import { Node, } from "ts-morph";
+import { buildFileOutline } from "./outline.js";
+export function sourceFileSymbols(sourceFile, projectRoot) {
+    const file = path.relative(projectRoot, sourceFile.getFilePath());
+    const signatures = new Map(buildFileOutline(sourceFile).symbols.map((symbol) => [
+        `${symbol.symbolPath}@${symbol.startLine}`,
+        symbol.signature,
+    ]));
+    return collectSymbols(sourceFile).map((symbol) => ({
+        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(),
+    }));
+}
 export function symbolMatchRank(query, symbol) {
     const normalizedQuery = query.toLowerCase();
     const normalizedPath = symbol.symbolPath.toLowerCase();
@@ -15,6 +33,47 @@ export function symbolMatchRank(query, symbol) {
     }
     return 4;
 }
+export function searchProjectSymbols(project, projectRoot, options) {
+    const normalizedQuery = options.query.toLowerCase();
+    const normalizedFileFilter = options.fileFilter?.toLowerCase();
+    const kindSet = options.kinds ? new Set(options.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 = sourceFileSymbols(sourceFile, projectRoot).filter((symbol) => {
+            return ((!kindSet || kindSet.has(symbol.kind)) &&
+                (symbol.name.toLowerCase().includes(normalizedQuery) ||
+                    symbol.symbol_path.toLowerCase().includes(normalizedQuery) ||
+                    symbol.selector.toLowerCase().includes(normalizedQuery)));
+        });
+        if (matchingSymbols.length === 0)
+            continue;
+        for (const symbol of matchingSymbols) {
+            matches.push(symbol);
+        }
+    }
+    matches.sort((left, right) => {
+        const rank = symbolMatchRank(options.query, {
+            symbolPath: left.symbol_path,
+            name: left.name,
+            line: left.line,
+        }) -
+            symbolMatchRank(options.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));
+    });
+    return matches;
+}
 function namedNode(node) {
     if (Node.isConstructorDeclaration(node))
         return "constructor";

package/dist/services/workspace.js

@@ -65,12 +65,15 @@ export function createConfigSnapshot(rootConfigPath) {
 export function createWorkspaceSnapshot(context) {
     const sourcePaths = context.project
         .getSourceFiles()
-        .map((sourceFile) => sourceFile.getFilePath());
-    const paths = [...sourcePaths, ...createConfigSnapshot(context.tsConfigFilePath).files]
-        .map(canonicalPath)
-        .sort();
-    const files = new Map();
-    for (const filePath of paths) {
+        .map((sourceFile) => canonicalPath(sourceFile.getFilePath()));
+    const configSnapshot = createConfigSnapshot(context.tsConfigFilePath);
+    const sourceFiles = new Map();
+    for (const filePath of [...new Set(sourcePaths)].sort()) {
+        const digest = hashBytes(fs.readFileSync(filePath));
+        sourceFiles.set(filePath, digest);
+    }
+    const files = new Map(sourceFiles);
+    for (const filePath of configSnapshot.files) {
         const digest = hashBytes(fs.readFileSync(filePath));
         const previous = files.get(filePath);
         if (previous && previous !== digest) {
@@ -80,6 +83,9 @@ export function createWorkspaceSnapshot(context) {
     }
     return {
         digest: hashWorkspaceFiles(files),
+        sourceDigest: hashWorkspaceFiles(sourceFiles),
+        configDigest: configSnapshot.digest,
+        sourceFileCount: sourceFiles.size,
         fileCount: files.size,
         files,
     };

package/dist/tools/explore.js

@@ -0,0 +1,174 @@
+import { z } from "zod";
+import { buildExploreContext, EXPLORE_DEFAULT_LIMIT, EXPLORE_DEFAULT_MAX_BYTES, EXPLORE_DEFAULT_REFERENCE_LIMIT, EXPLORE_MAX_BYTES, } from "../services/context-builder.js";
+import { createPaginationInputSchema } from "../services/pagination.js";
+import { withProject } from "../services/project.js";
+import { FRESHNESS_CAUSES, SNAPSHOT_STATES, TRUNCATION_REASONS, } from "../services/read-contracts.js";
+import { errorResult, structuredResult } from "./result.js";
+const ExploreDetailSchema = z.enum(["selectors", "summary", "context", "full"]).default("summary");
+const ReferenceDetailSchema = z.enum(["locations", "context"]).default("locations");
+const ExploreInputSchema = z
+    .object({
+    project_root: z
+        .string()
+        .describe("Absolute project directory containing tsconfig.json, or the config path."),
+    query: z.string().min(1).optional().describe("Bounded case-insensitive symbol query."),
+    file_path: z.string().optional().describe("Known project-relative or unambiguous source file."),
+    symbol_path: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Exact symbol path or selector, valid only with file_path."),
+    kinds: z.array(z.string()).max(32).optional().describe("Optional exact syntax-kind filters."),
+    file_filter: z.string().optional().describe("Optional query-route file path substring filter."),
+    detail: ExploreDetailSchema.describe("selectors returns routing coordinates; summary adds signatures; context adds source; full adds source and references."),
+    include_source: z
+        .boolean()
+        .optional()
+        .describe("Override detail-based source expansion for selected symbols."),
+    include_references: z
+        .boolean()
+        .optional()
+        .describe("Override detail-based compiler reference expansion for selected symbols."),
+    reference_detail: ReferenceDetailSchema.describe("Reference locations or bounded source-line context."),
+    reference_limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .default(EXPLORE_DEFAULT_REFERENCE_LIMIT)
+        .describe("Maximum compiler references per selected symbol."),
+    ...createPaginationInputSchema(EXPLORE_DEFAULT_LIMIT),
+    max_bytes: z
+        .number()
+        .int()
+        .min(1024)
+        .max(EXPLORE_MAX_BYTES)
+        .default(EXPLORE_DEFAULT_MAX_BYTES)
+        .describe("Maximum serialized logical result size in UTF-8 bytes."),
+})
+    .refine((input) => Boolean(input.query || input.file_path), {
+    message: "Provide query, file_path, or both file_path and symbol_path.",
+    path: ["query"],
+})
+    .refine((input) => !input.symbol_path || Boolean(input.file_path), {
+    message: "symbol_path requires file_path so the exact declaration can be resolved.",
+    path: ["symbol_path"],
+});
+const ExploreSymbolSchema = z.object({
+    file: z.string(),
+    selector: z.string(),
+    kind: z.string(),
+    symbol_path: z.string().optional(),
+    name: z.string().optional(),
+    line: z.number().int().positive().optional(),
+    signature: z.string().optional(),
+});
+const ExploreSourceSchema = z.object({
+    file: z.string(),
+    startLine: z.number().int().positive(),
+    endLine: z.number().int().positive(),
+    text: z.string(),
+});
+const ExploreReferenceSchema = z.object({
+    file: z.string(),
+    line: z.number().int().positive(),
+    column: z.number().int().positive(),
+    kind: z.string(),
+    is_declaration: z.boolean(),
+    context: z.string().optional(),
+});
+const ExploreEvidenceSchema = z.object({
+    selector: z.string(),
+    source: ExploreSourceSchema.optional(),
+    references: z
+        .object({
+        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(ExploreReferenceSchema),
+        offset: z.number().int().min(0),
+        limit: z.number().int().positive(),
+        total: z.number().int().min(0),
+        has_more: z.boolean(),
+        next_offset: z.number().int().min(0).nullable(),
+    })
+        .optional(),
+});
+const ExploreOutputSchema = z.object({
+    route: z.enum(["query", "file", "symbol"]),
+    query: z.string().nullable(),
+    file: z.string().nullable(),
+    symbol: z.string().nullable(),
+    detail: ExploreDetailSchema,
+    symbols: z.array(ExploreSymbolSchema),
+    evidence: z.array(ExploreEvidenceSchema),
+    offset: z.number().int().min(0),
+    limit: z.number().int().positive(),
+    total: z.number().int().min(0),
+    has_more: z.boolean(),
+    next_offset: z.number().int().min(0).nullable(),
+    freshness: z.object({
+        state: z.enum(SNAPSHOT_STATES),
+        causes: z.array(z.enum(FRESHNESS_CAUSES)),
+        checked_at: z.string().nullable(),
+    }),
+    completeness: z.object({
+        complete: z.boolean(),
+        symbols_complete: z.boolean(),
+        evidence_complete: z.boolean(),
+        unresolved: z.array(z.object({
+            selector: z.string(),
+            reason: z.enum(["source_unresolved", "references_unresolved"]),
+        })),
+    }),
+    budget: z.object({
+        max_records: z.number().int().positive(),
+        max_bytes: z.number().int().positive(),
+        max_depth: z.null(),
+        max_edges: z.null(),
+        max_invocations: z.number().int().positive(),
+        used_bytes: z.number().int().nonnegative(),
+    }),
+    truncation: z.object({
+        truncated: z.boolean(),
+        reason: z.enum(TRUNCATION_REASONS).nullable(),
+    }),
+});
+export function registerExplore(server) {
+    server.registerTool("ast_explore", {
+        title: "Explore project context",
+        description: "Composes bounded structural search, exact selectors, source evidence and compiler references without weakening the primitive AST tools.",
+        inputSchema: ExploreInputSchema,
+        outputSchema: ExploreOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ project_root, query, file_path, symbol_path, kinds, file_filter, detail, include_source, include_references, reference_detail, reference_limit, offset, limit, max_bytes, }) => {
+        try {
+            const output = await withProject(project_root, (context) => buildExploreContext(context, {
+                query,
+                filePath: file_path,
+                symbolPath: symbol_path,
+                kinds,
+                fileFilter: file_filter,
+                detail,
+                includeSource: include_source,
+                includeReferences: include_references,
+                referenceDetail: reference_detail,
+                offset,
+                limit,
+                referenceLimit: reference_limit,
+                maxBytes: max_bytes,
+            }));
+            return structuredResult(ExploreOutputSchema.parse(output));
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+}