mikser-io-mcp 0.2.0

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "mikser-io-mcp",
+  "version": "0.2.0",
+  "description": "MCP (Model Context Protocol) substrate and tools for mikser-io. Extracted from core to iterate on its own release cadence.",
+  "main": "index.js",
+  "type": "module",
+  "files": [
+    "index.js",
+    "preview.js",
+    "public",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "npm run test:unit",
+    "test:unit": "node --test --test-reporter=spec 'test/unit/**/*.test.js'"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/almero-digital-marketing/mikser-io-mcp.git"
+  },
+  "keywords": [
+    "mikser",
+    "mikser-io",
+    "mcp",
+    "model-context-protocol",
+    "ai-agent"
+  ],
+  "author": "",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/almero-digital-marketing/mikser-io-mcp/issues"
+  },
+  "homepage": "https://github.com/almero-digital-marketing/mikser-io-mcp#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "minimatch": "^10.0.3"
+  },
+  "peerDependencies": {
+    "mikser-io": "^8.2.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "mikser-io": "file:../mikser-io",
+    "zod": "^4.0.0"
+  }
+}

package/preview.js

@@ -0,0 +1,532 @@
+// MCP-UI surface for mikser-io-mcp. Registers everything that
+// surfaces UI through MCP: the shell resource, the discovery resource
+// for mcpUi modes, the mikser_preview_ui tool (with _meta.ui.resourceUri
+// pointing at the shell), the mikser_ui_action tool (with
+// _meta.ui.visibility=['app']), the forwardToHandler webhook helper,
+// and the mikser_preview_render tool that streams pipeline output via
+// the in-memory preview cache.
+//
+// The cache itself lives in mikser-io's preview plugin
+// (runtime.options.preview.{store, get, stats, config}). This module
+// reaches into it via that surface — no cross-plugin imports.
+
+import path from 'node:path'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { randomUUID, createHmac } from 'node:crypto'
+import { z } from 'zod'
+import { useRenderer, mimeForEntity, matchEntity } from 'mikser-io'
+
+// Resolve a path relative to this module's file. Used to find the
+// public/ folder regardless of where the package is installed (works
+// in node_modules, file: deps, npm-link setups, etc.).
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+// 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 }
+}
+
+// The MCP-UI shell HTML. Served as a single `ui://mikser/preview-ui-shell`
+// resource that mikser_preview_ui's _meta.ui.resourceUri points at, per
+// the MCP Apps spec (2026-01-26). Spec-conformant hosts fetch this once
+// per call, load it in a sandboxed iframe, then push the tool's
+// structuredContent via `ui/notifications/tool-result`.
+//
+// What the shell does:
+//   - ui/initialize handshake with the host (timeouts at 2s)
+//   - Listens for ui/notifications/tool-result → injects structuredContent.html
+//     into #mikser-ui-root, re-executes any <script> tags the layout brought
+//   - Exposes window.sendAction(action, payload) — the API layouts use to
+//     deliver clicks back as `tools/call` against mikser_ui_action
+//   - Logs every protocol event to an in-iframe debug panel so authors can
+//     see exactly where the spec round-trip fails on hosts that don't bridge
+//
+// Why a shell at all: per spec, tool UIs are RESOURCES. The host fetches
+// the resource (static) and receives the dynamic per-call data via the
+// tool-result notification. Layouts can stay server-side-templated against
+// the entity (mikser's strength) — they just produce *body content*, not
+// full HTML documents. The shell handles the protocol; layouts handle the
+// content. See documentation/decisions/0008-mcp-ui-action-delivery.md.
+const PREVIEW_UI_SHELL_HTML = readFileSync(path.join(__dirname, "public", "preview-ui-shell.html"), "utf8")
+
+// Plugin function — invoked by mikser-io-mcp/index.js's factory after
+// the substrate is set up. Registers the MCP-UI surface (shell + modes
+// resource + preview_ui + ui_action) AND the preview-render tool (which
+// reaches into runtime.options.preview for the cache).
+//
+// Not a default export plugin in the mikser sense — this is internal
+// composition. The mcp plugin's index.js is what mikser loads; this
+// file is just an organization unit.
+export default ({
+    runtime,
+    onLoaded,
+    useLogger,
+    findEntity,
+    findEntities,
+}) => {
+    onLoaded(() => {
+        if (!runtime.options.mcp) return
+        const mcp = runtime.options.mcp
+        const { render: previewRender } = useRenderer(runtime, {
+            defaultTimeout: runtime.config.preview?.renderTimeout ?? 30_000,
+        })
+
+        // mikser_preview_render — render an entity through the pipeline,
+        // stash the bytes in the in-memory preview cache (provided by
+        // mikser-io core's preview plugin via runtime.options.preview),
+        // and return a clickable URL. Requires --server (or any
+        // engine-supplied Express app) so the URL is reachable.
+        mcp.simpleTool(
+            'mikser_preview_render',
+            'Render an entity through the engine pipeline AND surface the FINAL output as a clickable URL served by the running --server. Use this instead of mikser_render when the user needs to see the result in a browser. The URL serves the pipeline\'s final output — PDF for a `*.html-pdf.*` layout, MJML-derived HTML for `*.html-mjml.*`, etc. Requires --server. Previews live in memory (not on disk, never under outputFolder) and auto-expire — default 10 minutes, clamped 30..3600 seconds.',
+            {
+                entity:  z.record(z.any()).describe('Entity shape with at least { id, collection } and any meta/content the renderer needs. Same shape as mikser_render.'),
+                options: z.record(z.any()).optional().describe('Renderer options. Same as mikser_render, plus { expiresInSeconds: number = 600 } controlling preview TTL.'),
+            },
+            async ({ entity = {}, options = {} }) => {
+                const logger = useLogger()
+                const preview = runtime.options.preview
+                const ok = (data) => ({
+                    content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+                })
+                const fail = (msg) => ({
+                    isError: true,
+                    content: [{ type: 'text', text: msg }],
+                })
+
+                try {
+                    if (!runtime.options.port) {
+                        return fail('mikser_preview_render requires --server to be running so the preview URL is reachable. Use mikser_render to get raw bytes inline instead.')
+                    }
+                    if (!preview) {
+                        return fail('mikser_preview_render requires the preview cache. Ensure mikser-io core is loaded and runtime.options.preview is available.')
+                    }
+
+                    const cfg = preview.config()
+                    const { expiresInSeconds = cfg.defaultTtl, ...renderOptions } = options ?? {}
+                    const { output, entity: rendered } = await previewRender(entity, {
+                        ...renderOptions,
+                        save: false,
+                        catalog: false,
+                    })
+                    const result = output?.result
+                    if (result == null) {
+                        return fail('Render produced no output. Check that the entity has a resolvable layout and the layout matched a registered renderer.')
+                    }
+
+                    const destExt = path.extname(rendered.destination || '').slice(1)
+                    const ext = destExt || 'html'
+                    const filename = `${randomUUID()}.${ext}`
+                    const mime = mimeForEntity(rendered) ?? 'application/octet-stream'
+                    const ttlSec = Math.max(cfg.ttlMin, Math.min(cfg.ttlMax, expiresInSeconds))
+
+                    preview.store({ filename, bytes: result, mime, ttlMs: ttlSec * 1000 })
+
+                    const url = `http://localhost:${runtime.options.port}${cfg.path}/${filename}`
+                    const bytes = Buffer.isBuffer(result) ? result.length : Buffer.byteLength(result)
+
+                    logger.debug('MCP mikser_preview_render cached %s (%d bytes, ttl %ds): %s', filename, bytes, ttlSec, url)
+
+                    return ok({
+                        previewUrl: url,
+                        mimeType: mime,
+                        bytes,
+                        expiresInSeconds: ttlSec,
+                        instructions: 'Open previewUrl in a browser to view. The preview lives in mikser memory and auto-expires after expiresInSeconds — re-run mikser_preview_render to refresh.',
+                    })
+                } catch (err) {
+                    logger.error('MCP mikser_preview_render error: %s', err.message)
+                    return fail(err.message)
+                }
+            },
+        )
+
+        // Discovery resource. Read this BEFORE calling mikser_preview_ui
+        // to learn which modes exist in the current project and which
+        // entity patterns each one covers — saves a round of guess-and-
+        // retry on mode names. Derived live from the catalog, so newly
+        // added layouts show up without restarts or tool re-registration.
+        mcp.registerResource(
+            'mikser-mcp-ui-modes',
+            'mikser://mcp-ui/modes',
+            {
+                title: 'MCP-UI modes available in this project',
+                description: 'Live list of mcpUi modes and their candidate layouts, derived from layout frontmatter. Read this to discover what mikser_preview_ui can do before calling it.',
+                mimeType: 'application/json',
+            },
+            async (uri) => {
+                const all = await findEntities()
+                const layouts = all.filter(l =>
+                    l.collection === 'layouts' && l.meta?.mcpUi)
+                const modes = {}
+                for (const layout of layouts) {
+                    const m = layout.meta.mcpUi
+                    const mode = m.mode ?? 'preview'
+                    if (!modes[mode]) modes[mode] = []
+                    modes[mode].push({
+                        layoutId:    layout.id,
+                        match:       layout.meta.match ?? null,
+                        description: m.description ?? null,
+                        actions:     m.actions     ?? [],
+                        sandbox:     m.sandbox     ?? ['allow-scripts'],
+                    })
+                }
+                return {
+                    contents: [{
+                        uri: uri.href,
+                        mimeType: 'application/json',
+                        text: JSON.stringify({
+                            modes,
+                            totalLayouts: layouts.length,
+                            notes: [
+                                "Modes are derived from layout.meta.mcpUi.mode (defaults to 'preview' when omitted).",
+                                'Each candidate has a `match` pattern. mikser_preview_ui matches your entityId against these patterns when you call it with that mode.',
+                                'Layouts without `mcpUi` frontmatter are not listed here and not eligible for mikser_preview_ui.',
+                            ],
+                        }, null, 2),
+                    }],
+                }
+            },
+        )
+
+        // ui://mikser/preview-ui-shell — the MCP-UI shell resource.
+        // mikser_preview_ui's _meta.ui.resourceUri points here. Hosts
+        // that implement MCP Apps fetch this once via resources/read,
+        // load it in a sandboxed iframe, then deliver the per-call
+        // structuredContent via ui/notifications/tool-result. The shell
+        // is static and version-independent across tool calls.
+        //
+        // mimeType MUST be 'text/html;profile=mcp-app' per the spec —
+        // basic-host and other conformant hosts reject anything else.
+        mcp.registerResource(
+            'mikser-preview-ui-shell',
+            'ui://mikser/preview-ui-shell',
+            {
+                title: 'MCP-UI shell for mikser_preview_ui',
+                description: 'The static iframe shell that mikser_preview_ui renders into. Handles the MCP Apps protocol (ui/initialize, tool-result injection, tools/call relay) so layouts can be content-only HTML.',
+                mimeType: 'text/html;profile=mcp-app',
+            },
+            async (uri) => ({
+                contents: [{
+                    uri: uri.href,
+                    mimeType: 'text/html;profile=mcp-app',
+                    text: PREVIEW_UI_SHELL_HTML,
+                }],
+            }),
+        )
+
+        // mikser_preview_ui — uses registerTool (not simpleTool) so we
+        // can set _meta.ui.resourceUri pointing at the shell. Per the
+        // MCP Apps spec, this signals to hosts: "this tool renders UI
+        // — fetch the resource at ui:// for the iframe template, and
+        // pass the tool's structuredContent to the iframe via
+        // ui/notifications/tool-result." Hosts without MCP Apps
+        // support fall back to displaying content[0].text.
+        mcp.registerTool(
+            'mikser_preview_ui',
+            {
+                description: 'Render an entity through a layout that declares `mcpUi` frontmatter and return it as a UI block. Selects the layout by matching `entityId` against `layout.meta.match` and filtering on `mode`. **Read `mikser://mcp-ui/modes` first** to discover which modes and entity patterns this project supports. Layouts without `mcpUi` frontmatter are not eligible. Spec-conformant hosts render the result inside an iframe loaded from `ui://mikser/preview-ui-shell`; non-UI hosts display the rendered HTML as text.',
+                inputSchema: {
+                    entityId: z.string().describe('Entity to render, e.g. "/articles/2026-launch".'),
+                    mode: z.string().optional().describe('Which UI mode to render. Defaults to "preview". Available modes are whatever your layouts declare as `mcpUi.mode`.'),
+                },
+                _meta: {
+                    ui: {
+                        // Spec-required: tells MCP Apps hosts to render
+                        // this tool's result inside the shell iframe.
+                        resourceUri: 'ui://mikser/preview-ui-shell',
+                    },
+                },
+            },
+            async ({ entityId, mode = 'preview' }) => {
+                const logger = useLogger()
+                const fail = (msg) => ({
+                    isError: true,
+                    content: [{ type: 'text', text: msg }],
+                })
+
+                try {
+                    // Find candidate layouts for this mode. The catalog
+                    // already has frontmatter-parsed meta — front-matter
+                    // plugin ran at onProcess. No re-parse needed.
+                    const all = await findEntities()
+                    const candidates = all.filter(l =>
+                        l.collection === 'layouts'
+                        && l.meta?.mcpUi
+                        && (l.meta.mcpUi.mode ?? 'preview') === mode
+                    )
+                    if (candidates.length === 0) {
+                        return fail(`No layouts found with mcpUi.mode="${mode}". Author a layout with YAML frontmatter at the top: \`---\\nmatch: "@/articles/*"\\nmcpUi:\\n  mode: ${mode}\\n  description: "..."\\n  actions: [...]\\n---\``)
+                    }
+
+                    const entity = await findEntity({ id: entityId })
+                    if (!entity) return fail(`Entity not found: ${entityId}`)
+
+                    const matched = candidates.find(l =>
+                        l.meta?.match && matchEntity(entity, l.meta.match))
+                    if (!matched) {
+                        const patterns = candidates
+                            .map(l => `  ${l.id}: match=${JSON.stringify(l.meta?.match ?? null)}`)
+                            .join('\n')
+                        return fail(`No mcpUi layout matched ${entityId} in mode=${mode}.\nCandidates for this mode:\n${patterns}`)
+                    }
+
+                    // Force the chosen layout — bypass autoLayouts /
+                    // layouts.match resolution that onProcessed would do.
+                    // Both `entity.layout` AND `entity.meta.layout` need
+                    // to be set: the layouts plugin's onProcessed
+                    // re-resolves entity.layout from entity.meta.layout
+                    // on every cycle, and previewRender goes through
+                    // the full lifecycle. Without overriding meta.layout
+                    // the agent's `mcp-ui/post-approval` choice gets
+                    // silently replaced by the production `post` layout.
+                    const renderEntity = {
+                        ...entity,
+                        layout: matched,
+                        meta: { ...(entity.meta || {}), layout: matched.name },
+                    }
+                    const { output } = await previewRender(renderEntity, {
+                        save: false,
+                        catalog: false,
+                    })
+                    const result = output?.result
+                    if (result == null) {
+                        return fail(`Render produced no output for ${entityId} via ${matched.id}. Check that the layout's template engine has a matching renderer plugin loaded.`)
+                    }
+
+                    const html = typeof result === 'string'
+                        ? result
+                        : Buffer.isBuffer(result)
+                            ? result.toString('utf8')
+                            : String(result)
+
+                    const mcpUiMeta = matched.meta?.mcpUi ?? {}
+                    logger.debug('MCP mikser_preview_ui rendered %s via %s (mode=%s, %d chars)',
+                        entityId, matched.id, mode, html.length)
+
+                    // Structured payload the iframe receives via
+                    // ui/notifications/tool-result. The shell reads
+                    // structuredContent.html and injects it into its
+                    // #mikser-ui-root div; entityId + layoutId are what
+                    // window.sendAction() forwards back to mikser_ui_action.
+                    const structured = {
+                        entityId,
+                        layoutId:    matched.id,
+                        mode,
+                        html,
+                        mcpUi: {
+                            layoutId:    matched.id,
+                            mode,
+                            description: mcpUiMeta.description ?? null,
+                            actions:     mcpUiMeta.actions     ?? [],
+                            sandbox:     mcpUiMeta.sandbox     ?? ['allow-scripts'],
+                            actionTool:  'mikser_ui_action',
+                        },
+                    }
+                    return {
+                        // content[0] is the fallback for hosts that don't
+                        // implement MCP Apps. They'll display this as
+                        // text — the layout's body HTML — so the user
+                        // at least sees the rendered content even if
+                        // the iframe doesn't load.
+                        content: [
+                            { type: 'text', text: html, mimeType: 'text/html' },
+                        ],
+                        // structuredContent — the spec-mandated way to
+                        // deliver per-call data to a UI tool's iframe.
+                        // Hosts pass this to the iframe via
+                        // ui/notifications/tool-result after the shell
+                        // (loaded from _meta.ui.resourceUri) completes
+                        // ui/initialize.
+                        structuredContent: structured,
+                        // _meta.mcpUi kept for backward compatibility
+                        // with hosts/tools that read it directly.
+                        // structuredContent.mcpUi is the canonical copy
+                        // going forward.
+                        _meta: { mcpUi: structured.mcpUi },
+                    }
+                } catch (err) {
+                    logger.error('MCP mikser_preview_ui error: %s', err.message)
+                    return fail(err.message)
+                }
+            },
+        )
+
+        // 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 tools registered: mikser_preview_render + mikser_preview_ui + mikser_ui_action + mikser://mcp-ui/modes + ui://mikser/preview-ui-shell (mcp plugin)')
+    })
+}