mikser-io 7.12.1 → 8.0.0

package/README.md

@@ -84,7 +84,7 @@ Add `--mcp` to your mikser command and any MCP-speaking client — Claude Deskto
 - read every entity in the catalog
 - write new content files (markdown, layouts, configuration) — writes land on disk and the next cycle picks them up
 - render any layout for preview without touching the output folder
-- **surface interactive UI inline in the conversation** — you author the UI as a normal mikser layout with YAML frontmatter (`mcpUi: { mode, actions }`). The agent reads `mikser://mcp-ui/modes` to discover what UIs your project supports, calls `mikser_preview_ui` to render one against an entity, and the host displays the result as a sandboxed iframe in the chat. Buttons in the UI `postMessage` their click back as the tool result — no separate UI framework, no glue code; layouts are still just layouts
+- **surface interactive UI inline in the conversation** — you author the UI as a normal mikser layout with YAML frontmatter (`mcpUi: { mode, actions }`). The agent reads `mikser://mcp-ui/modes` to discover what UIs your project supports, calls `mikser_preview_ui` to render one against an entity, and the host displays the result as a sandboxed iframe in the chat. Buttons in the UI deliver their click back as a separate MCP tool turn — the iframe sends a JSON-RPC `tools/call` to the host over `postMessage` per the [MCP Apps spec](https://github.com/modelcontextprotocol/ext-apps), which the host bridges into a real `mikser_ui_action` invocation. The agent sees a structured `{action, entityId, payload}` result; if you declared `mcpUi.handler.url`, mikser forwards the action to your webhook first and uses its response. No separate UI framework, no glue code; layouts are still just layouts
 - watch every build log as it streams past
 - introspect engine state — current lifecycle phase, effective config, recent log buffer
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "mikser-io",
-	"version": "7.12.1",
+	"version": "8.0.0",
 	"description": "<p align=\"center\">   <img src=\"mikser-lockup-stacked.svg\" alt=\"mikser\" width=\"198\" /> </p>",
 	"main": "index.js",
 	"scripts": {

package/src/mcp.js

@@ -75,9 +75,11 @@ export function createMcpSubstrate() {
 
     function bind(server, filters = {}) {
         const { allowedTools, allowedResources, allowedPrompts } = filters
+        const bound = { tools: 0, resources: 0, prompts: 0 }
         for (const args of registrations.tools) {
             if (!matchesAny(args[0], allowedTools)) continue
             server.registerTool(...args)
+            bound.tools++
         }
         for (const args of registrations.resources) {
             // Resource registrations are (name, uri, config, handler).
@@ -87,11 +89,14 @@ export function createMcpSubstrate() {
             const uri = typeof args[1] === 'string' ? args[1] : args[0]
             if (!matchesAny(uri, allowedResources)) continue
             server.registerResource(...args)
+            bound.resources++
         }
         for (const args of registrations.prompts) {
             if (!matchesAny(args[0], allowedPrompts)) continue
             server.registerPrompt(...args)
+            bound.prompts++
         }
+        return bound
     }
 
     const substrate = {
@@ -101,22 +106,58 @@ export function createMcpSubstrate() {
         // shape, it just records and replays.
         registerTool(...args) {
             registrations.tools.push(args)
+            const name = args[0]
+            let replayed = 0
+            const replayErrors = []
             for (const s of activeServers) {
-                try { s.registerTool(...args) } catch { /* dup, etc. */ }
+                try { s.registerTool(...args); replayed++ }
+                catch (err) { replayErrors.push(err.message) }
+            }
+            const log = runtime.engine?.logger
+            if (log) {
+                log.debug('MCP substrate: registered tool %s (total=%d, live-replayed=%d/%d)',
+                    name, registrations.tools.length, replayed, activeServers.size)
+                for (const msg of replayErrors) {
+                    log.debug('MCP substrate: live-replay of tool %s failed on a session server: %s', name, msg)
+                }
             }
             return substrate
         },
         registerResource(...args) {
             registrations.resources.push(args)
+            const uri = typeof args[1] === 'string' ? args[1] : args[0]
+            let replayed = 0
+            const replayErrors = []
             for (const s of activeServers) {
-                try { s.registerResource(...args) } catch { /* dup */ }
+                try { s.registerResource(...args); replayed++ }
+                catch (err) { replayErrors.push(err.message) }
+            }
+            const log = runtime.engine?.logger
+            if (log) {
+                log.debug('MCP substrate: registered resource %s (total=%d, live-replayed=%d/%d)',
+                    uri, registrations.resources.length, replayed, activeServers.size)
+                for (const msg of replayErrors) {
+                    log.debug('MCP substrate: live-replay of resource %s failed on a session server: %s', uri, msg)
+                }
             }
             return substrate
         },
         registerPrompt(...args) {
             registrations.prompts.push(args)
+            const name = args[0]
+            let replayed = 0
+            const replayErrors = []
             for (const s of activeServers) {
-                try { s.registerPrompt(...args) } catch { /* dup */ }
+                try { s.registerPrompt(...args); replayed++ }
+                catch (err) { replayErrors.push(err.message) }
+            }
+            const log = runtime.engine?.logger
+            if (log) {
+                log.debug('MCP substrate: registered prompt %s (total=%d, live-replayed=%d/%d)',
+                    name, registrations.prompts.length, replayed, activeServers.size)
+                for (const msg of replayErrors) {
+                    log.debug('MCP substrate: live-replay of prompt %s failed on a session server: %s', name, msg)
+                }
             }
             return substrate
         },
@@ -136,17 +177,31 @@ export function createMcpSubstrate() {
         //   allowedResources: ['mikser://lifecycle', 'mikser://logs/*']
         // Omit a filter (or pass '*') to allow everything in that
         // category — that's the backward-compat default.
-        _createServer({ allowedTools, allowedResources, allowedPrompts } = {}) {
+        createServer({ allowedTools, allowedResources, allowedPrompts } = {}) {
             const server = new McpServer(
                 { name: 'mikser-io', version: packageInfo.version },
                 { capabilities: { tools: {}, resources: {}, logging: {} } },
             )
-            bind(server, { allowedTools, allowedResources, allowedPrompts })
+            const bound = bind(server, { allowedTools, allowedResources, allowedPrompts })
+            runtime.engine?.logger?.debug(
+                'MCP session server created (tools=%d/%d, resources=%d/%d, prompts=%d/%d)',
+                bound.tools, registrations.tools.length,
+                bound.resources, registrations.resources.length,
+                bound.prompts, registrations.prompts.length,
+            )
             return server
         },
-        _attach(server) { activeServers.add(server) },
-        _detach(server) { activeServers.delete(server) },
-        _activeServerCount() { return activeServers.size },
+        attach(server) {
+            activeServers.add(server)
+            runtime.engine?.logger?.debug(
+                'MCP session attached — active clients: %d', activeServers.size)
+        },
+        detach(server) {
+            activeServers.delete(server)
+            runtime.engine?.logger?.debug(
+                'MCP session detached — active clients: %d', activeServers.size)
+        },
+        activeServerCount() { return activeServers.size },
 
         // Send a logging-message notification to every connected
         // client. The SDK's per-session level filtering applies.
@@ -309,7 +364,7 @@ export function createMcpSubstrate() {
                     phase: runtime.phase ?? null,
                     workingFolder: runtime.options.workingFolder,
                     outputFolder: runtime.options.outputFolder,
-                    activeClients: substrate._activeServerCount(),
+                    activeClients: substrate.activeServerCount(),
                     server: serverInfo(),
                 }, null, 2),
             }],
@@ -373,6 +428,10 @@ export async function mountMcpOnExpress(app, substrate, defaultPath = '/mcp') {
     const endpoints = runtime.config.mcp?.endpoints
     const base = runtime.config.mcp?.base ?? defaultPath
 
+    runtime.engine?.logger?.debug(
+        'MCP mounting on Express (base=%s, endpoints=%d)',
+        base, endpoints ? Object.keys(endpoints).length : 1)
+
     if (endpoints && Object.keys(endpoints).length > 0) {
         for (const [name, ep] of Object.entries(endpoints)) {
             mountEndpoint(app, substrate, `${base}/${name}`, ep, name)
@@ -404,6 +463,8 @@ function mountEndpoint(app, substrate, path, ep, endpointName) {
         const presented = req.headers.authorization
         if (expectedAuth) {
             if (presented && presented !== expectedAuth) {
+                runtime.engine?.logger?.debug(
+                    'MCP auth denied at %s: invalid token (ip=%s)', path, req.ip)
                 res.status(401).json({
                     jsonrpc: '2.0',
                     error: { code: -32001, message: 'Invalid MCP token' },
@@ -416,6 +477,8 @@ function mountEndpoint(app, substrate, path, ep, endpointName) {
         }
         if (!presented || presented !== expectedAuth) {
             if (!ep.allowRemote && !isLoopback(req.ip)) {
+                runtime.engine?.logger?.debug(
+                    'MCP auth denied at %s: non-loopback without token (ip=%s)', path, req.ip)
                 res.status(403).json({
                     jsonrpc: '2.0',
                     error: {
@@ -436,7 +499,9 @@ function mountEndpoint(app, substrate, path, ep, endpointName) {
         }
 
         // New session — server filtered for this endpoint's surface.
-        const server = substrate._createServer({
+        runtime.engine?.logger?.debug(
+            'MCP new session at %s (ip=%s, method=%s)', path, req.ip, req.method)
+        const server = substrate.createServer({
             allowedTools:     ep.tools,
             allowedResources: ep.resources,
             allowedPrompts:   ep.prompts,
@@ -445,12 +510,12 @@ function mountEndpoint(app, substrate, path, ep, endpointName) {
             sessionIdGenerator: () => randomUUID(),
             onsessioninitialized: (id) => {
                 transports.set(id, transport)
-                substrate._attach(server)
+                substrate.attach(server)
             },
         })
         transport.onclose = () => {
             if (transport.sessionId) transports.delete(transport.sessionId)
-            substrate._detach(server)
+            substrate.detach(server)
         }
         await server.connect(transport)
         return transport.handleRequest(req, res, body)
@@ -519,6 +584,12 @@ export function wireLoggerToMcp(logger, substrate) {
             } catch { /* swallow — keep stdout pipeline working */ }
         }
     }
+    // No wire-up confirmation here — the wrapper has a load-bearing
+    // 1-broadcast-per-log-call invariant and a "skip missing methods"
+    // invariant. Operators still see the substrate's debug coverage
+    // (registrations, session lifecycle, auth deny) once the engine
+    // logger flows through. The "MCP mounted: …" info line at boot
+    // is the user-visible "ready" signal.
     return logger
 }
 
@@ -554,16 +625,3 @@ function format(template, args) {
 function pinoLevelNumber(name) {
     return { trace: 10, debug: 20, info: 30, warn: 40, error: 50, fatal: 60 }[name] ?? 30
 }
-
-// (whenMcpActive was removed in v7.4.0 — plugins now use the same
-// inline pattern as Express route registration: gate on the runtime
-// option inside whichever lifecycle hook makes sense.
-//
-//   onLoaded(async () => {
-//       if (runtime.options.mcp) {
-//           runtime.options.mcp.simpleTool(...)
-//       }
-//   })
-//
-// Reveals timing, matches the Express pattern, doesn't lock the
-// registration into onLoaded.)

package/src/plugins/preview.js

@@ -24,11 +24,85 @@
 // wrapper over this surface.
 
 import path from 'node:path'
-import { randomUUID } from 'node:crypto'
+import { randomUUID, createHmac } from 'node:crypto'
 import { z } from 'zod'
 import { useRenderer } from '../api.js'
 import { mimeForEntity, matchEntity } from '../utils.js'
 
+// Forward an MCP-UI action to an external handler URL. Returns the
+// handler's JSON response, which becomes the tool result. Throws on
+// network error, non-2xx status, timeout, or invalid response shape —
+// callers fall back to pure-relay on throw.
+//
+// HMAC signing: when handler.secret is set, we sign the request body
+// with sha256(secret) and pass it in X-Mikser-Signature. Receivers
+// MUST verify before processing. When secret is unset, no signature
+// is sent (acceptable for dev; not recommended in production — see
+// ADR-0008).
+//
+// Extracted as a standalone function so it can be unit-tested with a
+// mock URL and so mikser_ui_action's main path stays readable.
+export async function forwardToHandler(handler, body) {
+    const { url, secret, timeout = 5000 } = handler
+    if (!url) throw new Error('forwardToHandler: handler.url is required')
+
+    const json = JSON.stringify({
+        ...body,
+        // Timestamp is set inside the forward, not by the caller, so
+        // a stale callback that came in via a slow network still has
+        // a fresh timestamp on the outgoing forward. Receivers that
+        // care can put their own.
+        timestamp: new Date().toISOString(),
+    })
+
+    const headers = {
+        'content-type':         'application/json',
+        'x-mikser-layout-id':   body.layoutId   ?? '',
+        'x-mikser-mode':        body.mode       ?? '',
+        'x-mikser-request-id':  randomUUID(),
+    }
+    if (secret) {
+        const sig = createHmac('sha256', secret).update(json).digest('hex')
+        headers['x-mikser-signature'] = `sha256=${sig}`
+    }
+
+    const ac = new AbortController()
+    const timer = setTimeout(() => ac.abort(), timeout)
+
+    let res
+    try {
+        res = await fetch(url, {
+            method:  'POST',
+            headers,
+            body:    json,
+            signal:  ac.signal,
+        })
+    } catch (err) {
+        clearTimeout(timer)
+        if (err.name === 'AbortError') {
+            throw new Error(`Handler timeout (${timeout}ms) — ${url}`)
+        }
+        throw new Error(`Handler unreachable: ${err.message} — ${url}`)
+    }
+    clearTimeout(timer)
+
+    if (!res.ok) {
+        const text = await res.text().catch(() => '')
+        throw new Error(`Handler ${res.status} ${res.statusText} — ${text.slice(0, 200)}`)
+    }
+
+    const ct = res.headers.get('content-type') ?? ''
+    if (ct.includes('application/json')) {
+        return await res.json()
+    }
+    // Non-JSON response — wrap as a structured result so the agent
+    // sees something meaningful. The handler is technically off-spec
+    // here (ADR-0008 says return JSON), but we don't punish callers
+    // for a casual `res.send('ok')` from the handler side.
+    const text = await res.text()
+    return { ok: true, handlerResponse: text }
+}
+
 export default ({
     runtime,
     onLoaded,
@@ -361,9 +435,12 @@ export default ({
                             // surface it as text/preformatted.
                             { type: 'text', text: html, mimeType: 'text/html' },
                         ],
-                        // Side-channel metadata so hosts that wire up
-                        // postMessage back-channels know which actions
-                        // the UI emits and which sandbox flags to apply.
+                        // Side-channel metadata so hosts know what to
+                        // do with the rendered UI. Per the MCP Apps
+                        // spec (2026-01-26), the iframe speaks JSON-RPC
+                        // back to the host via postMessage; clicks
+                        // resolve as tools/call against `actionTool`
+                        // (registered with visibility=['app'] below).
                         _meta: {
                             mcpUi: {
                                 layoutId:    matched.id,
@@ -371,6 +448,14 @@ export default ({
                                 description: mcpUiMeta.description ?? null,
                                 actions:     mcpUiMeta.actions     ?? [],
                                 sandbox:     mcpUiMeta.sandbox     ?? ['allow-scripts'],
+                                // The app-callable tool the iframe
+                                // invokes for each user click. Hosts
+                                // that bridge iframe tools/call route
+                                // this through the existing MCP
+                                // transport — the click becomes a
+                                // separate tool turn in the agent's
+                                // conversation.
+                                actionTool:  'mikser_ui_action',
                             },
                         },
                     }
@@ -381,8 +466,112 @@ export default ({
             },
         )
 
+        // mikser_ui_action — app-callable tool that delivers a user
+        // click from inside an mcpUi iframe back to the agent (or to
+        // an external webhook handler).
+        //
+        // Visibility model (MCP Apps spec 2026-01-26):
+        //   _meta.ui.visibility = ['app']
+        //
+        // means this tool is invisible to the agent — it's never
+        // listed in the model's tool surface — but iframes opened by
+        // mikser_preview_ui can invoke it over the host's AppBridge
+        // (tools/call over postMessage). The host bridges the call
+        // into a real MCP tools/call, and the agent sees the result
+        // as a separate tool turn in the conversation.
+        //
+        // Auth boundary: the action MUST appear in the layout's
+        // declared mcpUi.actions list. Unknown actions return an
+        // error result. There is no callId / random URL / signature
+        // on this channel — the iframe's only path to mikser is
+        // through the host's authenticated MCP transport, which is
+        // already trusted.
+        //
+        // Resolution: pure relay (return { entityId, action, payload }
+        // as the tool result) unless the layout declared
+        // mcpUi.handler.url, in which case mikser POSTs the action
+        // to that URL (HMAC-signed if handler.secret is set) and
+        // returns the handler's response. See forwardToHandler above.
+        mcp.registerTool(
+            'mikser_ui_action',
+            {
+                description: 'Deliver a user action emitted from an mcpUi iframe. App-callable only — invisible to the agent, invoked exclusively by iframes opened via mikser_preview_ui. Validates the action against the layout\'s declared mcpUi.actions list, then either returns { entityId, action, payload } as a pure relay or forwards to the layout\'s handler.url webhook if one is declared.',
+                inputSchema: {
+                    entityId: z.string().describe('Entity the action targets (the same id the iframe was rendered for).'),
+                    layoutId: z.string().describe('Layout that rendered the iframe — used to look up the allowed-actions list and optional handler config.'),
+                    action:   z.string().describe('Action name. Must appear in the layout\'s mcpUi.actions list.'),
+                    payload:  z.record(z.any()).optional().describe('Structured payload — form fields, selected status, etc. Schema is layout-defined; mikser passes it through.'),
+                },
+                _meta: {
+                    ui: {
+                        // App-callable only — invisible to the model
+                        // per MCP Apps spec. Hosts MUST NOT include
+                        // it in the agent's tools/list response and
+                        // MUST allow iframes opened via mikser_preview_ui
+                        // to invoke it.
+                        visibility: ['app'],
+                    },
+                },
+            },
+            async ({ entityId, layoutId, action, payload = {} }) => {
+                const logger = useLogger()
+                const fail = (msg) => ({
+                    isError: true,
+                    content: [{ type: 'text', text: msg }],
+                })
+                const ok = (data) => ({
+                    content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+                })
+
+                try {
+                    const layout = await findEntity({ id: layoutId })
+                    if (!layout || layout.collection !== 'layouts') {
+                        return fail(`Layout not found or not a layout: ${layoutId}`)
+                    }
+                    const mcpUiMeta = layout.meta?.mcpUi
+                    if (!mcpUiMeta) {
+                        return fail(`Layout ${layoutId} does not declare mcpUi frontmatter — not eligible as an action source.`)
+                    }
+                    const allowed = mcpUiMeta.actions ?? []
+                    if (!allowed.includes(action)) {
+                        return fail(`Action "${action}" not in allowed list for ${layoutId}. Declared: [${allowed.join(', ')}]`)
+                    }
+
+                    const result = { entityId, action, payload }
+
+                    if (mcpUiMeta.handler?.url) {
+                        try {
+                            const handlerResult = await forwardToHandler(mcpUiMeta.handler, {
+                                ...result,
+                                layoutId,
+                                mode: mcpUiMeta.mode ?? 'preview',
+                            })
+                            logger.debug('MCP mikser_ui_action forwarded %s/%s → %s OK',
+                                entityId, action, mcpUiMeta.handler.url)
+                            return ok(handlerResult)
+                        } catch (err) {
+                            // Fail-safe: never lose the user's click.
+                            // Surface handler failure to the agent as
+                            // structured metadata alongside the relay
+                            // payload so the agent can decide whether
+                            // to retry or proceed without backend ack.
+                            logger.warn('MCP mikser_ui_action handler failed (%s) — falling back to pure relay: %s',
+                                mcpUiMeta.handler.url, err.message)
+                            return ok({ ...result, handlerError: err.message })
+                        }
+                    }
+
+                    logger.debug('MCP mikser_ui_action %s/%s (pure relay)', entityId, action)
+                    return ok(result)
+                } catch (err) {
+                    logger.error('MCP mikser_ui_action error: %s', err.message)
+                    return fail(err.message)
+                }
+            },
+        )
+
         const logger = useLogger()
-        logger.debug('MCP tool registered: mikser_preview_ui + mikser://mcp-ui/modes resource (preview plugin)')
+        logger.debug('MCP tools registered: mikser_preview_ui + mikser_ui_action + mikser://mcp-ui/modes resource (preview plugin)')
     })
 
     return { name: 'preview' }