ast-mcp-server 0.5.1 → 0.7.0

package/CHANGELOG.md

@@ -4,6 +4,40 @@ 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
 
 ### Added
@@ -16,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
 
@@ -84,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,15 +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                                        |
-| ------------------------------ | ------------------------- | ----------------------------------------------------- |
-| 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, 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. |
 
-Reads can start with a compact outline and fetch exact source only when needed. 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.
+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.
+
+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
 
@@ -39,14 +72,24 @@ Reads can start with a compact outline and fetch exact source only when needed.
 
 AST-aware editing is not a proof that a change is semantically correct. The safety comes from combining structural selection with diagnostics, exact previews, reviewed hashes, freshness checks, and fail-closed apply semantics.
 
-The included batch benchmark records a 50% reduction in model round-trips and a 94.67% reduction in serialized context for its search-to-source scenario. The result-shaping corpus records a 68.80% reduction in aggregate model-facing TOON tokens while preserving declared selectors/reference coordinates with the same six logical calls. The separate format benchmark records 25.87% across its eligible collection corpus. These are reproducible local `o200k_base` estimates, not universal token, billing, cache, or latency claims.
+The included batch benchmark records a 50% reduction in model round-trips and a 94.67% reduction in serialized context for its search-to-source scenario. The result-shaping corpus records a 68.80% reduction in aggregate model-facing TOON tokens while preserving declared selectors/reference coordinates with the same six logical calls. The separate format benchmark records 25.87% across its eligible collection corpus. The context workflow benchmark verifies evidence preservation and call bounds for full-file, primitive, and `ast_explore` workflows. These are reproducible local `o200k_base` estimates, not universal token, billing, cache, or latency claims.
 
 ## 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:
@@ -217,10 +260,14 @@ Project-scoped tools accept `project_root`, either the project directory or an e
 | Tool                        | Purpose                                                              | Mutates files |
 | --------------------------- | -------------------------------------------------------------------- | ------------- |
 | `ast_list_files`            | Paginated, project-relative source file inventory                    | No            |
+| `ast_get_project_status`    | Read-only compiler, freshness, index, and operation status           | No            |
+| `ast_explore`               | Bounded composed selectors, source evidence, and references          | No            |
+| `ast_get_file`              | Bounded exact source lines, byte hash, and snapshot state            | No            |
 | `ast_get_outline`           | Body-free declaration signatures; detailed symbol metadata is opt-in | No            |
 | `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            |
@@ -230,13 +277,15 @@ Project-scoped tools accept `project_root`, either the project directory or an e
 
 Read results use project-relative paths, deterministic ordering, structured MCP output, and pagination where result sets can grow with the project.
 
+`ast_explore` supports query, exact file, and exact symbol routes. Its default `summary` profile returns bounded reusable selectors; `context` adds selected source and `full` adds compiler references. Every response reports freshness, completeness, truncation, unresolved selectors, record limits, and a serialized byte budget. Use the primitive tools when a single exact operation is clearer or when preparing a mutation.
+
 Symbol search is relevance-ranked and defaults to at most 20 `summary` records containing `file`, a directly reusable `selector`, `kind`, and body-free `signature`. Request `detail: "selectors"` for routing coordinates only, or `detail: "full", limit: 100` for the v0.4.0 fields/page. References default to `detail: "locations"`; request `detail: "context"` only when the bounded source line is needed.
 
 ### 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.
 
@@ -392,7 +441,7 @@ The batch benchmark compares two separate client calls with one batch invocation
 
 The format benchmark runs real tools against this repository plus deterministic reference/diagnostic fixtures. It checks JSON→TOON→value equality, UTF-8 bytes, `gpt-tokenizer` `o200k_base` estimates, encode/decode latency, the actual MCP envelope, tool metadata, and negative controls. Its checked result is `benchmark/results/self-formats.json`; local tokenizer estimates do not establish provider-side billing or cache savings. See `benchmark/README.md` for methodology and limitations.
 
-The result-shaping benchmark compares the v0.4.0-compatible `full/100/context` profiles with the new public defaults across exact-name, exact-path, prefix, broad-substring, and multi-file-reference tasks. It fails on missing evidence, extra logical calls, fewer than 11 tools, or less than 35% aggregate TOON token reduction. Its checked result is `benchmark/results/self-result-shapes.json`.
+The result-shaping benchmark compares the v0.4.0-compatible `full/100/context` profiles with the new public defaults across exact-name, exact-path, prefix, broad-substring, and multi-file-reference tasks. It fails on missing evidence, extra required calls, fewer than the benchmark's required minimum tool surface, or less than 35% aggregate TOON token reduction. Its checked result is `benchmark/results/self-result-shapes.json`.
 
 ## Scope
 

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,8 +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";
@@ -12,20 +15,40 @@ import { registerRenameSymbol } from "./tools/rename_symbol.js";
 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);
     registerGetOutline(server);
     registerGetSymbolSource(server);
     registerSearchSymbols(server);
     registerFindReferences(server);
+    registerGetImpact(server);
     registerGetDiagnostics(server);
+    registerGetFile(server);
     registerRenameSymbol(server);
     registerReplaceSymbolBody(server);
     registerScaffoldClass(server);