loopengine 0.1.98 → 0.2.0

package/dist/core/mcp-abilities.js

@@ -0,0 +1,400 @@
+// Abilities whose tools come from an MCP server instead of tool files.
+// The ability's loopengine.ability.json carries an `mcp` block (the
+// server, how to authenticate, and an allowlist of its tools); its
+// actauth rules and skills stay ordinary files, installed the usual way.
+// add-ability records the block in the agent's .loopengine-abilities.json;
+// at run time loadMcpAbilityTools turns each allowlisted server tool into
+// a plain ToolDefinition, so permissions, the planner and the console
+// treat it like any other ability tool.
+//
+// Tool schemas are cached in agents/<name>/.loopengine-mcp-cache.json
+// once fetched, so an agent loads without a server round trip; a server
+// connection is opened on first use and reused after that.
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport, getDefaultEnvironment } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+import { createAgentEnv } from './agent-env.js';
+const TOOL_NAME = /^[a-z][a-z0-9_]*$/;
+const DEFAULT_MAX_OUTPUT_CHARS = 20000;
+export class McpManifestError extends Error {
+}
+/** Checks an ability's `mcp` block and works out its installed tool
+ * names. Throws McpManifestError on anything unusable, so a bad
+ * manifest fails at add-ability, not on the agent's first run. */
+export function resolveMcpManifest(abilityName, mcp) {
+    if (!mcp || typeof mcp !== 'object')
+        throw new McpManifestError(`'mcp' must be an object.`);
+    const m = mcp;
+    if (!!m.url === !!m.command)
+        throw new McpManifestError(`'mcp' needs exactly one of 'url' (a remote server) or 'command' (a local one).`);
+    if (m.url) {
+        let parsed;
+        try {
+            parsed = new URL(m.url);
+        }
+        catch {
+            throw new McpManifestError(`'mcp.url' isn't a valid URL: ${m.url}`);
+        }
+        const local = ['localhost', '127.0.0.1', '[::1]'].includes(parsed.hostname);
+        if (parsed.protocol !== 'https:' && !(parsed.protocol === 'http:' && local)) {
+            throw new McpManifestError(`'mcp.url' must be https (http is only allowed for localhost).`);
+        }
+    }
+    if (m.transport && m.transport !== 'streamable-http' && m.transport !== 'sse')
+        throw new McpManifestError(`'mcp.transport' must be 'streamable-http' or 'sse'.`);
+    if (m.auth && m.auth.type !== 'none' && m.auth.type !== 'key') {
+        throw new McpManifestError(`'mcp.auth.type' must be 'none' or 'key' — OAuth isn't supported yet.`);
+    }
+    if (m.auth?.type === 'key' && !m.auth.env)
+        throw new McpManifestError(`'mcp.auth' of type 'key' needs 'env', the setting that holds the key.`);
+    if (m.defaults !== undefined) {
+        const ok = m.defaults && typeof m.defaults === 'object' && Object.values(m.defaults).every((d) => typeof d === 'string' || (d && typeof d === 'object' && typeof d.env === 'string' && (d.part === undefined || Number.isInteger(d.part))));
+        if (!ok)
+            throw new McpManifestError(`'mcp.defaults' maps input names to a "\${SETTING}" string or { env, split?, part? }.`);
+    }
+    if (!Array.isArray(m.tools) || m.tools.length === 0 || !m.tools.every((t) => typeof t === 'string' && t)) {
+        throw new McpManifestError(`'mcp.tools' must list the server tools to expose.`);
+    }
+    const prefix = m.prefix ?? abilityName.replace(/^@[^/]+\//, '').replace(/^lp-/, '');
+    const tools = m.tools.map((remote) => ({ name: mcpToolName(prefix, remote), remote }));
+    const seen = new Set();
+    for (const tool of tools) {
+        if (!TOOL_NAME.test(tool.name))
+            throw new McpManifestError(`'${tool.remote}' doesn't make a valid tool name (got '${tool.name}').`);
+        if (seen.has(tool.name))
+            throw new McpManifestError(`Two tools in 'mcp.tools' both become '${tool.name}'.`);
+        seen.add(tool.name);
+    }
+    const { tools: _tools, prefix: _prefix, ...server } = m;
+    return { server, tools };
+}
+/** An installed tool's name: `<prefix>_<tool>` in snake_case, or just the
+ * tool's own name when it already carries the prefix as a word
+ * (`web_search_exa` stays as is for prefix `exa`). */
+export function mcpToolName(prefix, remote) {
+    const own = snakeCase(remote);
+    const p = snakeCase(prefix);
+    return p && own.split('_').includes(p) ? own : snakeCase(`${prefix}_${remote}`);
+}
+function snakeCase(value) {
+    return value
+        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .replace(/[^A-Za-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .toLowerCase();
+}
+// ---- Settings ----
+/** `${NAME}` → the agent's setting. A missing setting is an error
+ * naming it, so the console's message says exactly what to add. */
+function interpolate(value, env) {
+    return value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, name) => env.require(name));
+}
+function interpolateAll(values, env) {
+    return Object.fromEntries(Object.entries(values ?? {}).map(([k, v]) => [k, interpolate(v, env)]));
+}
+function resolveServer(server, env) {
+    const headers = interpolateAll(server.headers, env);
+    if (server.auth?.type === 'key') {
+        const header = server.auth.header ?? 'Authorization';
+        const prefix = server.auth.prefix ?? (header.toLowerCase() === 'authorization' ? 'Bearer ' : '');
+        headers[header] = `${prefix}${env.require(server.auth.env)}`;
+    }
+    return {
+        url: server.url,
+        transport: server.transport,
+        headers,
+        command: server.command,
+        args: (server.args ?? []).map((a) => interpolate(a, env)),
+        env: interpolateAll(server.env, env),
+    };
+}
+// ---- Connections ----
+// One client per agent folder, ability and resolved settings — a
+// changed key gets a fresh connection instead of reusing the old one.
+const clients = new Map();
+function clientKey(dir, abilityName, server) {
+    return `${dir}\0${abilityName}\0${createHash('sha256').update(JSON.stringify(server)).digest('hex')}`;
+}
+async function connect(server) {
+    const client = new Client({ name: 'loopengine', version: '1.0.0' });
+    if (server.command) {
+        // getDefaultEnvironment is a small safe set (PATH, HOME, ...), not
+        // this process's whole environment, so a local server only sees the
+        // settings its manifest passes it.
+        await client.connect(new StdioClientTransport({ command: server.command, args: server.args, env: { ...getDefaultEnvironment(), ...server.env }, stderr: 'ignore' }));
+        return client;
+    }
+    const url = new URL(server.url);
+    const requestInit = { headers: server.headers };
+    if (server.transport === 'sse') {
+        await client.connect(new SSEClientTransport(url, { requestInit }));
+        return client;
+    }
+    await client.connect(new StreamableHTTPClientTransport(url, { requestInit }));
+    return client;
+}
+function getClient(dir, abilityName, server) {
+    const key = clientKey(dir, abilityName, server);
+    let client = clients.get(key);
+    if (!client) {
+        client = connect(server);
+        clients.set(key, client);
+        // A failed connect isn't kept, so the next call tries again.
+        client.catch(() => clients.delete(key));
+    }
+    return client;
+}
+function dropClient(dir, abilityName, server) {
+    const key = clientKey(dir, abilityName, server);
+    const client = clients.get(key);
+    clients.delete(key);
+    client?.then((c) => c.close()).catch(() => { });
+}
+/** Closes every open server connection (and stops local servers). */
+export async function closeMcpConnections() {
+    const open = [...clients.values()];
+    clients.clear();
+    await Promise.all(open.map((c) => c.then((client) => client.close()).catch(() => { })));
+}
+/** Whether a connection failed because the server wants (other)
+ * credentials: an HTTP 401/403, or the SDK's own UnauthorizedError. */
+export function isMcpAuthError(err) {
+    const code = err?.code;
+    if (code === 401 || code === 403)
+        return true;
+    const e = err;
+    return e?.name === 'UnauthorizedError' || /\b(401|403)\b|unauthori[sz]ed|forbidden/i.test(String(e?.message ?? ''));
+}
+/** Every tool a server offers, over a one-off connection (closed after).
+ * `server` is an `mcp` block without its allowlist; settings in it are
+ * read from `env`. */
+export async function listMcpServerTools(server, env) {
+    const client = await connect(resolveServer(server, env));
+    try {
+        const tools = [];
+        let cursor;
+        do {
+            const page = await client.listTools(cursor ? { cursor } : undefined);
+            for (const tool of page.tools) {
+                const hints = (tool.annotations ?? {});
+                tools.push({
+                    name: tool.name,
+                    description: tool.description ?? '',
+                    inputSchema: tool.inputSchema,
+                    ...(typeof hints.readOnlyHint === 'boolean' ? { readOnly: hints.readOnlyHint } : {}),
+                    ...(typeof hints.destructiveHint === 'boolean' ? { destructive: hints.destructiveHint } : {}),
+                });
+            }
+            cursor = page.nextCursor;
+        } while (cursor && tools.length < 500);
+        return tools;
+    }
+    finally {
+        await client.close().catch(() => { });
+    }
+}
+function cachePath(dir) {
+    return join(dir, '.loopengine-mcp-cache.json');
+}
+function readCache(dir) {
+    try {
+        return JSON.parse(readFileSync(cachePath(dir), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+function writeCache(dir, cache) {
+    writeFileSync(cachePath(dir), JSON.stringify(cache, null, 2) + '\n');
+}
+/** Drops an ability's cached schemas — add-ability and upgrade-ability
+ * call this so a new version's tools are fetched fresh. */
+export function clearMcpSchemaCache(dir, abilityName) {
+    if (!existsSync(cachePath(dir)))
+        return;
+    const cache = readCache(dir);
+    if (!(abilityName in cache))
+        return;
+    delete cache[abilityName];
+    writeCache(dir, cache);
+}
+/** Why an MCP ability's tools didn't load on the last attempt, by agent
+ * folder and ability — e.g. a key that isn't set yet. Cleared once they
+ * load. */
+const loadErrors = new Map();
+export function mcpAbilityLoadError(dir, abilityName) {
+    return loadErrors.get(`${dir}\0${abilityName}`);
+}
+/** Every tool of every MCP ability installed in `dir` (an agent's
+ * folder). An ability whose schemas aren't cached yet is connected to
+ * once to fetch them; if that fails (no key yet, server down) its tools
+ * are left out and the reason is kept for mcpAbilityLoadError, rather
+ * than failing the whole agent. */
+export async function loadMcpAbilityTools(dir, agentName) {
+    const provenancePath = join(dir, '.loopengine-abilities.json');
+    if (!existsSync(provenancePath))
+        return [];
+    let provenance;
+    try {
+        provenance = JSON.parse(readFileSync(provenancePath, 'utf8'));
+    }
+    catch {
+        return [];
+    }
+    const entries = Object.entries(provenance).filter((e) => !!e[1].mcp);
+    if (entries.length === 0)
+        return [];
+    const cache = readCache(dir);
+    let cacheChanged = false;
+    const tools = [];
+    for (const [abilityName, record] of entries) {
+        const errorKey = `${dir}\0${abilityName}`;
+        let cached = cache[abilityName]?.version === record.version ? cache[abilityName].tools : undefined;
+        if (!cached || record.mcp.tools.some((t) => !cached[t.remote])) {
+            try {
+                cached = await fetchSchemas(dir, abilityName, record.mcp, createAgentEnv(agentName, dir));
+                cache[abilityName] = { version: record.version, tools: cached };
+                cacheChanged = true;
+            }
+            catch (err) {
+                loadErrors.set(errorKey, err instanceof Error ? err.message : String(err));
+                continue;
+            }
+        }
+        loadErrors.delete(errorKey);
+        const env = createAgentEnv(agentName, dir);
+        for (const tool of record.mcp.tools) {
+            const schema = cached[tool.remote];
+            if (schema)
+                tools.push(toolDefinition(dir, abilityName, record.mcp, tool, schema, env));
+        }
+    }
+    if (cacheChanged)
+        writeCache(dir, cache);
+    return tools;
+}
+async function fetchSchemas(dir, abilityName, mcp, env) {
+    const server = resolveServer(mcp.server, env);
+    const client = await getClient(dir, abilityName, server);
+    const wanted = new Set(mcp.tools.map((t) => t.remote));
+    const found = {};
+    let cursor;
+    do {
+        const page = await client.listTools(cursor ? { cursor } : undefined);
+        for (const tool of page.tools) {
+            if (wanted.has(tool.name))
+                found[tool.name] = { description: tool.description ?? '', input_schema: tool.inputSchema };
+        }
+        cursor = page.nextCursor;
+    } while (cursor);
+    const missing = mcp.tools.filter((t) => !found[t.remote]).map((t) => t.remote);
+    if (missing.length === mcp.tools.length)
+        throw new Error(`The ${abilityName} server has none of the listed tools (${missing.join(', ')}).`);
+    if (missing.length)
+        console.warn(`[loopengine] ${abilityName}: the server has no tool named ${missing.join(', ')} — left out.`);
+    return found;
+}
+/** Each `defaults` entry's value from the agent's settings; a setting
+ * that isn't set (or a missing part) leaves that input without one. */
+function defaultValues(defaults, env) {
+    const out = {};
+    for (const [input, spec] of Object.entries(defaults ?? {})) {
+        let value;
+        if (typeof spec === 'string') {
+            let missing = false;
+            value = spec.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, name) => {
+                const v = env.get(name);
+                if (v === undefined)
+                    missing = true;
+                return v ?? '';
+            });
+            if (missing)
+                value = undefined;
+        }
+        else {
+            const raw = env.get(spec.env);
+            value = raw === undefined ? undefined : spec.split !== undefined ? raw.split(spec.split)[spec.part ?? 0] : raw;
+        }
+        if (value?.trim())
+            out[input] = value.trim();
+    }
+    return out;
+}
+/** The server's schema, with each input that has a default made optional
+ * and its description saying what it defaults to. */
+function withDefaults(schema, values) {
+    const properties = (schema.properties ?? {});
+    const names = Object.keys(values).filter((n) => n in properties);
+    if (!names.length)
+        return schema;
+    const props = { ...properties };
+    for (const n of names)
+        props[n] = { ...props[n], description: `${props[n].description ? `${props[n].description}. ` : ''}Defaults to ${values[n]}.` };
+    const required = Array.isArray(schema.required) ? schema.required.filter((r) => !names.includes(r)) : schema.required;
+    return { ...schema, properties: props, ...(required !== undefined ? { required } : {}) };
+}
+function toolDefinition(dir, abilityName, mcp, tool, schema, env) {
+    const maxChars = mcp.server.maxOutputChars ?? DEFAULT_MAX_OUTPUT_CHARS;
+    const properties = (schema.input_schema.properties ?? {});
+    return {
+        name: tool.name,
+        description: schema.description || tool.remote,
+        input_schema: env ? withDefaults(schema.input_schema, defaultValues(mcp.server.defaults, env)) : schema.input_schema,
+        async execute(input, ctx) {
+            const server = resolveServer(mcp.server, ctx.env);
+            const args = { ...input };
+            for (const [name, value] of Object.entries(defaultValues(mcp.server.defaults, ctx.env))) {
+                if (name in properties && (args[name] === undefined || args[name] === ''))
+                    args[name] = value;
+            }
+            const call = async () => (await getClient(dir, abilityName, server)).callTool({ name: tool.remote, arguments: args });
+            let result;
+            try {
+                result = await call();
+            }
+            catch (err) {
+                // A dropped connection (a restarted server, an expired session)
+                // gets one fresh retry; anything else is the tool's own error.
+                if (!isConnectionError(err))
+                    throw err;
+                dropClient(dir, abilityName, server);
+                result = await call();
+            }
+            const text = resultText(result);
+            if (result.isError)
+                throw new Error(text || `${tool.remote} failed`);
+            return text.length > maxChars ? `${text.slice(0, maxChars)}\n\n[cut off at ${maxChars} characters]` : text;
+        },
+    };
+}
+function isConnectionError(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return /closed|ECONNRESET|ECONNREFUSED|EPIPE|not connected|session/i.test(message);
+}
+/** A tool result as text for the model: structured content as JSON when
+ * the server gives it, otherwise the text parts, with anything else
+ * (images, audio) noted rather than dropped silently. */
+function resultText(result) {
+    if (result.structuredContent !== undefined)
+        return JSON.stringify(result.structuredContent);
+    if ('toolResult' in result)
+        return typeof result.toolResult === 'string' ? result.toolResult : JSON.stringify(result.toolResult);
+    const content = Array.isArray(result.content) ? result.content : [];
+    return content
+        .map((part) => {
+        if (part.type === 'text')
+            return String(part.text ?? '');
+        if (part.type === 'resource') {
+            const resource = part.resource;
+            return resource?.text ?? `[resource ${resource?.uri ?? ''}]`;
+        }
+        if (part.type === 'resource_link')
+            return `[link ${String(part.uri ?? '')}]`;
+        return `[${String(part.type)} omitted]`;
+    })
+        .join('\n\n');
+}

package/dist/core/mcp-ability-generator.d.ts

@@ -0,0 +1,59 @@
+import type { ModelCall } from './run-agent.js';
+import { type McpToolInfo } from './mcp-abilities.js';
+import type { McpDirectoryServer } from './mcp-directory.js';
+export type Decision = 'allow' | 'ask';
+export interface McpAbilityStep {
+    /** The step's place in the workflow (0-based). */
+    index: number;
+    title: string;
+    kind: 'tool' | 'ask' | 'approval' | 'other';
+    detail?: string;
+    /** The server tool the planner named, if it could see them. */
+    tool?: string;
+}
+export interface McpAbilityRequest {
+    server: McpDirectoryServer;
+    key?: string;
+    /** Steps the app is used for, to work out each one's tool (workflow
+     * builder); none when it's connected from the Apps page. */
+    workflow?: {
+        name: string;
+        summary: string;
+        steps: McpAbilityStep[];
+    };
+    /** Matches steps to tools and writes the skill; without one, steps
+     * match only by the tool the planner named, and the skill is plainer. */
+    modelCall?: ModelCall;
+}
+export interface GeneratedMcpAbility {
+    /** A temporary folder holding the ability package. */
+    dir: string;
+    /** Its package name, e.g. mcp-linear. */
+    name: string;
+    /** The setting its key is read from, when it uses one. */
+    keyEnv?: string;
+    /** Every tool, with its default permission. */
+    tools: {
+        name: string;
+        remote: string;
+        decision: Decision;
+    }[];
+    /** Step index → the server tool that does it. */
+    stepTools: Record<number, string>;
+}
+export declare class McpAbilityGenerationError extends Error {
+}
+/** Names for a server's ability: mcp-<slug>, tools <prefix>_<tool>, key <PREFIX>_MCP_KEY. */
+export declare function mcpAbilityNames(server: Pick<McpDirectoryServer, 'id' | 'title'>): {
+    name: string;
+    prefix: string;
+    keyEnv: string;
+};
+/** A tool's default permission: Allow for a read-only tool, Ask me for
+ * anything else. */
+export declare function defaultMcpDecision(tool: McpToolInfo): Decision;
+/** Builds the app's ability package from `request.server`. Throws
+ * McpAbilityGenerationError when the server can't be reached or used. */
+export declare function generateMcpAbility(request: McpAbilityRequest): Promise<GeneratedMcpAbility>;
+/** The name of an app ability's rule for one of its tools. */
+export declare function appRuleName(abilityName: string, toolName: string): string;

package/dist/core/mcp-ability-generator.js

@@ -0,0 +1,193 @@
+// Makes an app's ability from its MCP server: connects (with the key the
+// person gave, if any), lists every tool the server offers, gives each a
+// default permission, writes a skill, and lays it all out as an ability
+// package (the `mcp` block of core/mcp-abilities.ts, actauth rules, a
+// SKILL.md). The caller stores it as a workspace ability: the app, as the
+// Apps page shows it.
+//
+// The package lists every tool; an agent that adds the app chooses which
+// of them it gets and with what permission (installAbility's mcpTools).
+// For the workflow builder it also works out which tool does each step
+// the app is used for, so Create can add exactly those.
+//
+// Default permissions lean strict: a tool runs on its own only when the
+// server marks it read-only (or, with no mark, its name reads as a
+// lookup); anything else, and anything marked destructive, asks.
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { stringify as stringifyYaml } from 'yaml';
+import { isReadOnlyToolName } from './gateway-tools.js';
+import { isMcpAuthError, listMcpServerTools, mcpToolName } from './mcp-abilities.js';
+export class McpAbilityGenerationError extends Error {
+}
+function slug(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 30).replace(/-+$/, '') || 'server';
+}
+const snake = (value) => value.replace(/([a-z0-9])([A-Z])/g, '$1_$2').replace(/[^A-Za-z0-9]+/g, '_').replace(/^_+|_+$/g, '').toLowerCase();
+/** Names for a server's ability: mcp-<slug>, tools <prefix>_<tool>, key <PREFIX>_MCP_KEY. */
+export function mcpAbilityNames(server) {
+    const base = slug(server.title || server.id.split('/').pop() || server.id);
+    const prefix = snake(base);
+    return { name: `mcp-${base}`, prefix, keyEnv: `${prefix.toUpperCase()}_MCP_KEY` };
+}
+function isReadOnly(tool) {
+    return tool.readOnly ?? (tool.destructive ? false : isReadOnlyToolName(snake(tool.name)));
+}
+/** A tool's default permission: Allow for a read-only tool, Ask me for
+ * anything else. */
+export function defaultMcpDecision(tool) {
+    return tool.destructive || !isReadOnly(tool) ? 'ask' : 'allow';
+}
+function envWith(name, value) {
+    const get = (n) => (n === name ? value : undefined);
+    return {
+        get,
+        require(n) {
+            const v = get(n);
+            if (v === undefined)
+                throw new McpAbilityGenerationError(`${n} is needed`);
+            return v;
+        },
+    };
+}
+/** Builds the app's ability package from `request.server`. Throws
+ * McpAbilityGenerationError when the server can't be reached or used. */
+export async function generateMcpAbility(request) {
+    const { server } = request;
+    const steps = request.workflow?.steps ?? [];
+    const key = request.key?.trim() || undefined;
+    const names = mcpAbilityNames(server);
+    const keyEnv = key ? names.keyEnv : undefined;
+    const serverBlock = {
+        url: server.url,
+        ...(server.headers ? { headers: server.headers } : {}),
+        ...(server.transport === 'sse' ? { transport: 'sse' } : {}),
+        auth: keyEnv ? { type: 'key', env: keyEnv, ...(server.auth?.header ? { header: server.auth.header } : {}), ...(server.auth?.prefix !== undefined ? { prefix: server.auth.prefix } : {}) } : { type: 'none' },
+    };
+    let available;
+    try {
+        available = await listMcpServerTools(serverBlock, envWith(keyEnv, key));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (isMcpAuthError(err)) {
+            throw new McpAbilityGenerationError(key
+                ? `${server.title} turned down the key.`
+                : `${server.title} needs a key to connect (or a sign-in, which LoopEngine doesn't support yet). Add its API key and try again.`);
+        }
+        throw new McpAbilityGenerationError(`Couldn't connect to ${server.title} (${server.url}): ${message}`);
+    }
+    if (!available.length)
+        throw new McpAbilityGenerationError(`${server.title} offers no tools.`);
+    // Two server tools that would get the same installed name: keep the first.
+    const seen = new Set();
+    available = available.filter((t) => {
+        const installed = mcpToolName(names.prefix, t.name);
+        if (seen.has(installed))
+            return false;
+        seen.add(installed);
+        return true;
+    });
+    const byName = new Map(available.map((t) => [t.name, t]));
+    const choice = request.modelCall ? await chooseWithModel(request.modelCall, server, request.workflow, available).catch(() => undefined) : undefined;
+    const stepTools = {};
+    for (const step of steps) {
+        const picked = choice?.steps[step.index] ?? (step.tool && byName.has(step.tool) ? step.tool : undefined);
+        if (picked && byName.has(picked))
+            stepTools[step.index] = picked;
+    }
+    const toolName = (remote) => mcpToolName(names.prefix, remote);
+    const tools = available.map((t) => ({ name: toolName(t.name), remote: t.name, decision: defaultMcpDecision(t) }));
+    // The model writes the server's own tool names; the agent sees the installed ones.
+    let skillBody = choice?.skill.body || plainSkill(server, tools, byName);
+    for (const t of tools) {
+        if (t.remote !== t.name)
+            skillBody = skillBody.replace(new RegExp(`(?<![A-Za-z0-9_])${t.remote.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![A-Za-z0-9_])`, 'g'), t.name);
+    }
+    const skillDescription = choice?.skill.description || `How to use ${server.title} (its MCP server): which tool does what, and when to ask first.`;
+    const dir = mkdtempSync(join(tmpdir(), 'loopengine-mcp-generated-'));
+    const skillId = slug(names.prefix);
+    mkdirSync(join(dir, 'actauth'), { recursive: true });
+    mkdirSync(join(dir, 'skills', skillId), { recursive: true });
+    writeFileSync(join(dir, 'package.json'), JSON.stringify({
+        name: names.name,
+        version: '1.0.0',
+        description: `${server.title}${server.description ? `: ${server.description}` : ''} (made from its MCP server)`.slice(0, 300),
+        private: true,
+        keywords: ['loopengine-ability', 'mcp'],
+    }, null, 2) + '\n');
+    writeFileSync(join(dir, 'loopengine.ability.json'), JSON.stringify({
+        loopengineVersion: '>=0.1.99',
+        mcp: { ...serverBlock, tools: tools.map((t) => t.remote), prefix: names.prefix },
+        skills: [`skills/${skillId}`],
+        actauth: 'actauth/rules.yml',
+        env: keyEnv ? [{ name: keyEnv, description: `API key for ${server.title}'s MCP server`, secret: true, scope: 'overridable' }] : [],
+        generatedFrom: { server: server.id, url: server.url, source: server.source },
+    }, null, 2) + '\n');
+    writeFileSync(join(dir, 'actauth', 'rules.yml'), stringifyYaml(tools.map((t) => ({ name: appRuleName(names.name, t.name), scope: '*/*', tool: t.name, decision: t.decision }))));
+    writeFileSync(join(dir, 'skills', skillId, 'SKILL.md'), `---\nname: ${skillId}\ndescription: ${JSON.stringify(skillDescription.slice(0, 300))}\n---\n\n${skillBody.trim()}\n`);
+    return { dir, name: names.name, ...(keyEnv ? { keyEnv } : {}), tools, stepTools };
+}
+/** The name of an app ability's rule for one of its tools. */
+export function appRuleName(abilityName, toolName) {
+    return `${abilityName}-${toolName.replace(/_/g, '-')}`.slice(0, 80);
+}
+const PLAIN_SKILL_TOOLS = 30;
+function plainSkill(server, tools, byName) {
+    const shown = tools.slice(0, PLAIN_SKILL_TOOLS);
+    const lines = shown.map((t) => `- \`${t.name}\`: ${(byName.get(t.remote)?.description || t.remote).split('\n')[0].slice(0, 160)}`);
+    const more = tools.length > shown.length ? `\n\n…and ${tools.length - shown.length} more; each tool's description says what it does.` : '';
+    return `# ${server.title}\n\nTools from ${server.title}'s MCP server. You only have the ones this agent was given.\n\n${lines.join('\n')}${more}\n\nUse the search and lookup tools to find exact ids before creating or changing anything. A tool set to ask waits for a person's OK.`;
+}
+const CHOOSER_PROMPT = `You set up an app's MCP server for LoopEngine agents.
+
+You get the app, every tool its server offers (with its hints: readOnly, destructive), and, when it's being set up for a workflow, the steps that use it. Call save_ability once with:
+- steps: for each step listed, the one server tool that does it (its exact name). Empty when no steps are listed.
+- skill: a short general guide to using this app's tools well (under 1200 characters): which tool to use for what, what ids to look up first, and that tools set to ask wait for a person. Agents are given only some of the tools, so don't rely on any one being there. description: one sentence.`;
+const CHOOSER_TOOL = {
+    name: 'save_ability',
+    description: 'Save the tool for each step, and the skill. Call once.',
+    input_schema: {
+        type: 'object',
+        properties: {
+            steps: { type: 'array', items: { type: 'object', properties: { step: { type: 'number' }, tool: { type: 'string' } }, required: ['step', 'tool'] } },
+            skill: { type: 'object', properties: { description: { type: 'string' }, body: { type: 'string' } }, required: ['description', 'body'] },
+        },
+        required: ['steps', 'skill'],
+    },
+};
+async function chooseWithModel(modelCall, server, workflow, available) {
+    const toolList = available.slice(0, 200).map((t) => ({
+        name: t.name,
+        description: t.description.split('\n')[0].slice(0, 240),
+        ...(t.readOnly !== undefined ? { readOnly: t.readOnly } : {}),
+        ...(t.destructive ? { destructive: true } : {}),
+    }));
+    const content = [
+        `App: ${server.title} (${server.url})`,
+        workflow?.steps.length
+            ? `Workflow: ${workflow.name}: ${workflow.summary}\n\nSteps that use it:\n${workflow.steps.map((s) => `- step ${s.index}: ${s.title}${s.detail ? `: ${s.detail}` : ''}${s.kind === 'approval' ? ' (a person approves first)' : ''}${s.tool ? ` (planner suggested ${s.tool})` : ''}`).join('\n')}`
+            : 'No workflow: the app is being connected for the workspace. Leave steps empty.',
+        `Its tools:\n${JSON.stringify(toolList)}`,
+    ].join('\n\n');
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const response = await modelCall([{ role: 'user', content: attempt ? `${content}\n\nCall save_ability now.` : content }], CHOOSER_PROMPT, [CHOOSER_TOOL]);
+        const call = response.content.find((b) => b.type === 'tool_use' && b.name === 'save_ability');
+        if (!call)
+            continue;
+        const input = (call.input ?? {});
+        const steps = {};
+        for (const s of Array.isArray(input.steps) ? input.steps : []) {
+            const e = (s ?? {});
+            if (typeof e.step === 'number' && typeof e.tool === 'string')
+                steps[e.step] = e.tool;
+        }
+        const skill = (input.skill ?? {});
+        return {
+            steps,
+            skill: { description: typeof skill.description === 'string' ? skill.description : '', body: typeof skill.body === 'string' ? skill.body.slice(0, 4000) : '' },
+        };
+    }
+    return undefined;
+}