skillmds 1.0.12 → 1.0.14

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to `skillmds` are documented here. Versions follow [semver](https://semver.org).
 
+## 1.0.14
+
+- Interactive menu (`skillmds` in a terminal) no longer exits after one action — it returns to the menu until you pick **Quit**; cancelling a sub-prompt goes back to the menu instead of quitting.
+- "List installed skills" now shows project **and** global skills together, tagged `[agent/scope]`, replacing the misleading "Include global skills?" prompt (which actually toggled global-only vs project-only). Invalid skills show the parse reason.
+- The in-menu command reference now includes `info`.
+
+## 1.0.13
+
+Safe & easy installs release.
+
+- **Packs install their full file tree.** `skillmd add owner/pack` now downloads the pack's source directory (pinned to the registry's commit; falls back to the default branch with a warning if the pin is gone upstream), so `assets/` and `references/` files referenced by SKILL.md actually exist. Hardened: symlinks are skipped, 200-file/20MB caps, temp dirs cleaned up.
+- **Unverified skills prompt instead of hard-blocking.** Interactive installs show the lint score and security flags and ask before installing; non-interactive installs (and `-y`) still require the explicit `--allow-unverified`. Blocked output links the skill's page for review.
+- **New `skillmd info <slug>`** shows verification status, security flags, rating, provenance (source repo @ commit), and the install snippet. Unknown subcommands now print a proper error instead of silently starting the MCP server.
+- **MCP `skillmd_install` gained the CLI's safety gates**: refuses unverified skills unless `allow_unverified: true` (only after explicit human approval), validates before writing, reports security flags, and guards against malformed skill names.
+- **Installs are exact.** The registry now stores the published SKILL.md verbatim (`raw_md`) and installs deliver it byte-for-byte; reconstructed frontmatter (legacy rows) is YAML-quoted so descriptions with `:`/`#`/quotes can't corrupt the file.
+- Description limit aligned with Claude Code's real spec (1024 chars, was 500) — valid skills are no longer flagged "(invalid SKILL.md)" by `skillmd list`, and `list` now says *why* a file is invalid.
+
+## 1.0.12
+
+- Registry-native `skillmd` CLI shipped inside `skillmds`: `search`, `add`, `list`, `remove`, `update`, `publish`, `login`/`logout`, plus lint/scan/rules/init. (Release notes added retroactively.)
+
 ## 1.0.11
 
 - Security flags render with full readable labels, each with its own marker: `⚑ Executes Scripts  ⚑ Calls Network  ⚑ Reads Secrets`.

package/bin/skillmd-mcp.mjs

@@ -1,232 +1,253 @@
-#!/usr/bin/env node
-// SkillMD MCP server (stdio). Wraps the public SkillMD API so any MCP-capable agent
-// can search, fetch, install, and discover Agent Skills by name or task.
-//
-//   claude mcp add skillmd -- npx -y skillmds
-//
-// Env:
-//   SKILLMD_API   override API base (default https://api.skillmd.com)
-//   SKILLMD_TOKEN  personal access token (enables skillmd_list_saved / personalized recommend)
-
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
-import { mkdir, writeFile } from "node:fs/promises";
-import { readFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join, resolve } from "node:path";
-
-const VERSION = (() => {
-  try {
-    return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
-  } catch {
-    return "0.0.0";
-  }
-})();
-// Shared validation engine, bundled into ./vendor at publish time (npm run build).
-// Falls back gracefully if the vendor build is absent (e.g. running from source).
-let lint = null;
-try {
-  ({ lint } = await import("../vendor/index.js"));
-} catch {
-  /* skillmd_lint will report that validation is unavailable */
-}
-
-const API = process.env.SKILLMD_API || "https://api.skillmd.com";
-const TOKEN = process.env.SKILLMD_TOKEN || "";
-
-async function api(path, init = {}) {
-  const headers = { accept: "application/json", ...(init.headers || {}) };
-  if (TOKEN) headers.authorization = `Bearer ${TOKEN}`;
-  const res = await fetch(API + path, { ...init, headers });
-  if (!res.ok) throw new Error(`SkillMD API ${res.status} on ${path}: ${await res.text().catch(() => "")}`);
-  return res.json();
-}
-const text = (obj) => ({ content: [{ type: "text", text: typeof obj === "string" ? obj : JSON.stringify(obj, null, 2) }] });
-
-const TOOLS = [
-  {
-    name: "skillmd_search",
-    description: "Search SkillMD for Agent Skills by name, description, or task. Returns matching skills with ratings and install snippets.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        query: { type: "string", description: "Natural-language query or keywords" },
-        category: { type: "string", description: "Filter by category slug (e.g. devops, data, security)" },
-        verified_only: { type: "boolean", description: "Only verified skills" },
-        type: { type: "string", enum: ["single", "pack"], description: "single file or pack" },
-        min_rating: { type: "number", description: "Minimum average rating 0-5" },
-        limit: { type: "number", description: "Max results (default 20)" },
-      },
-      required: ["query"],
-    },
-  },
-  {
-    name: "skillmd_get",
-    description: "Fetch a single skill by slug (owner/name), including its SKILL.md body, provenance, license and security flags.",
-    inputSchema: { type: "object", properties: { slug: { type: "string", description: "owner/name, e.g. anthropic/pdf" } }, required: ["slug"] },
-  },
-  {
-    name: "skillmd_install",
-    description: "Install a skill by slug: writes its SKILL.md into the agent's skills directory. Never executes any scripts.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        slug: { type: "string", description: "owner/name, e.g. anthropic/pdf" },
-        dest: { type: "string", description: "Target skills dir. Default ~/.claude/skills" },
-      },
-      required: ["slug"],
-    },
-  },
-  {
-    name: "skillmd_trending",
-    description: "Top skills on the SkillMD leaderboard. range: '30d' or 'all'.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        range: { type: "string", enum: ["30d", "all"], description: "Time window (default all)" },
-        category: { type: "string", description: "Optional category slug" },
-        limit: { type: "number", description: "Max results (default 20)" },
-      },
-    },
-  },
-  {
-    name: "skillmd_recommend",
-    description: "Recommend skills. If based_on is given, suggests skills similar to it (same category); otherwise returns trending.",
-    inputSchema: {
-      type: "object",
-      properties: { based_on: { type: "string", description: "A slug to base recommendations on" }, limit: { type: "number" } },
-    },
-  },
-  {
-    name: "skillmd_list_saved",
-    description: "List the signed-in user's saved skills. Requires SKILLMD_TOKEN to be set.",
-    inputSchema: { type: "object", properties: {} },
-  },
-  {
-    name: "skillmd_lint",
-    description:
-      "Validate a SKILL.md against the SkillMD spec and return diagnostics, security flags, and a quality score (0-100). Pass raw SKILL.md content, or a registry slug (owner/name) to fetch and lint.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        content: { type: "string", description: "Raw SKILL.md content to validate" },
-        slug: { type: "string", description: "Registry slug owner/name to fetch and validate" },
-      },
-    },
-  },
-];
-
-function reconstructSkillMd(skill) {
-  const fm = ["---", `name: ${skill.slug.split("/")[1] || skill.title}`, `description: ${String(skill.description).replace(/\n/g, " ")}`];
-  if (skill.license) fm.push(`license: ${skill.license}`);
-  fm.push("---", "");
-  return fm.join("\n") + (skill.body_md || "");
-}
-
-async function handleCall(name, args) {
-  switch (name) {
-    case "skillmd_search": {
-      const p = new URLSearchParams({ q: args.query, limit: String(args.limit ?? 20) });
-      if (args.category) p.set("category", args.category);
-      if (args.verified_only) p.set("verified", "true");
-      if (args.type) p.set("type", args.type);
-      if (args.min_rating != null) p.set("min_rating", String(args.min_rating));
-      const r = await api(`/api/search?${p}`);
-      return text(r.items ?? []);
-    }
-    case "skillmd_get": {
-      const [owner, slugName] = String(args.slug).split("/");
-      const r = await api(`/api/skills/${owner}/${slugName}`);
-      return text(r);
-    }
-    case "skillmd_trending": {
-      const p = new URLSearchParams({ range: args.range ?? "all", limit: String(args.limit ?? 20) });
-      if (args.category) p.set("category", args.category);
-      const r = await api(`/api/leaderboard?${p}`);
-      return text(r.items ?? []);
-    }
-    case "skillmd_recommend": {
-      if (args.based_on) {
-        const [owner, slugName] = String(args.based_on).split("/");
-        const base = await api(`/api/skills/${owner}/${slugName}`).catch(() => null);
-        if (base?.category_slug) {
-          const r = await api(`/api/leaderboard?range=all&limit=${args.limit ?? 10}&category=${base.category_slug}`);
-          return text((r.items ?? []).filter((s) => s.slug !== args.based_on));
-        }
-      }
-      const r = await api(`/api/leaderboard?range=30d&limit=${args.limit ?? 10}`);
-      return text(r.items ?? []);
-    }
-    case "skillmd_list_saved": {
-      if (!TOKEN) return text("Set SKILLMD_TOKEN (a SkillMD personal access token) to list your saved skills.");
-      const r = await api(`/api/favorites`);
-      return text(r.items ?? []);
-    }
-    case "skillmd_lint": {
-      if (!lint) return text("Validation engine unavailable — run `npm run build` in the skillmds package.");
-      let raw = args.content;
-      let slug;
-      if (!raw && args.slug) {
-        const [owner, slugName] = String(args.slug).split("/");
-        const skill = await api(`/api/skills/${owner}/${slugName}`);
-        raw = reconstructSkillMd(skill);
-        slug = slugName;
-      }
-      if (!raw) return text("Provide `content` (raw SKILL.md) or `slug` (owner/name).");
-      const result = lint(raw, slug ? { slug } : {});
-      return text({ ok: result.ok, score: result.score, diagnostics: result.diagnostics, security: result.security });
-    }
-    case "skillmd_install": {
-      const [owner, slugName] = String(args.slug).split("/");
-      const skill = await api(`/api/skills/${owner}/${slugName}`);
-      const baseDir = args.dest ? resolve(args.dest) : join(homedir(), ".claude", "skills");
-      const dir = join(baseDir, slugName);
-      await mkdir(dir, { recursive: true });
-      const file = join(dir, "SKILL.md");
-      await writeFile(file, reconstructSkillMd(skill), "utf8");
-      api(`/api/skills/${owner}/${slugName}/install`, { method: "POST", body: JSON.stringify({ via: "mcp" }) }).catch(() => {});
-      const note = skill.type === "pack"
-        ? " (pack assets are not bundled yet — only SKILL.md was written)"
-        : "";
-      return text(`Installed ${args.slug} → ${file}${note}`);
-    }
-    default:
-      throw new Error(`Unknown tool: ${name}`);
-  }
-}
-
-async function startMcpServer() {
-  const server = new Server({ name: "skillmd", version: VERSION }, { capabilities: { tools: {} } });
-  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
-  server.setRequestHandler(CallToolRequestSchema, async (req) => {
-    try {
-      return await handleCall(req.params.name, req.params.arguments ?? {});
-    } catch (e) {
-      return { isError: true, content: [{ type: "text", text: String(e?.message || e) }] };
-    }
-  });
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
-  console.error("skillmd MCP server running (stdio)");
-}
-
-// This binary is invoked three ways:
-//   - `skillmds lint .` etc.      → run the CLI (so `npx skillmds <cmd>` works without -p)
-//   - `skillmds` in a terminal    → run the CLI (opens the interactive menu)
-//   - `skillmds` over piped stdio → start the MCP server (how MCP clients launch it)
-// MCP clients always connect stdin as a pipe (never a TTY), so an interactive
-// stdin is a reliable signal that a human is present.
-const CLI_COMMANDS = new Set([
-  "lint", "check", "scan", "rules", "init", "search", "add", "list", "ls",
-  "remove", "rm", "update", "publish", "submit", "login", "logout", "help",
-  "--help", "-h", "--version", "-V",
-]);
-const first = process.argv[2];
-const isCliCommand = first && CLI_COMMANDS.has(first);
-const humanInTerminal = !first && process.stdin.isTTY;
-if (isCliCommand || humanInTerminal) {
-  await import("../dist/cli.js"); // the CLI parses process.argv itself
-} else {
-  await startMcpServer();
-}
+#!/usr/bin/env node
+// SkillMD MCP server (stdio). Wraps the public SkillMD API so any MCP-capable agent
+// can search, fetch, install, and discover Agent Skills by name or task.
+//
+//   claude mcp add skillmd -- npx -y skillmds
+//
+// Env:
+//   SKILLMD_API   override API base (default https://api.skillmd.com)
+//   SKILLMD_TOKEN  personal access token (enables skillmd_list_saved / personalized recommend)
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { mkdir, writeFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { stringify as stringifyYaml } from "yaml";
+
+const VERSION = (() => {
+  try {
+    return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+  } catch {
+    return "0.0.0";
+  }
+})();
+// Shared validation engine, bundled into ./vendor at publish time (npm run build).
+// Falls back gracefully if the vendor build is absent (e.g. running from source).
+let lint = null;
+try {
+  ({ lint } = await import("../vendor/index.js"));
+} catch {
+  /* skillmd_lint will report that validation is unavailable */
+}
+
+const API = process.env.SKILLMD_API || "https://api.skillmd.com";
+const TOKEN = process.env.SKILLMD_TOKEN || "";
+
+async function api(path, init = {}) {
+  const headers = { accept: "application/json", ...(init.headers || {}) };
+  if (TOKEN) headers.authorization = `Bearer ${TOKEN}`;
+  const res = await fetch(API + path, { ...init, headers });
+  if (!res.ok) throw new Error(`SkillMD API ${res.status} on ${path}: ${await res.text().catch(() => "")}`);
+  return res.json();
+}
+const text = (obj) => ({ content: [{ type: "text", text: typeof obj === "string" ? obj : JSON.stringify(obj, null, 2) }] });
+
+const TOOLS = [
+  {
+    name: "skillmd_search",
+    description: "Search SkillMD for Agent Skills by name, description, or task. Returns matching skills with ratings and install snippets.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Natural-language query or keywords" },
+        category: { type: "string", description: "Filter by category slug (e.g. devops, data, security)" },
+        verified_only: { type: "boolean", description: "Only verified skills" },
+        type: { type: "string", enum: ["single", "pack"], description: "single file or pack" },
+        min_rating: { type: "number", description: "Minimum average rating 0-5" },
+        limit: { type: "number", description: "Max results (default 20)" },
+      },
+      required: ["query"],
+    },
+  },
+  {
+    name: "skillmd_get",
+    description: "Fetch a single skill by slug (owner/name), including its SKILL.md body, provenance, license and security flags.",
+    inputSchema: { type: "object", properties: { slug: { type: "string", description: "owner/name, e.g. anthropic/pdf" } }, required: ["slug"] },
+  },
+  {
+    name: "skillmd_install",
+    description:
+      "Install a skill by slug: validates it, then writes its SKILL.md into the agent's skills directory. Never executes any scripts. Unverified skills are refused unless allow_unverified is true. Do not set allow_unverified on your own initiative — only after the human has explicitly approved installing this specific unverified skill.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        slug: { type: "string", description: "owner/name, e.g. anthropic/pdf" },
+        dest: { type: "string", description: "Target skills dir. Default ~/.claude/skills" },
+        allow_unverified: { type: "boolean", description: "Install even if the skill is not verified by SkillMD. Never set this on your own initiative — only after the human has explicitly approved this specific skill." },
+      },
+      required: ["slug"],
+    },
+  },
+  {
+    name: "skillmd_trending",
+    description: "Top skills on the SkillMD leaderboard. range: '30d' or 'all'.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        range: { type: "string", enum: ["30d", "all"], description: "Time window (default all)" },
+        category: { type: "string", description: "Optional category slug" },
+        limit: { type: "number", description: "Max results (default 20)" },
+      },
+    },
+  },
+  {
+    name: "skillmd_recommend",
+    description: "Recommend skills. If based_on is given, suggests skills similar to it (same category); otherwise returns trending.",
+    inputSchema: {
+      type: "object",
+      properties: { based_on: { type: "string", description: "A slug to base recommendations on" }, limit: { type: "number" } },
+    },
+  },
+  {
+    name: "skillmd_list_saved",
+    description: "List the signed-in user's saved skills. Requires SKILLMD_TOKEN to be set.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "skillmd_lint",
+    description:
+      "Validate a SKILL.md against the SkillMD spec and return diagnostics, security flags, and a quality score (0-100). Pass raw SKILL.md content, or a registry slug (owner/name) to fetch and lint.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        content: { type: "string", description: "Raw SKILL.md content to validate" },
+        slug: { type: "string", description: "Registry slug owner/name to fetch and validate" },
+      },
+    },
+  },
+];
+
+// KEEP IN SYNC with apps/cli/src/api.ts (reconstructSkillMd / skillMdFor) —
+// duplicated because the MCP bin ships as a standalone script; no automated
+// check enforces this.
+function reconstructSkillMd(skill) {
+  if (skill.raw_md) return skill.raw_md;
+  const fm = { name: skill.slug.split("/")[1] || skill.title, description: String(skill.description).replace(/\n/g, " ") };
+  if (skill.license) fm.license = skill.license;
+  return `---\n${stringifyYaml(fm)}---\n${skill.body_md || ""}`;
+}
+
+async function handleCall(name, args) {
+  switch (name) {
+    case "skillmd_search": {
+      const p = new URLSearchParams({ q: args.query, limit: String(args.limit ?? 20) });
+      if (args.category) p.set("category", args.category);
+      if (args.verified_only) p.set("verified", "true");
+      if (args.type) p.set("type", args.type);
+      if (args.min_rating != null) p.set("min_rating", String(args.min_rating));
+      const r = await api(`/api/search?${p}`);
+      return text(r.items ?? []);
+    }
+    case "skillmd_get": {
+      const [owner, slugName] = String(args.slug).split("/");
+      const r = await api(`/api/skills/${owner}/${slugName}`);
+      return text(r);
+    }
+    case "skillmd_trending": {
+      const p = new URLSearchParams({ range: args.range ?? "all", limit: String(args.limit ?? 20) });
+      if (args.category) p.set("category", args.category);
+      const r = await api(`/api/leaderboard?${p}`);
+      return text(r.items ?? []);
+    }
+    case "skillmd_recommend": {
+      if (args.based_on) {
+        const [owner, slugName] = String(args.based_on).split("/");
+        const base = await api(`/api/skills/${owner}/${slugName}`).catch(() => null);
+        if (base?.category_slug) {
+          const r = await api(`/api/leaderboard?range=all&limit=${args.limit ?? 10}&category=${base.category_slug}`);
+          return text((r.items ?? []).filter((s) => s.slug !== args.based_on));
+        }
+      }
+      const r = await api(`/api/leaderboard?range=30d&limit=${args.limit ?? 10}`);
+      return text(r.items ?? []);
+    }
+    case "skillmd_list_saved": {
+      if (!TOKEN) return text("Set SKILLMD_TOKEN (a SkillMD personal access token) to list your saved skills.");
+      const r = await api(`/api/favorites`);
+      return text(r.items ?? []);
+    }
+    case "skillmd_lint": {
+      if (!lint) return text("Validation engine unavailable — run `npm run build` in the skillmds package.");
+      let raw = args.content;
+      let slug;
+      if (!raw && args.slug) {
+        const [owner, slugName] = String(args.slug).split("/");
+        const skill = await api(`/api/skills/${owner}/${slugName}`);
+        raw = reconstructSkillMd(skill);
+        slug = slugName;
+      }
+      if (!raw) return text("Provide `content` (raw SKILL.md) or `slug` (owner/name).");
+      const result = lint(raw, slug ? { slug } : {});
+      return text({ ok: result.ok, score: result.score, diagnostics: result.diagnostics, security: result.security });
+    }
+    case "skillmd_install": {
+      const [owner, slugName] = String(args.slug).split("/");
+      // Defense in depth: slugName becomes a directory name below — refuse
+      // anything outside the registry's slugify alphabet (path separators,
+      // "..", etc.) before touching the network or filesystem.
+      if (!/^[a-z0-9][a-z0-9-]*$/.test(slugName ?? "")) {
+        return text(`Refused: invalid skill name "${slugName}" — expected a lowercase slug.`);
+      }
+      const skill = await api(`/api/skills/${owner}/${slugName}`);
+      const flags = skill.security_flags ?? [];
+      if (skill.verified === false && !args.allow_unverified) {
+        return text(
+          `Refused: ${args.slug} is not yet verified by SkillMD (security flags: ${flags.join(", ") || "unscanned"}). ` +
+          `Review it at https://skillmd.com/skills/${args.slug}. Only call skillmd_install again with allow_unverified: true ` +
+          `if the human explicitly approves installing this specific unverified skill — do not decide this yourself.`,
+        );
+      }
+      const raw = reconstructSkillMd(skill); // returns raw_md verbatim when the registry has it
+      if (lint) {
+        const result = lint(raw, { slug: slugName });
+        if (!result.ok) {
+          const errors = result.diagnostics.filter((d) => d.severity === "error");
+          return text(`Refused: ${args.slug} failed validation (${errors.map((d) => `${d.id}: ${d.message}`).join("; ")}). Not installed.`);
+        }
+      }
+      const baseDir = args.dest ? resolve(args.dest) : join(homedir(), ".claude", "skills");
+      const dir = join(baseDir, slugName);
+      await mkdir(dir, { recursive: true });
+      const file = join(dir, "SKILL.md");
+      await writeFile(file, raw, "utf8");
+      api(`/api/skills/${owner}/${slugName}/install`, { method: "POST", body: JSON.stringify({ via: "mcp" }) }).catch(() => {});
+      const note = skill.type === "pack"
+        ? ` NOTE: this is a pack and only SKILL.md was written — its assets/references are missing. For the full pack run: npx skillmds add ${args.slug}`
+        : "";
+      return text(`Installed ${args.slug} → ${file} (security: ${flags.join(", ") || "unscanned"})${note}`);
+    }
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+
+async function startMcpServer() {
+  const server = new Server({ name: "skillmd", version: VERSION }, { capabilities: { tools: {} } });
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    try {
+      return await handleCall(req.params.name, req.params.arguments ?? {});
+    } catch (e) {
+      return { isError: true, content: [{ type: "text", text: String(e?.message || e) }] };
+    }
+  });
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("skillmd MCP server running (stdio)");
+}
+
+// This binary is invoked three ways:
+//   - `skillmds <anything>`       → run the CLI. commander owns argv, so known
+//     commands run and unknown commands get a proper "unknown command" error
+//     instead of silently starting an MCP server.
+//   - `skillmds` in a terminal    → run the CLI (opens the interactive menu)
+//   - `skillmds` over piped stdio → start the MCP server (how MCP clients launch it;
+//     they always connect stdin as a pipe, never a TTY, and pass no args)
+if (process.argv.length > 2 || process.stdin.isTTY) {
+  await import("../dist/cli.js"); // the CLI parses process.argv itself
+} else {
+  await startMcpServer();
+}