@justmpm/supergrep 0.1.0

package/dist/chunk-4MPFPILM.js

@@ -0,0 +1,1342 @@
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/tools.ts
+import { z } from "zod";
+
+// src/tools/find.ts
+import { parse } from "@ast-grep/napi";
+import { readFile, readdir } from "fs/promises";
+import { join, relative, resolve, extname } from "path";
+
+// src/utils/lang.ts
+import { Lang } from "@ast-grep/napi";
+var LANG_ALIASES = {
+  // JavaScript
+  javascript: Lang.JavaScript,
+  js: Lang.JavaScript,
+  cjs: Lang.JavaScript,
+  mjs: Lang.JavaScript,
+  // TypeScript
+  typescript: Lang.TypeScript,
+  ts: Lang.TypeScript,
+  // TSX
+  tsx: Lang.Tsx,
+  // CSS
+  css: Lang.Css,
+  // HTML
+  html: Lang.Html
+};
+var EXT_TO_LANG_ALIAS = {
+  ".js": "javascript",
+  ".mjs": "javascript",
+  ".cjs": "javascript",
+  ".jsx": "javascript",
+  ".ts": "typescript",
+  ".tsx": "tsx",
+  ".css": "css",
+  ".scss": "css",
+  ".less": "css",
+  ".html": "html",
+  ".htm": "html"
+};
+var SUPPORTED_EXTENSIONS = new Set(Object.keys(EXT_TO_LANG_ALIAS));
+function resolveLang(input) {
+  const normalized = input.toLowerCase().replace(/^\./, "");
+  return LANG_ALIASES[normalized];
+}
+function detectLangFromFile(filePath) {
+  const ext = filePath.slice(filePath.lastIndexOf(".")).toLowerCase();
+  const alias = EXT_TO_LANG_ALIAS[ext];
+  return alias ? resolveLang(alias) : void 0;
+}
+function listSupportedLanguages() {
+  return ["JavaScript", "TypeScript", "TSX", "CSS", "HTML"];
+}
+function langName(lang) {
+  const langStr = String(lang);
+  const friendly = {
+    Html: "HTML",
+    JavaScript: "JavaScript",
+    Tsx: "TSX",
+    Css: "CSS",
+    TypeScript: "TypeScript"
+  };
+  return friendly[langStr] ?? langStr;
+}
+function isSupportedExtension(filePath) {
+  const ext = filePath.slice(filePath.lastIndexOf(".")).toLowerCase();
+  return SUPPORTED_EXTENSIONS.has(ext);
+}
+var IGNORED_EXTENSIONS_SUBSTRINGS = [
+  ".min.js",
+  ".min.css",
+  ".bundle.js",
+  ".chunk.js",
+  ".map",
+  ".d.ts"
+];
+function shouldIgnoreFile(filePath) {
+  const lower = filePath.toLowerCase();
+  for (const ext of IGNORED_EXTENSIONS_SUBSTRINGS) {
+    if (lower.includes(ext)) return true;
+  }
+  return false;
+}
+var IGNORED_DIRS = [
+  "node_modules",
+  "dist",
+  "build",
+  ".git",
+  ".next",
+  ".turbo",
+  "coverage",
+  "out"
+];
+
+// src/tools/find.ts
+var META_VAR_RE = /\$(\$\$)?([A-Z_][A-Z0-9_]*)/g;
+async function findPattern(options) {
+  const startTime = Date.now();
+  const warnings = [];
+  const cwd = options.cwd ?? process.cwd();
+  const lang = resolveLangForOptions(options, cwd, warnings);
+  if (!lang) {
+    throw new LanguageNotDetectedError(options.lang ?? "desconhecida");
+  }
+  validatePattern(options.pattern, lang);
+  const searchDir = resolve(cwd, options.path ?? ".");
+  const files = await findCodeFiles(searchDir, cwd, lang);
+  warnings.push(...files.warnings);
+  const metaVarNames = extractMetaVarNames(options.pattern);
+  const matches = [];
+  for (const filePath of files.paths) {
+    try {
+      const source = await readFile(filePath, "utf-8");
+      const ast = parse(lang, source);
+      const root = ast.root();
+      const foundNodes = root.findAll(options.pattern);
+      for (const node of foundNodes) {
+        const range = node.range();
+        const match = {
+          file: relative(cwd, filePath).replace(/\\/g, "/"),
+          line: range.start.line,
+          column: range.start.column,
+          endLine: range.end.line,
+          endColumn: range.end.column,
+          text: node.text(),
+          metaVariables: {},
+          context: extractContextLines(source, range.start.line, 2)
+        };
+        for (const varName of metaVarNames) {
+          const metaNode = node.getMatch(varName);
+          if (metaNode) {
+            match.metaVariables[varName] = metaNode.text();
+          }
+        }
+        matches.push(match);
+      }
+    } catch {
+      continue;
+    }
+  }
+  const uniqueFiles = new Set(matches.map((m) => m.file));
+  const executionTimeMs = Date.now() - startTime;
+  return {
+    result: {
+      pattern: options.pattern,
+      lang,
+      matches,
+      filesScanned: files.paths.length,
+      filesWithMatches: uniqueFiles.size,
+      executionTimeMs
+    },
+    warnings
+  };
+}
+function extractMetaVarNames(pattern) {
+  const names = /* @__PURE__ */ new Set();
+  let match;
+  const re = new RegExp(META_VAR_RE.source, "g");
+  while ((match = re.exec(pattern)) !== null) {
+    names.add(match[2]);
+  }
+  return [...names];
+}
+function extractContextLines(source, line, contextLines) {
+  const lines = source.split("\n");
+  const start = Math.max(0, line - contextLines);
+  const end = Math.min(lines.length, line + contextLines + 1);
+  return lines.slice(start, end);
+}
+function resolveLangForOptions(options, _cwd, warnings) {
+  if (options.lang) {
+    const lang = resolveLang(options.lang);
+    if (!lang) {
+      warnings.push(`Linguagem "${options.lang}" nao reconhecida. Tentando autodeteccao...`);
+    } else {
+      return lang;
+    }
+  }
+  if (options.path) {
+    const ext = extname(options.path).toLowerCase();
+    if (ext && isSupportedExtension(options.path)) {
+      const detected = detectLangFromFile(options.path);
+      if (detected) return detected;
+    }
+  }
+  warnings.push("Linguagem nao especificada, usando TypeScript como default.");
+  return resolveLang("typescript");
+}
+function validatePattern(pattern, lang) {
+  try {
+    parse(lang, pattern);
+  } catch {
+    try {
+      parse(lang, `const _x = ${pattern}`);
+    } catch {
+      throw new PatternParseError(pattern, lang);
+    }
+  }
+}
+async function findCodeFiles(searchDir, _cwd, _lang) {
+  const warnings = [];
+  try {
+    const { stat: stat3 } = await import("fs/promises");
+    const dirStat = await stat3(searchDir);
+    if (dirStat.isFile()) {
+      if (!isSupportedExtension(searchDir)) {
+        const fileName = searchDir.split(/[/\\]/).pop() ?? searchDir;
+        warnings.push(
+          `Arquivo ${fileName}: extensao pode nao ser suportada para ${langName(_lang)}`
+        );
+      }
+      return { paths: [searchDir], warnings };
+    }
+  } catch {
+    warnings.push(`Path nao encontrado: ${searchDir}. Usando diretorio atual.`);
+    return { paths: [], warnings };
+  }
+  const paths = [];
+  async function walk(dir) {
+    try {
+      const entries = await readdir(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        const fullPath = join(dir, entry.name);
+        if (entry.isDirectory()) {
+          if (IGNORED_DIRS.includes(entry.name) || entry.name.startsWith(".")) {
+            continue;
+          }
+          await walk(fullPath);
+        } else if (entry.isFile()) {
+          if (shouldIgnoreFile(fullPath)) continue;
+          if (!isSupportedExtension(fullPath)) continue;
+          paths.push(fullPath);
+        }
+      }
+    } catch {
+    }
+  }
+  await walk(searchDir);
+  if (paths.length > 5e3) {
+    warnings.push(
+      `Muitos arquivos encontrados (${paths.length}). Limitando a 5000. Use --path para focar em um diretorio.`
+    );
+    return { paths: paths.slice(0, 5e3), warnings };
+  }
+  if (paths.length === 0) {
+    warnings.push(
+      `Nenhum arquivo de codigo encontrado em: ${relative(_cwd, searchDir)}`
+    );
+  }
+  return { paths, warnings };
+}
+var PatternParseError = class extends Error {
+  pattern;
+  lang;
+  constructor(pattern, lang) {
+    super(`Erro ao parsear padrao "${pattern}" para ${langName(lang)}`);
+    this.name = "PatternParseError";
+    this.pattern = pattern;
+    this.lang = lang;
+  }
+};
+var LanguageNotDetectedError = class extends Error {
+  input;
+  constructor(input) {
+    super(`Nao foi possivel detectar a linguagem: "${input}"`);
+    this.name = "LanguageNotDetectedError";
+    this.input = input;
+  }
+};
+
+// src/tools/tree.ts
+import { parse as parse2 } from "@ast-grep/napi";
+import { readFile as readFile2, stat } from "fs/promises";
+import { resolve as resolve2, relative as relative2, extname as extname2 } from "path";
+async function exploreTree(options) {
+  const warnings = [];
+  const cwd = options.cwd ?? process.cwd();
+  let source;
+  let filePath;
+  let detectedLang;
+  if (options.code) {
+    source = options.code;
+    filePath = "<inline>";
+    if (options.lang) {
+      detectedLang = resolveLang(options.lang);
+      if (!detectedLang) {
+        warnings.push(`Linguagem "${options.lang}" nao reconhecida, usando TypeScript.`);
+        detectedLang = resolveLang("typescript");
+      }
+    } else {
+      warnings.push("Linguagem nao especificada para codigo inline, usando TypeScript.");
+      detectedLang = resolveLang("typescript");
+    }
+  } else if (options.path) {
+    filePath = resolve2(cwd, options.path);
+    try {
+      await stat(filePath);
+    } catch {
+      throw new FileNotFoundError(filePath);
+    }
+    source = await readFile2(filePath, "utf-8");
+    if (options.lang) {
+      detectedLang = resolveLang(options.lang);
+      if (!detectedLang) {
+        warnings.push(`Linguagem "${options.lang}" nao reconhecida. Tentando detectar...`);
+      }
+    }
+    if (!detectedLang) {
+      detectedLang = detectLangFromFile(filePath);
+      if (!detectedLang) {
+        warnings.push(
+          `Nao foi possivel detectar linguagem da extensao "${extname2(filePath)}". Usando TypeScript.`
+        );
+        detectedLang = resolveLang("typescript");
+      }
+    }
+  } else {
+    throw new Error("Informe path (arquivo) ou code (snippet) para analisar.");
+  }
+  const lang = detectedLang;
+  let ast;
+  try {
+    ast = parse2(lang, source);
+  } catch (parseErr) {
+    const msg = parseErr instanceof Error ? parseErr.message : String(parseErr);
+    throw new TreeParseError(filePath, lang, msg);
+  }
+  const root = ast.root();
+  const kindCounts = /* @__PURE__ */ new Map();
+  let totalNodes = 0;
+  walkAST(root, kindCounts, { count: 0 });
+  totalNodes = kindCounts.size > 0 ? [...kindCounts.values()].reduce((a, b) => a + b, 0) : 0;
+  const displayPath = options.path ? relative2(cwd, filePath).replace(/\\/g, "/") : filePath;
+  const result = {
+    file: displayPath,
+    lang,
+    totalNodes,
+    uniqueKinds: [...kindCounts.keys()].sort(),
+    kindCounts: Object.fromEntries(kindCounts),
+    rootKind: String(root.kind())
+  };
+  return { result, warnings };
+}
+function walkAST(node, kindCounts, state) {
+  state.count++;
+  const kind = String(node.kind());
+  kindCounts.set(kind, (kindCounts.get(kind) ?? 0) + 1);
+  if (state.count > 1e5) {
+    return;
+  }
+  for (const child of node.children()) {
+    walkAST(child, kindCounts, state);
+  }
+}
+var FileNotFoundError = class extends Error {
+  filePath;
+  constructor(filePath) {
+    super(`Arquivo nao encontrado: ${filePath}`);
+    this.name = "FileNotFoundError";
+    this.filePath = filePath;
+  }
+};
+var TreeParseError = class extends Error {
+  filePath;
+  lang;
+  constructor(filePath, lang, detail) {
+    super(`Erro ao parsear "${filePath}" como ${langName(lang)}: ${detail}`);
+    this.name = "TreeParseError";
+    this.filePath = filePath;
+    this.lang = lang;
+  }
+};
+
+// src/tools/replace.ts
+import { parse as parse3 } from "@ast-grep/napi";
+import { readFile as readFile3, readdir as readdir2, stat as stat2 } from "fs/promises";
+import { join as join2, resolve as resolve3, relative as relative3 } from "path";
+var META_VAR_RE2 = /\$(\$\$)?([A-Z_][A-Z0-9_]*)/g;
+async function replacePreview(options) {
+  const warnings = [];
+  const cwd = options.cwd ?? process.cwd();
+  let lang;
+  if (options.lang) {
+    const resolved = resolveLang(options.lang);
+    if (!resolved) {
+      throw new ReplaceLangError(options.lang);
+    }
+    lang = resolved;
+  } else if (options.path) {
+    const detected = detectLangFromFile(options.path);
+    if (!detected) {
+      throw new ReplaceLangError(options.path);
+    }
+    lang = detected;
+    warnings.push(`Linguagem detectada automaticamente: ${langName(lang)}`);
+  } else {
+    warnings.push("Linguagem nao especificada, usando TypeScript como default.");
+    lang = resolveLang("typescript");
+  }
+  validateReplacePattern(options.pattern, lang);
+  const searchDir = resolve3(cwd, options.path ?? ".");
+  const files = await findCodeFiles2(searchDir);
+  const metaVarNames = extractMetaVarNames2(options.pattern);
+  const changes = [];
+  for (const filePath of files.paths) {
+    try {
+      const source = await readFile3(filePath, "utf-8");
+      const ast = parse3(lang, source);
+      const root = ast.root();
+      const foundNodes = root.findAll(options.pattern);
+      for (const node of foundNodes) {
+        const metaVars = {};
+        for (const varName of metaVarNames) {
+          const metaNode = node.getMatch(varName);
+          if (metaNode) {
+            metaVars[varName] = metaNode.text();
+          }
+        }
+        let interpolated = options.rewrite;
+        for (const [name, value] of Object.entries(metaVars)) {
+          interpolated = interpolated.replaceAll(
+            new RegExp(`\\$${name}\\b`, "g"),
+            value
+          );
+        }
+        const range = node.range();
+        changes.push({
+          file: relative3(cwd, filePath).replace(/\\/g, "/"),
+          line: range.start.line,
+          column: range.start.column,
+          original: node.text(),
+          replacement: interpolated
+        });
+      }
+    } catch {
+      continue;
+    }
+  }
+  const uniqueFiles = new Set(changes.map((c) => c.file));
+  return {
+    result: {
+      pattern: options.pattern,
+      rewrite: options.rewrite,
+      lang,
+      changes,
+      filesScanned: files.paths.length,
+      filesAffected: uniqueFiles.size
+    },
+    warnings
+  };
+}
+function extractMetaVarNames2(pattern) {
+  const names = /* @__PURE__ */ new Set();
+  let match;
+  const re = new RegExp(META_VAR_RE2.source, "g");
+  while ((match = re.exec(pattern)) !== null) {
+    names.add(match[2]);
+  }
+  return [...names];
+}
+function validateReplacePattern(pattern, lang) {
+  try {
+    parse3(lang, pattern);
+  } catch {
+    try {
+      parse3(lang, `const _x = ${pattern}`);
+    } catch {
+      throw new ReplacePatternError(pattern, lang);
+    }
+  }
+}
+async function findCodeFiles2(searchDir) {
+  const warnings = [];
+  try {
+    const dirStat = await stat2(searchDir);
+    if (dirStat.isFile()) {
+      return { paths: [searchDir], warnings };
+    }
+  } catch {
+    return { paths: [], warnings };
+  }
+  const paths = [];
+  async function walk(dir) {
+    try {
+      const entries = await readdir2(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        const fullPath = join2(dir, entry.name);
+        if (entry.isDirectory()) {
+          if (IGNORED_DIRS.includes(entry.name) || entry.name.startsWith(".")) {
+            continue;
+          }
+          await walk(fullPath);
+        } else if (entry.isFile()) {
+          if (shouldIgnoreFile(fullPath)) continue;
+          if (!isSupportedExtension(fullPath)) continue;
+          paths.push(fullPath);
+        }
+      }
+    } catch {
+    }
+  }
+  await walk(searchDir);
+  if (paths.length > 5e3) {
+    warnings.push(
+      `Muitos arquivos (${paths.length}). Limitando a 5000. Use --path para focar.`
+    );
+    return { paths: paths.slice(0, 5e3), warnings };
+  }
+  return { paths, warnings };
+}
+var ReplacePatternError = class extends Error {
+  pattern;
+  lang;
+  constructor(pattern, lang) {
+    super(`Erro ao parsear padrao "${pattern}" para ${langName(lang)}`);
+    this.name = "ReplacePatternError";
+    this.pattern = pattern;
+    this.lang = lang;
+  }
+};
+var ReplaceLangError = class extends Error {
+  input;
+  constructor(input) {
+    super(`Linguagem nao suportada: "${input}"`);
+    this.name = "ReplaceLangError";
+    this.input = input;
+  }
+};
+
+// src/utils/hints.ts
+var COMMAND_MAP = {
+  find: {
+    cli: "supergrep find <pattern>",
+    mcp: "supergrep_find { pattern: '<pattern>' }"
+  },
+  tree: {
+    cli: "supergrep tree <file>",
+    mcp: "supergrep_tree { path: '<file>' }"
+  },
+  replace: {
+    cli: "supergrep replace <pattern> <rewrite>",
+    mcp: "supergrep_replace { pattern: '<pattern>', rewrite: '<rewrite>' }"
+  },
+  find_lang: {
+    cli: "supergrep find <pattern> --lang=<lang>",
+    mcp: "supergrep_find { pattern: '<pattern>', lang: '<lang>' }"
+  },
+  find_path: {
+    cli: "supergrep find <pattern> --path=<path>",
+    mcp: "supergrep_find { pattern: '<pattern>', path: '<path>' }"
+  }
+};
+function hint(command, ctx, params) {
+  const mapping = COMMAND_MAP[command];
+  if (!mapping) return command;
+  let instruction = mapping[ctx];
+  if (params) {
+    for (const [placeholder, value] of Object.entries(params)) {
+      instruction = instruction.replaceAll(placeholder, value);
+    }
+  }
+  return instruction;
+}
+var NEXT_STEPS = {
+  find: [
+    { command: "tree", description: "explorar a estrutura AST de um arquivo com matches" },
+    { command: "find", description: "refinar a busca com outro padrao" },
+    { command: "replace", description: "pre-visualizar uma substituicao estrutural" }
+  ],
+  tree: [
+    { command: "find", description: "usar os kinds descobertos para buscar padroes" },
+    { command: "tree", description: "explorar outro arquivo" }
+  ],
+  replace: [
+    { command: "find", description: "ver todos os matches do padrao antes de substituir" },
+    { command: "tree", description: "explorar a estrutura AST para criar padroes melhores" }
+  ]
+};
+function nextSteps(command, ctx) {
+  const steps = NEXT_STEPS[command];
+  if (!steps || steps.length === 0) return "";
+  let out = "\n\u{1F4D6} Proximos passos:\n";
+  for (const step of steps) {
+    const instruction = hint(step.command, ctx, step.params);
+    out += `   \u2192 ${instruction} - ${step.description}
+`;
+  }
+  return out;
+}
+function recoveryHint(errorType, ctx, _extra) {
+  switch (errorType) {
+    case "pattern_invalid":
+      return `
+\u{1F4A1} Dicas:
+   \u2192 O padrao deve ser codigo valido na linguagem escolhida
+   \u2192 Use $VAR para capturar um unico no da AST (ex: console.$METHOD($MSG))
+   \u2192 Use $$$VARS para capturar multiplos nos (ex: function $$$BODY)
+   \u2192 Teste seu padrao no playground: https://ast-grep.github.io/playground
+`;
+    case "no_matches":
+      return `
+\u{1F4A1} Nenhum match encontrado. Dicas:
+   \u2192 Verifique se a linguagem esta correta (use o parametro lang)
+   \u2192 Tente um padrao mais simples primeiro
+   \u2192 ${hint("tree", ctx)} - veja a estrutura AST do arquivo para criar padroes
+   \u2192 ${hint("find_lang", ctx)} - especifique a linguagem manualmente
+`;
+    case "lang_not_supported":
+      return `
+\u{1F4A1} Linguagem nao suportada. Dicas:
+   \u2192 ${hint("tree", ctx)} - use com arquivos de codigo fonte (.ts, .py, .rs, etc.)
+   \u2192 Extensoes suportadas: .ts, .tsx, .js, .py, .rs, .go, .java, .kt, .swift e mais
+   \u2192 Para JSON, YAML, CSS e HTML, use a linguagem correspondente
+`;
+    case "lang_not_detected":
+      return `
+\u{1F4A1} Nao foi possivel detectar a linguagem. Especifique manualmente:
+   \u2192 ${hint("find_lang", ctx)} - informe a linguagem (ex: 'typescript', 'python')
+`;
+    case "file_not_found":
+      return `
+\u{1F4A1} Arquivo nao encontrado. Verifique:
+   \u2192 O caminho esta correto?
+   \u2192 O arquivo existe no diretorio de trabalho (cwd)?
+   \u2192 Use caminho relativo ou absoluto
+`;
+    case "path_not_found":
+      return `
+\u{1F4A1} Diretorio nao encontrado. Verifique:
+   \u2192 O caminho esta correto?
+   \u2192 ${hint("find_path", ctx)} - tente com outro path
+`;
+    case "generic":
+    default:
+      return `
+\u{1F4A1} Tente:
+   \u2192 ${hint("find", ctx)} - buscar padroes no codigo
+   \u2192 ${hint("tree", ctx)} - explorar a estrutura AST
+   \u2192 Verifique se o diretorio (cwd) esta correto
+`;
+  }
+}
+
+// src/utils/formatters.ts
+function formatFindText(result, ctx) {
+  const { pattern, lang, matches, filesScanned, filesWithMatches, executionTimeMs } = result;
+  const langStr = langName(lang);
+  if (matches.length === 0) {
+    let out2 = `
+\u{1F50D} supergrep find: "${pattern}"
+`;
+    out2 += `   Linguagem: ${langStr}
+`;
+    out2 += `   Nenhum match encontrado em ${filesScanned} arquivos analisados
+`;
+    out2 += `   Tempo: ${executionTimeMs}ms
+`;
+    out2 += nextSteps("find", ctx);
+    return out2;
+  }
+  let out = `
+\u{1F50D} supergrep find: "${pattern}"
+`;
+  out += `   Linguagem: ${langStr}
+`;
+  out += `   ${matches.length} matches em ${filesWithMatches} arquivos (${filesScanned} analisados)
+`;
+  out += `   Tempo: ${executionTimeMs}ms
+
+`;
+  const grouped = groupBy(matches, (m) => m.file);
+  let matchCount = 0;
+  for (const [file, fileMatches] of Object.entries(grouped)) {
+    out += `\u{1F4C1} ${file} (${fileMatches.length} match${fileMatches.length > 1 ? "es" : ""})
+`;
+    for (const match of fileMatches.slice(0, 50)) {
+      matchCount++;
+      const lineStr = `${match.line + 1}:${match.column + 1}`.padEnd(10);
+      const text = match.text.length > 120 ? match.text.slice(0, 120) + "..." : match.text.replace(/\n/g, "\\n");
+      out += `   ${lineStr} ${text}
+`;
+      const metaEntries = Object.entries(match.metaVariables);
+      if (metaEntries.length > 0) {
+        for (const [name, value] of metaEntries) {
+          const truncated = value.length > 60 ? value.slice(0, 60) + "..." : value;
+          out += `   \u2514\u2500 $${name}: ${truncated}
+`;
+        }
+      }
+    }
+    if (fileMatches.length > 50) {
+      out += `   ... e mais ${fileMatches.length - 50} matches neste arquivo
+`;
+    }
+    out += "\n";
+  }
+  if (matchCount > 200) {
+    out += `\u{1F4CA} Resumo: ${matches.length} matches em ${filesWithMatches} arquivos
+`;
+    out += `   Dica: use path para focar em um diretorio especifico
+`;
+  }
+  out += `
+\u{1F4CA} ${matches.length} matches em ${filesWithMatches} arquivos
+`;
+  out += nextSteps("find", ctx);
+  return out;
+}
+function formatFindJson(result) {
+  return JSON.stringify({
+    pattern: result.pattern,
+    lang: langName(result.lang),
+    totalMatches: result.matches.length,
+    filesScanned: result.filesScanned,
+    filesWithMatches: result.filesWithMatches,
+    executionTimeMs: result.executionTimeMs,
+    matches: result.matches.map((m) => ({
+      file: m.file,
+      line: m.line + 1,
+      // 1-indexed para JSON
+      column: m.column + 1,
+      endLine: m.endLine + 1,
+      endColumn: m.endColumn + 1,
+      text: m.text,
+      metaVariables: m.metaVariables,
+      context: m.context
+    }))
+  }, null, 2);
+}
+function formatTreeText(result, ctx) {
+  const { file, lang, totalNodes, uniqueKinds, kindCounts, rootKind } = result;
+  const langStr = langName(lang);
+  let out = `
+\u{1F333} AST Tree: ${file}
+`;
+  out += `   Linguagem: ${langStr}
+`;
+  out += `   Total de nos: ${totalNodes}
+`;
+  out += `   Tipos unicos de nos (kinds): ${uniqueKinds.length}
+`;
+  out += `   No raiz: ${rootKind}
+
+`;
+  const sortedKinds = Object.entries(kindCounts).sort(([, a], [, b]) => b - a);
+  out += `\u{1F4CA} Distribuicao de kinds:
+`;
+  for (const [kind, count] of sortedKinds) {
+    const bar = "\u2588".repeat(Math.min(count, 50));
+    out += `   ${kind.padEnd(30)} ${String(count).padStart(4)}  ${bar}
+`;
+  }
+  out += `
+\u{1F4D6} Como usar esses kinds:
+`;
+  out += `   \u2022 supergrep_find com pattern string (ex: "const $X = $Y")
+`;
+  out += `   \u2022 Regras YAML com kind: "${sortedKinds[0]?.[0] ?? "function"}"
+`;
+  out += nextSteps("tree", ctx);
+  return out;
+}
+function formatTreeJson(result) {
+  return JSON.stringify({
+    file: result.file,
+    lang: langName(result.lang),
+    totalNodes: result.totalNodes,
+    uniqueKinds: result.uniqueKinds,
+    kindCounts: result.kindCounts,
+    rootKind: result.rootKind
+  }, null, 2);
+}
+function formatReplaceText(result, ctx) {
+  const { pattern, rewrite, lang, changes, filesAffected } = result;
+  const langStr = langName(lang);
+  if (changes.length === 0) {
+    let out2 = `
+\u{1F504} supergrep replace: "${pattern}" \u2192 "${rewrite}"
+`;
+    out2 += `   Linguagem: ${langStr}
+`;
+    out2 += `   Nenhum match encontrado para substituir
+`;
+    out2 += nextSteps("replace", ctx);
+    return out2;
+  }
+  let out = `
+\u{1F504} supergrep replace: "${pattern}" \u2192 "${rewrite}"
+`;
+  out += `   Linguagem: ${langStr}
+`;
+  out += `   ${changes.length} substituicoes em ${filesAffected} arquivos
+
+`;
+  const grouped = groupBy(changes, (c) => c.file);
+  for (const [file, fileChanges] of Object.entries(grouped)) {
+    out += `\u{1F4C1} ${file} (${fileChanges.length} mudanca${fileChanges.length > 1 ? "s" : ""})
+`;
+    for (const change of fileChanges.slice(0, 10)) {
+      const lineStr = `${change.line + 1}:${change.column + 1}`;
+      out += `   L${lineStr}:
+`;
+      out += `   [-] ${change.original.replace(/\n/g, "\\n")}
+`;
+      out += `   [+] ${change.replacement.replace(/\n/g, "\\n")}
+
+`;
+    }
+    if (fileChanges.length > 10) {
+      out += `   ... e mais ${fileChanges.length - 10} mudancas neste arquivo
+
+`;
+    }
+  }
+  out += `
+\u26A0\uFE0F Este e apenas um preview. Nenhum arquivo foi modificado.
+`;
+  out += `\u{1F4CA} ${changes.length} substituicoes em ${filesAffected} arquivos
+`;
+  out += nextSteps("replace", ctx);
+  return out;
+}
+function formatReplaceJson(result) {
+  return JSON.stringify({
+    pattern: result.pattern,
+    rewrite: result.rewrite,
+    lang: langName(result.lang),
+    totalChanges: result.changes.length,
+    filesScanned: result.filesScanned,
+    filesAffected: result.filesAffected,
+    changes: result.changes.map((c) => ({
+      file: c.file,
+      line: c.line + 1,
+      column: c.column + 1,
+      original: c.original,
+      replacement: c.replacement
+    }))
+  }, null, 2);
+}
+function groupBy(items, keyFn) {
+  const result = {};
+  for (const item of items) {
+    const key = keyFn(item);
+    if (!result[key]) result[key] = [];
+    result[key].push(item);
+  }
+  return result;
+}
+
+// src/utils/errors.ts
+function formatPatternError(options) {
+  const { pattern, lang, originalError, ctx = "mcp" } = options;
+  const langStr = langName(lang);
+  let out = `
+\u274C Erro ao parsear padrao em ${langStr}: "${pattern}"
+`;
+  if (originalError) {
+    out += `
+\u{1F4DD} Detalhe do parser: ${originalError}
+`;
+  }
+  out += `
+\u{1F4D6} Escrevendo padroes AST Grep:
+`;
+  out += `   \u2022 O padrao deve ser codigo sintaticamente valido na linguagem
+`;
+  out += `   \u2022 Use $NOME para capturar um unico no da AST (meta-variavel)
+`;
+  out += `   \u2022 Use $$$NOME para capturar zero ou mais nos
+`;
+  out += `   \u2022 Exemplos validos:
+`;
+  out += `     - console.log($MSG) \u2014 captura um argumento
+`;
+  out += `     - function $NOME($$$PARAMS) { $$$BODY } \u2014 captura funcoes
+`;
+  out += `     - import { $$$ITEMS } from '$MODULE' \u2014 captura imports
+`;
+  out += `     - const $VAR = $VALUE \u2014 captura declaracoes
+`;
+  out += `   \u2022 Teste seu padrao no playground: https://ast-grep.github.io/playground
+`;
+  out += recoveryHint("pattern_invalid", ctx);
+  return out;
+}
+function formatLangNotSupported(options) {
+  const { input } = options;
+  const supported = listSupportedLanguages();
+  let out = `
+\u274C Linguagem nao suportada pelo supergrep: "${input}"
+
+`;
+  const similar = findSimilarSimple(input, supported);
+  if (similar.length > 0) {
+    out += `\u{1F4A1} Voce quis dizer?
+`;
+    for (const s of similar.slice(0, 3)) {
+      out += `   \u2192 ${s}
+`;
+    }
+    out += `
+`;
+  }
+  out += `\u{1F4E6} Linguagens suportadas via @ast-grep/napi (${supported.length}):
+`;
+  for (const lang of supported) {
+    out += `   \u2022 ${lang}
+`;
+  }
+  out += `
+\u26A0\uFE0F O @ast-grep/napi suporta apenas linguagens do ecossistema web.
+`;
+  out += `   Para Python, Rust, Go e outras, use o CLI: npx @ast-grep/cli
+`;
+  out += `
+\u{1F4D6} Dicas:
+`;
+  out += `   \u2192 Use "typescript" ou "ts" para TypeScript
+`;
+  out += `   \u2192 Use "javascript" ou "js" para JavaScript
+`;
+  out += `   \u2192 Deixe vazio para autodeteccao por extensao
+`;
+  return out;
+}
+function formatFileNotFound(options) {
+  const { filePath, ctx = "mcp" } = options;
+  let out = `
+\u274C Arquivo nao encontrado: "${filePath}"
+
+`;
+  out += `\u{1F4D6} Verifique:
+`;
+  out += `   \u2192 O arquivo existe?
+`;
+  out += `   \u2192 O caminho e relativo ao diretorio de trabalho (cwd)?
+`;
+  out += recoveryHint("file_not_found", ctx);
+  return out;
+}
+function findSimilarSimple(input, candidates) {
+  const lower = input.toLowerCase();
+  const scored = candidates.map((c) => ({
+    name: c,
+    score: levenshteinDistance(lower, c.toLowerCase())
+  }));
+  return scored.filter((s) => s.score <= 4).sort((a, b) => a.score - b.score).map((s) => s.name);
+}
+function levenshteinDistance(a, b) {
+  const matrix = [];
+  for (let i = 0; i <= b.length; i++) {
+    matrix[i] = [i];
+  }
+  for (let j = 0; j <= a.length; j++) {
+    matrix[0][j] = j;
+  }
+  for (let i = 1; i <= b.length; i++) {
+    for (let j = 1; j <= a.length; j++) {
+      if (b.charAt(i - 1) === a.charAt(j - 1)) {
+        matrix[i][j] = matrix[i - 1][j - 1];
+      } else {
+        matrix[i][j] = Math.min(
+          matrix[i - 1][j - 1] + 1,
+          matrix[i][j - 1] + 1,
+          matrix[i - 1][j] + 1
+        );
+      }
+    }
+  }
+  return matrix[b.length][a.length];
+}
+function getCommandReference(ctx) {
+  let out = `
+\u{1F4CC} Ferramentas supergrep disponiveis:
+`;
+  out += `   \u2192 ${hint("find", ctx)} - Busca estrutural de codigo
+`;
+  out += `   \u2192 ${hint("tree", ctx)} - Explorar estrutura AST de um arquivo
+`;
+  out += `   \u2192 ${hint("replace", ctx)} - Pre-visualizar substituicao estrutural
+`;
+  return out;
+}
+function wrapError(message, errorType, ctx) {
+  return `
+\u274C ${message}
+${recoveryHint(errorType, ctx)}`;
+}
+
+// src/tools.ts
+var CTX = "mcp";
+function registerAllTools(server2) {
+  server2.registerTool(
+    "supergrep_find",
+    {
+      title: "Structural Code Search",
+      description: `\u26A0\uFE0F PREFIRA esta ferramenta ao inves de grep/bash quando a busca for em CODIGO-FONTE.
+
+Busca estrutural de codigo usando AST Grep. Diferente do grep textual (que
+quebra com quebras de linha, espacos extras ou comentarios no meio), o
+supergrep entende a SINTAXE da linguagem \u2014 ele busca pela ESTRUTURA do codigo,
+nao pelo texto cru.
+
+Escreva o padrao de busca na propria linguagem de programacao, usando
+metavariaveis ($VAR, $$$VARS) como curingas que capturam partes dinamicas.
+
+\u{1F4E6} LINGUAGENS SUPORTADAS (apenas 5):
+  \u2022 typescript  (.ts)
+  \u2022 javascript  (.js, .jsx, .mjs, .cjs)
+  \u2022 tsx         (.tsx)
+  \u2022 css         (.css, .scss, .less)
+  \u2022 html        (.html, .htm)
+
+\u26A0\uFE0F LIMITACAO IMPORTANTE: Apenas busca SINTAXICA. Nao resolve imports, nao
+entende tipos, nao segue referencias entre arquivos, nao faz analise de fluxo.
+Cada arquivo e analisado isoladamente. Para analise semantica, use ai-tool.
+
+\u2705 QUANDO USAR (supergrep_find e MELHOR que grep/bash):
+  \u2022 "Encontre todas as chamadas de console.LOG que tem 2 argumentos"
+  \u2022 "Ache funcoes que retornam Promise<any>"
+  \u2022 "Localize imports de uma lib deprecated"
+  \u2022 "Busque componentes React que usam useEffect sem dependencias"
+  \u2022 "Ache arrow functions que recebem exatamente 1 parametro"
+  \u2022 QUALQUER busca estrutural onde grep/quebraria com formatacao
+
+\u274C QUANDO NAO USAR (prefira ai-tool):
+  \u2022 "Onde a funcao useAuth e definida e usada?" \u2192 resolucao de escopo (aitool_find)
+  \u2022 "Quem depende deste arquivo?" \u2192 grafo de dependencias (aitool_impact_analysis)
+  \u2022 "Qual o tipo real desta variavel?" \u2192 type checker (aitool_file_context)
+  \u2022 Busca em texto plano, logs, markdown \u2192 use grep/bash comum
+
+\u{1F4DD} EXEMPLOS DE PATTERNS:
+  \u2022 console.$METHOD($$$ARGS)         \u2192 captura metodo e argumentos
+  \u2022 function $NAME($$$PARAMS) { $$$BODY }  \u2192 captura funcoes
+  \u2022 import { $$$ITEMS } from '$MODULE'     \u2192 captura imports
+  \u2022 const $VAR = $VALUE              \u2192 captura declaracoes
+  \u2022 try { $$$ } catch ($ERR) { $$$ } \u2192 captura try-catch
+  \u2022 await $FUNC($$$ARGS)             \u2192 captura chamadas assincronas
+
+\u{1F524} METAVARIAVEIS:
+  \u2022 $VAR    \u2192 captura UM no da AST (ex: um identificador, uma string)
+  \u2022 $$$VARS \u2192 captura ZERO OU MAIS nos (ex: todos os argumentos, corpo)
+
+\u{1F4A1} DICA: Se o pattern nao der match, use supergrep_tree primeiro para
+descobrir os kinds de nos disponiveis e ajustar o pattern.
+
+Workflow recomendado: supergrep_find \u2192 supergrep_tree \u2192 supergrep_replace`,
+      inputSchema: {
+        pattern: z.string().min(1).describe(
+          "Padrao AST Grep na linguagem alvo. Ex: 'console.$METHOD($$$ARGS)', 'function $NAME($$$PARAMS) { $$$BODY }'"
+        ),
+        lang: z.string().optional().describe(
+          "Linguagem: 'typescript' (.ts), 'javascript' (.js), 'tsx' (.tsx), 'css' (.css), 'html' (.html). Default: typescript. Deixe vazio para autodeteccao por extensao."
+        ),
+        path: z.string().optional().describe(
+          "Arquivo ou diretorio onde buscar. Default: diretorio atual. Ex: 'src/', 'app/page.tsx'"
+        ),
+        format: z.enum(["text", "json"]).default("text").describe(
+          "Formato de saida: text (legivel) ou json (estruturado)"
+        ),
+        cwd: z.string().optional().describe("Diretorio de trabalho. Default: diretorio atual")
+      },
+      annotations: {
+        title: "Structural Code Search",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    async (params) => {
+      try {
+        const { result, warnings } = await findPattern({
+          pattern: params.pattern,
+          lang: params.lang,
+          path: params.path,
+          cwd: params.cwd
+        });
+        const output = params.format === "json" ? formatFindJson(result) : formatFindText(result, CTX);
+        const warningText = warnings.length > 0 ? `
+\u26A0\uFE0F Avisos:
+${warnings.map((w) => `   \u2022 ${w}`).join("\n")}` : "";
+        return {
+          content: [{ type: "text", text: output + warningText }]
+        };
+      } catch (error) {
+        return handleFindError(error, CTX);
+      }
+    }
+  );
+  server2.registerTool(
+    "supergrep_tree",
+    {
+      title: "Explore AST Structure",
+      description: `Explora a estrutura da AST (Abstract Syntax Tree) de um arquivo.
+
+Mostra todos os tipos de nos (kinds) presentes, com contagens e distribuicao.
+Util para entender a estrutura do codigo e descobrir quais kinds usar
+em patterns de busca ou regras YAML.
+
+QUANDO USAR:
+- "Quais tipos de nos existem neste arquivo TypeScript?"
+- "Como escrever um pattern para capturar certas estruturas?"
+- "Preciso descobrir os kinds para uma regra de lint customizada"
+- Antes de escrever um pattern complexo, para conhecer a AST
+
+QUANDO NAO USAR:
+- Para buscar padroes no codigo \u2192 use supergrep_find
+- Para ver o conteudo do arquivo \u2192 leia o arquivo diretamente
+
+Workflow: supergrep_tree \u2192 supergrep_find (usar kinds descobertos)`,
+      inputSchema: {
+        path: z.string().optional().describe(
+          "Caminho do arquivo a analisar. Ex: 'src/app/page.tsx'"
+        ),
+        code: z.string().optional().describe(
+          "OU: snippet de codigo para analisar inline (em vez de arquivo)"
+        ),
+        lang: z.string().optional().describe(
+          "Linguagem: 'typescript', 'javascript', 'tsx', 'css', 'html'. Obrigatorio se usar 'code', opcional se usar 'path' (autodeteccao pela extensao)."
+        ),
+        format: z.enum(["text", "json"]).default("text").describe(
+          "Formato de saida: text (legivel) ou json (estruturado)"
+        ),
+        cwd: z.string().optional().describe("Diretorio de trabalho")
+      },
+      annotations: {
+        title: "Explore AST Structure",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    async (params) => {
+      try {
+        const { result, warnings } = await exploreTree({
+          path: params.path,
+          code: params.code,
+          lang: params.lang,
+          cwd: params.cwd
+        });
+        const output = params.format === "json" ? formatTreeJson(result) : formatTreeText(result, CTX);
+        const warningText = warnings.length > 0 ? `
+\u26A0\uFE0F Avisos:
+${warnings.map((w) => `   \u2022 ${w}`).join("\n")}` : "";
+        return {
+          content: [{ type: "text", text: output + warningText }]
+        };
+      } catch (error) {
+        return handleTreeError(error, CTX);
+      }
+    }
+  );
+  server2.registerTool(
+    "supergrep_replace",
+    {
+      title: "Preview Structural Replacement",
+      description: `Pre-visualiza uma substituicao estrutural de codigo (NAO modifica arquivos).
+
+Encontra padroes com AST Grep e mostra um diff de como o codigo ficaria
+apos a substituicao. Util para planejar refatoracoes em larga escala.
+
+LIMITACAO: Metavariaveis ($VAR) no rewrite sao interpoladas manualmente.
+Para casos complexos, verifique o preview antes de aplicar.
+
+QUANDO USAR:
+- "Como ficaria se eu trocasse console.log por logger.info?"
+- "Preview de substituir var por let em todo o projeto"
+- "Mostre o diff de trocar moment() por date-fns"
+- Planejar refatoracoes estruturais antes de aplicar
+
+QUANDO NAO USAR:
+- Para buscar padroes (sem substituir) \u2192 use supergrep_find
+- Para aplicar a substituicao de fato \u2192 use uma ferramenta de edicao
+- Para refatoracoes que envolvem logica complexa \u2192 implemente manualmente
+
+Workflow: supergrep_find \u2192 supergrep_replace (preview) \u2192 aplicar mudancas`,
+      inputSchema: {
+        pattern: z.string().min(1).describe(
+          "Padrao AST Grep a encontrar. Ex: 'console.log($$$ARGS)'"
+        ),
+        rewrite: z.string().min(1).describe(
+          "Texto de substituicao. Use $VAR para referenciar metavariaveis capturadas. Ex: 'logger.info($$$ARGS)'"
+        ),
+        lang: z.string().optional().describe(
+          "Linguagem: 'typescript', 'javascript', 'tsx', 'css', 'html'. Default: typescript."
+        ),
+        path: z.string().optional().describe(
+          "Arquivo ou diretorio onde buscar. Default: diretorio atual."
+        ),
+        format: z.enum(["text", "json"]).default("text").describe(
+          "Formato de saida: text (legivel/diff) ou json (estruturado)"
+        ),
+        cwd: z.string().optional().describe("Diretorio de trabalho")
+      },
+      annotations: {
+        title: "Preview Structural Replacement",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    async (params) => {
+      try {
+        const { result, warnings } = await replacePreview({
+          pattern: params.pattern,
+          rewrite: params.rewrite,
+          lang: params.lang,
+          path: params.path,
+          cwd: params.cwd
+        });
+        const output = params.format === "json" ? formatReplaceJson(result) : formatReplaceText(result, CTX);
+        const warningText = warnings.length > 0 ? `
+\u26A0\uFE0F Avisos:
+${warnings.map((w) => `   \u2022 ${w}`).join("\n")}` : "";
+        return {
+          content: [{ type: "text", text: output + warningText }]
+        };
+      } catch (error) {
+        return handleReplaceError(error, CTX);
+      }
+    }
+  );
+}
+function handleFindError(error, ctx) {
+  if (error instanceof PatternParseError) {
+    return {
+      content: [{
+        type: "text",
+        text: formatPatternError({
+          pattern: error.pattern,
+          lang: error.lang,
+          originalError: error.message,
+          ctx
+        })
+      }],
+      isError: true
+    };
+  }
+  if (error instanceof LanguageNotDetectedError) {
+    return {
+      content: [{
+        type: "text",
+        text: formatLangNotSupported({ input: error.input, ctx })
+      }],
+      isError: true
+    };
+  }
+  const msg = error instanceof Error ? error.message : String(error);
+  return {
+    content: [{
+      type: "text",
+      text: wrapError(msg, "generic", ctx) + "\n" + getCommandReference(ctx)
+    }],
+    isError: true
+  };
+}
+function handleTreeError(error, ctx) {
+  if (error instanceof FileNotFoundError) {
+    return {
+      content: [{
+        type: "text",
+        text: formatFileNotFound({ filePath: error.filePath, ctx })
+      }],
+      isError: true
+    };
+  }
+  if (error instanceof TreeParseError) {
+    return {
+      content: [{
+        type: "text",
+        text: `
+\u274C Erro ao analisar "${error.filePath}": ${error.message}
+${recoveryHint("generic", ctx)}`
+      }],
+      isError: true
+    };
+  }
+  const msg = error instanceof Error ? error.message : String(error);
+  return {
+    content: [{
+      type: "text",
+      text: wrapError(msg, "generic", ctx) + "\n" + getCommandReference(ctx)
+    }],
+    isError: true
+  };
+}
+function handleReplaceError(error, ctx) {
+  if (error instanceof ReplacePatternError) {
+    return {
+      content: [{
+        type: "text",
+        text: formatPatternError({
+          pattern: error.pattern,
+          lang: error.lang,
+          originalError: error.message,
+          ctx
+        })
+      }],
+      isError: true
+    };
+  }
+  if (error instanceof ReplaceLangError) {
+    return {
+      content: [{
+        type: "text",
+        text: formatLangNotSupported({ input: error.input, ctx })
+      }],
+      isError: true
+    };
+  }
+  const msg = error instanceof Error ? error.message : String(error);
+  return {
+    content: [{
+      type: "text",
+      text: wrapError(msg, "generic", ctx) + "\n" + getCommandReference(ctx)
+    }],
+    isError: true
+  };
+}
+
+// src/server.ts
+var VERSION = "0.1.0";
+var server = new McpServer({
+  name: "supergrep-mcp-server",
+  version: VERSION
+});
+registerAllTools(server);
+async function startMcpServer() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error(`[supergrep] MCP server v${VERSION} running via stdio`);
+}
+
+export {
+  startMcpServer
+};