@aiready/ast-mcp-server 0.1.0 → 0.1.2

package/README.md

@@ -1,118 +1,64 @@
 # @aiready/ast-mcp-server
 
-AST-aware codebase exploration tools for Model Context Protocol. Explore and navigate multi-project TypeScript/JavaScript codebases with high precision using AST and type information.
+**Best-in-Class TypeScript/JavaScript Codebase Exploration for AI Agents.**
 
-## Installation & Distribution Channels
+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.
 
-You can install and use the AIReady AST MCP server through several supported channels.
+## 🚀 Key Features
 
-### 1. Dedicated MCP Registries
+- **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.
 
-- **[Smithery](https://smithery.ai/server/@aiready/ast-mcp-server)**: Discover and install our server directly via the Smithery CLI:
-  ```bash
-  npx @smithery/cli install @aiready/ast-mcp-server
-  ```
-- **[Glama](https://glama.ai/mcp/@aiready/ast-mcp-server)**: View our listing and integration options on the Glama directory.
-- **[Pulsar](https://gotopulsar.com)**: Find us on the Pulsar registry for MCP servers.
+## 🛠 Tools Provided
 
-### 2. Direct IDE / Assistant Integrations
+| 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.               |
+| `build_symbol_index`   | Warm the disk cache for a project (highly recommended).         |
 
-#### Claude Desktop App
+## 📦 Installation
 
-To use the AIReady AST MCP server in the Claude Desktop app, add the following configuration to your `claude_desktop_config.json`:
-
-```json
-"mcpServers": {
-  "aiready-ast": {
-    "command": "npx",
-    "args": ["-y", "@aiready/ast-mcp-server"]
-  }
-}
+```bash
+npx -y @aiready/ast-mcp-server
 ```
 
-#### Cursor IDE
-
-1. Open Cursor Settings.
-2. Navigate to **Features** -> **MCP Servers**.
-3. Add a new server.
-4. Set the command to: `npx -y @aiready/ast-mcp-server`
-
-#### Windsurf IDE
-
-1. Open Windsurf Settings or local environment configuration.
-2. Add a new MCP Server integration.
-3. Configure the execution command: `npx -y @aiready/ast-mcp-server`
-
-## Features
-
-- **Resolve Definition**: Pinpoint exactly where symbols are defined using TypeScript's type system.
-- **Find References**: Locate every usage of a function, class, or variable.
-- **Find Implementations**: Discover concrete implementations of interfaces and abstract classes.
-- **File Structure overview**: Get a high-level summary of imports, exports, and declarations.
-- **Search Code**: Blazingly fast regex search powered by Ripgrep.
-- **Symbol Documentation**: Instantly fetch JSDoc/TSDoc for any symbol.
-- **Symbol Indexing**: Project-wide symbol indexing for rapid navigation.
-
-## Tools
-
-### 1. `resolve_definition`
-
-Find where a symbol is defined.
-
-- `symbol`: Name of the symbol.
-- `path`: Project root or target directory.
-
-### 2. `find_references`
-
-Find all usages of a symbol.
-
-- `symbol`: Symbol name.
-- `path`: Project root.
-
-### 3. `find_implementations`
+## ⚙️ Configuration
 
-Find implementations for interfaces/abstract classes.
+### Environment Variables
 
-- `symbol`: Symbol name.
-- `path`: Project root.
+- `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`).
 
-### 4. `get_file_structure`
+### Agent Configuration (Cursor/Claude Desktop)
 
-Overview of a file's structure.
-
-- `file`: Path to the file.
-
-### 5. `search_code`
-
-Fast regex search via bundled ripgrep.
-
-- `pattern`: Regex pattern.
-- `path`: Directory to search.
-- `filePattern`: Optional glob filter.
-
-### 6. `get_symbol_docs`
-
-Retrieve only documentation for a symbol.
-
-- `symbol`: Symbol name.
-- `path`: Project root.
-
-### 7. `build_symbol_index`
-
-Build/Warm project-wide index.
+```json
+{
+  "mcpServers": {
+    "ast-explorer": {
+      "command": "npx",
+      "args": ["-y", "@aiready/ast-mcp-server"],
+      "env": {
+        "AST_WORKSPACE_ROOT": "/path/to/your/project"
+      }
+    }
+  }
+}
+```
 
-- `path`: Project root to index.
+## 🛡 Security
 
-## Quick Start
+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.
 
-```bash
-npx @aiready/ast-mcp-server
-```
-
-## Development
+## 📄 License
 
-```bash
-pnpm install
-npm run build
-npm run test
-```
+MIT © [AIReady](https://getaiready.dev)

package/dist/chunk-PRWMQQYW.js

@@ -0,0 +1,80 @@
+// src/tools/search-code.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { rgPath } from "@vscode/ripgrep";
+
+// src/security.ts
+import path from "path";
+function resolveWorkspaceRoot() {
+  return process.env.AST_WORKSPACE_ROOT || process.cwd();
+}
+function validateWorkspacePath(inputPath) {
+  const root = resolveWorkspaceRoot();
+  const resolved = path.resolve(root, inputPath);
+  const normalized = path.normalize(resolved);
+  if (!normalized.startsWith(root)) {
+    throw new Error(
+      `Path traversal detected: ${inputPath} escapes workspace root`
+    );
+  }
+  if (normalized.includes("\0")) {
+    throw new Error("Path contains null bytes");
+  }
+  return normalized;
+}
+
+// src/tools/search-code.ts
+var execFileAsync = promisify(execFile);
+async function searchCode(pattern, searchPath, filePattern, limit = 50, regex = true) {
+  const safePath = validateWorkspacePath(searchPath);
+  const args = [
+    "--json",
+    "--max-count",
+    limit.toString(),
+    "--max-columns",
+    "500"
+  ];
+  if (!regex) {
+    args.push("--fixed-strings");
+  }
+  args.push(pattern, safePath);
+  if (filePattern) {
+    args.push("--glob", filePattern);
+  }
+  args.push("--glob", "!**/node_modules/**");
+  args.push("--glob", "!**/dist/**");
+  args.push("--glob", "!**/.git/**");
+  try {
+    const { stdout } = await execFileAsync(rgPath, args);
+    const lines = stdout.split("\n").filter(Boolean);
+    const results = [];
+    for (const line of lines) {
+      const data = JSON.parse(line);
+      if (data.type === "match") {
+        const file = data.data.path.text;
+        const lineNumber = data.data.line_number;
+        const submatches = data.data.submatches;
+        for (const submatch of submatches) {
+          results.push({
+            file,
+            line: lineNumber,
+            column: submatch.start,
+            text: data.data.lines.text.trim()
+          });
+        }
+      }
+    }
+    return results.slice(0, limit);
+  } catch (error) {
+    if (error.code === 1) {
+      return [];
+    }
+    throw error;
+  }
+}
+
+export {
+  validateWorkspacePath,
+  searchCode
+};
+//# sourceMappingURL=chunk-PRWMQQYW.js.map

package/dist/chunk-PRWMQQYW.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/tools/search-code.ts","../src/security.ts"],"sourcesContent":["import { execFile } from 'child_process';\nimport { promisify } from 'util';\nimport { rgPath } from '@vscode/ripgrep';\nimport { validateWorkspacePath } from '../security.js';\n\nconst execFileAsync = promisify(execFile);\n\nexport interface SearchResult {\n  file: string;\n  line: number;\n  column: number;\n  text: string;\n}\n\nexport async function searchCode(\n  pattern: string,\n  searchPath: string,\n  filePattern?: string,\n  limit: number = 50,\n  regex: boolean = true\n): Promise<SearchResult[]> {\n  const safePath = validateWorkspacePath(searchPath);\n\n  const args = [\n    '--json',\n    '--max-count',\n    limit.toString(),\n    '--max-columns',\n    '500',\n  ];\n\n  if (!regex) {\n    args.push('--fixed-strings');\n  }\n\n  args.push(pattern, safePath);\n\n  if (filePattern) {\n    args.push('--glob', filePattern);\n  }\n\n  // Common exclusions\n  args.push('--glob', '!**/node_modules/**');\n  args.push('--glob', '!**/dist/**');\n  args.push('--glob', '!**/.git/**');\n\n  try {\n    const { stdout } = await execFileAsync(rgPath, args);\n    const lines = stdout.split('\\n').filter(Boolean);\n    const results: SearchResult[] = [];\n\n    for (const line of lines) {\n      const data = JSON.parse(line);\n      if (data.type === 'match') {\n        const file = data.data.path.text;\n        const lineNumber = data.data.line_number;\n        const submatches = data.data.submatches;\n\n        for (const submatch of submatches) {\n          results.push({\n            file,\n            line: lineNumber,\n            column: submatch.start,\n            text: data.data.lines.text.trim(),\n          });\n        }\n      }\n    }\n\n    return results.slice(0, limit);\n  } catch (error: any) {\n    if (error.code === 1) {\n      // rg returns 1 if no matches found\n      return [];\n    }\n    throw error;\n  }\n}\n","import path from 'path';\nimport fs from 'fs';\n\nexport function resolveWorkspaceRoot(): string {\n  return process.env.AST_WORKSPACE_ROOT || process.cwd();\n}\n\nexport function validateWorkspacePath(inputPath: string): string {\n  const root = resolveWorkspaceRoot();\n  const resolved = path.resolve(root, inputPath);\n  const normalized = path.normalize(resolved);\n\n  // Reject path traversal\n  if (!normalized.startsWith(root)) {\n    throw new Error(\n      `Path traversal detected: ${inputPath} escapes workspace root`\n    );\n  }\n\n  // Reject null bytes\n  if (normalized.includes('\\0')) {\n    throw new Error('Path contains null bytes');\n  }\n\n  return normalized;\n}\n\nexport function validateFileExists(filePath: string): string {\n  const safe = validateWorkspacePath(filePath);\n  if (!fs.existsSync(safe)) {\n    throw new Error(`File not found: ${filePath}`);\n  }\n  if (!fs.statSync(safe).isFile()) {\n    throw new Error(`Not a file: ${filePath}`);\n  }\n  return safe;\n}\n"],"mappings":";AAAA,SAAS,gBAAgB;AACzB,SAAS,iBAAiB;AAC1B,SAAS,cAAc;;;ACFvB,OAAO,UAAU;AAGV,SAAS,uBAA+B;AAC7C,SAAO,QAAQ,IAAI,sBAAsB,QAAQ,IAAI;AACvD;AAEO,SAAS,sBAAsB,WAA2B;AAC/D,QAAM,OAAO,qBAAqB;AAClC,QAAM,WAAW,KAAK,QAAQ,MAAM,SAAS;AAC7C,QAAM,aAAa,KAAK,UAAU,QAAQ;AAG1C,MAAI,CAAC,WAAW,WAAW,IAAI,GAAG;AAChC,UAAM,IAAI;AAAA,MACR,4BAA4B,SAAS;AAAA,IACvC;AAAA,EACF;AAGA,MAAI,WAAW,SAAS,IAAI,GAAG;AAC7B,UAAM,IAAI,MAAM,0BAA0B;AAAA,EAC5C;AAEA,SAAO;AACT;;;ADpBA,IAAM,gBAAgB,UAAU,QAAQ;AASxC,eAAsB,WACpB,SACA,YACA,aACA,QAAgB,IAChB,QAAiB,MACQ;AACzB,QAAM,WAAW,sBAAsB,UAAU;AAEjD,QAAM,OAAO;AAAA,IACX;AAAA,IACA;AAAA,IACA,MAAM,SAAS;AAAA,IACf;AAAA,IACA;AAAA,EACF;AAEA,MAAI,CAAC,OAAO;AACV,SAAK,KAAK,iBAAiB;AAAA,EAC7B;AAEA,OAAK,KAAK,SAAS,QAAQ;AAE3B,MAAI,aAAa;AACf,SAAK,KAAK,UAAU,WAAW;AAAA,EACjC;AAGA,OAAK,KAAK,UAAU,qBAAqB;AACzC,OAAK,KAAK,UAAU,aAAa;AACjC,OAAK,KAAK,UAAU,aAAa;AAEjC,MAAI;AACF,UAAM,EAAE,OAAO,IAAI,MAAM,cAAc,QAAQ,IAAI;AACnD,UAAM,QAAQ,OAAO,MAAM,IAAI,EAAE,OAAO,OAAO;AAC/C,UAAM,UAA0B,CAAC;AAEjC,eAAW,QAAQ,OAAO;AACxB,YAAM,OAAO,KAAK,MAAM,IAAI;AAC5B,UAAI,KAAK,SAAS,SAAS;AACzB,cAAM,OAAO,KAAK,KAAK,KAAK;AAC5B,cAAM,aAAa,KAAK,KAAK;AAC7B,cAAM,aAAa,KAAK,KAAK;AAE7B,mBAAW,YAAY,YAAY;AACjC,kBAAQ,KAAK;AAAA,YACX;AAAA,YACA,MAAM;AAAA,YACN,QAAQ,SAAS;AAAA,YACjB,MAAM,KAAK,KAAK,MAAM,KAAK,KAAK;AAAA,UAClC,CAAC;AAAA,QACH;AAAA,MACF;AAAA,IACF;AAEA,WAAO,QAAQ,MAAM,GAAG,KAAK;AAAA,EAC/B,SAAS,OAAY;AACnB,QAAI,MAAM,SAAS,GAAG;AAEpB,aAAO,CAAC;AAAA,IACV;AACA,UAAM;AAAA,EACR;AACF;","names":[]}