specrails-desktop 2.15.0 → 2.17.0

package/server/dist/mcp/tools/agents.js

@@ -0,0 +1,319 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentsTools = agentsTools;
+const zod_1 = require("zod");
+const types_1 = require("./types");
+/**
+ * Agents domain — agent PROFILES (declarative per-project routing config) and
+ * the agents CATALOG (the `.claude/agents/*.md` definitions: read-only `sr-*`
+ * upstream agents + user-authored `custom-*` agents, with AI generate/test/
+ * iterative-refine on the custom ones).
+ *
+ * CLAUDE-ONLY: agent profiles are a Claude concept. On a project whose primary
+ * provider (or any installed provider) is codex/gemini, rails force-null the
+ * profile and the whole section is hidden client-side — creating profiles for a
+ * non-Claude project is mostly inert. The server still validates against that
+ * provider's adapter catalog. Prefer using this tool on Claude projects.
+ *
+ * Every operation is per-project (mounted at /api/projects/:projectId/profiles)
+ * and is gated by SPECRAILS_AGENTS_SECTION — a disabled server 404s every route.
+ *
+ * The catalog `generate`, `test`, `refine_start`, and `refine_turn` actions
+ * SPAWN the claude CLI and incur real cost (refine records ai_invocations and
+ * streams agent_refine_* WS events). `refine_apply` / `update_custom` /
+ * `delete_custom` / `create_custom` mutate `custom-*.md` files on disk.
+ */
+function agentsTools() {
+    return [
+        {
+            name: 'specrails_agents',
+            title: 'Agents (Profiles & Catalog)',
+            description: 'Manage agent PROFILES and the agents CATALOG for a project (Claude-only — profiles are inert on codex/gemini projects). ' +
+                'PROFILE actions: list, get, resolve (preview which profile a rail would resolve to), create, update, delete (destructive — protected default/project-default cannot be deleted), ' +
+                'duplicate, rename, migrate (seed a default profile from installed sr-*.md frontmatter), analytics (per-profile metrics), core_version (specrails-core version + 4.1.0 profile-aware check). ' +
+                'CATALOG actions: catalog_list, catalog_get (full agent .md body), versions (custom agent edit history), create_custom (custom-*.md), update_custom, delete_custom (destructive), ' +
+                'generate (AI-generate a draft custom agent — spawns claude, costs), test (AI smoke-test a draft body — spawns claude, costs), ' +
+                'refine_start / refine_turn (AI iterative refine of a custom agent — spawn claude, cost, stream over WS), refine_list, refine_get, refine_patch (toggle autoTest), refine_cancel (kill the spawn), refine_apply (write the refined draft to disk).',
+            hintTier: 'read',
+            tier: (a) => {
+                const action = a.action;
+                if (['delete', 'delete_custom'].includes(action))
+                    return 'destructive';
+                if (['generate', 'test', 'refine_start', 'refine_turn'].includes(action))
+                    return 'ai-spawn';
+                if ([
+                    'create',
+                    'update',
+                    'duplicate',
+                    'rename',
+                    'migrate',
+                    'create_custom',
+                    'update_custom',
+                    'refine_patch',
+                    'refine_cancel',
+                    'refine_apply',
+                ].includes(action)) {
+                    return 'write';
+                }
+                return 'read';
+            },
+            inputSchema: {
+                action: zod_1.z
+                    .enum([
+                    // PROFILES
+                    'list',
+                    'get',
+                    'resolve',
+                    'create',
+                    'update',
+                    'delete',
+                    'duplicate',
+                    'rename',
+                    'migrate',
+                    'analytics',
+                    'core_version',
+                    // CATALOG (definitions)
+                    'catalog_list',
+                    'catalog_get',
+                    'versions',
+                    'create_custom',
+                    'update_custom',
+                    'delete_custom',
+                    'generate',
+                    'test',
+                    // CATALOG (AI refine)
+                    'refine_start',
+                    'refine_turn',
+                    'refine_list',
+                    'refine_get',
+                    'refine_patch',
+                    'refine_cancel',
+                    'refine_apply',
+                ])
+                    .describe('Operation to perform (profile or catalog action)'),
+                projectId: zod_1.z.string().optional().describe('Project id (defaults to the active project)'),
+                // Profile params
+                name: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Profile name (get/update/delete/duplicate/rename source). For duplicate/rename, the NEW name goes in `newName`.'),
+                newName: zod_1.z.string().optional().describe('New profile name (for duplicate / rename)'),
+                profileName: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Explicit profile name to preview in `resolve` (omit to resolve the project default)'),
+                profile: zod_1.z
+                    .record(zod_1.z.unknown())
+                    .optional()
+                    .describe('Full Profile body for create/update: { schemaVersion:1, name, description?, provider?, orchestrator:{model}, agents:[], routing:[] }'),
+                windowDays: zod_1.z.number().int().optional().describe('analytics time window in days (1-365, default 30)'),
+                // Catalog params
+                agentId: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Agent id for catalog_get/versions/update_custom/delete_custom and all refine actions (custom-* for mutations, sr-*|custom-* for reads)'),
+                body: zod_1.z.string().optional().describe('Agent .md body (for create_custom / update_custom)'),
+                agentName: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('New custom agent id for create_custom — must match ^custom-[a-z0-9][a-z0-9-]*$'),
+                description: zod_1.z.string().optional().describe('Plain-language description for `generate` (AI draft a custom agent)'),
+                draftBody: zod_1.z.string().optional().describe('Draft agent body to smoke-test in `test`'),
+                sampleTask: zod_1.z.string().optional().describe('Sample task the `test` action runs the draft against'),
+                instruction: zod_1.z.string().optional().describe('Refine instruction (for refine_start / refine_turn)'),
+                autoTest: zod_1.z.boolean().optional().describe('Auto-test the refined draft (refine_start default true; refine_patch toggles it)'),
+                refineId: zod_1.z.string().optional().describe('Refine session id (for refine_get/refine_turn/refine_patch/refine_cancel/refine_apply)'),
+                force: zod_1.z.boolean().optional().describe('Bypass the disk-hash guard when applying a refine draft (refine_apply)'),
+            },
+            async handler(ctx, args) {
+                const base = `${(0, types_1.projectPath)(ctx, args.projectId)}/profiles`;
+                const action = args.action;
+                const agentId = args.agentId;
+                const refineId = args.refineId;
+                const profileName = args.name;
+                switch (action) {
+                    // ── PROFILES ────────────────────────────────────────────────────
+                    case 'list':
+                        return (0, types_1.apiCall)(ctx, 'GET', base);
+                    case 'get': {
+                        if (!profileName)
+                            throw new Error('get requires a profile "name".');
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/${encodeURIComponent(profileName)}`);
+                    }
+                    case 'resolve': {
+                        const p = args.profileName;
+                        const qs = p ? `?profile=${encodeURIComponent(p)}` : '';
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/resolve${qs}`);
+                    }
+                    case 'create': {
+                        if (!args.profile)
+                            throw new Error('create requires a "profile" body.');
+                        return (0, types_1.apiCall)(ctx, 'POST', base, args.profile);
+                    }
+                    case 'update': {
+                        if (!profileName)
+                            throw new Error('update requires a profile "name".');
+                        if (!args.profile)
+                            throw new Error('update requires a "profile" body (its name must equal "name").');
+                        return (0, types_1.apiCall)(ctx, 'PATCH', `${base}/${encodeURIComponent(profileName)}`, args.profile);
+                    }
+                    case 'delete': {
+                        if (!profileName)
+                            throw new Error('delete requires a profile "name".');
+                        return (0, types_1.apiCall)(ctx, 'DELETE', `${base}/${encodeURIComponent(profileName)}`);
+                    }
+                    case 'duplicate': {
+                        if (!profileName)
+                            throw new Error('duplicate requires a source profile "name".');
+                        const newName = args.newName;
+                        if (!newName)
+                            throw new Error('duplicate requires a "newName".');
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/${encodeURIComponent(profileName)}/duplicate`, { name: newName });
+                    }
+                    case 'rename': {
+                        if (!profileName)
+                            throw new Error('rename requires a source profile "name".');
+                        const newName = args.newName;
+                        if (!newName)
+                            throw new Error('rename requires a "newName".');
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/${encodeURIComponent(profileName)}/rename`, { name: newName });
+                    }
+                    case 'migrate':
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/migrate-from-settings`);
+                    case 'analytics': {
+                        const wd = args.windowDays;
+                        const qs = typeof wd === 'number' ? `?windowDays=${wd}` : '';
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/analytics${qs}`);
+                    }
+                    case 'core_version':
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/core-version`);
+                    // ── CATALOG: definitions ────────────────────────────────────────
+                    case 'catalog_list':
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/catalog`);
+                    case 'catalog_get': {
+                        if (!agentId)
+                            throw new Error('catalog_get requires an "agentId".');
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/catalog/${encodeURIComponent(agentId)}`);
+                    }
+                    case 'versions': {
+                        if (!agentId)
+                            throw new Error('versions requires an "agentId".');
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/catalog/${encodeURIComponent(agentId)}/versions`);
+                    }
+                    case 'create_custom': {
+                        const id = args.agentName;
+                        const body = args.body;
+                        if (!id)
+                            throw new Error('create_custom requires an "agentName" (custom-* id).');
+                        if (!body)
+                            throw new Error('create_custom requires a "body".');
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/catalog`, { id, body });
+                    }
+                    case 'update_custom': {
+                        if (!agentId)
+                            throw new Error('update_custom requires an "agentId" (custom-* only).');
+                        const body = args.body;
+                        if (!body)
+                            throw new Error('update_custom requires a "body".');
+                        return (0, types_1.apiCall)(ctx, 'PATCH', `${base}/catalog/${encodeURIComponent(agentId)}`, { body });
+                    }
+                    case 'delete_custom': {
+                        if (!agentId)
+                            throw new Error('delete_custom requires an "agentId" (custom-* only).');
+                        return (0, types_1.apiCall)(ctx, 'DELETE', `${base}/catalog/${encodeURIComponent(agentId)}`);
+                    }
+                    // ── CATALOG: AI spawns (cost) ───────────────────────────────────
+                    case 'generate': {
+                        const name = args.agentName;
+                        const description = args.description;
+                        if (!name)
+                            throw new Error('generate requires an "agentName" (custom-* id).');
+                        if (!description)
+                            throw new Error('generate requires a "description".');
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/catalog/generate`, { name, description });
+                    }
+                    case 'test': {
+                        const draftBody = args.draftBody;
+                        const sampleTask = args.sampleTask;
+                        if (!draftBody)
+                            throw new Error('test requires a "draftBody".');
+                        if (!sampleTask)
+                            throw new Error('test requires a "sampleTask".');
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/catalog/test`, {
+                            ...(agentId ? { agentId } : {}),
+                            draftBody,
+                            sampleTask,
+                        });
+                    }
+                    // ── CATALOG: AI refine sessions ─────────────────────────────────
+                    case 'refine_start': {
+                        if (!agentId)
+                            throw new Error('refine_start requires an "agentId" (custom-* only).');
+                        const instruction = args.instruction;
+                        if (!instruction)
+                            throw new Error('refine_start requires an "instruction".');
+                        const r = await (0, types_1.apiCall)(ctx, 'POST', `${base}/catalog/${encodeURIComponent(agentId)}/refine`, {
+                            instruction,
+                            ...(typeof args.autoTest === 'boolean' ? { autoTest: args.autoTest } : {}),
+                        });
+                        return {
+                            ...r,
+                            hint: 'Refine streams over WS (agent_refine_* events). Use refine_get with the returned refineId to poll the session, then refine_apply to write the draft to disk.',
+                        };
+                    }
+                    case 'refine_turn': {
+                        if (!agentId)
+                            throw new Error('refine_turn requires an "agentId".');
+                        if (!refineId)
+                            throw new Error('refine_turn requires a "refineId".');
+                        const instruction = args.instruction;
+                        if (!instruction)
+                            throw new Error('refine_turn requires an "instruction".');
+                        const r = await (0, types_1.apiCall)(ctx, 'POST', `${base}/catalog/${encodeURIComponent(agentId)}/refine/${encodeURIComponent(refineId)}/turn`, { instruction });
+                        return {
+                            ...r,
+                            hint: 'The turn streams over WS (agent_refine_* events). Use refine_get with the refineId to read the updated draft.',
+                        };
+                    }
+                    case 'refine_list': {
+                        if (!agentId)
+                            throw new Error('refine_list requires an "agentId".');
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/catalog/${encodeURIComponent(agentId)}/refine`);
+                    }
+                    case 'refine_get': {
+                        if (!agentId)
+                            throw new Error('refine_get requires an "agentId".');
+                        if (!refineId)
+                            throw new Error('refine_get requires a "refineId".');
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/catalog/${encodeURIComponent(agentId)}/refine/${encodeURIComponent(refineId)}`);
+                    }
+                    case 'refine_patch': {
+                        if (!agentId)
+                            throw new Error('refine_patch requires an "agentId".');
+                        if (!refineId)
+                            throw new Error('refine_patch requires a "refineId".');
+                        if (typeof args.autoTest !== 'boolean')
+                            throw new Error('refine_patch requires a boolean "autoTest".');
+                        return (0, types_1.apiCall)(ctx, 'PATCH', `${base}/catalog/${encodeURIComponent(agentId)}/refine/${encodeURIComponent(refineId)}`, { autoTest: args.autoTest });
+                    }
+                    case 'refine_cancel': {
+                        if (!agentId)
+                            throw new Error('refine_cancel requires an "agentId".');
+                        if (!refineId)
+                            throw new Error('refine_cancel requires a "refineId".');
+                        return (0, types_1.apiCall)(ctx, 'DELETE', `${base}/catalog/${encodeURIComponent(agentId)}/refine/${encodeURIComponent(refineId)}`);
+                    }
+                    case 'refine_apply': {
+                        if (!agentId)
+                            throw new Error('refine_apply requires an "agentId".');
+                        if (!refineId)
+                            throw new Error('refine_apply requires a "refineId".');
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/catalog/${encodeURIComponent(agentId)}/refine/${encodeURIComponent(refineId)}/apply`, { ...(typeof args.force === 'boolean' ? { force: args.force } : {}) });
+                    }
+                    default:
+                        throw new Error(`Unknown action "${action}".`);
+                }
+            },
+        },
+    ];
+}

package/server/dist/mcp/tools/analytics.js

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyticsTools = analyticsTools;
+const zod_1 = require("zod");
+const types_1 = require("./types");
+/**
+ * Build a `?a=b&c=d` query string from a flat record, skipping undefined/null/''
+ * values. Arrays are joined with commas (the spending router parses CSV for
+ * surface/model/modelProvider/provider). Used by the read actions below.
+ */
+function buildQuery(params) {
+    const parts = [];
+    for (const [k, v] of Object.entries(params)) {
+        if (v === undefined || v === null || v === '')
+            continue;
+        const value = Array.isArray(v) ? v.join(',') : String(v);
+        if (value === '')
+            continue;
+        parts.push(`${encodeURIComponent(k)}=${encodeURIComponent(value)}`);
+    }
+    return parts.length ? `?${parts.join('&')}` : '';
+}
+function analyticsTools() {
+    return [
+        {
+            name: 'specrails_analytics',
+            title: 'Analytics & Spending',
+            description: 'Per-project cost analytics over billable AI-CLI invocations (jobs, quick-spec, explore-spec, ai-edit, smash, file-summary, loop). ' +
+                'All read-only except set_budget. Actions: ' +
+                'spending (full dashboard: cost summary with prev-period delta, by-surface/model/mode/provider breakdowns, daily timeline, cost-vs-turns scatter, top tickets), ' +
+                'invocations (paginated raw invocation table), ' +
+                'ticket_summary (per-ticket cost aggregate across all surfaces), ' +
+                'export (download summary/raw analytics as CSV or JSON — file download, returns a note + headers), ' +
+                'budget_get (daily budget, per-job threshold, cost-today, utilization %), ' +
+                'budget_set (write — set/clear daily budget cap + per-job cost threshold; a too-low budget pauses the job queue). ' +
+                'Prefer spending over invocations/export-raw for token economy. ' +
+                'Filters: period(7d|30d|90d|all|custom), from/to (ISO, required for custom), surface[], model[], modelProvider[] (index-aligned to model), provider[], status(success|failed|aborted), minCostUsd, ticketId, tzOffsetMinutes(±840 — pass the user local offset so "today" lines up), sortBy.',
+            hintTier: 'read',
+            tier: (a) => (a.action === 'budget_set' ? 'write' : 'read'),
+            inputSchema: {
+                action: zod_1.z
+                    .enum(['spending', 'invocations', 'ticket_summary', 'export', 'budget_get', 'budget_set'])
+                    .describe('Operation to perform'),
+                projectId: zod_1.z.string().optional().describe('Project id (defaults to the active project)'),
+                // ─── Filters shared by spending / invocations / export ────────────────
+                period: zod_1.z
+                    .enum(['7d', '30d', '90d', 'all', 'custom'])
+                    .optional()
+                    .describe('Time window (default 30d). "custom" requires from + to.'),
+                from: zod_1.z.string().optional().describe('ISO start date (required when period=custom)'),
+                to: zod_1.z.string().optional().describe('ISO end date (required when period=custom)'),
+                surface: zod_1.z
+                    .array(zod_1.z.enum(['job', 'quick-spec', 'explore-spec', 'ai-edit', 'smash', 'file-summary', 'loop']))
+                    .optional()
+                    .describe('Filter to these surfaces (CSV)'),
+                model: zod_1.z.array(zod_1.z.string()).optional().describe('Filter to these model ids (CSV)'),
+                modelProvider: zod_1.z
+                    .array(zod_1.z.string())
+                    .optional()
+                    .describe('Providers index-aligned to model[] (scopes each model id to its provider so codex/gemini estimated cost does not merge into a claude bar)'),
+                provider: zod_1.z
+                    .array(zod_1.z.string())
+                    .optional()
+                    .describe('Filter to these providers (e.g. claude, codex, gemini) (CSV)'),
+                status: zod_1.z.enum(['success', 'failed', 'aborted']).optional().describe('Filter by invocation status'),
+                minCostUsd: zod_1.z.number().optional().describe('Only invocations costing at least this many USD'),
+                ticketId: zod_1.z.number().int().optional().describe('Scope to a single ticket id'),
+                tzOffsetMinutes: zod_1.z
+                    .number()
+                    .int()
+                    .optional()
+                    .describe('Local UTC offset in minutes (±840) for daily-timeline calendar-day bucketing (default 0 = UTC)'),
+                sortBy: zod_1.z.enum(['recency', 'cost']).optional().describe('Sort order'),
+                // ─── invocations pagination ───────────────────────────────────────────
+                limit: zod_1.z
+                    .number()
+                    .int()
+                    .optional()
+                    .describe('invocations: max rows (clamped server-side to [1, 10000])'),
+                offset: zod_1.z.number().int().optional().describe('invocations: row offset for pagination'),
+                // ─── ticket_summary ───────────────────────────────────────────────────
+                id: zod_1.z.number().int().optional().describe('ticket_summary: the ticket id to aggregate'),
+                // ─── export ───────────────────────────────────────────────────────────
+                format: zod_1.z.enum(['csv', 'json']).optional().describe('export: output format (default json)'),
+                mode: zod_1.z
+                    .enum(['summary', 'raw'])
+                    .optional()
+                    .describe('export: summary (aggregated dashboard) or raw (up to 10000 invocation rows). Default summary.'),
+                // ─── budget_set ───────────────────────────────────────────────────────
+                dailyBudgetUsd: zod_1.z
+                    .number()
+                    .nullable()
+                    .optional()
+                    .describe('budget_set: daily budget cap USD (>0); null clears it'),
+                jobCostThresholdUsd: zod_1.z
+                    .number()
+                    .nullable()
+                    .optional()
+                    .describe('budget_set: per-job cost alert threshold USD (>0); null clears it'),
+            },
+            async handler(ctx, args) {
+                const base = (0, types_1.projectPath)(ctx, args.projectId);
+                const action = args.action;
+                const filters = {
+                    period: args.period,
+                    from: args.from,
+                    to: args.to,
+                    surface: args.surface,
+                    model: args.model,
+                    modelProvider: args.modelProvider,
+                    provider: args.provider,
+                    status: args.status,
+                    minCostUsd: args.minCostUsd,
+                    ticketId: args.ticketId,
+                    tzOffsetMinutes: args.tzOffsetMinutes,
+                    sortBy: args.sortBy,
+                };
+                switch (action) {
+                    case 'spending':
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/spending${buildQuery(filters)}`);
+                    case 'invocations':
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/invocations${buildQuery({
+                            ...filters,
+                            limit: args.limit,
+                            offset: args.offset,
+                        })}`);
+                    case 'ticket_summary': {
+                        const id = args.id;
+                        if (id === undefined || id === null) {
+                            throw new Error('ticket_summary requires an "id" (ticket id).');
+                        }
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/tickets/${id}/spending-summary`);
+                    }
+                    case 'export': {
+                        // GET /analytics/export streams a file download (Content-Disposition).
+                        // apiCall returns the body text/JSON; for CSV it is the raw CSV string,
+                        // for JSON the parsed dashboard/invocations object. We surface it
+                        // inline with a note since there is no file sink over MCP.
+                        const format = args.format ?? 'json';
+                        const mode = args.mode ?? 'summary';
+                        const data = await (0, types_1.apiCall)(ctx, 'GET', `${base}/analytics/export${buildQuery({ ...filters, format, mode })}`);
+                        return {
+                            note: `Analytics export (mode=${mode}, format=${format}). This endpoint is normally a file download; the content is returned inline below. Raw mode caps at 10000 rows. Prefer the "spending" action for already-aggregated, bounded data.`,
+                            format,
+                            mode,
+                            data,
+                        };
+                    }
+                    case 'budget_get':
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/budget`);
+                    case 'budget_set': {
+                        const body = {};
+                        if ('dailyBudgetUsd' in args)
+                            body.dailyBudgetUsd = args.dailyBudgetUsd;
+                        if ('jobCostThresholdUsd' in args)
+                            body.jobCostThresholdUsd = args.jobCostThresholdUsd;
+                        if (Object.keys(body).length === 0) {
+                            throw new Error('budget_set requires dailyBudgetUsd and/or jobCostThresholdUsd (number>0 to set, null to clear).');
+                        }
+                        return (0, types_1.apiCall)(ctx, 'PATCH', `${base}/budget`, body);
+                    }
+                    default:
+                        throw new Error(`Unknown action "${action}".`);
+                }
+            },
+        },
+    ];
+}

package/server/dist/mcp/tools/app-settings.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appTools = appTools;
+const zod_1 = require("zod");
+const desktop_db_1 = require("../../desktop-db");
+const mcp_tiers_1 = require("../mcp-tiers");
+// App-level settings the MCP may read/write. NOTE: the MCP enable flag and the
+// permission-tier toggles are intentionally NOT writable here — an external LLM
+// must never be able to escalate its own permissions. Those are user-only,
+// changed in the Settings ▸ MCP panel.
+const WRITABLE_THEMES = ['specrails', 'dracula', 'aurora-light', 'obsidian-dark', 'matrix'];
+const WRITABLE_LANGS = ['en', 'es', 'fr', 'de', 'pt', 'it', 'zh', 'ja'];
+function appTools() {
+    return [
+        {
+            name: 'specrails_settings',
+            title: 'App settings',
+            description: 'Read or update app-level Specrails settings (theme, language, daily budget, cost-alert threshold). ' +
+                'Actions: get, set. The MCP enable flag and permission tiers are read-only here (user-controlled in the app).',
+            hintTier: 'read',
+            tier: (args) => (args.action === 'set' ? 'write' : 'read'),
+            inputSchema: {
+                action: zod_1.z.enum(['get', 'set']).describe('Operation'),
+                theme: zod_1.z.enum(WRITABLE_THEMES).optional(),
+                language: zod_1.z.enum(WRITABLE_LANGS).optional(),
+                dailyBudgetUsd: zod_1.z.number().min(0).nullable().optional(),
+                costAlertThresholdUsd: zod_1.z.number().min(0).nullable().optional(),
+            },
+            handler: (ctx, args) => {
+                const db = ctx.desktopDb;
+                if (args.action === 'get') {
+                    return {
+                        theme: (0, desktop_db_1.getDesktopSetting)(db, 'ui_theme') ?? 'specrails',
+                        language: (0, desktop_db_1.getDesktopSetting)(db, 'ui_language') ?? null,
+                        dailyBudgetUsd: num((0, desktop_db_1.getDesktopSetting)(db, 'desktop_daily_budget_usd')),
+                        costAlertThresholdUsd: num((0, desktop_db_1.getDesktopSetting)(db, 'cost_alert_threshold_usd')),
+                        mcp: {
+                            enabled: (0, mcp_tiers_1.isMcpEnabled)(db),
+                            tierWrite: (0, mcp_tiers_1.isTierEnabled)(db, 'write'),
+                            tierAiSpawn: (0, mcp_tiers_1.isTierEnabled)(db, 'ai-spawn'),
+                            tierDestructive: (0, mcp_tiers_1.isTierEnabled)(db, 'destructive'),
+                        },
+                    };
+                }
+                // set
+                const changed = [];
+                if (args.theme !== undefined) {
+                    (0, desktop_db_1.setDesktopSetting)(db, 'ui_theme', String(args.theme));
+                    changed.push('theme');
+                }
+                if (args.language !== undefined) {
+                    (0, desktop_db_1.setDesktopSetting)(db, 'ui_language', String(args.language));
+                    changed.push('language');
+                }
+                if (args.dailyBudgetUsd !== undefined) {
+                    writeNumOrClear(db, 'desktop_daily_budget_usd', args.dailyBudgetUsd);
+                    changed.push('dailyBudgetUsd');
+                }
+                if (args.costAlertThresholdUsd !== undefined) {
+                    writeNumOrClear(db, 'cost_alert_threshold_usd', args.costAlertThresholdUsd);
+                    changed.push('costAlertThresholdUsd');
+                }
+                if (!changed.length)
+                    throw new Error('set requires at least one field (theme, language, dailyBudgetUsd, costAlertThresholdUsd).');
+                return { ok: true, changed };
+            },
+        },
+    ];
+}
+function num(v) {
+    if (v === undefined)
+        return null;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : null;
+}
+function writeNumOrClear(db, key, value) {
+    if (value === null)
+        (0, desktop_db_1.setDesktopSetting)(db, key, '');
+    else
+        (0, desktop_db_1.setDesktopSetting)(db, key, String(value));
+}

package/server/dist/mcp/tools/catalog.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildToolSpecs = buildToolSpecs;
+const projects_1 = require("./projects");
+const app_settings_1 = require("./app-settings");
+const watch_1 = require("./watch");
+const meta_1 = require("./meta");
+const specs_1 = require("./specs");
+const rails_1 = require("./rails");
+const jobs_1 = require("./jobs");
+const chat_1 = require("./chat");
+const agents_1 = require("./agents");
+const plugins_1 = require("./plugins");
+const jira_1 = require("./jira");
+const loops_1 = require("./loops");
+const code_1 = require("./code");
+const setup_1 = require("./setup");
+const analytics_1 = require("./analytics");
+/**
+ * The full MCP tool catalog. Domain-facade tools each expose an `action` enum
+ * and call the app's REST API over loopback (see apiCall). Meta tools receive a
+ * lazy getter so `search`/`describe` can see the whole list.
+ */
+function buildToolSpecs() {
+    const specs = [];
+    // App-level + meta + watch
+    specs.push(...(0, projects_1.projectsTools)());
+    specs.push(...(0, app_settings_1.appTools)());
+    specs.push((0, watch_1.watchTool)());
+    // Per-project domains
+    specs.push(...(0, specs_1.specsTools)());
+    specs.push(...(0, rails_1.railsTools)());
+    specs.push(...(0, jobs_1.jobsTools)());
+    specs.push(...(0, chat_1.chatTools)());
+    specs.push(...(0, agents_1.agentsTools)());
+    specs.push(...(0, plugins_1.pluginsTools)());
+    specs.push(...(0, jira_1.jiraTools)());
+    specs.push(...(0, loops_1.loopsTools)());
+    specs.push(...(0, code_1.codeTools)());
+    specs.push(...(0, setup_1.setupTools)());
+    specs.push(...(0, analytics_1.analyticsTools)());
+    // Meta last (needs the full list for search/describe)
+    specs.push(...(0, meta_1.metaTools)(() => specs));
+    return specs;
+}