@loompad/cli 0.1.0 → 1.1.1

package/dist/core/mcp-catalog.js

@@ -0,0 +1,431 @@
+/**
+ * The MCP catalog — where a server comes from before it is a row in config.
+ *
+ * core/mcp.ts is the back half of this story: it takes the servers a project has
+ * configured and puts them in front of an agent. This is the front half, and it
+ * is the half that didn't exist. Until now the only way to add a server was to
+ * know its URL and type it into a prompt — so the composer shipped six hardcoded
+ * rows with empty urls (GitHub, Slack, Supabase, …) which looked like
+ * integrations and were placeholders. A logo is not an integration, and neither
+ * is a name with nothing behind it.
+ *
+ * Two sources, and the difference between them is the whole design:
+ *
+ *   1. **The official registry** (registry.modelcontextprotocol.io). Thousands
+ *      of servers, searchable, maintained by somebody else. Everything in here
+ *      is normalised from what the registry actually returned — nothing is
+ *      filled in, and an entry that is installable by neither a URL nor a
+ *      package is dropped rather than shown as a row that can't be clicked.
+ *
+ *   2. **A curated shortlist** of well-known providers, for the empty state,
+ *      because "search 4000 servers" is a bad first screen and the registry's
+ *      ranking is not ours to reinterpret. Every URL and command in that list
+ *      was verified against the vendor's own documentation and, where it is a
+ *      remote, probed for a live response. The ones that could NOT be pinned to
+ *      a single correct endpoint carry `needsUrl` so the UI asks the user
+ *      instead of us guessing — a hosted telemetry backend whose hostname
+ *      contains the account's own region is not knowable from here.
+ *
+ * ## Why the cache exists
+ *
+ * The catalog modal searches as you type. Without a cache that is one HTTP
+ * request per keystroke against somebody else's public service, which is rude
+ * at best and rate-limited at worst. A short TTL is enough — the registry does
+ * not change between two keystrokes, and 60 seconds of staleness in a browse
+ * list costs nothing.
+ *
+ * ## Why a failed fetch is `degraded` and not an error
+ *
+ * A laptop on a plane still deserves the curated list. Returning an empty array
+ * would read as "there are no MCP servers", which is false; throwing would take
+ * the modal down over a network blip. `degraded: true` says exactly what
+ * happened — the registry did not answer, this is what we know without it — and
+ * the UI can say so out loud.
+ */
+// ---------------------------------------------------------------------------
+// The curated shelf
+// ---------------------------------------------------------------------------
+/**
+ * Well-known providers, verified against vendor documentation.
+ *
+ * Each remote below was confirmed twice: it appears in the vendor's own docs (or
+ * in the official registry under the vendor's namespace), and a live MCP
+ * `initialize` to it answered — 401 for the ones that need auth, which is a
+ * server saying "not without credentials" and therefore proof the endpoint is
+ * real. A DNS failure or a 404 would have disqualified an entry.
+ *
+ * Three entries are worth reading the comment on rather than trusting the shape:
+ * SigNoz (region in the hostname), Postgres (no official server exists at all),
+ * and Cloudflare (sixteen servers, not one).
+ */
+export const CURATED_MCPS = [
+    {
+        slug: "github",
+        name: "GitHub",
+        description: "Repositories, issues, pull requests, Actions, and code search.",
+        homepage: "https://github.com/github/github-mcp-server",
+        transport: "http",
+        // The trailing slash is what GitHub's own docs and registry entry use.
+        url: "https://api.githubcopilot.com/mcp/",
+        requires: "a GitHub account; the server authenticates over OAuth on first use",
+        maintainer: "official",
+        source: "curated",
+    },
+    {
+        slug: "linear",
+        name: "Linear",
+        description: "Issues, projects, cycles, and comments in Linear.",
+        homepage: "https://linear.app/docs/mcp",
+        transport: "http",
+        // Linear also publishes /sse, but its docs mark that a deprecated fallback.
+        url: "https://mcp.linear.app/mcp",
+        maintainer: "official",
+        source: "curated",
+    },
+    {
+        slug: "slack",
+        name: "Slack",
+        description: "Search and read Slack messages, channels, and files.",
+        homepage: "https://docs.slack.dev/ai/slack-mcp-server/",
+        transport: "http",
+        url: "https://mcp.slack.com/mcp",
+        // Slack's docs say plainly that they do not support Dynamic Client
+        // Registration, so the generic "add a remote server and let it OAuth" path
+        // does not work here — you need a Slack app declaring the mcp:connect
+        // scope. Said out loud because the failure otherwise looks like a bug.
+        requires: "a Slack app with the mcp:connect scope — Slack does not support dynamic client registration",
+        maintainer: "official",
+        source: "curated",
+    },
+    {
+        slug: "notion",
+        name: "Notion",
+        description: "Search, read, create, and update Notion pages and databases.",
+        homepage: "https://developers.notion.com/docs/mcp",
+        transport: "http",
+        url: "https://mcp.notion.com/mcp",
+        maintainer: "official",
+        source: "curated",
+    },
+    {
+        slug: "sentry",
+        name: "Sentry",
+        description: "Query Sentry issues, errors, traces, and releases.",
+        homepage: "https://mcp.sentry.dev",
+        transport: "http",
+        url: "https://mcp.sentry.dev/mcp",
+        maintainer: "official",
+        source: "curated",
+    },
+    {
+        slug: "stripe",
+        name: "Stripe",
+        description: "Manage Stripe customers, products, prices, payments, and invoices.",
+        homepage: "https://docs.stripe.com/mcp",
+        transport: "http",
+        url: "https://mcp.stripe.com",
+        maintainer: "official",
+        source: "curated",
+    },
+    {
+        slug: "supabase",
+        name: "Supabase",
+        description: "Manage Supabase projects, run SQL, inspect schemas, generate types.",
+        homepage: "https://supabase.com/docs/guides/getting-started/mcp",
+        transport: "http",
+        url: "https://mcp.supabase.com/mcp",
+        maintainer: "official",
+        source: "curated",
+    },
+    {
+        slug: "figma",
+        name: "Figma",
+        description: "Pull Figma design context, components, and variables into code.",
+        homepage: "https://developers.figma.com/docs/figma-mcp-server/",
+        transport: "http",
+        url: "https://mcp.figma.com/mcp",
+        maintainer: "official",
+        source: "curated",
+    },
+    {
+        slug: "cloudflare",
+        name: "Cloudflare Docs",
+        // Cloudflare publishes sixteen topic servers (bindings, observability,
+        // radar, browser, logs, …) at <topic>.mcp.cloudflare.com/mcp, not one
+        // "Cloudflare" server. Featuring the docs one is a choice, and the honest
+        // way to make it is to name it for what it is and say where the rest are —
+        // rather than shipping a row called "Cloudflare" that turns out to only
+        // answer documentation questions.
+        description: "Search Cloudflare's documentation. Cloudflare's other servers (bindings, observability, radar, browser, logs, …) live at https://<topic>.mcp.cloudflare.com/mcp.",
+        homepage: "https://developers.cloudflare.com/agents/model-context-protocol/mcp-servers-for-cloudflare/",
+        transport: "http",
+        url: "https://docs.mcp.cloudflare.com/mcp",
+        maintainer: "official",
+        source: "curated",
+    },
+    {
+        slug: "playwright",
+        name: "Playwright",
+        description: "Drive a browser: navigate, click, fill, snapshot, screenshot.",
+        homepage: "https://github.com/microsoft/playwright-mcp",
+        transport: "stdio",
+        command: "npx",
+        args: ["@playwright/mcp@latest"],
+        maintainer: "official",
+        source: "curated",
+    },
+    {
+        slug: "postgres",
+        name: "Postgres",
+        // The reference server everyone still links to — @modelcontextprotocol/
+        // server-postgres — is deprecated on npm, archived upstream, last released
+        // in 2024, and carries a published SQL-injection flaw (it wrapped queries
+        // in a read-only transaction but accepted semicolon-delimited statements,
+        // so a caller could break out of it). It is not shipped here at any price.
+        //
+        // The PostgreSQL project publishes no MCP server of its own, so the honest
+        // label on the best-maintained alternative is "community", and the default
+        // access mode is the restricted one. Someone who wants write access can say
+        // so; nobody should get it because a featured row defaulted to it.
+        description: "Query a PostgreSQL database: schemas, indexes, health checks, and read-only SQL. Community-maintained — PostgreSQL publishes no official MCP server.",
+        homepage: "https://github.com/crystaldba/postgres-mcp",
+        transport: "stdio",
+        command: "uvx",
+        args: ["postgres-mcp", "--access-mode=restricted"],
+        requires: "a DATABASE_URI environment variable pointing at your database",
+        maintainer: "community",
+        source: "curated",
+    },
+    {
+        slug: "filesystem",
+        name: "Filesystem",
+        // The allowed directories are positional arguments and the server will not
+        // start without at least one. They are deliberately NOT defaulted to the
+        // project directory here: which files an agent may write is the user's
+        // decision, and a default that happens to be right is still a decision
+        // nobody made.
+        description: "Read and write local files, restricted to directories you allow.",
+        homepage: "https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem",
+        transport: "stdio",
+        command: "npx",
+        args: ["-y", "@modelcontextprotocol/server-filesystem"],
+        requires: "one or more directories the server may access, appended as arguments",
+        maintainer: "official",
+        source: "curated",
+    },
+    {
+        slug: "signoz",
+        name: "SigNoz",
+        // SigNoz Cloud's MCP hostname contains the account's region
+        // (mcp.us / mcp.eu / mcp.in …), and their docs are explicit that the wrong
+        // region fails authentication. There is no correct value to hardcode, so
+        // this asks — with the documented shape prefilled so the user only has to
+        // replace the one part we can't know. Self-hosted SigNoz is a different
+        // endpoint entirely, which is another reason not to guess.
+        description: "Query SigNoz metrics, traces, logs, alerts, and dashboards.",
+        homepage: "https://signoz.io/docs/ai/signoz-mcp-server/",
+        transport: "http",
+        needsUrl: true,
+        urlTemplate: "https://mcp.<region>.signoz.cloud/mcp",
+        requires: "your SigNoz Cloud region, or the URL of your self-hosted deployment",
+        maintainer: "official",
+        source: "curated",
+    },
+];
+// ---------------------------------------------------------------------------
+// The registry
+// ---------------------------------------------------------------------------
+const DEFAULT_REGISTRY_URL = "https://registry.modelcontextprotocol.io/v0/servers";
+/**
+ * Which registry to ask.
+ *
+ * Read per call rather than captured at import, so a test can point it at a
+ * local stub without a module-load dance — and so anyone running one of the
+ * private subregistries the MCP spec allows can point Loom at theirs. Reading
+ * it live is also what keeps the test suite off the public registry entirely: a
+ * unit test that quietly makes a real network request is slow, flaky under
+ * load, and fails on a plane.
+ */
+function registryUrl() {
+    return process.env.LOOM_MCP_REGISTRY?.trim() || DEFAULT_REGISTRY_URL;
+}
+/**
+ * How long a search stays fresh. Short, because the point is to survive a burst
+ * of keystrokes rather than to avoid the network — a browse list that is a
+ * minute stale is indistinguishable from a live one.
+ */
+const TTL_MS = 60_000;
+/**
+ * A failure is cached too, briefly. Otherwise every keystroke while offline
+ * costs a full 8-second timeout, and the modal becomes unusable in exactly the
+ * situation the curated fallback exists to handle. Ten seconds is long enough
+ * to stop the storm and short enough that reconnecting feels immediate.
+ */
+const FAILURE_TTL_MS = 10_000;
+const DEFAULT_LIMIT = 30;
+const MAX_LIMIT = 100;
+const cache = new Map();
+/** Drop everything cached. Exported for tests, which must not inherit a result. */
+export function clearCatalogCache() {
+    cache.clear();
+}
+/**
+ * Search the official registry, falling back to the curated shelf.
+ *
+ * `query` is passed through as the registry's own `search` parameter — its
+ * matching is its business, and reimplementing it here would give different
+ * answers than the registry's website for the same words.
+ */
+export async function searchCatalog(query, limit) {
+    const q = String(query ?? "").trim();
+    const n = Math.min(Math.max(Math.trunc(Number(limit) || DEFAULT_LIMIT), 1), MAX_LIMIT);
+    const key = `${n}\0${q}`;
+    const hit = cache.get(key);
+    if (hit && Date.now() - hit.at < hit.ttl)
+        return hit.value;
+    const featured = CURATED_MCPS;
+    let result;
+    try {
+        const url = new URL(registryUrl());
+        url.searchParams.set("limit", String(n));
+        if (q)
+            url.searchParams.set("search", q);
+        const res = await fetch(url, {
+            signal: AbortSignal.timeout(8_000),
+            headers: { accept: "application/json" },
+        });
+        if (!res.ok)
+            throw new Error(`registry responded ${res.status}`);
+        const body = (await res.json());
+        result = { servers: normalizeRegistry(body), featured, degraded: false };
+    }
+    catch {
+        // Offline, timed out, rate-limited, or the registry changed shape under us.
+        // All four have the same honest answer: here is what we know for certain,
+        // and a flag saying the rest is missing. Nothing is invented to fill it.
+        result = { servers: [], featured, degraded: true };
+    }
+    cache.set(key, { at: Date.now(), ttl: result.degraded ? FAILURE_TTL_MS : TTL_MS, value: result });
+    // The cache is a keystroke buffer, not a store. A bound keeps a long typing
+    // session from retaining every prefix of every query for the process's life.
+    if (cache.size > 200) {
+        const oldest = [...cache.entries()].sort((a, b) => a[1].at - b[1].at)[0];
+        if (oldest)
+            cache.delete(oldest[0]);
+    }
+    return result;
+}
+/**
+ * Registry entries → installable rows.
+ *
+ * Two things happen here that the raw response doesn't do for you:
+ *
+ *   - **Deduplication.** The registry returns every published version of a
+ *     server as its own entry, so an unfiltered list shows "inference.sh" three
+ *     times. Entries are collapsed by name, preferring the one the registry
+ *     marks `isLatest` and otherwise the last seen (the list is version-ordered).
+ *
+ *   - **Dropping the uninstallable.** `remotes` and `packages` are both nullable
+ *     and an entry can have neither — it is a name in a directory, not something
+ *     you can connect to. Those are removed rather than rendered as a row whose
+ *     Install button would have nothing to write.
+ */
+export function normalizeRegistry(body) {
+    const byName = new Map();
+    const pinned = new Set();
+    for (const item of body?.servers ?? []) {
+        const server = item?.server;
+        const name = String(server?.name ?? "").trim();
+        if (!server || !name)
+            continue;
+        const normalized = normalizeServer(server);
+        if (!normalized)
+            continue;
+        const isLatest = Object.values(item?._meta ?? {}).some((m) => m?.isLatest === true);
+        // A version the registry marks latest wins and holds; otherwise later
+        // entries overwrite earlier ones, which for a version-ordered list is the
+        // newest one we saw.
+        if (pinned.has(name) && !isLatest)
+            continue;
+        byName.set(name, normalized);
+        if (isLatest)
+            pinned.add(name);
+    }
+    return [...byName.values()];
+}
+/** One entry, or null when it is installable by neither a remote nor a package. */
+function normalizeServer(server) {
+    const name = String(server.name ?? "").trim();
+    const base = {
+        id: name,
+        name,
+        title: String(server.title ?? "").trim() || humanize(name),
+        description: String(server.description ?? "").trim(),
+        ...(server.repository?.url ? { homepage: String(server.repository.url) } : {}),
+        ...(server.version ? { version: String(server.version) } : {}),
+        source: "registry",
+    };
+    // A remote wins over a package every time: it is a URL the user can connect
+    // to now, against a package that has to be downloaded and run locally with
+    // whatever credentials it wants in its environment.
+    const remote = pickRemote(server.remotes);
+    if (remote)
+        return { ...base, transport: remote.transport, url: remote.url };
+    const pkg = pickPackage(server.packages);
+    if (pkg)
+        return { ...base, transport: "stdio", command: pkg.command, args: pkg.args };
+    return null;
+}
+/** The best remote: streamable-http if offered, else sse. */
+function pickRemote(remotes) {
+    const usable = (remotes ?? []).filter((r) => /^https?:\/\//i.test(String(r?.url ?? "").trim()));
+    const http = usable.find((r) => String(r.type ?? "").toLowerCase() === "streamable-http" || String(r.type ?? "").toLowerCase() === "http");
+    if (http)
+        return { transport: "http", url: String(http.url).trim() };
+    const sse = usable.find((r) => String(r.type ?? "").toLowerCase() === "sse");
+    if (sse)
+        return { transport: "sse", url: String(sse.url).trim() };
+    // A remote with a URL but an unfamiliar `type`. It is still a URL, and
+    // core/mcp.ts guesses http-vs-sse from the path the same way — so honour it
+    // rather than dropping a server over a spelling we haven't seen.
+    const other = usable[0];
+    return other ? { transport: /\/sse\/?$/i.test(String(other.url)) ? "sse" : "http", url: String(other.url).trim() } : null;
+}
+/**
+ * A package → the command that runs it.
+ *
+ * Only the two ecosystems with a standard zero-install runner: npm via `npx -y`
+ * and PyPI via `uvx`, both of which take `name@version`. Anything else (OCI,
+ * NuGet, a bare binary) needs a decision about a runtime that isn't ours to
+ * make, so those entries are left uninstallable rather than given a command
+ * that probably doesn't exist on the machine.
+ *
+ * The registry's `runtimeArguments` are deliberately ignored: they encode
+ * per-package placeholders that the user is expected to fill in, and splicing
+ * them in unfilled produces a command line that looks complete and isn't.
+ */
+function pickPackage(packages) {
+    for (const pkg of packages ?? []) {
+        const id = String(pkg?.identifier ?? "").trim();
+        if (!id)
+            continue;
+        const version = String(pkg?.version ?? "").trim();
+        const spec = version ? `${id}@${version}` : id;
+        const type = String(pkg?.registryType ?? "").toLowerCase();
+        const hint = String(pkg?.runtimeHint ?? "").toLowerCase();
+        if (type === "npm" || hint === "npx")
+            return { command: "npx", args: ["-y", spec] };
+        if (type === "pypi" || hint === "uvx")
+            return { command: "uvx", args: [spec] };
+    }
+    return null;
+}
+/** `ai.smithery/smithery-ai-github` → `Smithery Ai Github`, for an entry with no title. */
+function humanize(name) {
+    const tail = name.split("/").pop() ?? name;
+    return tail
+        .replace(/[-_.]+/g, " ")
+        .trim()
+        .replace(/\b\w/g, (c) => c.toUpperCase()) || name;
+}
+//# sourceMappingURL=mcp-catalog.js.map

package/dist/core/mcp-catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-catalog.js","sourceRoot":"","sources":["../../src/core/mcp-catalog.ts"],"names":[],"mappings":"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"}

package/dist/core/mcp.d.ts

@@ -0,0 +1,87 @@
+/**
+ * MCP servers — turning the project's configured list into something the agents
+ * actually receive.
+ *
+ * Until this existed, `config.mcps` was a list you could edit and nothing else:
+ * it was written by the composer, read back by GET /mcps, and never once handed
+ * to an agent. A row said "connected" because it had a URL typed into it, which
+ * is not the same claim at all. Both halves of that are fixed here.
+ *
+ *   1. `writeMcpSession` renders the enabled servers into the standard
+ *      `{"mcpServers": {…}}` document, in a temp file the adapter passes to its
+ *      CLI for one turn and which is deleted afterwards. Nothing is left behind
+ *      in the project, and nothing survives a turn it wasn't meant for.
+ *
+ *   2. `probeMcpServer` asks the server whether it is there. A bounded HTTP
+ *      round-trip is a weak signal — it proves an endpoint answered, not that it
+ *      speaks MCP — but it is a *measurement*, and the alternative on offer was
+ *      `!!url`. A server that refuses the connection is reported as unreachable,
+ *      which is the honest reading.
+ *
+ * Two adapters consume this, each through its harness's own API: the Claude
+ * adapter passes the servers as the Agent SDK's `mcpServers` option, and the
+ * Codex adapter as `mcp_servers.<key>` config on app-server `thread/start`.
+ * The config file itself is what `claude -p` callers (Insights) read.
+ */
+import type { McpServerConfig, McpServerEntry, ResolvedMcpServer } from "../types.js";
+export type { McpServerEntry, ResolvedMcpServer };
+/** A generated config file plus the servers in it. Alive for exactly one turn. */
+export interface McpSession {
+    /** Absolute path to the `{"mcpServers": …}` document. */
+    configPath: string;
+    servers: ResolvedMcpServer[];
+    /** Delete the temp file (and its directory). Idempotent, never throws. */
+    cleanup: () => void;
+}
+/**
+ * MCP config keys land in a TOML dotted path (`mcp_servers.<key>` for codex),
+ * so a display name like "My Server / prod" can't be used raw. Lower-cased and
+ * reduced to word characters, which is stable across turns and collision-free
+ * for any two names that differ by more than punctuation.
+ */
+export declare function mcpKey(name: string): string;
+/**
+ * Which configured servers are real enough to hand to an agent.
+ *
+ * A server counts when it has somewhere to connect to — a URL, or a command to
+ * run — and hasn't been switched off for the session. The built-in suggestion
+ * rows (GitHub, Slack, … with an empty url) are exactly the rows that fail this,
+ * which is the point: they're placeholders, and shipping a placeholder to a CLI
+ * as if it were a server is how you get an agent that reports a tool it doesn't
+ * have.
+ */
+export declare function resolveMcpServers(mcps: McpServerConfig[] | undefined): ResolvedMcpServer[];
+/** The config document itself — the shape every MCP client reads. */
+export declare function mcpConfigDocument(servers: ResolvedMcpServer[]): {
+    mcpServers: Record<string, McpServerEntry>;
+};
+/**
+ * Write the enabled servers to a temp config file for one turn.
+ *
+ * Returns null when there is nothing to write — callers use that to decide
+ * whether the CLI gets the flag at all, because passing an empty config is not
+ * the same as passing none (with `--strict-mcp-config` it would *suppress* the
+ * user's own servers).
+ */
+export declare function writeMcpSession(mcps: McpServerConfig[] | undefined): McpSession | null;
+/**
+ * Is the server actually there?
+ *
+ * HEAD first (cheapest thing that proves a listener answered), then GET for the
+ * servers that only implement the methods MCP uses. ANY HTTP status counts as
+ * reachable — a 405 or a 401 is a server saying "not like that", which is still
+ * a server. A connection refused, a DNS failure or a timeout is not.
+ *
+ * Bounded hard: this sits behind an HTTP handler that renders a list, and a
+ * hanging endpoint must cost that request two seconds, not forever. The body is
+ * cancelled immediately because an MCP endpoint may answer GET with an open SSE
+ * stream that never ends.
+ */
+export declare function probeMcpServer(url: string, timeoutMs?: number): Promise<boolean>;
+/**
+ * Probe every configured server that has a URL, in parallel, and report which
+ * ones answered. Servers with no URL aren't probed and aren't reachable —
+ * including the command-based ones, whose liveness is "does the process start",
+ * a question this can't answer without spawning it.
+ */
+export declare function probeMcpServers(mcps: McpServerConfig[], timeoutMs?: number): Promise<Record<string, boolean>>;