@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