ast-mcp-server 0.3.0

package/dist/services/outline.js

@@ -0,0 +1,233 @@
+import path from "node:path";
+import { Node, } from "ts-morph";
+function joinPresent(parts) {
+    return parts.filter((part) => Boolean(part)).join(" ");
+}
+function modifiersOf(node) {
+    return node
+        .getModifiers()
+        .map((modifier) => modifier.getText())
+        .join(" ");
+}
+function typeParametersOf(node) {
+    const parameters = node.getTypeParameters().map((parameter) => parameter.getText());
+    return parameters.length > 0 ? `<${parameters.join(", ")}>` : "";
+}
+function parametersOf(node) {
+    return node
+        .getParameters()
+        .map((parameter) => parameter.getText())
+        .join(", ");
+}
+function returnTypeOf(node) {
+    const returnType = node.getReturnTypeNode()?.getText();
+    return returnType ? `: ${returnType}` : "";
+}
+function optionalMarker(node) {
+    return node.hasQuestionToken() ? "?" : "";
+}
+function functionSignature(node) {
+    const name = node.getName() ?? "<anonymous>";
+    const generator = node.getAsteriskToken() ? "*" : "";
+    const declaration = `function${generator} ${name}${typeParametersOf(node)}(${parametersOf(node)})${returnTypeOf(node)};`;
+    return joinPresent([modifiersOf(node), declaration]);
+}
+function methodSignature(node) {
+    const generator = node.getAsteriskToken() ? "*" : "";
+    const declaration = `${generator}${node.getName()}${optionalMarker(node)}${typeParametersOf(node)}(${parametersOf(node)})${returnTypeOf(node)};`;
+    return joinPresent([modifiersOf(node), declaration]);
+}
+function callableExpressionSignature(node) {
+    const generic = typeParametersOf(node);
+    const returnType = node.getReturnTypeNode()?.getText() ?? "unknown";
+    return `${generic}(${parametersOf(node)}) => ${returnType}`;
+}
+function memberSignature(member) {
+    if (Node.isMethodDeclaration(member))
+        return methodSignature(member);
+    if (Node.isConstructorDeclaration(member)) {
+        return joinPresent([modifiersOf(member), `constructor(${parametersOf(member)});`]);
+    }
+    if (Node.isGetAccessorDeclaration(member)) {
+        return joinPresent([modifiersOf(member), `get ${member.getName()}()${returnTypeOf(member)};`]);
+    }
+    if (Node.isSetAccessorDeclaration(member)) {
+        return joinPresent([modifiersOf(member), `set ${member.getName()}(${parametersOf(member)});`]);
+    }
+    if (Node.isPropertyDeclaration(member)) {
+        const question = member.hasQuestionToken() ? "?" : "";
+        const definite = member.hasExclamationToken() ? "!" : "";
+        const explicitType = member.getTypeNode()?.getText();
+        const initializer = member.getInitializer();
+        const callableType = initializer && (Node.isArrowFunction(initializer) || Node.isFunctionExpression(initializer))
+            ? callableExpressionSignature(initializer)
+            : undefined;
+        const type = explicitType ?? callableType;
+        return joinPresent([
+            modifiersOf(member),
+            `${member.getName()}${question}${definite}${type ? `: ${type}` : ""};`,
+        ]);
+    }
+    return undefined;
+}
+function symbolOf(node, symbolPath, name, signature) {
+    return {
+        symbolPath,
+        name,
+        kind: node.getKindName(),
+        signature,
+        startLine: node.getStartLineNumber(),
+        endLine: node.getEndLineNumber(),
+    };
+}
+function formatClass(statement, prefix = "") {
+    const name = statement.getName() ?? "<anonymous>";
+    const symbolPath = prefix ? `${prefix}.${name}` : name;
+    const heritage = statement.getExtends()?.getText();
+    const implementations = statement.getImplements().map((item) => item.getText());
+    const declaration = joinPresent([
+        modifiersOf(statement),
+        `class ${name}${typeParametersOf(statement)}`,
+        heritage ? `extends ${heritage}` : undefined,
+        implementations.length > 0 ? `implements ${implementations.join(", ")}` : undefined,
+    ]);
+    const lines = [`${declaration} {`];
+    const symbols = [symbolOf(statement, symbolPath, name, declaration)];
+    for (const member of statement.getMembers()) {
+        const signature = memberSignature(member);
+        if (!signature)
+            continue;
+        const memberName = Node.isConstructorDeclaration(member) ? "constructor" : member.getName();
+        lines.push(`  ${signature}`);
+        symbols.push(symbolOf(member, `${symbolPath}.${memberName}`, memberName, signature));
+    }
+    lines.push("}");
+    return { lines, symbols };
+}
+function formatInterface(statement, prefix = "") {
+    const name = statement.getName();
+    const symbolPath = prefix ? `${prefix}.${name}` : name;
+    const extensions = statement.getExtends().map((item) => item.getText());
+    const declaration = joinPresent([
+        modifiersOf(statement),
+        `interface ${name}${typeParametersOf(statement)}`,
+        extensions.length > 0 ? `extends ${extensions.join(", ")}` : undefined,
+    ]);
+    const lines = [`${declaration} {`];
+    const symbols = [symbolOf(statement, symbolPath, name, declaration)];
+    for (const member of statement.getMembers()) {
+        const signature = member.getText().trim();
+        lines.push(`  ${signature}`);
+        const memberName = "getName" in member ? member.getName() : member.getKindName();
+        symbols.push(symbolOf(member, `${symbolPath}.${memberName}`, memberName, signature));
+    }
+    lines.push("}");
+    return { lines, symbols };
+}
+function formatVariable(statement) {
+    const lines = [];
+    const symbols = [];
+    const keyword = statement.getDeclarationKind();
+    const modifiers = modifiersOf(statement);
+    for (const declaration of statement.getDeclarations()) {
+        const name = declaration.getName();
+        const explicitType = declaration.getTypeNode()?.getText();
+        const initializer = declaration.getInitializer();
+        const callableType = initializer && (Node.isArrowFunction(initializer) || Node.isFunctionExpression(initializer))
+            ? callableExpressionSignature(initializer)
+            : undefined;
+        const signature = joinPresent([
+            modifiers,
+            `${keyword} ${name}${explicitType || callableType ? `: ${explicitType ?? callableType}` : ""};`,
+        ]);
+        lines.push(signature);
+        symbols.push(symbolOf(declaration, name, name, signature));
+    }
+    return { lines, symbols };
+}
+function moduleStatements(module) {
+    const body = module.getBody();
+    if (!body)
+        return [];
+    if (Node.isModuleBlock(body))
+        return body.getStatements();
+    if (Node.isModuleDeclaration(body))
+        return [body];
+    return [];
+}
+function formatStatement(statement, prefix = "") {
+    if (Node.isClassDeclaration(statement))
+        return formatClass(statement, prefix);
+    if (Node.isInterfaceDeclaration(statement))
+        return formatInterface(statement, prefix);
+    if (Node.isFunctionDeclaration(statement)) {
+        const name = statement.getName() ?? "<anonymous>";
+        const symbolPath = prefix ? `${prefix}.${name}` : name;
+        const signature = functionSignature(statement);
+        return { lines: [signature], symbols: [symbolOf(statement, symbolPath, name, signature)] };
+    }
+    if (Node.isTypeAliasDeclaration(statement)) {
+        const name = statement.getName();
+        const symbolPath = prefix ? `${prefix}.${name}` : name;
+        const signature = joinPresent([
+            modifiersOf(statement),
+            `type ${name}${typeParametersOf(statement)} = ${statement.getTypeNode()?.getText() ?? "unknown"};`,
+        ]);
+        return { lines: [signature], symbols: [symbolOf(statement, symbolPath, name, signature)] };
+    }
+    if (Node.isEnumDeclaration(statement)) {
+        const name = statement.getName();
+        const symbolPath = prefix ? `${prefix}.${name}` : name;
+        const members = statement
+            .getMembers()
+            .map((member) => member.getName())
+            .join(", ");
+        const signature = joinPresent([modifiersOf(statement), `enum ${name} { ${members} }`]);
+        return { lines: [signature], symbols: [symbolOf(statement, symbolPath, name, signature)] };
+    }
+    if (Node.isVariableStatement(statement))
+        return formatVariable(statement);
+    if (Node.isModuleDeclaration(statement)) {
+        const name = statement.getName();
+        const symbolPath = prefix ? `${prefix}.${name}` : name;
+        const declaration = joinPresent([modifiersOf(statement), `namespace ${name}`]);
+        const lines = [`${declaration} {`];
+        const symbols = [symbolOf(statement, symbolPath, name, declaration)];
+        for (const child of moduleStatements(statement)) {
+            const formatted = formatStatement(child, symbolPath);
+            if (!formatted)
+                continue;
+            lines.push(...formatted.lines.map((line) => `  ${line}`));
+            symbols.push(...formatted.symbols);
+        }
+        lines.push("}");
+        return { lines, symbols };
+    }
+    return undefined;
+}
+export function buildFileOutline(sourceFile) {
+    const lines = [];
+    const symbols = [];
+    for (const statement of sourceFile.getStatements()) {
+        const formatted = formatStatement(statement);
+        if (!formatted)
+            continue;
+        lines.push(...formatted.lines);
+        symbols.push(...formatted.symbols);
+    }
+    return { text: lines.join("\n"), symbols };
+}
+export function fileOutline(sourceFile) {
+    return buildFileOutline(sourceFile).text;
+}
+export function nodeSourceWithLocation(node, projectRoot) {
+    const sourceFile = node.getSourceFile();
+    return {
+        file: projectRoot
+            ? path.relative(projectRoot, sourceFile.getFilePath())
+            : sourceFile.getFilePath(),
+        startLine: node.getStartLineNumber(),
+        endLine: node.getEndLineNumber(),
+        text: node.getText(),
+    };
+}

package/dist/services/pagination.js

@@ -0,0 +1,33 @@
+import { z } from "zod";
+export const DEFAULT_PAGE_LIMIT = 100;
+export const MAX_PAGE_LIMIT = 500;
+export const PaginationInputSchema = {
+    offset: z.number().int().min(0).default(0).describe("Zero-based result offset."),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_PAGE_LIMIT)
+        .default(DEFAULT_PAGE_LIMIT)
+        .describe(`Maximum results to return (1-${MAX_PAGE_LIMIT}).`),
+};
+export const PaginationOutputSchema = {
+    offset: z.number().int().min(0),
+    limit: z.number().int().min(1),
+    total: z.number().int().min(0),
+    has_more: z.boolean(),
+    next_offset: z.number().int().min(0).nullable(),
+};
+export function paginate(items, offset, limit) {
+    const pageItems = items.slice(offset, offset + limit);
+    const nextOffset = offset + pageItems.length;
+    const hasMore = nextOffset < items.length;
+    return {
+        items: pageItems,
+        offset,
+        limit,
+        total: items.length,
+        has_more: hasMore,
+        next_offset: hasMore ? nextOffset : null,
+    };
+}

package/dist/services/project.js

@@ -0,0 +1,123 @@
+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";
+const MAX_PROJECT_SESSIONS = 8;
+const projectSessions = new Map();
+const projectRoots = new WeakMap();
+export function resolveTsConfigPath(projectRoot) {
+    const abs = path.resolve(projectRoot);
+    const stat = fs.existsSync(abs) ? fs.statSync(abs) : null;
+    if (stat?.isFile() && abs.endsWith(".json")) {
+        return fs.realpathSync(abs);
+    }
+    const candidate = path.join(abs, "tsconfig.json");
+    if (fs.existsSync(candidate)) {
+        return fs.realpathSync(candidate);
+    }
+    throw new Error(`No tsconfig.json found at "${abs}". Pass a project directory containing tsconfig.json or the config file itself.`);
+}
+function buildProjectContext(tsConfigFilePath) {
+    const project = new Project({
+        tsConfigFilePath,
+        skipAddingFilesFromTsConfig: false,
+    });
+    const projectRoot = path.dirname(tsConfigFilePath);
+    projectRoots.set(project, projectRoot);
+    return { project, projectRoot, tsConfigFilePath };
+}
+export function createFreshProject(projectRoot) {
+    return buildProjectContext(resolveTsConfigPath(projectRoot));
+}
+function evictSessions() {
+    if (projectSessions.size < MAX_PROJECT_SESSIONS)
+        return;
+    const candidate = [...projectSessions.entries()]
+        .filter(([, session]) => session.activeOperations === 0)
+        .sort((left, right) => left[1].lastAccessedAt - right[1].lastAccessedAt)[0];
+    if (candidate)
+        projectSessions.delete(candidate[0]);
+}
+function getOrCreateSession(projectRoot) {
+    const tsConfigFilePath = resolveTsConfigPath(projectRoot);
+    const existing = projectSessions.get(tsConfigFilePath);
+    if (existing)
+        return existing;
+    evictSessions();
+    const session = {
+        context: buildProjectContext(tsConfigFilePath),
+        configDigest: createConfigSnapshot(tsConfigFilePath).digest,
+        queue: Promise.resolve(),
+        activeOperations: 0,
+        lastAccessedAt: Date.now(),
+    };
+    projectSessions.set(tsConfigFilePath, session);
+    return session;
+}
+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;
+    }
+    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);
+    session.activeOperations += 1;
+    let release;
+    const previous = session.queue;
+    session.queue = new Promise((resolve) => {
+        release = resolve;
+    });
+    await previous;
+    try {
+        await synchronizeSession(session);
+        session.lastAccessedAt = Date.now();
+        return await operation(session.context);
+    }
+    finally {
+        session.activeOperations -= 1;
+        release?.();
+    }
+}
+// Compatibility API for internal scripts. MCP tools should use withProject().
+export function getProject(projectRoot) {
+    return createFreshProject(projectRoot).project;
+}
+export function invalidateProject(projectRoot) {
+    const tsConfigFilePath = resolveTsConfigPath(projectRoot);
+    projectSessions.delete(tsConfigFilePath);
+}
+export function clearProjectSessions() {
+    projectSessions.clear();
+}
+export function getSourceFileOrThrow(project, filePath) {
+    const projectRoot = projectRoots.get(project) ?? process.cwd();
+    const normalizedInput = path.normalize(filePath);
+    const exactPath = path.isAbsolute(normalizedInput)
+        ? normalizedInput
+        : path.resolve(projectRoot, normalizedInput);
+    const sourceFiles = project.getSourceFiles();
+    const exact = sourceFiles.find((sourceFile) => path.normalize(sourceFile.getFilePath()) === exactPath);
+    if (exact)
+        return exact;
+    const suffix = normalizedInput.split(path.sep).join("/");
+    const candidates = sourceFiles.filter((sourceFile) => sourceFile.getFilePath().split(path.sep).join("/").endsWith(`/${suffix}`));
+    if (candidates.length === 1)
+        return candidates[0];
+    if (candidates.length > 1) {
+        const relativeCandidates = candidates
+            .map((sourceFile) => path.relative(projectRoot, sourceFile.getFilePath()))
+            .sort();
+        throw new Error(`Ambiguous source file "${filePath}". Use one of: ${relativeCandidates.join(", ")}.`);
+    }
+    throw new Error(`Source file "${filePath}" was not found in the project. Use a project-relative or absolute path returned by ast_list_files.`);
+}
+export function findDeclarationByName(sourceFile, symbolPath) {
+    return findDeclaration(sourceFile, symbolPath);
+}

package/dist/services/runtime-state.js

@@ -0,0 +1,75 @@
+import { createHash } from "node:crypto";
+import { chmod, lstat, mkdir, open, unlink } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+export function resolveRuntimeStateDirectory(options = {}) {
+    if (options.stateDirectory)
+        return path.resolve(options.stateDirectory);
+    if (process.env.AST_TOOL_STATE_DIR)
+        return path.resolve(process.env.AST_TOOL_STATE_DIR);
+    const base = process.env.XDG_STATE_HOME
+        ? path.resolve(process.env.XDG_STATE_HOME)
+        : path.join(os.homedir(), ".local", "state");
+    return path.join(base, "ast-tool");
+}
+export async function ensurePrivateDirectory(directory) {
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    if (process.platform !== "win32") {
+        const root = path.parse(directory).root;
+        let current = root;
+        for (const segment of path.relative(root, directory).split(path.sep).filter(Boolean)) {
+            current = path.join(current, segment);
+            const currentStat = await lstat(current);
+            if (currentStat.isSymbolicLink()) {
+                throw new Error(`Runtime state path must not traverse symbolic links: ${current}`);
+            }
+        }
+        const directoryStat = await lstat(directory);
+        if (!directoryStat.isDirectory()) {
+            throw new Error(`Runtime state path is not a directory: ${directory}`);
+        }
+        const uid = process.getuid?.();
+        if (uid !== undefined && directoryStat.uid !== uid) {
+            throw new Error(`Runtime state directory is not owned by the current user: ${directory}`);
+        }
+        await chmod(directory, 0o700);
+    }
+}
+export async function withWorkspaceFileLock(workspaceKey, options, callback) {
+    const locksDirectory = path.join(resolveRuntimeStateDirectory(options), "locks");
+    await ensurePrivateDirectory(locksDirectory);
+    const key = createHash("sha256").update(workspaceKey).digest("hex");
+    const lockPath = path.join(locksDirectory, `${key}.lock`);
+    let handle;
+    try {
+        handle = await open(lockPath, "wx", 0o600);
+        await handle.writeFile(JSON.stringify({
+            pid: process.pid,
+            workspace_key: workspaceKey,
+            phase: "applying",
+            created_at: new Date().toISOString(),
+        }), "utf8");
+        await handle.sync();
+    }
+    catch (error) {
+        if (handle) {
+            await handle.close().catch(() => undefined);
+            await unlink(lockPath).catch(() => undefined);
+        }
+        if (error.code === "EEXIST") {
+            throw new Error(`Another AST apply holds the workspace lock. Inspect and remove a stale lock only if no apply is running: ${lockPath}`, { cause: error });
+        }
+        throw error;
+    }
+    try {
+        return await callback();
+    }
+    finally {
+        try {
+            await handle.close();
+        }
+        finally {
+            await unlink(lockPath);
+        }
+    }
+}

package/dist/services/setup-wizard.js

@@ -0,0 +1,113 @@
+export const AGENT_IDS = ["claude", "hermes"];
+const AGENT_LABELS = {
+    claude: "Claude Code",
+    hermes: "Hermes",
+};
+function isAgentId(value) {
+    return AGENT_IDS.includes(value);
+}
+export function parseAgentsArgument(value) {
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "") {
+        throw new Error("The --agents value cannot be empty.");
+    }
+    if (normalized === "all") {
+        return [...AGENT_IDS];
+    }
+    const requested = normalized
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean);
+    if (requested.length === 0) {
+        throw new Error("The --agents value cannot be empty.");
+    }
+    const unsupported = requested.find((item) => !isAgentId(item));
+    if (unsupported !== undefined) {
+        throw new Error(`Unsupported agent: ${unsupported}. Expected claude, hermes, or all.`);
+    }
+    const selected = new Set(requested);
+    return AGENT_IDS.filter((agent) => selected.has(agent));
+}
+export function applyAgentDeselections(answer, detections) {
+    const installed = detections.filter((item) => item.installed);
+    const selected = new Set(installed.map((item) => item.id));
+    const normalized = answer.trim().toLowerCase();
+    if (normalized === "") {
+        return AGENT_IDS.filter((agent) => selected.has(agent));
+    }
+    if (normalized === "none") {
+        return [];
+    }
+    const tokens = normalized
+        .split(/[\s,]+/)
+        .map((item) => item.trim())
+        .filter(Boolean);
+    for (const token of tokens) {
+        let detection;
+        if (/^\d+$/.test(token)) {
+            detection = detections[Number(token) - 1];
+        }
+        else if (isAgentId(token)) {
+            detection = detections.find((item) => item.id === token);
+        }
+        if (detection === undefined) {
+            throw new Error(`Invalid selection: ${token}.`);
+        }
+        if (!detection.installed) {
+            throw new Error(`${detection.label} is not installed.`);
+        }
+        selected.delete(detection.id);
+    }
+    return AGENT_IDS.filter((agent) => selected.has(agent));
+}
+function renderSelectionQuestion(detections, validationMessage) {
+    const choices = detections
+        .map((item, index) => {
+        const marker = item.installed ? "x" : " ";
+        const detail = item.installed
+            ? [item.version, item.executable].filter(Boolean).join(" · ")
+            : "not installed";
+        return `  [${marker}] ${index + 1}. ${AGENT_LABELS[item.id]} (${detail})`;
+    })
+        .join("\n");
+    const validation = validationMessage === undefined ? "" : `\n${validationMessage}\n`;
+    return `\nDetected agents (all installed agents are selected):\n${choices}\n${validation}\nEnter agents to deselect by number or name, 'none' to deselect all, or press Enter to keep all:\n> `;
+}
+function renderConfirmation(agents, validationMessage) {
+    const labels = agents.map((agent) => AGENT_LABELS[agent]).join(", ");
+    const validation = validationMessage === undefined ? "" : `\n${validationMessage}\n`;
+    return `${validation}\nSetup will install the MCP server and skill for: ${labels}.\nContinue? [Y/n] `;
+}
+export async function promptForAgentSelection(detections, ask) {
+    if (!detections.some((item) => item.installed)) {
+        throw new Error("No supported agents were detected in PATH.");
+    }
+    let selected;
+    let selectionError;
+    while (true) {
+        const answer = await ask(renderSelectionQuestion(detections, selectionError));
+        try {
+            selected = applyAgentDeselections(answer, detections);
+            break;
+        }
+        catch (error) {
+            selectionError = error instanceof Error ? error.message : String(error);
+        }
+    }
+    if (selected.length === 0) {
+        return [];
+    }
+    let confirmationError;
+    while (true) {
+        const answer = (await ask(renderConfirmation(selected, confirmationError)))
+            .trim()
+            .toLowerCase();
+        if (answer === "" || answer === "y" || answer === "yes") {
+            return selected;
+        }
+        if (answer === "n" || answer === "no") {
+            return [];
+        }
+        confirmationError = "Enter y or n.";
+    }
+}