ast-search-mcp 0.1.0

package/build/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/build/index.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { server } from "./server.js";
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/build/server.d.ts

@@ -0,0 +1,77 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+export declare function loadPlugins(plugins: string[]): Promise<void>;
+/** Reset plugin tracking — for testing only. */
+export declare function _resetLoadedPlugins(): void;
+type ToolResult = {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+};
+export declare const searchSchema: z.ZodObject<{
+    queries: z.ZodArray<z.ZodString, "many">;
+    dir: z.ZodOptional<z.ZodString>;
+    lang: z.ZodOptional<z.ZodString>;
+    exclude: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    context: z.ZodOptional<z.ZodNumber>;
+    showAst: z.ZodOptional<z.ZodBoolean>;
+    plugins: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    queries: string[];
+    dir?: string | undefined;
+    lang?: string | undefined;
+    exclude?: string[] | undefined;
+    limit?: number | undefined;
+    context?: number | undefined;
+    showAst?: boolean | undefined;
+    plugins?: string[] | undefined;
+}, {
+    queries: string[];
+    dir?: string | undefined;
+    lang?: string | undefined;
+    exclude?: string[] | undefined;
+    limit?: number | undefined;
+    context?: number | undefined;
+    showAst?: boolean | undefined;
+    plugins?: string[] | undefined;
+}>;
+export declare const validateSchema: z.ZodObject<{
+    query: z.ZodString;
+    lang: z.ZodOptional<z.ZodString>;
+    plugins: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    lang?: string | undefined;
+    plugins?: string[] | undefined;
+}, {
+    query: string;
+    lang?: string | undefined;
+    plugins?: string[] | undefined;
+}>;
+export declare const showAstSchema: z.ZodObject<{
+    code: z.ZodOptional<z.ZodString>;
+    file: z.ZodOptional<z.ZodString>;
+    lines: z.ZodOptional<z.ZodString>;
+    lang: z.ZodOptional<z.ZodString>;
+    plugins: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    code?: string | undefined;
+    lang?: string | undefined;
+    plugins?: string[] | undefined;
+    file?: string | undefined;
+    lines?: string | undefined;
+}, {
+    code?: string | undefined;
+    lang?: string | undefined;
+    plugins?: string[] | undefined;
+    file?: string | undefined;
+    lines?: string | undefined;
+}>;
+export declare function handleSearch(args: z.infer<typeof searchSchema>): Promise<ToolResult>;
+export declare function handleValidateQuery(args: z.infer<typeof validateSchema>): Promise<ToolResult>;
+export declare function handleShowAst(args: z.infer<typeof showAstSchema>): Promise<ToolResult>;
+export declare const server: McpServer;
+export {};

package/build/server.js

@@ -0,0 +1,206 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { searchRepoWithMeta, defaultRegistry, explainSelector, enrichWithContext, } from "ast-search-js";
+import { LanguageRegistry } from "ast-search-js/plugin";
+import { readFile } from "node:fs/promises";
+import { extname } from "node:path";
+// ---------------------------------------------------------------------------
+// Plugin management
+// ---------------------------------------------------------------------------
+// Track loaded plugins so we never double-register.
+// Node.js module caching makes re-imports free; the Set prevents duplicate register() calls.
+const loadedPlugins = new Set();
+export async function loadPlugins(plugins) {
+    for (const pkg of plugins) {
+        if (loadedPlugins.has(pkg))
+            continue;
+        const mod = (await import(pkg));
+        const reg = mod.register ?? mod.default?.register;
+        if (typeof reg !== "function") {
+            throw new Error(`Plugin "${pkg}" has no register() export`);
+        }
+        reg(defaultRegistry);
+        loadedPlugins.add(pkg);
+    }
+}
+/** Reset plugin tracking — for testing only. */
+export function _resetLoadedPlugins() {
+    loadedPlugins.clear();
+}
+// ---------------------------------------------------------------------------
+// Input schemas (exported so tests can inspect them)
+// ---------------------------------------------------------------------------
+export const searchSchema = z.object({
+    queries: z.array(z.string()).min(1).describe("One or more AST selector queries. CSS selectors for JS/TS/Vue; S-expressions for Python."),
+    dir: z.string().optional().describe("Root directory to search (default: current working directory)"),
+    lang: z.string().optional().describe('Restrict search to one language backend, e.g. "js" or "python"'),
+    exclude: z.array(z.string()).optional().describe('Glob patterns to exclude, e.g. ["**/*.test.ts", "dist/**"]'),
+    limit: z.number().int().positive().optional().describe("Stop after N matches. Use for exploratory scope checks on large repos."),
+    context: z.number().int().nonnegative().optional().describe("Number of lines of source context to include above and below each match"),
+    showAst: z.boolean().optional().describe("Include the AST subtree of each matched node. Useful when writing or debugging queries."),
+    plugins: z.array(z.string()).optional().describe('Language plugin packages to load, e.g. ["ast-search-python"]. Loaded once per session.'),
+});
+export const validateSchema = z.object({
+    query: z.string().describe("AST selector to validate"),
+    lang: z.string().optional().describe('Language backend to validate against: "js" (default) or "python"'),
+    plugins: z.array(z.string()).optional().describe("Language plugin packages required for the target language"),
+});
+export const showAstSchema = z.object({
+    code: z.string().optional().describe("Inline code snippet to parse and print"),
+    file: z.string().optional().describe("Path to a source file to parse"),
+    lines: z.string().optional().describe('Line range when using file, e.g. "10-20" (1-indexed, inclusive)'),
+    lang: z.string().optional().describe('Language to use for parsing: "js" (default) or "python". Inferred from file extension when using file.'),
+    plugins: z.array(z.string()).optional().describe("Language plugin packages required for the target language"),
+});
+// ---------------------------------------------------------------------------
+// Handler: search
+// ---------------------------------------------------------------------------
+export async function handleSearch(args) {
+    const { queries, dir, lang, exclude, limit, context, showAst, plugins } = args;
+    try {
+        await loadPlugins(plugins ?? []);
+        let registry = defaultRegistry;
+        if (lang) {
+            const backend = defaultRegistry.getByLangId(lang);
+            if (!backend) {
+                const available = defaultRegistry.allBackends.map((b) => b.langId).join(", ");
+                throw new Error(`Unknown language "${lang}". Available: ${available}`);
+            }
+            registry = new LanguageRegistry();
+            registry.register(backend);
+        }
+        const startMs = Date.now();
+        const { matches: rawMatches, filesSearched, truncated } = await searchRepoWithMeta(queries, dir ?? process.cwd(), registry, exclude ?? [], { showAst, limit });
+        const wallMs = Date.now() - startMs;
+        const matches = (context ?? 0) > 0
+            ? await enrichWithContext(rawMatches, context)
+            : rawMatches;
+        const output = {
+            matches,
+            _meta: { matchCount: matches.length, filesSearched, wallMs, queries, truncated },
+        };
+        return { content: [{ type: "text", text: JSON.stringify(output, null, 2) }] };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: `Error: ${msg}` }], isError: true };
+    }
+}
+// ---------------------------------------------------------------------------
+// Handler: validate_query
+// ---------------------------------------------------------------------------
+export async function handleValidateQuery(args) {
+    const { query, lang, plugins } = args;
+    try {
+        await loadPlugins(plugins ?? []);
+        const backend = lang
+            ? defaultRegistry.getByLangId(lang)
+            : defaultRegistry.getByLangId("js");
+        if (!backend) {
+            const available = defaultRegistry.allBackends.map((b) => b.langId).join(", ");
+            throw new Error(`Unknown language "${lang}". Available: ${available}`);
+        }
+        await backend.validateSelector(query);
+        const explanation = backend.langId === "js" ? explainSelector(query) : undefined;
+        const result = { valid: true, lang: backend.langId };
+        if (explanation)
+            result.explanation = explanation;
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const isConfigError = msg.startsWith("Unknown language");
+        if (isConfigError) {
+            return { content: [{ type: "text", text: `Error: ${msg}` }], isError: true };
+        }
+        return {
+            content: [
+                { type: "text", text: JSON.stringify({ valid: false, error: msg }, null, 2) },
+            ],
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Handler: show_ast
+// ---------------------------------------------------------------------------
+export async function handleShowAst(args) {
+    const { code, file, lines, lang, plugins } = args;
+    try {
+        await loadPlugins(plugins ?? []);
+        let source;
+        let filePath;
+        if (file) {
+            source = await readFile(file, "utf8");
+            if (lines) {
+                const parts = lines.split("-").map(Number);
+                const start = parts[0];
+                const end = parts[1] ?? start;
+                if (isNaN(start) || isNaN(end) || start < 1 || end < start) {
+                    throw new Error(`Invalid lines value "${lines}". Expected format: N or N-M (e.g. "10-20")`);
+                }
+                source = source.split("\n").slice(start - 1, end).join("\n");
+            }
+            filePath = file;
+        }
+        else if (code) {
+            source = code;
+            filePath = lang === "python" ? "snippet.py" : "snippet.ts";
+        }
+        else {
+            throw new Error("Provide either code (inline snippet) or file (path to source file)");
+        }
+        const backend = lang
+            ? defaultRegistry.getByLangId(lang)
+            : file
+                ? defaultRegistry.getByExtension(extname(file))
+                : defaultRegistry.getByLangId("js");
+        if (!backend) {
+            const available = defaultRegistry.allBackends.map((b) => b.langId).join(", ");
+            const hint = lang ? ` Did you forget to include it in plugins?` : "";
+            throw new Error(`No backend for "${lang ?? extname(file ?? "")}".${hint} Available: ${available}`);
+        }
+        if (!backend.printAst) {
+            throw new Error(`Backend "${backend.langId}" does not support show_ast`);
+        }
+        const ast = await backend.parse(source, filePath);
+        const text = backend.printAst(ast, source, "text");
+        return { content: [{ type: "text", text }] };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: `Error: ${msg}` }], isError: true };
+    }
+}
+// ---------------------------------------------------------------------------
+// Server (configured but not connected — connection happens in index.ts)
+// ---------------------------------------------------------------------------
+export const server = new McpServer({ name: "ast-search", version: "0.1.0" });
+server.registerTool("search", {
+    title: "Search code by AST pattern",
+    description: `Search source code using AST structural patterns (CSS selectors for JS/TS/Vue; S-expressions for Python).
+Returns precise match locations with file path, line, column, source snippet, and scope metadata.
+Prefer this over grep/ripgrep when the query is about code structure rather than text.
+
+Query examples:
+  ["FunctionDeclaration[async=true]"]          — async function declarations
+  ["call[callee.property.name='log']"]         — calls to any .log() method
+  ["await"]                                    — all await expressions
+  ["ImportDeclaration[source.value='react']"]  — files importing react
+
+Workflow tips:
+- Use limit (e.g. 10) for scope checks before committing to a large refactor.
+- Pass multiple queries to search for several patterns in a single repo walk.
+- Use showAst: true when you need to refine a query — it prints the AST subtree of each match.
+- For Python files, pass plugins: ["ast-search-python"] and use tree-sitter S-expressions.`,
+    inputSchema: searchSchema,
+}, handleSearch);
+server.registerTool("validate_query", {
+    title: "Validate an AST query",
+    description: "Validate an AST selector without running a search. Returns whether the syntax is valid and, for JS queries, a plain-English explanation of what nodes the query matches. Use this before running an unfamiliar query on a large repo.",
+    inputSchema: validateSchema,
+}, handleValidateQuery);
+server.registerTool("show_ast", {
+    title: "Show AST structure for code",
+    description: "Print the AST structure of a code snippet or file. Use this to discover node types and property paths when writing queries. Pass a short code snippet to see its structure, or specify a file with an optional line range.",
+    inputSchema: showAstSchema,
+}, handleShowAst);

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "ast-search-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for ast-search — structural code search for AI agents",
+  "type": "module",
+  "bin": {
+    "ast-search-mcp": "./build/index.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./build/index.js",
+      "types": "./build/index.d.ts"
+    }
+  },
+  "author": "shiplet",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/willey-shiplet/ast-search.git",
+    "directory": "packages/ast-search-mcp"
+  },
+  "files": [
+    "build/*.js",
+    "build/*.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "npx tsc",
+    "test": "jest --testPathPattern='src/__tests__'",
+    "prepublishOnly": "pnpm build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "ast-search-js": "workspace:^",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@jest/globals": "^29.7.0",
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.12.7",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.2",
+    "typescript": "^5.0.0"
+  }
+}