github-search-cli 9.5.0 → 9.6.0

package/dist/cli.js

@@ -501,6 +501,55 @@ function appendPage(url, page, perPage) {
   return u.toString();
 }
 var TRENDING_URL = "https://github.com/trending";
+var TRENDING_LANGUAGES = /* @__PURE__ */ new Set([
+  "c",
+  "c#",
+  "c++",
+  "clojure",
+  "crystal",
+  "css",
+  "dart",
+  "dockerfile",
+  "elixir",
+  "go",
+  "haskell",
+  "html",
+  "java",
+  "javascript",
+  "jupyter-notebook",
+  "kotlin",
+  "lua",
+  "objective-c",
+  "ocaml",
+  "perl",
+  "php",
+  "powershell",
+  "python",
+  "r",
+  "ruby",
+  "rust",
+  "scala",
+  "shell",
+  "solidity",
+  "svelte",
+  "swift",
+  "typescript",
+  "vue",
+  "zig"
+]);
+function trendingLanguageSlug(language) {
+  return language.trim().toLowerCase().replace(/\s+/g, "-");
+}
+function buildTrendingUrl(since, language) {
+  const params = new URLSearchParams();
+  if (since !== "daily") params.set("since", since);
+  if (language) {
+    const slug = trendingLanguageSlug(language);
+    if (TRENDING_LANGUAGES.has(slug)) params.set("language", slug);
+  }
+  const qs = params.toString();
+  return qs ? `${TRENDING_URL}?${qs}` : TRENDING_URL;
+}
 function trendingRepoToRepo(r) {
   return {
     id: 0,
@@ -531,7 +580,7 @@ var TrendingAdapter = class {
   }
   async search(_query, options) {
     const since = options.trendingSince ?? "daily";
-    const url = since === "daily" ? TRENDING_URL : `${TRENDING_URL}?since=${since}`;
+    const url = buildTrendingUrl(since, options.trendingLanguage);
     let res;
     try {
       res = await fetch(url, { headers: { "User-Agent": "ghfind" } });
@@ -560,7 +609,8 @@ var SearchModule = class _SearchModule {
       options.sort,
       String(options.limit),
       String(options.page ?? 1),
-      options.trendingSince ?? "none"
+      options.trendingSince ?? "none",
+      options.trendingLanguage ?? "none"
     );
     const cached2 = _SearchModule.cache.get(cacheKey);
     if (cached2) {
@@ -1315,7 +1365,9 @@ function checkDirs() {
   }
 }
 function printReport() {
+  const noColor = process.env.NO_COLOR !== void 0 || !process.stdout.isTTY;
   const colors2 = (s, n) => {
+    if (noColor) return s;
     const code = n === "PASS" ? "\x1B[32m" : n === "WARN" ? "\x1B[33m" : "\x1B[31m";
     return `${code}${s}\x1B[0m`;
   };
@@ -1376,7 +1428,7 @@ var cached = null;
 function getVersion() {
   if (cached) return cached;
   if (true) {
-    cached = "9.5.0";
+    cached = "9.6.0";
     return cached;
   }
   try {
@@ -2659,6 +2711,10 @@ function buildHelpSections() {
         { keys: "Packages", action: "Switch to npm packages" },
         { keys: "Export", action: "Export results to file" },
         { keys: "Share", action: "Share repo as text" },
+        {
+          keys: "Org profile",
+          action: "Org summary: repos, stars, top languages"
+        },
         { keys: "Topics", action: "Browse GitHub topics" },
         { keys: "Saved", action: "View saved searches" },
         { keys: "Notifs", action: "Check GitHub notifications" },
@@ -5950,6 +6006,715 @@ if (import.meta.main && false) {
   launchBrowser();
 }
 
+// src/agent-skill.ts
+function buildGhfindSkill() {
+  return {
+    name: "ghfind-cli",
+    title: "ghfind CLI for agents",
+    description: "Search GitHub (repos, trending, npm packages, org/user profiles) from the terminal via the `ghfind` command. Use when the user asks to find, compare, or track GitHub repositories or npm packages.",
+    builtin: true,
+    content: `# ghfind \u2014 GitHub search for agents
+
+ghfind searches GitHub from the terminal: repositories, trending, npm
+packages, org/user profiles. This guide covers the non-interactive surface
+only \u2014 ignore anything about a TUI in other docs; agents cannot drive it.
+
+## Search GitHub repositories
+
+    ghfind "QUERY" --json [--limit N] [--sort best-match|stars|updated|forks]
+
+Query language (GitHub search qualifiers):
+  language:Rust stars:>1000 topic:cli org:vercel user:torvalds
+  repo:facebook/react pushed:>2026-01-01 license:mit archived:false
+  "exact phrase" -language:JavaScript        # quotes, negation
+
+Formats: --json | --csv | --markdown | --count | --format urls|names|ssh-urls|clone-commands|ids
+
+## Trending repositories
+
+    ghfind --trending --json [--since daily|weekly|monthly]
+
+## npm packages
+
+    ghfind pkg "QUERY" --json [--limit N] [--sort best-match|score|downloads|name]
+
+## Org & user profiles
+
+    ghfind org vercel --json
+    ghfind user torvalds --json
+
+## Compare repositories
+
+    ghfind --compare owner/a owner/b [--json]
+Compare is text-only; there is no JSON formatter for it yet.
+
+## Deep-dive a repo (languages, contributors, README)
+
+Not exposed on the CLI. Fetch directly instead:
+  curl -s https://api.github.com/repos/OWNER/REPO/languages
+  curl -s https://raw.githubusercontent.com/OWNER/REPO/main/README.md
+
+## Rate limits
+
+60 req/hr unauthenticated, 5,000 with GITHUB_TOKEN (env var or \`ghfind login\`).
+Responses are cached ~5 min, so repeated identical queries are cheap.
+
+## Bookmarking & release tracking
+
+Bookmarks live in ghfind's local state, not GitHub. An agent can read the
+release feed with:
+    ghfind --releases --json
+Marking releases seen and editing bookmarks is a TUI action; skip it.
+
+## Token efficiency
+
+Prefer --count when only the number of results matters, --format names when
+you only need fullNames, and --limit to cap payload size (default 50, max 100).
+`
+  };
+}
+var registry = /* @__PURE__ */ new Map();
+function registerSkill(skill) {
+  registry.set(skill.name, skill);
+}
+function getSkill(name) {
+  return registry.get(name);
+}
+function listSkills() {
+  return [...registry.values()].sort((a, b) => {
+    if (a.builtin !== b.builtin) return a.builtin ? -1 : 1;
+    return a.name.localeCompare(b.name);
+  });
+}
+function ensureBuiltinSkill() {
+  if (!registry.has("ghfind-cli")) {
+    registerSkill(buildGhfindSkill());
+  }
+}
+function formatSkillCatalog() {
+  ensureBuiltinSkill();
+  const lines = listSkills().map(
+    (s) => `  ${s.name.padEnd(16)} ${s.description}`
+  );
+  return [
+    "Available agent skills:",
+    ...lines,
+    "",
+    `Run \`ghfind skill <name>\` to print one (ghfind v${getVersion()}).`
+  ].join("\n");
+}
+
+// src/mcp-server.ts
+var SUPPORTED_PROTOCOL_VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];
+var LATEST_PROTOCOL_VERSION = SUPPORTED_PROTOCOL_VERSIONS[0];
+var JSONRPC_VERSION = "2.0";
+var PARSE_ERROR = -32700;
+var INVALID_REQUEST = -32600;
+var METHOD_NOT_FOUND = -32601;
+var INVALID_PARAMS = -32602;
+var McpToolError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "McpToolError";
+  }
+};
+function resolveToken(state, arg) {
+  if (typeof arg === "string" && arg.trim()) return arg.trim();
+  if (state.token) return state.token;
+  return loadConfig().githubToken ?? process.env.GITHUB_TOKEN;
+}
+function coerceInt(value, fallback, min, max) {
+  const n = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(n)) return fallback;
+  return Math.min(Math.max(Math.trunc(n), min), max);
+}
+function coerceEnum(value, allowed, fallback) {
+  return typeof value === "string" && allowed.includes(value) ? value : fallback;
+}
+var fmtInt = (n) => n.toLocaleString("en-US");
+function truncate(s, max) {
+  return s.length <= max ? s : `${s.slice(0, max - 1)}\u2026`;
+}
+function slimRepo(r) {
+  return {
+    fullName: r.fullName,
+    description: r.description,
+    url: r.url,
+    stars: r.stars,
+    forks: r.forks,
+    language: r.language,
+    topics: r.topics,
+    pushedAt: r.pushedAt,
+    archived: r.archived
+  };
+}
+function formatRepoLines(repos) {
+  return repos.map((r, i) => {
+    const desc = r.description ? ` \u2014 ${truncate(r.description, 100)}` : "";
+    const lang = r.language ? ` [${r.language}]` : "";
+    return `${i + 1}. ${r.fullName} \u2605 ${fmtInt(r.stars)}${lang}${desc}`;
+  }).join("\n");
+}
+function formatPackageLines(pkgs) {
+  return pkgs.map((p, i) => {
+    const desc = p.description ? ` \u2014 ${truncate(p.description, 90)}` : "";
+    return `${i + 1}. ${p.name}@${p.version}${desc} (\u2193 ${fmtInt(p.downloads)}/mo)`;
+  }).join("\n");
+}
+var REPO_NAME_RE = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
+function parseRepoName(input) {
+  const fullName = input.trim().replace(/\.git$/, "").replace(/^@/, "");
+  if (!REPO_NAME_RE.test(fullName)) {
+    throw new McpToolError(
+      `"${input}" is not a repo name \u2014 use owner/name, e.g. facebook/react.`
+    );
+  }
+  const [owner, name] = fullName.split("/");
+  return { owner, name };
+}
+function stubRepo(fullName) {
+  const { owner, name } = parseRepoName(fullName);
+  return {
+    id: 0,
+    fullName: `${owner}/${name}`,
+    name,
+    owner,
+    description: null,
+    url: `https://github.com/${owner}/${name}`,
+    stars: 0,
+    forks: 0,
+    watchers: 0,
+    language: null,
+    topics: [],
+    archived: false,
+    isFork: false,
+    private: false,
+    createdAt: "",
+    updatedAt: "",
+    pushedAt: "",
+    score: 0
+  };
+}
+var TRENDING_QUERY = { keywords: [], qualifiers: [], raw: "trending" };
+var REPO_SORTS = ["best-match", "stars", "updated", "forks"];
+var TRENDING_SINCE = ["daily", "weekly", "monthly"];
+var PKG_SORTS = ["best-match", "score", "downloads", "name"];
+var TOOLS = [
+  {
+    name: "ghfind_search_repos",
+    title: "Search GitHub repositories",
+    description: "Search GitHub repositories with the GitHub search syntax. Supports qualifiers like language:, stars:>1000, topic:, org:, user:, pushed:>2026-01-01, quoted phrases, and -negation. Returns fullNames, stars, languages, descriptions, and URLs.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: 'GitHub search query, e.g. "rust cli stars:>500" or "language:TypeScript topic:mcp".'
+        },
+        limit: {
+          type: "number",
+          description: "Max results, 1-100 (default 20).",
+          minimum: 1,
+          maximum: 100
+        },
+        sort: {
+          type: "string",
+          description: "Sort strategy (default best-match).",
+          enum: [...REPO_SORTS]
+        },
+        token: {
+          type: "string",
+          description: "Optional GitHub token (raises the rate limit from 60/hr to 5,000/hr)."
+        }
+      },
+      required: ["query"]
+    },
+    async run(args, state) {
+      const query = String(args.query ?? "").trim();
+      if (!query) throw new McpToolError("query must be a non-empty string.");
+      const limit = coerceInt(args.limit, 20, 1, 100);
+      const sort = coerceEnum(
+        args.sort,
+        REPO_SORTS,
+        "best-match"
+      );
+      const token = resolveToken(state, args.token);
+      const provider = createGitHubSearch(void 0, token ? [token] : []);
+      const parsed = parseQuery(query);
+      const options = {
+        limit,
+        sort,
+        json: false,
+        verbose: false,
+        token
+      };
+      const response = await provider.search(parsed, options);
+      const repos = rankRepos(response.repos, sort);
+      try {
+        appendHistory({
+          query,
+          mode: "search",
+          timestamp: Date.now(),
+          resultCount: repos.length
+        });
+      } catch {
+      }
+      const text = repos.length === 0 ? `No repositories found for "${query}" (total_count ${response.totalCount}).` : formatRepoLines(repos) + (response.totalCount > repos.length ? `
+
+(${fmtInt(response.totalCount)} total matches; showing ${repos.length}.)` : "");
+      return {
+        text,
+        data: {
+          totalCount: response.totalCount,
+          repos: repos.map(slimRepo),
+          ...response.rateLimited ? { rateLimited: true } : {}
+        }
+      };
+    }
+  },
+  {
+    name: "ghfind_trending",
+    title: "Trending GitHub repositories",
+    description: "List repositories trending on GitHub today, this week, or this month, optionally filtered by language. Uses github.com/trending, so results carry stars-today momentum the Search API cannot provide.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        since: {
+          type: "string",
+          description: "Trending period (default daily).",
+          enum: [...TRENDING_SINCE]
+        },
+        language: {
+          type: "string",
+          description: 'Optional language filter slug, e.g. "rust", "python", "typescript".'
+        },
+        limit: {
+          type: "number",
+          description: "Max results, 1-50 (default 25).",
+          minimum: 1,
+          maximum: 50
+        },
+        token: { type: "string", description: "Optional GitHub token." }
+      }
+    },
+    async run(args, state) {
+      const since = coerceEnum(args.since, TRENDING_SINCE, "daily");
+      const limit = coerceInt(args.limit, 25, 1, 50);
+      const token = resolveToken(state, args.token);
+      let language;
+      const langArg = typeof args.language === "string" ? args.language.trim() : "";
+      if (langArg) {
+        const slug = trendingLanguageSlug(langArg);
+        if (!TRENDING_LANGUAGES.has(slug)) {
+          throw new McpToolError(
+            `"${langArg}" is not a trending language filter. Try one of: rust, python, typescript, javascript, go, zig.`
+          );
+        }
+        language = slug;
+      }
+      const trending = createTrendingSearch();
+      const options = {
+        limit,
+        sort: "stars",
+        json: false,
+        verbose: false,
+        trendingSince: since,
+        ...language ? { trendingLanguage: language } : {},
+        token
+      };
+      const response = await trending.search(TRENDING_QUERY, options);
+      const repos = response.repos.slice(0, limit);
+      const text = repos.length === 0 ? `No trending repositories returned (${since}${language ? `, ${language}` : ""}).` : formatRepoLines(repos);
+      return {
+        text,
+        data: {
+          since,
+          ...language ? { language } : {},
+          repos: repos.map(slimRepo)
+        }
+      };
+    }
+  },
+  {
+    name: "ghfind_npm_packages",
+    title: "Search npm packages",
+    description: "Search the npm registry: name, version, monthly downloads, quality score, and description for each package.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: 'Package search text, e.g. "terminal ui".'
+        },
+        limit: {
+          type: "number",
+          description: "Max results, 1-100 (default 20).",
+          minimum: 1,
+          maximum: 100
+        },
+        sort: {
+          type: "string",
+          description: "Sort strategy (default best-match).",
+          enum: [...PKG_SORTS]
+        }
+      },
+      required: ["query"]
+    },
+    async run(args) {
+      const query = String(args.query ?? "").trim();
+      if (!query) throw new McpToolError("query must be a non-empty string.");
+      const limit = coerceInt(args.limit, 20, 1, 100);
+      const sort = coerceEnum(
+        args.sort,
+        PKG_SORTS,
+        "best-match"
+      );
+      const { totalCount, packages } = await createPackageSearch().searchPackage(query, limit);
+      const sorted = sortPackages(packages, sort);
+      const text = sorted.length === 0 ? `No npm packages found for "${query}".` : formatPackageLines(sorted);
+      return { text, data: { totalCount, packages: sorted } };
+    }
+  },
+  {
+    name: "ghfind_org_profile",
+    title: "GitHub org profile",
+    description: "Aggregate profile for a GitHub organization: repo count, total stars/forks of fetched repos, top languages, top repos by stars, and recently active repos.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        org: { type: "string", description: 'Org login, e.g. "vercel".' },
+        limit: {
+          type: "number",
+          description: "How many repos to aggregate, 1-500 (default 100).",
+          minimum: 1,
+          maximum: 500
+        },
+        token: { type: "string", description: "Optional GitHub token." }
+      },
+      required: ["org"]
+    },
+    async run(args, state) {
+      const org = String(args.org ?? "").trim();
+      if (!org) throw new McpToolError("org must be a non-empty string.");
+      const limit = coerceInt(args.limit, 100, 1, 500);
+      const profile = await fetchOrgProfile(org, {
+        token: resolveToken(state, args.token),
+        limit
+      });
+      return { text: formatOrgText(profile), data: { ...profile } };
+    }
+  },
+  {
+    name: "ghfind_user_profile",
+    title: "GitHub user profile",
+    description: "Aggregate profile for a GitHub user: repo count, total stars/forks, followers, top languages, top repos, and recently active repos.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        user: { type: "string", description: 'GitHub login, e.g. "torvalds".' },
+        limit: {
+          type: "number",
+          description: "How many repos to aggregate, 1-500 (default 100).",
+          minimum: 1,
+          maximum: 500
+        },
+        token: { type: "string", description: "Optional GitHub token." }
+      },
+      required: ["user"]
+    },
+    async run(args, state) {
+      const user = String(args.user ?? "").trim();
+      if (!user) throw new McpToolError("user must be a non-empty string.");
+      const limit = coerceInt(args.limit, 100, 1, 500);
+      const profile = await fetchUserProfile(user, {
+        token: resolveToken(state, args.token),
+        limit
+      });
+      return { text: formatUserJson(profile), data: { ...profile } };
+    }
+  },
+  {
+    name: "ghfind_compare_repos",
+    title: "Compare GitHub repositories",
+    description: "Fetch 2-5 repositories and return a side-by-side comparison (stars, forks, language, age, topics, descriptions).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        repos: {
+          type: "array",
+          description: 'Repo fullNames to compare, e.g. ["oven-sh/bun", "nodejs/node"].',
+          items: { type: "string" },
+          minItems: 2,
+          maxItems: 5
+        },
+        token: { type: "string", description: "Optional GitHub token." }
+      },
+      required: ["repos"]
+    },
+    async run(args, state) {
+      const names = Array.isArray(args.repos) ? args.repos.map((r) => String(r)) : [];
+      if (names.length < 2 || names.length > 5) {
+        throw new McpToolError("repos must contain 2-5 repo fullNames.");
+      }
+      const token = resolveToken(state, args.token);
+      const provider = createGitHubSearch(void 0, token ? [token] : []);
+      const found = [];
+      const missing = [];
+      for (const fullName of names) {
+        const res = await provider.search(parseQuery(fullName), {
+          limit: 1,
+          sort: "stars",
+          json: false,
+          verbose: false,
+          token
+        });
+        if (res.repos.length > 0) found.push(res.repos[0]);
+        else missing.push(fullName);
+      }
+      if (found.length < 2) {
+        throw new McpToolError(
+          `Could not resolve enough repos to compare (found ${found.length}${missing.length ? `; not found: ${missing.join(", ")}` : ""}).`
+        );
+      }
+      const text = buildComparisonTable(found) + (missing.length ? `
+
+Not found: ${missing.join(", ")}` : "");
+      return { text, data: { repos: found.map(slimRepo) } };
+    }
+  },
+  {
+    name: "ghfind_deep_dive",
+    title: "GitHub repo deep-dive",
+    description: "Rich detail for one repository: language breakdown (bytes), top contributors, and a README excerpt.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        repo: {
+          type: "string",
+          description: 'Repo fullName, e.g. "facebook/react".'
+        },
+        token: { type: "string", description: "Optional GitHub token." }
+      },
+      required: ["repo"]
+    },
+    async run(args, state) {
+      const repo = String(args.repo ?? "").trim();
+      if (!repo) throw new McpToolError("repo must be a non-empty string.");
+      const stub = stubRepo(repo);
+      const data = await fetchDeepDive(stub, resolveToken(state, args.token));
+      return { text: buildDeepDiveText(data), data: { ...data } };
+    }
+  },
+  {
+    name: "ghfind_bookmarked_releases",
+    title: "Bookmarked repo releases",
+    description: "The cached release feed for the user's ghfind bookmarks (read-only). Run `ghfind --releases` in a terminal first to refresh the cache.",
+    inputSchema: { type: "object", properties: {} },
+    async run() {
+      const releases = allCachedReleases();
+      const bookmarkCount = getBookmarks().length;
+      const text = releases.length === 0 ? bookmarkCount === 0 ? "No bookmarks yet. Bookmark repos in the ghfind TUI (Space \u2192 Bookmark)." : `${bookmarkCount} bookmarks, no cached releases. Run \`ghfind --releases\` in a terminal to refresh.` : releases.map(
+        (r) => `${r.fullName} ${r.tagName}${r.prerelease ? " [pre]" : ""} \u2014 ${r.publishedAt.slice(0, 10)}
+  ${r.url}`
+      ).join("\n");
+      return {
+        text,
+        data: {
+          bookmarkCount,
+          releases: releases.map((r) => ({ ...r }))
+        }
+      };
+    }
+  },
+  {
+    name: "ghfind_skill",
+    title: "ghfind CLI usage guide for agents",
+    description: "Print a token-efficient guide to running ghfind directly in a shell (search syntax, flags, rate limits, token-efficiency tips). Prefer this over parsing --help output.",
+    inputSchema: { type: "object", properties: {} },
+    async run() {
+      ensureBuiltinSkill();
+      const skill = getSkill("ghfind-cli");
+      return {
+        text: skill?.content ?? "ghfind skill unavailable.",
+        data: { name: "ghfind-cli" }
+      };
+    }
+  }
+];
+function toolSummaries() {
+  return TOOLS.map((t3) => ({
+    name: t3.name,
+    title: t3.title,
+    description: t3.description,
+    inputSchema: t3.inputSchema
+  }));
+}
+function respond(id, result) {
+  return JSON.stringify({ jsonrpc: JSONRPC_VERSION, id, result });
+}
+function respondError(id, code, message, data) {
+  return JSON.stringify({
+    jsonrpc: JSONRPC_VERSION,
+    id,
+    error: { code, message, ...data !== void 0 ? { data } : {} }
+  });
+}
+function findTool(name) {
+  return TOOLS.find((t3) => t3.name === name);
+}
+async function callTool(name, args, state) {
+  const tool = findTool(name);
+  if (!tool) throw new McpToolError(`Unknown tool: ${name}`);
+  try {
+    return await tool.run(args, state);
+  } catch (err) {
+    if (err instanceof McpToolError) throw err;
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new McpToolError(`ghfind ${name} failed: ${msg}`);
+  }
+}
+async function processServerLine(line, state, config) {
+  let msg;
+  try {
+    msg = JSON.parse(line);
+  } catch {
+    config.write(respondError(null, PARSE_ERROR, "Parse error"));
+    return;
+  }
+  if (typeof msg !== "object" || msg === null || typeof msg.method !== "string") {
+    config.write(respondError(null, INVALID_REQUEST, "Invalid Request"));
+    return;
+  }
+  const isNotification = msg.id === void 0 || msg.id === null;
+  const id = isNotification ? null : msg.id;
+  if (msg.method === "notifications/initialized") {
+    state.initialized = true;
+    return;
+  }
+  if (isNotification) return;
+  if (!state.initialized && msg.method !== "initialize" && msg.method !== "ping") {
+    config.write(
+      respondError(
+        id,
+        INVALID_REQUEST,
+        `Server not initialized \u2014 send "initialize" first (method was "${msg.method}").`
+      )
+    );
+    return;
+  }
+  switch (msg.method) {
+    case "initialize": {
+      const requested = String(msg.params?.protocolVersion ?? "");
+      const negotiated = SUPPORTED_PROTOCOL_VERSIONS.includes(requested) ? requested : LATEST_PROTOCOL_VERSION;
+      state.initialized = true;
+      config.write(
+        respond(id, {
+          protocolVersion: negotiated,
+          capabilities: { tools: { listChanged: false } },
+          serverInfo: {
+            name: "ghfind",
+            title: "ghfind \u2014 GitHub search for agents",
+            version: getVersion()
+          },
+          instructions: "ghfind gives agents GitHub search: repositories, trending, npm packages, org/user profiles, repo comparison and deep-dives. Call ghfind_skill for the full CLI guide. Unauthenticated requests are rate-limited to 60/hr; pass a token or set GITHUB_TOKEN for 5,000/hr."
+        })
+      );
+      return;
+    }
+    case "ping": {
+      config.write(respond(id, {}));
+      return;
+    }
+    case "tools/list": {
+      config.write(respond(id, { tools: toolSummaries() }));
+      return;
+    }
+    case "tools/call": {
+      const name = String(msg.params?.name ?? "");
+      const tool = findTool(name);
+      if (!tool) {
+        config.write(respondError(id, INVALID_PARAMS, `Unknown tool: ${name}`));
+        return;
+      }
+      const rawArgs = msg.params?.arguments;
+      const args = typeof rawArgs === "object" && rawArgs !== null ? rawArgs : {};
+      try {
+        const outcome = await callTool(name, args, state);
+        config.write(
+          respond(id, {
+            content: [{ type: "text", text: outcome.text }],
+            ...outcome.data ? { structuredContent: outcome.data } : {},
+            isError: false
+          })
+        );
+      } catch (err) {
+        const message = err instanceof McpToolError ? err.message : `ghfind tool "${name}" failed: ${err instanceof Error ? err.message : String(err)}`;
+        config.write(
+          respond(id, {
+            content: [{ type: "text", text: message }],
+            isError: true
+          })
+        );
+      }
+      return;
+    }
+    default: {
+      config.write(
+        respondError(id, METHOD_NOT_FOUND, `Method not found: ${msg.method}`)
+      );
+    }
+  }
+}
+function writeStdout(line) {
+  process.stdout.write(line + "\n");
+}
+async function runMcpServer(options = {}) {
+  const state = {
+    initialized: false,
+    ...options.token ? { token: options.token } : {}
+  };
+  const config = { write: writeStdout };
+  let pending = 0;
+  let stdinClosed = false;
+  let shutdownTimer;
+  const maybeExit = () => {
+    if (!stdinClosed || pending > 0) return;
+    process.exit(0);
+  };
+  process.stdin.setEncoding("utf8");
+  let buffer = "";
+  process.stdin.on("data", (chunk) => {
+    buffer += chunk;
+    let idx;
+    while ((idx = buffer.indexOf("\n")) >= 0) {
+      const line = buffer.slice(0, idx).trim();
+      buffer = buffer.slice(idx + 1);
+      if (!line) continue;
+      pending++;
+      void processServerLine(line, state, config).finally(() => {
+        pending--;
+        if (shutdownTimer) {
+          clearTimeout(shutdownTimer);
+          shutdownTimer = void 0;
+        }
+        maybeExit();
+      });
+    }
+  });
+  const close = () => {
+    stdinClosed = true;
+    if (pending === 0) {
+      process.exit(0);
+      return;
+    }
+    shutdownTimer = setTimeout(() => process.exit(0), 3e4);
+  };
+  process.stdin.on("end", close);
+  process.stdin.on("error", close);
+  await new Promise(() => {
+  });
+}
+
 // src/cli.ts
 process.env.GHFIND_CLI_RUN = "1";
 var __dirname3 = dirname4(fileURLToPath4(import.meta.url));
@@ -5976,7 +6741,8 @@ function parseArgs(args) {
     pkg: false,
     registry: "npm",
     compare: [],
-    doctor: false
+    doctor: false,
+    mcp: false
   };
   let queryParts = [];
   for (let i = 0; i < args.length; i++) {
@@ -6055,6 +6821,19 @@ function parseArgs(args) {
       case "--completion":
         flags.completion = args[++i];
         break;
+      case "mcp":
+        flags.mcp = true;
+        break;
+      case "skill": {
+        const next = args[i + 1];
+        if (next && !next.startsWith("-")) {
+          flags.skill = next;
+          i++;
+        } else {
+          flags.skill = "";
+        }
+        break;
+      }
       case "org": {
         const parts = [];
         while (i + 1 < args.length && !args[i + 1].startsWith("-")) {
@@ -6114,12 +6893,13 @@ Usage:
   ghfind <query> --pipe <target>   Pipe to clone/open
   ghfind --trending --json         Trending repos as JSON
   ghfind --releases                Check bookmarks for new releases
-  ghfind --compare <repo1> <repo2> Compare two+ repos side-by-side
+  ghfind --compare <r1> <r2>       Compare two+ repos side-by-side
   ghfind org <name> --json         Org profile: repos, stars, top languages
   ghfind user <name> --json        User profile: repos, stars, top languages
-  ghfind user <name> --json        User profile: repos, stars, top languages
-  ghfind pkg <query> --json         Search npm packages, output JSON
-  ghfind pkg <query>                Search npm packages, text list
+  ghfind pkg <query> --json        Search npm packages, output JSON
+  ghfind pkg <query>               Search npm packages, text list
+  ghfind mcp                       Run the MCP server for AI agents (stdio)
+  ghfind skill [name]              Print the agent skill guide (or catalog)
   ghfind --watch <query>           Watch mode (poll every Ns)
   ghfind init                      Run setup wizard
   ghfind login                     Import the gh CLI token or paste one
@@ -6168,6 +6948,14 @@ Options:
     await runLoginWizard();
     return;
   }
+  if (flags.mcp) {
+    await runMcpServer({ token: flags.token });
+    return;
+  }
+  if (flags.skill !== void 0) {
+    printAgentSkill(flags.skill);
+    return;
+  }
   if (flags.pkg) {
     const interactive = !flags.query && !flags.json && !flags.csv && !flags.markdown && !flags.count && !flags.format;
     if (interactive) {
@@ -6205,6 +6993,21 @@ function buildSearchContext(flags) {
     provider: createGitHubSearch(void 0, flags.token ? [flags.token] : [])
   };
 }
+function printAgentSkill(name) {
+  ensureBuiltinSkill();
+  if (!name) {
+    console.log(formatSkillCatalog());
+    return;
+  }
+  const skill = getSkill(name);
+  if (!skill) {
+    console.error(
+      `Unknown skill: ${name}. Available: ${listSkills().map((s) => s.name).join(", ")}`
+    );
+    process.exit(1);
+  }
+  console.log(skill.content);
+}
 async function runUserProfile(flags, outputFormat) {
   try {
     const profile = await fetchUserProfile(flags.user, {
@@ -6254,14 +7057,14 @@ async function runPackageSearch(flags) {
     console.error(`Registry "${flags.registry}" not yet supported (only npm).`);
     process.exit(1);
   }
-  const PKG_SORTS = [
+  const PKG_SORTS2 = [
     "best-match",
     "score",
     "downloads",
     "name"
   ];
   const pkgSort = flags.sort;
-  if (!PKG_SORTS.includes(pkgSort)) {
+  if (!PKG_SORTS2.includes(pkgSort)) {
     console.error(
       `Invalid sort for pkg: "${flags.sort}" (use best-match|score|downloads|name).`
     );