Commands

InstallCopy Anchor Link

npm install --save-dev @mwillbanks/ast-mcp

Runtime formatting is disabled by default. Install a formatter separately only when you choose to enable it; ast-mcp does not download formatter binaries during file operations. See the optional formatting guide.

Manage host surfacesCopy Anchor Link

./node_modules/.bin/ast-mcp install --scope local --target all
./node_modules/.bin/ast-mcp install --scope local --target all \
  --transport http --host 127.0.0.1 --port 3768 [--service]
./node_modules/.bin/ast-mcp update --scope local --target all \
  [--transport stdio|http] [--no-service]
./node_modules/.bin/ast-mcp uninstall --scope local --target all

Installer results contain changed paths, the effective transport, HTTP endpoint, service identity/state, and a manual startup command when no service is managed. The shared CLI renderer selects the output format described below.

Export the skill for unsupported clientsCopy Anchor Link

ast-mcp skills export <destination>
ast-mcp skills update <destination>

The destination is the skill root and contains SKILL.md. Export preserves existing files and records managed hashes. Update replaces only unchanged managed files. It preserves customizations and returns a nonzero exit for conflicts. MCP Skills clients need no manual refresh unless they select a local copy. See the MCP Skills guide for recovery and migration.

ConfigurationCopy Anchor Link

ast-mcp config validate
ast-mcp config show
ast-mcp config migrate
ast-mcp config migrate --check
ast-mcp config migrate --write [--no-backup]
ast-mcp config migrate --file ./ast-mcp.toml [--to 2]
ast-mcp config migrate --global [--check|--write]

validate and show resolve environment, project, global, and default layers. Migration defaults to preview; --check exits 0 when current, 2 when migration is required, and 1 for invalid input. --write performs atomic replacement and creates a .v1.bak unless disabled.

Output formatsCopy Anchor Link

User-facing configuration, installer, and skills commands detect whether stdout is an interactive terminal. Interactive stdout defaults to readable human summaries and sections. Redirected or piped stdout defaults to JSON.

ast-mcp config show --output human
ast-mcp config validate --output=json
ast-mcp --output yaml config show
ast-mcp skills export ./manual-skill --output toml

Both --output <format> and --output=<format> accept human, json, yaml, or toml. The flag can appear before or after the command. Explicit flags override configured defaults. Invalid, missing, or duplicate output flags fail before command execution, including when help is requested.

JSON preserves the existing configuration and installer result fields. Skills commands return operation, destination, written, updated, unchanged, preserved, obsolete, and conflicts. YAML and TOML use Bun's native serializers. TOML omits null and undefined object fields recursively. Unrepresentable array entries produce an error; select JSON or YAML instead. Diagnostics remain on stderr and command exit codes are unchanged.

For uninstall or skills commands, specify --output json when invalid runtime configuration prevents loading output defaults. Explicit output skips that configuration lookup. Operation-specific configuration validation still applies.

MCP and hook commands retain their protocol output and reject --output.

RuntimeCopy Anchor Link

ast-mcp mcp
ast-mcp mcp --transport http [--host 127.0.0.1] [--port 3768]
bun run dev
bun run dev:http

Runtime HTTP flags have highest precedence. --host and --port are rejected for stdio, and invalid transport or port values return command-specific usage errors.

Quality gatesCopy Anchor Link

bun run tools:check
bun run format
bun run lint
bun run test
bun run skill:check
bun run evals:check
bun run fallow

Development uses Bun 1.4.4. bun run format executes bun fmt .; bun run format:check runs bun fmt --check .. The lint script combines formatting checks, Bun typechecking, and runtime import-boundary validation. Use bun check --no-script to run Bun's native checker without the aggregate check script.

DistributionCopy Anchor Link

bun run build
bun pm pack --dry-run

The Bun build bundles bin/ast-mcp.ts into dist/ast-mcp.js as a Bun-targeted ESM executable with an external source map. Its install, update, uninstall, hook, mcp, skills, and config subcommands share the same stable package dependency tree.

DocumentationCopy Anchor Link

bun install --cwd website
bun run --cwd website dev
bun run --cwd website lint
bun run --cwd website test
BASE_PATH=/ast-mcp/ bun run --cwd website build