mcpapp

package
v0.92.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

README

mcpapp: interactive charts for MCP hosts

This package makes Rill's MCP server render charts inside MCP hosts such as Claude (web, desktop, mobile), ChatGPT, Cursor and VS Code. It implements the server side of the MCP Apps extension and owns the widget bundle, the resource and tool metadata that describe it, and the capability that advertises it.

Standards

Layer Standard Where Rill implements it
Transport and protocol Model Context Protocol, streamable HTTP transport, JSON-RPC 2.0; the server negotiates protocol versions 2026-07-28 (which has no initialize handshake), 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05 runtime/server/mcp.go (runtime endpoint), admin/server/mcp.go (unified Rill Cloud endpoint), both on github.com/modelcontextprotocol/go-sdk v1.8.0
Tools with structured results MCP tools/call with content and structuredContent validated against the tool's outputSchema runtime/ai/ai.go (RegisterTool), runtime/ai/create_chart.go, runtime/ai/chart_data.go
Interactive UI MCP Apps, the official MCP extension SEP-1865 (specification revision 2026-01-26, extension identifier io.modelcontextprotocol/ui, source in modelcontextprotocol/ext-apps) this package, runtime/ai/mcp.go, admin/server/mcp.go; the widget in web-mcp-app/
ChatGPT compatibility OpenAI's plugin UI metadata layered on MCP Apps (openai/* _meta keys); ChatGPT reads the standard _meta.ui fields first WidgetResource in this package; openai/toolInvocation/* strings on the tools

Nothing here is Rill-specific protocol: any host that implements MCP Apps renders the chart, and any host that does not falls back to the tool's text result.

How it works

  1. Capability. When the widget is served, the server's initialize result advertises the extension: capabilities.extensions["io.modelcontextprotocol/ui"] = {"mimeTypes": ["text/html;profile=mcp-app"]} (ServerCapabilities). Hosts that support MCP Apps advertise the same extension in their request; the server does not gate on it because the stateless transport does not carry the client's capabilities on later requests, and the extension is harmless to hosts that ignore it.
  2. UI resource. The widget is one self-contained HTML document, served as an MCP resource with URI ui://rill/widget/<hash>.html and MIME type text/html;profile=mcp-app (WidgetResource, Register). <hash> is the first 12 hex characters of the SHA-256 of the bundle: hosts cache resources by URI, so a new build gets a new URI and is refetched. A resource template also serves the current bundle under any ui://rill/widget/*.html URI, because hosts keep the tool list of the build they last saw and request that URI after a release.
  3. Tool linkage. create_chart carries _meta.ui.resourceUri pointing at the resource (WidgetToolMeta). When the model calls it, the host reads the resource, renders it in a sandboxed iframe (a native WebView on mobile) and delivers the call's arguments and result to the iframe through the extension's ui/notifications/tool-input and ui/notifications/tool-result messages. On MCP servers the tool takes only the Flint shape of a chart (ai.MCPSpecProvider, runtime/ai/chart_flint.go): chart_spec with a chartType from the embedded catalog (runtime/ai/chartquery/flint_catalog.json, generated from the installed flint-chart package) and encodings binding channels to fields, plus a data block naming the metrics view, time range, comparison, filter and grain. The in-app chat keeps Rill's own chart spec (Spec); it renders the chart and queries its data itself, so its result carries no data and never reaches the widget.
  4. Data passing. The tool result has two parts. content is a markdown rendering (title, a table of the first rows, the "Open in Rill" link) for the model and for hosts without MCP Apps. structuredContent is the full chart payload the widget renders from: the effective input (the chart spec with the applied top-N limits, the data block with the resolved grain and the caller's semantic_types overrides), rows keyed by field, field metadata with formats, the Flint semantic types and display names derived from the metrics view (runtime/ai/chart_semantics.go), domain values, resolved time ranges, the project theme and the deep link. The contract is the JSON form of CreateChartResult in runtime/ai/create_chart.go. The widget compiles the spec with Flint and renders the Vega-Lite it produces; it needs no network access and never talks to the runtime directly.
  5. App-only tools. chart_data carries _meta.ui.visibility: ["app"] (AppOnlyToolMeta). Hosts hide it from the model and only let the widget call it, through the host's tools/call bridge, when the user changes the time grain, the top-N limit or the comparison inside the widget. It takes the arguments of a create_chart call and returns the data section of its result plus the effective input, with a one-line text content and a minimal input schema, since hosts without MCP Apps list it to the model. Those calls are not persisted as conversation messages (a sessionless call does not even create a session), but they count in the tool_call metric, since they run real queries.
  6. Host context. The host tells the widget its theme (light or dark), CSS variables, display mode (inline or fullscreen), container size, locale and time zone. The widget sends ui/open-link for "Open in Rill" and ui/update-model-context so the model knows what the chart currently shows.

Request flow for one chart:

model -> tools/call create_chart ------------> runtime: validate the chart spec against the catalog and the metrics view,
                                               plan the queries from the bound fields (chartquery.BuildFlint), run them
                                               through the metrics resolver, return content (markdown) + structuredContent
host  -> resources/read ui://rill/widget/.. -> runtime (or admin): widget HTML (cached by the host afterwards)
host  -> iframe: tool-input, tool-result ----> widget compiles the spec with Flint and renders the Vega-Lite with Rill's theme
widget -> host -> tools/call chart_data -----> runtime: fresh rows for the changed spec (app-only, ephemeral)

Security

  • The host enforces a Content Security Policy built from the resource's _meta.ui.csp. Rill declares no connectDomains and no frameDomains; the only external origin is https://assets.claude.ai in resourceDomains, which lets the widget load the host font Claude provides. Everything else is inline.
  • The widget runs with the same security claims as the conversation: every query behind create_chart and chart_data goes through the metrics resolver with the caller's claims, so metrics view security policies, row filters and field access apply unchanged.
  • No tokens are ever placed in the result or the widget; data flows only through the host's MCP bridge.

Gating and rollout

  • Two feature flags, both on by default, gate charts for external clients (mcpChartsEnabled in runtime/ai/util.go): chat_charts turns charts on or off in every AI chat, Rill's own included, and mcp_charts turns them off for external MCP clients alone. Together they enable the chart tools, the rill-charts skill and, on the runtime's own endpoint, the widget. Clients without MCP Apps get the markdown table and the link.
  • The widget is served whenever the binary carries the bundle. The unified /v1/mcp endpoint of the admin service cannot evaluate per-project flags, so it serves the widget unconditionally and leaves the per-project check to the runtime, which rejects create_chart calls for projects with charts disabled.
  • chart_data may only be called by the widget, so both endpoints advertise it exactly when they serve the widget (Session.MCPServer in runtime/ai/mcp.go and mcpForwardedToolSpecs in admin/server/mcp.go); create_chart is advertised regardless.
  • chart_data calls count in the tool_call metric like every other data tool, since they run real queries; they are not persisted in the session, since they are widget plumbing rather than conversation.
  • Both servers register the resource and the _meta.ui entries with the same helpers from this package (Register, WidgetToolMeta, AppOnlyToolMeta, ToolWithMeta, ServerCapabilities), so the two endpoints advertise identical metadata.

Building and serving the bundle

  • embed/widget.html is the build output of the web-mcp-app workspace and is not committed. make runtime.mcpapp.embed builds it and copies it into embed/; make cli runs that through cli.prepare, and the Rill Cloud image build runs it before go build embeds the file.
  • Widget() returns the embedded bundle, or the file named by RILL_MCP_APP_DIR during development (re-read whenever it changes, so npm run dev -w web-mcp-app gives a hot-reload loop). When no bundle is available the server simply does not advertise the widget.

Testing

  • go test ./runtime/ai/mcpapp/ covers the metadata (structpb-safe types), URI hashing, the resource template for stale URIs and the _meta merge helper.
  • go test ./runtime/server/ -run MCP and go test ./admin/server/ -run 'MCP|CallRuntimeTool' cover capability negotiation, resources/list and resources/read, tool metadata with the flag on and off, the markdown fallback and the pass-through of results on the unified endpoint.
  • Protocol check against a running server: npx @modelcontextprotocol/inspector --cli http://localhost:9009/mcp --transport http --method resources/list.
  • End to end in Claude: add the server as a custom connector (through a tunnel for a local server, with the Host header rewritten to localhost:<port>), or through mcp-remote in Claude Desktop; in ChatGPT, Plugins > Add custom MCP server.

References

Documentation

Overview

Package mcpapp serves the MCP Apps widget that renders Rill charts inside MCP hosts such as Claude and ChatGPT.

MCP Apps (the io.modelcontextprotocol/ui extension) lets a server register a resource with a ui:// URI whose body is a self-contained HTML document. A tool links to it through _meta.ui.resourceUri, and the host renders the HTML in a sandboxed iframe, pushing the tool call's result into it. This package owns the embedded widget bundle, the resource and tool metadata that describe it, and the server capability that advertises support for the extension.

The package has no dependency on the runtime so that tool specs can be built without one.

Index

Constants

View Source
const (
	// MIMEType is the MIME type of MCP Apps HTML resources.
	MIMEType = "text/html;profile=mcp-app"
	// ResourceName is the name of the widget resource.
	ResourceName = "rill-widget"
	// UIExtension is the identifier of the MCP Apps extension in capability negotiation.
	UIExtension = "io.modelcontextprotocol/ui"
	// VisibilityApp marks a tool as callable only by the widget (through the host), not by the model.
	VisibilityApp = "app"

	// DirEnv is an environment variable naming a directory to load the widget from instead of the embedded copy.
	// The file is re-read whenever it changes, which gives a hot reload loop during widget development.
	DirEnv = "RILL_MCP_APP_DIR"
)

Variables

This section is empty.

Functions

func AppOnlyToolMeta

func AppOnlyToolMeta(visibility []string) map[string]any

AppOnlyToolMeta returns the _meta entry that restricts a tool to the given callers (see VisibilityApp).

func Register

func Register(srv *mcp.Server, a *Asset)

Register adds the widget resource to the server. The current URI is listed as a resource. A template additionally serves the current bundle under any widget URI, because hosts cache the tool list and keep requesting the URI of the build they last saw; after a release that would otherwise fail until they refresh. The response echoes the requested URI.

func ServerCapabilities

func ServerCapabilities() *mcp.ServerCapabilities

ServerCapabilities returns the server capabilities to use when the widget is served: the MCP Apps extension with the MIME types the server can render. Tools and resources capabilities are still inferred by the SDK from what is registered. They leave out the logging capability the SDK advertises when given no capabilities: it is deprecated as of protocol version 2026-07-28, and Rill's servers never send log messages.

func ToolWithMeta

func ToolWithMeta(spec *mcp.Tool, meta map[string]any) *mcp.Tool

ToolWithMeta returns a shallow copy of a tool spec with meta merged into its _meta, or the spec itself when meta is empty. The copy gets its own _meta map, so the spec's _meta (which also flows into the in-app tool definitions) is left untouched.

func WidgetResource

func WidgetResource(a *Asset) *mcp.Resource

WidgetResource returns the MCP resource that serves the widget. Its _meta follows the MCP Apps spec plus the ChatGPT extras: a CSP that only allows Claude's font assets, a host-drawn border, inline and fullscreen display modes, and a description that keeps the model from restating the chart. Nested values are only map[string]any and []any so that they can also be converted with structpb.

func WidgetToolMeta

func WidgetToolMeta(a *Asset) map[string]any

WidgetToolMeta returns the _meta entry that links a tool to the widget resource.

Types

type Asset

type Asset struct {
	// Name is the file name of the bundle.
	Name string
	// Hash is the first 12 hex characters of the SHA-256 of HTML.
	// The URI embeds it so that hosts, which cache resources by URI, refetch the widget exactly when the bundle changes.
	Hash string
	// URI is the ui:// URI the widget resource is served at.
	URI string
	// HTML is the self-contained widget document.
	HTML string
}

Asset is a loaded widget bundle.

func Widget

func Widget() (*Asset, bool)

Widget returns the widget bundle, or false when none is available. The bundle comes from DirEnv when set, otherwise from the copy embedded at build time (see embed/README.md).

type ToolUI

type ToolUI struct {
	// Visibility lists who may call the tool. Empty means the model: the tool renders the widget with its result.
	// VisibilityApp means only the widget may call it (through the host), for example to refetch data.
	Visibility []string
}

ToolUI describes how a tool takes part in the MCP Apps widget.

func (*ToolUI) AppOnly

func (u *ToolUI) AppOnly() bool

AppOnly reports whether only the widget may call the tool: its visibility is exactly VisibilityApp. Calls to such tools are plumbing (the widget refetching data) rather than conversation turns.

func (*ToolUI) Meta

func (u *ToolUI) Meta(a *Asset) map[string]any

Meta returns the _meta.ui entry for a tool with this UI, or nil when the tool has nothing to advertise. Widget-rendering tools link to the widget resource, which requires the asset; app-only tools only declare their visibility.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL