zmarketplace 0.4.2

package/src/index.ts

@@ -0,0 +1,255 @@
+/**
+ * zmarketplace — /zmarketplace slash command for pi/omp.
+ *
+ * Flow: /zmarketplace → type query → browse results → enter → detail+README → install (audit first)
+ */
+
+import { search } from "./core/search.ts";
+import { getDetail } from "./core/detail.ts";
+import { auditPackage } from "./core/audit.ts";
+import { cacheResults, resolveRef, cacheAudit } from "./core/cache.ts";
+import { formatResultOption, formatAuditReport, formatHelp, parseArgs } from "./core/tui.ts";
+import type { PackageResult } from "./core/types.ts";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+interface UI {
+  select(title: string, options: Array<string | { label: string; description?: string }>): Promise<string | undefined>;
+  confirm(title: string, message: string): Promise<boolean>;
+  input(title: string, placeholder?: string): Promise<string | undefined>;
+  notify(message: string, level?: string): void;
+  setStatus?(message: string): void;
+}
+
+interface Ctx { cwd: string; hasUI: boolean; ui: UI }
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function openUrl(url: string): void {
+  if (process.platform === "win32") Bun.spawn(["cmd", "/c", "start", "", url], { stdout: "ignore", stderr: "ignore" });
+  else if (process.platform === "darwin") Bun.spawn(["open", url], { stdout: "ignore", stderr: "ignore" });
+  else Bun.spawn(["xdg-open", url], { stdout: "ignore", stderr: "ignore" });
+}
+
+function extractUrl(line: string, repoBase?: string): string | null {
+  const direct = line.match(/https?:\/\/[^\s)>]+/);
+  if (direct) return direct[0].replace(/[.)]+$/, "");
+  const rel = line.match(/🖼 IMAGE: (.+)/);
+  if (rel && repoBase) return `${repoBase}/raw/main/${rel[1].replace(/^\.\//, "")}`;
+  return null;
+}
+
+// ── Search ─────────────────────────────────────────────────────────────────
+
+async function doSearch(query: string, ctx: Ctx, limit = 50): Promise<void> {
+  ctx.ui.setStatus?.("Searching...");
+  const results = await search({ query, limit, type: "all", ecosystem: "all" });
+  cacheResults(results, query);
+  if (results.length === 0) { ctx.ui.notify("No packages found.", "warning"); return; }
+  ctx.ui.notify(`Found ${results.length} packages.`, "info");
+  await browseResults(results, ctx);
+}
+
+const PAGE_SIZE = 50;
+
+async function browseResults(results: PackageResult[], ctx: Ctx): Promise<void> {
+  let pageStart = 0;
+  while (true) {
+    const pageEnd = Math.min(pageStart + PAGE_SIZE, results.length);
+    const page = results.slice(pageStart, pageEnd);
+
+    const options = page.map((r, i) => {
+      const globalIdx = pageStart + i;
+      return { label: formatResultOption(r, globalIdx).label, description: r.installCommand ?? "" };
+    });
+
+    // Pagination controls
+    if (pageStart > 0) {
+      const prevStart = Math.max(0, pageStart - PAGE_SIZE) + 1;
+      const prevEnd = pageStart;
+      options.push({ label: `← Previous (${prevStart}-${prevEnd})`, description: "" });
+    }
+    if (pageEnd < results.length) {
+      const nextStart = pageEnd + 1;
+      const nextEnd = Math.min(pageEnd + PAGE_SIZE, results.length);
+      options.push({ label: `→ Next (${nextStart}-${nextEnd})`, description: "" });
+    }
+    options.push({ label: "↩ Done", description: "" });
+
+    const title = `zmarketplace: ${results.length} results (page ${Math.floor(pageStart / PAGE_SIZE) + 1}/${Math.ceil(results.length / PAGE_SIZE)})`;
+    const selected = await ctx.ui.select(title, options);
+
+    if (!selected || selected === "↩ Done") return;
+    if (selected.startsWith("← Previous")) { pageStart = Math.max(0, pageStart - PAGE_SIZE); continue; }
+    if (selected.startsWith("→ Next")) { pageStart += PAGE_SIZE; continue; }
+
+    const match = selected.match(/\[(\d+)\]/);
+    if (match) {
+      const pkg = results[parseInt(match[1], 10) - 1];
+      if (pkg) await packageDetail(pkg, ctx);
+    }
+  }
+}
+
+// ── Detail + README ────────────────────────────────────────────────────────
+
+async function packageDetail(pkg: PackageResult, ctx: Ctx): Promise<void> {
+  ctx.ui.setStatus?.(`Loading ${pkg.name}...`);
+  const detail = await getDetail(pkg.name);
+  if (!detail) { ctx.ui.notify(`"${pkg.name}" not found.`, "warning"); return; }
+
+  const repoBase = detail.repository?.replace(/^git\+/, "").replace(/\.git$/, "");
+  const lines: string[] = [
+    "⬇ Install (audit first)",
+    "🔒 Audit only",
+    "↩ Back to results",
+    "━━━ Package ━━━",
+    `📦 ${detail.name} v${detail.version ?? "?"}`,
+    detail.description || "",
+    `License: ${detail.license ?? "?"}  Deps: ${detail.dependencyCount ?? "?"}  Size: ${detail.size ? (detail.size / 1024).toFixed(1) + " KB" : "?"}`,
+    `Published: ${detail.publishedAt?.slice(0, 10) ?? "?"}`,
+  ];
+  if (detail.keywords?.length) lines.push(`Keywords: ${detail.keywords.join(", ")}`);
+  if (detail.npmUrl) lines.push(`🔗 ${detail.npmUrl}`);
+  if (repoBase) lines.push(`🔗 ${repoBase}`);
+
+  if (detail.readme) {
+    lines.push("━━━ README (enter on 🔗/🖼 to open) ━━━");
+    const rl = detail.readme
+      .replace(/!\[.*?\]\((https?:\/\/[^)]+)\)/g, "\n🖼 IMAGE: $1\n")
+      .replace(/!\[.*?\]\(([^)]+)\)/g, (_m, p) => `\n🖼 IMAGE: ${repoBase ? repoBase + "/raw/main/" + p.replace(/^\.\//, "") : p}\n`)
+      .replace(/\[([^\]]+)\]\((https?:\/\/[^)]+)\)/g, "$1 → $2")
+      .replace(/<img[^>]*src=["']([^"']+)["'][^>]*>/gi, (_m, p) => `\n🖼 IMAGE: ${p}\n`)
+      .replace(/<a[^>]*href=["']([^"']+)["'][^>]*>(.*?)<\/a>/gi, "$2 → $1")
+      .replace(/<[^>]+>/g, "")
+      .split("\n").map(l => l.trimEnd()).filter(l => l.length > 0)
+      .slice(0, 150);
+    lines.push(...rl);
+    if (detail.readme.length > 8000) lines.push("...(truncated — see npm for full README)");
+  }
+
+  while (true) {
+    const selected = await ctx.ui.select(`${detail.name} — Details`, lines);
+    if (!selected) continue;  // ESC → stay in detail, don't quit to results
+    if (selected.includes("Back to results")) return;
+    if (selected.includes("Install")) { await doInstall(pkg, ctx); continue; }  // stay in detail after install
+    if (selected.includes("Audit only")) { await doAudit(pkg.name, ctx); continue; }
+    const url = extractUrl(selected, repoBase);
+    if (url) { openUrl(url); ctx.ui.notify("🌐 Opened in browser", "info"); }
+  }
+}
+
+// ── Audit ──────────────────────────────────────────────────────────────────
+
+async function doAudit(name: string, ctx: Ctx): Promise<void> {
+  ctx.ui.setStatus?.(`Auditing ${name}...`);
+  const report = await auditPackage(name, { deepScan: true });
+  cacheAudit(name, report);
+  const lines = [
+    `${report.risk === "safe" ? "✅" : report.risk === "low" ? "🟢" : report.risk === "moderate" ? "🟡" : "🔴"} Risk: ${report.risk.toUpperCase()}`,
+    `Deep scan: ${report.deepScanned ? "yes" : "no"}`,
+    "",
+    report.findings.length === 0 ? "No issues found." : `${report.findings.length} finding(s):`,
+    ...report.findings.slice(0, 20).map(f => `[${f.severity.toUpperCase()}] ${f.reason}${f.file ? ` (${f.file})` : ""}`),
+    "↩ Back",
+  ];
+  await ctx.ui.select(`Audit: ${name}`, lines);
+}
+
+// ── Install (audit FIRST, then options) ────────────────────────────────────
+
+async function doInstall(pkg: PackageResult, ctx: Ctx): Promise<void> {
+  // Audit first
+  ctx.ui.setStatus?.(`Auditing ${pkg.name} before install...`);
+  const report = await auditPackage(pkg.name, { deepScan: true });
+  cacheAudit(pkg.name, report);
+
+  // Show audit results
+  const auditLines = [
+    `${report.risk === "safe" ? "✅" : "🔴"} Risk: ${report.risk.toUpperCase()} (${report.findings.length} findings)`,
+    ...report.findings.slice(0, 10).map(f => `[${f.severity}] ${f.reason}`),
+    "",
+    report.risk === "critical" || report.risk === "high" ? "⚠️ High risk — proceed with caution" : "✅ Safe to install",
+    "",
+  ];
+
+  // Build install options
+  const cmds: Array<{ label: string; description: string }> = [];
+  const seen = new Set<string>();
+  for (const eco of pkg.ecosystems) {
+    if ((eco === "pi" || eco === "omp") && !seen.has("pi")) {
+      seen.add("pi");
+      auditLines.push("🥧 pi install");
+      cmds.push({ label: "🥧 pi install", description: `pi install npm:${pkg.name}` });
+      cmds.push({ label: "⌥ omp install", description: `omp plugin install npm:${pkg.name}` });
+      auditLines.push("⌥ omp install");
+    }
+    if (eco === "claude" && !seen.has("claude")) { seen.add("claude"); cmds.push({ label: "🤖 claude", description: `claude plugin install npm:${pkg.name}` }); auditLines.push("🤖 claude install"); }
+    if (eco === "opencode" && !seen.has("opencode")) { seen.add("opencode"); cmds.push({ label: "🔓 opencode", description: `opencode plugin ${pkg.name}` }); auditLines.push("🔓 opencode install"); }
+    if (eco === "gemini" && !seen.has("gemini")) { seen.add("gemini"); cmds.push({ label: "💎 gemini", description: `gemini extension install ${pkg.repository ?? pkg.name}` }); auditLines.push("💎 gemini install"); }
+    if (eco === "codex" && !seen.has("codex")) { seen.add("codex"); cmds.push({ label: "🔲 codex", description: `codex plugin add npm:${pkg.name}` }); auditLines.push("🔲 codex install"); }
+  }
+  if (!seen.has("npm")) { cmds.push({ label: "📦 npm", description: `npm install ${pkg.name}` }); auditLines.push("📦 npm install"); }
+  cmds.push({ label: "⚡ bunx", description: `bunx ${pkg.name}` });
+  cmds.push({ label: "↩ Cancel", description: "" });
+
+  // High risk confirmation
+  if (report.risk === "critical" || report.risk === "high") {
+    const proceed = await ctx.ui.confirm(`${report.risk} risk`, `⚠️ ${pkg.name}: ${report.findings.length} security findings. Install anyway?`);
+    if (!proceed) { ctx.ui.notify("Cancelled.", "info"); return; }
+  }
+
+  const choice = await ctx.ui.select(`Install ${pkg.name} — Audit: ${report.risk}`, cmds);
+  if (!choice || choice.includes("Cancel")) return;
+  const selected = cmds.find(c => c.label === choice);
+  if (!selected) return;
+  ctx.ui.notify(`✅ Run:\n  ${selected.description}`, "info");
+}
+
+// ── Factory ────────────────────────────────────────────────────────────────
+
+export default function zmarketplace(pi: {
+  registerCommand(name: string, def: { description: string; handler: (args: string, ctx: Ctx) => Promise<void> }): void;
+  setLabel?(label: string): void;
+}) {
+  pi.setLabel?.("Z Marketplace");
+  pi.registerCommand("zmarketplace", {
+    description: "Search, audit, and install packages across agent ecosystems",
+    handler: async (rawArgs: string, ctx: Ctx) => {
+      const args = parseArgs(rawArgs.trim().split(/\s+/).filter(Boolean));
+
+      switch (args.subcommand) {
+        case "help": {
+          ctx.ui.notify(formatHelp(), "info");
+          break;
+        }
+        case "audit":
+        case "a": {
+          const ref = args.positional[0];
+          if (!ref) { ctx.ui.notify("Usage: /zmarketplace audit <name>", "info"); break; }
+          await doAudit(resolveRef(ref)?.name ?? ref, ctx);
+          break;
+        }
+        case "search":
+        case "s":
+        case "": {
+          let query = args.positional.join(" ").trim();
+          let limit = 50;
+          if (!query && ctx.hasUI) {
+            // Choose result limit
+            const limitChoice = await ctx.ui.select("Results limit (50 per page)", ["25", "50", "150", "All (paged — may lag on fetch)"]);
+            limit = limitChoice?.startsWith("All") ? 999999 : parseInt(limitChoice ?? "50", 10);
+            query = (await ctx.ui.input("🔍 Search packages", "Type search query...")) ?? "";
+            if (!query) return;
+          }
+          await doSearch(query, ctx, limit);
+          break;
+        }
+        default: {
+          // Treat unknown as search query
+          await doSearch(rawArgs.trim(), ctx);
+        }
+      }
+    },
+  });
+}

package/src/opencode.ts

@@ -0,0 +1,119 @@
+/**
+ * OpenCode plugin entry point.
+ *
+ * OpenCode plugins are npm packages with `exports["./server"]` pointing here.
+ * They export a Plugin function that returns hooks.
+ *
+ * Install in opencode:
+ *   opencode plugin zmarketplace
+ *
+ * Or add to opencode.json:
+ *   { "plugin": ["zmarketplace"] }
+ */
+
+import { search } from "./core/search.ts";
+import { getDetail } from "./core/detail.ts";
+import { auditPackage } from "./core/audit.ts";
+import { installPackage } from "./core/install.ts";
+import type { SearchOptions } from "./core/types.ts";
+
+/**
+ * Minimal OpenCode plugin type shape.
+ * Not imported from @opencode-ai/plugin to keep zero deps.
+ */
+interface OpenCodeToolContext {
+  sessionID?: string;
+  messageID?: string;
+  agent?: string;
+  directory?: string;
+  ask?(message: string): Promise<string>;
+}
+
+interface OpenCodePluginParams {
+  project?: string;
+  serverUrl?: string;
+  // Bun shell `$`
+  $?: unknown;
+}
+
+interface OpenCodeHooks {
+  "tool.definition"?: (tools: unknown[]) => unknown[];
+}
+
+type PluginFn = (params: OpenCodePluginParams) => Promise<OpenCodeHooks>;
+
+const ZMARKETPLACE_TOOL = {
+  type: "function" as const,
+  function: {
+    name: "zmarketplace",
+    description:
+      "Search, inspect, audit, and install packages across agent ecosystems. " +
+      "Actions: search, detail, audit, install.",
+    parameters: {
+      type: "object",
+      properties: {
+        action: { type: "string", enum: ["search", "detail", "audit", "install"] },
+        query: { type: "string" },
+        name: { type: "string" },
+        type: { type: "string", enum: ["extension", "skill", "theme", "prompt", "plugin", "mcp", "all"] },
+        ecosystem: { type: "string", enum: ["pi", "omp", "claude", "opencode", "gemini", "codex", "all"] },
+        limit: { type: "number" },
+        deepScan: { type: "boolean" },
+        skipAudit: { type: "boolean" },
+      },
+      required: ["action"],
+    },
+    execute: async (args: Record<string, unknown>, _ctx: OpenCodeToolContext): Promise<string> => {
+      const action = args["action"] as string;
+
+      if (action === "search") {
+        const opts: SearchOptions = {
+          query: (args["query"] as string) ?? "",
+          type: (args["type"] as SearchOptions["type"]) ?? "all",
+          ecosystem: (args["ecosystem"] as SearchOptions["ecosystem"]) ?? "all",
+          limit: (args["limit"] as number) ?? 20,
+        };
+        const results = await search(opts);
+        return results.length === 0
+          ? "No packages found."
+          : results.map(r => `${r.name} [${r.ecosystems.filter(e => e !== "unknown").join(",")}] — ${r.description}`).join("\n");
+      }
+
+      if (action === "detail") {
+        const name = args["name"] as string;
+        if (!name) return "Error: 'name' required for detail.";
+        const detail = await getDetail(name);
+        if (!detail) return `Package "${name}" not found.`;
+        return `${detail.name} v${detail.version}\n${detail.description}\nDeps: ${detail.dependencyCount}  Size: ${detail.size ? (detail.size / 1024).toFixed(1) + " KB" : "?"}\n${detail.npmUrl}`;
+      }
+
+      if (action === "audit") {
+        const name = args["name"] as string;
+        if (!name) return "Error: 'name' required for audit.";
+        const report = await auditPackage(name, { deepScan: (args["deepScan"] as boolean) ?? true });
+        return report.summary + "\n" + (report.findings.map(f => `[${f.severity.toUpperCase()}] ${f.reason}`).join("\n") || "No findings.");
+      }
+
+      if (action === "install") {
+        const name = args["name"] as string;
+        if (!name) return "Error: 'name' required for install.";
+        const result = await installPackage(name, { skipAudit: (args["skipAudit"] as boolean) ?? false });
+        return result.message;
+      }
+
+      return `Unknown action: ${action}`;
+    },
+  },
+};
+
+const ZmarketplacePlugin: PluginFn = async (_params: OpenCodePluginParams) => {
+  return {
+    "tool.definition": (tools: unknown[]) => {
+      tools.push(ZMARKETPLACE_TOOL);
+      return tools;
+    },
+  };
+};
+
+export default ZmarketplacePlugin;
+export { ZmarketplacePlugin };

package/src/registries/claude.ts

@@ -0,0 +1,80 @@
+/**
+ * Claude marketplace adapter — fetches plugin catalogs from GitHub raw.
+ * Sources: anthropics/claude-plugins-official + anthropics/claude-plugins-community.
+ */
+
+import type { PackageResult, PackageType, RegistrySource } from "../core/types.ts";
+
+const MARKETPLACE_URLS = [
+  "https://raw.githubusercontent.com/anthropics/claude-plugins-official/main/.claude-plugin/marketplace.json",
+  "https://raw.githubusercontent.com/anthropics/claude-plugins-community/main/.claude-plugin/marketplace.json",
+] as const;
+
+interface MarketplacePlugin {
+  name: string;
+  description?: string;
+  source: string | { source: string; url?: string; repo?: string; ref?: string };
+  version?: string;
+  author?: { name?: string; email?: string } | string;
+  homepage?: string;
+  repository?: string | { url?: string };
+  license?: string;
+  keywords?: string[];
+  category?: string;
+}
+
+interface MarketplaceCatalog {
+  name: string;
+  owner?: { name?: string };
+  plugins: MarketplacePlugin[];
+}
+
+/** Search the Claude marketplace catalogs. */
+export async function searchClaudeMarketplace(query: string, limit = 25): Promise<PackageResult[]> {
+  const catalogs = await Promise.allSettled(
+    MARKETPLACE_URLS.map(async url => {
+      const resp = await fetch(url, { signal: AbortSignal.timeout(10000) });
+      if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
+      return await resp.json() as MarketplaceCatalog;
+    }),
+  );
+
+  const results: PackageResult[] = [];
+  const q = query.toLowerCase().trim();
+
+  for (const settled of catalogs) {
+    if (settled.status !== "fulfilled") continue;
+    for (const plugin of settled.value.plugins) {
+      const name = plugin.name.toLowerCase();
+      const desc = (plugin.description ?? "").toLowerCase();
+      // No query → return all; otherwise match name or description
+      if (q && !name.includes(q) && !desc.includes(q)) continue;
+
+      const repo = typeof plugin.repository === "string"
+        ? plugin.repository
+        : plugin.repository?.url;
+      const author = typeof plugin.author === "string"
+        ? plugin.author
+        : plugin.author?.name;
+
+      results.push({
+        name: plugin.name,
+        description: plugin.description ?? "",
+        version: plugin.version,
+        author,
+        ecosystems: ["claude"],
+        type: (plugin.category === "theme" ? "theme" : "plugin") as PackageType,
+        source: "claude-marketplace" as RegistrySource,
+        homepage: plugin.homepage ?? repo,
+        repository: repo,
+        license: plugin.license,
+        installCommand: `claude plugin install ${plugin.name}`,
+      });
+
+      if (results.length >= limit) break;
+    }
+    if (results.length >= limit) break;
+  }
+
+  return results;
+}

package/src/registries/gemini.ts

@@ -0,0 +1,89 @@
+/**
+ * Gemini CLI extensions adapter — fetches the community-maintained extensions registry.
+ * Source: geminicli.com/extensions.json (~12,000+ extensions crawled from GitHub topics).
+ */
+
+import type { PackageResult, PackageType, RegistrySource } from "../core/types.ts";
+
+const GEMINI_REGISTRY_URL = "https://geminicli.com/extensions.json";
+
+interface GeminiExtension {
+  id?: string;
+  url?: string;
+  fullName?: string;
+  repoDescription?: string;
+  stars?: number;
+  extensionName?: string;
+  extensionVersion?: string;
+  extensionDescription?: string;
+  avatarUrl?: string;
+  hasMCP?: boolean;
+  hasContext?: boolean;
+  hasHooks?: boolean;
+  hasSkills?: boolean;
+  hasCustomCommands?: boolean;
+  isGoogleOwned?: boolean;
+  licenseKey?: string;
+  lastUpdated?: string;
+}
+
+let cachedExtensions: GeminiExtension[] | null = null;
+let cacheTime = 0;
+const CACHE_TTL_MS = 5 * 60 * 1000;
+
+/** Fetch the full Gemini extensions registry (cached for 5 min). */
+async function getRegistry(): Promise<GeminiExtension[]> {
+  const now = Date.now();
+  if (cachedExtensions && now - cacheTime < CACHE_TTL_MS) return cachedExtensions;
+
+  try {
+    const resp = await fetch(GEMINI_REGISTRY_URL, { signal: AbortSignal.timeout(15000) });
+    if (!resp.ok) return cachedExtensions ?? [];
+    const data = await resp.json();
+    cachedExtensions = Array.isArray(data) ? data : [];
+    cacheTime = now;
+    return cachedExtensions;
+  } catch {
+    return cachedExtensions ?? [];
+  }
+}
+
+/** Determine the package type from Gemini extension flags. */
+function geminiType(ext: GeminiExtension): PackageType {
+  if (ext.hasMCP) return "mcp";
+  if (ext.hasSkills) return "skill";
+  return "extension";
+}
+
+/** Search the Gemini CLI extensions registry. */
+export async function searchGeminiExtensions(query: string, limit = 25): Promise<PackageResult[]> {
+  const extensions = await getRegistry();
+  const q = query.toLowerCase().trim();
+
+  const matched = q
+    ? extensions.filter(ext => {
+        const name = (ext.extensionName ?? ext.id ?? "").toLowerCase();
+        const desc = (ext.extensionDescription ?? ext.repoDescription ?? "").toLowerCase();
+        return name.includes(q) || desc.includes(q);
+      })
+    : extensions;
+
+  return matched.slice(0, limit).map(ext => {
+    const repoUrl = ext.url ?? `https://github.com/${ext.fullName ?? ""}`;
+    return {
+      name: ext.extensionName ?? ext.id ?? ext.fullName ?? "unknown",
+      description: ext.extensionDescription ?? ext.repoDescription ?? "",
+      version: ext.extensionVersion,
+      author: ext.fullName?.split("/")[0],
+      ecosystems: ["gemini"],
+      type: geminiType(ext),
+      source: "gemini-extensions" as RegistrySource,
+      homepage: repoUrl,
+      repository: repoUrl,
+      publishedAt: ext.lastUpdated,
+      installCommand: ext.url
+        ? `gemini extension install ${ext.url}`
+        : "gemini extension install <github-url>",
+    };
+  });
+}

package/src/registries/mcp.ts

@@ -0,0 +1,77 @@
+/**
+ * Official MCP Registry adapter — queries registry.modelcontextprotocol.io.
+ * Free, no auth required. Returns MCP server metadata.
+ */
+
+import type { PackageResult, PackageType, RegistrySource } from "../core/types.ts";
+
+const MCP_REGISTRY_URL = "https://registry.modelcontextprotocol.io/v0.1/servers";
+
+interface McpRegistryServer {
+  name?: string;
+  description?: string;
+  repository?: { url?: string; source?: string };
+  version_detail?: { version?: string };
+  authors?: Array<{ name?: string; email?: string }>;
+  homepage?: string;
+  license?: string;
+}
+
+interface McpRegistryResponse {
+  servers?: McpRegistryServer[];
+  next_cursor?: string;
+}
+
+/** Search the official MCP registry. */
+export async function searchMcpRegistry(query: string, limit = 25): Promise<PackageResult[]> {
+  const q = query.toLowerCase().trim();
+  const results: PackageResult[] = [];
+  let cursor: string | undefined;
+
+  // Paginate until we have enough results or run out
+  for (let page = 0; page < 5 && results.length < limit; page++) {
+    const url = cursor
+      ? `${MCP_REGISTRY_URL}?cursor=${encodeURIComponent(cursor)}&limit=100`
+      : `${MCP_REGISTRY_URL}?limit=100`;
+
+    try {
+      const resp = await fetch(url, { signal: AbortSignal.timeout(15000) });
+      if (!resp.ok) break;
+      const data = await resp.json() as McpRegistryResponse;
+      const servers = data.servers ?? [];
+
+      for (const srv of servers) {
+        const name = srv.name ?? "unknown";
+        const desc = srv.description ?? "";
+        // Filter by query
+        if (q && !name.toLowerCase().includes(q) && !desc.toLowerCase().includes(q)) continue;
+
+        const repo = srv.repository?.url ?? srv.repository?.source;
+        const author = srv.authors?.[0]?.name;
+
+        results.push({
+          name,
+          description: desc,
+          version: srv.version_detail?.version,
+          author,
+          ecosystems: ["universal"],
+          type: "mcp" as PackageType,
+          source: "mcp-registry" as RegistrySource,
+          homepage: srv.homepage ?? repo,
+          repository: repo,
+          license: srv.license,
+          installCommand: `npx ${name}`,
+        });
+
+        if (results.length >= limit) break;
+      }
+
+      cursor = data.next_cursor;
+      if (!cursor) break;
+    } catch {
+      break;
+    }
+  }
+
+  return results;
+}