@kammcs/buildit-mcp 0.0.0-stage → 0.2.0

package/dist/api/operations.js

@@ -0,0 +1,43 @@
+import { ToolInputError } from '../errors.js';
+import { OPERATIONS } from './generated/operations.js';
+/** A path segment that would climb or stay in place once the URL is resolved. */
+const DOT_SEGMENT = /^\.{1,2}$/;
+/**
+ * Fills in the path's placeholders. A value is URL-encoded, so it stays one
+ * segment; a value that is "." or "..", or has such a segment between
+ * slashes, is refused (ToolInputError) because the URL would resolve it
+ * into another route.
+ */
+export function operationPath(id, values = {}) {
+    return OPERATIONS[id].path.replace(/\{(\w+)\}/g, (_match, name) => {
+        const value = values[name];
+        if (value === undefined)
+            throw new Error(`${id}: missing path parameter ${name}`);
+        if (value.split(/[/\\]/).some((segment) => DOT_SEGMENT.test(segment))) {
+            throw new ToolInputError(`${name} can't be "." or "..", or contain such a part between slashes. Use the name or id as listed.`);
+        }
+        return encodeURIComponent(value);
+    });
+}
+/** Calls one operation and parses its response with the generated (tolerant) schema. */
+export async function callOperation(api, id, args, options) {
+    const op = OPERATIONS[id];
+    // The API lists what it serves from 1.1.0; an operation it leaves out would answer 404.
+    const served = api.served;
+    if (served?.operations !== undefined && !served.operations.has(id)) {
+        throw new ToolInputError(`This buildIt.Social server (API ${served.apiVersion}) doesn't serve ${id} yet, which this needs. Tell the person: it works once their buildIt.Social server is updated; until then they can do it in the app.`);
+    }
+    const path = operationPath(id, args.path);
+    const query = args.query;
+    const body = args.body;
+    const schema = op.response;
+    return api.requestParsed(op.method, path, schema, {
+        ...options,
+        // Logged instead of the filled-in path, which can carry names.
+        operation: id,
+        pathTemplate: op.path,
+        ...(query === undefined ? {} : { query }),
+        // A POST without a body still sends an empty object, which the contract expects.
+        ...(body === undefined ? (op.hasBody ? { body: {} } : {}) : { body }),
+    });
+}

package/dist/config.js

@@ -0,0 +1,280 @@
+/**
+ * Configuration from environment variables and command-line flags.
+ *
+ * Flags win over environment variables. The token is only ever read from the
+ * environment (a flag would be visible to other processes), and no message
+ * produced here ever contains it.
+ */
+import { parseArgs } from 'node:util';
+import { LOG_LEVELS, scrubString } from './log.js';
+import { DEFAULT_TOOLSETS, isToolsetName, TOOLSET_NAMES, } from './toolsets/toolsets.js';
+export const DEFAULT_API_URL = 'https://api.buildit.social/functions/v1/agent-api';
+export const DEFAULT_HTTP_HOST = '127.0.0.1';
+export const DEFAULT_HTTP_PORT = 8765;
+export class ConfigError extends Error {
+    name = 'ConfigError';
+}
+export const USAGE = `Usage: buildit-mcp [options]
+
+An MCP server for buildIt.Social. By default it serves one person over stdio,
+with the personal access token in the BUILDIT_TOKEN environment variable.
+
+Options (each also has an environment variable):
+  --api-url <url>           BUILDIT_API_URL           Agent API base URL
+                                                      (default ${DEFAULT_API_URL})
+  --toolsets <list>         BUILDIT_TOOLSETS          Comma-separated toolsets, or "all"
+                                                      (default ${DEFAULT_TOOLSETS.join(',')};
+                                                      known: ${TOOLSET_NAMES.join(', ')})
+  --read-only               BUILDIT_READ_ONLY=true    Only list tools that change nothing
+  --exclude-tools <list>    BUILDIT_EXCLUDE_TOOLS     Comma-separated tool names to hide
+  --log-level <level>       BUILDIT_LOG_LEVEL         ${LOG_LEVELS.join(', ')} (default info)
+  --http                    BUILDIT_HTTP=true         Serve Streamable HTTP instead of stdio
+  --host <host>             BUILDIT_HOST              HTTP bind address (default ${DEFAULT_HTTP_HOST})
+  --port <port>             BUILDIT_PORT              HTTP port (default ${DEFAULT_HTTP_PORT})
+  --allowed-hosts <list>    BUILDIT_ALLOWED_HOSTS     Hostnames accepted in the Host header
+  --allowed-origins <list>  BUILDIT_ALLOWED_ORIGINS   Hostnames accepted in the Origin header
+  --allow-any-host          BUILDIT_ALLOW_ANY_HOST=true
+                                                      Off loopback, serve without checking the
+                                                      Host header (otherwise BUILDIT_ALLOWED_HOSTS
+                                                      is required there)
+  -h, --help                                          Show this help
+  -v, --version                                       Show the version
+
+The token is never accepted as a flag. In stdio mode set BUILDIT_TOKEN; in HTTP
+mode every request carries its own "Authorization: Bearer <token>" header.
+`;
+const TRUE_VALUES = new Set(['1', 'true', 'yes', 'on']);
+const FALSE_VALUES = new Set(['0', 'false', 'no', 'off', '']);
+export function parseBoolean(name, raw, fallback) {
+    if (raw === undefined)
+        return fallback;
+    const value = raw.trim().toLowerCase();
+    if (TRUE_VALUES.has(value))
+        return true;
+    if (FALSE_VALUES.has(value))
+        return false;
+    throw new ConfigError(`${name} must be true or false (got "${raw}").`);
+}
+function splitList(raw) {
+    return [
+        ...new Set(raw
+            .split(',')
+            .map((s) => s.trim())
+            .filter((s) => s.length > 0)),
+    ];
+}
+/** Parses a toolset list such as "items,comments" or "all". Throws ConfigError on unknown names. */
+export function parseToolsets(raw, source = 'BUILDIT_TOOLSETS') {
+    const names = splitList(raw.toLowerCase());
+    if (names.length === 0)
+        return [...DEFAULT_TOOLSETS];
+    if (names.includes('all'))
+        return [...TOOLSET_NAMES];
+    const unknown = names.filter((n) => !isToolsetName(n));
+    if (unknown.length > 0) {
+        throw new ConfigError(`${source} has unknown toolset(s): ${unknown.join(', ')}. Known toolsets: ${TOOLSET_NAMES.join(', ')}, or "all".`);
+    }
+    // Keep the canonical order so the tool list doesn't depend on how the list was written.
+    return TOOLSET_NAMES.filter((n) => names.includes(n));
+}
+const TOOL_NAME = /^[a-z][a-z0-9_]{0,63}$/;
+function parseToolNames(raw, source) {
+    const names = splitList(raw.toLowerCase());
+    const bad = names.filter((n) => !TOOL_NAME.test(n));
+    if (bad.length > 0) {
+        throw new ConfigError(`${source} has invalid tool name(s): ${bad.join(', ')}. Tool names are lowercase letters, digits and underscores.`);
+    }
+    return names;
+}
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
+export function isLoopbackHost(host) {
+    return LOOPBACK_HOSTS.has(host.toLowerCase());
+}
+export function parseApiUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw.trim());
+    }
+    catch {
+        throw new ConfigError(`BUILDIT_API_URL is not a valid URL (got "${raw}").`);
+    }
+    if (url.username || url.password) {
+        throw new ConfigError('BUILDIT_API_URL must not contain credentials.');
+    }
+    if (url.search || url.hash) {
+        throw new ConfigError('BUILDIT_API_URL must not have a query string or fragment.');
+    }
+    const loopback = isLoopbackHost(url.hostname);
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)) {
+        throw new ConfigError('BUILDIT_API_URL must use https:// (plain http:// is only allowed for localhost).');
+    }
+    return url.toString().replace(/\/+$/, '');
+}
+const HOSTNAME = /^(\[[0-9a-f:.]+\]|[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*)$/;
+const EXTENSION_ORIGIN = /^[a-z][a-z0-9+.-]*:\/\/\*$/;
+/** Normalises a host or origin entry to the bare hostname the SDK's validators compare. */
+function normaliseHostEntry(entry, source, allowSchemeWildcard) {
+    const value = entry.toLowerCase();
+    if (allowSchemeWildcard && EXTENSION_ORIGIN.test(value)) {
+        if (value === 'http://*' || value === 'https://*') {
+            throw new ConfigError(`${source}: "${entry}" would allow every web page; list hostnames.`);
+        }
+        return value;
+    }
+    let host;
+    if (value.includes('://')) {
+        try {
+            host = new URL(value).hostname;
+        }
+        catch {
+            throw new ConfigError(`${source}: "${entry}" is not a valid origin.`);
+        }
+    }
+    else if (!value.startsWith('[')) {
+        host = value.replace(/:\d+$/, '');
+    }
+    else {
+        host = value.replace(/\]:\d+$/, ']');
+    }
+    if (host === '::1')
+        host = '[::1]';
+    if (!HOSTNAME.test(host)) {
+        throw new ConfigError(`${source}: "${entry}" is not a valid hostname.`);
+    }
+    return host;
+}
+function parseHostList(raw, source, allowSchemeWildcard) {
+    return [
+        ...new Set(splitList(raw).map((e) => normaliseHostEntry(e, source, allowSchemeWildcard))),
+    ];
+}
+function parsePort(raw) {
+    const value = raw.trim();
+    if (!/^\d+$/.test(value))
+        throw new ConfigError(`The port must be a number (got "${raw}").`);
+    const port = Number(value);
+    if (port > 65535)
+        throw new ConfigError(`The port must be at most 65535 (got ${port}).`);
+    return port;
+}
+function parseLogLevel(raw) {
+    const value = raw.trim().toLowerCase();
+    if (LOG_LEVELS.includes(value))
+        return value;
+    throw new ConfigError(`The log level must be one of ${LOG_LEVELS.join(', ')} (got "${raw}").`);
+}
+function nonEmpty(value) {
+    return value === undefined || value.trim() === '' ? undefined : value;
+}
+/**
+ * Parses flags and environment variables. Throws ConfigError with a message
+ * that is safe to print (it never contains the token).
+ */
+export function parseCli(argv, env) {
+    const secrets = env.BUILDIT_TOKEN ? [env.BUILDIT_TOKEN] : [];
+    if (argv.some((a) => a === '--token' || a.startsWith('--token='))) {
+        throw new ConfigError('The token is never accepted as a flag (other processes can read flags). Set the BUILDIT_TOKEN environment variable instead.');
+    }
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args: [...argv],
+            strict: true,
+            allowPositionals: false,
+            options: {
+                'api-url': { type: 'string' },
+                toolsets: { type: 'string' },
+                'read-only': { type: 'boolean' },
+                'exclude-tools': { type: 'string' },
+                'log-level': { type: 'string' },
+                http: { type: 'boolean' },
+                host: { type: 'string' },
+                port: { type: 'string' },
+                'allowed-hosts': { type: 'string' },
+                'allowed-origins': { type: 'string' },
+                'allow-any-host': { type: 'boolean' },
+                help: { type: 'boolean', short: 'h' },
+                version: { type: 'boolean', short: 'v' },
+            },
+        }));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new ConfigError(`${scrubString(message, secrets)} Run with --help for the options.`);
+    }
+    if (values.help === true)
+        return { kind: 'help' };
+    if (values.version === true)
+        return { kind: 'version' };
+    const str = (flag, envName) => {
+        const fromFlag = values[flag];
+        return typeof fromFlag === 'string' ? fromFlag : nonEmpty(env[envName]);
+    };
+    const warnings = [];
+    const http = values.http === true || parseBoolean('BUILDIT_HTTP', env.BUILDIT_HTTP, false);
+    const mode = http ? 'http' : 'stdio';
+    const apiUrl = parseApiUrl(str('api-url', 'BUILDIT_API_URL') ?? DEFAULT_API_URL);
+    const toolsetsRaw = str('toolsets', 'BUILDIT_TOOLSETS');
+    const toolsets = toolsetsRaw === undefined ? [...DEFAULT_TOOLSETS] : parseToolsets(toolsetsRaw);
+    const readOnly = values['read-only'] === true || parseBoolean('BUILDIT_READ_ONLY', env.BUILDIT_READ_ONLY, false);
+    const excludeRaw = str('exclude-tools', 'BUILDIT_EXCLUDE_TOOLS');
+    const excludeTools = excludeRaw === undefined ? [] : parseToolNames(excludeRaw, 'BUILDIT_EXCLUDE_TOOLS');
+    const logLevelRaw = str('log-level', 'BUILDIT_LOG_LEVEL');
+    const logLevel = logLevelRaw === undefined ? 'info' : parseLogLevel(logLevelRaw);
+    const host = (str('host', 'BUILDIT_HOST') ?? DEFAULT_HTTP_HOST).trim();
+    if (host === '')
+        throw new ConfigError('The HTTP host must not be empty.');
+    const portRaw = str('port', 'BUILDIT_PORT');
+    const port = portRaw === undefined ? DEFAULT_HTTP_PORT : parsePort(portRaw);
+    const hostsRaw = str('allowed-hosts', 'BUILDIT_ALLOWED_HOSTS');
+    const originsRaw = str('allowed-origins', 'BUILDIT_ALLOWED_ORIGINS');
+    const httpConfig = { host, port };
+    if (hostsRaw !== undefined) {
+        httpConfig.allowedHosts = parseHostList(hostsRaw, 'BUILDIT_ALLOWED_HOSTS', false);
+    }
+    if (originsRaw !== undefined) {
+        httpConfig.allowedOrigins = parseHostList(originsRaw, 'BUILDIT_ALLOWED_ORIGINS', true);
+    }
+    let token;
+    const rawToken = env.BUILDIT_TOKEN;
+    if (mode === 'stdio') {
+        if (rawToken === undefined || rawToken.trim() === '') {
+            throw new ConfigError('BUILDIT_TOKEN is not set. Create a personal access token in buildIt.Social and put it in the BUILDIT_TOKEN environment variable (never in a file you commit).');
+        }
+        token = rawToken.trim();
+        if (/\s/.test(token)) {
+            throw new ConfigError('BUILDIT_TOKEN contains whitespace; check that it was copied whole.');
+        }
+        if (!token.startsWith('buildit_pat_')) {
+            warnings.push('BUILDIT_TOKEN does not start with "buildit_pat_"; buildIt.Social personal access tokens do.');
+        }
+    }
+    else {
+        if (rawToken !== undefined && rawToken.trim() !== '') {
+            warnings.push('BUILDIT_TOKEN is ignored in HTTP mode: each request must carry its own Authorization header.');
+        }
+        if (!isLoopbackHost(host) && httpConfig.allowedHosts === undefined) {
+            const anyHost = values['allow-any-host'] === true ||
+                parseBoolean('BUILDIT_ALLOW_ANY_HOST', env.BUILDIT_ALLOW_ANY_HOST, false);
+            if (!anyHost) {
+                throw new ConfigError(`Binding to ${host} needs BUILDIT_ALLOWED_HOSTS (or --allowed-hosts): the hostnames clients use, so the Host header can be checked. To serve without that check (for example behind a proxy that checks it), set BUILDIT_ALLOW_ANY_HOST=true or pass --allow-any-host.`);
+            }
+            httpConfig.allowAnyHost = true;
+            warnings.push(`Binding to ${host} without BUILDIT_ALLOWED_HOSTS, as BUILDIT_ALLOW_ANY_HOST asks: the Host header is not checked.`);
+        }
+    }
+    return {
+        kind: 'run',
+        config: {
+            mode,
+            apiUrl,
+            ...(token === undefined ? {} : { token }),
+            toolsets,
+            readOnly,
+            excludeTools,
+            http: httpConfig,
+            logLevel,
+            warnings,
+        },
+    };
+}

package/dist/errors.js

@@ -0,0 +1,347 @@
+import { ApiError, LOCAL_ERROR_CODES } from './api/client.js';
+import { ERROR_HINTS } from './api/generated/operations.js';
+import { scrubString } from './log.js';
+import { neutralize, sanitizeLabel, wrapUntrusted } from './untrusted.js';
+const MAX_DETAILS_CHARS = 4000;
+/**
+ * Arguments that pass the input schema but can't make a valid call (for
+ * example two options that exclude each other). The text says how to fix
+ * the call; nothing was sent to the API.
+ */
+export class ToolInputError extends Error {
+    name = 'ToolInputError';
+    code = 'invalid_arguments';
+}
+/**
+ * What to do, for the codes this server makes itself. The API's own codes
+ * come with a hint (the error envelope's `hint`); for an older API that
+ * sends none, the contract's wording (ERROR_HINTS, generated) is used.
+ */
+const LOCAL_HINTS = {
+    http_401: 'The token was refused. Ask the person to check it in buildIt.Social, under Settings → Agent tokens (it may be expired, revoked, or suspended by the org).',
+    http_403: 'The token or its owner may not do this. Do not retry the same call.',
+    http_429: 'Too many calls. Wait a little, then retry.',
+    invalid_arguments: 'Fix the arguments as described, then call the tool again.',
+    [LOCAL_ERROR_CODES.timeout]: 'The API was slow to answer. Retry once; if it fails again, stop.',
+    [LOCAL_ERROR_CODES.network]: 'The API could not be reached. Retry later.',
+    [LOCAL_ERROR_CODES.invalidResponse]: 'This server may be older than the API. Ask the person to update buildit-mcp.',
+};
+/**
+ * Notes that put the API's advice in this server's terms (its tools and
+ * settings), shown after the hint, only where they add something: none when
+ * the hint or the details already say it.
+ */
+const NEW_PLAN_NOTE = "In this server, that means calling the same propose_* tool again. Then show the person the new preview and wait for their yes before apply_plan: their yes to the old plan doesn't carry over.";
+const TOOL_NOTES = {
+    token_invalid: () => 'In this server the token comes from BUILDIT_TOKEN (or the Authorization header in HTTP mode).',
+    // The details list the token's scopes; without them, whoami does.
+    scope_missing: (d) => Array.isArray(d.granted) ? undefined : 'whoami lists the scopes this token has.',
+    validation: () => 'describe_project lists the allowed statuses, types, labels, fields and estimates.',
+    conflict: (d) => d.kind === 'page'
+        ? 'get_page reads the current text and version.'
+        : d.kind === 'item' || d.kind === 'description'
+            ? 'get_item reads the current item, version and description_version.'
+            : undefined,
+    // An eval agent re-proposed after plan_expired and applied the new plan
+    // without asking: a yes is for the plan the person saw.
+    plan_stale: () => NEW_PLAN_NOTE,
+    plan_expired: () => NEW_PLAN_NOTE,
+};
+/**
+ * What to do about a not_found, by the kind of thing that wasn't found, in
+ * this server's tools. The API's own hint names the item and project tools
+ * whatever the kind.
+ */
+const NOT_FOUND_HINTS = {
+    project: 'whoami lists the project keys in reach (list_projects too); check the key, then retry.',
+    item: 'Check the key with search_items (the item may have moved or been deleted), then retry.',
+    initiative: 'Check the key with search_items, then retry.',
+    status: "describe_project lists the project's statuses by workflow; use one of those names.",
+    type: "describe_project lists the project's types; use one of those names.",
+    label: "describe_project lists the project's labels; use one of those names.",
+    field: "describe_project lists the project's fields; use one of those names.",
+    option: "describe_project lists each field's options; use one of those.",
+    workflow: "describe_project lists the project's workflows; use one of those names.",
+    user: 'find_users lists the people of the project; use an email or "me".',
+    sprint: 'list_sprints lists the project\'s sprints; name one by number, name or "active".',
+    release: "list_releases lists the project's releases; use one of those names.",
+    link: "get_item lists the item's links; unlink only one that is listed.",
+    comment: "list_comments lists the item's comments and their ids.",
+    page: "list_pages lists a channel's pages and their ids.",
+    channel: 'list_channels lists the channels in reach; use one of those names.',
+    message: 'read_channel lists the messages of a channel and their ids.',
+    plan: 'Use a handle a propose_* tool returned in this conversation, or propose the change again.',
+    route: 'The API does not serve this call: it may be older than this buildit-mcp. Check BUILDIT_API_URL, or use another tool.',
+};
+/**
+ * Each of the contract's rate-limit buckets, in plain words. A bucket the
+ * contract adds later is shown by retry_after alone, as the contract asks.
+ */
+const RATE_BUCKETS = {
+    token_requests_per_minute: 'requests per minute for this token',
+    token_writes_per_minute: 'writes per minute for this token',
+    token_writes_per_day: 'writes per day for this token',
+    org_requests_per_minute: 'requests per minute for the whole org, across all its tokens',
+    user_requests_per_minute: 'requests per minute for your account, across all your tokens',
+};
+/** The release operations, as plan_release's actions. */
+const RELEASE_ACTIONS = {
+    create_release: 'create',
+    release_version: 'release',
+    update_release: 'update',
+    reopen_release: 'reopen',
+    archive_release: 'archive',
+    restore_release: 'restore',
+};
+/** The API's own terms, as this server names them. */
+function inServerTerms(hint) {
+    return hint
+        .replace(/\bget_me\b/g, 'whoami')
+        .replace(/\b(create_release|release_version|update_release|reopen_release|archive_release|restore_release)\b/g, (op) => `plan_release (action "${RELEASE_ACTIONS[op] ?? op}")`);
+}
+/** The next step for an error: the API's hint, else the contract's, else this server's own. */
+export function hintFor(code, apiHint) {
+    return apiHint ?? ERROR_HINTS[code] ?? LOCAL_HINTS[code];
+}
+/** Lower case letters and digits only, to tell whether one text already says another. */
+function squash(text) {
+    return text.toLowerCase().replace(/[^a-z0-9]+/g, '');
+}
+/** Whether a sentence points at the wait (details.retry_after, the Retry-After header). */
+const RETRY_ADVICE = /retry[_-]after/i;
+/**
+ * A rate-limit message without its pointer to the wait, which the
+ * "Retry after" line gives in seconds: "Too many requests. Retry after the
+ * number of seconds in details.retry_after ..." becomes "Too many requests.".
+ */
+function withoutRetryAdvice(message) {
+    const kept = message
+        .split(/(?<=[.!?])\s+/)
+        .filter((sentence) => !RETRY_ADVICE.test(sentence))
+        .join(' ')
+        .trim();
+    return kept === '' ? 'Too many requests.' : kept;
+}
+/** Whether `text` adds nothing to what `shown` already says. */
+function alreadySaid(text, shown) {
+    const t = squash(text);
+    return t === '' || shown.some((s) => squash(s).includes(t));
+}
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function str(value) {
+    if (value === undefined)
+        return 'unknown';
+    return typeof value === 'string' ? sanitizeLabel(value, 300) : JSON.stringify(value);
+}
+function list(value) {
+    return Array.isArray(value) ? value.map(str).join(', ') || 'none' : str(value);
+}
+function formatValue(value) {
+    if (Array.isArray(value) && value.every((v) => typeof v === 'string' || typeof v === 'number')) {
+        return value.join(', ');
+    }
+    if (typeof value === 'string')
+        return value;
+    return JSON.stringify(value);
+}
+/** Code-specific renderings of the details, so the agent reads what matters. */
+function formatKnownDetails(code, d) {
+    switch (code) {
+        case 'ambiguous': {
+            const candidates = Array.isArray(d.candidates) ? d.candidates : [];
+            return [
+                `- ${str(d.kind)} "${str(d.ref)}" matches:`,
+                ...candidates.map((c) => {
+                    const r = record(c);
+                    return `  - ${str(r?.label)} (id ${str(r?.id)})`;
+                }),
+            ];
+        }
+        case 'conflict': {
+            const current = record(d.current) ?? {};
+            const parts = Object.entries(current).map(([k, v]) => `${k} ${str(v)}`);
+            return [`- ${str(d.kind)} changed; current: ${parts.join(', ') || 'unknown'}`];
+        }
+        case 'transition_not_allowed': {
+            const moves = Array.isArray(d.moves) ? d.moves.map(record) : undefined;
+            return [
+                `- from: ${str(d.from)}`,
+                `- asked for: ${str(d.to)}`,
+                ...(moves
+                    ? [
+                        `- moves allowed from here: ${moves
+                            .map((m) => {
+                            const needs = Array.isArray(m?.required_fields) ? m.required_fields : [];
+                            const notes = [
+                                ...(needs.length > 0 ? [`needs ${list(needs)}`] : []),
+                                ...(m?.admins_only === true ? ['project admins only'] : []),
+                            ];
+                            return notes.length > 0 ? `${str(m?.to)} (${notes.join('; ')})` : str(m?.to);
+                        })
+                            .join('; ') || 'none'}`,
+                    ]
+                    : [`- allowed from here: ${list(d.allowed)}`]),
+                ...(Array.isArray(d.required_fields) && d.required_fields.length > 0
+                    ? [`- the asked-for move needs: ${list(d.required_fields)}`]
+                    : []),
+                ...(d.admins_only === true ? ['- the asked-for move is for project admins only'] : []),
+            ];
+        }
+        case 'field_required':
+            return [`- set: ${list(d.fields)}`];
+        case 'validation':
+        case 'image_layout_invalid': {
+            const fields = Array.isArray(d.fields) ? d.fields : [];
+            return fields.map((f) => {
+                const r = record(f);
+                return `- ${str(r?.path)}: ${str(r?.message)}`;
+            });
+        }
+        case 'scope_missing':
+            return [`- needs: ${str(d.scope)}`, `- the token has: ${list(d.granted)}`];
+        case 'not_found':
+        case 'archived':
+        case 'outside_limits':
+            return [`- ${str(d.kind)}: ${str(d.ref)}`];
+        case 'plan_used':
+            return [`- plan ${str(d.handle)} was applied at ${str(d.used_at)}`];
+        case 'plan_expired':
+            return [`- plan ${str(d.handle)}`];
+        case 'plan_stale': {
+            const changed = Array.isArray(d.changed) ? d.changed : [];
+            return [
+                `- plan ${str(d.handle)}; changed since the preview: ${changed
+                    .map((c) => {
+                    const r = record(c);
+                    return `${str(r?.kind)} ${str(r?.ref)}`;
+                })
+                    .join(', ') || 'unknown'}`,
+            ];
+        }
+        case 'bulk_too_large':
+            return [`- ${str(d.count)} items; at most ${str(d.max)}`];
+        case 'limit_reached':
+            return [`- ${str(d.limit)}: at most ${str(d.max)}`];
+        case 'rate_limited':
+            // retry_after and bucket are shown above, in words.
+            return [];
+        default:
+            return undefined;
+    }
+}
+/**
+ * Renders the details object as lines, scrubbed of anything token-shaped,
+ * inside one untrusted block: details can echo people-written names
+ * (statuses, the candidates of an ambiguous name, refs).
+ */
+function formatDetails(code, details) {
+    if (details === undefined || details === null)
+        return undefined;
+    const obj = record(details);
+    let text;
+    if (obj) {
+        if (Object.keys(obj).length === 0)
+            return undefined;
+        const known = formatKnownDetails(code, obj);
+        if (known?.length === 0)
+            return undefined;
+        text = (known ?? Object.entries(obj).map(([key, value]) => `- ${key}: ${formatValue(value)}`)).join('\n');
+    }
+    else {
+        text = formatValue(details);
+    }
+    // eslint-disable-next-line no-control-regex -- stripping control characters is the point
+    text = scrubString(text.replace(/[\u0000-\u0008\u000B-\u001F\u007F]/g, ' '));
+    return wrapUntrusted(text, {
+        source: 'error_details',
+        maxChars: MAX_DETAILS_CHARS,
+        moreHint: 'The rest of the details is left out.',
+    });
+}
+/** Text from the API or a tool, made safe to show: nothing token-shaped, no block tags. */
+function clean(text) {
+    return neutralize(scrubString(text));
+}
+/** The actionable text for an ApiError. */
+export function describeApiError(err) {
+    const details = record(err.details) ?? {};
+    const rateLimited = err.code === 'rate_limited' || err.status === 429;
+    // With the wait in seconds on its own line, the message's and the hint's
+    // pointers to details.retry_after (which isn't shown) would repeat it.
+    const waitShown = rateLimited && err.retryAfterSeconds !== undefined;
+    const message = clean(waitShown ? withoutRetryAdvice(err.message) : err.message);
+    const lines = [
+        `buildIt.Social API error: ${err.code}${err.status ? ` (HTTP ${err.status})` : ''}`,
+        message,
+    ];
+    // Each piece of advice once: the message, then the hint, then a note in
+    // this server's terms, each left out when what came before says it.
+    const said = [message];
+    const kindHint = err.code === 'not_found' && typeof details.kind === 'string'
+        ? NOT_FOUND_HINTS[details.kind]
+        : undefined;
+    const hint = kindHint ?? hintFor(err.code, err.hint);
+    if (hint && !(waitShown && RETRY_ADVICE.test(hint))) {
+        const text = clean(inServerTerms(hint));
+        if (!alreadySaid(text, said)) {
+            lines.push(`What to do: ${text}`);
+            said.push(text);
+        }
+    }
+    const note = err.note ? clean(err.note) : undefined;
+    // A tool's own note is more precise than the general one.
+    const toolNote = note === undefined ? TOOL_NOTES[err.code]?.(details) : undefined;
+    if (toolNote && !alreadySaid(toolNote, said)) {
+        lines.push(toolNote);
+        said.push(toolNote);
+    }
+    if (err.retryAfterSeconds !== undefined) {
+        lines.push(`Retry after: ${Math.ceil(err.retryAfterSeconds)} s`);
+    }
+    if (rateLimited && typeof details.bucket === 'string') {
+        const bucket = RATE_BUCKETS[details.bucket];
+        if (bucket !== undefined)
+            lines.push(`Limit reached: ${bucket}.`);
+    }
+    const formatted = formatDetails(err.code, err.details);
+    if (formatted)
+        lines.push('Details:', formatted);
+    if (note && !alreadySaid(note, said))
+        lines.push(note);
+    lines.push(`Request id: ${err.requestId}`);
+    return lines.join('\n');
+}
+/** A tool result for any failure inside a tool handler. */
+export function toolErrorResult(err, requestId) {
+    if (err instanceof ApiError) {
+        return { isError: true, content: [{ type: 'text', text: describeApiError(err) }] };
+    }
+    if (err instanceof ToolInputError) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: 'text',
+                    text: [
+                        `buildit-mcp error: ${err.code} (nothing was sent to buildIt.Social)`,
+                        clean(err.message),
+                        `What to do: ${LOCAL_HINTS.invalid_arguments ?? ''}`,
+                    ].join('\n'),
+                },
+            ],
+        };
+    }
+    return {
+        isError: true,
+        content: [
+            {
+                type: 'text',
+                text: `Internal error in buildit-mcp${requestId ? ` (request id ${requestId})` : ''}. This is a bug in the server, not in your call; retrying is unlikely to help.`,
+            },
+        ],
+    };
+}