@aiready/ast-mcp-server

Best-in-Class TypeScript/JavaScript Codebase Exploration for AI Agents.

This Model Context Protocol (MCP) server provides high-precision, AST-aware tools for navigating complex codebases. Unlike standard search tools, it understands imports, exports, types, and references.

🚀 Key Features

• Hybrid Indexing: Combines ripgrep speed with ts-morph precision. Only loads relevant files into memory to handle massive monorepos.
• O(1) Symbol Resolution: Instantly find where any function, class, or type is defined using a pre-built disk cache.
• Surgical Reference Finding: Uses a two-stage lookup (Regex + AST) to find every usage of a symbol across the project without OOM crashes.
• Monorepo Intelligent: Automatically discovers tsconfig.json boundaries and respects TypeScript project references.
• Zero Configuration: Bundles the ripgrep binary and handles all TypeScript parsing out-of-the-box.
• Path Security: Hardened against path traversal and malicious agent inputs.

🛠 Tools Provided

Tool	Purpose
resolve_definition	Find where a symbol is defined (file, line, signature, JSDoc).
find_references	Find all usages of a symbol across the project (paged).
find_implementations	Find concrete classes implementing an interface/abstract class.
get_file_structure	Return a structural tree of a file (classes, methods, enums).
search_code	Blazingly fast regex search via bundled ripgrep.
get_symbol_docs	Extract full JSDoc/TSDoc metadata for any symbol.
get_call_hierarchy	Find callers and callees for a symbol (incoming/outgoing).
build_symbol_index	Warm the disk cache for a project (highly recommended).

📦 Installation

npx -y @aiready/ast-mcp-server

⚙️ Configuration

Environment Variables

• AST_WORKSPACE_ROOT: Path to the root of the allowed workspace (default: cwd).
• AST_MAX_HEAP_MB: Max memory allowed for AST Projects (default: 1536).
• AST_WORKER_POOL_SIZE: Number of worker threads for parsing (default: 2).

Agent Configuration (Cursor/Claude Desktop)

{
  "mcpServers": {
    "ast-explorer": {
      "command": "npx",
      "args": ["-y", "@aiready/ast-mcp-server"],
      "env": {
        "AST_WORKSPACE_ROOT": "/path/to/your/project"
      }
    }
  }
}

🛡 Security

All tool arguments are strictly validated. Any attempt by an agent to access files outside the AST_WORKSPACE_ROOT will result in a hard rejection.

📄 License

MIT © AIReady