@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

📦 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