Skip to content

feat(mcp): Zernio MCP App, interactive views in Claude and ChatGPT (behind ZERNIO_MCP_APPS) - #113

Merged
Ooscaar merged 12 commits into
developfrom
feat/mcp-apps
Nov 18, 2026
Merged

Ooscaar merged 12 commits into
developfrom
feat/mcp-apps

Conversation

@Ooscaar

@Ooscaar Ooscaar commented Nov 18, 2026 •

Copy link
Copy Markdown
Member

Summary

Adds an MCP App: an interactive Zernio panel that Claude and ChatGPT render inside the chat (Claude calls these "interactive connectors"). It's off unless ZERNIO_MCP_APPS=1, so production is unchanged when this merges.

It's one app with several screens, drawn in the dashboard's design system v2 (data-look="v2" in Schedule-Posts-API). It's structured like beel-mcp's app and built on the official ext-apps React pattern.

The screens

Screen Opened by What it shows Actions
Home zernio_open_app Accounts, how many need attention, failed posts, with lists of the accounts that need attention and the latest failed posts Reconnect, Ask Claude, Retry
Inbox show_inbox Latest conversations (with an unread pill) and posts with comments Open a thread
Conversation show_conversation The DM thread, oldest first, your messages tinted Send a reply, Draft with Claude
Comments show_post_comments A post's comments Reply per comment, Draft with Claude, View post
Failed posts show_failed_posts Every failed post, its reason behind the "Failed" pill Retry
Analytics show_analytics KPIs (impressions, engagement, views, posts); clicking one switches the daily chart; a platform table with share bars —
Accounts show_account_health Every account by health, the broken ones first Reconnect, which opens that account's reconnect link, and Ask Claude
Ads show_ads_alerts Rejected ads, delivery and payment problems, spend without results, capped budgets Fix (the alert's own link), Dismiss, Ask Claude
Post preview show_post_preview How a post goes out on each platform: resolved accounts, media, validation Publish now (two clicks), Save as draft

All of them share one header (logo, breadcrumb, refresh, full screen). In full screen there are tabs for Home, Inbox, Failed posts, Analytics, Accounts and Ads. Inline, each screen shows a compact card.

How it works

  • The app: apps-src/ is Vite 8, React 19, TypeScript 7 and @modelcontextprotocol/ext-apps 2.0.4 (the useApp/useHostStyles pattern from the SDK's basic-server-react example). It builds into one self-contained src/late/mcp/apps/bundle/mcp-app.html (500 kB, 142 kB gzipped). The built file is committed, so the Python image needs no Node. Rebuild with cd apps-src && npm run build.
  • The tools: every tool in src/late/mcp/apps/tools.py opens the same resource, ui://zernio/v2/app.html. Each returns a text summary for the model and for clients without MCP Apps, plus {view, data, args} for the app. The app switches tabs and refreshes by calling those same tools. These tools are added to the always-listed set while the switch is on, because a view only renders for a tool the host received in tools/list.
  • View-only tools (visibility: ["app"], hidden from the model):
    • ui_reconnect_account: GET /v1/connect/{platform} with reconnectAccountId
    • ui_send_message: messages_send_inbox_message isn't listed, so the app can't call it directly
    • ui_dismiss_ads_alert
  • Design:
    • the exact Theme, Scale and type/* values of libs/design-system/new-look.ts
    • Geist, Geist Mono and Geist Pixel Square
    • pixelarticons and the platform app icons from zernio.com/platform-logos
    • components follow design-principles.md, cited by number in the code
  • Fonts: MCP Apps only load fonts from declared domains, never as data: URLs. So the server serves the three woff2 files at /apps/fonts/ with CORS *, and writes its own MCP_PUBLIC_URL into the bundle and into the resource's CSP.
  • Talking to Claude: the app sends updateModelContext after each screen and each action, and sendMessage for "Ask Claude" and "Draft with Claude".
  • Starting up: if the opening tool's result never arrives (for example when opened from Claude's Artifacts page), the app loads the screen itself after 2.5 s.

Other changes

  • zernio_overview is plain text while the switch is on. With it off, it keeps its current card.

  • server.py: _platform_errors now builds on a new _failed_targets helper, which the failed-posts screen also uses. Merged with develop's media_item (fix(mcp): leave the media type out when the URL has no known extension #102), which the preview uses too.

  • .railway/railway.ts: ZERNIO_MCP_APPS added to the production variables that railway config apply keeps. Without it, the next apply would delete the variable.

Testing

  • The existing suite passes with the switch off and on (3265 passed, 14 skipped), and ruff is clean. As agreed, there are no new tests for the app yet.
  • Each tool was run against a mocked API, and each screen was rendered in a mock MCP Apps host, in light, dark, inline and full screen.
  • Still to check in Claude:
    • fonts and icons load in Claude's sandbox
    • Reconnect, Retry, Send and Reply buttons, and Claude's approval prompts
    • inline sizing
    • the Artifacts-page entry point

Not in this PR

  • Claude controlling the open panel (app-registered tools such as show_view)
  • CSV downloads
  • The post composer and the content calendar
  • Splitting the SDK and the MCP server into separate packages

🤖 Generated with Claude Code

Ooscaar and others added 11 commits November 18, 2026 14:55
Interactive views Claude and ChatGPT render in the chat, off unless
ZERNIO_MCP_APPS=1 so production is unchanged until it is turned on.

A view binds to the tool the host called, and most tools are reached
through call_tool, so each view gets its own always-listed show_* display
tool that fetches its own data (monday.com's show-* pattern):

- show_post_preview: per-platform preview with validation, Publish now /
  Save as draft via posts_cross_post
- show_failed_posts: failed posts with a Retry per post
- show_analytics: daily totals and chart, fullscreen platform breakdown
- show_account_health: accounts by health, Reconnect link
- show_ads_alerts: ads needing attention, Fix / Dismiss / Ask Claude
- show_automation_approvals: pending automation changes, Approve / Reject
- zernio_overview: the overview card, rebuilt on the runtime

ui_dismiss_ads_alert and ui_decide_automation_approval are app-only, for
the views' buttons. Views are self-contained HTML (no CDN) on a shared
MCP Apps 2026-01-26 bridge, styled with host tokens and the zernio.com
accent. Everything lives in late/mcp/apps so the trial can be removed in
one go.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A first cut of one app instead of separate views, following beel-mcp's
structure: apps-src/ is a Vite + TypeScript project on the official
ext-apps SDK, built by vite-plugin-singlefile into one self-contained
src/late/mcp/apps/bundle/app.html (248 kB, 66 kB gzipped), committed so
the Python image needs no Node.

zernio_open_app opens it (also listed on Claude's Artifacts page through
the openai/ui entry point). The app loads its own data with
callServerTool: account health, and failed posts through the unlisted
posts_list_posts, which tests whether Claude lets an app call a tool it
never listed. Inline it is a compact card with Open Zernio for full
screen; it tells Claude what it shows (updateModelContext) and hands
fixes to the chat (sendMessage). zernio.com tokens, Lucide icons.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Rebuilt on the ext-apps SDK's React pattern (useApp, useHostStyles, as
in its basic-server-react example) instead of beel-mcp's structure, and
drawn in the dashboard's product look (data-look="v2"): the Theme,
Scale and type/* values of Schedule-Posts-API's new-look.ts, Geist,
Geist Mono and Geist Pixel Square, pixelarticons, platform app icons
from zernio.com, square panels with a grey eyebrow bar, KPIs on one row
divided by hairlines, StatusPill with its reason behind the info mark,
the fix as an outline button in the row, notices as coloured text and
the pixel-rain spinner.

MCP Apps take fonts only from declared origins, so the server serves the
three woff2 files at /apps/fonts/ (CORS *) and fills its own
MCP_PUBLIC_URL into the bundle and into the resource's CSP, with
zernio.com for the icons.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The previous commit was pushed before these files were staged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Every screen now lives in the React app and is drawn from the same
design system v2 components (Section, Kpis, Row, StatusPill,
PlatformTile, Badge, Tabs, Notice, Button, Spinner), as beel-mcp keeps
one app: Home, Failed posts, Analytics, Accounts, Ads, Post preview and
Approvals.

Every show_* tool and zernio_open_app opens that one resource
(ui://zernio/v2/app.html) and returns {view, data, args}; the app
switches tabs and refreshes by calling the same tools, so data comes
from listed tools only. If the opening tool's result never arrives (the
app loaded no data on dev), it loads the opening tool's screen itself.
Full screen adds tabs; publishing from the preview takes two clicks.

The seven hand-written HTML views, their runtime.js and base.css are
gone; zernio_overview is text while the app is on.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The Reconnect button asked nothing of the account and opened the
dashboard. It now gets the account's reconnect link through the app-only
ui_reconnect_account (GET /v1/connect/{platform} with reconnectAccountId
and the account's profileId), so signing in refreshes that same account,
keeping its id and history. A refusal shows on the row's state pill.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
New Inbox tab, drawn with the same components as every other screen:
the latest conversations and the posts with comments
(show_inbox), a conversation as a thread with a reply box
(show_conversation, sending through the app-only ui_send_message, since
messages_send_inbox_message is not listed) and a post's comments with a
reply per comment (show_post_comments, replying through the listed
comments_reply_to_inbox_post). Each reply box can hand drafting to
Claude.

The Approvals screen, show_automation_approvals and
ui_decide_automation_approval are gone for now.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@railway-app
railway-app Bot temporarily deployed to zernio-mcp / dev November 18, 2026 15:36 Inactive
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@railway-app
railway-app Bot temporarily deployed to zernio-mcp / dev November 18, 2026 15:49 Inactive
@Ooscaar
Ooscaar merged commit f2096c0 into develop Nov 18, 2026
5 checks passed

This branch was previously deployed

1 inactive deployment
zernio-mcp / dev — c8533f64 Deployed Nov 18, 2026 by railway-app[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant