loopengine 0.1.98 → 0.1.99

package/dist/core/mcp-apps.d.ts

@@ -0,0 +1,95 @@
+import { type McpDirectoryServer } from './mcp-directory.js';
+import type { WorkspaceAbility } from './workspace-abilities.js';
+export interface AppCatalogEntry {
+    /** Its MCP Registry name. */
+    id: string;
+    /** The app's own website, for its icon when the registry has none. */
+    site: string;
+    title: string;
+    url: string;
+    category: string;
+    description: string;
+    /** Headers the server needs to offer the right tools (e.g. GitHub's
+     * toolsets). */
+    headers?: Record<string, string>;
+}
+export declare const APP_CATALOG: AppCatalogEntry[];
+/** A catalog entry as a directory server (what the generator takes). */
+export declare function catalogServer(entry: AppCatalogEntry): McpDirectoryServer;
+/** The server for an app id: from the catalog, else the directory
+ * (saved servers, then the registry). */
+export declare function appServer(id: string): Promise<McpDirectoryServer | undefined>;
+/** Starts fetching the catalog's icons (once); resolves when done. */
+export declare function loadAppIcons(): Promise<void>;
+export interface ConnectedApp {
+    /** The registry name or saved id it was made from, when recorded. */
+    id?: string;
+    title: string;
+    url: string;
+    /** The workspace ability it is (e.g. mcp-linear) and its spec. */
+    ability: string;
+    spec: string;
+    /** Its tools, with the permission each was set up with. */
+    tools: {
+        name: string;
+        decision?: 'allow' | 'ask' | 'deny';
+    }[];
+    /** The setting its key is read from, and whether it has a value. */
+    keyEnv?: string;
+    keySet: boolean;
+    /** Agents that have added it. */
+    agents: string[];
+    connectedAt: string;
+}
+export interface AppView extends AppCatalogEntry {
+    icon?: string;
+    connected: boolean;
+}
+/** Whether a workspace ability takes its tools from an MCP server (a
+ * connected app). */
+export declare function isAppAbility(a: Pick<WorkspaceAbility, 'spec'>): boolean;
+/** The workspace abilities that take their tools from an MCP server, as
+ * connected apps. */
+export declare function connectedApps(workspace: WorkspaceAbility[], agentAbilities: Record<string, string[]>, envValue: (name: string) => string | undefined): ConnectedApp[];
+/** The catalog, each app marked connected or not, with its icon once known. */
+export declare function appCatalog(connected: ConnectedApp[]): AppView[];
+export declare class AppToolsError extends Error {
+}
+export interface AppTool {
+    /** The server's name for it, and the name agents see. */
+    remote: string;
+    name: string;
+    description: string;
+    readOnly?: boolean;
+    destructive?: boolean;
+    /** Its default permission. */
+    decision: 'allow' | 'ask' | 'deny';
+    /** Agents that have it, with the permission each gave it. */
+    usedBy: {
+        agent: string;
+        decision: 'allow' | 'ask' | 'deny';
+    }[];
+}
+/** An agent's tools from one app: its chosen server tools, each with its
+ * permission there (the agent's first rule for the tool). */
+export type AgentAppTools = Record<string, {
+    remote: string;
+    decision: 'allow' | 'ask' | 'deny';
+}[]>;
+/** Every tool of the app, with its default permission and the agents
+ * using it. Tools the server added since connecting are listed too, at
+ * their default (see refreshAppTools to add them for good). */
+export declare function appTools(spec: string, envValue: (name: string) => string | undefined, agents: AgentAppTools, options?: {
+    fresh?: boolean;
+}): Promise<AppTool[]>;
+/** Sets a tool's default permission, for agents that add it from now on;
+ * agents that already have it keep theirs. */
+export declare function setAppDefault(spec: string, remote: string, decision: 'allow' | 'ask' | 'deny'): void;
+/** Brings the app's tool list up to date with its server: new tools are
+ * added at their default permission, ones it no longer offers dropped.
+ * Agents keep the tools they chose (one the server dropped just stops
+ * loading). Returns what changed. */
+export declare function refreshAppTools(spec: string, envValue: (name: string) => string | undefined): Promise<{
+    added: string[];
+    removed: string[];
+}>;

package/dist/core/mcp-apps.js

@@ -0,0 +1,254 @@
+// The workspace's Apps (the console's Apps page): popular apps that
+// publish their own remote MCP server, and the ones this workspace has
+// connected. Connecting one makes a private ability from its server
+// (core/mcp-ability-generator.ts, with no workflow to fit, so it picks
+// the tools most useful day to day) and stores it as a workspace ability
+// with source `mcp:<url>`; agents then add it from their Apps tab.
+//
+// Every entry below is the app's own server as listed in the official MCP
+// Registry (checked November 2026). The URL is kept here so the page works
+// without reaching the registry; the registry only adds icons.
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { getMcpServer } from './mcp-directory.js';
+import { readAbilityDetails } from './ability-details.js';
+import { appRuleName, defaultMcpDecision, mcpAbilityNames } from './mcp-ability-generator.js';
+import { listMcpServerTools, mcpToolName } from './mcp-abilities.js';
+export const APP_CATALOG = [
+    { id: 'com.stripe/mcp', site: 'stripe.com', title: 'Stripe', url: 'https://mcp.stripe.com', category: 'Payments', description: 'Customers, payments, invoices, subscriptions and refunds.' },
+    { id: 'com.paypal.mcp/mcp', site: 'paypal.com', title: 'PayPal', url: 'https://mcp.paypal.com/mcp', category: 'Payments', description: 'Invoices, orders, payments and disputes.' },
+    { id: 'com.notion/mcp', site: 'notion.com', title: 'Notion', url: 'https://mcp.notion.com/mcp', category: 'Docs', description: 'Search, read and write pages and databases.' },
+    { id: 'com.atlassian/atlassian-mcp-server', site: 'atlassian.com', title: 'Jira & Confluence', url: 'https://mcp.atlassian.com/v2/mcp', category: 'Projects', description: 'Jira issues and Confluence pages (Atlassian).' },
+    { id: 'app.linear/linear', site: 'linear.app', title: 'Linear', url: 'https://mcp.linear.app/mcp', category: 'Projects', description: 'Issues, projects and documents.' },
+    { id: 'com.monday/monday.com', site: 'monday.com', title: 'monday.com', url: 'https://mcp.monday.com/mcp', category: 'Projects', description: 'Boards, items and updates.' },
+    { id: 'com.basecamp/mcp', site: 'basecamp.com', title: 'Basecamp', url: 'https://mcp.basecamp.com/mcp', category: 'Projects', description: 'Projects, to-dos and messages.' },
+    { id: 'net.todoist/mcp', site: 'todoist.com', title: 'Todoist', url: 'https://ai.todoist.net/mcp', category: 'Projects', description: 'Tasks and projects.' },
+    { id: 'com.airtable/mcp', site: 'airtable.com', title: 'Airtable', url: 'https://mcp.airtable.com/mcp', category: 'Data', description: 'Bases, tables and records.' },
+    { id: 'io.github.github/github-mcp-server', site: 'github.com', title: 'GitHub', url: 'https://api.githubcopilot.com/mcp/', category: 'Engineering', description: 'Repositories, issues, pull requests and Actions runs.', headers: { 'X-MCP-Toolsets': 'repos,issues,pull_requests,actions' } },
+    { id: 'com.gitlab/mcp', site: 'gitlab.com', title: 'GitLab', url: 'https://gitlab.com/api/v4/mcp', category: 'Engineering', description: 'Projects, issues and merge requests.' },
+    { id: 'io.github.getsentry/sentry-mcp', site: 'sentry.io', title: 'Sentry', url: 'https://mcp.sentry.dev/mcp', category: 'Engineering', description: 'Errors, issues and releases.' },
+    { id: 'com.vercel/vercel-mcp', site: 'vercel.com', title: 'Vercel', url: 'https://mcp.vercel.com', category: 'Engineering', description: 'Projects, deployments and logs.' },
+    { id: 'com.supabase/mcp', site: 'supabase.com', title: 'Supabase', url: 'https://mcp.supabase.com/mcp', category: 'Engineering', description: 'Databases, tables and projects.' },
+    { id: 'com.circleci/mcp', site: 'circleci.com', title: 'CircleCI', url: 'https://mcp.circleci.com/v1/mcp', category: 'Engineering', description: 'Pipelines, builds and test results.' },
+    { id: 'io.github.PostHog/mcp', site: 'posthog.com', title: 'PostHog', url: 'https://mcp.posthog.com/mcp', category: 'Analytics', description: 'Product analytics, insights and feature flags.' },
+    { id: 'com.amplitude/mcp-server', site: 'amplitude.com', title: 'Amplitude', url: 'https://mcp.amplitude.com/mcp', category: 'Analytics', description: 'Charts, dashboards and events.' },
+    { id: 'com.figma.mcp/mcp', site: 'figma.com', title: 'Figma', url: 'https://mcp.figma.com/mcp', category: 'Design', description: 'Design files, frames and comments.' },
+    { id: 'com.canva.mcp/mcp', site: 'canva.com', title: 'Canva', url: 'https://mcp.canva.com/mcp', category: 'Design', description: 'Designs, templates and exports.' },
+    { id: 'io.github.miroapp/mcp-server', site: 'miro.com', title: 'Miro', url: 'https://mcp.miro.com/', category: 'Design', description: 'Boards, sticky notes and diagrams.' },
+    { id: 'com.webflow/mcp', site: 'webflow.com', title: 'Webflow', url: 'https://mcp.webflow.com/mcp', category: 'Websites', description: 'Sites, pages and CMS items.' },
+    { id: 'com.wix/mcp', site: 'wix.com', title: 'Wix', url: 'https://mcp.wix.com/mcp', category: 'Websites', description: 'Sites, stores and bookings.' },
+    { id: 'com.typeform/typeform', site: 'typeform.com', title: 'Typeform', url: 'https://api.typeform.com/mcp', category: 'Forms', description: 'Forms and responses.' },
+    { id: 'com.jotform/mcp', site: 'jotform.com', title: 'Jotform', url: 'https://mcp.jotform.com/', category: 'Forms', description: 'Forms and submissions.' },
+    { id: 'com.zapier/mcp', site: 'zapier.com', title: 'Zapier', url: 'https://mcp.zapier.com/api/v1/connect', category: 'Automation', description: 'Actions across thousands of apps, through your Zapier account.' },
+    { id: 'com.apify/apify-mcp-server', site: 'apify.com', title: 'Apify', url: 'https://mcp.apify.com/', category: 'Web data', description: 'Scrapers and crawlers (Apify Actors).' },
+    { id: 'io.github.firecrawl/firecrawl-mcp-server', site: 'firecrawl.dev', title: 'Firecrawl', url: 'https://mcp.firecrawl.dev/v2/mcp', category: 'Web data', description: 'Search the web, read pages and files, map and crawl sites. Add an API key for crawling, mapping and monitors.' },
+    { id: 'ai.exa/exa', site: 'exa.ai', title: 'Exa', url: 'https://mcp.exa.ai/mcp', category: 'Web data', description: 'Web search built for AI.' },
+    { id: 'co.huggingface/hf-mcp-server', site: 'huggingface.co', title: 'Hugging Face', url: 'https://huggingface.co/mcp?login', category: 'AI', description: 'Models, datasets and Spaces.' },
+];
+/** A catalog entry as a directory server (what the generator takes). */
+export function catalogServer(entry) {
+    return { id: entry.id, title: entry.title, description: entry.description, url: entry.url, transport: 'streamable-http', source: 'registry', verified: true, ...(entry.headers ? { headers: entry.headers } : {}) };
+}
+/** The server for an app id: from the catalog, else the directory
+ * (saved servers, then the registry). */
+export async function appServer(id) {
+    const entry = APP_CATALOG.find((a) => a.id === id);
+    return entry ? catalogServer(entry) : getMcpServer(id);
+}
+// Icons come from the registry, fetched once in the background; an app
+// without one there gets its own site's favicon.
+const icons = new Map();
+let iconsLoading;
+/** Starts fetching the catalog's icons (once); resolves when done. */
+export function loadAppIcons() {
+    iconsLoading ??= (async () => {
+        for (let i = 0; i < APP_CATALOG.length; i += 6) {
+            await Promise.all(APP_CATALOG.slice(i, i + 6).map(async (entry) => {
+                try {
+                    icons.set(entry.id, (await getMcpServer(entry.id))?.icon ?? null);
+                }
+                catch {
+                    icons.set(entry.id, null);
+                }
+            }));
+        }
+    })();
+    return iconsLoading;
+}
+/** Whether a workspace ability takes its tools from an MCP server (a
+ * connected app). */
+export function isAppAbility(a) {
+    return Boolean(readManifestAt(a.spec.replace(/^file:/, '')).mcp?.url);
+}
+function readManifestAt(dir) {
+    try {
+        if (existsSync(join(dir, 'loopengine.ability.json')))
+            return JSON.parse(readFileSync(join(dir, 'loopengine.ability.json'), 'utf8'));
+    }
+    catch { }
+    return {};
+}
+/** The workspace abilities that take their tools from an MCP server, as
+ * connected apps. */
+export function connectedApps(workspace, agentAbilities, envValue) {
+    return workspace.flatMap((a) => {
+        const dir = a.spec.replace(/^file:/, '');
+        const manifest = readManifestAt(dir);
+        const url = manifest.mcp?.url;
+        if (!url)
+            return [];
+        let tools = [];
+        try {
+            tools = readAbilityDetails(dir).tools.map((t) => ({ name: t.name, ...(t.decision ? { decision: t.decision } : {}) }));
+        }
+        catch { }
+        const entry = APP_CATALOG.find((e) => e.url === url || e.id === manifest.generatedFrom?.server);
+        const keyEnv = manifest.mcp?.auth?.type === 'key' ? manifest.mcp.auth.env : undefined;
+        return [{
+                ...(manifest.generatedFrom?.server ?? entry?.id ? { id: manifest.generatedFrom?.server ?? entry.id } : {}),
+                title: entry?.title || a.description.split(':')[0].replace(/ \(made from its MCP server\)$/, '') || a.name,
+                url,
+                ability: a.name,
+                spec: a.spec,
+                tools,
+                ...(keyEnv ? { keyEnv } : {}),
+                keySet: keyEnv ? envValue(keyEnv) !== undefined : true,
+                agents: Object.entries(agentAbilities).filter(([, names]) => names.includes(a.name)).map(([agent]) => agent),
+                connectedAt: a.installedAt,
+            }];
+    });
+}
+/** The catalog, each app marked connected or not, with its icon once known. */
+export function appCatalog(connected) {
+    return APP_CATALOG.map((entry) => {
+        const icon = icons.get(entry.id);
+        return {
+            ...entry,
+            icon: icon || `https://${entry.site}/favicon.ico`,
+            connected: connected.some((c) => c.url === entry.url || c.id === entry.id || c.ability === mcpAbilityNames(entry).name),
+        };
+    });
+}
+// ---- An app's tools ----
+// A connected app lists every tool its server offers, each with a
+// default permission (Allow when it only reads, else Ask me). Agents
+// choose which of them they get, and with what permission, when they add
+// the app; the defaults are what an agent starts from.
+export class AppToolsError extends Error {
+}
+function readApp(dir) {
+    const manifestPath = join(dir, 'loopengine.ability.json');
+    if (!existsSync(manifestPath))
+        throw new AppToolsError('That app isn\'t in the workspace any more.');
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    if (!manifest.mcp || !Array.isArray(manifest.mcp.tools))
+        throw new AppToolsError('That ability doesn\'t come from an MCP server.');
+    const name = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).name;
+    const rulesPath = join(dir, manifest.actauth ?? 'actauth/rules.yml');
+    const rules = existsSync(rulesPath) ? (parseYaml(readFileSync(rulesPath, 'utf8')) ?? []) : [];
+    return { name, manifest, rules, rulesPath };
+}
+function prefixOf(name, manifest) {
+    return manifest.mcp.prefix ?? name.replace(/^@[^/]+\//, '').replace(/^(lp|mcp)-/, '');
+}
+function envFrom(value) {
+    return {
+        get: value,
+        require(name) {
+            const v = value(name);
+            if (v === undefined)
+                throw new AppToolsError(`${name} isn't set, so the app's tools can't be listed.`);
+            return v;
+        },
+    };
+}
+// The server's list, kept a few minutes so opening the list again
+// doesn't reconnect each time.
+const listings = new Map();
+const LISTING_MS = 5 * 60 * 1000;
+async function serverTools(dir, manifest, envValue, fresh = false) {
+    const hit = listings.get(dir);
+    if (!fresh && hit && Date.now() - hit.at < LISTING_MS)
+        return hit.tools;
+    const { tools: _tools, prefix: _prefix, ...server } = manifest.mcp;
+    const tools = await listMcpServerTools(server, envFrom(envValue));
+    listings.set(dir, { at: Date.now(), tools });
+    return tools;
+}
+/** Every tool of the app, with its default permission and the agents
+ * using it. Tools the server added since connecting are listed too, at
+ * their default (see refreshAppTools to add them for good). */
+export async function appTools(spec, envValue, agents, options = {}) {
+    const dir = spec.replace(/^file:/, '');
+    const { name, manifest, rules } = readApp(dir);
+    const prefix = prefixOf(name, manifest);
+    let listed = [];
+    try {
+        listed = await serverTools(dir, manifest, envValue, options.fresh);
+    }
+    catch {
+        // Unreachable for now: still list what the app had, without details.
+    }
+    const byRemote = new Map(listed.map((t) => [t.name, t]));
+    const remotes = [...new Set([...manifest.mcp.tools, ...listed.map((t) => t.name)])];
+    return remotes.map((remote) => {
+        const info = byRemote.get(remote);
+        const installed = mcpToolName(prefix, remote);
+        const decision = rules.find((r) => r.tool === installed)?.decision ?? (info ? defaultMcpDecision(info) : 'ask');
+        return {
+            remote,
+            name: installed,
+            description: info ? info.description.split('\n')[0].slice(0, 240) : listed.length ? 'The server no longer offers this tool.' : '',
+            ...(info?.readOnly !== undefined ? { readOnly: info.readOnly } : {}),
+            ...(info?.destructive ? { destructive: true } : {}),
+            decision,
+            usedBy: Object.entries(agents).flatMap(([agent, tools]) => tools.filter((t) => t.remote === remote).map((t) => ({ agent, decision: t.decision }))),
+        };
+    });
+}
+/** Sets a tool's default permission, for agents that add it from now on;
+ * agents that already have it keep theirs. */
+export function setAppDefault(spec, remote, decision) {
+    const dir = spec.replace(/^file:/, '');
+    const { name, manifest, rules, rulesPath } = readApp(dir);
+    if (!manifest.mcp.tools.includes(remote))
+        throw new AppToolsError(`${remote} isn't one of the app's tools.`);
+    const installed = mcpToolName(prefixOf(name, manifest), remote);
+    const rule = rules.find((r) => r.tool === installed);
+    if (rule)
+        rule.decision = decision;
+    else
+        rules.push({ name: appRuleName(name, installed), scope: '*/*', tool: installed, decision });
+    writeFileSync(rulesPath, stringifyYaml(rules));
+}
+/** Brings the app's tool list up to date with its server: new tools are
+ * added at their default permission, ones it no longer offers dropped.
+ * Agents keep the tools they chose (one the server dropped just stops
+ * loading). Returns what changed. */
+export async function refreshAppTools(spec, envValue) {
+    const dir = spec.replace(/^file:/, '');
+    const { name, manifest, rules, rulesPath } = readApp(dir);
+    const prefix = prefixOf(name, manifest);
+    const listed = await serverTools(dir, manifest, envValue, true);
+    const taken = new Set();
+    const offered = listed.filter((t) => {
+        const installed = mcpToolName(prefix, t.name);
+        if (taken.has(installed))
+            return false;
+        taken.add(installed);
+        return true;
+    });
+    const added = offered.filter((t) => !manifest.mcp.tools.includes(t.name));
+    const removed = manifest.mcp.tools.filter((r) => !offered.some((t) => t.name === r));
+    for (const t of added) {
+        const installed = mcpToolName(prefix, t.name);
+        if (!rules.some((r) => r.tool === installed))
+            rules.push({ name: appRuleName(name, installed), scope: '*/*', tool: installed, decision: defaultMcpDecision(t) });
+    }
+    const gone = new Set(removed.map((r) => mcpToolName(prefix, r)));
+    manifest.mcp.tools = offered.map((t) => t.name);
+    writeFileSync(join(dir, 'loopengine.ability.json'), JSON.stringify(manifest, null, 2) + '\n');
+    writeFileSync(rulesPath, stringifyYaml(rules.filter((r) => !gone.has(r.tool))));
+    return { added: added.map((t) => t.name), removed };
+}

package/dist/core/mcp-directory.d.ts

@@ -0,0 +1,32 @@
+export interface McpDirectoryServer {
+    /** The registry name (com.stripe/mcp) or a saved server's id. */
+    id: string;
+    title: string;
+    description: string;
+    url: string;
+    transport: 'streamable-http' | 'sse';
+    website?: string;
+    /** An https icon from its registry entry, when it has one. */
+    icon?: string;
+    source: 'saved' | 'registry';
+    /** Saved by the workspace, or on its publisher's own verified domain. */
+    verified: boolean;
+    /** Verified, and the publisher is the app searched for (com.stripe for
+     * "stripe"), not someone else's server for it. Set by searchMcpServers. */
+    official?: boolean;
+    /** How a key is sent, when it isn't Authorization: Bearer. */
+    auth?: {
+        header?: string;
+        prefix?: string;
+    };
+    /** Extra headers the server needs (e.g. which toolsets to offer). */
+    headers?: Record<string, string>;
+}
+export declare const MCP_REGISTRY_URL_ENV = "LOOPENGINE_MCP_REGISTRY_URL";
+export declare const MCP_SERVERS_FILE_ENV = "LOOPENGINE_MCP_SERVERS_FILE";
+/** The workspace's saved servers. A malformed entry is skipped. */
+export declare function savedMcpServers(): McpDirectoryServer[];
+/** Saved servers matching `query`, then registry ones, verified first. */
+export declare function searchMcpServers(query: string, limit?: number): Promise<McpDirectoryServer[]>;
+/** One server by id: a saved one, else the registry's latest entry. */
+export declare function getMcpServer(id: string): Promise<McpDirectoryServer | undefined>;

package/dist/core/mcp-directory.js

@@ -0,0 +1,191 @@
+// Where the workflow planner finds MCP servers: the workspace's own saved
+// servers (mcp-servers.yml in the project root, or the file
+// LOOPENGINE_MCP_SERVERS_FILE names), then the official MCP Registry.
+// Only remote servers are offered: a local one from a public listing
+// would mean running someone else's code here without anyone choosing to.
+//
+//   servers:
+//     - id: acme-crm
+//       title: Acme CRM
+//       description: Our internal CRM
+//       url: https://mcp.acme.internal/mcp
+//       auth: { header: X-Api-Key }     # optional; default Authorization: Bearer
+//
+// A registry server counts as verified when its URL is on the domain its
+// registry name was verified for (com.stripe/mcp at mcp.stripe.com); the
+// rest are shown as unverified.
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+export const MCP_REGISTRY_URL_ENV = 'LOOPENGINE_MCP_REGISTRY_URL';
+export const MCP_SERVERS_FILE_ENV = 'LOOPENGINE_MCP_SERVERS_FILE';
+const DEFAULT_REGISTRY = 'https://registry.modelcontextprotocol.io';
+const CACHE_MS = 10 * 60 * 1000;
+function registryBase() {
+    const value = process.env[MCP_REGISTRY_URL_ENV]?.trim();
+    if (value === 'off')
+        return undefined;
+    return (value || DEFAULT_REGISTRY).replace(/\/+$/, '');
+}
+/** The workspace's saved servers. A malformed entry is skipped. */
+export function savedMcpServers() {
+    const path = resolve(process.cwd(), process.env[MCP_SERVERS_FILE_ENV]?.trim() || 'mcp-servers.yml');
+    if (!existsSync(path))
+        return [];
+    let raw;
+    try {
+        raw = parseYaml(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return [];
+    }
+    const list = raw?.servers;
+    return (Array.isArray(list) ? list : []).flatMap((s) => {
+        const e = (s ?? {});
+        if (typeof e.id !== 'string' || typeof e.url !== 'string' || !isRemoteUrl(e.url))
+            return [];
+        const auth = (e.auth ?? undefined);
+        return [{
+                id: e.id,
+                title: typeof e.title === 'string' ? e.title : e.id,
+                description: typeof e.description === 'string' ? e.description : '',
+                url: e.url,
+                transport: e.transport === 'sse' ? 'sse' : 'streamable-http',
+                source: 'saved',
+                verified: true,
+                ...(auth && (typeof auth.header === 'string' || typeof auth.prefix === 'string')
+                    ? { auth: { ...(typeof auth.header === 'string' ? { header: auth.header } : {}), ...(typeof auth.prefix === 'string' ? { prefix: auth.prefix } : {}) } }
+                    : {}),
+            }];
+    });
+}
+function isRemoteUrl(url) {
+    try {
+        const u = new URL(url);
+        const local = ['localhost', '127.0.0.1', '[::1]'].includes(u.hostname);
+        // A URL with a {placeholder} (a token in the path) needs filling in
+        // by hand, so it can't be connected to as listed.
+        return (u.protocol === 'https:' || (u.protocol === 'http:' && local)) && !/[{}]|%7B|%7D/i.test(url);
+    }
+    catch {
+        return false;
+    }
+}
+/** io.github.firecrawl/… → firecrawl: the GitHub organisation the
+ * registry verified the name for. */
+function githubOrg(name) {
+    const ns = name.split('/')[0];
+    return ns.startsWith('io.github.') ? ns.slice('io.github.'.length).toLowerCase() || undefined : undefined;
+}
+/** com.stripe/mcp → stripe.com; io.github.* names aren't domains. */
+function publisherDomain(name) {
+    const ns = name.split('/')[0];
+    if (!ns || ns.startsWith('io.github.'))
+        return undefined;
+    const parts = ns.split('.');
+    return parts.length >= 2 ? parts.reverse().join('.') : undefined;
+}
+/** Whether the server's URL is on its publisher's own domain: the
+ * domain a reverse-domain name was verified for, or, for a name verified
+ * through a GitHub organisation, a domain named like it
+ * (io.github.firecrawl at mcp.firecrawl.dev). */
+function onPublisherDomain(name, url) {
+    let host;
+    try {
+        host = new URL(url).hostname;
+    }
+    catch {
+        return false;
+    }
+    const domain = publisherDomain(name);
+    if (domain)
+        return host === domain || host.endsWith(`.${domain}`);
+    const org = githubOrg(name);
+    const labels = host.split('.');
+    return Boolean(org && labels.length >= 2 && labels[labels.length - 2] === org);
+}
+/** The publisher's own name: firecrawl for io.github.firecrawl, stripe for com.stripe. */
+function publisherLabel(name) {
+    return githubOrg(name) ?? publisherDomain(name)?.split('.')[0];
+}
+function fromRegistry(entry) {
+    const s = entry.server;
+    if (!s?.name)
+        return undefined;
+    const remotes = (s.remotes ?? []).filter((r) => typeof r.url === 'string' && isRemoteUrl(r.url) && (r.type === 'streamable-http' || r.type === 'sse'));
+    // Streamable HTTP when offered (the current transport), and the
+    // full-access endpoint before a read-only variant.
+    const remote = remotes.find((r) => r.type === 'streamable-http' && !/readonly|read-only/i.test(r.url)) ?? remotes.find((r) => r.type === 'streamable-http') ?? remotes[0];
+    if (!remote)
+        return undefined;
+    const icons = (s.icons ?? []).filter((i) => typeof i.src === 'string' && i.src.startsWith('https://'));
+    const icon = (icons.find((i) => i.mimeType === 'image/svg+xml') ?? icons[0])?.src;
+    return {
+        id: s.name,
+        title: s.title || s.name.split('/').pop() || s.name,
+        description: (s.description ?? '').slice(0, 300),
+        url: remote.url,
+        transport: remote.type === 'sse' ? 'sse' : 'streamable-http',
+        ...(s.websiteUrl ? { website: s.websiteUrl } : {}),
+        ...(icon ? { icon } : {}),
+        source: 'registry',
+        verified: onPublisherDomain(s.name, remote.url),
+    };
+}
+const searches = new Map();
+async function registrySearch(query) {
+    const base = registryBase();
+    if (!base || !query)
+        return [];
+    const key = `${base}\0${query.toLowerCase()}`;
+    const hit = searches.get(key);
+    if (hit && Date.now() - hit.at < CACHE_MS)
+        return hit.servers;
+    const url = `${base}/v0/servers?search=${encodeURIComponent(query)}&version=latest&limit=50`;
+    const res = await fetch(url, { signal: AbortSignal.timeout(10000), headers: { accept: 'application/json' } });
+    if (!res.ok)
+        throw new Error(`the MCP Registry answered ${res.status}`);
+    const body = (await res.json());
+    const seen = new Set();
+    const servers = (body.servers ?? []).flatMap((e) => {
+        const s = fromRegistry(e);
+        if (!s || seen.has(s.id))
+            return [];
+        seen.add(s.id);
+        return [s];
+    });
+    searches.set(key, { at: Date.now(), servers });
+    return servers;
+}
+/** Saved servers matching `query`, then registry ones, verified first. */
+export async function searchMcpServers(query, limit = 10) {
+    const q = query.trim().toLowerCase();
+    const words = q.split(/\s+/).filter(Boolean);
+    const saved = savedMcpServers().filter((s) => words.some((w) => `${s.id} ${s.title} ${s.description}`.toLowerCase().includes(w)));
+    let registry = [];
+    try {
+        // The registry matches names, so search on the first word ("linear
+        // issues" → "linear") when the whole phrase finds nothing.
+        registry = await registrySearch(q);
+        if (!registry.length && words.length > 1)
+            registry = await registrySearch(words[0]);
+    }
+    catch { }
+    const ranked = registry
+        .map((r) => ({ ...r, official: r.verified && words.includes(publisherLabel(r.id) ?? '') }))
+        .sort((a, b) => Number(b.official) - Number(a.official) || Number(b.verified) - Number(a.verified));
+    return [...saved, ...ranked.filter((r) => !saved.some((s) => s.url === r.url))].slice(0, limit);
+}
+/** One server by id: a saved one, else the registry's latest entry. */
+export async function getMcpServer(id) {
+    const saved = savedMcpServers().find((s) => s.id === id);
+    if (saved)
+        return saved;
+    const name = id.split('/').pop() ?? id;
+    try {
+        return (await registrySearch(name)).find((s) => s.id === id) ?? (await registrySearch(id)).find((s) => s.id === id);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/core/run-agent.js

@@ -19,6 +19,7 @@ import { recordUsage } from './usage.js';
 import { loadAgentModule } from './discover-agents.js';
 import { agentAsTool } from './agent-as-tool.js';
 import { loadGatewayToolsFromDir } from './gateway-tools.js';
+import { loadMcpAbilityTools } from './mcp-abilities.js';
 import { systemTools, createAskUserTool, createScheduleTools, CliQuestionHandler, isDurableQuestionHandler } from './system-tools/index.js';
 import { resolveHttpNotifier } from './http-notifier.js';
 import { CRASH_RECOVERY_CONTINUATION } from './session-store.js';
@@ -177,7 +178,9 @@ async function loadToolsFromDir(toolsDir) {
     return [];
 }
 export async function loadDefaultTools(config) {
-    return loadToolsFromDir(resolveAgentCodeDir(config.name, 'tools', true));
+    // MCP abilities' tools (core/mcp-abilities.ts) have no files in tools/,
+    // but are installed ability tools all the same, so they come with it.
+    return [...(await loadToolsFromDir(resolveAgentCodeDir(config.name, 'tools', true))), ...(await loadMcpAbilityTools(agentDirFor(config), config.name))];
 }
 /** Every other folder-form default in this file (loadDefaultTools,
  * loadRules, the skillsDirs default below) resolves against
@@ -210,7 +213,7 @@ export async function loadDefaultTools(config) {
  * gateway-tools.yml the way it opts out of the tools/ folder default. */
 async function resolveSubagentConfig(config, dir) {
     const resolved = { ...config };
-    const baseTools = resolved.tools === undefined ? await loadToolsFromDir(join(dir, 'tools')) : resolved.tools;
+    const baseTools = resolved.tools === undefined ? [...(await loadToolsFromDir(join(dir, 'tools'))), ...(await loadMcpAbilityTools(dir, config.name))] : resolved.tools;
     resolved.tools = [...baseTools, ...(await loadGatewayToolsFromDir(dir))];
     if (resolved.rules === undefined) {
         const rulesPath = join(dir, 'actauth.yml');

package/dist/core/system-agents/interviewer.d.ts

@@ -5,7 +5,7 @@ export type InterviewStage = (typeof INTERVIEW_STAGES)[number];
 export interface CandidateNeed {
     /** ability: a LoopEngine ability (name = its package). api: a system to
      * connect. key: a secret to add. messaging: an app for approvals. */
-    kind: 'ability' | 'api' | 'key' | 'messaging' | 'other';
+    kind: 'ability' | 'app' | 'api' | 'key' | 'messaging' | 'other';
     name?: string;
     description: string;
 }

package/dist/core/system-agents/interviewer.js

@@ -138,7 +138,7 @@ export function validateCandidate(raw) {
     const needs = Array.isArray(c.needs)
         ? c.needs.flatMap((n) => {
             const need = (n ?? {});
-            const needKind = ['ability', 'api', 'key', 'messaging', 'other'].includes(need.kind) ? need.kind : 'other';
+            const needKind = ['ability', 'app', 'api', 'key', 'messaging', 'other'].includes(need.kind) ? need.kind : 'other';
             const description = str(need.description, 300);
             return description ? [{ kind: needKind, ...(str(need.name, 120) ? { name: str(need.name, 120) } : {}), description }] : [];
         })

package/dist/core/system-agents/templates.d.ts

@@ -22,9 +22,20 @@ export interface TemplateSchedule {
     /** What the agent receives on each run. */
     message: string;
 }
+/** An app (core/mcp-apps.ts) a template works through, and the server
+ * tools it relies on: switched on when the agent is created, if the app is
+ * connected; otherwise connecting it heads the checklist. */
+export interface TemplateApp {
+    /** Its MCP Registry name, as in the Apps catalog. */
+    id: string;
+    title: string;
+    tools: string[];
+}
 export interface TemplateSetup {
     /** npm names of the abilities to install. */
     abilities: string[];
+    /** Apps it uses (connected on the Apps page). */
+    apps?: TemplateApp[];
     /** Keys the agent needs before it can work, from its abilities' declared
      * settings: a name, or a list where any one of them will do. */
     keys: (string | string[])[];