Connection diagnosis

During install or update, ast-mcp launches the configured executable and checks MCP initialization, discovery of the required file and workspace tools, and clean shutdown before it writes host configuration. The separate scripts/check-install.ts checker can run a stdio smoke test that also opens the requested workspace; a failed smoke check marks MCP unhealthy. It does not verify a live host connection or HTTP endpoint.

Local installations use their installed executable alias when available. Source launches use absolute Bun and script paths with the project working directory. Verified source launches have project-bound receipts outside the bundled skill directory. Incorrect arguments, missing scripts, or mismatched working directories fail health checks. Source-mode installs record the absolute runtime, script, and project root in a project-bound receipt under the user's home directory. The receipt lets checks verify the source launch belongs to that project; it does not prove the host is currently connected.

Missing tools or lost connectionsCopy Anchor Link

A stdio server runs as a child of its host. A crashed child, invalid launch command, closed stream, or blocked request can make its tools unavailable.

Inspect the host's MCP logs and the server's stderr. Protocol responses use stdout; diagnostics use stderr. Check the executable, arguments, working directory, and configured transport.

After updating the package or launch configuration, restart or reconnect the MCP server through your host. An MCP server cannot restart its host-owned stdio process. Restarting stdio or a legacy HTTP session clears its session-scoped approvals. Modern stateless HTTP has no trusted caller session for host approval, so any request requiring elicitation fails closed with approval_required; use stdio or a legacy host session for approval flows. Explicit global permissions remain usable. If tools are available but the skill is missing, check whether the host supports MCP Skills. Compatible clients discover and load the skill from the server; other clients need ast-mcp skills export <destination> and host-side setup. See the skills guide.

Recoverable framing and tool errors leave the connection usable. Fatal failures emit diagnostics, perform bounded cleanup, and exit nonzero. Shutdown uses a five-second deadline.

Slow or blocked requestsCopy Anchor Link

A legacy client's roots request has a five-second deadline. Failed roots requests leave the cache so later calls can retry. Cancelling one caller does not cancel a shared roots request.

Legacy approval prompts have a 60-second absolute deadline. Progress notifications cannot extend that deadline. Other requests can proceed while a prompt waits. A timeout denies the pending operation; inspect the response and retry when the host can display prompts. Modern clients receive input_required immediately and submit their approval response separately.

File reads, hashes, and capability checks have a 30-second deadline. Cancellation closes their active streams and stops further batch work. Mutation snapshots reject pipes and other nonregular files before reading them.

File write and patch batches wait up to ten seconds for mutation locks. Caller cancellation stops lock waits and is checked before replacements. A cancelled batch rolls back completed replacements before releasing its locks.

Mutation recovery and writes use one fenced transaction lock per checkout. Operating-system transactions prevent an expired lease from admitting another writer while its owner remains active. Process exit releases the operating-system lock. Lock identities use canonical paths and private account storage, independent of host temporary directories and intelligence storage domains. Restart every MCP process after upgrading so all writers use this protocol. Fast recovery requires a current-protocol record owned by the same operating-system account; foreign and legacy records retain their actual lease expiry. Private account guards also acquire resource-local SQLite guards. File and checkout guards use a hashed database under Git metadata in ast-mcp-locks, or under the nearest configured root in .ast-mcp-locks. Git worktree metadata files are supported. Unmarked external paths use .ast-mcp-mutation-locks in their nearest existing parent. Intelligence and export guards remain inside their resource directories. These resource guards serialize accounts that can open the same guard database. POSIX guard files use mode 0600; another account without access fails closed. Windows uses filesystem ACL authorization and shared SQLite exclusion. Guard databases remain present after release; do not remove them while any server process runs. File deletion preserves empty ancestor cleanup within Git and configured projects. Unmarked external paths can retain their reserved coordination directory. Guard databases and SQLite sidecars are excluded from working-state identities and intelligence source selection. Symlinks, nonregular files, hard links, and replaced guard inodes fail closed. Recovery cannot restore another active transaction. Preview-only patches do not open the intelligence store. Writes do not initialize a previously unindexed workspace; explicitly index it when needed. Existing indexed workspaces retain their synchronous freshness checks. Refresh has a cooperative 30-second deadline and uses cancellable parser workers. A refresh timeout rolls back the mutation; explicitly index the workspace before retrying.

Install, update, and uninstall operations serialize shared checkout and home state. Service commands have a ten-second deadline. Readiness checks have a five-second overall deadline. Configuration updates use atomic replacements and reject concurrent changes with configuration_conflict; reload and retry. A busy configuration transaction fails promptly instead of waiting inside an approval prompt.

Configuration commits keep <canonical config>.config-commit.sqlite beside the resolved configuration file. For symlinked configuration, the database lives beside the symlink target. SQLite can also create -journal, -wal, and -shm sidecars. Releasing the lock closes its handles but preserves the database to maintain one shared operating-system lock identity. Do not delete these files while any MCP server or installer process is active.

If the configuration target is in a versioned repository, add these patterns to that repository's .gitignore:

*.config-commit.sqlite
*.config-commit.sqlite-journal
*.config-commit.sqlite-wal
*.config-commit.sqlite-shm

Default embedding model queue waits and model loading have separate five-minute deadlines. Inference has a 30-second deadline. Patch preparation also runs in workers, including native AST rewrites and text matching. Cancellation terminates active preparation before file replacement. Worker retirement retains its capacity reservation until termination completes. Language requests wait within their request admission deadline while their worker retires, then resume automatically when retirement succeeds. Failed retirement remains quarantined, reports queue_full, and cleanup reports the failure. Restart the affected MCP process when retirement cannot complete.

A stalled-tool telemetry event reports an operation still running after 15 seconds. It does not cancel the operation or indicate a completed failure. Inspect completed events separately. See telemetry.

Stdio framingCopy Anchor Link

Each newline-delimited JSON frame can contain up to 10 MiB. Multiple valid frames can arrive together in a larger aggregate chunk. Fragmented frames remain supported.

Malformed or oversized frames receive protocol errors and recover at the next newline boundary. Requests retain their IDs. Notifications receive no response. Stdio keeps one connection state per process. Modern HTTP requests are stateless and do not require an initialize exchange or MCP session header; pass workspaceId to reuse application workspace handles within the running server. Legacy HTTP clients retain separate, isolated MCP session state.

Intelligence request budgetsCopy Anchor Link

Intelligence parsing and graph computation run in workers. A timed-out or cancelled request terminates its worker so subsequent MCP calls can proceed.

Requests default to a 30-second deadline. Parsing limits each source to 2 MiB and 100,000 nodes. Request source and parsed-data budgets are 16 MiB. At most four CPU requests run concurrently, and file inventories are limited to 100,000 paths.

An intelligence_budget_exceeded response requires a narrower request. Select explicit paths, a glob, or a smaller scan_limit. Narrow paths or globs when the file inventory itself exceeds its limit.

For file_delete, reference_verification_failed means the reference scan could not finish safely; no batch targets were deleted. Check for parser errors, invalid UTF-8, per-file or total byte limits, and inventory limits. External cancellation may return its own cancellation error instead; cancellation during preflight still leaves all targets unchanged. Resolve the issue and retry. Use forceReferences: true only after reviewing references yourself. See the filesystem access guide for scan coverage and exact limits.

A successful delete response may include cleanup.status: "deferred" with cleanup.code: "lock_deadline", or cleanup.status: "failed" with lock_fenced, EACCES, EPERM, or cleanup_failed. The file deletion already committed in either case; do not retry it. removedDirectories is empty; some empty parent directories may remain. The deferred result means waiting for a contended cleanup lock exceeded its 1-second deadline; path resolution, filesystem operations, or lease publication may take longer. Caller cancellation does not abort cleanup after deletion commits.

Tool schemas reject unsupported fields before scanning. Supply target for impact, callers, callees, trace, context, and implements. Supply file or path for dependency queries, a query or target for search, and pattern for run.

For example, limit an impact request to the relevant source directory:

{
  "target": "reconcile",
  "paths": ["src"],
  "scan_limit": 100,
  "timeout_ms": 5000
}

Use workspaceId when the host exposes multiple workspaces. Inspect truncation and omission metadata before treating scan results as exhaustive.