@aiready/ast-mcp-server 0.1.0 → 0.1.1

package/dist/index.js

@@ -0,0 +1,742 @@
+// src/index.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+
+// src/schemas.ts
+import { z } from "zod";
+var ResolveDefinitionSchema = z.object({
+  symbol: z.string().describe(
+    "Symbol name to resolve (function, class, type, interface, etc.)"
+  ),
+  path: z.string().describe("Project root or target directory")
+});
+var FindReferencesSchema = z.object({
+  symbol: z.string().describe("Symbol name to find references for"),
+  path: z.string().describe("Project root directory"),
+  limit: z.number().optional().default(50).describe("Max results per page (default 50)"),
+  offset: z.number().optional().default(0).describe("Pagination offset")
+});
+var FindImplementationsSchema = z.object({
+  symbol: z.string().describe("Interface or abstract class name to find implementations for"),
+  path: z.string().describe("Project root directory"),
+  limit: z.number().optional().default(50).describe("Max results per page"),
+  offset: z.number().optional().default(0).describe("Pagination offset")
+});
+var GetFileStructureSchema = z.object({
+  file: z.string().describe("Absolute path to the file to analyze")
+});
+var SearchCodeSchema = z.object({
+  pattern: z.string().describe("Search pattern (regex)"),
+  path: z.string().describe("Directory to search in"),
+  filePattern: z.string().optional().describe('Glob filter (e.g., "*.ts")'),
+  limit: z.number().optional().default(50).describe("Max matches to return")
+});
+var GetSymbolDocsSchema = z.object({
+  symbol: z.string().describe("Symbol name to get documentation for"),
+  path: z.string().describe("Project root directory")
+});
+var BuildSymbolIndexSchema = z.object({
+  path: z.string().describe("Project root directory to index")
+});
+
+// src/adapters/typescript-adapter.ts
+import {
+  Node,
+  SyntaxKind
+} from "ts-morph";
+
+// src/project-manager.ts
+import { Project } from "ts-morph";
+import path from "path";
+import fs from "fs";
+import { glob } from "glob";
+var ProjectManager = class {
+  projects = /* @__PURE__ */ new Map();
+  tsconfigCache = /* @__PURE__ */ new Map();
+  /**
+   * Find all tsconfig.json files in a directory (recursive)
+   */
+  async findTsConfigs(rootDir) {
+    if (this.tsconfigCache.has(rootDir)) {
+      return this.tsconfigCache.get(rootDir);
+    }
+    const configs = await glob("**/tsconfig.json", {
+      cwd: rootDir,
+      absolute: true,
+      ignore: ["**/node_modules/**", "**/dist/**"]
+    });
+    this.tsconfigCache.set(rootDir, configs);
+    return configs;
+  }
+  /**
+   * Get or create a Project for a specific file path
+   */
+  async getProjectForFile(filePath) {
+    const tsconfigPath = await this.findNearestTsConfig(filePath);
+    if (!tsconfigPath) return void 0;
+    return this.getOrCreateProject(tsconfigPath);
+  }
+  /**
+   * Get or create a Project for a tsconfig path
+   */
+  getOrCreateProject(tsconfigPath) {
+    if (this.projects.has(tsconfigPath)) {
+      return this.projects.get(tsconfigPath);
+    }
+    const project = new Project({
+      tsConfigFilePath: tsconfigPath,
+      skipAddingFilesFromTsConfig: false
+    });
+    this.projects.set(tsconfigPath, project);
+    return project;
+  }
+  /**
+   * Find the nearest tsconfig.json for a file
+   */
+  async findNearestTsConfig(filePath) {
+    let currentDir = path.dirname(filePath);
+    const root = path.parse(currentDir).root;
+    while (currentDir !== root) {
+      const tsconfigPath = path.join(currentDir, "tsconfig.json");
+      if (fs.existsSync(tsconfigPath)) {
+        return tsconfigPath;
+      }
+      currentDir = path.dirname(currentDir);
+    }
+    return void 0;
+  }
+  /**
+   * Get all projects that might contain a file or serve a path
+   */
+  async getProjectsForPath(rootDir) {
+    const configs = await this.findTsConfigs(rootDir);
+    return configs.map((config) => this.getOrCreateProject(config));
+  }
+  /**
+   * Dispose all projects to free memory
+   */
+  disposeAll() {
+    for (const project of this.projects.values()) {
+      project.getLanguageService().compilerObject.dispose();
+    }
+    this.projects.clear();
+  }
+};
+var projectManager = new ProjectManager();
+
+// src/adapters/typescript-adapter.ts
+var TypeScriptAdapter = class {
+  /**
+   * Resolve definition of a symbol at a path
+   */
+  async resolveDefinition(symbolName, path2) {
+    const projects = await projectManager.getProjectsForPath(path2);
+    const results = [];
+    for (const project of projects) {
+      const sourceFiles = project.getSourceFiles();
+      for (const sourceFile of sourceFiles) {
+        const nodes = sourceFile.getDescendantsOfKind(SyntaxKind.Identifier).filter((id) => id.getText() === symbolName);
+        for (const node of nodes) {
+          const definitions = node.getDefinitionNodes();
+          for (const defNode of definitions) {
+            results.push(this.mapToDefinitionLocation(defNode));
+          }
+        }
+      }
+    }
+    return this.deduplicateLocations(results);
+  }
+  /**
+   * Find references to a symbol
+   */
+  async findReferences(symbolName, path2, limit = 50, offset = 0) {
+    const projects = await projectManager.getProjectsForPath(path2);
+    const results = [];
+    for (const project of projects) {
+      const sourceFiles = project.getSourceFiles();
+      for (const sourceFile of sourceFiles) {
+        const nodes = sourceFile.getDescendantsOfKind(SyntaxKind.Identifier).filter((id) => id.getText() === symbolName);
+        for (const node of nodes) {
+          const referencedSymbols = node.findReferences();
+          for (const referencedSymbol of referencedSymbols) {
+            const references = referencedSymbol.getReferences();
+            for (const ref of references) {
+              const sourceFile2 = ref.getSourceFile();
+              const lineAndColumn = sourceFile2.getLineAndColumnAtPos(
+                ref.getTextSpan().getStart()
+              );
+              results.push({
+                file: sourceFile2.getFilePath(),
+                line: lineAndColumn.line,
+                column: lineAndColumn.column,
+                text: ref.getNode().getParent()?.getText() || ref.getNode().getText()
+              });
+            }
+          }
+        }
+      }
+    }
+    const uniqueResults = this.deduplicateLocations(results);
+    return {
+      references: uniqueResults.slice(offset, offset + limit),
+      total_count: uniqueResults.length
+    };
+  }
+  /**
+   * Find implementations for a symbol
+   */
+  async findImplementations(symbolName, path2, limit = 50, offset = 0) {
+    const projects = await projectManager.getProjectsForPath(path2);
+    const results = [];
+    for (const project of projects) {
+      const sourceFiles = project.getSourceFiles();
+      for (const sourceFile of sourceFiles) {
+        const nodes = sourceFile.getDescendantsOfKind(SyntaxKind.Identifier).filter((id) => id.getText() === symbolName);
+        for (const node of nodes) {
+          const implementations = node.getImplementations();
+          for (const impl of implementations) {
+            const sourceFile2 = impl.getSourceFile();
+            const lineAndColumn = sourceFile2.getLineAndColumnAtPos(
+              impl.getTextSpan().getStart()
+            );
+            results.push({
+              file: sourceFile2.getFilePath(),
+              line: lineAndColumn.line,
+              column: lineAndColumn.column,
+              text: impl.getNode().getParent()?.getText() || impl.getNode().getText()
+            });
+          }
+        }
+      }
+    }
+    const uniqueResults = this.deduplicateLocations(results);
+    return {
+      implementations: uniqueResults.slice(offset, offset + limit),
+      total_count: uniqueResults.length
+    };
+  }
+  /**
+   * Get file structure overview
+   */
+  async getFileStructure(filePath) {
+    const project = await projectManager.getProjectForFile(filePath);
+    if (!project) return void 0;
+    const sourceFile = project.getSourceFile(filePath);
+    if (!sourceFile) return void 0;
+    const structure = {
+      file: filePath,
+      imports: sourceFile.getImportDeclarations().map((imp) => ({
+        module: imp.getModuleSpecifierValue(),
+        names: imp.getNamedImports().map((ni) => ni.getName())
+      })),
+      exports: sourceFile.getExportSymbols().map((sym) => ({
+        name: sym.getName(),
+        kind: this.mapSymbolKind(sym)
+      })),
+      classes: sourceFile.getClasses().map((cls) => this.mapToClassInfo(cls)),
+      functions: sourceFile.getFunctions().map((fn) => this.mapToFunctionInfo(fn)),
+      interfaces: sourceFile.getInterfaces().map((itf) => this.mapToInterfaceInfo(itf)),
+      typeAliases: sourceFile.getTypeAliases().map((ta) => this.mapToTypeAliasInfo(ta)),
+      enums: sourceFile.getEnums().map((enm) => this.mapToEnumInfo(enm))
+    };
+    return structure;
+  }
+  /**
+   * Helper: Map ts-morph Node (Declaration) to DefinitionLocation
+   */
+  mapToDefinitionLocation(node) {
+    const sourceFile = node.getSourceFile();
+    const lineAndColumn = sourceFile.getLineAndColumnAtPos(node.getStart());
+    return {
+      file: sourceFile.getFilePath(),
+      line: lineAndColumn.line,
+      column: lineAndColumn.column,
+      kind: this.mapNodeToSymbolKind(node),
+      snippet: node.getText(),
+      documentation: this.getJsDoc(node)
+    };
+  }
+  /**
+   * Helper: Map ts-morph Node to SymbolKind
+   */
+  mapNodeToSymbolKind(node) {
+    if (Node.isClassDeclaration(node)) return "class";
+    if (Node.isFunctionDeclaration(node)) return "function";
+    if (Node.isInterfaceDeclaration(node)) return "interface";
+    if (Node.isTypeAliasDeclaration(node)) return "type_alias";
+    if (Node.isEnumDeclaration(node)) return "enum";
+    if (Node.isVariableDeclaration(node)) return "variable";
+    if (Node.isMethodDeclaration(node)) return "method";
+    if (Node.isPropertyDeclaration(node)) return "property";
+    if (Node.isParameterDeclaration(node)) return "parameter";
+    return "variable";
+  }
+  /**
+   * Helper: Map Symbol to SymbolKind
+   */
+  mapSymbolKind(symbol) {
+    const decls = symbol.getDeclarations();
+    if (decls.length > 0) return this.mapNodeToSymbolKind(decls[0]);
+    return "variable";
+  }
+  /**
+   * Helper: Get JSDoc from Node
+   */
+  getJsDoc(node) {
+    if (Node.isJSDocable(node)) {
+      const docs = node.getJsDocs();
+      if (docs.length > 0) {
+        return docs[0].getCommentText();
+      }
+    }
+    return void 0;
+  }
+  /**
+   * Helper: Get full JSDoc info (with tags)
+   */
+  getSymbolDocs(node) {
+    if (Node.isJSDocable(node)) {
+      const docs = node.getJsDocs();
+      if (docs.length > 0) {
+        const doc = docs[0];
+        return {
+          documentation: doc.getCommentText(),
+          tags: doc.getTags().map((tag) => ({
+            name: tag.getTagName(),
+            text: tag.getCommentText() || ""
+          }))
+        };
+      }
+    }
+    return void 0;
+  }
+  mapToClassInfo(cls) {
+    return {
+      name: cls.getName() || "anonymous",
+      ...this.getSymbolDocs(cls),
+      methods: cls.getMethods().map((m) => this.mapToFunctionInfo(m)),
+      properties: cls.getProperties().map((p) => this.mapToPropertyInfo(p))
+    };
+  }
+  mapToFunctionInfo(fn) {
+    return {
+      name: fn.getName() || "anonymous",
+      ...this.getSymbolDocs(fn),
+      params: fn.getParameters().map((p) => ({
+        name: p.getName(),
+        type: p.getType().getText()
+      })),
+      returnType: fn.getReturnType().getText()
+    };
+  }
+  mapToPropertyInfo(p) {
+    return {
+      name: p.getName(),
+      type: p.getType().getText(),
+      ...this.getSymbolDocs(p)
+    };
+  }
+  mapToInterfaceInfo(itf) {
+    return {
+      name: itf.getName(),
+      ...this.getSymbolDocs(itf),
+      properties: itf.getProperties().map((p) => this.mapToPropertyInfo(p)),
+      methods: itf.getMethods().map((m) => this.mapToFunctionInfo(m))
+    };
+  }
+  mapToTypeAliasInfo(ta) {
+    return {
+      name: ta.getName(),
+      type: ta.getType().getText(),
+      ...this.getSymbolDocs(ta)
+    };
+  }
+  mapToEnumInfo(enm) {
+    return {
+      name: enm.getName(),
+      ...this.getSymbolDocs(enm),
+      members: enm.getMembers().map((m) => m.getName())
+    };
+  }
+  /**
+   * Helper: Deduplicate locations
+   */
+  deduplicateLocations(locations) {
+    const seen = /* @__PURE__ */ new Set();
+    return locations.filter((loc) => {
+      const key = `${loc.file}:${loc.line}:${loc.column}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+  }
+};
+var typescriptAdapter = new TypeScriptAdapter();
+
+// src/tools/resolve-definition.ts
+async function resolveDefinition(symbol, path2) {
+  return await typescriptAdapter.resolveDefinition(symbol, path2);
+}
+
+// src/tools/find-references.ts
+async function findReferences(symbol, path2, limit = 50, offset = 0) {
+  return await typescriptAdapter.findReferences(symbol, path2, limit, offset);
+}
+
+// src/tools/find-implementations.ts
+async function findImplementations(symbol, path2, limit = 50, offset = 0) {
+  return await typescriptAdapter.findImplementations(
+    symbol,
+    path2,
+    limit,
+    offset
+  );
+}
+
+// src/tools/get-file-structure.ts
+async function getFileStructure(file) {
+  return await typescriptAdapter.getFileStructure(file);
+}
+
+// src/tools/search-code.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { rgPath } from "@vscode/ripgrep";
+var execFileAsync = promisify(execFile);
+async function searchCode(pattern, searchPath, filePattern, limit = 50) {
+  const args = [
+    "--json",
+    "--max-count",
+    limit.toString(),
+    "--fixed-strings",
+    // Default to fixed strings unless we want regex
+    pattern,
+    searchPath
+  ];
+  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;
+  }
+}
+
+// src/tools/get-symbol-docs.ts
+import { SyntaxKind as SyntaxKind2 } from "ts-morph";
+async function getSymbolDocs(symbol, filePath) {
+  const projects = await projectManager.getProjectsForPath(filePath);
+  for (const project of projects) {
+    const sourceFile = project.getSourceFile(filePath);
+    if (sourceFile) {
+      const node = sourceFile.getDescendantsOfKind(SyntaxKind2.Identifier).find((id) => id.getText() === symbol);
+      if (node) {
+        const decls = node.getSymbol()?.getDeclarations();
+        if (decls && decls.length > 0) {
+          const docs = typescriptAdapter.getSymbolDocs(decls[0]);
+          if (docs) {
+            return {
+              symbol,
+              file: sourceFile.getFilePath(),
+              line: sourceFile.getLineAndColumnAtPos(decls[0].getStart()).line,
+              ...docs
+            };
+          }
+        }
+      }
+    }
+  }
+  return void 0;
+}
+
+// src/index/symbol-index.ts
+var SymbolIndex = class {
+  /**
+   * Build/Warm the index for a given path
+   */
+  async buildIndex(rootDir) {
+    const startTime = Date.now();
+    const projects = await projectManager.getProjectsForPath(rootDir);
+    let fileCount = 0;
+    let functionCount = 0;
+    let classCount = 0;
+    let interfaceCount = 0;
+    let typeCount = 0;
+    for (const project of projects) {
+      const sourceFiles = project.getSourceFiles();
+      fileCount += sourceFiles.length;
+      for (const sourceFile of sourceFiles) {
+        functionCount += sourceFile.getFunctions().length;
+        classCount += sourceFile.getClasses().length;
+        interfaceCount += sourceFile.getInterfaces().length;
+        typeCount += sourceFile.getTypeAliases().length;
+      }
+    }
+    const duration = Date.now() - startTime;
+    const memoryUsage = process.memoryUsage().heapUsed / 1024 / 1024;
+    return {
+      indexed: {
+        files: fileCount,
+        functions: functionCount,
+        classes: classCount,
+        interfaces: interfaceCount,
+        types: typeCount
+      },
+      duration_ms: duration,
+      memory_mb: Math.round(memoryUsage)
+    };
+  }
+};
+var symbolIndex = new SymbolIndex();
+
+// src/tools/build-symbol-index.ts
+async function buildSymbolIndex(path2) {
+  return await symbolIndex.buildIndex(path2);
+}
+
+// src/index.ts
+var ASTExplorerServer = class {
+  server;
+  version = "0.1.0";
+  constructor() {
+    this.server = new Server(
+      {
+        name: "ast-explorer-server",
+        version: this.version
+      },
+      {
+        capabilities: {
+          tools: {}
+        }
+      }
+    );
+    this.setupHandlers();
+    this.server.onerror = (error) => {
+      console.error("[MCP Error]", error);
+    };
+  }
+  setupHandlers() {
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+      return {
+        tools: [
+          {
+            name: "resolve_definition",
+            description: "Find where a symbol is defined using TypeScript AST.",
+            inputSchema: {
+              type: "object",
+              properties: {
+                symbol: {
+                  type: "string",
+                  description: "Symbol name (e.g., function, class)"
+                },
+                path: {
+                  type: "string",
+                  description: "Project root or target directory"
+                }
+              },
+              required: ["symbol", "path"]
+            }
+          },
+          {
+            name: "find_references",
+            description: "Find all usages of a symbol across the project.",
+            inputSchema: {
+              type: "object",
+              properties: {
+                symbol: { type: "string", description: "Symbol name" },
+                path: { type: "string", description: "Project root" },
+                limit: { type: "number", default: 50 },
+                offset: { type: "number", default: 0 }
+              },
+              required: ["symbol", "path"]
+            }
+          },
+          {
+            name: "find_implementations",
+            description: "Find implementations of interfaces or abstract classes.",
+            inputSchema: {
+              type: "object",
+              properties: {
+                symbol: { type: "string", description: "Interface/Class name" },
+                path: { type: "string", description: "Project root" },
+                limit: { type: "number", default: 50 },
+                offset: { type: "number", default: 0 }
+              },
+              required: ["symbol", "path"]
+            }
+          },
+          {
+            name: "get_file_structure",
+            description: "Get structural overview of a file (imports, exports, symbols).",
+            inputSchema: {
+              type: "object",
+              properties: {
+                file: { type: "string", description: "Absolute path to file" }
+              },
+              required: ["file"]
+            }
+          },
+          {
+            name: "search_code",
+            description: "Fast regex search via bundled ripgrep.",
+            inputSchema: {
+              type: "object",
+              properties: {
+                pattern: { type: "string", description: "Search pattern" },
+                path: { type: "string", description: "Directory to search" },
+                filePattern: { type: "string", description: "Glob filter" },
+                limit: { type: "number", default: 50 }
+              },
+              required: ["pattern", "path"]
+            }
+          },
+          {
+            name: "get_symbol_docs",
+            description: "Get JSDoc/TSDoc for a specific symbol.",
+            inputSchema: {
+              type: "object",
+              properties: {
+                symbol: { type: "string", description: "Symbol name" },
+                path: { type: "string", description: "Project root" }
+              },
+              required: ["symbol", "path"]
+            }
+          },
+          {
+            name: "build_symbol_index",
+            description: "Warm the symbol index for faster navigation.",
+            inputSchema: {
+              type: "object",
+              properties: {
+                path: { type: "string", description: "Project root to index" }
+              },
+              required: ["path"]
+            }
+          }
+        ]
+      };
+    });
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const { name, arguments: args } = request.params;
+      try {
+        switch (name) {
+          case "resolve_definition": {
+            const { symbol, path: path2 } = ResolveDefinitionSchema.parse(args);
+            const results = await resolveDefinition(symbol, path2);
+            return {
+              content: [
+                { type: "text", text: JSON.stringify(results, null, 2) }
+              ]
+            };
+          }
+          case "find_references": {
+            const { symbol, path: path2, limit, offset } = FindReferencesSchema.parse(args);
+            const results = await findReferences(symbol, path2, limit, offset);
+            return {
+              content: [
+                { type: "text", text: JSON.stringify(results, null, 2) }
+              ]
+            };
+          }
+          case "find_implementations": {
+            const { symbol, path: path2, limit, offset } = FindImplementationsSchema.parse(args);
+            const results = await findImplementations(
+              symbol,
+              path2,
+              limit,
+              offset
+            );
+            return {
+              content: [
+                { type: "text", text: JSON.stringify(results, null, 2) }
+              ]
+            };
+          }
+          case "get_file_structure": {
+            const { file } = GetFileStructureSchema.parse(args);
+            const structure = await getFileStructure(file);
+            return {
+              content: [
+                { type: "text", text: JSON.stringify(structure, null, 2) }
+              ]
+            };
+          }
+          case "search_code": {
+            const { pattern, path: path2, filePattern, limit } = SearchCodeSchema.parse(args);
+            const results = await searchCode(pattern, path2, filePattern, limit);
+            return {
+              content: [
+                { type: "text", text: JSON.stringify(results, null, 2) }
+              ]
+            };
+          }
+          case "get_symbol_docs": {
+            const { symbol, path: path2 } = GetSymbolDocsSchema.parse(args);
+            const docs = await getSymbolDocs(symbol, path2);
+            return {
+              content: [{ type: "text", text: JSON.stringify(docs, null, 2) }]
+            };
+          }
+          case "build_symbol_index": {
+            const { path: path2 } = BuildSymbolIndexSchema.parse(args);
+            const stats = await buildSymbolIndex(path2);
+            return {
+              content: [{ type: "text", text: JSON.stringify(stats, null, 2) }]
+            };
+          }
+          default:
+            throw new Error(`Unknown tool: ${name}`);
+        }
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: `Error: ${error.message}` }],
+          isError: true
+        };
+      }
+    });
+  }
+  async run() {
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+    console.error("AST Explorer MCP Server started");
+  }
+};
+var server = new ASTExplorerServer();
+server.run().catch((error) => {
+  console.error("Fatal error starting AST Explorer MCP Server:", error);
+  process.exit(1);
+});
+export {
+  ASTExplorerServer
+};
+//# sourceMappingURL=index.js.map