@bridgeline-digital/hawk-app-cli 0.1.0-dev.20261020202308 → 0.1.0

package/src/mcp.mjs

@@ -1,539 +1,539 @@
-// `hawk-app mcp`: a local MCP server (stdio) for AI coding assistants. Its tools run the CLI's own commands, so they
-// can't drift from it, with these limits:
-//   - Always the dev platform (--env dev): prod, approvals, secrets and logins stay with people. Clients can be added
-//     by name ("deploy to OTC"), never removed.
-//   - No client names: outputs show client ids only. clients_add asks the person to pick the client in a form their
-//     assistant shows (MCP elicitation); the answer comes back to this server, and the assistant hears only that a
-//     client was added. Without forms, it sends the person to `hawk-app clients add --pick` in a terminal.
-//   - No query results: `data run` would put client rows in the assistant's context. Table and column names only.
-//   - The publisher key never passes through a tool: the commands use the saved login, as the CLI does.
-//   - deploy asks nothing: the assistant's client asks the user before calling it (destructive hint),
-//     and a question the CLI would ask (a teammate's app, serious vulnerabilities) cancels unless `force` is set.
-// stdout is the protocol: everything the commands print is captured and returned, and builds run with piped output.
-import { spawn } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
-import { isAbsolute, join, relative, resolve } from 'node:path';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { z } from 'zod';
-import { main } from './cli.mjs';
-import { resolveSettings } from './env.mjs';
-import { searchDocs } from './mcp-docs.mjs';
-import { describeUi } from './mcp-ui.mjs';
-import { APIS, createHawkSearchReference } from './mcp-hawksearch.mjs';
-import { createReportCatalog } from './mcp-reports.mjs';
-import { createPlatformRules } from './mcp-rules.mjs';
-import { platformClient } from './platform.mjs';
-
-const MAX_OUTPUT = 20_000;
-const TAIL_LINES = 40;
-
-const INSTRUCTIONS = `Tools for building Hawk Apps: static web apps that run inside the HawkSearch dashboard and get their context and data through the bridge (@bridgeline-digital/hawk-app-bridge).
-- Read the app's AGENTS.md first. Before using a bridge call, look it up with \`docs\` (options, limits, error codes); the showcase sections are working examples of every feature.
-- Before building a screen, \`ui_components\` lists the UI kit's components for this app's template (Spark's look): use them instead of writing your own.
-- For analytics data, \`analytics_reports\` lists the reports app.analytics.report() can call, and gives one report's columns and filters: check it before writing a query.
-- For HawkSearch's own APIs (dashboard, search, recommendations, indexing), \`hawksearch_api\` gives an operation's fields, the bridge call and its scope, and says what apps can't call: check it before writing one.
-- \`validate\` after changing hawk-app.json, queries/ or functions/, and \`validate\` with build=true after changing the build setup.
-- \`deploy\` changes the app on the dev platform: only when the user asks (dryRun: true only shows what hawk-app.json would change). It never touches prod.
-- \`doctor\` says what's wrong with the setup; \`versions\` and \`why\` explain which version a client gets.
-- \`status\` shows the review checks approvers will see; fix failed ones before the user submits the app for approval.
-- To give a client the app ("deploy to OTC", "give it to Outdoor Demo"), call \`clients_add\` with the user's words for the client: it asks the user to pick the exact client. \`deploy\` first if they asked for a new version. Client names aren't shared with you; don't ask the user to type them into the chat.`;
-
-/** `npm run <script>` without inheriting stdout (the protocol): resolves with the output's last lines, rejects on failure. */
-function runQuiet(args, { cwd, env = process.env }) {
-    return new Promise((resolvePromise, reject) => {
-        const child = spawn('npm', args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'], shell: process.platform === 'win32' });
-        const lines = [];
-        const collect = (chunk) => {
-            lines.push(...chunk.toString('utf8').split(/\r?\n/).filter(Boolean));
-            if (lines.length > 500) lines.splice(0, lines.length - 500);
-        };
-        child.stdout.on('data', collect);
-        child.stderr.on('data', collect);
-        child.on('error', reject);
-        child.on('close', (code) => {
-            const tail = lines.slice(-TAIL_LINES).join('\n');
-            if (code === 0) resolvePromise(tail);
-            else reject(new Error(`\`npm ${args.join(' ')}\` failed (exit code ${code}):\n${tail}`));
-        });
-    });
-}
-
-/**
- * Runs one CLI command in `dir` and returns what it printed. Commands run one at a time: they use the process's
- * working directory.
- */
-export function createRunner({ root = process.cwd(), cli = main } = {}) {
-    let queue = Promise.resolve();
-    return function run(argv, { dir, force = false } = {}) {
-        const job = queue.then(async () => {
-            const cwd = resolve(root, dir ?? '.');
-            const inside = relative(root, cwd);
-            if (inside.startsWith('..') || isAbsolute(inside)) return { ok: false, text: `"${dir}" is outside the workspace (${root}).` };
-            if (!existsSync(cwd)) return { ok: false, text: `"${dir}" doesn't exist.` };
-
-            const out = [];
-            const log = (line = '') => out.push(String(line));
-            const previous = process.cwd();
-            process.chdir(cwd);
-            try {
-                const code = await cli([...argv, '--env', 'dev'], {
-                    log,
-                    clientNames: false,
-                    // No terminal: a question cancels, unless the user said to go on (force). The assistant sees it.
-                    confirm: async (question) => {
-                        log(`? ${question}`);
-                        return force;
-                    },
-                    runBuild: async ({ basePath, cwd: buildDir = cwd }) => {
-                        const tail = await runQuiet(['run', 'build'], { cwd: buildDir, env: { ...process.env, HAWK_APP_BASE_PATH: basePath } });
-                        log(tail);
-                    },
-                    runInstall: async ({ cwd: installDir }) => log(await runQuiet(['install', '--no-audit', '--no-fund'], { cwd: installDir })),
-                });
-                return { ok: code === 0, text: out.join('\n') };
-            } catch (error) {
-                out.push(`✖ ${error.message ?? error}`);
-                if (/Cancelled/.test(error.message ?? '') && !force) {
-                    out.push('(The CLI would have asked the user. Ask them, and call again with force: true only if they say to go on.)');
-                }
-                return { ok: false, text: out.join('\n') };
-            } finally {
-                process.chdir(previous);
-            }
-        });
-        queue = job.catch(() => {});
-        return job;
-    };
-}
-
-const result = ({ ok, text }) => ({
-    content: [{ type: 'text', text: text.length > MAX_OUTPUT ? `${text.slice(0, MAX_OUTPUT)}\n… (output cut)` : text || '(no output)' }],
-    ...(ok ? {} : { isError: true }),
-});
-
-const dirParam = z.string().optional().describe("The app's folder (the one with hawk-app.json), relative to the workspace. Default: the workspace itself.");
-
-/** The app's slug from hawk-app.json in `dir`, if there is one. */
-function slugIn(root, dir) {
-    try {
-        return JSON.parse(readFileSync(join(resolve(root, dir ?? '.'), 'hawk-app.json'), 'utf8')).slug;
-    } catch {
-        return undefined;
-    }
-}
-
-/** The dev platform with the saved login, as the CLI resolves it in `dir` (for clients_add, which talks to it directly). */
-function devPlatform(dir) {
-    const { url, key } = resolveSettings({ flagEnv: 'dev', dir });
-    return platformClient({ url, key });
-}
-
-/** How long the person has to pick a client in the form (the SDK's default is a minute). */
-const PICK_TIMEOUT_MS = 5 * 60_000;
-
-/**
- * A platform error without its detail, which can name a client (e.g. the "did you mean" of an unknown id): the status,
- * title and code. Errors before any answer (not logged in, unreachable) name no client and are kept whole.
- */
-const withoutNames = (error) => (error.status ? `${error.status} ${error.data?.title ?? 'error'}${error.data?.code ? ` (${error.data.code})` : ''}` : error.message ?? String(error));
-
-/** What apps may call, from the dev platform's /meta/rules: shared by analytics_reports and hawksearch_api. */
-const platformRules = createPlatformRules();
-
-/** The MCP server with every tool registered (not connected). */
-export function createMcpServer({
-    root = process.cwd(),
-    run = createRunner({ root }),
-    platform = devPlatform,
-    reports = createReportCatalog({ rules: platformRules }),
-    hawksearch = createHawkSearchReference({ rules: platformRules }),
-    version = '0.0.0',
-} = {}) {
-    const server = new McpServer({ name: 'hawk-apps', version }, { instructions: INSTRUCTIONS });
-    const readOnly = { readOnlyHint: true, openWorldHint: false };
-
-    server.registerTool(
-        'docs',
-        {
-            title: 'Hawk Apps documentation',
-            description:
-                'The bridge (every app.* call, its scope, options, limits and error codes), the CLI, the hawk-app.json schema and the showcase app (working code for every feature). Without arguments: the list of sections. With query: the best matching sections. With section: one section in full.',
-            inputSchema: {
-                query: z.string().optional().describe('Words to look for, e.g. "data.query partitions" or "functions secrets".'),
-                section: z.string().optional().describe('A section title from the list or an earlier result, e.g. "bridge: Functions: `functions:invoke`".'),
-                offset: z.number().int().min(0).optional().describe('For a long section: where to go on reading (the earlier result says).'),
-                dir: dirParam,
-            },
-            annotations: readOnly,
-        },
-        async ({ query, section, offset, dir }) => result({ ok: true, text: searchDocs({ appDir: resolve(root, dir ?? '.'), query, section, offset }) }),
-    );
-
-    server.registerTool(
-        'ui_components',
-        {
-            title: 'UI kit components',
-            description:
-                "The Hawk Apps UI kit's parts for this app's template, to build screens from instead of writing your own: React + MUI apps (next-mui) the provider, components and theme; every other app the stylesheet classes and custom elements (<hawk-kpi>, <hawk-data-table>, <hawk-bar-list>, <hawk-column-chart>). With component: only what's said about it. Links the live gallery.",
-            inputSchema: {
-                component: z.string().optional().describe('A component, element or class, e.g. "DataTable", "hawk-kpi" or "hawk-notice".'),
-                flavour: z.enum(['mui', 'elements']).optional().describe("Default: the app's (mui for next-mui, else elements)."),
-                dir: dirParam,
-            },
-            annotations: readOnly,
-        },
-        async ({ component, flavour, dir }) => result(describeUi({ appDir: resolve(root, dir ?? '.'), component, flavour })),
-    );
-
-    server.registerTool(
-        'analytics_reports',
-        {
-            title: 'Analytics reports',
-            description:
-                "The HawkSearch Analytics API's reports, which app.analytics.report(name, request) calls (scope reports:read), read from its developer portal. Without arguments: every report with a one-line summary. With report: that report's description, columns, filters and having fields, and an example call. No client data.",
-            inputSchema: { report: z.string().optional().describe('A report name from the list, e.g. "assistant-prompts"; "" for the ad-hoc / natural-language root.') },
-            annotations: { ...readOnly, openWorldHint: true },
-        },
-        async ({ report }) => result(await reports({ report })),
-    );
-
-    server.registerTool(
-        'hawksearch_api',
-        {
-            title: 'HawkSearch API reference',
-            description:
-                "HawkSearch's own API reference (developerdocs.hawksearch.com), with what apps can call of it: app.dashboard.*, app.hawksearch.search/autocomplete, recommendations and index. Without arguments: every API's operation groups and what apps can do with them. With api: that API's operations. With operation (an id from the list, or words): its method and path, parameters, request and response fields, the bridge call and its scope, or why apps can't call it. No client data.",
-            inputSchema: {
-                api: z.enum(Object.keys(APIS)).optional().describe('Only this API.'),
-                operation: z.string().optional().describe('An operation id from the list (e.g. "synonym_post_synonym"), or words to find one ("update redirect").'),
-                offset: z.number().int().min(0).optional().describe('For a long operation: where to read on from (the previous answer says).'),
-            },
-            annotations: { ...readOnly, openWorldHint: true },
-        },
-        async ({ api, operation, offset }) => result(await hawksearch({ api, operation, offset })),
-    );
-
-    server.registerTool(
-        'validate',
-        {
-            title: 'Validate the app',
-            description:
-                'Checks hawk-app.json, queries/ and functions/ like deploy does, and the project (the bridge and its version, a build script). build: true also builds the app as deploy does (base path /<slug>/v0) and fails on HTML URLs outside the base path.',
-            inputSchema: { build: z.boolean().optional(), folder: z.string().optional().describe("The build's output folder; default: the template's (dist, out, public)."), dir: dirParam },
-            annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
-        },
-        async ({ build, folder, dir }) => result(await run(['validate', ...(build ? ['--build', ...(folder ? [folder] : [])] : [])], { dir })),
-    );
-
-    server.registerTool(
-        'status',
-        {
-            title: 'App status on dev',
-            description: 'Where the app stands on the dev platform: the released version (default), the newest version, settings waiting for review, the approval request, the aliases, and the automated review checks approvers will see.',
-            inputSchema: { dir: dirParam },
-            annotations: { ...readOnly, openWorldHint: true },
-        },
-        async ({ dir }) => result(await run(['status'], { dir })),
-    );
-
-    server.registerTool(
-        'doctor',
-        {
-            title: 'Check the setup',
-            description: "Checks everything a developer needs, with what to fix: Node, the login and the dev platform, hawk-app.json, the project (bridge, build script), scopes the code uses that hawk-app.json lacks, the template, the app on the platform and the MCP config.",
-            inputSchema: { dir: dirParam },
-            annotations: { ...readOnly, openWorldHint: true },
-        },
-        async ({ dir }) => result(await run(['doctor'], { dir })),
-    );
-
-    server.registerTool(
-        'versions',
-        {
-            title: 'App versions on dev',
-            description: "Every version on the dev platform with its status (draft, waiting, approved, rejected) and the aliases on it. Clients get their alias's version (default without one); users see it only when it's approved.",
-            inputSchema: { dir: dirParam },
-            annotations: { ...readOnly, openWorldHint: true },
-        },
-        async ({ dir }) => result(await run(['versions'], { dir })),
-    );
-
-    server.registerTool(
-        'why',
-        {
-            title: 'Why a client sees (or not) the app on dev',
-            description: "What a client's users see of the app on the dev platform, and why: the client list, the client's alias and that version's status. Takes the client id (e.g. e3141).",
-            inputSchema: { client: z.string().describe('The client id, e.g. e3141.'), dir: dirParam },
-            annotations: { ...readOnly, openWorldHint: true },
-        },
-        async ({ client, dir }) => result(await run(['why', client], { dir })),
-    );
-
-    server.registerTool(
-        'data_tables',
-        {
-            title: 'Analytics tables',
-            description: 'The analytics tables app queries (queries/*.sql, scope data:read) can use, including whether this app may use the sensitive ones. Names only, no data.',
-            inputSchema: { dir: dirParam },
-            annotations: { ...readOnly, openWorldHint: true },
-        },
-        async ({ dir }) => {
-            const slug = slugIn(root, dir);
-            return result(await run(['data', 'tables', ...(slug ? ['--app', slug] : [])], { dir }));
-        },
-    );
-
-    server.registerTool(
-        'data_describe',
-        {
-            title: 'Table columns',
-            description: "An analytics table's columns and types, for writing queries/*.sql. No data.",
-            inputSchema: { table: z.string().describe('A table name from data_tables.'), dir: dirParam },
-            annotations: { ...readOnly, openWorldHint: true },
-        },
-        async ({ table, dir }) => result(await run(['data', 'describe', table], { dir })),
-    );
-
-    server.registerTool(
-        'logs',
-        {
-            title: 'Function logs on dev',
-            description: "A function's logs on the dev platform (functions/<name>.ts).",
-            inputSchema: {
-                function: z.string().describe('The function name.'),
-                since: z.string().optional().describe('15m, 1h, 1d or an ISO time; default 1h.'),
-                dir: dirParam,
-            },
-            annotations: { ...readOnly, openWorldHint: true },
-        },
-        async ({ function: name, since, dir }) => result(await run(['logs', name, ...(since ? ['--since', since] : [])], { dir })),
-    );
-
-    server.registerTool(
-        'errors',
-        {
-            title: 'App errors on dev',
-            description: "Errors in the app's pages on the dev platform (uncaught errors, unhandled rejections, app.reportError), grouped by kind, the most frequent first, with versions, clients and the top stack frames.",
-            inputSchema: { days: z.number().int().min(1).max(30).optional().describe('Days back; default 7.'), dir: dirParam },
-            annotations: { ...readOnly, openWorldHint: true },
-        },
-        async ({ days, dir }) => result(await run(['errors', ...(days ? ['--days', String(days)] : [])], { dir })),
-    );
-
-    server.registerTool(
-        'usage',
-        {
-            title: 'App usage on dev',
-            description: 'Opens of the app and of its views, distinct users and clients per day on the dev platform (Bridgeline staff counted apart).',
-            inputSchema: { days: z.number().int().min(1).max(400).optional().describe('Days back; default 30.'), dir: dirParam },
-            annotations: { ...readOnly, openWorldHint: true },
-        },
-        async ({ days, dir }) => result(await run(['usage', ...(days ? ['--days', String(days)] : [])], { dir })),
-    );
-
-    server.registerTool(
-        'init',
-        {
-            title: 'Make a project a Hawk App',
-            description: 'For a project without hawk-app.json: writes it (refusing a slug that is already an app), plus AGENTS.md and the MCP settings. Then add the bridge and the base path as AGENTS.md says.',
-            inputSchema: { slug: z.string().optional(), name: z.string().optional(), dir: dirParam },
-            annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-        },
-        async ({ slug, name, dir }) => result(await run(['init', ...(slug ? ['--slug', slug] : []), ...(name ? ['--name', name] : [])], { dir })),
-    );
-
-    server.registerTool(
-        'upgrade',
-        {
-            title: 'Upgrade to the template',
-            description:
-                "Shows how the app differs from the CLI's template (package versions, unedited config files, AGENTS.md). apply: true changes those files and runs npm install. channel: 'latest' moves the bridge and CLI from dev builds to the released versions, 'dev' onto the dev builds (only when the user asks).",
-            inputSchema: { apply: z.boolean().optional(), channel: z.enum(['latest', 'dev']).optional(), dir: dirParam },
-            annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
-        },
-        async ({ apply, channel, dir }) => result(await run(['upgrade', ...(channel ? ['--channel', channel] : []), ...(apply ? ['--yes'] : [])], { dir })),
-    );
-
-    server.registerTool(
-        'deploy',
-        {
-            title: 'Deploy a version to dev',
-            description:
-                "Builds the app (npm run build with HAWK_APP_BASE_PATH) and uploads it as a new version on the dev platform, with hawk-app.json, queries/ and functions/. Runs npm audit first. alias: deploys off the main line and points that alias at the new version (only Bridgeline staff in its clients see it). dryRun: true only shows what hawk-app.json would change, and deploys nothing. Deploy only when the user asks (a dry run is fine any time).",
-            inputSchema: {
-                folder: z.string().optional().describe("The build output folder; default: the template's (dist, out, public)."),
-                alias: z.string().optional().describe('An alias, e.g. staging or preview-my-branch: lowercase letters, digits and dashes.'),
-                dryRun: z.boolean().optional().describe('Only show what hawk-app.json would change.'),
-                noBuild: z.boolean().optional().describe('Upload the folder as it is (plain HTML/JS).'),
-                force: z.boolean().optional().describe("Go on despite high or critical vulnerabilities, or a teammate's last change: only after the user says so."),
-                dir: dirParam,
-            },
-            annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
-        },
-        async ({ folder, alias, dryRun, noBuild, force, dir }) =>
-            result(await run(['deploy', ...(folder ? [folder] : []), ...(alias ? ['--alias', alias] : []), ...(dryRun ? ['--dry-run'] : []), ...(noBuild ? ['--no-build'] : [])], { dir, force })),
-    );
-
-    server.registerTool(
-        'clients',
-        {
-            title: "The app's clients on dev",
-            description: "Which clients have the app on the dev platform (+ has it, - opted out), by id, and its visibility. Client names aren't shown.",
-            inputSchema: { dir: dirParam },
-            annotations: { ...readOnly, openWorldHint: true },
-        },
-        async ({ dir }) => result(await run(['clients'], { dir })),
-    );
-
-    server.registerTool(
-        'clients_add',
-        {
-            title: 'Give a client the app on dev',
-            description:
-                'Gives a client the app on the dev platform, at once (with visibility allowList, only listed clients have the app). Pass the user\'s words for the client ("OTC", "Outdoor Demo" or an id): the tool finds the matches and asks the user to pick one in a form. You hear only whether a client was added, never the names.',
-            inputSchema: {
-                client: z.string().describe('The client as the user named it, e.g. "OTC".'),
-                alias: z.string().optional().describe("The alias the client follows (the version it gets), e.g. \"review\"; \"default\" for the default. On an alias whose version isn't approved only Bridgeline staff in the client see the app."),
-                dir: dirParam,
-            },
-            annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
-        },
-        async ({ client: words, alias, dir }) => {
-            const wanted = words.trim();
-            const slug = slugIn(root, dir);
-            if (!slug) return result({ ok: false, text: `No hawk-app.json in ${dir ?? 'the workspace'}: run this in the app's folder (dir).` });
-            if (wanted.length < 2) return result({ ok: false, text: "Ask the user for at least 2 characters of the client's name or id." });
-            const terminal = `In a terminal, in the app's folder: npx hawk-app clients add --pick "${wanted.replace(/"/g, '')}"${alias ? ` --alias ${alias}` : ''} --env dev`;
-            if (!server.server.getClientCapabilities()?.elicitation) {
-                return result({ ok: false, text: `This assistant can't show the user a form to pick the client, and client names aren't shared with you. Ask the user to run this themselves (it lists the matches for them to pick from):\n${terminal}` });
-            }
-
-            let devApi;
-            let found;
-            try {
-                devApi = platform(resolve(root, dir ?? '.'));
-                found = await devApi.searchClients(wanted);
-            } catch (error) {
-                return result({ ok: false, text: `✖ ${withoutNames(error)}` });
-            }
-            if (!found.clients?.length) {
-                return result({ ok: false, text: 'No client matches what the user typed. Ask them for another part of the name, or the id the dashboard shows (e.g. e3141).' });
-            }
-
-            let answer;
-            try {
-                answer = await server.server.elicitInput(
-                    {
-                        message: `Which client should get ${slug} on dev?${found.more ? " These are the best matches for what you typed: cancel and use more of the name if yours isn't here." : ''}`,
-                        requestedSchema: {
-                            type: 'object',
-                            properties: {
-                                client: { type: 'string', title: 'Client', oneOf: found.clients.map((c) => ({ const: c.id, title: c.name ? `${c.name} (${c.id})` : c.id })) },
-                            },
-                            required: ['client'],
-                        },
-                    },
-                    { timeout: PICK_TIMEOUT_MS },
-                );
-            } catch {
-                // Not shown, not answered in time, or answered with something other than the choices (the SDK checks).
-                return result({ ok: false, text: `The form to pick the client didn't get an answer. Nothing was changed. Ask the user to try again, or to run:\n${terminal}` });
-            }
-            const id = answer.action === 'accept' ? answer.content?.client : undefined;
-            if (!found.clients.some((c) => c.id === id)) {
-                return result({ ok: false, text: 'The user cancelled: no client was added. Ask them what they want instead.' });
-            }
-
-            try {
-                await devApi.setClient(slug, id, { enabled: true, ...(alias ? { alias } : {}) });
-            } catch (error) {
-                if (error.data?.code === 'approver_required') return result({ ok: false, text: "The client's users see the app now: only an approver can change what it gets (the app's Rollout tab in the Hawk Analytics portal, or HawkSearch). Nothing was changed." });
-                return result({ ok: false, text: `✖ The client wasn't added: ${withoutNames(error)}` });
-            }
-            return result({ ok: true, text: `✔ Added the client the user picked to ${slug} on dev${alias ? ` on ${alias}` : ''}. It applies now (recorded in the app's history). The user saw its name in the form; it isn't shared here.` });
-        },
-    );
-
-    registerPrompts(server);
-    return server;
-}
-
-/**
- * Prompts: ready-made tasks that clients list where developers look (Claude Code shows them as slash commands), so
- * the tools are found without reading about them. Each one tells the assistant which tools to use, in what order.
- */
-const PROMPTS = {
-    'check-before-submit': {
-        title: 'Check before submitting for approval',
-        description: 'Validates the app (with a build check), reads its status, review checks and errors on dev, and explains how to fix anything an approver would have to force approve.',
-        text: (dir) => `Check this Hawk App${where(dir)} before it's submitted for approval in HawkSearch.
-1. Run the hawk-apps \`validate\` tool with build: true${dirArg(dir)}. Fix what it reports in the code (ask me before changing hawk-app.json scopes or externalOrigins).
-2. Run \`status\`${dirArg(dir)}, and \`deploy\` with dryRun: true to see what hawk-app.json would change. If the app isn't on the platform or its newest version is older than the code, say so: I decide when to deploy.
-3. For each review check that fails or needs attention (bundle, dependencies, accessibility, external origins, queries, functions, external Lambdas), explain what an approver will see and how to fix it, using \`docs\` where it helps.
-4. Run \`errors\`${dirArg(dir)} and fix the errors the deployed versions threw, the most frequent first.
-End with a short list: ready to submit, or what's left to do.`,
-    },
-    'add-feature': {
-        title: 'Add a feature',
-        description: 'Builds a feature the Hawk Apps way: finds the right bridge calls, scopes and examples in the docs, makes the change, and validates it.',
-        args: { feature: z.string().describe('What to build, e.g. "a chart of searches per day for the selected date range".') },
-        text: (dir, { feature }) => `Add this feature to the Hawk App${where(dir)}: ${feature}
-1. Read AGENTS.md. Use the hawk-apps \`docs\` tool to find the bridge calls it needs (their options, limits and error codes) and a working example in the showcase sections. Prefer what the bridge offers over anything custom.
-2. Tell me which scopes, analytics reports (check them with \`analytics_reports\`), HawkSearch API calls (check them with \`hawksearch_api\`), queries (queries/*.sql, check tables and columns with \`data_tables\` and \`data_describe\`) or functions it needs, and anything that makes the review harder (elevated scopes, new outside origins), before changing hawk-app.json.
-3. Make the change in the app's style. Handle a client without analytics and the errors the docs list.
-4. Run \`validate\`${dirArg(dir)} and fix what it reports. Don't deploy unless I ask.`,
-    },
-    'deploy-to-client': {
-        title: 'Deploy to a client',
-        description: 'Deploys a new version to dev and gives a client the app: you pick the client from the matches for its name.',
-        args: { client: z.string().describe('The client\'s name or id, e.g. "OTC" or "Outdoor Demo".') },
-        text: (dir, { client }) => `Deploy this Hawk App${where(dir)} to the client "${client}" on dev.
-1. Run the hawk-apps \`deploy\` tool${dirArg(dir)}. If it asks a question, ask me.
-2. Run \`clients_add\` with client "${client}"${dirArg(dir)}. It asks me to pick the exact client; if it says it can't, tell me the command it gives.
-3. Run \`status\`${dirArg(dir)}.
-End with where I'll find it: the HawkSearch dev dashboard, with the client I picked selected, on the Apps page.`,
-    },
-    'explain-app': {
-        title: 'Explain this app',
-        description: 'Summarizes what the app does, the data and scopes it uses, and where it stands in review on dev.',
-        text: (dir) => `Explain this Hawk App${where(dir)} to me.
-1. Read hawk-app.json, AGENTS.md and the main source files: what does the app do, for whom, and which bridge calls, queries and functions does it use?
-2. Which scopes does it ask for, and are any unused or missing for what the code calls?
-3. Run the hawk-apps \`status\` tool${dirArg(dir)}: what's released, what's waiting for approval, and what do the review checks say?
-Keep it short: a paragraph, then bullets.`,
-    },
-};
-
-const where = (dir) => (dir ? ` in ${dir}` : '');
-const dirArg = (dir) => (dir ? ` (dir: "${dir}")` : '');
-
-function registerPrompts(server) {
-    for (const [name, prompt] of Object.entries(PROMPTS)) {
-        server.registerPrompt(
-            name,
-            {
-                title: prompt.title,
-                description: prompt.description,
-                argsSchema: { ...prompt.args, dir: z.string().optional().describe("The app's folder, when the workspace has several apps.") },
-            },
-            ({ dir, ...args }) => ({
-                description: prompt.description,
-                messages: [{ role: 'user', content: { type: 'text', text: prompt.text(dir?.trim() || undefined, args) } }],
-            }),
-        );
-    }
-}
-
-/** `hawk-app mcp`: serves the tools over stdio until the client closes the connection. */
-export async function serveMcp({ version } = {}) {
-    // stdout belongs to the protocol: anything else printed by mistake goes to stderr.
-    console.log = (...args) => console.error(...args);
-    const server = createMcpServer({ version });
-    const closed = new Promise((resolveClosed) => {
-        server.server.onclose = resolveClosed;
-    });
-    await server.connect(new StdioServerTransport());
-    await closed;
-    return 0;
-}
+// `hawk-app mcp`: a local MCP server (stdio) for AI coding assistants. Its tools run the CLI's own commands, so they
+// can't drift from it, with these limits:
+//   - Always the dev platform (--env dev): prod, approvals, secrets and logins stay with people. Clients can be added
+//     by name ("deploy to OTC"), never removed.
+//   - No client names: outputs show client ids only. clients_add asks the person to pick the client in a form their
+//     assistant shows (MCP elicitation); the answer comes back to this server, and the assistant hears only that a
+//     client was added. Without forms, it sends the person to `hawk-app clients add --pick` in a terminal.
+//   - No query results: `data run` would put client rows in the assistant's context. Table and column names only.
+//   - The publisher key never passes through a tool: the commands use the saved login, as the CLI does.
+//   - deploy asks nothing: the assistant's client asks the user before calling it (destructive hint),
+//     and a question the CLI would ask (a teammate's app, serious vulnerabilities) cancels unless `force` is set.
+// stdout is the protocol: everything the commands print is captured and returned, and builds run with piped output.
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { main } from './cli.mjs';
+import { resolveSettings } from './env.mjs';
+import { searchDocs } from './mcp-docs.mjs';
+import { describeUi } from './mcp-ui.mjs';
+import { APIS, createHawkSearchReference } from './mcp-hawksearch.mjs';
+import { createReportCatalog } from './mcp-reports.mjs';
+import { createPlatformRules } from './mcp-rules.mjs';
+import { platformClient } from './platform.mjs';
+
+const MAX_OUTPUT = 20_000;
+const TAIL_LINES = 40;
+
+const INSTRUCTIONS = `Tools for building Hawk Apps: static web apps that run inside the HawkSearch dashboard and get their context and data through the bridge (@bridgeline-digital/hawk-app-bridge).
+- Read the app's AGENTS.md first. Before using a bridge call, look it up with \`docs\` (options, limits, error codes); the showcase sections are working examples of every feature.
+- Before building a screen, \`ui_components\` lists the UI kit's components for this app's template (Spark's look): use them instead of writing your own.
+- For analytics data, \`analytics_reports\` lists the reports app.analytics.report() can call, and gives one report's columns and filters: check it before writing a query.
+- For HawkSearch's own APIs (dashboard, search, recommendations, indexing), \`hawksearch_api\` gives an operation's fields, the bridge call and its scope, and says what apps can't call: check it before writing one.
+- \`validate\` after changing hawk-app.json, queries/ or functions/, and \`validate\` with build=true after changing the build setup.
+- \`deploy\` changes the app on the dev platform: only when the user asks (dryRun: true only shows what hawk-app.json would change). It never touches prod.
+- \`doctor\` says what's wrong with the setup; \`versions\` and \`why\` explain which version a client gets.
+- \`status\` shows the review checks approvers will see; fix failed ones before the user submits the app for approval.
+- To give a client the app ("deploy to OTC", "give it to Outdoor Demo"), call \`clients_add\` with the user's words for the client: it asks the user to pick the exact client. \`deploy\` first if they asked for a new version. Client names aren't shared with you; don't ask the user to type them into the chat.`;
+
+/** `npm run <script>` without inheriting stdout (the protocol): resolves with the output's last lines, rejects on failure. */
+function runQuiet(args, { cwd, env = process.env }) {
+    return new Promise((resolvePromise, reject) => {
+        const child = spawn('npm', args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'], shell: process.platform === 'win32' });
+        const lines = [];
+        const collect = (chunk) => {
+            lines.push(...chunk.toString('utf8').split(/\r?\n/).filter(Boolean));
+            if (lines.length > 500) lines.splice(0, lines.length - 500);
+        };
+        child.stdout.on('data', collect);
+        child.stderr.on('data', collect);
+        child.on('error', reject);
+        child.on('close', (code) => {
+            const tail = lines.slice(-TAIL_LINES).join('\n');
+            if (code === 0) resolvePromise(tail);
+            else reject(new Error(`\`npm ${args.join(' ')}\` failed (exit code ${code}):\n${tail}`));
+        });
+    });
+}
+
+/**
+ * Runs one CLI command in `dir` and returns what it printed. Commands run one at a time: they use the process's
+ * working directory.
+ */
+export function createRunner({ root = process.cwd(), cli = main } = {}) {
+    let queue = Promise.resolve();
+    return function run(argv, { dir, force = false } = {}) {
+        const job = queue.then(async () => {
+            const cwd = resolve(root, dir ?? '.');
+            const inside = relative(root, cwd);
+            if (inside.startsWith('..') || isAbsolute(inside)) return { ok: false, text: `"${dir}" is outside the workspace (${root}).` };
+            if (!existsSync(cwd)) return { ok: false, text: `"${dir}" doesn't exist.` };
+
+            const out = [];
+            const log = (line = '') => out.push(String(line));
+            const previous = process.cwd();
+            process.chdir(cwd);
+            try {
+                const code = await cli([...argv, '--env', 'dev'], {
+                    log,
+                    clientNames: false,
+                    // No terminal: a question cancels, unless the user said to go on (force). The assistant sees it.
+                    confirm: async (question) => {
+                        log(`? ${question}`);
+                        return force;
+                    },
+                    runBuild: async ({ basePath, cwd: buildDir = cwd }) => {
+                        const tail = await runQuiet(['run', 'build'], { cwd: buildDir, env: { ...process.env, HAWK_APP_BASE_PATH: basePath } });
+                        log(tail);
+                    },
+                    runInstall: async ({ cwd: installDir }) => log(await runQuiet(['install', '--no-audit', '--no-fund'], { cwd: installDir })),
+                });
+                return { ok: code === 0, text: out.join('\n') };
+            } catch (error) {
+                out.push(`✖ ${error.message ?? error}`);
+                if (/Cancelled/.test(error.message ?? '') && !force) {
+                    out.push('(The CLI would have asked the user. Ask them, and call again with force: true only if they say to go on.)');
+                }
+                return { ok: false, text: out.join('\n') };
+            } finally {
+                process.chdir(previous);
+            }
+        });
+        queue = job.catch(() => {});
+        return job;
+    };
+}
+
+const result = ({ ok, text }) => ({
+    content: [{ type: 'text', text: text.length > MAX_OUTPUT ? `${text.slice(0, MAX_OUTPUT)}\n… (output cut)` : text || '(no output)' }],
+    ...(ok ? {} : { isError: true }),
+});
+
+const dirParam = z.string().optional().describe("The app's folder (the one with hawk-app.json), relative to the workspace. Default: the workspace itself.");
+
+/** The app's slug from hawk-app.json in `dir`, if there is one. */
+function slugIn(root, dir) {
+    try {
+        return JSON.parse(readFileSync(join(resolve(root, dir ?? '.'), 'hawk-app.json'), 'utf8')).slug;
+    } catch {
+        return undefined;
+    }
+}
+
+/** The dev platform with the saved login, as the CLI resolves it in `dir` (for clients_add, which talks to it directly). */
+function devPlatform(dir) {
+    const { url, key } = resolveSettings({ flagEnv: 'dev', dir });
+    return platformClient({ url, key });
+}
+
+/** How long the person has to pick a client in the form (the SDK's default is a minute). */
+const PICK_TIMEOUT_MS = 5 * 60_000;
+
+/**
+ * A platform error without its detail, which can name a client (e.g. the "did you mean" of an unknown id): the status,
+ * title and code. Errors before any answer (not logged in, unreachable) name no client and are kept whole.
+ */
+const withoutNames = (error) => (error.status ? `${error.status} ${error.data?.title ?? 'error'}${error.data?.code ? ` (${error.data.code})` : ''}` : error.message ?? String(error));
+
+/** What apps may call, from the dev platform's /meta/rules: shared by analytics_reports and hawksearch_api. */
+const platformRules = createPlatformRules();
+
+/** The MCP server with every tool registered (not connected). */
+export function createMcpServer({
+    root = process.cwd(),
+    run = createRunner({ root }),
+    platform = devPlatform,
+    reports = createReportCatalog({ rules: platformRules }),
+    hawksearch = createHawkSearchReference({ rules: platformRules }),
+    version = '0.0.0',
+} = {}) {
+    const server = new McpServer({ name: 'hawk-apps', version }, { instructions: INSTRUCTIONS });
+    const readOnly = { readOnlyHint: true, openWorldHint: false };
+
+    server.registerTool(
+        'docs',
+        {
+            title: 'Hawk Apps documentation',
+            description:
+                'The bridge (every app.* call, its scope, options, limits and error codes), the CLI, the hawk-app.json schema and the showcase app (working code for every feature). Without arguments: the list of sections. With query: the best matching sections. With section: one section in full.',
+            inputSchema: {
+                query: z.string().optional().describe('Words to look for, e.g. "data.query partitions" or "functions secrets".'),
+                section: z.string().optional().describe('A section title from the list or an earlier result, e.g. "bridge: Functions: `functions:invoke`".'),
+                offset: z.number().int().min(0).optional().describe('For a long section: where to go on reading (the earlier result says).'),
+                dir: dirParam,
+            },
+            annotations: readOnly,
+        },
+        async ({ query, section, offset, dir }) => result({ ok: true, text: searchDocs({ appDir: resolve(root, dir ?? '.'), query, section, offset }) }),
+    );
+
+    server.registerTool(
+        'ui_components',
+        {
+            title: 'UI kit components',
+            description:
+                "The Hawk Apps UI kit's parts for this app's template, to build screens from instead of writing your own: React + MUI apps (next-mui) the provider, components and theme; every other app the stylesheet classes and custom elements (<hawk-kpi>, <hawk-data-table>, <hawk-bar-list>, <hawk-column-chart>). With component: only what's said about it. Links the live gallery.",
+            inputSchema: {
+                component: z.string().optional().describe('A component, element or class, e.g. "DataTable", "hawk-kpi" or "hawk-notice".'),
+                flavour: z.enum(['mui', 'elements']).optional().describe("Default: the app's (mui for next-mui, else elements)."),
+                dir: dirParam,
+            },
+            annotations: readOnly,
+        },
+        async ({ component, flavour, dir }) => result(describeUi({ appDir: resolve(root, dir ?? '.'), component, flavour })),
+    );
+
+    server.registerTool(
+        'analytics_reports',
+        {
+            title: 'Analytics reports',
+            description:
+                "The HawkSearch Analytics API's reports, which app.analytics.report(name, request) calls (scope reports:read), read from its developer portal. Without arguments: every report with a one-line summary. With report: that report's description, columns, filters and having fields, and an example call. No client data.",
+            inputSchema: { report: z.string().optional().describe('A report name from the list, e.g. "assistant-prompts"; "" for the ad-hoc / natural-language root.') },
+            annotations: { ...readOnly, openWorldHint: true },
+        },
+        async ({ report }) => result(await reports({ report })),
+    );
+
+    server.registerTool(
+        'hawksearch_api',
+        {
+            title: 'HawkSearch API reference',
+            description:
+                "HawkSearch's own API reference (developerdocs.hawksearch.com), with what apps can call of it: app.dashboard.*, app.hawksearch.search/autocomplete, recommendations and index. Without arguments: every API's operation groups and what apps can do with them. With api: that API's operations. With operation (an id from the list, or words): its method and path, parameters, request and response fields, the bridge call and its scope, or why apps can't call it. No client data.",
+            inputSchema: {
+                api: z.enum(Object.keys(APIS)).optional().describe('Only this API.'),
+                operation: z.string().optional().describe('An operation id from the list (e.g. "synonym_post_synonym"), or words to find one ("update redirect").'),
+                offset: z.number().int().min(0).optional().describe('For a long operation: where to read on from (the previous answer says).'),
+            },
+            annotations: { ...readOnly, openWorldHint: true },
+        },
+        async ({ api, operation, offset }) => result(await hawksearch({ api, operation, offset })),
+    );
+
+    server.registerTool(
+        'validate',
+        {
+            title: 'Validate the app',
+            description:
+                'Checks hawk-app.json, queries/ and functions/ like deploy does, and the project (the bridge and its version, a build script). build: true also builds the app as deploy does (base path /<slug>/v0) and fails on HTML URLs outside the base path.',
+            inputSchema: { build: z.boolean().optional(), folder: z.string().optional().describe("The build's output folder; default: the template's (dist, out, public)."), dir: dirParam },
+            annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+        },
+        async ({ build, folder, dir }) => result(await run(['validate', ...(build ? ['--build', ...(folder ? [folder] : [])] : [])], { dir })),
+    );
+
+    server.registerTool(
+        'status',
+        {
+            title: 'App status on dev',
+            description: 'Where the app stands on the dev platform: the released version (default), the newest version, settings waiting for review, the approval request, the aliases, and the automated review checks approvers will see.',
+            inputSchema: { dir: dirParam },
+            annotations: { ...readOnly, openWorldHint: true },
+        },
+        async ({ dir }) => result(await run(['status'], { dir })),
+    );
+
+    server.registerTool(
+        'doctor',
+        {
+            title: 'Check the setup',
+            description: "Checks everything a developer needs, with what to fix: Node, the login and the dev platform, hawk-app.json, the project (bridge, build script), scopes the code uses that hawk-app.json lacks, the template, the app on the platform and the MCP config.",
+            inputSchema: { dir: dirParam },
+            annotations: { ...readOnly, openWorldHint: true },
+        },
+        async ({ dir }) => result(await run(['doctor'], { dir })),
+    );
+
+    server.registerTool(
+        'versions',
+        {
+            title: 'App versions on dev',
+            description: "Every version on the dev platform with its status (draft, waiting, approved, rejected) and the aliases on it. Clients get their alias's version (default without one); users see it only when it's approved.",
+            inputSchema: { dir: dirParam },
+            annotations: { ...readOnly, openWorldHint: true },
+        },
+        async ({ dir }) => result(await run(['versions'], { dir })),
+    );
+
+    server.registerTool(
+        'why',
+        {
+            title: 'Why a client sees (or not) the app on dev',
+            description: "What a client's users see of the app on the dev platform, and why: the client list, the client's alias and that version's status. Takes the client id (e.g. e3141).",
+            inputSchema: { client: z.string().describe('The client id, e.g. e3141.'), dir: dirParam },
+            annotations: { ...readOnly, openWorldHint: true },
+        },
+        async ({ client, dir }) => result(await run(['why', client], { dir })),
+    );
+
+    server.registerTool(
+        'data_tables',
+        {
+            title: 'Analytics tables',
+            description: 'The analytics tables app queries (queries/*.sql, scope data:read) can use, including whether this app may use the sensitive ones. Names only, no data.',
+            inputSchema: { dir: dirParam },
+            annotations: { ...readOnly, openWorldHint: true },
+        },
+        async ({ dir }) => {
+            const slug = slugIn(root, dir);
+            return result(await run(['data', 'tables', ...(slug ? ['--app', slug] : [])], { dir }));
+        },
+    );
+
+    server.registerTool(
+        'data_describe',
+        {
+            title: 'Table columns',
+            description: "An analytics table's columns and types, for writing queries/*.sql. No data.",
+            inputSchema: { table: z.string().describe('A table name from data_tables.'), dir: dirParam },
+            annotations: { ...readOnly, openWorldHint: true },
+        },
+        async ({ table, dir }) => result(await run(['data', 'describe', table], { dir })),
+    );
+
+    server.registerTool(
+        'logs',
+        {
+            title: 'Function logs on dev',
+            description: "A function's logs on the dev platform (functions/<name>.ts).",
+            inputSchema: {
+                function: z.string().describe('The function name.'),
+                since: z.string().optional().describe('15m, 1h, 1d or an ISO time; default 1h.'),
+                dir: dirParam,
+            },
+            annotations: { ...readOnly, openWorldHint: true },
+        },
+        async ({ function: name, since, dir }) => result(await run(['logs', name, ...(since ? ['--since', since] : [])], { dir })),
+    );
+
+    server.registerTool(
+        'errors',
+        {
+            title: 'App errors on dev',
+            description: "Errors in the app's pages on the dev platform (uncaught errors, unhandled rejections, app.reportError), grouped by kind, the most frequent first, with versions, clients and the top stack frames.",
+            inputSchema: { days: z.number().int().min(1).max(30).optional().describe('Days back; default 7.'), dir: dirParam },
+            annotations: { ...readOnly, openWorldHint: true },
+        },
+        async ({ days, dir }) => result(await run(['errors', ...(days ? ['--days', String(days)] : [])], { dir })),
+    );
+
+    server.registerTool(
+        'usage',
+        {
+            title: 'App usage on dev',
+            description: 'Opens of the app and of its views, distinct users and clients per day on the dev platform (Bridgeline staff counted apart).',
+            inputSchema: { days: z.number().int().min(1).max(400).optional().describe('Days back; default 30.'), dir: dirParam },
+            annotations: { ...readOnly, openWorldHint: true },
+        },
+        async ({ days, dir }) => result(await run(['usage', ...(days ? ['--days', String(days)] : [])], { dir })),
+    );
+
+    server.registerTool(
+        'init',
+        {
+            title: 'Make a project a Hawk App',
+            description: 'For a project without hawk-app.json: writes it (refusing a slug that is already an app), plus AGENTS.md and the MCP settings. Then add the bridge and the base path as AGENTS.md says.',
+            inputSchema: { slug: z.string().optional(), name: z.string().optional(), dir: dirParam },
+            annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+        },
+        async ({ slug, name, dir }) => result(await run(['init', ...(slug ? ['--slug', slug] : []), ...(name ? ['--name', name] : [])], { dir })),
+    );
+
+    server.registerTool(
+        'upgrade',
+        {
+            title: 'Upgrade to the template',
+            description:
+                "Shows how the app differs from the CLI's template (package versions, unedited config files, AGENTS.md). apply: true changes those files and runs npm install. channel: 'latest' moves the bridge and CLI from dev builds to the released versions, 'dev' onto the dev builds (only when the user asks).",
+            inputSchema: { apply: z.boolean().optional(), channel: z.enum(['latest', 'dev']).optional(), dir: dirParam },
+            annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
+        },
+        async ({ apply, channel, dir }) => result(await run(['upgrade', ...(channel ? ['--channel', channel] : []), ...(apply ? ['--yes'] : [])], { dir })),
+    );
+
+    server.registerTool(
+        'deploy',
+        {
+            title: 'Deploy a version to dev',
+            description:
+                "Builds the app (npm run build with HAWK_APP_BASE_PATH) and uploads it as a new version on the dev platform, with hawk-app.json, queries/ and functions/. Runs npm audit first. alias: deploys off the main line and points that alias at the new version (only Bridgeline staff in its clients see it). dryRun: true only shows what hawk-app.json would change, and deploys nothing. Deploy only when the user asks (a dry run is fine any time).",
+            inputSchema: {
+                folder: z.string().optional().describe("The build output folder; default: the template's (dist, out, public)."),
+                alias: z.string().optional().describe('An alias, e.g. staging or preview-my-branch: lowercase letters, digits and dashes.'),
+                dryRun: z.boolean().optional().describe('Only show what hawk-app.json would change.'),
+                noBuild: z.boolean().optional().describe('Upload the folder as it is (plain HTML/JS).'),
+                force: z.boolean().optional().describe("Go on despite high or critical vulnerabilities, or a teammate's last change: only after the user says so."),
+                dir: dirParam,
+            },
+            annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+        },
+        async ({ folder, alias, dryRun, noBuild, force, dir }) =>
+            result(await run(['deploy', ...(folder ? [folder] : []), ...(alias ? ['--alias', alias] : []), ...(dryRun ? ['--dry-run'] : []), ...(noBuild ? ['--no-build'] : [])], { dir, force })),
+    );
+
+    server.registerTool(
+        'clients',
+        {
+            title: "The app's clients on dev",
+            description: "Which clients have the app on the dev platform (+ has it, - opted out), by id, and its visibility. Client names aren't shown.",
+            inputSchema: { dir: dirParam },
+            annotations: { ...readOnly, openWorldHint: true },
+        },
+        async ({ dir }) => result(await run(['clients'], { dir })),
+    );
+
+    server.registerTool(
+        'clients_add',
+        {
+            title: 'Give a client the app on dev',
+            description:
+                'Gives a client the app on the dev platform, at once (with visibility allowList, only listed clients have the app). Pass the user\'s words for the client ("OTC", "Outdoor Demo" or an id): the tool finds the matches and asks the user to pick one in a form. You hear only whether a client was added, never the names.',
+            inputSchema: {
+                client: z.string().describe('The client as the user named it, e.g. "OTC".'),
+                alias: z.string().optional().describe("The alias the client follows (the version it gets), e.g. \"review\"; \"default\" for the default. On an alias whose version isn't approved only Bridgeline staff in the client see the app."),
+                dir: dirParam,
+            },
+            annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+        },
+        async ({ client: words, alias, dir }) => {
+            const wanted = words.trim();
+            const slug = slugIn(root, dir);
+            if (!slug) return result({ ok: false, text: `No hawk-app.json in ${dir ?? 'the workspace'}: run this in the app's folder (dir).` });
+            if (wanted.length < 2) return result({ ok: false, text: "Ask the user for at least 2 characters of the client's name or id." });
+            const terminal = `In a terminal, in the app's folder: npx hawk-app clients add --pick "${wanted.replace(/"/g, '')}"${alias ? ` --alias ${alias}` : ''} --env dev`;
+            if (!server.server.getClientCapabilities()?.elicitation) {
+                return result({ ok: false, text: `This assistant can't show the user a form to pick the client, and client names aren't shared with you. Ask the user to run this themselves (it lists the matches for them to pick from):\n${terminal}` });
+            }
+
+            let devApi;
+            let found;
+            try {
+                devApi = platform(resolve(root, dir ?? '.'));
+                found = await devApi.searchClients(wanted);
+            } catch (error) {
+                return result({ ok: false, text: `✖ ${withoutNames(error)}` });
+            }
+            if (!found.clients?.length) {
+                return result({ ok: false, text: 'No client matches what the user typed. Ask them for another part of the name, or the id the dashboard shows (e.g. e3141).' });
+            }
+
+            let answer;
+            try {
+                answer = await server.server.elicitInput(
+                    {
+                        message: `Which client should get ${slug} on dev?${found.more ? " These are the best matches for what you typed: cancel and use more of the name if yours isn't here." : ''}`,
+                        requestedSchema: {
+                            type: 'object',
+                            properties: {
+                                client: { type: 'string', title: 'Client', oneOf: found.clients.map((c) => ({ const: c.id, title: c.name ? `${c.name} (${c.id})` : c.id })) },
+                            },
+                            required: ['client'],
+                        },
+                    },
+                    { timeout: PICK_TIMEOUT_MS },
+                );
+            } catch {
+                // Not shown, not answered in time, or answered with something other than the choices (the SDK checks).
+                return result({ ok: false, text: `The form to pick the client didn't get an answer. Nothing was changed. Ask the user to try again, or to run:\n${terminal}` });
+            }
+            const id = answer.action === 'accept' ? answer.content?.client : undefined;
+            if (!found.clients.some((c) => c.id === id)) {
+                return result({ ok: false, text: 'The user cancelled: no client was added. Ask them what they want instead.' });
+            }
+
+            try {
+                await devApi.setClient(slug, id, { enabled: true, ...(alias ? { alias } : {}) });
+            } catch (error) {
+                if (error.data?.code === 'approver_required') return result({ ok: false, text: "The client's users see the app now: only an approver can change what it gets (the app's Rollout tab in the Hawk Analytics portal, or HawkSearch). Nothing was changed." });
+                return result({ ok: false, text: `✖ The client wasn't added: ${withoutNames(error)}` });
+            }
+            return result({ ok: true, text: `✔ Added the client the user picked to ${slug} on dev${alias ? ` on ${alias}` : ''}. It applies now (recorded in the app's history). The user saw its name in the form; it isn't shared here.` });
+        },
+    );
+
+    registerPrompts(server);
+    return server;
+}
+
+/**
+ * Prompts: ready-made tasks that clients list where developers look (Claude Code shows them as slash commands), so
+ * the tools are found without reading about them. Each one tells the assistant which tools to use, in what order.
+ */
+const PROMPTS = {
+    'check-before-submit': {
+        title: 'Check before submitting for approval',
+        description: 'Validates the app (with a build check), reads its status, review checks and errors on dev, and explains how to fix anything an approver would have to force approve.',
+        text: (dir) => `Check this Hawk App${where(dir)} before it's submitted for approval in HawkSearch.
+1. Run the hawk-apps \`validate\` tool with build: true${dirArg(dir)}. Fix what it reports in the code (ask me before changing hawk-app.json scopes or externalOrigins).
+2. Run \`status\`${dirArg(dir)}, and \`deploy\` with dryRun: true to see what hawk-app.json would change. If the app isn't on the platform or its newest version is older than the code, say so: I decide when to deploy.
+3. For each review check that fails or needs attention (bundle, dependencies, accessibility, external origins, queries, functions, external Lambdas), explain what an approver will see and how to fix it, using \`docs\` where it helps.
+4. Run \`errors\`${dirArg(dir)} and fix the errors the deployed versions threw, the most frequent first.
+End with a short list: ready to submit, or what's left to do.`,
+    },
+    'add-feature': {
+        title: 'Add a feature',
+        description: 'Builds a feature the Hawk Apps way: finds the right bridge calls, scopes and examples in the docs, makes the change, and validates it.',
+        args: { feature: z.string().describe('What to build, e.g. "a chart of searches per day for the selected date range".') },
+        text: (dir, { feature }) => `Add this feature to the Hawk App${where(dir)}: ${feature}
+1. Read AGENTS.md. Use the hawk-apps \`docs\` tool to find the bridge calls it needs (their options, limits and error codes) and a working example in the showcase sections. Prefer what the bridge offers over anything custom.
+2. Tell me which scopes, analytics reports (check them with \`analytics_reports\`), HawkSearch API calls (check them with \`hawksearch_api\`), queries (queries/*.sql, check tables and columns with \`data_tables\` and \`data_describe\`) or functions it needs, and anything that makes the review harder (elevated scopes, new outside origins), before changing hawk-app.json.
+3. Make the change in the app's style. Handle a client without analytics and the errors the docs list.
+4. Run \`validate\`${dirArg(dir)} and fix what it reports. Don't deploy unless I ask.`,
+    },
+    'deploy-to-client': {
+        title: 'Deploy to a client',
+        description: 'Deploys a new version to dev and gives a client the app: you pick the client from the matches for its name.',
+        args: { client: z.string().describe('The client\'s name or id, e.g. "OTC" or "Outdoor Demo".') },
+        text: (dir, { client }) => `Deploy this Hawk App${where(dir)} to the client "${client}" on dev.
+1. Run the hawk-apps \`deploy\` tool${dirArg(dir)}. If it asks a question, ask me.
+2. Run \`clients_add\` with client "${client}"${dirArg(dir)}. It asks me to pick the exact client; if it says it can't, tell me the command it gives.
+3. Run \`status\`${dirArg(dir)}.
+End with where I'll find it: the HawkSearch dev dashboard, with the client I picked selected, on the Apps page.`,
+    },
+    'explain-app': {
+        title: 'Explain this app',
+        description: 'Summarizes what the app does, the data and scopes it uses, and where it stands in review on dev.',
+        text: (dir) => `Explain this Hawk App${where(dir)} to me.
+1. Read hawk-app.json, AGENTS.md and the main source files: what does the app do, for whom, and which bridge calls, queries and functions does it use?
+2. Which scopes does it ask for, and are any unused or missing for what the code calls?
+3. Run the hawk-apps \`status\` tool${dirArg(dir)}: what's released, what's waiting for approval, and what do the review checks say?
+Keep it short: a paragraph, then bullets.`,
+    },
+};
+
+const where = (dir) => (dir ? ` in ${dir}` : '');
+const dirArg = (dir) => (dir ? ` (dir: "${dir}")` : '');
+
+function registerPrompts(server) {
+    for (const [name, prompt] of Object.entries(PROMPTS)) {
+        server.registerPrompt(
+            name,
+            {
+                title: prompt.title,
+                description: prompt.description,
+                argsSchema: { ...prompt.args, dir: z.string().optional().describe("The app's folder, when the workspace has several apps.") },
+            },
+            ({ dir, ...args }) => ({
+                description: prompt.description,
+                messages: [{ role: 'user', content: { type: 'text', text: prompt.text(dir?.trim() || undefined, args) } }],
+            }),
+        );
+    }
+}
+
+/** `hawk-app mcp`: serves the tools over stdio until the client closes the connection. */
+export async function serveMcp({ version } = {}) {
+    // stdout belongs to the protocol: anything else printed by mistake goes to stderr.
+    console.log = (...args) => console.error(...args);
+    const server = createMcpServer({ version });
+    const closed = new Promise((resolveClosed) => {
+        server.server.onclose = resolveClosed;
+    });
+    await server.connect(new StdioServerTransport());
+    await closed;
+    return 0;
+}