diff --git a/CLAUDE.md b/CLAUDE.md index 7d15992d..3d89f67f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,6 +1,6 @@ # MCP AppsKit Development Guidelines -A TypeScript framework for building interactive MCP applications that work with both **MCP Apps (Claude Desktop)** and **ChatGPT (OpenAI Apps SDK)** from a single codebase. +A TypeScript framework for building interactive MCP applications that work with both **MCP Apps** and **ChatGPT (OpenAI Apps SDK)** from a single codebase. ## Project Structure diff --git a/docs/quickstart.md b/docs/quickstart.md index 3d941472..2116626e 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -1,6 +1,6 @@ # Quickstart -Build interactive MCP applications with rich UIs that work on both **Claude Desktop** and **ChatGPT** from a single codebase. +Build interactive MCP applications with rich UIs that work on both **MCP Apps** and **ChatGPT** from a single codebase. ## Installation @@ -321,8 +321,8 @@ tools: { MCP Apps Kit automatically handles protocol differences: -| Feature | Claude Desktop | ChatGPT | -|---------|---------------|---------| +| Feature | MCP Apps | ChatGPT | +|---------|----------|---------| | Tool execution | MCP protocol | OpenAI Apps SDK | | UI rendering | iframe | Widget runtime | | Theme support | Auto-detected | Auto-detected | diff --git a/examples/minimal/README.md b/examples/minimal/README.md index 7a67f401..cc848122 100644 --- a/examples/minimal/README.md +++ b/examples/minimal/README.md @@ -49,22 +49,12 @@ curl -X POST http://localhost:3000/v2/mcp \ -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"greet","arguments":{"name":"John","surname":"Doe"}},"id":1}' ``` -## Connecting to Claude Desktop +## Connecting to an MCP Apps Host -Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`): +Configure your MCP Apps-compatible host to connect to one or both API versions: -```json -{ - "mcpServers": { - "minimal-app-v1": { - "url": "http://localhost:3000/v1/mcp" - }, - "minimal-app-v2": { - "url": "http://localhost:3000/v2/mcp" - } - } -} -``` +- **v1 endpoint**: `http://localhost:3000/v1/mcp` +- **v2 endpoint**: `http://localhost:3000/v2/mcp` ## Testing diff --git a/examples/minimal/src/ui/GreetingWidgetV1.tsx b/examples/minimal/src/ui/GreetingWidgetV1.tsx index b7bb1adc..2604c2ad 100644 --- a/examples/minimal/src/ui/GreetingWidgetV1.tsx +++ b/examples/minimal/src/ui/GreetingWidgetV1.tsx @@ -6,7 +6,7 @@ * * This version demonstrates the debug logging via MCP tool transport: * - Logs are sent via the log_debug MCP tool - * - Default behavior for MCP adapter (Claude Desktop, etc.) + * - Default behavior for MCP adapter */ import { useEffect, useState } from "react"; diff --git a/examples/restaurant-finder/README.md b/examples/restaurant-finder/README.md index 56bfd7e1..2245ab21 100644 --- a/examples/restaurant-finder/README.md +++ b/examples/restaurant-finder/README.md @@ -69,17 +69,16 @@ Get mood-based restaurant recommendations. - `mood`: One of "quick", "romantic", "family", "business" -## Connecting to Claude Desktop - -Add to your Claude Desktop config: - -```json -{ - "mcpServers": { - "restaurant-finder": { - "command": "npx", - "args": ["tsx", "path/to/examples/restaurant-finder/src/index.ts"] - } - } -} +## Connecting to an MCP Apps Host + +Configure your MCP Apps-compatible host to connect to the server: + +**HTTP mode (default):** + +- Endpoint: `http://localhost:3000/mcp` + +**Stdio mode (for hosts that support it):** + +```bash +npx tsx path/to/examples/restaurant-finder/src/index.ts ``` diff --git a/package.json b/package.json index 39cf9294..0e0c02a1 100644 --- a/package.json +++ b/package.json @@ -3,7 +3,7 @@ "version": "0.3.0", "private": true, "type": "module", - "description": "Unified MCP Apps Builder SDK - Build MCP apps for Claude Desktop and ChatGPT from a single codebase", + "description": "Unified MCP Apps Builder SDK - Build MCP apps for any MCP Apps-compatible host from a single codebase", "scripts": { "build": "nx run-many --target=build", "test": "nx run-many --target=test", diff --git a/packages/core/README.md b/packages/core/README.md index 3c9f9b72..6e6e1120 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -4,7 +4,7 @@ Server-side framework for building MCP applications. -MCP AppsKit Core is the server runtime for defining tools, validating inputs and outputs with Zod, and binding UI resources. It targets both MCP Apps (Claude Desktop) and ChatGPT (OpenAI Apps SDK) from the same definitions. +MCP AppsKit Core is the server runtime for defining tools, validating inputs and outputs with Zod, and binding UI resources. It targets both MCP Apps and ChatGPT (OpenAI Apps SDK) from the same definitions. ## Table of Contents diff --git a/packages/core/src/adapters/mcp.ts b/packages/core/src/adapters/mcp.ts index 13396196..4baf7f61 100644 --- a/packages/core/src/adapters/mcp.ts +++ b/packages/core/src/adapters/mcp.ts @@ -1,7 +1,7 @@ /** * MCP Protocol Adapter * - * Handles metadata generation for MCP Apps protocol (Claude Desktop, etc.). + * Handles metadata generation for MCP Apps protocol. * Uses camelCase naming and _meta.ui.* namespace. */ diff --git a/packages/core/src/adapters/types.ts b/packages/core/src/adapters/types.ts index 7bf95edb..91082fbd 100644 --- a/packages/core/src/adapters/types.ts +++ b/packages/core/src/adapters/types.ts @@ -40,7 +40,7 @@ export interface UIResourceMetaResult { * Protocol adapter interface * * Implementations handle protocol-specific metadata generation for: - * - MCP Apps (Claude Desktop, etc.) + * - MCP Apps * - OpenAI/ChatGPT Apps * * This allows server/index.ts to remain protocol-agnostic. diff --git a/packages/core/src/types/config.ts b/packages/core/src/types/config.ts index a162fedc..a9fbd763 100644 --- a/packages/core/src/types/config.ts +++ b/packages/core/src/types/config.ts @@ -14,7 +14,7 @@ import type { UIDefs } from "./ui"; /** * Target protocol for metadata generation * - * - `"mcp"`: MCP Apps protocol (Claude Desktop, etc.) - uses camelCase metadata + * - `"mcp"`: MCP Apps protocol - uses camelCase metadata * - `"openai"`: OpenAI/ChatGPT Apps protocol - uses snake_case metadata with openai/ prefixes * * @internal @@ -239,7 +239,7 @@ export interface GlobalConfig { /** * Target protocol for metadata generation. * - * - `"mcp"` (default): MCP Apps protocol for Claude Desktop, etc. + * - `"mcp"` (default): MCP Apps protocol. * Uses camelCase metadata format (e.g., `_meta.ui.csp.connectDomains`) * * - `"openai"`: OpenAI/ChatGPT Apps protocol. diff --git a/packages/core/src/types/tools.ts b/packages/core/src/types/tools.ts index 3a6ae630..763d1b55 100644 --- a/packages/core/src/types/tools.ts +++ b/packages/core/src/types/tools.ts @@ -73,7 +73,7 @@ export interface UserLocation { /** * Context provided by the client during tool invocation * - * Contains metadata hints from the host platform (ChatGPT, Claude Desktop, etc.). + * Contains metadata hints from the host platform (ChatGPT, MCP Apps hosts, etc.). * All fields are optional as availability depends on the client. * * @example diff --git a/packages/core/tests/unit/context.test.ts b/packages/core/tests/unit/context.test.ts index 694001f0..863eebf0 100644 --- a/packages/core/tests/unit/context.test.ts +++ b/packages/core/tests/unit/context.test.ts @@ -166,11 +166,11 @@ describe("ToolContext", () => { it("should have correct type for userAgent", () => { const context: ToolContext = { - userAgent: "Claude Desktop/1.0", + userAgent: "MCP Host/1.0", raw: {}, }; - expect(context.userAgent).toBe("Claude Desktop/1.0"); + expect(context.userAgent).toBe("MCP Host/1.0"); }); it("should have correct type for userLocation", () => { diff --git a/packages/create-app/src/index.ts b/packages/create-app/src/index.ts index 00a93b5e..2617a0b6 100644 --- a/packages/create-app/src/index.ts +++ b/packages/create-app/src/index.ts @@ -417,19 +417,16 @@ ${packageManager} run dev ${packageManager} run build \`\`\` -## Connecting to Claude Desktop +## Connecting to an MCP Apps Host -Add to your Claude Desktop config: +Configure your MCP Apps-compatible host to connect to the server: -\`\`\`json -{ - "mcpServers": { - "${name}": { - "command": "npx", - "args": ["tsx", "path/to/${name}/server/index.ts"] - } - } -} +**HTTP mode (default):** +- Endpoint: \`http://localhost:3000/mcp\` + +**Stdio mode (for hosts that support it):** +\`\`\`bash +npx tsx path/to/${name}/server/index.ts \`\`\` ${ vercel @@ -804,19 +801,16 @@ ${packageManager} run dev ${packageManager} run build \`\`\` -## Connecting to Claude Desktop +## Connecting to an MCP Apps Host -Add to your Claude Desktop config: +Configure your MCP Apps-compatible host to connect to the server: -\`\`\`json -{ - "mcpServers": { - "${name}": { - "command": "npx", - "args": ["tsx", "path/to/${name}/server/index.ts"] - } - } -} +**HTTP mode (default):** +- Endpoint: \`http://localhost:3000/mcp\` + +**Stdio mode (for hosts that support it):** +\`\`\`bash +npx tsx path/to/${name}/server/index.ts \`\`\` ${ vercel diff --git a/packages/testing/src/ui/mock-host.ts b/packages/testing/src/ui/mock-host.ts index cd39004e..6879e0ca 100644 --- a/packages/testing/src/ui/mock-host.ts +++ b/packages/testing/src/ui/mock-host.ts @@ -12,7 +12,7 @@ import { uiLogger } from "../debug"; * Create a mock host environment for testing UI components * * This creates a standalone mock host that can be used to test UI widgets - * without requiring an actual host platform (like Claude Desktop or ChatGPT). + * without requiring an actual host platform (like an MCP Apps host or ChatGPT). * * @param options - Mock host configuration * @returns Mock host instance diff --git a/packages/ui-react-builder/README.md b/packages/ui-react-builder/README.md index 623cb31a..114aa77b 100644 --- a/packages/ui-react-builder/README.md +++ b/packages/ui-react-builder/README.md @@ -4,7 +4,7 @@ Build tool for React-based MCP application UIs. -`@mcp-apps-kit/ui-react-builder` allows you to define UI resources using React components instead of pre-built HTML files. The framework handles bundling React, ReactDOM, and `@mcp-apps-kit/ui-react` into self-contained HTML that works with both MCP Apps (Claude Desktop) and ChatGPT. +`@mcp-apps-kit/ui-react-builder` allows you to define UI resources using React components instead of pre-built HTML files. The framework handles bundling React, ReactDOM, and `@mcp-apps-kit/ui-react` into self-contained HTML that works with both MCP Apps and ChatGPT. ## Table of Contents @@ -193,14 +193,14 @@ If you need patterns not supported by auto-discovery, use `defineUI({ html: "... #### `defineReactUI` Options -| Option | Type | Default | Description | -| --------------- | --------------- | ---------- | ------------------------------------------------------------------------------------------------------------ | -| `component` | `ComponentType` | (required) | React component to render | -| `name` | `string` | (required) | Display name for the UI | -| `description` | `string` | - | Description of the UI widget | -| `prefersBorder` | `boolean` | - | Hint to the host whether a border should be drawn | -| `autoResize` | `boolean` | `true` | Enable automatic size change notifications. Only supported in MCP Apps (Claude Desktop); ignored in ChatGPT. | -| `csp` | `CSPConfig` | - | Content Security Policy configuration (ChatGPT only) | +| Option | Type | Default | Description | +| --------------- | --------------- | ---------- | ------------------------------------------------------------------------------------------- | +| `component` | `ComponentType` | (required) | React component to render | +| `name` | `string` | (required) | Display name for the UI | +| `description` | `string` | - | Description of the UI widget | +| `prefersBorder` | `boolean` | - | Hint to the host whether a border should be drawn | +| `autoResize` | `boolean` | `true` | Enable automatic size change notifications. Only supported in MCP Apps; ignored in ChatGPT. | +| `csp` | `CSPConfig` | - | Content Security Policy configuration (ChatGPT only) | ### Types diff --git a/packages/ui-react-builder/src/index.ts b/packages/ui-react-builder/src/index.ts index 7f6a6cec..4d0907c1 100644 --- a/packages/ui-react-builder/src/index.ts +++ b/packages/ui-react-builder/src/index.ts @@ -6,7 +6,7 @@ * This package allows you to define UI resources using React components * instead of pre-built HTML files. The framework handles bundling React, * ReactDOM, and @mcp-apps-kit/ui-react into self-contained HTML that works - * with both MCP Apps (Claude Desktop) and ChatGPT. + * with both MCP Apps and ChatGPT. * * @example Basic usage * ```typescript diff --git a/packages/ui-react/README.md b/packages/ui-react/README.md index 583d3fec..bffdcd94 100644 --- a/packages/ui-react/README.md +++ b/packages/ui-react/README.md @@ -119,7 +119,7 @@ export function App() { ### Automatic size notifications -By default, the MCP adapter automatically reports UI size changes to the host using a ResizeObserver. This feature is **only supported in MCP Apps (Claude Desktop)** and is silently ignored in ChatGPT. +By default, the MCP adapter automatically reports UI size changes to the host using a ResizeObserver. This feature is **only supported in MCP Apps** and is silently ignored in ChatGPT. To disable automatic resizing: @@ -166,7 +166,7 @@ export type AppClientTools = ClientToolsFromCore; - `AppsProvider` - Context wrapper for all hooks - `client?` - Pre-initialized client instance (optional) - `forceAdapter?` - Force a specific adapter ("mcp" | "openai" | "mock") - - `autoResize?` - Enable/disable automatic size change notifications (default: `true`). Only supported in MCP Apps (Claude Desktop); ignored in ChatGPT. Note: changing this prop after initial mount has no effect. + - `autoResize?` - Enable/disable automatic size change notifications (default: `true`). Only supported in MCP Apps; ignored in ChatGPT. Note: changing this prop after initial mount has no effect. - `fallback?` - Component to show while client initializes - `errorFallback?` - Component to show on initialization error @@ -225,7 +225,7 @@ function Widget() { const hasFileUpload = !!capabilities?.fileUpload; // Host version (MCP Apps only) - // { name: "Claude Desktop", version: "1.0.0" } + // { name: "MCP Host", version: "1.0.0" } return
Host: {version?.name}
; } ``` diff --git a/packages/ui/README.md b/packages/ui/README.md index b7263857..60039de4 100644 --- a/packages/ui/README.md +++ b/packages/ui/README.md @@ -203,7 +203,7 @@ capabilities?.views; // {} if supported ```ts const version = client.getHostVersion(); -// { name: "Claude Desktop", version: "1.0.0" } (MCP Apps only) +// { name: "MCP Host", version: "1.0.0" } (MCP Apps only) ``` ### Theme & Style Utilities diff --git a/packages/ui/src/adapters/mcp.ts b/packages/ui/src/adapters/mcp.ts index bdbb6e59..99920ef1 100644 --- a/packages/ui/src/adapters/mcp.ts +++ b/packages/ui/src/adapters/mcp.ts @@ -1,7 +1,7 @@ /** - * MCP Apps adapter for Claude Desktop + * MCP Apps adapter * - * Implements the ProtocolAdapter interface for MCP Apps running in Claude Desktop. + * Implements the ProtocolAdapter interface for MCP Apps hosts. * Uses @modelcontextprotocol/ext-apps (JSON-RPC over postMessage + ui/initialize). * * @internal @@ -63,7 +63,7 @@ export type McpAdapterOptions = { }; /** - * Adapter for MCP Apps (Claude Desktop) + * Adapter for MCP Apps hosts * * @internal * diff --git a/packages/ui/src/adapters/types.ts b/packages/ui/src/adapters/types.ts index edd8e360..df996b3d 100644 --- a/packages/ui/src/adapters/types.ts +++ b/packages/ui/src/adapters/types.ts @@ -26,7 +26,7 @@ import type { LogEntry } from "../debug/logger"; * Internal interface for protocol adapters * * Implemented by: - * - McpAppsAdapter: For Claude Desktop (MCP Apps) + * - McpAppsAdapter: For MCP Apps hosts * - ChatGptAppsAdapter: For ChatGPT (OpenAI Apps SDK) * - MockAdapter: For development/testing * diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts index 6fb3686a..468b9a31 100644 --- a/packages/ui/src/index.ts +++ b/packages/ui/src/index.ts @@ -7,7 +7,7 @@ * ```typescript * import { createClient } from "@mcp-apps-kit/ui"; * - * // Auto-detects platform (Claude Desktop vs ChatGPT) + * // Auto-detects platform (MCP Apps vs ChatGPT) * const client = await createClient(); * * // Type-safe tool calls @@ -148,7 +148,7 @@ function createAdapter( /** * Create a unified client for UI code * - * Automatically detects the host platform (Claude Desktop vs ChatGPT) + * Automatically detects the host platform (MCP Apps vs ChatGPT) * and returns a client with the appropriate adapter. * * @param options - Optional configuration diff --git a/packages/ui/src/types.ts b/packages/ui/src/types.ts index 0dbccc66..e9cad244 100644 --- a/packages/ui/src/types.ts +++ b/packages/ui/src/types.ts @@ -44,7 +44,7 @@ export interface HostCapabilities { }; // =========================================================================== - // MCP Apps specific capabilities (Claude Desktop) + // MCP Apps specific capabilities // =========================================================================== /** Host can proxy resource reads to MCP server (MCP Apps only) */ @@ -106,7 +106,7 @@ export interface HostCapabilities { * @internal */ export interface HostVersion { - /** Host application name (e.g., "Claude Desktop") */ + /** Host application name (e.g., "MCP Host") */ name: string; /** Host application version */ version: string; diff --git a/packages/ui/tests/unit/detection.test.ts b/packages/ui/tests/unit/detection.test.ts index 2299d650..61956203 100644 --- a/packages/ui/tests/unit/detection.test.ts +++ b/packages/ui/tests/unit/detection.test.ts @@ -2,7 +2,7 @@ * Unit tests for protocol detection * * Tests the detectProtocol() function that auto-detects - * whether the UI is running in Claude Desktop, ChatGPT, or development mode. + * whether the UI is running in an MCP Apps host, ChatGPT, or development mode. * * @vitest-environment jsdom */ diff --git a/packages/ui/tests/unit/mcp-adapter.test.ts b/packages/ui/tests/unit/mcp-adapter.test.ts index 7985d6e1..bd9f6797 100644 --- a/packages/ui/tests/unit/mcp-adapter.test.ts +++ b/packages/ui/tests/unit/mcp-adapter.test.ts @@ -1,7 +1,7 @@ /** * Unit tests for MCP adapter * - * Tests the McpAdapter implementation for Claude Desktop (MCP Apps). + * Tests the McpAdapter implementation for MCP Apps hosts. */ import { describe, it, expect, vi, beforeEach } from "vitest";