specrails-desktop 2.16.0 → 2.18.0

package/server/dist/agent-store.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAgentConversation = createAgentConversation;
+exports.getAgentConversation = getAgentConversation;
+exports.listAgentConversations = listAgentConversations;
+exports.updateAgentConversation = updateAgentConversation;
+exports.deleteAgentConversation = deleteAgentConversation;
+exports.addAgentMessage = addAgentMessage;
+exports.listAgentMessages = listAgentMessages;
+const crypto_1 = require("crypto");
+const agent_tier_1 = require("./agent-tier");
+function mapConversation(row) {
+    if (!row)
+        return undefined;
+    return { ...row, tier_level: (0, agent_tier_1.normalizeLevel)(row.tier_level) };
+}
+function createAgentConversation(db, input = {}) {
+    const id = (0, crypto_1.randomUUID)();
+    db.prepare(`INSERT INTO agent_conversations (id, provider, model, pinned_project_id, tier_level)
+     VALUES (?, ?, ?, ?, ?)`).run(id, input.provider ?? 'claude', input.model ?? null, input.pinnedProjectId ?? null, input.tierLevel ?? 0);
+    return getAgentConversation(db, id);
+}
+function getAgentConversation(db, id) {
+    return mapConversation(db.prepare('SELECT * FROM agent_conversations WHERE id = ?').get(id));
+}
+function listAgentConversations(db, limit = 100) {
+    return db
+        .prepare('SELECT * FROM agent_conversations ORDER BY updated_at DESC LIMIT ?')
+        .all(limit).map((r) => mapConversation(r));
+}
+/** Patch a conversation. Only the provided fields change; `updated_at` always bumps. */
+function updateAgentConversation(db, id, patch) {
+    const sets = [];
+    const vals = [];
+    for (const [k, v] of Object.entries(patch)) {
+        sets.push(`${k} = ?`);
+        vals.push(v);
+    }
+    sets.push("updated_at = datetime('now')");
+    if (sets.length > 0) {
+        db.prepare(`UPDATE agent_conversations SET ${sets.join(', ')} WHERE id = ?`).run(...vals, id);
+    }
+    return getAgentConversation(db, id);
+}
+function deleteAgentConversation(db, id) {
+    db.prepare('DELETE FROM agent_conversations WHERE id = ?').run(id);
+}
+function addAgentMessage(db, input) {
+    const id = (0, crypto_1.randomUUID)();
+    db.prepare('INSERT INTO agent_messages (id, conversation_id, role, content) VALUES (?, ?, ?, ?)').run(id, input.conversationId, input.role, input.content);
+    // Touch the parent so the list stays ordered by latest activity.
+    db.prepare("UPDATE agent_conversations SET updated_at = datetime('now') WHERE id = ?").run(input.conversationId);
+    return db.prepare('SELECT * FROM agent_messages WHERE id = ?').get(id);
+}
+function listAgentMessages(db, conversationId) {
+    return db
+        .prepare('SELECT * FROM agent_messages WHERE conversation_id = ? ORDER BY created_at ASC, rowid ASC')
+        .all(conversationId);
+}

package/server/dist/agent-tier.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENT_PROJECT_ENV = exports.AGENT_PROJECT_HEADER = exports.AGENT_TIER_ENV = exports.AGENT_TIER_HEADER = exports.AGENT_TIER_NAMES = void 0;
+exports.tierNameForLevel = tierNameForLevel;
+exports.levelForTierName = levelForTierName;
+exports.normalizeLevel = normalizeLevel;
+exports.nextLevel = nextLevel;
+exports.levelAllowsTier = levelAllowsTier;
+exports.levelFromHeader = levelFromHeader;
+exports.tierNeedsApproval = tierNeedsApproval;
+exports.AGENT_TIER_NAMES = [
+    'observe',
+    'edit',
+    'operate',
+    'autonomous',
+];
+/** The HTTP header the agent's MCP bridge sets so the tool guard can read the level. */
+exports.AGENT_TIER_HEADER = 'x-specrails-agent-tier';
+/** Env var the AgentChatManager sets on the bridge spawn; the bridge forwards it as the header. */
+exports.AGENT_TIER_ENV = 'SPECRAILS_AGENT_TIER';
+/** Header carrying the pinned project id so tools resolve it per-request. */
+exports.AGENT_PROJECT_HEADER = 'x-specrails-active-project';
+/** Env var the manager sets on the bridge spawn; the bridge forwards it as the project header. */
+exports.AGENT_PROJECT_ENV = 'SPECRAILS_ACTIVE_PROJECT';
+/** Which MCP tiers a given ladder level unlocks (cumulative). */
+const TIERS_BY_LEVEL = {
+    0: new Set(['read']),
+    1: new Set(['read', 'write']),
+    2: new Set(['read', 'write', 'ai-spawn']),
+    3: new Set(['read', 'write', 'ai-spawn', 'destructive']),
+};
+function tierNameForLevel(level) {
+    return exports.AGENT_TIER_NAMES[level];
+}
+function levelForTierName(name) {
+    const idx = exports.AGENT_TIER_NAMES.indexOf(name);
+    return idx === -1 ? null : idx;
+}
+/** Clamp an arbitrary number/string to a valid ladder level (default observe). */
+function normalizeLevel(value) {
+    const n = typeof value === 'string' ? Number(value) : value;
+    if (typeof n === 'number' && Number.isInteger(n) && n >= 0 && n <= 3) {
+        return n;
+    }
+    // Allow the name form too.
+    if (typeof value === 'string') {
+        const byName = levelForTierName(value);
+        if (byName !== null)
+            return byName;
+    }
+    return 0;
+}
+/** Cycle Shift+Tab: 0→1→2→3→0. */
+function nextLevel(level) {
+    return ((level + 1) % 4);
+}
+/** True when the given MCP tier is permitted at the given ladder level. */
+function levelAllowsTier(level, tier) {
+    return TIERS_BY_LEVEL[level].has(tier);
+}
+/**
+ * Parse the agent-tier header value into a level, or null when absent/invalid.
+ * The header carries the tier NAME (observe/edit/operate/autonomous) or the
+ * numeric level; anything else yields null (→ fall back to Settings tiers).
+ */
+function levelFromHeader(headerValue) {
+    if (headerValue == null)
+        return null;
+    const raw = Array.isArray(headerValue) ? headerValue[0] : headerValue;
+    if (typeof raw !== 'string' || raw.trim() === '')
+        return null;
+    const byName = levelForTierName(raw.trim());
+    if (byName !== null)
+        return byName;
+    const n = Number(raw.trim());
+    if (Number.isInteger(n) && n >= 0 && n <= 3)
+        return n;
+    return null;
+}
+/**
+ * Whether a cost/destructive action needs an explicit inline approval (Option C):
+ * reversible writes (read/write) run silently; ai-spawn and destructive prompt.
+ */
+function tierNeedsApproval(tier) {
+    return tier === 'ai-spawn' || tier === 'destructive';
+}

package/server/dist/desktop-db.js

@@ -351,6 +351,33 @@ function applyDesktopMigrations(db) {
           ('seed-min-coverage', 'MIN_COVERAGE', '80');
       `);
         },
+        // 17: app-global agent chat (design D2). The agent chat lives ABOVE projects,
+        // so its conversations are stored in the app registry DB (not any per-project
+        // jobs.sqlite). `pinned_project_id` records the Cursor-style selector target
+        // (NULL = Home / app-global); `tier_level` records the Shift+Tab ladder.
+        () => {
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS agent_conversations (
+          id                TEXT PRIMARY KEY,
+          title             TEXT,
+          provider          TEXT NOT NULL DEFAULT 'claude',
+          model             TEXT,
+          session_id        TEXT,
+          pinned_project_id TEXT,
+          tier_level        INTEGER NOT NULL DEFAULT 0,
+          created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+          updated_at        TEXT NOT NULL DEFAULT (datetime('now'))
+        );
+        CREATE TABLE IF NOT EXISTS agent_messages (
+          id              TEXT PRIMARY KEY,
+          conversation_id TEXT NOT NULL REFERENCES agent_conversations(id) ON DELETE CASCADE,
+          role            TEXT NOT NULL,
+          content         TEXT NOT NULL,
+          created_at      TEXT NOT NULL DEFAULT (datetime('now'))
+        );
+        CREATE INDEX IF NOT EXISTS idx_agent_messages_conv ON agent_messages(conversation_id, created_at);
+      `);
+        },
     ];
     for (let i = 0; i < migrations.length; i++) {
         const version = i + 1;

package/server/dist/index.js

@@ -23,6 +23,9 @@ const terminal_manager_1 = require("./terminal-manager");
 const terminal_shell_integration_1 = require("./terminal-shell-integration");
 const feature_flags_1 = require("./feature-flags");
 const mobile_1 = require("./mobile");
+const mcp_1 = require("./mcp");
+const agent_chat_manager_1 = require("./agent-chat-manager");
+const agent_chat_router_1 = require("./agent-chat-router");
 const browser_playwright_1 = require("./browser-playwright");
 const telemetry_receiver_1 = require("./telemetry-receiver");
 const telemetry_compactor_1 = require("./telemetry-compactor");
@@ -150,6 +153,20 @@ app.use(corsMiddleware);
 // 12mb limit FIRST — once it sets req._body the global parser below no-ops for
 // these paths. (The actual /otlp router still requires loopback.)
 app.use('/otlp', express_1.default.json({ limit: '12mb' }));
+// ─── MCP streamable-HTTP transport (design D1) ───────────────────────────────
+// Mounted BEFORE the global express.json so it claims `/api/mcp` with a larger
+// body limit (req._body makes the global parser no-op for this path), and
+// BEFORE `app.use('/api', requireAuth)` so it uses the SCOPED mcp token via
+// requireMcpAuth rather than inheriting the all-powerful master token. The
+// dispatcher delegates to the McpServerManager constructed during Super-mode
+// bootstrap (lazily referenced — it exists by request time).
+app.use('/api/mcp', express_1.default.json({ limit: '4mb' }), auth_1.requireLoopback, mcp_1.requireMcpAuth, (req, res) => {
+    if (_mcpManager) {
+        void _mcpManager.handleHttp(req, res);
+        return;
+    }
+    res.status(503).json({ jsonrpc: '2.0', error: { code: -32000, message: 'MCP transport not ready' }, id: null });
+});
 app.use(express_1.default.json({ limit: '1mb' }));
 const server = http_1.default.createServer(app);
 const wsServerOptions = {
@@ -219,6 +236,8 @@ let _getProjectCount = () => 0;
 let _registry = null;
 /** The mobile companion gateway (off by default); torn down on shutdown. */
 let _mobileGateway = null;
+let _mcpManager = null;
+let _agentChatManager = null;
 server.on('upgrade', (request, socket, head) => {
     const urlStr = request.url ?? '/';
     const auth = authorizeUpgrade(request);
@@ -507,6 +526,23 @@ function applyPtyWsRateLimiting(ws) {
     if (mobileGateway.isEnabledSetting()) {
         mobileGateway.start().catch((err) => console.error('[mobile-gateway] boot start failed:', err));
     }
+    // ─── Embedded MCP server (the /api/mcp transport mounted above) ─────────────
+    const mcpManager = new mcp_1.McpServerManager({ registry, broadcast, desktopPort: port, version: PKG_VERSION });
+    _mcpManager = mcpManager;
+    // Loopback + master-token control plane for the Settings ▸ MCP panel.
+    app.use('/api/mcp-admin', auth_1.requireLoopback, (0, mcp_1.createMcpAdminRouter)({
+        manager: mcpManager,
+        desktopDb: registry.desktopDb,
+        desktopPort: port,
+        broadcast,
+    }));
+    if (mcpManager.isEnabledSetting()) {
+        mcpManager.start().catch((err) => console.error('[mcp] boot start failed:', err));
+    }
+    // ─── App-global agent chat (drives the app via its own MCP) ────────────────
+    const agentChatManager = new agent_chat_manager_1.AgentChatManager(broadcast, registry.desktopDb, port);
+    _agentChatManager = agentChatManager;
+    app.use('/api/agent', (0, agent_chat_router_1.createAgentChatRouter)({ manager: agentChatManager, desktopDb: registry.desktopDb }));
     // App-level routes. CRITICAL mount order: the desktop router is mounted at
     // '/api' BEFORE the project router below so its exact routes (e.g.
     // GET /api/projects, DELETE /api/projects/:id) are handled here, while
@@ -611,6 +647,8 @@ async function shutdown() {
     catch { /* ignore */ }
     try {
         await _mobileGateway?.stop();
+        await _mcpManager?.stop();
+        await _agentChatManager?.shutdown();
     }
     catch { /* ignore */ }
     try {

package/server/dist/mcp/guide.js

@@ -0,0 +1,82 @@
+"use strict";
+// The platform guide returned by the `specrails_guide` meta tool and the
+// `specrails://guide` resource. This is what lets an external LLM "understand
+// the platform" without prior knowledge. It is intentionally English (the LLM
+// consumes it); human-facing onboarding docs are localized separately.
+//
+// Keep this BYTE-STABLE where possible (no timestamps / live data) so MCP
+// clients that cache resources stay valid.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SPECRAILS_GUIDE = void 0;
+exports.SPECRAILS_GUIDE = `# Specrails Desktop — Agent Guide
+
+You are operating Specrails Desktop through its MCP server. Specrails is a local
+dashboard + pipeline runner that manages multiple software projects and drives AI
+coding agents (Claude Code, Codex, Gemini) to implement specs.
+
+## Core concepts
+
+- **Project**: a registered repository. Almost every tool is project-scoped and
+  takes a \`projectId\`. Use \`specrails_select_project\` to set an active project so
+  you can omit \`projectId\` on later calls; pass an explicit \`projectId\` to override.
+- **Spec / ticket**: a unit of work in a project's backlog. Statuses: \`draft\`,
+  \`todo\`, \`in_progress\`, \`done\`, \`cancelled\`. Priorities: \`critical\`, \`high\`,
+  \`medium\`, \`low\`. INVARIANT: priority may be null ONLY when status is \`draft\`.
+- **Rail**: a launch slot that runs the AI pipeline over one or more assigned
+  tickets. Modes: \`implement\`, \`batch-implement\`, \`ultracode\`, \`loop\`. Launching a
+  rail spawns AI CLI processes that write code, run tests and commit — it costs
+  money and runs for minutes.
+- **Job**: one spawned pipeline run. Jobs stream logs/events over the WebSocket
+  and settle (completed/failed/canceled). Cost is authoritative for Claude and
+  estimated for Codex/Gemini.
+- **Profile**: a per-project agent configuration (which agents, which models,
+  routing). Profiles are CLAUDE-ONLY; they are ignored for Codex/Gemini rails.
+- **Provider / engine**: claude, codex, or gemini. A project installs one or
+  more. A requested provider must be one of the project's installed providers.
+- **Loop**: a saved, app-driven workflow graph runnable on a rail in \`loop\` mode.
+- **Plugin**: an MCP-based integration installed per project (e.g. serena).
+
+## Async results (IMPORTANT)
+
+Cost-incurring / streaming actions (launch a rail, generate a spec, send a chat
+turn, refine an agent, SMASH) return immediately with a reference (jobId /
+requestId) and emit their REAL result over the WebSocket bus. To get the actual
+outcome, call \`specrails_watch\` with the returned reference; it waits for the
+operation to settle and returns the final result. Do not assume success from the
+acceptance alone.
+
+## Permission tiers
+
+The server enforces four opt-in tiers, configured by the user in Settings ▸ MCP:
+- **Read** (always on): queries + resources.
+- **Write**: create/edit specs, settings, rail config.
+- **AI-spawn**: actions that spawn an AI CLI and cost money.
+- **Destructive**: delete data, kill processes, mutate external systems.
+
+If a tool is refused, the error names the tier the user must enable. Relay that
+to the user rather than retrying blindly.
+
+## Claude-only features
+
+Agent profiles, Contract Refine, and SMASH are Claude-only. They are unavailable
+(and rejected) on projects whose selected provider is Codex or Gemini.
+
+## Typical workflow
+
+1. \`specrails_projects(list)\` → pick a project; \`specrails_select_project\`.
+2. \`specrails_specs(list)\` → inspect the backlog. To ADD a spec from a user
+   request, use \`specrails_specs(action:'create')\` — it routes through **Quick
+   Add Spec**: the specrails agent generates a structured spec with AI from the
+   request, exactly like the app's "Add Spec" button (so MCP-created specs are
+   indistinguishable from UI-created ones). It is async — watch the returned ref
+   with \`specrails_watch\`. Use \`from_prompt\` only to store a finished spec verbatim.
+3. \`specrails_rails(set_tickets)\` then \`specrails_rails(launch)\` → run the pipeline;
+   \`specrails_watch\` the returned jobId.
+4. \`specrails_analytics(spending)\` → review cost.
+
+## Resources
+
+Read-only state is also exposed as MCP resources: \`specrails://projects\`,
+\`specrails://projects/{id}/tickets\`, \`specrails://projects/{id}/rails\`,
+\`specrails://projects/{id}/analytics\`, and \`specrails://guide\` (this document).
+`;

package/server/dist/mcp/index.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildToolSpecs = exports.TIER_SETTING_KEY = exports.MCP_ENABLED_KEY = exports.MCP_TIERS = exports.isTierEnabled = exports.isMcpEnabled = exports._resetMcpTokenForTest = exports.loadOrGenerateMcpToken = exports.regenerateMcpToken = exports.getMcpToken = exports.requireMcpAuth = exports.createMcpAdminRouter = exports.McpServerManager = void 0;
+var mcp_server_1 = require("./mcp-server");
+Object.defineProperty(exports, "McpServerManager", { enumerable: true, get: function () { return mcp_server_1.McpServerManager; } });
+var mcp_admin_router_1 = require("./mcp-admin-router");
+Object.defineProperty(exports, "createMcpAdminRouter", { enumerable: true, get: function () { return mcp_admin_router_1.createMcpAdminRouter; } });
+var mcp_token_1 = require("./mcp-token");
+Object.defineProperty(exports, "requireMcpAuth", { enumerable: true, get: function () { return mcp_token_1.requireMcpAuth; } });
+Object.defineProperty(exports, "getMcpToken", { enumerable: true, get: function () { return mcp_token_1.getMcpToken; } });
+Object.defineProperty(exports, "regenerateMcpToken", { enumerable: true, get: function () { return mcp_token_1.regenerateMcpToken; } });
+Object.defineProperty(exports, "loadOrGenerateMcpToken", { enumerable: true, get: function () { return mcp_token_1.loadOrGenerateMcpToken; } });
+Object.defineProperty(exports, "_resetMcpTokenForTest", { enumerable: true, get: function () { return mcp_token_1._resetMcpTokenForTest; } });
+var mcp_tiers_1 = require("./mcp-tiers");
+Object.defineProperty(exports, "isMcpEnabled", { enumerable: true, get: function () { return mcp_tiers_1.isMcpEnabled; } });
+Object.defineProperty(exports, "isTierEnabled", { enumerable: true, get: function () { return mcp_tiers_1.isTierEnabled; } });
+Object.defineProperty(exports, "MCP_TIERS", { enumerable: true, get: function () { return mcp_tiers_1.MCP_TIERS; } });
+Object.defineProperty(exports, "MCP_ENABLED_KEY", { enumerable: true, get: function () { return mcp_tiers_1.MCP_ENABLED_KEY; } });
+Object.defineProperty(exports, "TIER_SETTING_KEY", { enumerable: true, get: function () { return mcp_tiers_1.TIER_SETTING_KEY; } });
+var catalog_1 = require("./tools/catalog");
+Object.defineProperty(exports, "buildToolSpecs", { enumerable: true, get: function () { return catalog_1.buildToolSpecs; } });

package/server/dist/mcp/mcp-admin-router.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMcpAdminRouter = createMcpAdminRouter;
+const express_1 = require("express");
+const mcp_token_1 = require("./mcp-token");
+const desktop_db_1 = require("../desktop-db");
+const mcp_tiers_1 = require("./mcp-tiers");
+function tierState(db) {
+    return {
+        write: (0, mcp_tiers_1.isTierEnabled)(db, 'write'),
+        aiSpawn: (0, mcp_tiers_1.isTierEnabled)(db, 'ai-spawn'),
+        destructive: (0, mcp_tiers_1.isTierEnabled)(db, 'destructive'),
+    };
+}
+function redact(token) {
+    return token.length > 4 ? `…${token.slice(-4)}` : '…';
+}
+function createMcpAdminRouter(deps) {
+    const router = (0, express_1.Router)();
+    const { manager, desktopDb, desktopPort } = deps;
+    router.get('/status', (_req, res) => {
+        res.json({ ...manager.status(), tiers: tierState(desktopDb), tokenHint: redact((0, mcp_token_1.getMcpToken)()) });
+    });
+    router.post('/enable', async (_req, res) => {
+        try {
+            res.json(await manager.setEnabled(true));
+        }
+        catch (err) {
+            res.status(409).json({ error: err instanceof Error ? err.message : 'Failed to enable MCP' });
+        }
+    });
+    router.post('/disable', async (_req, res) => {
+        res.json(await manager.setEnabled(false));
+    });
+    // Update the opt-in permission tiers (read is always on, not settable here).
+    router.patch('/tiers', (req, res) => {
+        const body = (req.body ?? {});
+        const fields = [
+            ['write', 'write'],
+            ['aiSpawn', 'ai-spawn'],
+            ['destructive', 'destructive'],
+        ];
+        for (const [bodyKey, tier] of fields) {
+            if (bodyKey in body) {
+                if (typeof body[bodyKey] !== 'boolean') {
+                    res.status(400).json({ error: `${bodyKey} must be a boolean` });
+                    return;
+                }
+                (0, desktop_db_1.setDesktopSetting)(desktopDb, mcp_tiers_1.TIER_SETTING_KEY[tier], body[bodyKey] ? 'true' : 'false');
+            }
+        }
+        res.json({ ok: true, tiers: tierState(desktopDb) });
+    });
+    // The full token — deliberately a separate loopback-only action so it never
+    // leaks through a general settings payload. Used by the panel's copy button.
+    router.get('/token', (_req, res) => {
+        res.json({ token: (0, mcp_token_1.getMcpToken)() });
+    });
+    router.post('/regenerate-token', (_req, res) => {
+        res.json({ token: (0, mcp_token_1.regenerateMcpToken)() });
+    });
+    // Connection info for the panel to render a ready-to-paste client config.
+    router.get('/config', (_req, res) => {
+        res.json({
+            httpUrl: `http://127.0.0.1:${desktopPort}/api/mcp`,
+            bridgeCommand: 'specrails-mcp',
+            hasToken: true,
+        });
+    });
+    return router;
+}

package/server/dist/mcp/mcp-server.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpServerManager = void 0;
+const crypto_1 = require("crypto");
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const mobile_event_bus_1 = require("../mobile/mobile-event-bus");
+const mcp_tiers_1 = require("./mcp-tiers");
+const desktop_db_1 = require("../desktop-db");
+const catalog_1 = require("./tools/catalog");
+const types_1 = require("./tools/types");
+const resources_1 = require("./resources");
+function jsonRpcError(message, code = -32000) {
+    return { jsonrpc: '2.0', error: { code, message }, id: null };
+}
+/**
+ * Embedded MCP server manager. Mirrors the MobileGateway lifecycle shape
+ * (isEnabledSetting / setEnabled / start / stop / status) but mounts on the
+ * EXISTING Express app rather than binding a second port. Uses the SDK's
+ * stateful streamable-HTTP transport (a transport per MCP session).
+ */
+class McpServerManager {
+    _ctx;
+    _version;
+    _transports = {};
+    _toolCount;
+    constructor(deps) {
+        this._ctx = {
+            registry: deps.registry,
+            desktopDb: deps.registry.desktopDb,
+            broadcast: deps.broadcast,
+            eventBus: deps.eventBus ?? (0, mobile_event_bus_1.getMobileEventBus)(),
+            desktopPort: deps.desktopPort,
+        };
+        this._version = deps.version ?? '1.0.0';
+        this._toolCount = (0, catalog_1.buildToolSpecs)().length;
+    }
+    isEnabledSetting() {
+        return (0, mcp_tiers_1.isMcpEnabled)(this._ctx.desktopDb);
+    }
+    /** Persist the enable flag and tear down sessions when disabling. */
+    async setEnabled(enabled) {
+        (0, desktop_db_1.setDesktopSetting)(this._ctx.desktopDb, mcp_tiers_1.MCP_ENABLED_KEY, enabled ? 'true' : 'false');
+        if (!enabled)
+            await this.stop();
+        this._ctx.broadcast({ type: 'mcp.state', enabled, running: enabled });
+        return this.status();
+    }
+    // Mounting happens on the shared app, so start() has no port to bind; it
+    // exists for lifecycle symmetry with MobileGateway. The transport only serves
+    // when isEnabledSetting() is true (checked in handleHttp).
+    async start() {
+        /* no-op: served on the shared app, gated by isEnabledSetting() */
+    }
+    /** Close all open MCP sessions. */
+    async stop() {
+        for (const sid of Object.keys(this._transports)) {
+            try {
+                await this._transports[sid].close();
+            }
+            catch {
+                /* ignore */
+            }
+            delete this._transports[sid];
+        }
+    }
+    status() {
+        return {
+            enabled: this.isEnabledSetting(),
+            running: this.isEnabledSetting(),
+            activeSessions: Object.keys(this._transports).length,
+            toolCount: this._toolCount,
+        };
+    }
+    /** Build a fresh McpServer with the full tool + resource catalog registered. */
+    buildServer() {
+        const server = new mcp_js_1.McpServer({ name: 'specrails-desktop', version: this._version }, { capabilities: { logging: {}, tools: {}, resources: {} } });
+        for (const spec of (0, catalog_1.buildToolSpecs)()) {
+            (0, types_1.registerTieredTool)(server, this._ctx, spec);
+        }
+        (0, resources_1.registerResources)(server, this._ctx);
+        return server;
+    }
+    /**
+     * Express handler for the `/api/mcp` streamable-HTTP endpoint. Stateful:
+     * an initialize POST mints a session + transport; subsequent POST/GET/DELETE
+     * carry the `mcp-session-id` header.
+     */
+    async handleHttp(req, res) {
+        if (!this.isEnabledSetting()) {
+            res.status(404).json(jsonRpcError('MCP is disabled. Enable it in the Specrails app under Settings ▸ MCP.', -32004));
+            return;
+        }
+        const sessionId = req.headers['mcp-session-id'];
+        try {
+            if (req.method === 'POST') {
+                let transport = sessionId ? this._transports[sessionId] : undefined;
+                if (!transport) {
+                    if (sessionId) {
+                        res.status(400).json(jsonRpcError('Unknown or expired MCP session. Reinitialize.'));
+                        return;
+                    }
+                    if (!(0, types_js_1.isInitializeRequest)(req.body)) {
+                        res.status(400).json(jsonRpcError('Missing mcp-session-id and body is not an initialize request.'));
+                        return;
+                    }
+                    transport = new streamableHttp_js_1.StreamableHTTPServerTransport({
+                        sessionIdGenerator: () => (0, crypto_1.randomUUID)(),
+                        onsessioninitialized: (sid) => {
+                            this._transports[sid] = transport;
+                        },
+                    });
+                    transport.onclose = () => {
+                        const sid = transport?.sessionId;
+                        if (sid && this._transports[sid])
+                            delete this._transports[sid];
+                    };
+                    const server = this.buildServer();
+                    await server.connect(transport);
+                }
+                await transport.handleRequest(req, res, req.body);
+                return;
+            }
+            if (req.method === 'GET' || req.method === 'DELETE') {
+                const transport = sessionId ? this._transports[sessionId] : undefined;
+                if (!transport) {
+                    res.status(400).json(jsonRpcError('Missing or unknown mcp-session-id.'));
+                    return;
+                }
+                await transport.handleRequest(req, res);
+                return;
+            }
+            res.status(405).json(jsonRpcError('Method not allowed.'));
+        }
+        catch (err) {
+            if (!res.headersSent) {
+                res.status(500).json(jsonRpcError(err instanceof Error ? err.message : 'Internal MCP error', -32603));
+            }
+        }
+    }
+}
+exports.McpServerManager = McpServerManager;

package/server/dist/mcp/mcp-tiers.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCP_ENABLED_KEY = exports.TIER_SETTING_KEY = exports.MCP_TIERS = void 0;
+exports.isMcpEnabled = isMcpEnabled;
+exports.isTierEnabled = isTierEnabled;
+exports.tierLabel = tierLabel;
+exports.tierRefusalMessage = tierRefusalMessage;
+const desktop_db_1 = require("../desktop-db");
+exports.MCP_TIERS = ['read', 'write', 'ai-spawn', 'destructive'];
+/** desktop_settings keys for the opt-in tiers (read is implicit). */
+exports.TIER_SETTING_KEY = {
+    write: 'mcp_tier_write',
+    'ai-spawn': 'mcp_tier_ai_spawn',
+    destructive: 'mcp_tier_destructive',
+};
+exports.MCP_ENABLED_KEY = 'mcp_enabled';
+/** True when MCP itself is enabled (default false). */
+function isMcpEnabled(db) {
+    return (0, desktop_db_1.getDesktopSetting)(db, exports.MCP_ENABLED_KEY) === 'true';
+}
+/**
+ * True when a tool of the given tier may run right now. Read is always allowed
+ * (its availability is governed by MCP being enabled, checked at the transport
+ * gate). The other tiers require their opt-in flag to be 'true'.
+ */
+function isTierEnabled(db, tier) {
+    if (tier === 'read')
+        return true;
+    return (0, desktop_db_1.getDesktopSetting)(db, exports.TIER_SETTING_KEY[tier]) === 'true';
+}
+/** Human-readable label for a tier, used in refusal messages. */
+function tierLabel(tier) {
+    switch (tier) {
+        case 'read':
+            return 'Read';
+        case 'write':
+            return 'Write';
+        case 'ai-spawn':
+            return 'AI-spawn (cost-incurring)';
+        case 'destructive':
+            return 'Destructive';
+    }
+}
+/** The message returned when a tool is refused because its tier is disabled. */
+function tierRefusalMessage(tier) {
+    return (`This action requires the "${tierLabel(tier)}" permission tier, which is currently disabled. ` +
+        `Enable it in the Specrails app under Settings ▸ MCP, then retry.`);
+}