ast-mcp-server 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -4,13 +4,38 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.0] — release candidate (unreleased, 2026-08-11)
+
+### Added
+
+- Compiler-backed, freshness-aware impact traversal with bounded direct/transitive relationships and fail-closed test-candidate evidence.
+- Opt-in SQLite symbol-index canary with corruption/write-failure fallback, restart reuse, explicit recovery, and bounded project-status observability; default and reserved `enabled` policies remain memory-only.
+- Bounded per-project scheduling, cancellation/deadline semantics, idempotent graceful shutdown, and a closed public-error envelope with correlation IDs.
+- Deterministic Linux x64 production-readiness evidence across Node.js 22.5.0 and Node.js 24 for this repository and `x-scraper`.
+- Exact-SHA staged release workflows for `next` publication, public-registry verification, and separately authorized `latest` promotion.
+
+### Changed
+
+- Symbol search and impact discovery now remain compiler-authoritative while applying deterministic limits before globally materializing expensive relationships.
+- The supported release target is explicitly Linux x64 with the required GNU coreutils publication primitive; other platforms and architectures remain unverified.
+- The package now ships its support and security policies alongside the README, changelog, binaries, and bundled structural-editing skill.
+
+### Security
+
+- Release preparation, GitHub authorization, OIDC publication, and npm-token promotion use physically separated least-authority phases with lifecycle scripts disabled.
+- Workflow actions, permissions, inputs, conditions, commands, environments, and credential placement are checked against a closed immutable policy.
+- Package publication binds exact tarball bytes and packed `gitHead` to the authorized SHA; consumer verification independently proves preview/apply/replay postimages and no-write failure paths.
+- Public MCP and stderr errors are bounded and sanitized against source, path, stack, environment, and credential disclosure.
+
 ## [0.6.0] - 2026-08-05
 
 ### Added
 
 - Read-only `ast_get_file` with bounded exact source lines, SHA-256 byte hashes, compiler snapshot state, and `symbols_only` body-free output.
+- `ast_get_file` now also returns bounded project freshness metadata, distinguishing fresh, pending, stale, rebuilding, and degraded session state from the file-level snapshot state.
 - Project-scoped file snapshot validation with UTF-8 checks, traversal rejection, symlink containment checks, and ambiguous-path failures.
 - Read-only `ast_explore` with query/file/symbol routing, progressive source and compiler-reference evidence, freshness/completeness metadata, unresolved selectors, and serialized byte budgets.
+- Public trust guidance for compiler, syntax, heuristic and derived-index evidence, including the fail-closed rules for stale/degraded reads and compiler-backed test candidates.
 - A deterministic context workflow benchmark comparing full-file, primitive, and composed exploration workflows.
 
 ## [0.5.1] - 2026-08-05
@@ -25,6 +50,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 - Source synchronization verifies stability across refresh, snapshot, refresh, and verification before reporting fresh state.
 - Phase 1 keeps the symbol index disabled while exposing explicit stale/degraded recovery state.
+- Documentation now distinguishes file snapshot freshness from project freshness, reports bounded read budgets/truncation, and defines the prepare-review-apply mutation boundary.
 
 ### Security
 
@@ -93,6 +119,7 @@ Initial public release.
 - Apply rejects stale workspaces, changed configs/sources, mismatched plan hashes, unsafe plan files, conflicting MCP registrations, and conflicting skill content.
 - Inputs, outputs, operation stores, subprocesses, batch fan-out, plan lifetime, and filesystem access are bounded.
 
+[0.6.0]: https://github.com/yailPeralta/ast-mcp-server/releases/tag/v0.6.0
 [0.5.1]: https://github.com/yailPeralta/ast-mcp-server/releases/tag/v0.5.1
 [0.5.0]: https://github.com/yailPeralta/ast-mcp-server/releases/tag/v0.5.0
 [0.4.0]: https://github.com/yailPeralta/ast-mcp-server/releases/tag/v0.4.0

package/README.md

@@ -1,8 +1,12 @@
+<p align="center">
+  <img src="assets/header.jpg" alt="Abstract network of connected code symbols with the text AST MCP Server." width="100%" />
+</p>
+
 # ast-mcp-server
 
 [![CI](https://github.com/yailPeralta/ast-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/yailPeralta/ast-mcp-server/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/ast-mcp-server.svg)](https://www.npmjs.com/package/ast-mcp-server)
-[![Node.js 20.19+](https://img.shields.io/badge/Node.js-20.19%2B-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![Node.js 22.5+](https://img.shields.io/badge/Node.js-22.5%2B-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
 [![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](LICENSE)
 
 `ast-mcp-server` gives coding agents compact, type-aware access to TypeScript and JavaScript projects. It uses the real compiler project model through `ts-morph`, so declarations, references, rename locations, and diagnostics come from the AST instead of text-search guesses.
@@ -21,27 +25,44 @@ Coding agents often fall back to two generic operations: read files as plain tex
 
 This MCP server gives the agent structural code tools in addition to generic file reads and writes. Under the hood, `ts-morph` uses the TypeScript compiler project model, so the server can reason about declarations and references as code rather than undifferentiated text.
 
-| Need                           | Structural operation      | Returned scope                                        |
-| ------------------------------ | ------------------------- | ----------------------------------------------------- |
-| Read a bounded file            | `ast_get_file`            | Exact selected source lines, hash, and snapshot state |
-| Explore bounded context        | `ast_explore`             | Ranked selectors plus optional source and references  |
-| Understand a file              | `ast_get_outline`         | Signatures without implementation bodies              |
-| Inspect one declaration        | `ast_get_symbol_source`   | Exact source for one function, method, class, or type |
-| Find usages across the project | `ast_find_references`     | Compiler-resolved reference locations                 |
-| Rename a symbol everywhere     | `ast_rename_symbol`       | A reviewed project-wide rename plan                   |
-| Change one implementation      | `ast_replace_symbol_body` | A body-only plan that preserves the declaration       |
+| Need                           | Structural operation      | Returned scope                                             |
+| ------------------------------ | ------------------------- | ---------------------------------------------------------- |
+| Read a bounded file            | `ast_get_file`            | Exact selected source lines, hashes, and bounded freshness |
+| Explore bounded context        | `ast_explore`             | Ranked selectors plus optional source and references       |
+| Understand a file              | `ast_get_outline`         | Signatures without implementation bodies                   |
+| Inspect one declaration        | `ast_get_symbol_source`   | Exact source for one function, method, class, or type      |
+| Find usages across the project | `ast_find_references`     | Compiler-resolved reference locations                      |
+| Understand symbol impact       | `ast_get_impact`          | Bounded direct/transitive compiler-backed relationships    |
+| Rename a symbol everywhere     | `ast_rename_symbol`       | A reviewed project-wide rename plan                        |
+| Change one implementation      | `ast_replace_symbol_body` | A body-only plan that preserves the declaration            |
 
 Reads can start with a bounded file slice, a compact outline, or exact source only for the declaration that needs inspection. Mutations are prepared in memory first, compared against baseline diagnostics, and returned as immutable, hash-bound plans. Nothing is written until the caller reviews and explicitly applies the plan.
 
 ### Choosing a read tool
 
-- Use `ast_get_file` when the file path is known and the agent needs exact source lines. It is read-only, uses zero-based `offset` and bounded `limit`, returns one-based line records, a SHA-256 byte hash, and `snapshot_state`.
+- Use `ast_get_file` when the file path is known and the agent needs exact source lines. It is read-only, uses zero-based `offset` and bounded `limit`, returns one-based line records, a SHA-256 byte hash, file-level `snapshot_state`, and bounded project `freshness` metadata (`fresh`, `pending`, `stale`, `rebuilding`, or `degraded`).
 - Use `ast_get_file` with `symbols_only: true` when only selectors and body-free signatures are needed from one known file.
 - Use `ast_explore` when the question spans discovery and evidence. Its default summary is bounded; use `detail: "context"` for selected source and `detail: "full"` for source plus compiler references.
 - Use `ast_get_outline` for a compact body-free view of a known file without source lines.
 - Use `ast_get_symbol_source` when one declaration or implementation is the required evidence.
+- Use `ast_get_impact` when the exact symbol is known and bounded direct/transitive compiler relationships are needed; it is read-only evidence, not a mutation plan.
+
+`snapshot_state: "fresh"` means that the returned file bytes match the synchronized compiler snapshot. The separate `freshness` object describes the project/session state and preserves causes such as source changes or watcher failure. Neither field means that the project has zero TypeScript diagnostics; use `ast_get_diagnostics` for compiler errors and warnings.
+
+### Trust, freshness and completeness
+
+The server exposes evidence labels instead of collapsing every result into an unqualified confidence score:
+
+| Label                                                                                                 | Meaning                                                                                                                                                                                                       | Safe use                                                                                                 |
+| ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `provenance: "compiler"`, `confidence: "exact"`, `resolution: "resolved"`, `freshness.state: "fresh"` | A relationship resolved by the active TypeScript compiler snapshot. This is the only combination that sets `compiler_authoritative: true`.                                                                    | May support bounded impact evidence and compiler-backed test candidates.                                 |
+| `provenance: "syntax"`                                                                                | Syntax or AST structure without semantic symbol resolution.                                                                                                                                                   | Navigation and structural context only; not proof that two symbols are related.                          |
+| `provenance: "heuristic"`                                                                             | A convention or name-based suggestion.                                                                                                                                                                        | Discovery hints only; never mutation authority or a compiler-backed test candidate.                      |
+| index evidence                                                                                        | A derived query accelerator, not compiler authority. The current production status reports the index as disabled; any future ready index still requires compiler selector validation and a compiler fallback. | Faster routing only; stale, missing or mismatched entries must fail closed or fall back to the compiler. |
+
+Freshness is orthogonal to TypeScript diagnostics. `fresh` means the evidence matches the synchronized snapshot; `pending`, `rebuilding`, `stale`, or `degraded` means the response must not be presented as current compiler evidence. Read tools expose the state, causes (`source_change`, `config_change`, `index_failure`, `watcher_failure`, or `compiler_rebuild`), and bounded `checked_at` timestamp. `ast_get_impact` refuses non-fresh compiler relationships. `ast_explore` returns the state together with `completeness`, `unresolved`, `budget`, and `truncation` metadata rather than silently dropping evidence.
 
-`snapshot_state: "fresh"` means that the returned file bytes match the synchronized compiler snapshot. It does not mean that the project has zero TypeScript diagnostics; use `ast_get_diagnostics` for compiler errors and warnings.
+All reads are budgeted. Callers control pagination and, where applicable, `max_bytes`, `reference_limit`, `max_depth`, `max_nodes`, and `max_edges`; responses report the effective limits and whether a record, byte, depth, edge, invocation, or serialization limit truncated the result. A truncated or unresolved result is incomplete evidence, not an empty negative result. The internal test-candidate resolver follows the same rule: it accepts only fresh, exact compiler-backed impact, emits direct/transitive evidence and bounded relationship IDs, and never executes tests or guesses from filenames alone.
 
 ## Why this helps
 
@@ -55,10 +76,20 @@ The included batch benchmark records a 50% reduction in model round-trips and a
 
 ## Requirements
 
-- Node.js 20.19 or newer
+- Node.js 22.5.0 or newer
 - Corepack with Yarn 4.15.0 (pinned by `packageManager`)
 - A target project with a `tsconfig.json`
 
+## Supported environment and trust boundary
+
+The supported v0.7.0 target is Linux x64 with GNU coreutils `mv` supporting `--update=none-fail`, under Node.js 22.5.0 and the current Node.js 24 line. The production-readiness matrix covers both runtimes on that target; the Node 22.5 persistence canary requires `--experimental-sqlite`. Other Linux architectures or systems without the required GNU `mv`, macOS, and Windows are unverified until they pass equivalent filesystem, process, MCP/CLI/package, and mutation gates.
+
+This is a local stdio server. It runs with the invoking user's filesystem permissions, and clients may request any `project_root` that user can access. It does not provide HTTP authentication, sandboxing, tenant isolation, or a remote-service security boundary. Remote, untrusted, and multi-tenant operation is unsupported.
+
+Symbol-index persistence remains disabled by default. `AST_SYMBOL_INDEX_PERSISTENCE=canary` additionally requires an explicit absolute `AST_SYMBOL_INDEX_CACHE_ROOT`; the reserved `enabled` mode fails closed to memory-only with `enabled_not_released`.
+
+See [Support policy](docs/support.md) for the complete platform, runtime, persistence, and operational contract. Report security issues through [SECURITY.md](SECURITY.md).
+
 ## Install
 
 Install the published CLI globally while keeping dependency lifecycle scripts disabled:
@@ -236,6 +267,7 @@ Project-scoped tools accept `project_root`, either the project directory or an e
 | `ast_get_symbol_source`     | Exact source for one declaration                                     | No            |
 | `ast_search_symbols`        | Paginated structural symbol discovery                                | No            |
 | `ast_find_references`       | Compiler-resolved references with bounded context                    | No            |
+| `ast_get_impact`            | Bounded incoming/outgoing compiler-backed impact evidence            | No            |
 | `ast_get_diagnostics`       | Project- or file-scoped TypeScript diagnostics                       | No            |
 | `ast_rename_symbol`         | Prepare a project-wide rename                                        | No            |
 | `ast_replace_symbol_body`   | Prepare a body-only replacement while preserving the signature       | No            |
@@ -251,9 +283,9 @@ Symbol search is relevance-ranked and defaults to at most 20 `summary` records c
 
 ### Optional TOON results
 
-`ast_search_symbols`, `ast_find_references`, and `ast_get_diagnostics` accept `output_format: "toon"` for collection-heavy results consumed directly by a model. JSON remains the default and preserves the canonical structured object.
+`ast_search_symbols`, `ast_find_references`, `ast_get_impact`, and `ast_get_diagnostics` accept `output_format: "toon"` for collection-heavy results consumed directly by a model. JSON remains the default and preserves the canonical structured object.
 
-MCP TOON is returned once as structured content shaped like `{ "format": "toon", "data": "..." }`; `data` is the lossless TOON document. The complete JSON result is not duplicated. These three tools validate their canonical Zod result and verify an encode/decode deep-equality round trip before presentation, but do not advertise a single MCP `outputSchema` because their successful structured content has two representations.
+MCP TOON is returned once as structured content shaped like `{ "format": "toon", "data": "..." }`; `data` is the lossless TOON document. The complete JSON result is not duplicated. These four tools validate their canonical Zod result and verify an encode/decode deep-equality round trip before presentation, but do not advertise a single MCP `outputSchema` because their successful structured content has two representations.
 
 Do not request TOON for source, outlines, file lists, previews, or mutation results. Checked negative controls show that the MCP envelope makes those shapes larger. TOON is an explicit shape-specific optimization, not a new dialect for every object in sight.
 

package/SECURITY.md

@@ -0,0 +1,31 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes are provided for the latest published minor release and the current `main` development line. During the v0.7.0 release-candidate cycle, the support window is:
+
+| Version                            | Supported                          |
+| ---------------------------------- | ---------------------------------- |
+| `main` / v0.7.0 release candidates | Yes                                |
+| 0.6.x                              | Yes, until v0.7.0 becomes `latest` |
+| 0.5.x and earlier                  | No                                 |
+
+This project supports trusted single-user local stdio use. The current v0.7.0 target supports Linux x64 only when GNU coreutils `mv` provides `--update=none-fail`, with Node.js 22.5.0 or the current Node.js 24 line. Other Linux architectures, systems without that primitive, macOS and Windows are unverified. Remote, untrusted and multi-tenant use is outside the supported security boundary.
+
+## Reporting a vulnerability
+
+Do not open a public issue for a suspected vulnerability. Email `yaildeveloper@gmail.com` with the subject `ast-mcp-server security report` and include:
+
+- affected version or commit;
+- impact and required attacker access;
+- minimal reproduction steps;
+- whether source mutation, credentials or local paths may have been exposed;
+- a safe way to coordinate follow-up.
+
+Do not include live API keys, tokens, credentials, private source bodies or production connection strings. Replace any necessary secret-shaped evidence with `[REDACTED]` and use a disposable fixture where possible.
+
+A maintainer will acknowledge the report within five business days and provide an initial triage result within ten business days. Remediation and coordinated disclosure timing depend on severity, exploitability and release impact; no universal fix deadline is promised.
+
+## Disclosure and scope
+
+Please allow time for a fix and package readback before public disclosure. Reports are evaluated against the documented local stdio trust boundary: the server runs with the invoking user's filesystem permissions and is not an OS sandbox. Vulnerabilities that cross the compiler-authority, reviewed mutation, path-containment, credential-redaction, package-provenance or release-integrity boundaries remain in scope.

package/dist/index.js

@@ -1,13 +1,132 @@
 #!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createServer } from "./server.js";
-async function main() {
-    const server = createServer();
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-    console.error("ast-mcp-server running over stdio.");
-}
-main().catch((error) => {
-    console.error("Fatal ast-mcp-server error:", error);
-    process.exit(1);
-});
+import { beginProjectShutdown, closeDrainedProjectSessions, getProjectRuntimeShutdownSnapshot, prepareProjectRuntimeForStartup, waitForProjectCompletionCriticalOperationsToDrain, waitForProjectOperationsToDrain, } from "./services/project.js";
+import { RuntimeActivityTracker } from "./services/runtime-activity.js";
+import { readRuntimePolicy } from "./services/runtime-policy.js";
+import { emitIncompleteShutdownEvent, ShutdownCoordinator, } from "./services/shutdown.js";
+function emitShutdownFailureEvent() {
+    process.stderr.write(`${JSON.stringify({ event: "shutdown_failed", version: 1 })}\n`);
+}
+export async function runStdioServer(options = {}) {
+    if (options.server && !options.runtimeActivity) {
+        throw new Error("An injected MCP server requires its runtime activity tracker.");
+    }
+    prepareProjectRuntimeForStartup();
+    const runtimeActivity = options.runtimeActivity ?? new RuntimeActivityTracker();
+    runtimeActivity.prepareForStartup();
+    const server = options.server ?? createServer({ runtimeActivity });
+    const transport = options.transport ?? new StdioServerTransport();
+    const send = transport.send.bind(transport);
+    transport.send = (message, sendOptions) => runtimeActivity.trackSend(() => send(message, sendOptions));
+    const runtimePolicy = options.runtimePolicy ?? readRuntimePolicy();
+    const installProcessHandlers = options.installProcessHandlers ?? true;
+    const exit = options.exit ?? ((code) => process.exit(code));
+    const protocol = server.server;
+    const previousTransportClose = protocol.onclose;
+    let listenersInstalled = false;
+    let terminalHandlerInstalled = false;
+    const onSigint = () => requestFromRuntime("sigint");
+    const onSigterm = () => requestFromRuntime("sigterm");
+    const onStdinEnd = () => requestFromRuntime("stdin_eof");
+    const onStdinClose = () => requestFromRuntime("stdin_eof");
+    const onTransportClose = () => {
+        previousTransportClose?.();
+        requestFromRuntime("transport_closed");
+    };
+    const removeLifecycleListeners = () => {
+        if (listenersInstalled) {
+            process.off("SIGINT", onSigint);
+            process.off("SIGTERM", onSigterm);
+            process.stdin.off("end", onStdinEnd);
+            process.stdin.off("close", onStdinClose);
+            listenersInstalled = false;
+        }
+        if (protocol.onclose === onTransportClose)
+            protocol.onclose = previousTransportClose;
+    };
+    const coordinator = new ShutdownCoordinator({
+        drainTimeoutMs: runtimePolicy.shutdownDrainTimeoutMs,
+        stopAdmissionAndCancel: () => {
+            runtimeActivity.beginShutdown();
+            return beginProjectShutdown();
+        },
+        getDrainSnapshot: getProjectRuntimeShutdownSnapshot,
+        waitForDrain: async () => {
+            await Promise.all([waitForProjectOperationsToDrain(), runtimeActivity.waitForIdle()]);
+        },
+        waitForCompletionCriticalOperationsToDrain: waitForProjectCompletionCriticalOperationsToDrain,
+        closeMcp: async () => {
+            await server.close();
+        },
+        closeProjects: closeDrainedProjectSessions,
+        emitIncompleteShutdown: emitIncompleteShutdownEvent,
+        onCompletionCriticalWait: options.onCompletionCriticalWait,
+    });
+    let lifecycleCompletion;
+    function requestShutdown(trigger) {
+        lifecycleCompletion ??= coordinator.shutdown(trigger).finally(removeLifecycleListeners);
+        return lifecycleCompletion;
+    }
+    function requestFromRuntime(trigger) {
+        try {
+            options.onRuntimeTrigger?.(trigger);
+        }
+        catch {
+            // Runtime observation is non-authoritative and must never interrupt shutdown.
+        }
+        const completion = requestShutdown(trigger);
+        if (terminalHandlerInstalled)
+            return;
+        terminalHandlerInstalled = true;
+        void completion
+            .then((result) => {
+            if (result.state === "forced_noncritical")
+                exit(1);
+        })
+            .catch(() => {
+            emitShutdownFailureEvent();
+            exit(1);
+        });
+    }
+    protocol.onclose = onTransportClose;
+    if (installProcessHandlers) {
+        process.on("SIGINT", onSigint);
+        process.on("SIGTERM", onSigterm);
+        process.stdin.once("end", onStdinEnd);
+        process.stdin.once("close", onStdinClose);
+        listenersInstalled = true;
+    }
+    try {
+        await server.connect(transport);
+    }
+    catch (error) {
+        await requestShutdown("requested").catch(() => undefined);
+        throw error;
+    }
+    if (options.logStartup ?? true)
+        process.stderr.write("ast-mcp-server running over stdio.\n");
+    return Object.freeze({
+        shutdown: (trigger = "requested") => requestShutdown(trigger),
+    });
+}
+function isMainModule() {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    try {
+        return fs.realpathSync(entry) === fs.realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return path.resolve(entry) === path.resolve(fileURLToPath(import.meta.url));
+    }
+}
+if (isMainModule()) {
+    runStdioServer().catch(() => {
+        process.stderr.write("Fatal ast-mcp-server startup error.\n");
+        process.exit(1);
+    });
+}

package/dist/server.js

@@ -1,9 +1,11 @@
 import { createRequire } from "node:module";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer, } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { PublicOperationalError } from "./services/public-errors.js";
 import { registerApplyOperation } from "./tools/apply_operation.js";
 import { registerFindReferences } from "./tools/find_references.js";
 import { registerGetDiagnostics } from "./tools/get_diagnostics.js";
 import { registerGetFile } from "./tools/get_file.js";
+import { registerGetImpact } from "./tools/get_impact.js";
 import { registerGetOperationPreview } from "./tools/get_operation_preview.js";
 import { registerGetOutline } from "./tools/get_outline.js";
 import { registerGetProjectStatus } from "./tools/get_project_status.js";
@@ -14,13 +16,29 @@ import { registerReplaceSymbolBody } from "./tools/replace_symbol_body.js";
 import { registerScaffoldClass } from "./tools/scaffold_class.js";
 import { registerSearchSymbols } from "./tools/search_symbols.js";
 import { registerExplore } from "./tools/explore.js";
+import { createToolErrorContext, errorResult } from "./tools/result.js";
 const packageMetadata = createRequire(import.meta.url)("../package.json");
 export const PACKAGE_VERSION = packageMetadata.version;
-export function createServer() {
+function installRuntimeActivityTracking(server, runtimeActivity) {
+    const registerTool = server.registerTool.bind(server);
+    function trackedRegisterTool(name, config, callback) {
+        const trackedCallback = (async (...args) => runtimeActivity.trackRequest(() => {
+            if (runtimeActivity.admission === "closed") {
+                return errorResult(new PublicOperationalError("SERVER_SHUTTING_DOWN", "Server is shutting down."), createToolErrorContext(name));
+            }
+            return Reflect.apply(callback, undefined, args);
+        }));
+        return registerTool(name, config, trackedCallback);
+    }
+    server.registerTool = trackedRegisterTool;
+}
+export function createServer(options = {}) {
     const server = new McpServer({
         name: "ast-mcp-server",
         version: PACKAGE_VERSION,
     });
+    if (options.runtimeActivity)
+        installRuntimeActivityTracking(server, options.runtimeActivity);
     registerListFiles(server);
     registerGetProjectStatus(server);
     registerExplore(server);
@@ -28,6 +46,7 @@ export function createServer() {
     registerGetSymbolSource(server);
     registerSearchSymbols(server);
     registerFindReferences(server);
+    registerGetImpact(server);
     registerGetDiagnostics(server);
     registerGetFile(server);
     registerRenameSymbol(server);

package/dist/services/agent-setup.js

@@ -4,27 +4,9 @@ import { access, realpath, stat } from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";
 import { installBundledSkill, SkillConflictError, } from "./skill-installer.js";
-import { AGENT_IDS } from "./setup-wizard.js";
-const MCP_SERVER_NAME = "ast";
+import { AGENT_IDS, getAgentTarget, MCP_SERVER_NAME, } from "./agent-targets.js";
 const DEFAULT_COMMAND_TIMEOUT_MS = 120_000;
 const MAX_COMMAND_OUTPUT_BYTES = 1024 * 1024;
-const EXPECTED_HERMES_TOOLS = [
-    "ast_list_files",
-    "ast_get_outline",
-    "ast_get_symbol_source",
-    "ast_search_symbols",
-    "ast_find_references",
-    "ast_get_diagnostics",
-    "ast_rename_symbol",
-    "ast_replace_symbol_body",
-    "ast_scaffold_class",
-    "ast_get_operation_preview",
-    "ast_apply_operation",
-];
-const AGENT_DEFINITIONS = {
-    claude: { label: "Claude Code", command: "claude" },
-    hermes: { label: "Hermes", command: "hermes" },
-};
 export class AgentSetupError extends Error {
     code;
     details;
@@ -128,102 +110,44 @@ async function runCommand(executable, args, options) {
 }
 function commandFailure(agent, operation, result) {
     const output = `${result.stdout}\n${result.stderr}`.trim().slice(0, 4000);
-    return new AgentSetupError(`${AGENT_DEFINITIONS[agent].label} ${operation} failed with exit code ${result.exitCode}.`, "AGENT_COMMAND_FAILED", { agent, operation, output });
+    return new AgentSetupError(`${getAgentTarget(agent).label} ${operation} failed with exit code ${result.exitCode}.`, "AGENT_COMMAND_FAILED", { agent, operation, output });
 }
-function isMissingClaudeMcp(output) {
-    return (/\bno\s+mcp\s+server\b/i.test(output) &&
-        /(?:\bfound\b|\bnamed?\b)/i.test(output) &&
-        /\bast\b/i.test(output));
-}
-async function inspectClaudeMcp(detection, serverEntryPath, nodeExecutable, environment, timeoutMs) {
-    const result = await runCommand(detection.executable, ["mcp", "get", MCP_SERVER_NAME], {
-        environment,
-        timeoutMs,
-    });
-    const output = `${result.stdout}\n${result.stderr}`;
-    if (result.exitCode !== 0) {
-        if (isMissingClaudeMcp(output)) {
-            return { agent: "claude", status: "missing" };
-        }
-        throw commandFailure("claude", "MCP inspection", result);
-    }
-    const fields = new Map();
-    for (const line of result.stdout.split(/\r?\n/)) {
-        const match = line.match(/^\s*(Status|Type|Command|Args):\s*(.*)$/i);
-        if (match !== null) {
-            fields.set(match[1].toLowerCase(), match[2].trim());
-        }
-    }
-    const current = /connected/i.test(fields.get("status") ?? "") &&
-        fields.get("type")?.toLowerCase() === "stdio" &&
-        fields.get("command") === nodeExecutable &&
-        fields.get("args") === serverEntryPath;
-    return current
-        ? { agent: "claude", status: "current" }
-        : {
-            agent: "claude",
-            status: "conflict",
-            detail: "The existing user-scoped 'ast' registration does not match this package.",
-        };
-}
-async function inspectHermesMcp(detection, environment, timeoutMs) {
-    const listed = await runCommand(detection.executable, ["mcp", "list"], {
-        environment,
-        timeoutMs,
-    });
-    if (listed.exitCode !== 0) {
-        throw commandFailure("hermes", "MCP list", listed);
-    }
-    if (!/^\s*ast(?:\s|$)/im.test(listed.stdout)) {
-        return { agent: "hermes", status: "missing" };
-    }
-    const tested = await runCommand(detection.executable, ["mcp", "test", MCP_SERVER_NAME], {
-        environment,
-        timeoutMs,
-    });
-    const current = tested.exitCode === 0 && EXPECTED_HERMES_TOOLS.every((tool) => tested.stdout.includes(tool));
-    return current
-        ? { agent: "hermes", status: "current" }
-        : {
-            agent: "hermes",
-            status: "conflict",
-            detail: "The existing 'ast' registration does not expose the expected structural tools.",
-        };
+function targetRuntime(detection, environment, timeoutMs) {
+    return {
+        run: (args, input) => runCommand(detection.executable, [...args], {
+            environment,
+            timeoutMs,
+            input,
+        }),
+    };
 }
 async function inspectMcp(agent, detection, serverEntryPath, nodeExecutable, environment, timeoutMs) {
-    return agent === "claude"
-        ? inspectClaudeMcp(detection, serverEntryPath, nodeExecutable, environment, timeoutMs)
-        : inspectHermesMcp(detection, environment, timeoutMs);
-}
-async function configureClaudeMcp(detection, serverEntryPath, nodeExecutable, environment, timeoutMs) {
-    const added = await runCommand(detection.executable, [
-        "mcp",
-        "add",
-        "--scope",
-        "user",
-        "--transport",
-        "stdio",
-        MCP_SERVER_NAME,
-        "--",
-        nodeExecutable,
+    const target = getAgentTarget(agent);
+    const inspection = await target.mcp.inspect(targetRuntime(detection, environment, timeoutMs), {
         serverEntryPath,
-    ], { environment, timeoutMs });
-    if (added.exitCode !== 0) {
-        throw commandFailure("claude", "MCP registration", added);
-    }
-    const verified = await inspectClaudeMcp(detection, serverEntryPath, nodeExecutable, environment, timeoutMs);
-    if (verified.status !== "current") {
-        throw new AgentSetupError("Claude Code saved the MCP registration but verification did not match.", "AGENT_VERIFICATION_FAILED", { agent: "claude", inspection: verified });
+        nodeExecutable,
+    });
+    if (inspection.status === "error") {
+        throw commandFailure(agent, inspection.operation, inspection.result);
     }
+    return {
+        agent,
+        status: inspection.status,
+        ...(inspection.detail ? { detail: inspection.detail } : {}),
+    };
 }
-async function configureHermesMcp(detection, serverEntryPath, nodeExecutable, environment, timeoutMs) {
-    const added = await runCommand(detection.executable, ["mcp", "add", MCP_SERVER_NAME, "--command", nodeExecutable, "--args", serverEntryPath], { environment, timeoutMs, input: "\n" });
-    if (added.exitCode !== 0 || !/saved\s+'ast'/i.test(added.stdout)) {
-        throw commandFailure("hermes", "MCP registration", added);
+async function configureMcp(agent, detection, serverEntryPath, nodeExecutable, environment, timeoutMs) {
+    const target = getAgentTarget(agent);
+    const added = await target.mcp.register(targetRuntime(detection, environment, timeoutMs), {
+        serverEntryPath,
+        nodeExecutable,
+    });
+    if (!target.mcp.registrationAccepted(added)) {
+        throw commandFailure(agent, "MCP registration", added);
     }
-    const verified = await inspectHermesMcp(detection, environment, timeoutMs);
+    const verified = await inspectMcp(agent, detection, serverEntryPath, nodeExecutable, environment, timeoutMs);
     if (verified.status !== "current") {
-        throw new AgentSetupError("Hermes saved the MCP registration but verification did not expose the expected tools.", "AGENT_VERIFICATION_FAILED", { agent: "hermes", inspection: verified });
+        throw new AgentSetupError(`${target.label} saved the MCP registration but verification did not match.`, "AGENT_VERIFICATION_FAILED", { agent, inspection: verified });
     }
 }
 async function assertRegularFile(filePath, label) {
@@ -248,7 +172,7 @@ export async function detectInstalledAgents(options = {}) {
     const environment = options.environment ?? process.env;
     const timeoutMs = options.commandTimeoutMs ?? 5000;
     return Promise.all(AGENT_IDS.map(async (id) => {
-        const definition = AGENT_DEFINITIONS[id];
+        const definition = getAgentTarget(id);
         const executable = await findExecutable(definition.command, environment);
         if (executable === undefined) {
             return { id, label: definition.label, installed: false };
@@ -282,7 +206,7 @@ export async function runAgentSetup(options) {
     for (const agent of requested) {
         const detection = detectionMap.get(agent);
         if (!detection?.installed || detection.executable === undefined) {
-            throw new AgentSetupError(`${AGENT_DEFINITIONS[agent].label} is not installed or is not available in PATH.`, "AGENT_NOT_INSTALLED", { agent });
+            throw new AgentSetupError(`${getAgentTarget(agent).label} is not installed or is not available in PATH.`, "AGENT_NOT_INSTALLED", { agent });
         }
     }
     await assertRegularFile(options.serverEntryPath, "MCP server entrypoint");
@@ -290,9 +214,9 @@ export async function runAgentSetup(options) {
     const inspections = await Promise.all(requested.map((agent) => inspectMcp(agent, detectionMap.get(agent), options.serverEntryPath, nodeExecutable, environment, timeoutMs)));
     const conflict = inspections.find((item) => item.status === "conflict");
     if (conflict !== undefined) {
-        throw new AgentSetupError(`Conflicting ${AGENT_DEFINITIONS[conflict.agent].label} MCP registration: ${conflict.detail}`, "AGENT_MCP_CONFLICT", { agent: conflict.agent });
+        throw new AgentSetupError(`Conflicting ${getAgentTarget(conflict.agent).label} MCP registration: ${conflict.detail}`, "AGENT_MCP_CONFLICT", { agent: conflict.agent });
     }
-    const skillTarget = requested.length === 2 ? "all" : requested[0];
+    const skillTarget = requested.length === AGENT_IDS.length ? "all" : getAgentTarget(requested[0]).skillTarget;
     const skillResult = await installBundledSkill({
         target: skillTarget,
         scope: "user",
@@ -312,12 +236,7 @@ export async function runAgentSetup(options) {
         const inspection = inspections.find((item) => item.agent === agent);
         try {
             if (inspection.status === "missing") {
-                if (agent === "claude") {
-                    await configureClaudeMcp(detection, options.serverEntryPath, nodeExecutable, environment, timeoutMs);
-                }
-                else {
-                    await configureHermesMcp(detection, options.serverEntryPath, nodeExecutable, environment, timeoutMs);
-                }
+                await configureMcp(agent, detection, options.serverEntryPath, nodeExecutable, environment, timeoutMs);
             }
             completed.push({
                 agent,