### Install and Run Restaurant Finder Example

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/examples/restaurant-finder/README.md

Commands to install dependencies, start the development server, or build and start the production server for the restaurant finder example.

```bash
pnpm install

pnpm dev

# Or start production server
pnpm build
pnpm start
```

--------------------------------

### Basic Server Setup with MCP Apps Kit

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/docs/quickstart.md

Sets up a basic MCP server using `@mcp-apps-kit/core`. It defines a tool named 'greet' with input validation using Zod and a UI resource. The server is then started on port 3000.

```typescript
import { createApp, defineTool, defineUI } from "@mcp-apps-kit/core";
import { z } from "zod";

// Define a UI resource for the tool
const greetingWidget = defineUI({
  name: "Greeting Widget",
  html: "./ui/dist/greeting.html",
  prefersBorder: true,
});

// Create the app
const app = createApp({
  name: "my-app",
  version: "1.0.0",
  tools: {
    greet: defineTool({
      title: "Greet User",
      description: "Generate a personalized greeting",
      input: z.object({
        name: z.string().describe("Name to greet"),
      }),
      output: z.object({
        message: z.string(),
        timestamp: z.string(),
      }),
      ui: greetingWidget,
      handler: async ({ name }) => ({
        message: `Hello, ${name}!`,
        timestamp: new Date().toISOString(),
      }),
    }),
  },
});

// Start the server
await app.start({ port: 3000 });
```

--------------------------------

### Install and Run Development Server

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/examples/minimal/README.md

Commands to install dependencies and start the development or production server for the application. These are standard Node.js package management commands.

```bash
pnpm install

pnpm dev

# Or start production server
pnpm build
pnpm start
```

--------------------------------

### Install MCP Apps Kit: Create or Add to Project

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/docs/quickstart.md

Installs the MCP Apps Kit CLI to create a new project or adds the core and UI packages to an existing project. Uses pnpm for package management.

```bash
# Create a new project
npx @mcp-apps-kit/create-app my-app
cd my-app
pnpm install

# Or add to an existing project
pnpm add @mcp-apps-kit/core @mcp-apps-kit/ui-react zod
```

--------------------------------

### Usage Examples for @mcp-apps-kit/create-app CLI

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/packages/create-app/README.md

Demonstrates various ways to use the @mcp-apps-kit/create-app CLI to scaffold applications. This includes specifying the app name, choosing a template (React or vanilla), setting an output directory, and controlling installation and Git initialization. It also shows how to include Vercel configuration.

```bash
# Create an app with a specific name
npx @mcp-apps-kit/create-app@latest my-app

# Choose a template (React or vanilla)
npx @mcp-apps-kit/create-app@latest my-app --template react
npx @mcp-apps-kit/create-app@latest my-app --template vanilla

# Specify the output directory
npx @mcp-apps-kit/create-app@latest my-app --directory ./apps/my-app

# Skip dependency installation and Git initialization
npx @mcp-apps-kit/create-app@latest my-app --skip-install
npx @mcp-apps-kit/create-app@latest my-app --skip-git

# Add Vercel configuration
npx @mcp-apps-kit/create-app@latest my-app --vercel
```

--------------------------------

### Server Setup with MCP Apps Kit Core

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/README.md

Demonstrates setting up a server using MCP Apps Kit core. It includes defining a UI widget and a tool for searching restaurants, then starting the application on port 3000.

```typescript
// server/index.ts
import { createApp, defineTool, defineUI, type ClientToolsFromCore } from "@mcp-apps-kit/core";
import { z } from "zod";

// Define UI widget for displaying restaurant results
const restaurantListUI = defineUI({
  name: "Restaurant List",
  description: "Displays restaurant search results",
  html: "./dist/widget.html",
  csp: {
    connectDomains: ["https://api.yelp.com"],
  },
});

const app = createApp({
  name: "restaurant-finder",
  version: "1.0.0",

  tools: {
    search_restaurants: defineTool({
      description: "Search for restaurants by location",
      input: z.object({
        location: z.string(),
        cuisine: z.string().optional(),
      }),
      output: z.object({
        count: z.number(),
        restaurants: z.array(
          z.object({
            id: z.string(),
            name: z.string(),
            rating: z.number(),
          })
        ),
      }),
      handler: async (input) => {
        const results = await fetchRestaurants(input.location, input.cuisine);
        return {
          count: results.length,
          restaurants: results,
          _meta: { fullDetails: results },
        };
      },
      ui: restaurantListUI,
    }),
  },
});

await app.start({ port: 3000 });

export type AppTools = typeof app.tools;
export type AppClientTools = ClientToolsFromCore<AppTools>;

```

--------------------------------

### React UI Component Setup with MCP Apps Kit

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/docs/quickstart.md

Demonstrates setting up a root React component (`App.tsx`) and a specific widget (`GreetingWidget.tsx`) for MCP applications. It utilizes `AppsProvider` from `@mcp-apps-kit/ui-react` to wrap the application and `useToolResult` and `useHostContext` hooks to display tool results and access host information.

```tsx
// ui/src/App.tsx
import { AppsProvider } from "@mcp-apps-kit/ui-react";
import { GreetingWidget } from "./GreetingWidget";

export function App() {
  return (
    <AppsProvider>
      <GreetingWidget />
    </AppsProvider>
  );
}

// ui/src/GreetingWidget.tsx
import { useToolResult, useHostContext } from "@mcp-apps-kit/ui-react";

interface GreetingResult {
  message: string;
  timestamp: string;
}

export function GreetingWidget() {
  const result = useToolResult<GreetingResult>();
  const { theme } = useHostContext();

  if (!result) {
    return <div>Loading...</div>;
  }

  return (
    <div style={{
      padding: "1rem",
      background: theme === "dark" ? "#1a1a1a" : "#fff"
    }}>
      <h2>{result.message}</h2>
      <p>Generated at: {new Date(result.timestamp).toLocaleString()}</p>
    </div>
  );
}
```

--------------------------------

### Extend Functionality with Plugins

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/docs/quickstart.md

Extend application functionality by providing plugins during app creation. Plugins can hook into various lifecycle events such as initialization and startup. The `loggingPlugin` is an example of a pre-built plugin that can be included.

```typescript
import { loggingPlugin } from "@mcp-apps-kit/core";

const app = createApp({
  name: "my-app",
  version: "1.0.0",
  plugins: [loggingPlugin],
  tools: { /* ... */ },
});
```

--------------------------------

### Quick Start: Define and Start an App with a Tool

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/packages/core/README.md

Demonstrates how to create a simple MCP application using createApp, define a tool with input and output schemas using Zod, and start the server.

```typescript
import { createApp, defineTool } from "@mcp-apps-kit/core";
import { z } from "zod";

const app = createApp({
  name: "my-app",
  version: "1.0.0",

  tools: {
    greet: defineTool({
      description: "Greet a user",
      input: z.object({
        name: z.string().describe("Name to greet"),
      }),
      output: z.object({ message: z.string() }),
      handler: async (input) => {
        return { message: `Hello, ${input.name}!` };
      },
    }),
  },
});

await app.start({ port: 3000 });
```

--------------------------------

### Install @mcp-apps-kit/create-app CLI

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/packages/create-app/README.md

Instructions for installing the @mcp-apps-kit/create-app CLI tool. It can be run directly using npx or installed globally for command-line access. Global installation provides a dedicated command 'create-mcp-apps-kit'.

```bash
# Run without installing
npx @mcp-apps-kit/create-app@latest

# Or install globally
npm install -g @mcp-apps-kit/create-app
create-mcp-apps-kit
```

--------------------------------

### React UI Setup with MCP Apps Kit

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/README.md

Demonstrates setting up a React component for UI in an MCP application. It utilizes type-safe hooks for interacting with tools and the host context. The `useAppsClient` hook provides access to tools, while `useToolResult` fetches results. The example shows how to call tools using both string names and a typed proxy, and how to render dynamic content based on tool results.

```typescript
// ui/src/App.tsx
import { useAppsClient, useToolResult, useHostContext } from "@mcp-apps-kit/ui-react";
import type { AppClientTools } from "../../server";

function RestaurantList() {
  // Type-safe hooks - tool names, inputs, and outputs are all inferred
  const client = useAppsClient<AppClientTools>();
  const result = useToolResult<AppClientTools>();
  const context = useHostContext();

  const restaurants = result?.search_restaurants?.restaurants ?? [];

  const handleRefresh = async () => {
    // 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" });
  };

  return (
    <div className={context.theme}>
      <h1>Restaurants ({result?.search_restaurants?.count})</h1>
      {restaurants.map((r) => (
        <div key={r.id}>
          <h3>{r.name}</h3>
          <p>Rating: {r.rating}</p>
        </div>
      ))}
      <button onClick={handleRefresh}>Refresh</button>
    </div>
  );
}

```

--------------------------------

### Monorepo Commands

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/CLAUDE.md

Lists essential commands for managing the pnpm monorepo, including installation, building, testing, linting, and type checking at the root level. It also shows how to run commands for specific packages or examples, and how to manage releases.

```bash
# Root commands
pnpm install && pnpm build && pnpm test && pnpm lint && pnpm typecheck

# Package-specific
pnpm -C packages/core test        # Test single package
pnpm -C examples/minimal dev      # Run minimal example with hot reload

# Release
pnpm release:version:patch|minor|major
```

--------------------------------

### MCP v1 API

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/examples/minimal/README.md

The v1 API for the MCP app, supporting a simple greet tool.

```APIDOC
## POST /v1/mcp

### Description
MCP v1 API endpoint for calling tools, specifically the 'greet' tool which takes only a name.

### Method
POST

### Endpoint
/v1/mcp

### Parameters
#### Query Parameters
None

#### Request Body
- **jsonrpc** (string) - The JSON-RPC version, should be "2.0".
- **method** (string) - The method to call, typically "tools/call".
- **params** (object) - Parameters for the method.
  - **name** (string) - The name of the tool to call, e.g., "greet".
  - **arguments** (object) - Arguments for the tool.
    - **name** (string) - Required. The name to be greeted.
- **id** (number) - The ID of the request.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "greet",
    "arguments": {
      "name": "World"
    }
  },
  "id": 1
}
```

### Response
#### Success Response (200)
- **jsonrpc** (string) - The JSON-RPC version, will be "2.0".
- **result** (object) - The result of the tool call.
  - **message** (string) - The greeting message.
  - **timestamp** (string) - The ISO timestamp of the greeting.
- **id** (number) - The ID of the request.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "result": {
    "message": "Hello, World!",
    "timestamp": "2023-10-27T10:00:00.000Z"
  },
  "id": 1
}
```
```

--------------------------------

### Test MCP API v1

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/examples/minimal/README.md

Example cURL command to test the v1 MCP API endpoint for the 'greet' tool. It sends a POST request with a JSONRPC payload, specifying the tool and arguments. This demonstrates how to interact with a specific API version.

```bash
curl -X POST http://localhost:3000/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"greet","arguments":{"name":"World"}},"id":1}'
```

--------------------------------

### Start MCP App with Stdio Transport

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/README.md

This snippet illustrates how to start an MCP application using the standard input/output (stdio) transport, typically used for CLI tools. It involves calling `app.start` with the `transport` option set to 'stdio'.

```typescript
await app.start({ transport: "stdio" });
```

--------------------------------

### Start MCP App with Express Server

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/README.md

This snippet shows the default method for starting an MCP application using an Express server. It utilizes the `app.start` method with a specified port.

```typescript
await app.start({ port: 3000 });
```

--------------------------------

### Clone and Run Kanban Demo Repository

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/README.md

This bash command sequence outlines the steps to clone the Kanban demo repository, navigate into its directory, install dependencies, and run the development server. It's useful for exploring advanced features like tool calling and React widgets.

```bash
git clone https://github.com/AndurilCode/kanban-mcp-example.git
cd kanban-mcp-example
npm install
npm run dev
```

--------------------------------

### Use Server-Side Debug Logger

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/docs/quickstart.md

Utilize the server-side `debugLogger` for logging information from your backend. This logger supports different levels (e.g., `info`) and allows passing contextual data as the second argument, such as user IDs.

```typescript
import { debugLogger } from "@mcp-apps-kit/core";

debugLogger.info("User action", { userId: "456" });
```

--------------------------------

### MCP v2 API

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/examples/minimal/README.md

The v2 API for the MCP app, supporting an enhanced greet tool with an optional surname.

```APIDOC
## POST /v2/mcp

### Description
MCP v2 API endpoint for calling tools, specifically the 'greet' tool which takes a name and an optional surname.

### Method
POST

### Endpoint
/v2/mcp

### Parameters
#### Query Parameters
None

#### Request Body
- **jsonrpc** (string) - The JSON-RPC version, should be "2.0".
- **method** (string) - The method to call, typically "tools/call".
- **params** (object) - Parameters for the method.
  - **name** (string) - The name of the tool to call, e.g., "greet".
  - **arguments** (object) - Arguments for the tool.
    - **name** (string) - Required. The first name to be greeted.
    - **surname** (string, optional) - The surname to be included in the greeting.
- **id** (number) - The ID of the request.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "greet",
    "arguments": {
      "name": "John",
      "surname": "Doe"
    }
  },
  "id": 1
}
```

### Response
#### Success Response (200)
- **jsonrpc** (string) - The JSON-RPC version, will be "2.0".
- **result** (object) - The result of the tool call.
  - **message** (string) - The greeting message.
  - **fullName** (string) - The full name used in the greeting.
  - **timestamp** (string) - The ISO timestamp of the greeting.
- **id** (number) - The ID of the request.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "result": {
    "message": "Hello, John Doe!",
    "fullName": "John Doe",
    "timestamp": "2023-10-27T10:00:00.000Z"
  },
  "id": 1
}
```
```

--------------------------------

### Creating a New MCP App via CLI

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/README.md

Demonstrates the command-line interface (CLI) command to create a new MCP application. This command initializes a new project with the necessary structure and dependencies for an MCP app, allowing developers to start building quickly.

```bash
npx @mcp-apps-kit/create-app@latest my-app

```

--------------------------------

### Configure OAuth 2.1 Authentication

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/docs/quickstart.md

Set up OAuth 2.1 authentication for your application by configuring protected resources, authorization servers, and required scopes. This enables bearer token validation and secure access to resources.

```typescript
const app = createApp({
  name: "my-app",
  version: "1.0.0",
  tools: { /* ... */ },
  config: {
    oauth: {
      protectedResource: "http://localhost:3000",
      authorizationServer: "https://auth.example.com",
      scopes: ["mcp:read", "mcp:write"],
    },
  },
});
```

--------------------------------

### TypeScript Configuration for Versioned App

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/examples/minimal/README.md

TypeScript code demonstrating how to configure a versioned application using `@mcp-apps-kit/core`. It shows setting up shared configurations (CORS, debug) and defining version-specific tools and versions.

```typescript
const app = createApp({
  name: "minimal-app",

  // Shared config across all versions
  config: {
    cors: { origin: true },
    debug: { logTool: true, level: "info" },
  },

  // Version-specific tools and config
  versions: {
    v1: {
      version: "1.0.0",
      tools: { greet: greetToolV1 },
    },
    v2: {
      version: "2.0.0",
      tools: { greet: greetToolV2 },
    },
  },
});

// Access version info programmatically
console.log(app.getVersions()); // ["v1", "v2"]
const v2App = app.getVersion("v2");
```

--------------------------------

### Create Custom Plugins

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/docs/quickstart.md

Define custom plugins to hook into specific application lifecycle events. This allows for fine-grained control over initialization, startup, and tool execution phases. Custom plugins can execute logic before or after tool calls and during app initialization.

```typescript
const myPlugin = {
  name: "my-plugin",
  onInit: async () => console.log("App initializing..."),
  onStart: async () => console.log("App started"),
  beforeToolCall: async (context) => {
    console.log(`Tool called: ${context.toolName}`);
  },
  afterToolCall: async (context) => {
    console.log(`Tool completed: ${context.toolName}`);
  },
};
```

--------------------------------

### Test MCP API v2

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/examples/minimal/README.md

Example cURL command to test the v2 MCP API endpoint for the 'greet' tool. This version supports an optional surname argument, demonstrating enhanced functionality in a later API version. It uses a similar JSONRPC payload structure.

```bash
curl -X POST http://localhost:3000/v2/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"greet","arguments":{"name":"John","surname":"Doe"}},"id":1}'
```

--------------------------------

### Install @mcp-apps-kit/ui-react-builder

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/packages/ui-react-builder/README.md

Install the UI React builder package using npm. This package is a dependency for building React-based UIs for MCP applications.

```bash
npm install @mcp-apps-kit/ui-react-builder
```

--------------------------------

### MCP Apps Kit React Hooks: Core and Host Capabilities

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/docs/quickstart.md

Provides an overview of core React hooks available in `@mcp-apps-kit/ui-react`, such as `useAppsClient`, `useToolResult`, and `useHostContext`. It also demonstrates how to use `useHostCapabilities` and `useHostVersion` to access information about the host environment, including theming and display modes.

```tsx
import { useHostCapabilities, useHostVersion } from "@mcp-apps-kit/ui-react";

function Widget() {
  const capabilities = useHostCapabilities();
  const version = useHostVersion();

  const themes = capabilities?.theming?.themes;       // ["light", "dark"]
  const modes = capabilities?.displayModes?.modes;    // ["inline", "fullscreen"]
  const hasFileUpload = !!capabilities?.fileUpload;   // ChatGPT only

  return <div>Host: {version?.name}</div>;
}
```

--------------------------------

### Subscribe to App Lifecycle Events

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/docs/quickstart.md

Subscribe to application lifecycle events to trigger custom actions. The `on` method allows you to listen for specific events, such as `tool:called`, and execute a callback function with event-specific data. This is useful for analytics or logging.

```typescript
app.on("tool:called", ({ toolName }) => {
  analytics.track("tool_called", { tool: toolName });
});
```

--------------------------------

### Health Check

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/examples/minimal/README.md

Provides a health check for the server.

```APIDOC
## GET /health

### Description
Checks the health status of the server.

### Method
GET

### Endpoint
/health

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **status** (string) - Indicates if the server is healthy (e.g., "OK").

#### Response Example
```json
{
  "status": "OK"
}
```
```

--------------------------------

### Install MCP Apps Kit Core Server Framework

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/README.md

Installs the core server framework for MCP Apps Kit along with its peer dependency Zod. This package is essential for building the server-side logic of your application.

```bash
npm install @mcp-apps-kit/core zod
```

--------------------------------

### Enable Debug Logging

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/docs/quickstart.md

Configure debug logging for your application to receive detailed logs from client UIs and the server. The `config.debug` object allows enabling specific logging features like `logTool` and setting the logging `level`.

```typescript
const app = createApp({
  name: "my-app",
  version: "1.0.0",
  tools: { /* ... */ },
  config: {
    debug: {
      logTool: true,
      level: "debug",
    },
  },
});
```

--------------------------------

### Claude Desktop MCP Server Configuration

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/examples/minimal/README.md

JSON configuration snippet to add to Claude Desktop's `claude_desktop_config.json`. This allows connecting to the different API versions exposed by the application, enabling Claude Desktop to utilize the services.

```json
{
  "mcpServers": {
    "minimal-app-v1": {
      "url": "http://localhost:3000/v1/mcp"
    },
    "minimal-app-v2": {
      "url": "http://localhost:3000/v2/mcp"
    }
  }
}
```

--------------------------------

### Access Auth Context in Handlers

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/docs/quickstart.md

Access authentication context within tool handlers to retrieve information about the authenticated user. The `context.subject` property provides the authenticated user ID, which can be used for authorization or personalization.

```typescript
tools: {
  get_user_data: defineTool({
    input: z.object({}),
    handler: async (_input, context) => {
      const subject = context.subject; // Authenticated user ID
      return { userId: subject };
    },
  }),
}
```

--------------------------------

### Install @mcp-apps-kit/ui-react

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/packages/ui-react/README.md

Installs the @mcp-apps-kit/ui-react package using npm. This package provides React bindings for MCP applications.

```bash
npm install @mcp-apps-kit/ui-react
```

--------------------------------

### API Versioning with Multiple Versions in MCP Apps Kit

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/packages/core/README.md

This example shows how to manage multiple API versions within a single application using `createApp`. Each version can have its own set of tools, UI configurations, and specific overrides for global settings like CORS or OAuth. The `versions` property in `createApp` allows defining these distinct versions, each with its own `version` number and `tools`. The application is started with `app.start()`, and each version is accessible at a dedicated route (e.g., `/v1/mcp`, `/v2/mcp`).

```typescript
const app = createApp({
  name: "my-app",

  // Shared config across all versions
  config: {
    cors: { origin: true },
    debug: { logTool: true, level: "info" },
  },

  // Version definitions
  versions: {
    v1: {
      version: "1.0.0",
      tools: {
        greet: defineTool({
          description: "Greet v1",
          input: z.object({ name: z.string() }),
          output: z.object({ message: z.string() }),
          handler: async ({ name }) => ({ message: `Hello, ${name}!` }),
        }),
      },
    },
    v2: {
      version: "2.0.0",
      tools: {
        greet: defineTool({
          description: "Greet v2",
          input: z.object({ name: z.string(), surname: z.string().optional() }),
          output: z.object({ message: z.string() }),
          handler: async ({ name, surname }) => ({
            message: `Hello, ${name} ${surname || ""}!`.trim(),
          }),
        }),
      },
    },
  },
});

await app.start({ port: 3000 });

// Each version is exposed at its dedicated route:
// - v1: http://localhost:3000/v1/mcp
// - v2: http://localhost:3000/v2/mcp

```

--------------------------------

### Install @mcp-apps-kit/ui Package

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/packages/ui/README.md

This command installs the @mcp-apps-kit/ui package using npm. This package is a dependency for developing client-side UIs for MCP applications.

```bash
npm install @mcp-apps-kit/ui
```

--------------------------------

### Initialize UI Client and Call a Tool (JavaScript)

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/packages/ui/README.md

Demonstrates the basic usage of the @mcp-apps-kit/ui SDK. It initializes a client, calls a 'greet' tool with a name parameter, and sets up a listener for host context changes to update the document's theme.

```typescript
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;
});
```

--------------------------------

### Build Commands

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/packages/ui-react-builder/README.md

Provides the standard npm/pnpm scripts for developing and building React UIs.

```APIDOC
## Build Commands

```json
{
  "scripts": {
    "dev": "concurrently \"pnpm dev:server\" \"pnpm dev:ui\"",
    "dev:server": "tsx watch src/index.ts",
    "dev:ui": "vite build --watch",
    "build": "pnpm build:ui && tsc",
    "build:ui": "vite build"
  }
}
```
```

--------------------------------

### Vite Plugin - Custom Logger

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/packages/ui-react-builder/README.md

Provides an example of how to configure a custom logger for the `mcpReactUI` Vite plugin. This allows for integration with existing logging mechanisms.

```typescript
mcpReactUI({
  serverEntry: "./src/index.ts",
  logger: {
    info: (msg) => myLogger.info(msg),
    warn: (msg) => myLogger.warn(msg),
    error: (msg) => myLogger.error(msg),
  },
});
```

--------------------------------

### Supported Patterns for defineReactUI

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/packages/ui-react-builder/README.md

Explains the recommended patterns for using `defineReactUI` for reliable static analysis detection.

```APIDOC
## Supported Patterns for `defineReactUI`

The plugin discovers `defineReactUI` calls using static analysis. For reliable detection:

- **Import components directly** from their source files:
  ```ts
  import { MyWidget } from "./ui/MyWidget"; // ✓ Works
  import { MyWidget } from "./ui"; // ✗ Barrel imports not supported
  ```
- **Use string literals** for the `name` property:
  ```ts
  name: "My Widget"; // ✓ Works
  name: `My ${type}`; // ✗ Template literals not supported
  ```
- **Reference components by identifier**:
  ```ts
  component: MyWidget; // ✓ Works
  component: widgets.MyWidget; // ✗ Property access not supported
  ```

If you need patterns not supported by auto-discovery, use `defineUI({ html: "..." })` with manual Vite bundling.
```

--------------------------------

### Scaffold New App with MCP Apps Kit CLI

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/README.md

Initializes a new application project using the MCP Apps Kit CLI scaffolding tool. This command fetches the latest version of the create-app package and executes it.

```bash
npx @mcp-apps-kit/create-app@latest
```

--------------------------------

### GET /health

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/CLAUDE.md

Provides a health check for the MCP Apps Kit service. This endpoint can be used to verify if the service is running and responsive.

```APIDOC
## GET /health

### Description
Health check endpoint to verify service status.

### Method
GET

### Endpoint
/health

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **status** (string) - Indicates the health status, e.g., "ok".

#### Response Example
```json
{
  "status": "ok"
}
```
```

--------------------------------

### HTML Utilities

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/packages/ui-react-builder/README.md

Lists utility functions for generating HTML documents and entry points.

```APIDOC
## HTML Utilities

| Export               | Description                            |
| -------------------- | -------------------------------------- |
| `generateHTML`       | Generate HTML document from bundled JS |
| `generateEntryPoint` | Generate React entry point code        |
```

--------------------------------

### Define Tool with React UI

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/packages/ui-react-builder/README.md

Example of defining a tool within an MCP application that utilizes a React-based UI. This integrates the `defineReactUI` helper with `defineTool` from `@mcp-apps-kit/core`.

```typescript
// src/index.ts
import { createApp, defineTool } from "@mcp-apps-kit/core";
import { defineReactUI } from "@mcp-apps-kit/ui-react-builder";
import { GreetingWidget } from "./ui/GreetingWidget";
import { z } from "zod";

const app = createApp({
  name: "my-app",
  version: "1.0.0",
  tools: {
    greet: defineTool({
      description: "Greet someone",
      input: z.object({ name: z.string() }),
      output: z.object({ message: z.string() }),
      ui: defineReactUI({
        component: GreetingWidget,
        name: "Greeting Widget",
        prefersBorder: true,
      }),
      handler: async ({ name }) => ({
        message: `Hello, ${name}!`,
      }),
    }),
  },
});
```

--------------------------------

### Define React Component for UI

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/packages/ui-react-builder/README.md

Example of defining a React component that can be used within an MCP application UI. It demonstrates fetching tool results and host context.

```tsx
// src/ui/GreetingWidget.tsx
import { useToolResult, useHostContext } from "@mcp-apps-kit/ui-react";

export function GreetingWidget() {
  const result = useToolResult();
  const { theme } = useHostContext();

  return (
    <div data-theme={theme}>
      <h1>{result?.greet?.message}</h1>
    </div>
  );
}
```

--------------------------------

### Implement Logging Middleware (TypeScript)

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/packages/core/README.md

Shows how to define and apply middleware to an application instance. This example implements a logger middleware that measures and logs the execution time of tool handlers.

```typescript
import type { Middleware } from "@mcp-apps-kit/core";

const logger: Middleware = async (context, next) => {
  const start = Date.now();
  context.state.set("startTime", start);
  await next();
  console.log(`${context.toolName} completed in ${Date.now() - start}ms`);
};

app.use(logger);
```

--------------------------------

### Get Host Version (TypeScript)

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/packages/ui/README.md

Fetches the version information of the host application. This typically includes the application name and its version number, which can be useful for version-specific logic or debugging.

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

--------------------------------

### Claude Desktop Configuration for Restaurant Finder

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/examples/restaurant-finder/README.md

JSON configuration to connect Claude Desktop to the restaurant finder MCP server. It specifies the command to run the server using tsx.

```json
{
  "mcpServers": {
    "restaurant-finder": {
      "command": "npx",
      "args": ["tsx", "path/to/examples/restaurant-finder/src/index.ts"]
    }
  }
}
```

--------------------------------

### Express Server Deployment

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/CLAUDE.md

Shows the default deployment option using an Express server. The `app.start` method initiates the server on a specified port. It also demonstrates how to integrate the MCP AppsKit application handler into custom Express middleware.

```typescript
// Express server (default)
await app.start({ port: 3000 });

// Custom Express middleware
expressApp.use("/mcp", app.handler());
```

--------------------------------

### Implement Custom OAuth Token Verification (TypeScript)

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/packages/core/README.md

Provides an example of how to implement a custom token verifier for OAuth 2.1 authentication. This is useful for handling non-JWT tokens or integrating with custom token introspection endpoints.

```typescript
import type { TokenVerifier } from "@mcp-apps-kit/core";

const customVerifier: TokenVerifier = {
  async verifyAccessToken(token: string) {
    const response = await fetch("https://auth.example.com/introspect", {
      method: "POST",
      body: new URLSearchParams({ token }),
    });

    const data = await response.json();

    if (!data.active) {
      throw new Error("Token inactive");
    }

    return {
      token,
      clientId: data.client_id,
      scopes: data.scope.split(" "),
      expiresAt: data.exp,
      extra: { subject: data.sub },
    };
  },
};

const app = createApp({
  name: "my-app",
  version: "1.0.0",
  tools: {
    /* ... */
  },
  config: {
    oauth: {
      protectedResource: "http://localhost:3000",
      authorizationServer: "https://auth.example.com",
      tokenVerifier: customVerifier,
    },
  },
});
```

--------------------------------

### Client-Side SDK Usage in MCP Apps

Source: https://github.com/andurilcode/mcp-apps-kit/blob/main/README.md

Demonstrates how to use the client-side SDK (`@mcp-apps-kit/ui`) to interact with MCP applications. The SDK provides a unified API for calling tools, sending follow-up messages, and requesting display mode changes, regardless of the host environment. It shows two methods for calling tools: using a string tool name or the recommended typed tools proxy.

```typescript
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("my_tool", { arg: "value" });

// Option 2: Using the typed tools proxy (recommended)
await client.tools.callMyTool({ arg: "value" });

await client.sendFollowUpMessage("Tell me more");
await client.requestDisplayMode("fullscreen");

```