Description

Introduce comprehensive UIResource support for seamless integration with MCP-UI clients, enabling interactive widget serving through a unified API.

BREAKING CHANGE: None - this is purely additive functionality

New Features

Core UIResource API

• Add uiResource() method to McpServer for unified widget registration
• Support three resource types: externalUrl (iframe), rawHtml (direct), remoteDom (scripted)
• Automatic tool and resource generation with consistent naming patterns
• Props-to-parameters conversion with type safety and defaults

MCP-UI Adapter Layer

• Pure adapter functions for @mcp-ui/server compatibility
• URL building with query parameter encoding
• Support for text/blob encoding variants
• Framework support for React and Web Components

Template System

• New uiresource template demonstrating all resource types
• Comprehensive examples: Kanban board, welcome card, quick poll
• Complete documentation and usage patterns

Inspector Integration

• Enhanced resource rendering for MCP-UI compatibility
• Interactive widget preview and testing
• Seamless integration with existing inspector UI

Technical Details

Type System

• Discriminated union types for type-safe resource definitions
• Comprehensive prop configuration with validation
• Widget manifest system for declarative configuration

Testing

• Complete test coverage for all adapter functions
• URL parameter handling and encoding verification
• Error handling and edge case validation

Dependencies

• Add @mcp-ui/server v5.12.0 for UI resource creation
• Maintain backward compatibility with existing MCP functionality

Usage Example

// Register widget as both tool and resource
server.uiResource({
  type: 'externalUrl',
  name: 'kanban-board',
  widget: 'kanban-board',
  title: 'Kanban Board',
  props: {
    initialTasks: { type: 'array', required: false },
    theme: { type: 'string', default: 'light' }
  },
  size: ['900px', '600px']
})

// Automatically creates:
// - Tool: ui_kanban-board (accepts parameters)
// - Resource: ui://widget/kanban-board (static access)

Migration Path

• Existing servers continue to work unchanged
• New UIResource functionality is opt-in
• Gradual migration supported through template system

Closes #MCP-638

Does this PR need a changeset?

• ✅ Yes - I have created a changeset (pnpm changeset)
• ❌ No - This is an internal-only change (docs, tests, tooling)

Quick reminder:

pnpm changeset  # Creates a changeset interactively

📚 Full guide: Changeset Workflow Guide
Need help? See when to create changesets and examples

🚀 Release Target

• main branch → Stable release (default)
• beta branch → Beta/prerelease version
• Other feature branch → No release

Releasing a beta? See the Beta Release Workflow Guide for instructions.

Checklist

Code Quality

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have added tests that prove my fix is effective or that my feature works
• Existing tests pass locally (pnpm test)
• Linting passes (pnpm lint)
• Build succeeds (pnpm build)

Documentation

• The title of my pull request follows the conventional commits standard
• Changes have been documented in the README/documentation (if applicable)
• Breaking changes are clearly documented with migration steps

Release Preparation

• I have created a changeset (pnpm changeset) - if this affects published packages
• The changeset has a clear, user-focused description
• Version bump type is appropriate (patch/minor/major)
• All affected packages are included in the changeset

Additional Notes