ast-mcp-server 0.3.0

package/dist/services/skill-installer.js

@@ -0,0 +1,127 @@
+import { randomUUID } from "node:crypto";
+import { link, mkdir, readFile, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+const SKILL_NAME = "structural-code-editing";
+export class SkillConflictError extends Error {
+    destination;
+    constructor(destination) {
+        super(`Skill already exists with different content at ${destination}; pass --force to replace it.`);
+        this.name = "SkillConflictError";
+        this.destination = destination;
+    }
+}
+export async function resolveBundledSkillPath(executablePath) {
+    const resolvedExecutable = await realpath(executablePath);
+    return path.resolve(path.dirname(resolvedExecutable), "..", "skills", SKILL_NAME, "SKILL.md");
+}
+function resolveConfiguredDirectory(configured, fallback, workingDirectory) {
+    return path.resolve(workingDirectory, configured ?? fallback);
+}
+async function resolveDestinationPlans(options) {
+    if (options.scope === "project" && options.target !== "claude") {
+        throw new Error("Project scope is supported only for Claude Code skills.");
+    }
+    const homeDirectory = options.homeDirectory ?? os.homedir();
+    const workingDirectory = options.workingDirectory ?? process.cwd();
+    const environment = options.environment ?? process.env;
+    const targets = options.target === "all" ? ["claude", "hermes"] : [options.target];
+    let projectRoot;
+    if (options.scope === "project") {
+        projectRoot = path.resolve(workingDirectory, options.projectRoot ?? workingDirectory);
+        const projectStats = await stat(projectRoot).catch((error) => {
+            if (error.code === "ENOENT") {
+                throw new Error(`Project root does not exist: ${projectRoot}`);
+            }
+            throw error;
+        });
+        if (!projectStats.isDirectory()) {
+            throw new Error(`Project root is not a directory: ${projectRoot}`);
+        }
+    }
+    return targets.map((target) => {
+        if (target === "claude") {
+            const root = options.scope === "project"
+                ? path.join(projectRoot, ".claude")
+                : resolveConfiguredDirectory(environment.CLAUDE_CONFIG_DIR, path.join(homeDirectory, ".claude"), workingDirectory);
+            return {
+                target,
+                scope: options.scope,
+                path: path.join(root, "skills", SKILL_NAME, "SKILL.md"),
+            };
+        }
+        const hermesHome = resolveConfiguredDirectory(environment.HERMES_HOME, path.join(homeDirectory, ".hermes"), workingDirectory);
+        return {
+            target,
+            scope: "user",
+            path: path.join(hermesHome, "skills", "software-development", SKILL_NAME, "SKILL.md"),
+        };
+    });
+}
+async function classifyDestination(destination, sourceContent, force) {
+    try {
+        const existingContent = await readFile(destination, "utf8");
+        if (existingContent === sourceContent)
+            return "unchanged";
+        if (!force) {
+            throw new SkillConflictError(destination);
+        }
+        return "updated";
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return "installed";
+        throw error;
+    }
+}
+async function writeSkill(destination, sourceContent, status) {
+    if (status === "unchanged")
+        return;
+    const directory = path.dirname(destination);
+    await mkdir(directory, { recursive: true });
+    const temporaryPath = path.join(directory, `.${path.basename(destination)}.${process.pid}.${randomUUID()}.tmp`);
+    await writeFile(temporaryPath, sourceContent, {
+        encoding: "utf8",
+        flag: "wx",
+        mode: 0o644,
+    });
+    try {
+        if (status === "installed") {
+            await link(temporaryPath, destination).catch((error) => {
+                if (error.code === "EEXIST") {
+                    throw new Error(`Skill appeared concurrently at ${destination}; no files were replaced.`);
+                }
+                throw error;
+            });
+            await rm(temporaryPath);
+            return;
+        }
+        await rename(temporaryPath, destination);
+    }
+    finally {
+        await rm(temporaryPath, { force: true });
+    }
+}
+export async function installBundledSkill(options) {
+    const sourceContent = await readFile(path.resolve(options.sourceSkillPath), "utf8");
+    const destinations = await resolveDestinationPlans(options);
+    const force = options.force ?? false;
+    const statusByPath = new Map();
+    for (const destination of destinations) {
+        if (!statusByPath.has(destination.path)) {
+            statusByPath.set(destination.path, await classifyDestination(destination.path, sourceContent, force));
+        }
+    }
+    for (const [destination, status] of statusByPath) {
+        await writeSkill(destination, sourceContent, status);
+    }
+    return {
+        version: 1,
+        status: "ok",
+        skill: SKILL_NAME,
+        installations: destinations.map((destination) => ({
+            ...destination,
+            status: statusByPath.get(destination.path),
+        })),
+    };
+}

package/dist/services/symbols.js

@@ -0,0 +1,117 @@
+import { Node, } from "ts-morph";
+function namedNode(node) {
+    if (Node.isConstructorDeclaration(node))
+        return "constructor";
+    if (Node.isFunctionDeclaration(node) ||
+        Node.isClassDeclaration(node) ||
+        Node.isInterfaceDeclaration(node) ||
+        Node.isEnumDeclaration(node) ||
+        Node.isTypeAliasDeclaration(node) ||
+        Node.isModuleDeclaration(node) ||
+        Node.isMethodDeclaration(node) ||
+        Node.isMethodSignature(node) ||
+        Node.isPropertyDeclaration(node) ||
+        Node.isPropertySignature(node) ||
+        Node.isGetAccessorDeclaration(node) ||
+        Node.isSetAccessorDeclaration(node) ||
+        Node.isVariableDeclaration(node)) {
+        return node.getName();
+    }
+    return undefined;
+}
+function addLocated(node, symbolPath, output) {
+    const name = namedNode(node);
+    if (!name)
+        return;
+    output.push({
+        node,
+        symbolPath,
+        name,
+        kind: node.getKindName(),
+        line: node.getStartLineNumber(),
+    });
+}
+function collectClassLike(node, prefix, output) {
+    if (!Node.isClassDeclaration(node) && !Node.isInterfaceDeclaration(node))
+        return;
+    for (const member of node.getMembers()) {
+        const name = namedNode(member);
+        if (name)
+            addLocated(member, `${prefix}.${name}`, output);
+    }
+}
+function moduleStatements(module) {
+    let body = module.getBody();
+    while (body && Node.isModuleDeclaration(body))
+        body = body.getBody();
+    return body && Node.isModuleBlock(body) ? body.getStatements() : [];
+}
+function collectStatements(statements, prefix, output) {
+    for (const statement of statements) {
+        if (Node.isVariableStatement(statement)) {
+            for (const declaration of statement.getDeclarations()) {
+                const path = prefix ? `${prefix}.${declaration.getName()}` : declaration.getName();
+                addLocated(declaration, path, output);
+            }
+            continue;
+        }
+        const name = namedNode(statement);
+        if (!name)
+            continue;
+        const symbolPath = prefix ? `${prefix}.${name}` : name;
+        addLocated(statement, symbolPath, output);
+        collectClassLike(statement, symbolPath, output);
+        if (Node.isModuleDeclaration(statement)) {
+            collectStatements(moduleStatements(statement), symbolPath, output);
+        }
+    }
+}
+export function collectSymbols(sourceFile) {
+    const symbols = [];
+    collectStatements(sourceFile.getStatements(), undefined, symbols);
+    return symbols;
+}
+function parseSelector(symbolPath) {
+    const match = /^(.*)@(\d+)$/.exec(symbolPath);
+    return match ? { path: match[1], line: Number(match[2]) } : { path: symbolPath };
+}
+export function findDeclaration(sourceFile, requestedPath) {
+    const selector = parseSelector(requestedPath);
+    let matches = collectSymbols(sourceFile).filter((symbol) => symbol.symbolPath === selector.path && (!selector.line || symbol.line === selector.line));
+    if (matches.length > 1) {
+        const implementations = matches.filter((symbol) => {
+            const node = symbol.node;
+            return ((Node.isFunctionDeclaration(node) || Node.isMethodDeclaration(node)) &&
+                node.getBody() !== undefined);
+        });
+        if (implementations.length === 1)
+            matches = implementations;
+    }
+    if (matches.length === 1)
+        return matches[0].node;
+    if (matches.length === 0) {
+        throw new Error(`Symbol "${requestedPath}" was not found in ${sourceFile.getFilePath()}. Use ast_get_outline or ast_search_symbols to obtain an exact symbol path.`);
+    }
+    throw new Error(`Symbol "${requestedPath}" is ambiguous. Select one by line: ${matches
+        .map((symbol) => `${symbol.symbolPath}@${symbol.line}`)
+        .join(", ")}.`);
+}
+export function executableDeclaration(node) {
+    if (Node.isFunctionDeclaration(node) ||
+        Node.isMethodDeclaration(node) ||
+        Node.isConstructorDeclaration(node) ||
+        Node.isGetAccessorDeclaration(node) ||
+        Node.isSetAccessorDeclaration(node) ||
+        Node.isArrowFunction(node) ||
+        Node.isFunctionExpression(node)) {
+        return node;
+    }
+    if (Node.isVariableDeclaration(node) || Node.isPropertyDeclaration(node)) {
+        const initializer = node.getInitializer();
+        if (initializer &&
+            (Node.isArrowFunction(initializer) || Node.isFunctionExpression(initializer))) {
+            return initializer;
+        }
+    }
+    throw new Error(`Symbol kind ${node.getKindName()} does not have a replaceable executable body.`);
+}

package/dist/services/workspace.js

@@ -0,0 +1,86 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { ts } from "ts-morph";
+export function hashBytes(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+export function hashWorkspaceFiles(files) {
+    const digest = createHash("sha256");
+    for (const [filePath, fileHash] of [...files].sort(([left], [right]) => left.localeCompare(right))) {
+        digest.update(filePath);
+        digest.update("\0");
+        digest.update(fileHash);
+        digest.update("\0");
+    }
+    return digest.digest("hex");
+}
+function canonicalPath(filePath) {
+    return fs.realpathSync(filePath);
+}
+function parseConfig(configPath) {
+    const source = ts.readJsonConfigFile(configPath, ts.sys.readFile);
+    const parsed = ts.parseJsonSourceFileConfigFileContent(source, ts.sys, path.dirname(configPath));
+    return {
+        extendedSourceFiles: source.extendedSourceFiles ?? [],
+        projectReferences: (parsed.projectReferences ?? []).map((reference) => reference.path),
+    };
+}
+function collectConfigPaths(rootConfigPath) {
+    const pending = [canonicalPath(rootConfigPath)];
+    const collected = new Set();
+    while (pending.length > 0) {
+        const configPath = pending.pop();
+        if (collected.has(configPath))
+            continue;
+        collected.add(configPath);
+        const { extendedSourceFiles, projectReferences } = parseConfig(configPath);
+        for (const extendedPath of extendedSourceFiles) {
+            if (fs.existsSync(extendedPath))
+                pending.push(canonicalPath(extendedPath));
+        }
+        for (const referencePath of projectReferences) {
+            if (!fs.existsSync(referencePath))
+                continue;
+            const candidate = fs.statSync(referencePath).isDirectory()
+                ? path.join(referencePath, "tsconfig.json")
+                : referencePath;
+            if (fs.existsSync(candidate))
+                pending.push(canonicalPath(candidate));
+        }
+    }
+    return [...collected].sort();
+}
+export function createConfigSnapshot(rootConfigPath) {
+    const files = collectConfigPaths(rootConfigPath);
+    const digest = createHash("sha256");
+    for (const filePath of files) {
+        digest.update(filePath);
+        digest.update("\0");
+        digest.update(hashBytes(fs.readFileSync(filePath)));
+        digest.update("\0");
+    }
+    return { digest: digest.digest("hex"), files };
+}
+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) {
+        const digest = hashBytes(fs.readFileSync(filePath));
+        const previous = files.get(filePath);
+        if (previous && previous !== digest) {
+            throw new Error(`Workspace identity collision for ${filePath}.`);
+        }
+        files.set(filePath, digest);
+    }
+    return {
+        digest: hashWorkspaceFiles(files),
+        fileCount: files.size,
+        files,
+    };
+}

package/dist/tools/apply_operation.js

@@ -0,0 +1,36 @@
+import { z } from "zod";
+import { applyOperation } from "../services/operations.js";
+import { errorResult, structuredResult } from "./result.js";
+const AstApplyOperationInputSchema = z.object({
+    operation_id: z.string().uuid().describe("Identifier returned by a prepare operation."),
+    plan_hash: z.string().length(64).describe("Plan hash returned by the same prepare operation."),
+});
+const AstApplyOperationOutputSchema = z.object({
+    operation_id: z.string().uuid(),
+    kind: z.enum(["rename_symbol", "replace_symbol_body"]),
+    status: z.literal("applied"),
+    applied_at: z.string(),
+    affected_files: z.array(z.string()),
+    idempotent_replay: z.boolean(),
+});
+export function registerApplyOperation(server) {
+    server.registerTool("ast_apply_operation", {
+        title: "Apply a prepared structural operation",
+        description: "Applies exactly the reviewed plan after verifying its plan hash and the complete TypeScript workspace fingerprint. Conflicts abort before writes; retries after success are idempotent.",
+        inputSchema: AstApplyOperationInputSchema,
+        outputSchema: AstApplyOperationOutputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ operation_id, plan_hash }) => {
+        try {
+            return structuredResult({ ...(await applyOperation(operation_id, plan_hash)) });
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+}

package/dist/tools/find_references.js

@@ -0,0 +1,97 @@
+import path from "node:path";
+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";
+const AstFindReferencesInputSchema = z.object({
+    project_root: z
+        .string()
+        .describe("Absolute project directory containing tsconfig.json, or the config path."),
+    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),
+    ...PaginationInputSchema,
+});
+const ReferenceSchema = 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(),
+});
+const AstFindReferencesOutputSchema = z.object({
+    symbol: z.string(),
+    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,
+});
+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 }) => {
+        try {
+            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;
+                return {
+                    symbol: symbol_path,
+                    declaration_count: 1,
+                    reference_count: references.length,
+                    affected_files: affectedFiles,
+                    references: items,
+                    ...metadata,
+                };
+            });
+            return structuredResult(structuredContent);
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+}

package/dist/tools/get_diagnostics.js

@@ -0,0 +1,70 @@
+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";
+const DiagnosticSchema = z.object({
+    code: z.number().int(),
+    category: z.string(),
+    file: z.string().nullable(),
+    line: z.number().int().positive().nullable(),
+    column: z.number().int().positive().nullable(),
+    message: z.string(),
+});
+const AstGetDiagnosticsInputSchema = z.object({
+    project_root: z
+        .string()
+        .describe("Absolute project directory containing tsconfig.json, or the config path."),
+    file_path: z
+        .string()
+        .optional()
+        .describe("Optional project-relative or absolute file path. Omit for project diagnostics."),
+    ...PaginationInputSchema,
+});
+const AstGetDiagnosticsOutputSchema = z.object({
+    diagnostics: z.array(DiagnosticSchema),
+    error_count: z.number().int().min(0),
+    warning_count: z.number().int().min(0),
+    duration_ms: z.number().min(0),
+    ...PaginationOutputSchema,
+});
+export function registerGetDiagnostics(server) {
+    server.registerTool("ast_get_diagnostics", {
+        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 }) => {
+        try {
+            const structuredContent = await withProject(project_root, ({ project, projectRoot }) => {
+                const startedAt = performance.now();
+                const diagnostics = file_path
+                    ? getSourceFileOrThrow(project, file_path).getPreEmitDiagnostics()
+                    : [...project.getConfigFileParsingDiagnostics(), ...project.getPreEmitDiagnostics()];
+                const normalized = diagnostics
+                    .map((diagnostic) => normalizeDiagnostic(diagnostic, projectRoot))
+                    .sort((left, right) => `${left.file ?? ""}:${left.line ?? 0}:${left.column ?? 0}:${left.code}`.localeCompare(`${right.file ?? ""}:${right.line ?? 0}:${right.column ?? 0}:${right.code}`));
+                const page = paginate(normalized, offset, limit);
+                const { items, ...metadata } = page;
+                return {
+                    diagnostics: items,
+                    error_count: normalized.filter((diagnostic) => diagnostic.category === "Error").length,
+                    warning_count: normalized.filter((diagnostic) => diagnostic.category === "Warning")
+                        .length,
+                    duration_ms: performance.now() - startedAt,
+                    ...metadata,
+                };
+            });
+            return structuredResult(structuredContent);
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+}

package/dist/tools/get_operation_preview.js

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import { getOperationPreview } from "../services/operations.js";
+import { errorResult, structuredResult } from "./result.js";
+const AstGetOperationPreviewInputSchema = z.object({
+    operation_id: z.string().uuid(),
+    file: z.string().optional().describe("Optional affected file path to retrieve only its diff."),
+});
+const AstGetOperationPreviewOutputSchema = z.object({
+    operation_id: z.string().uuid(),
+    plan_hash: z.string().length(64),
+    files: z.array(z.object({ file: z.string(), diff: z.string() })),
+});
+export function registerGetOperationPreview(server) {
+    server.registerTool("ast_get_operation_preview", {
+        title: "Get complete prepared-operation diff",
+        description: "Retrieves exact unified diffs retained for a prepared operation, optionally one affected file at a time.",
+        inputSchema: AstGetOperationPreviewInputSchema,
+        outputSchema: AstGetOperationPreviewOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ operation_id, file }) => {
+        try {
+            return structuredResult(getOperationPreview(operation_id, file));
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+}

package/dist/tools/get_outline.js

@@ -0,0 +1,58 @@
+import path from "node:path";
+import { z } from "zod";
+import { buildFileOutline } from "../services/outline.js";
+import { getSourceFileOrThrow, withProject } from "../services/project.js";
+import { errorResult, structuredResult } from "./result.js";
+const AstGetOutlineInputSchema = 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 absolute source file path."),
+    include_symbols: z
+        .boolean()
+        .default(false)
+        .describe("Include detailed symbol metadata. Omit for the smallest body-free response."),
+});
+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 AstGetOutlineOutputSchema = z.object({
+    file: z.string(),
+    outline: z.string(),
+    symbols: z.array(OutlineSymbolSchema).optional(),
+});
+export function registerGetOutline(server) {
+    server.registerTool("ast_get_outline", {
+        title: "Get compact file outline",
+        description: "Returns body-free declaration signatures for one TypeScript/JavaScript file. Detailed symbol metadata is opt-in because it duplicates signature text.",
+        inputSchema: AstGetOutlineInputSchema,
+        outputSchema: AstGetOutlineOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ project_root, file_path, include_symbols }) => {
+        try {
+            const structuredContent = await withProject(project_root, ({ project, projectRoot }) => {
+                const sourceFile = getSourceFileOrThrow(project, file_path);
+                const outline = buildFileOutline(sourceFile);
+                return {
+                    file: path.relative(projectRoot, sourceFile.getFilePath()),
+                    outline: outline.text,
+                    ...(include_symbols ? { symbols: outline.symbols } : {}),
+                };
+            });
+            return structuredResult(structuredContent);
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+}

package/dist/tools/get_symbol_source.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import { nodeSourceWithLocation } from "../services/outline.js";
+import { findDeclarationByName, getSourceFileOrThrow, withProject } from "../services/project.js";
+import { errorResult, structuredResult } from "./result.js";
+const AstGetSymbolSourceInputSchema = 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 absolute source file path."),
+    symbol_path: z.string().describe('Symbol path such as "formatDate" or "UserService.create".'),
+});
+const AstGetSymbolSourceOutputSchema = z.object({
+    file: z.string(),
+    startLine: z.number().int().positive(),
+    endLine: z.number().int().positive(),
+    text: z.string(),
+});
+export function registerGetSymbolSource(server) {
+    server.registerTool("ast_get_symbol_source", {
+        title: "Get one symbol implementation",
+        description: "Returns exactly one declaration or implementation with its project-relative location, not the complete file.",
+        inputSchema: AstGetSymbolSourceInputSchema,
+        outputSchema: AstGetSymbolSourceOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ project_root, file_path, symbol_path }) => {
+        try {
+            const structuredContent = await withProject(project_root, ({ project, projectRoot }) => {
+                const sourceFile = getSourceFileOrThrow(project, file_path);
+                const node = findDeclarationByName(sourceFile, symbol_path);
+                return nodeSourceWithLocation(node, projectRoot);
+            });
+            return structuredResult(structuredContent);
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+}