@aiready/ast-mcp-server 0.4.1 → 0.4.2

package/README.md

@@ -23,6 +23,7 @@ This Model Context Protocol (MCP) server provides high-precision, AST-aware tool
 | `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

package/dist/index.cjs

@@ -31,10 +31,10 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
-// ../../node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.8_tsx@4.21.0_typescript@5.9.3_yaml@2.8.2/node_modules/tsup/assets/cjs_shims.js
+// ../../node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.8_tsx@4.21.0_typescript@6.0.2_yaml@2.8.3/node_modules/tsup/assets/cjs_shims.js
 var getImportMetaUrl, importMetaUrl;
 var init_cjs_shims = __esm({
-  "../../node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.8_tsx@4.21.0_typescript@5.9.3_yaml@2.8.2/node_modules/tsup/assets/cjs_shims.js"() {
+  "../../node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.8_tsx@4.21.0_typescript@6.0.2_yaml@2.8.3/node_modules/tsup/assets/cjs_shims.js"() {
     "use strict";
     getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.tagName.toUpperCase() === "SCRIPT" ? document.currentScript.src : new URL("main.js", document.baseURI).href;
     importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
@@ -182,6 +182,10 @@ var GetCallHierarchySchema = import_zod.z.object({
   path: import_zod.z.string().describe("Project root directory"),
   direction: import_zod.z.enum(["incoming", "outgoing", "both"]).optional().default("both").describe("Direction of calls (default: both)")
 });
+var CheckSymbolGroundingSchema = import_zod.z.object({
+  symbol: import_zod.z.string().describe("Symbol name to assess grounding for"),
+  path: import_zod.z.string().describe("Project root directory")
+});
 
 // src/tools/resolve-definition.ts
 init_cjs_shims();
@@ -376,7 +380,7 @@ var SymbolIndex = class {
     const startTime = Date.now();
     const safeRoot = validateWorkspacePath(rootDir);
     const cachePath = this.getCachePath(safeRoot);
-    if (import_fs2.default.existsSync(cachePath)) {
+    if (import_fs2.default.existsSync(cachePath) && process.env.AST_DISABLE_CACHE !== "true") {
       try {
         const cached = JSON.parse(
           import_fs2.default.readFileSync(cachePath, "utf-8")
@@ -490,6 +494,7 @@ var WorkerPool = class {
   constructor(poolSize) {
     this.poolSize = poolSize;
   }
+  poolSize;
   workers = [];
   available = [];
   queue = [];
@@ -500,7 +505,7 @@ var WorkerPool = class {
     const workerPath = import_path4.default.join(__dirname, "ast-worker.js");
     for (let i = 0; i < this.poolSize; i++) {
       const worker = new import_worker_threads.Worker(workerPath);
-      worker.on("message", (msg) => this.handleResult(msg));
+      worker.on("message", (msg) => this.handleResult(worker, msg));
       worker.on("error", (_err) => this.handleWorkerError(worker, _err));
       this.workers.push(worker);
       this.available.push(worker);
@@ -522,7 +527,7 @@ var WorkerPool = class {
     this.activeJobs.set(task.id, task);
     worker.postMessage({ id: task.id, type: task.type, payload: task.payload });
   }
-  handleResult(msg) {
+  handleResult(worker, msg) {
     const task = this.activeJobs.get(msg.id);
     if (!task) return;
     this.activeJobs.delete(msg.id);
@@ -531,6 +536,12 @@ var WorkerPool = class {
     } else {
       task.resolve(msg.result);
     }
+    const nextTask = this.queue.shift();
+    if (nextTask) {
+      this.dispatch(worker, nextTask);
+    } else {
+      this.available.push(worker);
+    }
   }
   handleWorkerError(worker, err) {
     const idx = this.workers.indexOf(worker);
@@ -539,7 +550,7 @@ var WorkerPool = class {
       const __dirname = import_path4.default.dirname((0, import_url.fileURLToPath)(importMetaUrl));
       const workerPath = import_path4.default.join(__dirname, "ast-worker.js");
       const newWorker = new import_worker_threads.Worker(workerPath);
-      newWorker.on("message", (msg) => this.handleResult(msg));
+      newWorker.on("message", (msg) => this.handleResult(newWorker, msg));
       newWorker.on("error", (_e) => this.handleWorkerError(newWorker, _e));
       this.workers[idx] = newWorker;
       this.available.push(newWorker);
@@ -638,16 +649,12 @@ var TypeScriptAdapter = class {
     const project = projectManager.ensureProject(tsconfig);
     const sourceFile = project.addSourceFileAtPathIfExists(hit.file);
     if (!sourceFile) return { references: [], total_count: 0 };
-    const exported = sourceFile.getExportedDeclarations().get(symbolName);
-    if (!exported || exported.length === 0)
-      return { references: [], total_count: 0 };
-    const targetNode = exported[0];
     try {
       const { searchCode: searchCode2 } = await Promise.resolve().then(() => (init_search_code(), search_code_exports));
       const searchResults = await searchCode2(
         symbolName,
         path6,
-        "*.{ts,tsx,js,jsx}",
+        "**/*.{ts,tsx,js,jsx}",
         1e3,
         false
       );
@@ -655,8 +662,13 @@ var TypeScriptAdapter = class {
       for (const file of filesToLoad) {
         project.addSourceFileAtPathIfExists(file);
       }
+      project.resolveSourceFileDependencies();
     } catch (_e) {
     }
+    const exported = sourceFile.getExportedDeclarations().get(symbolName);
+    if (!exported || exported.length === 0)
+      return { references: [], total_count: 0 };
+    const targetNode = exported[0];
     const refSymbols = "findReferences" in targetNode && typeof targetNode.findReferences === "function" ? targetNode.findReferences() : void 0;
     if (!refSymbols) return { references: [], total_count: 0 };
     const results = [];
@@ -712,7 +724,7 @@ var TypeScriptAdapter = class {
         const searchResults = await searchCode2(
           symbolName,
           path6,
-          "*.{ts,tsx,js,jsx}",
+          "**/*.{ts,tsx,js,jsx}",
           1e3,
           false
         );
@@ -1044,6 +1056,86 @@ async function getCallHierarchy(symbolName, rootDir, direction = "both") {
   return results;
 }
 
+// src/tools/check-symbol-grounding.ts
+init_cjs_shims();
+var import_ts_morph6 = require("ts-morph");
+init_security();
+async function checkSymbolGrounding(symbol, filePath) {
+  const safePath = validateWorkspacePath(filePath);
+  const tsconfig = await projectManager.findNearestTsConfig(safePath);
+  if (!tsconfig) return void 0;
+  const project = projectManager.ensureProject(tsconfig);
+  const sourceFile = project.addSourceFileAtPathIfExists(safePath);
+  if (!sourceFile) return void 0;
+  const node = sourceFile.getDescendantsOfKind(import_ts_morph6.SyntaxKind.Identifier).find((id) => id.getText() === symbol);
+  if (!node) return void 0;
+  const decl = node.getSymbol()?.getDeclarations()?.[0];
+  if (!decl) return void 0;
+  let docScore = 0;
+  let typeScore = 0;
+  let depthScore = 30;
+  const recommendations = [];
+  const docs = typescriptAdapter.getSymbolDocs(decl);
+  if (docs) {
+    docScore += 10;
+    if (docs.documentation && docs.documentation.length > 20) docScore += 10;
+    const hasParams = docs.tags.some((t) => t.name === "param");
+    const hasReturns = docs.tags.some(
+      (t) => t.name === "returns" || t.name === "return"
+    );
+    if (hasParams) docScore += 10;
+    else
+      recommendations.push(
+        "Add @param tags to document implementation details for the agent."
+      );
+    if (hasReturns) docScore += 10;
+    else
+      recommendations.push("Add @returns tag to clarify output expectations.");
+  } else {
+    recommendations.push(
+      "Missing JSDoc. Agents need explicit documentation to understand intent without reading the source."
+    );
+  }
+  const typeText = decl.getType?.()?.getText?.() || "";
+  if (typeText) {
+    if (!typeText.includes("any")) typeScore += 15;
+    else
+      recommendations.push(
+        'Avoid "any" types. They break agentic reasoning and cause hallucinations.'
+      );
+    if (!typeText.includes("unknown")) typeScore += 15;
+    else
+      recommendations.push(
+        'Use specific interfaces instead of "unknown" to minimize agent probe requirements.'
+      );
+  }
+  const importCount = sourceFile.getImportDeclarations().length;
+  if (importCount > 10) {
+    const penalty = Math.min(20, (importCount - 10) * 2);
+    depthScore -= penalty;
+    recommendations.push(
+      `High dependency depth (${importCount} imports). Agents must load more files to understand this symbol's context.`
+    );
+  }
+  const totalScore = docScore + typeScore + depthScore;
+  let grade = "F";
+  if (totalScore >= 90) grade = "S (Agent-Native)";
+  else if (totalScore >= 80) grade = "A (Highly Grounded)";
+  else if (totalScore >= 70) grade = "B (Good)";
+  else if (totalScore >= 60) grade = "C (Acceptable)";
+  else if (totalScore >= 40) grade = "D (Poor)";
+  return {
+    score: totalScore,
+    grade,
+    breakdown: {
+      documentation: docScore,
+      typeClarity: typeScore,
+      depthImpact: depthScore
+    },
+    recommendations
+  };
+}
+
 // src/index.ts
 var import_types2 = require("@modelcontextprotocol/sdk/types.js");
 var ASTExplorerServer = class {
@@ -1207,16 +1299,28 @@ var ASTExplorerServer = class {
             inputSchema: {
               type: "object",
               properties: {
-                symbol: { type: "string", description: "Symbol name" },
-                path: { type: "string", description: "Project root" },
+                symbol: { type: "string" },
+                path: { type: "string" },
                 direction: {
                   type: "string",
-                  enum: ["incoming", "outgoing", "both"],
-                  default: "both"
+                  enum: ["incoming", "outgoing"],
+                  default: "outgoing"
                 }
               },
               required: ["symbol", "path"]
             }
+          },
+          {
+            name: "check_symbol_grounding",
+            description: "Assess a symbol's AI grounding quality (docs, type clarity, depth).",
+            inputSchema: {
+              type: "object",
+              properties: {
+                symbol: { type: "string" },
+                path: { type: "string" }
+              },
+              required: ["symbol", "path"]
+            }
           }
         ]
       };
@@ -1305,6 +1409,15 @@ var ASTExplorerServer = class {
               ]
             };
           }
+          case "check_symbol_grounding": {
+            const { symbol, path: path6 } = CheckSymbolGroundingSchema.parse(args);
+            const result = await checkSymbolGrounding(symbol, path6);
+            return {
+              content: [
+                { type: "text", text: JSON.stringify(result, null, 2) }
+              ]
+            };
+          }
           default:
             throw new Error(`Unknown tool: ${name}`);
         }