mcpui

MCP-UI support for Kit — rich UI rendering in MCP tool results

Files

Dependencies

Capabilities

This package requires the net capability. Pass --allow=net when building or running:

kit build --allow=net myfile.kit -o myfile
kit run --allow=net myfile.kit

Installation

kit add gitlab.com/kit-lang/packages/kit-mcp-ui.git

Usage

import Kit.MCP as MCP
import Kit.MCPUI as UI

# Build a tool that returns rich HTML content
greeting-handler = fn(-params) =>
  html = <<~HTML
    <div style="font-family: sans-serif; padding: 20px;">
      <h1>Hello from Kit!</h1>
      <p>This is a rich UI greeting rendered inline.</p>
    </div>
  HTML
  UI.html-resource "ui://greeting" html

# Build a tool that embeds an external URL in an iframe
site-handler = fn(params) =>
  url = JSON.get-string params "url" ?? "https://example.com"
  UI.url-resource "ui://site" url
    |> UI.with-frame-size "800px" "600px"

# Register tools with an MCP server
main = fn =>
  greeting-tool = MCP.tool "show-greeting" "Display an HTML greeting" greeting-handler
  site-tool = MCP.tool "show-site" "Display a website in an iframe" site-handler

  srv = MCP.server "my-ui-server" "0.1.0"
    |> MCP.register greeting-tool
    |> MCP.register site-tool

  # Run with stdio transport
  MCP.serve-stdio srv

main

UIResource Builders

Action Builders

postMessage Helper

Development

Running Examples

Run examples with the interpreter:

kit run --allow=net examples/ui-server.kit
kit run --allow=net examples/actions-demo.kit

Compile examples to a native binary:

kit build --allow=net examples/ui-server.kit -o ui-server && ./ui-server http

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

Running kit dev

Run the standard development workflow (format, check, test):

kit dev

This will:

1. Format and check source files in src/
2. Run tests in tests/ with coverage

Generating Documentation

Generate API documentation from doc comments:

kit doc

Note: Kit sources with doc comments (##) will generate HTML documents in docs/*.html

Cleaning Build Artifacts

Remove generated files, caches, and build artifacts:

kit task clean

Note: Defined in kit.toml.

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/mcpui/, making it available for import as Kit.MCPUI in other projects.

License

This package is released under the MIT License - see LICENSE for details.

Exported Functions & Types

html-resource

Create a UIResource from raw HTML content. Returns a complete MCP tool result JSONValue with text/html mimeType.

String -> String -> JSONValue

url-resource

Create a UIResource from an external URL (rendered as iframe). Returns a complete MCP tool result JSONValue with text/uri-list mimeType.

String -> String -> JSONValue

blob-resource

Create a UIResource from base64-encoded content. Returns a complete MCP tool result JSONValue with the specified mimeType and blob data.

String -> String -> String -> JSONValue

with-frame-size

Attach preferred frame size to a UIResource result. Adds _meta.preferredFrameSize with the given width and height.

JSONValue -> String -> String -> JSONValue

tool-action

Build a tool action JSONValue — invokes an MCP tool.

String -> JSONValue -> JSONValue

intent-action

Build an intent action JSONValue — triggers a client-defined intent.

String -> JSONValue -> JSONValue

prompt-action

Build a prompt action JSONValue — inserts text into the user's prompt.

String -> JSONValue

notify-action

Build a notify action JSONValue — displays a notification.

String -> JSONValue

link-action

Build a link action JSONValue — opens a URL in the browser.

String -> JSONValue

post-message-script

Generate a script tag that sends a postMessage action from an iframe. The action JSONValue is serialized and sent to the parent window.

JSONValue -> String

html-resource

Create a UIResource from raw HTML content. Returns a complete MCP tool result JSONValue with text/html mimeType.

String -> String -> JSONValue

url-resource

Create a UIResource from an external URL (rendered as iframe). Returns a complete MCP tool result JSONValue with text/uri-list mimeType.

String -> String -> JSONValue

blob-resource

Create a UIResource from base64-encoded content. Returns a complete MCP tool result JSONValue with the specified mimeType and blob data.

String -> String -> String -> JSONValue

with-frame-size

Attach preferred frame size to a UIResource result. Adds _meta.preferredFrameSize with the given width and height.

JSONValue -> String -> String -> JSONValue

tool-action

Build a tool action JSONValue — invokes an MCP tool.

String -> JSONValue -> JSONValue

intent-action

Build an intent action JSONValue — triggers a client-defined intent.

String -> JSONValue -> JSONValue

prompt-action

Build a prompt action JSONValue — inserts text into the user's prompt.

String -> JSONValue

notify-action

Build a notify action JSONValue — displays a notification.

String -> JSONValue

link-action

Build a link action JSONValue — opens a URL in the browser.

String -> JSONValue

post-message-script

Generate a script tag that sends a postMessage action from an iframe. The action JSONValue is serialized and sent to the parent window.

JSONValue -> String

UIAction

An action sent from an iframe to the MCP client via postMessage. ToolAction invokes an MCP tool with parameters. IntentAction triggers a client-defined intent. PromptAction inserts text into the user's prompt. NotifyAction displays a notification to the user. LinkAction opens a URL in the user's browser.