@mcp-apps-kit/ui

Client-side SDK for MCP applications (vanilla JavaScript).

Use this inside the HTML/JS UI returned by your tools. The SDK auto-detects the host (MCP Apps or ChatGPT Apps) and exposes a unified client for tool calls and host context.

Table of Contents

• Background
• Features
• Compatibility
• Install
• Usage
• Debug Logging
• Examples
• API
• Contributing
• License

Background

Widget UIs run inside host environments with different APIs and capabilities. This package normalizes those differences so your UI code can call tools, read results, and respond to host context changes from a single API. For React apps, use @mcp-apps-kit/ui-react.

Features

• createClient() with host auto-detection
• Tool calls with optional TypeScript typing
• Host context access (theme, display mode, safe areas)
• Tool inputs and results access
• Optional debug logger that transports logs via MCP
• Test adapter for local development
• Host capabilities - Query what the host supports (theming, display modes, file upload, etc.)
• Bidirectional tools - Register handlers for host-initiated tool calls
• Theme & style utilities - Apply host themes and CSS variables

Compatibility

• Hosts: MCP Apps and ChatGPT (OpenAI Apps SDK)
• Node.js: >= 18 for tooling/builds (browser runtime)
• MCP SDK: uses @modelcontextprotocol/ext-apps

Install

npm install @mcp-apps-kit/ui

Usage

Quick start

import { createClient } from "@mcp-apps-kit/ui";

const client = await createClient();

await client.callTool("greet", { name: "Alice" });

client.onHostContextChange((ctx) => {
  document.documentElement.dataset.theme = ctx.theme;
});

Typed tool calls

import { createClient } from "@mcp-apps-kit/ui";
import type { AppClientTools } from "../server";

const client = await createClient<AppClientTools>();

// Option 1: Using callTool with tool name string
await client.callTool("search_restaurants", { location: "Paris" });

// Option 2: Using the typed tools proxy (recommended)
await client.tools.callSearchRestaurants({ location: "Paris" });

The tools property provides a typed proxy with methods like callGreet(), callSearchRestaurants(), etc. Method names are generated from tool names by prepending "call" and capitalizing the first letter.

Local testing

import { createClient } from "@mcp-apps-kit/ui";

const client = await createClient({ forceAdapter: "mock" });

Automatic size notifications

By default, the MCP adapter automatically reports UI size changes to the host using a ResizeObserver. This allows the host to resize the UI container accordingly.

To disable automatic size change notifications:

import { createClient } from "@mcp-apps-kit/ui";

const client = await createClient({ autoResize: false });

When disabled, you can manually send size notifications:

await client.sendSizeChanged({ width: 800, height: 600 });

When to disable autoResize:

• When you want manual control over size notifications
• When your UI has a fixed size that never changes
• When implementing custom resize behavior

Default: true (auto-resize enabled)

Debug Logging

Send structured logs from the UI to the server via MCP:

import { clientDebugLogger } from "@mcp-apps-kit/ui";

clientDebugLogger.configure({
  enabled: true,
  level: "debug",
  source: "my-widget",
});

clientDebugLogger.info("Component mounted", { props: "..." });

Server-side configuration:

const app = createApp({
  config: {
    debug: {
      logTool: true,
      level: "debug",
    },
  },
});

Examples

• ../../examples/minimal
• kanban-mcp-example

API

Client Factory

• createClient(options?) - Create a connected client with auto-detection
  • options.forceAdapter - Force a specific adapter ("mcp" | "openai" | "mock")
  • options.autoResize - Enable/disable automatic size change notifications (default: true, MCP only)
• detectProtocol() - Detect the host platform ("mcp" | "openai" | "mock")

Typed Tools Proxy

The client.tools property provides typed method wrappers for tool calls:

import type { AppClientTools } from "../server";

const client = await createClient<AppClientTools>();

// Tool name "greet" becomes method "callGreet"
const result = await client.tools.callGreet({ name: "Alice" });

// Tool name "searchRestaurants" becomes "callSearchRestaurants"
const restaurants = await client.tools.callSearchRestaurants({ location: "Paris" });

This is equivalent to client.callTool("greet", { name: "Alice" }) but provides better IDE autocomplete and type checking.

Host Capabilities

const capabilities = client.getHostCapabilities();

// Common capabilities (both platforms)
capabilities?.theming?.themes; // ["light", "dark"]
capabilities?.displayModes?.modes; // ["inline", "fullscreen", "pip"]
capabilities?.statePersistence?.persistent; // boolean
capabilities?.openLinks; // {} if supported
capabilities?.logging; // {} if supported

// MCP Apps specific
capabilities?.serverTools?.listChanged; // boolean
capabilities?.serverResources?.listChanged; // boolean
capabilities?.sizeNotifications; // {} if supported
capabilities?.partialToolInput; // {} if supported

// ChatGPT specific
capabilities?.fileUpload; // {} if supported
capabilities?.safeAreaInsets; // {} if supported
capabilities?.views; // {} if supported

Host Version

const version = client.getHostVersion();
// { name: "MCP Host", version: "1.0.0" } (MCP Apps only)

Theme & Style Utilities

import {
  applyDocumentTheme,
  getDocumentTheme,
  applyHostStyleVariables,
  applyHostFonts,
  removeHostFonts,
  clearHostStyleVariables,
} from "@mcp-apps-kit/ui";

// Apply theme to document
applyDocumentTheme("dark"); // or "light" or "os"

// Apply host-provided CSS variables
applyHostStyleVariables({
  "primary-color": "#007bff",
  "--font-size": "16px",
});

// Apply host-provided font CSS
applyHostFonts("@font-face { ... }");

Bidirectional Tools (MCP Apps)

// Register a handler for host-initiated tool calls
client.setCallToolHandler(async (toolName, args) => {
  if (toolName === "get_selection") {
    return { selection: document.getSelection()?.toString() };
  }
  throw new Error(`Unknown tool: ${toolName}`);
});

// Register a handler for listing available tools
client.setListToolsHandler(async () => [
  { name: "get_selection", description: "Get current text selection" },
]);

Protocol Logging

// Send logs via the MCP protocol (appears in host logs)
await client.sendLog("info", { event: "user_action", details: "..." });

Error Handling

import { UIError, UIErrorCode } from "@mcp-apps-kit/ui";

try {
  await client.callTool("unknown");
} catch (error) {
  if (error instanceof UIError) {
    console.error(error.code, error.message);
  }
}

Key Types

• HostContext - Theme, viewport, locale, display mode, etc.
• HostCapabilities - Protocol-agnostic capability interface
• HostVersion - Host application name and version
• AppsClient - Main client interface
• UIError, UIErrorCode - Client-side error types

Contributing

See ../../CONTRIBUTING.md for development setup and guidelines. Issues and pull requests are welcome.

License

MIT