Repository: MCP-UI-Org/mcp-ui
Branch: main
Commit: af881f9eff2c
Files: 165
Total size: 833.0 KB

Directory structure:
gitextract_f5vcxr1e/

├── .github/
│   ├── CONTRIBUTING.md
│   ├── copilot-instructions.md
│   └── workflows/
│       ├── ci.yml
│       └── deploy-docs.yml
├── .gitignore
├── .prettierignore
├── .prettierrc.json
├── .releaserc.json
├── .ruby-version
├── CHANGELOG.md
├── CODE_OF_CONDUCT.md
├── LICENSE
├── README.md
├── SECURITY.md
├── docs/
│   ├── README.md
│   ├── package.json
│   └── src/
│       ├── .vitepress/
│       │   ├── config.ts
│       │   └── theme/
│       │       ├── custom.css
│       │       └── index.ts
│       ├── about.md
│       ├── guide/
│       │   ├── apps-sdk.md
│       │   ├── client/
│       │   │   ├── app-renderer.md
│       │   │   ├── overview.md
│       │   │   └── walkthrough.md
│       │   ├── embeddable-ui.md
│       │   ├── getting-started.md
│       │   ├── introduction.md
│       │   ├── mcp-apps.md
│       │   ├── protocol-details.md
│       │   ├── server/
│       │   │   ├── python/
│       │   │   │   ├── overview.md
│       │   │   │   ├── usage-examples.md
│       │   │   │   └── walkthrough.md
│       │   │   ├── ruby/
│       │   │   │   ├── overview.md
│       │   │   │   ├── usage-examples.md
│       │   │   │   └── walkthrough.md
│       │   │   └── typescript/
│       │   │       ├── overview.md
│       │   │       ├── usage-examples.md
│       │   │       └── walkthrough.md
│       │   └── supported-hosts.md
│       ├── index.md
│       └── team.md
├── eslint.config.mjs
├── examples/
│   ├── external-url-demo/
│   │   ├── index.html
│   │   ├── package.json
│   │   ├── src/
│   │   │   ├── App.css
│   │   │   ├── App.tsx
│   │   │   ├── index.css
│   │   │   └── main.tsx
│   │   ├── tsconfig.app.json
│   │   ├── tsconfig.json
│   │   ├── tsconfig.node.json
│   │   └── vite.config.ts
│   ├── mcp-apps-demo/
│   │   ├── package.json
│   │   ├── src/
│   │   │   └── index.ts
│   │   └── tsconfig.json
│   ├── python-server-demo/
│   │   ├── README.md
│   │   ├── pyproject.toml
│   │   └── python_server_demo.py
│   ├── ruby-server-demo/
│   │   ├── Gemfile
│   │   ├── README.md
│   │   └── server.rb
│   ├── server/
│   │   ├── .react-router/
│   │   │   └── types/
│   │   │       ├── +future.ts
│   │   │       ├── +routes.ts
│   │   │       ├── +server-build.d.ts
│   │   │       └── app/
│   │   │           ├── +types/
│   │   │           │   └── root.ts
│   │   │           └── routes/
│   │   │               └── +types/
│   │   │                   ├── home.ts
│   │   │                   ├── task.ts
│   │   │                   └── user.ts
│   │   ├── README.md
│   │   ├── app/
│   │   │   ├── app.css
│   │   │   ├── entry.server.tsx
│   │   │   ├── graph/
│   │   │   │   └── graph.tsx
│   │   │   ├── images.d.ts
│   │   │   ├── root.tsx
│   │   │   ├── routes/
│   │   │   │   ├── home.tsx
│   │   │   │   ├── task.tsx
│   │   │   │   └── user.tsx
│   │   │   ├── routes.ts
│   │   │   ├── user/
│   │   │   │   └── user.tsx
│   │   │   └── utils/
│   │   │       └── messageUtils.ts
│   │   ├── biome.json
│   │   ├── package.json
│   │   ├── pnpm-workspace.yaml
│   │   ├── react-router.config.ts
│   │   ├── src/
│   │   │   └── index.ts
│   │   ├── tsconfig.cloudflare.json
│   │   ├── tsconfig.json
│   │   ├── tsconfig.node.json
│   │   ├── vite.config.ts
│   │   ├── worker-configuration.d.ts
│   │   └── wrangler.jsonc
│   └── typescript-server-demo/
│       ├── README.md
│       ├── package.json
│       ├── src/
│       │   └── index.ts
│       └── tsconfig.json
├── lefthook.yml
├── package.json
├── pnpm-workspace.yaml
├── sdks/
│   ├── python/
│   │   └── server/
│   │       ├── CHANGELOG.md
│   │       ├── README.md
│   │       ├── pyproject.toml
│   │       ├── release.config.js
│   │       ├── src/
│   │       │   └── mcp_ui_server/
│   │       │       ├── __init__.py
│   │       │       ├── core.py
│   │       │       ├── exceptions.py
│   │       │       ├── types.py
│   │       │       └── utils.py
│   │       └── tests/
│   │           ├── __init__.py
│   │           ├── test_create_ui_resource.py
│   │           ├── test_metadata.py
│   │           └── test_ui_action_results.py
│   ├── ruby/
│   │   ├── .rspec
│   │   ├── .rubocop.yml
│   │   ├── CHANGELOG.md
│   │   ├── Gemfile
│   │   ├── README.md
│   │   ├── Rakefile
│   │   ├── lib/
│   │   │   ├── mcp_ui_server/
│   │   │   │   └── version.rb
│   │   │   └── mcp_ui_server.rb
│   │   ├── mcp_ui_server.gemspec
│   │   ├── release.config.js
│   │   └── spec/
│   │       ├── mcp_ui_server_spec.rb
│   │       └── spec_helper.rb
│   └── typescript/
│       ├── client/
│       │   ├── CHANGELOG.md
│       │   ├── README.md
│       │   ├── package.json
│       │   ├── scripts/
│       │   │   └── proxy/
│       │   │       └── index.html
│       │   ├── src/
│       │   │   ├── __tests__/
│       │   │   │   └── capabilities.test.ts
│       │   │   ├── capabilities.ts
│       │   │   ├── components/
│       │   │   │   ├── AppFrame.tsx
│       │   │   │   ├── AppRenderer.tsx
│       │   │   │   └── __tests__/
│       │   │   │       ├── AppFrame.test.tsx
│       │   │   │       ├── AppRenderer.test.tsx
│       │   │   │       └── ProxyScript.test.ts
│       │   │   ├── index.ts
│       │   │   ├── test-setup.ts
│       │   │   ├── types.ts
│       │   │   └── utils/
│       │   │       ├── __tests__/
│       │   │       │   ├── isUIResource.test.ts
│       │   │       │   └── metadataUtils.test.ts
│       │   │       ├── app-host-utils.ts
│       │   │       ├── isUIResource.ts
│       │   │       └── metadataUtils.ts
│       │   ├── tsconfig.json
│       │   ├── tsconfig.test.json
│       │   ├── vite.config.ts
│       │   └── vitest.config.ts
│       ├── server/
│       │   ├── CHANGELOG.md
│       │   ├── README.md
│       │   ├── package.json
│       │   ├── src/
│       │   │   ├── __tests__/
│       │   │   │   ├── index.test.ts
│       │   │   │   ├── test-utils.ts
│       │   │   │   └── utils.test.ts
│       │   │   ├── index.ts
│       │   │   ├── types.ts
│       │   │   └── utils.ts
│       │   ├── tsconfig.json
│       │   ├── vite.config.ts
│       │   └── vitest.config.ts
│       └── shared/
│           ├── package.json
│           ├── src/
│           │   └── index.ts
│           ├── tsconfig.json
│           └── vite.config.ts
├── tsconfig.base.json
├── vitest.config.ts
└── vitest.setup.ts

================================================
FILE CONTENTS
================================================

================================================
FILE: .github/CONTRIBUTING.md
================================================
# Contributing to MCP-UI

First of all, thank you for your interest in contributing to MCP-UI! We appreciate the time and effort you're willing to invest in improving the project. This document provides guidelines and information to make the contribution process as smooth as possible.

## Table of Contents

- [Getting Started](#getting-started)
- [Local Development](#local-development)
  - [Prerequisites](#prerequisites)
  - [Setting Up Your Development Environment](#setting-up-your-development-environment)
  - [Running the Project Locally](#running-the-project-locally)
  - [Testing](#testing)
  - [Code Formatting](#code-formatting)
  - [Development Workflow](#development-workflow)
  - [Project Structure](#project-structure)
- [How to Contribute](#how-to-contribute)
  - [Reporting Bugs](#reporting-bugs)
  - [Suggesting Enhancements](#suggesting-enhancements)
  - [Submitting Pull Requests](#submitting-pull-requests)
- [Style Guidelines](#style-guidelines)
  - [Code Style](#code-style)
  - [Commit Messages](#commit-messages)
- [Additional Resources](#additional-resources)

## Getting Started

1. Fork the repository and clone it to your local machine.
2. Set up the development environment.
3. Explore the codebase, run tests, and verify that everything works as expected.

## Local Development

### Prerequisites

Before you start working on MCP-UI, make sure you have the following installed:

- [Node.js](https://nodejs.org/) (version 18 or higher recommended)
- [pnpm](https://pnpm.io/) (version 8.15.7 or higher)
- Git

### Setting Up Your Development Environment

1. Clone your forked repository:

   ```bash
   git clone https://github.com/your-username/mcp-ui.git
   cd mcp-ui
   ```

2. Install dependencies:

   ```bash
   pnpm install
   ```

3. Set up environment variables:
   - Create a `.env.local` file in the root directory
   - Add any necessary environment variables (ask project maintainers if you need access to specific API keys)

### Running the Project Locally

To start the development server:

```bash
pnpm vercel dev
```

This will start the Next.js development server, typically at http://localhost:3000.

For running with the MCP Inspector (useful for debugging MCP endpoints):

```bash
pnpm run inspector
```

### Testing

To run tests:

```bash
pnpm test
```

MCP-UI uses Vitest as the testing framework. When adding new features, please include appropriate tests.

### Code Formatting

MCP-UI uses Prettier for code formatting and lint-staged to ensure code is properly formatted before committing. Pre-commit hooks are set up with Husky to run these checks automatically.

To manually format your code:

```bash
pnpm prettier --write .
```

### Development Workflow

1. Create a new branch for your feature/bugfix
2. Make your changes
3. Add tests for your changes when applicable
4. Run the tests to ensure they pass
5. Commit your changes following the commit message guidelines
6. Push your branch and open a pull request

### Project Structure

- `api/`: Contains the server-side code and MCP implementation
  - `tools/`: MCP tools implementation
  - `utils/`: Utility functions for the API
- `app/`: Next.js app directory with React components
- `pages/`: Additional Next.js pages
- `public/`: Static assets
- `shared/`: Shared utilities used across the codebase

## How to Contribute

### Reporting Bugs

If you encounter a bug or issue while using MCP-UI, please open a new issue on the [GitHub Issues](https://github.com/idosal/mcp-ui/issues) page. Provide a clear and concise description of the problem, steps to reproduce it, and any relevant error messages or logs.

### Suggesting Enhancements

We welcome ideas for improvements and new features. To suggest an enhancement, open a new issue on the [GitHub Issues](https://github.com/idosal/mcp-ui/issues) page. Describe the enhancement in detail, explain the use case, and outline the benefits it would bring to the project.

### Submitting Pull Requests

1. Create a new branch for your feature or bugfix. Use a descriptive name like `feature/your-feature-name` or `fix/your-bugfix-name`.
2. Make your changes, following the [Style Guidelines](#style-guidelines) below.
3. Test your changes and ensure that they don't introduce new issues or break existing functionality.
4. Commit your changes, following the [commit message guidelines](#commit-messages).
5. Push your branch to your fork on GitHub.
6. Open a new pull request against the `main` branch of the `mcp-ui` repository. Include a clear and concise description of your changes, referencing any related issues.

## Style Guidelines

### Code Style

MCP-UI uses [ESLint](https://eslint.org/) as its code style guide. Please ensure that your code follows these guidelines.

### Commit Messages

Write clear and concise commit messages that briefly describe the changes made in each commit. Use the imperative mood and start with a capitalized verb, e.g., "Add new feature" or "Fix bug in function".

## Additional Resources

- [GitHub Help](https://help.github.com/)
- [GitHub Pull Request Documentation](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests)
- [ESLint Style Guide](https://eslint.org/)

Thank you once again for your interest in contributing to MCP UI. We look forward to collaborating with you and creating an even better project together!


================================================
FILE: .github/copilot-instructions.md
================================================
# MCP-UI Development Instructions

**ALWAYS follow these instructions first and fallback to additional search and context gathering only if the information here is incomplete or found to be in error.**

MCP-UI is a Model Context Protocol UI SDK monorepo providing TypeScript and Ruby SDKs for building MCP enabled applications with interactive UI components. The repository includes client SDKs, server SDKs, documentation, and examples.

## Working Effectively

### Bootstrap and Build (CRITICAL - Set 60+ minute timeouts)
- Install Node.js 22.x and pnpm 9+: `npm install -g pnpm`
- Install Ruby 3.x and bundler: `sudo apt-get install -y ruby ruby-dev build-essential && sudo gem install bundler`
- Clone repository: `git clone https://github.com/idosal/mcp-ui.git && cd mcp-ui`
- Install dependencies: `pnpm install` -- takes ~60 seconds. NEVER CANCEL.
- Build all packages: `pnpm build` -- takes ~15 seconds. NEVER CANCEL. Set timeout to 120+ seconds.
- Build documentation: `pnpm docs:build` -- takes ~17 seconds. NEVER CANCEL. Set timeout to 180+ seconds.

### Testing (CRITICAL - Set 30+ minute timeouts)
- Run TypeScript tests: `pnpm test:ts` -- takes ~6 seconds. NEVER CANCEL. Set timeout to 300+ seconds.
- Run Ruby tests: `pnpm test:ruby` -- takes ~1 second. NEVER CANCEL. Set timeout to 300+ seconds.
- Run all tests: `pnpm test` -- combines TypeScript and Ruby tests. NEVER CANCEL. Set timeout to 300+ seconds.
- Run with coverage: `pnpm coverage` -- NEVER CANCEL. Set timeout to 600+ seconds.

### Code Quality (Always run before committing)
- Lint code: `pnpm lint` -- takes ~2.4 seconds. Uses ESLint with TypeScript parser.
- Fix linting issues: `pnpm lint:fix`
- Format code: `pnpm format` -- Uses Prettier with single quotes, trailing commas, 100 char width.

### Development Workflow
- Run TypeScript SDKs in development: `pnpm dev` -- starts all TypeScript package dev servers in parallel.
- Run docs in development: `pnpm docs:dev` -- starts VitePress dev server.
- Preview builds: `pnpm preview` -- preview built packages.

## Validation (CRITICAL - Always perform these after changes)

### Mandatory End-to-End Validation Scenarios
1. **Always build and test after making changes:** Run `pnpm build && pnpm test` to ensure nothing is broken.
2. **Validate examples work:** Test working examples by running:
   - `cd examples/remote-dom-demo && npm run build` -- takes ~1 second. Always works.
   - `cd examples/wc-demo && npm run build` -- takes ~1 second. Always works.
   - NOTE: `typescript-server-demo` may have import issues and should be tested separately after SDK changes.
3. **Test UI components:** When changing client components, manually verify React rendering works by running example applications.
4. **Validate SDK functionality:** When changing server SDKs, test resource creation with both TypeScript and Ruby implementations.
5. **Documentation validation:** When updating docs, run `pnpm docs:build` and verify no broken links or build errors.

### Ruby SDK Specific Validation
- Ruby gems must be installed with `sudo bundle install` in `sdks/ruby/` directory
- Run Ruby linting: `cd sdks/ruby && sudo bundle exec rubocop`
- Ruby tests validate resource creation: `cd sdks/ruby && sudo bundle exec rake spec`

## Project Structure

### Key Directories
- `sdks/typescript/` - TypeScript SDKs (client, server, shared)
  - `client/` - React components for rendering MCP-UI resources
  - `server/` - Utilities for creating UI resources on MCP servers
  - `shared/` - Common types and utilities
- `sdks/ruby/` - Ruby SDK (`mcp_ui_server` gem)
- `examples/` - Demo applications showcasing SDK usage
  - `remote-dom-demo/` - Interactive UI script testing
  - `typescript-server-demo/` - Complete TypeScript server example
  - `ruby-server-demo/` - Complete Ruby server example
- `docs/` - VitePress documentation site

### Critical Files
- `package.json` - Root monorepo configuration with pnpm workspaces
- `pnpm-workspace.yaml` - Workspace configuration for TypeScript packages and examples
- `.github/workflows/ci.yml` - CI pipeline with build, test, and release steps
- `vitest.config.ts` - Test configuration for TypeScript packages
- `tsconfig.base.json` - Base TypeScript configuration

## Build System Details

### Package Management
- Uses pnpm workspaces for monorepo management
- TypeScript packages use Vite for building with dual ESM/CJS output
- Ruby uses standard gem building with bundler

### Dependencies and Versions
- Node.js 22.x (required for TypeScript SDKs)
- pnpm 9+ (required for workspace management)
- Ruby 3.x (required for Ruby SDK)
- React 18+ (peer dependency for client SDK)

### Build Outputs
- TypeScript client: Builds to `dist/` with ESM, CJS, and Web Component builds
- TypeScript server: Builds to `dist/` with ESM and CJS formats
- Ruby gem: Standard gem structure in `lib/`
- Documentation: Static site built to `docs/src/.vitepress/dist/`

## Common Development Tasks

### Adding New Features
1. Determine if change affects TypeScript SDKs, Ruby SDK, or both
2. Make changes following existing patterns
3. Add appropriate tests (Vitest for TypeScript, RSpec for Ruby)
4. Update documentation if needed
5. Run full validation workflow: `pnpm build && pnpm test && pnpm lint`

### Working with Examples
- Examples use workspace dependencies and build independently
- External URL demo shows partial externalUrl content type functionality
- Remote DOM demo shows partial remote-dom content type functionality
- The Server demo shows a full MCP server implementation with Cloudflare
- The Ruby and Typescript server demos show basic MCP server implementations
- WC-demo showcases the web components client implementation
- Always test example builds after making SDK changes

### Documentation Updates
- Documentation uses VitePress with enhanced styling
- Edit files in `docs/src/` directory
- Test changes with `pnpm docs:dev` before building
- Always build docs to check for errors: `pnpm docs:build`

## Troubleshooting

### Common Issues
- **TypeScript version warnings:** Current setup uses TypeScript 5.8.3 with ESLint plugins that support <5.4.0. This is expected and working.
- **Ruby permission errors:** Use `sudo bundle install` and `sudo bundle exec` for Ruby commands in CI environment.
- **Build failures:** Always run `pnpm install` first, then check individual package builds.
- **Test failures:** Check if all dependencies are installed and built before running tests.

### CI/CD Pipeline
- CI runs on Node.js 22.x with pnpm 10
- Separate jobs for TypeScript and Ruby testing
- Path filtering prevents unnecessary builds
- Semantic release handles versioning and publishing

### Performance Notes
- TypeScript builds are fast (~15 seconds total)
- Ruby tests run very quickly (~1 second)
- Documentation builds may take longer (~17 seconds)
- Full CI pipeline completes in under 5 minutes

## CRITICAL REMINDERS
- **NEVER CANCEL builds or long-running commands** - Always set appropriate timeouts
- **Always validate changes** with complete build and test cycle
- **Test examples** after SDK changes to ensure compatibility
- **Run linting and formatting** before committing changes
- **Update documentation** when adding or changing features
- **Use workspace commands** from root directory for consistency


================================================
FILE: .github/workflows/ci.yml
================================================
name: CI

on:
  push:
    branches:
      - main
      - alpha
  pull_request:
    branches:
      - main
      - alpha
  release:
    types: [published]

jobs:
  filter_changed_paths:
    runs-on: ubuntu-latest
    outputs:
      ts_client_files: ${{ steps.filter.outputs.ts_client_files }}
      ts_server_files: ${{ steps.filter.outputs.ts_server_files }}
      ruby_sdk_files: ${{ steps.filter.outputs.ruby_sdk_files }}
      python_sdk_files: ${{ steps.filter.outputs.python_sdk_files }}
      example_files: ${{ steps.filter.outputs.example_files }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: dorny/paths-filter@v2
        id: filter
        with:
          base: ${{ github.event_name == 'push' && github.event.before || github.base_ref }}
          filters: |
            ts_client_files:
              - 'sdks/typescript/client/**'
            ts_server_files:
              - 'sdks/typescript/server/**'
            ruby_sdk_files:
              - 'sdks/ruby/**'
            python_sdk_files:
              - 'sdks/python/**'
            example_files:
              - 'examples/**'

  js_build_and_test:
    needs: filter_changed_paths
    if: needs.filter_changed_paths.outputs.ts_client_files == 'true' || needs.filter_changed_paths.outputs.ts_server_files == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup pnpm
        uses: pnpm/action-setup@v2
        with:
          version: 10

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22.x
          cache: 'pnpm'

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Lint
        run: pnpm lint

      - name: Test
        run: pnpm test:ts

      - name: Build
        run: pnpm build

  ruby_sdk_test:
    needs: filter_changed_paths
    if: needs.filter_changed_paths.outputs.ruby_sdk_files == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup pnpm
        uses: pnpm/action-setup@v2
        with:
          version: 10

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22.x
          cache: 'pnpm'

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Set up Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.2'
          bundler: latest
          bundler-cache: true
          working-directory: 'sdks/ruby'

      - name: Lint
        run: bundle exec rubocop
        working-directory: 'sdks/ruby'

      - name: Run tests
        run: pnpm test:ruby

  python_sdk_test:
    needs: filter_changed_paths
    if: needs.filter_changed_paths.outputs.python_sdk_files == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Set up uv
        uses: astral-sh/setup-uv@v3
        with:
          enable-cache: true

      - name: Install dependencies
        run: uv sync --dev
        working-directory: sdks/python/server

      - name: Lint with ruff
        run: uv run ruff check
        working-directory: sdks/python/server

      - name: Type check with pyright
        run: uv run pyright
        working-directory: sdks/python/server

      - name: Run tests
        run: uv run pytest
        working-directory: sdks/python/server

      - name: Build package
        run: uv build
        working-directory: sdks/python/server

  release_ts_client:
    needs: [js_build_and_test, filter_changed_paths]
    if: (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/alpha') && needs.filter_changed_paths.outputs.ts_client_files == 'true'
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write # to be able to comment on released pull requests
      issues: write
      id-token: write
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - name: Fetch all tags
        run: git fetch --tags --force
      - name: Setup pnpm
        uses: pnpm/action-setup@v2
        with: { version: 10 }
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with: { node-version: 22.x, cache: 'pnpm' }
      - name: Install dependencies
        run: pnpm install --frozen-lockfile
      - name: Release
        working-directory: sdks/typescript/client
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: npx semantic-release

  release_ts_server:
    needs: [js_build_and_test, release_ts_client, filter_changed_paths]
    if: >
      always() &&
      (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/alpha') &&
      needs.filter_changed_paths.outputs.ts_server_files == 'true' &&
      needs.js_build_and_test.result == 'success'
    runs-on: ubuntu-latest
    permissions:
      contents: write
      issues: write
      pull-requests: write
      id-token: write
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - name: Pull latest changes
        run: git pull --rebase origin ${{ github.ref_name }}
      - name: Fetch all tags
        run: git fetch --tags --force
      - name: Setup pnpm
        uses: pnpm/action-setup@v2
        with: { version: 10 }
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with: { node-version: 22.x, cache: 'pnpm' }
      - name: Install dependencies
        run: pnpm install --frozen-lockfile
      - name: Release
        working-directory: sdks/typescript/server
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: npx semantic-release

  release_ruby_sdk:
    name: Release Ruby SDK
    needs: [ruby_sdk_test, filter_changed_paths, release_ts_server]
    if: >
      always() &&
      (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/alpha') &&
      needs.filter_changed_paths.outputs.ruby_sdk_files == 'true' &&
      needs.ruby_sdk_test.result == 'success'
    runs-on: ubuntu-latest
    environment: release
    permissions:
      contents: write # to push commits and tags
      id-token: write # for trusted publishing
      issues: write # to comment on issues
      pull-requests: write # to comment on pull requests
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - name: Pull latest changes
        run: git pull --rebase origin ${{ github.ref_name }}
      - name: Setup pnpm
        uses: pnpm/action-setup@v2
        with: { version: 10 }
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with: { node-version: 22.x, cache: 'pnpm' }
      - name: Install dependencies
        run: pnpm install --frozen-lockfile
      - name: Set up Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.2'
          bundler: latest
          bundler-cache: true
          working-directory: sdks/ruby
      - name: Configure RubyGems Credentials
        uses: rubygems/configure-rubygems-credentials@main
      - name: Release
        working-directory: sdks/ruby
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: npx semantic-release

  release_python_sdk:
    name: Release Python SDK
    needs: [python_sdk_test, filter_changed_paths, release_ruby_sdk]
    if: >
      always() &&
      (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/alpha') &&
      needs.filter_changed_paths.outputs.python_sdk_files == 'true' &&
      needs.python_sdk_test.result == 'success'
    runs-on: ubuntu-latest
    environment: release
    permissions:
      contents: write # to push commits and tags
      id-token: write # for trusted publishing to PyPI
      issues: write # to comment on issues
      pull-requests: write # to comment on pull requests
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - name: Pull latest changes
        run: git pull --rebase origin ${{ github.ref_name }}
      - name: Fetch all tags
        run: git fetch --tags --force
      - name: Setup pnpm
        uses: pnpm/action-setup@v2
        with: { version: 10 }
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with: { node-version: 22.x, cache: 'pnpm' }
      - name: Install dependencies
        run: pnpm install --frozen-lockfile
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - name: Set up uv
        uses: astral-sh/setup-uv@v3
        with:
          enable-cache: true
      - name: Install Python dependencies
        run: uv sync --dev
        working-directory: sdks/python/server
      - name: Release
        working-directory: sdks/python/server
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: npx semantic-release


================================================
FILE: .github/workflows/deploy-docs.yml
================================================
#
name: Deploy VitePress site to Pages

on:
  # Runs on pushes targeting the `main` branch. Change this to `master` if you\'re
  # using the `master` branch as the default branch.
  push:
    branches: [main]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Not needed if lastUpdated is not enabled
      - name: Use pnpm
        uses: pnpm/action-setup@v3
        with:
          version: 10 # Specify pnpm version from package.json
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'
      - name: Setup Pages
        uses: actions/configure-pages@v4
      - name: Install dependencies
        run: pnpm install
      - name: Build with VitePress
        run: pnpm docs:build # This script is \'vitepress build docs\'
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          # Path to the output directory of 'vitepress build docs/src'
          path: docs/src/.vitepress/dist

  # Deployment job
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    needs: build
    runs-on: ubuntu-latest
    name: Deploy
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4


================================================
FILE: .gitignore
================================================
# Logs
logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*
lerna-debug.log*

# Diagnostic reports (https://nodejs.org/api/report.html)
report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json

# Runtime data
pids
*.pid
*.seed
*.pid.lock

examples/server/build

# Directory for instrumented libs generated by jscoverage/JSCover
lib-cov

# Coverage directory used by tools like istanbul
coverage
*.lcov

# nyc test coverage
.nyc_output

# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
.grunt

# Bower dependency directory (https://bower.io/)
bower_components

# node-waf configuration
.lock-wscript

# Compiled binary addons (https://nodejs.org/api/addons.html)
build/Release

# Dependency directories
node_modules/
jspm_packages/

# Snowpack dependency directory (https://snowpack.dev/)
web_modules/

# PNPM
.pnpm-store/

# TypeScript cache
*.tsbuildinfo

# Optional npm cache directory
.npm

# Optional eslint cache
.eslintcache

# Microbundle cache
.rpt2_cache/
.rts2_cache_cjs/
.rts2_cache_es/
.rts2_cache_umd/

# Optional REPL history
.node_repl_history

# Output of 'npm pack'
*.tgz

# Yarn Integrity file
.yarnclean

# dotenv environment variables file
.env
.env.development.local
.env.test.local
.env.production.local
.env.local

# Serverless directories
.serverless/

# FuseBox cache
.fusebox/

# DynamoDB Local files
DynamoDBLocal_lib/

# TernJS port file
.tern-port

# Stores VSCode versions used for testing VSCode extensions
.vscode-test

# yarn v2
.yarn/cache
.yarn/unplugged
.yarn/build-state.yml
.yarn/install-state.gz
.pnp.*

# Parcel cache files
.cache
.parcel-cache

# Next.js build output
.next
out

# Nuxt.js build output
.nuxt

# Svelte build output
.svelte-kit

# Docusaurus build output
.docusaurus

# Gatsby cache
.cache/


# Vite build output
dist

# VitePress
docs/src/.vitepress/dist
docs/.vitepress/cache
docs/src/.vitepress/cache

# Monorepo specific
/sdks/**/dist
/sdks/**/coverage
/examples/**/dist
/examples/**/coverage

# OS generated files #
######################
.DS_Store
.DS_Store?
._*
.Spotlight-V100
.Trashes
ehthumbs.db
Thumbs.db

# IDEs and Editors #
####################

# VSCode
.vscode/*
!.vscode/settings.json
!.vscode/tasks.json
!.vscode/launch.json
!.vscode/extensions.json
*.code-workspace

# JetBrains
.idea/
*.iws
*.iml
*.ipr

# Sublime Text
*.sublime-project
*.sublime-workspace

# Compilation artifacts
#######################
*.o
*.obj
*.exe
*.dll
*.so
*.dylib

# C/C++ specific
*.gch
*.pch

# Python specific
__pycache__/
*.py[cod]
*$py.class

# Environment variables
.env*
!.env.example

# Husky
.husky/_/
.husky/.gitignore

# Auto-generated files
adapter-runtime.bundled.ts

================================================
FILE: .prettierignore
================================================
# Ignore artifacts:
node_modules
dist
build
coverage
venv

# Ignore package manager files (if you commit them)
package-lock.json
yarn.lock
pnpm-lock.yaml

# Ignore specific configuration files if managed elsewhere or intentionally unformatted
# .vscode/
# .idea/

# Ignore generated/bundled files
*.generated.*
*.bundled.ts
docs/src/.vitepress/cache
extensions/vscode/out

*.log
*.md 

================================================
FILE: .prettierrc.json
================================================
{
  "semi": true,
  "trailingComma": "all",
  "singleQuote": true,
  "printWidth": 100,
  "tabWidth": 2,
  "plugins": ["prettier-plugin-tailwindcss"]
}


================================================
FILE: .releaserc.json
================================================
{
  "branches": [
    "main",
    {
      "name": "alpha",
      "prerelease": true
    }
  ],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    [
      "@semantic-release/npm",
      {
        "pkgRoot": "sdks/typescript/client",
        "npmPublish": true
      }
    ],
    [
      "@semantic-release/npm",
      {
        "pkgRoot": "sdks/typescript/server",
        "npmPublish": true
      }
    ],
    [
      "@semantic-release/npm",
      {
        "npmPublish": false
      }
    ],
    [
      "@semantic-release/exec",
      {
        "prepareCmd": "pnpm install --lockfile-only --ignore-scripts"
      }
    ],
    [
      "@semantic-release/git",
      {
        "assets": [
          "CHANGELOG.md",
          "package.json",
          "sdks/typescript/client/package.json",
          "sdks/typescript/server/package.json",
          "pnpm-lock.yaml"
        ],
        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
      }
    ],
    "@semantic-release/github"
  ]
}


================================================
FILE: .ruby-version
================================================
3.2.2


================================================
FILE: CHANGELOG.md
================================================
# [5.2.0](https://github.com/idosal/mcp-ui/compare/v5.1.2...v5.2.0) (2025-07-18)


### Features

* support generic messages response ([#35](https://github.com/idosal/mcp-ui/issues/35)) ([10b407b](https://github.com/idosal/mcp-ui/commit/10b407b279b3ee9608ef077445f4d714f88343c5))

## [5.1.2](https://github.com/idosal/mcp-ui/compare/v5.1.1...v5.1.2) (2025-07-18)


### Bug Fixes

* use targetOrigin in the proxy message relay ([#40](https://github.com/idosal/mcp-ui/issues/40)) ([b3fb54e](https://github.com/idosal/mcp-ui/commit/b3fb54e28ca7b8eeda896b5bcf478b6343dbba47))

## [5.1.1](https://github.com/idosal/mcp-ui/compare/v5.1.0...v5.1.1) (2025-07-18)


### Bug Fixes

* add a bridge to pass messages in and out of the proxy ([#38](https://github.com/idosal/mcp-ui/issues/38)) ([30ccac0](https://github.com/idosal/mcp-ui/commit/30ccac0706ad8e02ebcd8960924ed1d58ddedf85))

# [5.1.0](https://github.com/idosal/mcp-ui/compare/v5.0.0...v5.1.0) (2025-07-18)


### Features

* add proxy option to externalUrl ([#37](https://github.com/idosal/mcp-ui/issues/37)) ([7b95cd0](https://github.com/idosal/mcp-ui/commit/7b95cd0b3873fc1cde28748ec463e81c6ff1c494))

# [5.0.0](https://github.com/idosal/mcp-ui/compare/v4.1.4...v5.0.0) (2025-07-17)


### Bug Fixes

* rename delivery -> encoding and flavor -> framework ([#36](https://github.com/idosal/mcp-ui/issues/36)) ([9a509ed](https://github.com/idosal/mcp-ui/commit/9a509ed80d051b0a8042b36958b401a0a7c1e138))


### BREAKING CHANGES

* The existing naming is ambiguous. Renaming delivery to encoding and flavor to framework should clarify the intent.

## [4.1.4](https://github.com/idosal/mcp-ui/compare/v4.1.3...v4.1.4) (2025-07-16)


### Bug Fixes

* pass ref explicitly using iframeProps ([#33](https://github.com/idosal/mcp-ui/issues/33)) ([d01b5d1](https://github.com/idosal/mcp-ui/commit/d01b5d1e4cdaedc436ba2fa8984d866d93d59087))

## [4.1.3](https://github.com/idosal/mcp-ui/compare/v4.1.2...v4.1.3) (2025-07-15)


### Bug Fixes

* ref passing to UIResourceRenderer ([#32](https://github.com/idosal/mcp-ui/issues/32)) ([d28c23f](https://github.com/idosal/mcp-ui/commit/d28c23f9b8ee320f4e361200ae02a23f0d2a1c0c))

## [4.1.2](https://github.com/idosal/mcp-ui/compare/v4.1.1...v4.1.2) (2025-07-10)


### Bug Fixes

* validate URL ([b7c994d](https://github.com/idosal/mcp-ui/commit/b7c994dfdd947b3dfbb903fc8cb896d61004c8d8))

## [4.1.1](https://github.com/idosal/mcp-ui/compare/v4.1.0...v4.1.1) (2025-07-06)


### Bug Fixes

* text and blob support in RemoteDOM resources ([ec68eb9](https://github.com/idosal/mcp-ui/commit/ec68eb90df984da8b492cc25eafdafdeda79f299))

# [4.1.0](https://github.com/idosal/mcp-ui/compare/v4.0.0...v4.1.0) (2025-07-05)


### Features

* separate html and remote-dom props ([#24](https://github.com/idosal/mcp-ui/issues/24)) ([a7f0529](https://github.com/idosal/mcp-ui/commit/a7f05299dc9cc40184f9ab25c5b648ee7077be64))

# [4.0.0](https://github.com/idosal/mcp-ui/compare/v3.0.0...v4.0.0) (2025-07-05)


### Bug Fixes

* rename components and methods to fit new scope ([#22](https://github.com/idosal/mcp-ui/issues/22)) ([6bab1fe](https://github.com/idosal/mcp-ui/commit/6bab1fe3a168a18e7ba4762e23478abf4e0cc84c))


### BREAKING CHANGES

* exported names have changed

# [3.0.0](https://github.com/idosal/mcp-ui/compare/v2.5.1...v3.0.0) (2025-07-04)


### Features

* switch to UiResourceRenderer ([#21](https://github.com/idosal/mcp-ui/issues/21)) ([6fe3166](https://github.com/idosal/mcp-ui/commit/6fe316682675e27db914d60696754677e3783448))


### BREAKING CHANGES

* removed deprecated client API

## [2.5.1](https://github.com/idosal/mcp-ui/compare/v2.5.0...v2.5.1) (2025-06-28)


### Bug Fixes

* export RemoteDomResource ([2b86f2d](https://github.com/idosal/mcp-ui/commit/2b86f2dd4506de49c69908e23d84a2a323170446))
* export UiResourceRenderer and HtmlResource ([2b841a5](https://github.com/idosal/mcp-ui/commit/2b841a556c1111ed70ccb3d3987afd21fe7df897))

# [2.5.0](https://github.com/idosal/mcp-ui/compare/v2.4.0...v2.5.0) (2025-06-27)


### Features

* add remote-dom content type ([#18](https://github.com/idosal/mcp-ui/issues/18)) ([5dacf37](https://github.com/idosal/mcp-ui/commit/5dacf37c22b5ee6ae795049a8d573fc073b8a1f5))

# [2.4.0](https://github.com/idosal/mcp-ui/compare/v2.3.3...v2.4.0) (2025-06-20)


### Features

* **client:** allow setting supportedContentTypes for HtmlResource ([#17](https://github.com/idosal/mcp-ui/issues/17)) ([e009ef1](https://github.com/idosal/mcp-ui/commit/e009ef10010134ba3d9893314cc4d8e1274f1f07))

## [2.3.3](https://github.com/idosal/mcp-ui/compare/v2.3.2...v2.3.3) (2025-06-19)


### Bug Fixes

* typescript types to be compatible with MCP SDK ([#10](https://github.com/idosal/mcp-ui/issues/10)) ([74365d7](https://github.com/idosal/mcp-ui/commit/74365d7ed6422beef6cd9ee0f5a97c847bd9827b))

## [2.3.2](https://github.com/idosal/mcp-ui/compare/v2.3.1...v2.3.2) (2025-06-14)


### Bug Fixes

* trigger release ([aaca831](https://github.com/idosal/mcp-ui/commit/aaca83125c3f7825ccdebf0f04f8553e953c5249))

## [2.3.1](https://github.com/idosal/mcp-ui/compare/v2.3.0...v2.3.1) (2025-06-14)


### Bug Fixes

* iframe handle ([#15](https://github.com/idosal/mcp-ui/issues/15)) ([66bd4fd](https://github.com/idosal/mcp-ui/commit/66bd4fd3d04f82e3e4557f064e701b68e1d8af11))

# [2.3.0](https://github.com/idosal/mcp-ui/compare/v2.2.0...v2.3.0) (2025-06-13)


### Features

* pass iframe props down ([#14](https://github.com/idosal/mcp-ui/issues/14)) ([112539d](https://github.com/idosal/mcp-ui/commit/112539d28640a96e8375a6b416f2ba559370b312))

# [2.2.0](https://github.com/idosal/mcp-ui/compare/v2.1.0...v2.2.0) (2025-06-03)


### Features

* support ui action result types ([#6](https://github.com/idosal/mcp-ui/issues/6)) ([899d152](https://github.com/idosal/mcp-ui/commit/899d1527286a281a23fbb8f3a207d435dfc3fe96))

# [2.1.0](https://github.com/idosal/mcp-ui/compare/v2.0.0...v2.1.0) (2025-05-31)


### Features

* consolidate ui:// and ui-app:// ([#8](https://github.com/idosal/mcp-ui/issues/8)) ([2e08035](https://github.com/idosal/mcp-ui/commit/2e08035676bb6a46ef3c94dba916bc895f1fa3cc))

# [2.0.0](https://github.com/idosal/mcp-ui/compare/v1.1.0...v2.0.0) (2025-05-23)


### Documentation

* bump ([#4](https://github.com/idosal/mcp-ui/issues/4)) ([ad4d163](https://github.com/idosal/mcp-ui/commit/ad4d1632cc1f9c99072349a8f0cdaac343236132))


### BREAKING CHANGES

* (previous one didn't take due to semantic-release misalignment)

# [1.1.0](https://github.com/idosal/mcp-ui/compare/v1.0.7...v1.1.0) (2025-05-16)


### Bug Fixes

* update deps ([4091ef4](https://github.com/idosal/mcp-ui/commit/4091ef47da048fab3c4feb002f5287b2ff295744))


### Features

* change onGenericMcpAction to optional onUiAction ([1913b59](https://github.com/idosal/mcp-ui/commit/1913b5977c30811f9e67659949e2d961f2eda983))

## [1.0.7](https://github.com/idosal/mcp-ui/compare/v1.0.6...v1.0.7) (2025-05-16)


### Bug Fixes

* **client:** specify iframe ([fd0b70a](https://github.com/idosal/mcp-ui/commit/fd0b70a84948d3aa5d7a79269ff7c3bcd0946689))

## [1.0.6](https://github.com/idosal/mcp-ui/compare/v1.0.5...v1.0.6) (2025-05-16)


### Bug Fixes

* support react-router ([21ffb95](https://github.com/idosal/mcp-ui/commit/21ffb95fe6d77a348b95b38dbf3741ba6442894e))

## [1.0.5](https://github.com/idosal/mcp-ui/compare/v1.0.4...v1.0.5) (2025-05-16)


### Bug Fixes

* **client:** styling ([6ff9b68](https://github.com/idosal/mcp-ui/commit/6ff9b685fd1be770fd103943e45275e9ec86905c))

## [1.0.4](https://github.com/idosal/mcp-ui/compare/v1.0.3...v1.0.4) (2025-05-16)


### Bug Fixes

* packaging ([9e6babd](https://github.com/idosal/mcp-ui/commit/9e6babd3a587213452ea7aec4cc9ae3a50fa1965))

## [1.0.3](https://github.com/idosal/mcp-ui/compare/v1.0.2...v1.0.3) (2025-05-16)


### Bug Fixes

* exports ([3a93a16](https://github.com/idosal/mcp-ui/commit/3a93a16e1b7438ba7b2ef49ca854479f755abcc6))

## [1.0.2](https://github.com/idosal/mcp-ui/compare/v1.0.1...v1.0.2) (2025-05-16)


### Bug Fixes

* remove shared dependency ([e66e8f4](https://github.com/idosal/mcp-ui/commit/e66e8f49b1ba46090db6e4682060488566f4fe41))

## [1.0.1](https://github.com/idosal/mcp-ui/compare/v1.0.0...v1.0.1) (2025-05-16)


### Bug Fixes

* publish ([0943e7a](https://github.com/idosal/mcp-ui/commit/0943e7acaf17f32aae085c2313bfbec47bc59f1f))

# 1.0.0 (2025-05-16)


### Bug Fixes

* dependencies ([887f61f](https://github.com/idosal/mcp-ui/commit/887f61f827b4585c17493d4fa2dfb251ea598587))
* lint ([4487820](https://github.com/idosal/mcp-ui/commit/44878203a71c3c9173d463b809be36769e996ba9))
* lint ([d0a91f9](https://github.com/idosal/mcp-ui/commit/d0a91f9a07ec0042690240c3d8d0bad620f8c765))
* package config ([8dc1e53](https://github.com/idosal/mcp-ui/commit/8dc1e5358c3c8e641206a5e6851427d360cc1955))


================================================
FILE: CODE_OF_CONDUCT.md
================================================
# Contributor Covenant Code of Conduct

## Our Pledge

We as members, contributors, and leaders pledge to make participation in our
community a harassment-free experience for everyone, regardless of age, body
size, visible or invisible disability, ethnicity, sex characteristics, gender
identity and expression, level of experience, education, socio-economic status,
nationality, personal appearance, race, religion, or sexual identity
and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming,
diverse, inclusive, and healthy community.

## Our Standards

Examples of behavior that contributes to a positive environment for our
community include:

* Demonstrating empathy and kindness toward other people
* Being respectful of differing opinions, viewpoints, and experiences
* Giving and gracefully accepting constructive feedback
* Accepting responsibility and apologizing to those affected by our mistakes,
  and learning from the experience
* Focusing on what is best not just for us as individuals, but for the
  overall community

Examples of unacceptable behavior include:

* The use of sexualized language or imagery, and sexual attention or
  advances of any kind
* Trolling, insulting or derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or email
  address, without their explicit permission
* Other conduct which could reasonably be considered inappropriate in a
  professional setting

## Enforcement Responsibilities

Community leaders are responsible for clarifying and enforcing our standards of
acceptable behavior and will take appropriate and fair corrective action in
response to any behavior that they deem inappropriate, threatening, offensive,
or harmful.

Community leaders have the right and responsibility to remove, edit, or reject
comments, commits, code, wiki edits, issues, and other contributions that are
not aligned to this Code of Conduct, and will communicate reasons for moderation
decisions when appropriate.

## Scope

This Code of Conduct applies within all community spaces, and also applies when
an individual is officially representing the community in public spaces.
Examples of representing our community include using an official e-mail address,
posting via an official social media account, or acting as an appointed
representative at an online or offline event.

## Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported to the community leaders responsible for enforcement at
idosalomon@gmail.com.
All complaints will be reviewed and investigated promptly and fairly.

All community leaders are obligated to respect the privacy and security of the
reporter of any incident.

## Enforcement Guidelines

Community leaders will follow these Community Impact Guidelines in determining
the consequences for any action they deem in violation of this Code of Conduct:

### 1. Correction

**Community Impact**: Use of inappropriate language or other behavior deemed
unprofessional or unwelcome in the community.

**Consequence**: A private, written warning from community leaders, providing
clarity around the nature of the violation and an explanation of why the
behavior was inappropriate. A public apology may be requested.

### 2. Warning

**Community Impact**: A violation through a single incident or series
of actions.

**Consequence**: A warning with consequences for continued behavior. No
interaction with the people involved, including unsolicited interaction with
those enforcing the Code of Conduct, for a specified period of time. This
includes avoiding interactions in community spaces as well as external channels
like social media. Violating these terms may lead to a temporary or
permanent ban.

### 3. Temporary Ban

**Community Impact**: A serious violation of community standards, including
sustained inappropriate behavior.

**Consequence**: A temporary ban from any sort of interaction or public
communication with the community for a specified period of time. No public or
private interaction with the people involved, including unsolicited interaction
with those enforcing the Code of Conduct, is allowed during this period.
Violating these terms may lead to a permanent ban.

### 4. Permanent Ban

**Community Impact**: Demonstrating a pattern of violation of community
standards, including sustained inappropriate behavior,  harassment of an
individual, or aggression toward or disparagement of classes of individuals.

**Consequence**: A permanent ban from any sort of public interaction within
the community.

## Attribution

This Code of Conduct is adapted from the [Contributor Covenant][homepage],
version 2.0, available at
https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.

Community Impact Guidelines were inspired by [Mozilla's code of conduct
enforcement ladder](https://github.com/mozilla/diversity).

[homepage]: https://www.contributor-covenant.org

For answers to common questions about this code of conduct, see the FAQ at
https://www.contributor-covenant.org/faq. Translations are available at
https://www.contributor-covenant.org/translations.


================================================
FILE: LICENSE
================================================
                                 Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/

   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

   1. Definitions.

      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.

      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.

      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      "control" means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.

      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.

      "Source" form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.

      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.

      "Work" shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below).

      "Derivative Works" shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.

      "Contribution" shall mean any work of authorship, including
      the original version of the Work and any modifications or additions
      to that Work or Derivative Works thereof, that is intentionally
      submitted to Licensor for inclusion in the Work by the copyright owner
      or by an individual or Legal Entity authorized to submit on behalf of
      the copyright owner. For the purposes of this definition, "submitted"
      means any form of electronic, verbal, or written communication sent
      to the Licensor or its representatives, including but not limited to
      communication on electronic mailing lists, source code control systems,
      and issue tracking systems that are managed by, or on behalf of, the
      Licensor for the purpose of discussing and improving the Work, but
      excluding communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as "Not a Contribution."

      "Contributor" shall mean Licensor and any individual or Legal Entity
      on behalf of whom a Contribution has been received by Licensor and
      subsequently incorporated within the Work.

   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.

   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a
      cross-claim or counterclaim in a lawsuit) alleging that the Work
      or a Contribution incorporated within the Work constitutes direct
      or contributory patent infringement, then any patent licenses
      granted to You under this License for that Work shall terminate
      as of the date such litigation is filed.

   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:

      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and

      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and

      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and

      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, then any Derivative Works that You distribute must
          include a readable copy of the attribution notices contained
          within such NOTICE file, excluding those notices that do not
          pertain to any part of the Derivative Works, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.

      You may add Your own copyright statement to Your modifications and
      may provide additional or different license terms and conditions
      for use, reproduction, or distribution of Your modifications, or
      for any such Derivative Works as a whole, provided Your use,
      reproduction, and distribution of the Work otherwise complies with
      the conditions stated in this License.

   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to the Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.

   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.

   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.

   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or consequential damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or any and all
      other commercial damages or losses), even if such Contributor
      has been advised of the possibility of such damages.

   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.

   END OF TERMS AND CONDITIONS

   APPENDIX: How to apply the Apache License to your work.

      To apply the Apache License to your work, attach the following
      boilerplate notice, with the fields enclosed by brackets "[]"
      replaced with your own identifying information. (Don't include
      the brackets!)  The text should be enclosed in the appropriate
      comment syntax for the file format. We also recommend that a
      file or class name and description of purpose be included on the
      same "printed page" as the copyright notice for easier
      identification within third-party archives.

   Copyright 2025 Ido Salomon

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.


================================================
FILE: README.md
================================================
## 📦 Model Context Protocol UI SDK

<p align="center">
  <img width="250" alt="image" src="https://github.com/user-attachments/assets/65b9698f-990f-4846-9b2d-88de91d53d4d" />
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@mcp-ui/server"><img src="https://img.shields.io/npm/v/@mcp-ui/server?label=server&color=green" alt="Server Version"></a>
  <a href="https://www.npmjs.com/package/@mcp-ui/client"><img src="https://img.shields.io/npm/v/@mcp-ui/client?label=client&color=blue" alt="Client Version"></a>
  <a href="https://rubygems.org/gems/mcp_ui_server"><img src="https://img.shields.io/gem/v/mcp_ui_server" alt="Ruby Server SDK Version"></a>
  <a href="https://pypi.org/project/mcp-ui-server/"><img src="https://img.shields.io/pypi/v/mcp-ui-server?label=python&color=yellow" alt="Python Server SDK Version"></a>
  <a href="https://discord.gg/CEAG4KW7ZH"><img src="https://img.shields.io/discord/1401195140436983879?logo=discord&label=discord" alt="Discord"></a>
  <a href="https://gitmcp.io/idosal/mcp-ui"><img src="https://img.shields.io/endpoint?url=https://gitmcp.io/badge/idosal/mcp-ui" alt="MCP Documentation"></a>
</p>

<p align="center">
  <a href="#-whats-mcp-ui">What's mcp-ui?</a> •
  <a href="#-core-concepts">Core Concepts</a> •
  <a href="#-installation">Installation</a> •
  <a href="#-getting-started">Getting Started</a> •
  <a href="#-walkthrough">Walkthrough</a> •
  <a href="#-examples">Examples</a> •
  <a href="#-supported-hosts">Supported Hosts</a> •
  <a href="#-security">Security</a> •
  <a href="#-roadmap">Roadmap</a> •
  <a href="#-contributing">Contributing</a> •
  <a href="#-license">License</a>
</p>

----

**`mcp-ui`** pioneered the concept of interactive UI over [MCP](https://modelcontextprotocol.io/introduction), enabling rich web interfaces for AI tools. Alongside Apps SDK, the patterns developed here directly influenced the [MCP Apps](https://github.com/modelcontextprotocol/ext-apps) specification, which standardized UI delivery over the protocol.

The `@mcp-ui/*` packages implement the MCP Apps standard. `@mcp-ui/client` is the recommended SDK for MCP Apps Hosts.

> *The @mcp-ui/* packages are fully compliant with the MCP Apps specification and ready for production use.*

<p align="center">
  <video src="https://github.com/user-attachments/assets/7180c822-2dd9-4f38-9d3e-b67679509483"></video>
</p>

## 💡 What's `mcp-ui`?

`mcp-ui` is an SDK implementing the [MCP Apps](https://github.com/modelcontextprotocol/ext-apps) standard for UI over MCP. It provides:

* **`@mcp-ui/server` (TypeScript)**: Create UI resources with `createUIResource`. Works with `registerAppTool` and `registerAppResource` from `@modelcontextprotocol/ext-apps/server`.
* **`@mcp-ui/client` (TypeScript)**: Render tool UIs with `AppRenderer` (MCP Apps) or `UIResourceRenderer` (legacy MCP-UI hosts).
* **`mcp_ui_server` (Ruby)**: Create UI resources in Ruby.
* **`mcp-ui-server` (Python)**: Create UI resources in Python.

The MCP Apps pattern links tools to their UIs via `_meta.ui.resourceUri`. Hosts fetch and render the UI alongside tool results.

## ✨ Core Concepts

### MCP Apps Pattern (Recommended)

The MCP Apps standard links tools to their UIs via `_meta.ui.resourceUri`:

```ts
import { registerAppTool, registerAppResource } from '@modelcontextprotocol/ext-apps/server';
import { createUIResource } from '@mcp-ui/server';

// 1. Create UI resource
const widgetUI = await createUIResource({
  uri: 'ui://my-server/widget',
  content: { type: 'rawHtml', htmlString: '<h1>Widget</h1>' },
  encoding: 'text',
});

// 2. Register resource handler
registerAppResource(server, 'widget_ui', widgetUI.resource.uri, {}, async () => ({
  contents: [widgetUI.resource]
}));

// 3. Register tool with _meta linking
registerAppTool(server, 'show_widget', {
  description: 'Show widget',
  inputSchema: { query: z.string() },
  _meta: { ui: { resourceUri: widgetUI.resource.uri } }  // Links tool → UI
}, async ({ query }) => {
  return { content: [{ type: 'text', text: `Query: ${query}` }] };
});
```

Hosts detect `_meta.ui.resourceUri`, fetch the UI via `resources/read`, and render it with `AppRenderer`.

### UIResource (Wire Format)

The underlying payload for UI content:

```ts
interface UIResource {
  type: 'resource';
  resource: {
    uri: string;       // e.g., ui://component/id
    mimeType: 'text/html;profile=mcp-app';
    text?: string;      // HTML content
    blob?: string;      // Base64-encoded HTML content
  };
}
```

* **`uri`**: Unique identifier using `ui://` scheme
* **`mimeType`**: `text/html;profile=mcp-app` — the MCP Apps standard MIME type
* **`text` vs. `blob`**: Plain text or Base64-encoded content

### Client Components

#### AppRenderer (MCP Apps)

For MCP Apps hosts, use `AppRenderer` to render tool UIs:

```tsx
import { AppRenderer } from '@mcp-ui/client';

function ToolUI({ client, toolName, toolInput, toolResult }) {
  return (
    <AppRenderer
      client={client}
      toolName={toolName}
      sandbox={{ url: sandboxUrl }}
      toolInput={toolInput}
      toolResult={toolResult}
      onOpenLink={async ({ url }) => window.open(url)}
      onMessage={async (params) => console.log('Message:', params)}
    />
  );
}
```

Key props:
- **`client`**: Optional MCP client for automatic resource fetching
- **`toolName`**: Tool name to render UI for
- **`sandbox`**: Sandbox configuration with proxy URL
- **`toolInput`** / **`toolResult`**: Tool arguments and results
- **`onOpenLink`** / **`onMessage`**: Handlers for UI requests

#### UIResourceRenderer (Legacy MCP-UI)

For legacy hosts that embed resources in tool responses:

```tsx
import { UIResourceRenderer } from '@mcp-ui/client';

<UIResourceRenderer
  resource={mcpResource.resource}
  onUIAction={(action) => console.log('Action:', action)}
/>
```

Props:
- **`resource`**: Resource object with `uri`, `mimeType`, and content (`text`/`blob`)
- **`onUIAction`**: Callback for handling tool, prompt, link, notify, and intent actions

Also available as a Web Component:
```html
<ui-resource-renderer
  resource='{ "mimeType": "text/html", "text": "<h2>Hello!</h2>" }'
></ui-resource-renderer>
```

### Supported Resource Types

#### HTML (`text/html;profile=mcp-app`)

Rendered using the internal `<HTMLResourceRenderer />` component, which displays content inside an `<iframe>`. This is suitable for self-contained HTML.

*   **`mimeType`**: `text/html;profile=mcp-app` (MCP Apps standard)

### UI Action

UI snippets must be able to interact with the agent. In `mcp-ui`, this is done by hooking into events sent from the UI snippet and reacting to them in the host (see `onUIAction` prop). For example, an HTML may trigger a tool call when a button is clicked by sending an event which will be caught handled by the client.


### Platform Adapters

MCP-UI SDKs includes adapter support for host-specific implementations, enabling your open MCP-UI widgets to work seamlessly regardless of host. Adapters automatically translate between MCP-UI's `postMessage` protocol and host-specific APIs. Over time, as hosts become compatible with the open spec, these adapters wouldn't be needed.

#### Available Adapters

##### Apps SDK Adapter

For Apps SDK environments (e.g., ChatGPT), this adapter translates MCP-UI protocol to Apps SDK API calls (e.g., `window.openai`).

**How it Works:**
- Intercepts MCP-UI `postMessage` calls from your widgets
- Translates them to appropriate Apps SDK API calls
- Handles bidirectional communication (tools, prompts, state management)
- Works transparently - your existing MCP-UI code continues to work without changes

**Usage:**

```ts
import { createUIResource } from '@mcp-ui/server';

const htmlResource = await createUIResource({
  uri: 'ui://greeting/1',
  content: {
    type: 'rawHtml',
    htmlString: `
      <button onclick="window.parent.postMessage({ type: 'tool', payload: { toolName: 'myTool', params: {} } }, '*')">
        Call Tool
      </button>
    `
  },
  encoding: 'text',
});
```


## 🏗️ Installation

### TypeScript

```bash
# using npm
npm install @mcp-ui/server @mcp-ui/client

# or pnpm
pnpm add @mcp-ui/server @mcp-ui/client

# or yarn
yarn add @mcp-ui/server @mcp-ui/client
```

### Ruby

```bash
gem install mcp_ui_server
```

### Python

```bash
# using pip
pip install mcp-ui-server

# or uv
uv add mcp-ui-server
```

## 🚀 Getting Started

You can use [GitMCP](https://gitmcp.io/idosal/mcp-ui) to give your IDE access to `mcp-ui`'s latest documentation!

### TypeScript (MCP Apps Pattern)

1. **Server-side**: Create a tool with UI using `_meta.ui.resourceUri`

   ```ts
   import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
   import { registerAppTool, registerAppResource } from '@modelcontextprotocol/ext-apps/server';
   import { createUIResource } from '@mcp-ui/server';
   import { z } from 'zod';

   const server = new McpServer({ name: 'my-server', version: '1.0.0' });

   // Create UI resource
   const widgetUI = await createUIResource({
     uri: 'ui://my-server/widget',
     content: { type: 'rawHtml', htmlString: '<h1>Interactive Widget</h1>' },
     encoding: 'text',
   });

   // Register resource handler
   registerAppResource(server, 'widget_ui', widgetUI.resource.uri, {}, async () => ({
     contents: [widgetUI.resource]
   }));

   // Register tool with _meta linking
   registerAppTool(server, 'show_widget', {
     description: 'Show widget',
     inputSchema: { query: z.string() },
     _meta: { ui: { resourceUri: widgetUI.resource.uri } }
   }, async ({ query }) => {
     return { content: [{ type: 'text', text: `Query: ${query}` }] };
   });
   ```

2. **Client-side**: Render tool UIs with `AppRenderer`

   ```tsx
   import { AppRenderer } from '@mcp-ui/client';

   function ToolUI({ client, toolName, toolInput, toolResult }) {
     return (
       <AppRenderer
         client={client}
         toolName={toolName}
         sandbox={{ url: sandboxUrl }}
         toolInput={toolInput}
         toolResult={toolResult}
         onOpenLink={async ({ url }) => window.open(url)}
         onMessage={async (params) => console.log('Message:', params)}
       />
     );
   }
   ```

### Legacy MCP-UI Pattern

For hosts that don't support MCP Apps yet:

   ```tsx
   import { UIResourceRenderer } from '@mcp-ui/client';

   <UIResourceRenderer
     resource={mcpResource.resource}
     onUIAction={(action) => console.log('Action:', action)}
   />
   ```

### Python

**Server-side**: Build your UI resources

   ```python
   from mcp_ui_server import create_ui_resource

   # Inline HTML
   html_resource = create_ui_resource({
     "uri": "ui://greeting/1",
     "content": { "type": "rawHtml", "htmlString": "<p>Hello, from Python!</p>" },
     "encoding": "text",
   })

   # External URL
   external_url_resource = create_ui_resource({
     "uri": "ui://greeting/2",
     "content": { "type": "externalUrl", "iframeUrl": "https://example.com" },
     "encoding": "text",
   })
   ```

### Ruby

**Server-side**: Build your UI resources

   ```ruby
   require 'mcp_ui_server'

   # Inline HTML
   html_resource = McpUiServer.create_ui_resource(
     uri: 'ui://greeting/1',
     content: { type: :raw_html, htmlString: '<p>Hello, from Ruby!</p>' },
     encoding: :text
   )

   # External URL
   external_url_resource = McpUiServer.create_ui_resource(
     uri: 'ui://greeting/2',
     content: { type: :external_url, iframeUrl: 'https://example.com' },
     encoding: :text
   )

   # remote-dom
   remote_dom_resource = McpUiServer.create_ui_resource(
     uri: 'ui://remote-component/action-button',
     content: {
       type: :remote_dom,
       script: "
        const button = document.createElement('ui-button');
        button.setAttribute('label', 'Click me from Ruby!');
        button.addEventListener('press', () => {
          window.parent.postMessage({ type: 'tool', payload: { toolName: 'uiInteraction', params: { action: 'button-click', from: 'ruby-remote-dom' } } }, '*');
        });
        root.appendChild(button);
        ",
       framework: :react,
     },
     encoding: :text
   )
   ```

## 🚶 Walkthrough

For a detailed, simple, step-by-step guide on how to integrate `mcp-ui` into your own server, check out the full server walkthroughs on the [mcp-ui documentation site](https://mcpui.dev):

- **[TypeScript Server Walkthrough](https://mcpui.dev/guide/server/typescript/walkthrough)**
- **[Ruby Server Walkthrough](https://mcpui.dev/guide/server/ruby/walkthrough)**
- **[Python Server Walkthrough](https://mcpui.dev/guide/server/python/walkthrough)**

These guides will show you how to add a `mcp-ui` endpoint to an existing server, create tools that return UI resources, and test your setup with the `ui-inspector`!

## 🌍 Examples

**Client Examples**
* [Goose](https://github.com/block/goose) - open source AI agent that supports `mcp-ui`.
* [LibreChat](https://github.com/danny-avila/LibreChat) - enhanced ChatGPT clone that supports `mcp-ui`.
* [ui-inspector](https://github.com/idosal/ui-inspector) - inspect local `mcp-ui`-enabled servers.
* [MCP-UI Chat](https://github.com/idosal/scira-mcp-ui-chat) - interactive chat built with the `mcp-ui` client. Check out the [hosted version](https://scira-mcp-chat-git-main-idosals-projects.vercel.app/)!
* MCP-UI RemoteDOM Playground (`examples/remote-dom-demo`) - local demo app to test RemoteDOM resources
* MCP-UI Web Component Demo (`examples/wc-demo`) - local demo app to test the Web Component integration in hosts

**Server Examples**
* **TypeScript**: A [full-featured server](examples/server) that is deployed to a hosted environment for easy testing.
  * **[`typescript-server-demo`](./examples/typescript-server-demo)**: A simple Typescript server that demonstrates how to generate UI resources.
  * **server**: A [full-featured Typescript server](examples/server) that is deployed to a hosted Cloudflare environment for easy testing.
    * **HTTP Streaming**: `https://remote-mcp-server-authless.idosalomon.workers.dev/mcp`
    * **SSE**: `https://remote-mcp-server-authless.idosalomon.workers.dev/sse`
* **Ruby**: A barebones [demo server](/examples/ruby-server-demo) that shows how to use `mcp_ui_server` and `mcp` gems together.
* **Python**: A simple [demo server](/examples/python-server-demo) that shows how to use the `mcp-ui-server` Python package.
* [XMCP](https://github.com/basementstudio/xmcp/tree/main/examples/mcp-ui) - Typescript MCP framework with `mcp-ui` starter example.

Drop those URLs into any MCP-compatible host to see `mcp-ui` in action. For a supported local inspector, see the [ui-inspector](https://github.com/idosal/ui-inspector).

## 💻 Supported Hosts

The `@mcp-ui/*` packages work with both MCP Apps hosts and legacy MCP-UI hosts.

### MCP Apps Hosts

These hosts implement the [MCP Apps specification](https://github.com/modelcontextprotocol/ext-apps) and support tools with `_meta.ui.resourceUri`:

| Host | Notes |
| :--- | :---- |
| [Claude](https://www.claude.ai/) | ✅ | ✅ |
| [VSCode](https://github.com/microsoft/vscode/issues/260218) | |
| [Postman](https://www.postman.com/) | |
| [Goose](https://block.github.io/goose/) | |
| [MCPJam](https://www.mcpjam.com/) | |
| [LibreChat](https://www.librechat.ai/) | |
| [mcp-use](https://mcp-use.com/) | |
| [Smithery](https://smithery.ai/playground) | |

### Legacy MCP-UI Hosts

These hosts expect UI resources embedded directly in tool responses:

| Host | Rendering | UI Actions | Notes |
| :--- | :-------: | :--------: | :---- |
| [Nanobot](https://www.nanobot.ai/) | ✅ | ✅ |
| [MCPJam](https://www.mcpjam.com/) | ✅ | ✅ |
| [Postman](https://www.postman.com/) | ✅ | ⚠️ | |
| [Goose](https://block.github.io/goose/) | ✅ | ⚠️ | |
| [LibreChat](https://www.librechat.ai/) | ✅ | ⚠️ | |
| [Smithery](https://smithery.ai/playground) | ✅ | ❌ | |
| [fast-agent](https://fast-agent.ai/mcp/mcp-ui/) | ✅ | ❌ | |

### Hosts Requiring Adapters

| Host | Protocol | Notes |
| :--- | :------: | :---- |
| [ChatGPT](https://chatgpt.com/) | Apps SDK | [Guide](https://mcpui.dev/guide/apps-sdk) |

**Legend:** ✅ Supported · ⚠️ Partial · ❌ Not yet supported

## 🔒 Security
Host and user security is one of `mcp-ui`'s primary concerns. In all content types, the remote code is executed in a sandboxed iframe.

## 🛣️ Roadmap

- [X] Add online playground
- [X] Expand UI Action API (beyond tool calls)
- [X] Support Web Components
- [X] Support Remote-DOM
- [ ] Add component libraries (in progress)
- [ ] Add SDKs for additional programming languages (in progress; Ruby, Python available)
- [ ] Support additional frontend frameworks
- [ ] Explore providing a UI SDK (in addition to the client and server one)
- [ ] Add declarative UI content type
- [ ] Support generative UI?
      
## Core Team
`mcp-ui` is a project by [Ido Salomon](https://x.com/idosal1), in collaboration with [Liad Yosef](https://x.com/liadyosef).

## 🤝 Contributing

Contributions, ideas, and bug reports are welcome! See the [contribution guidelines](https://github.com/idosal/mcp-ui/blob/main/.github/CONTRIBUTING.md) to get started.

## 📄 License

Apache License 2.0 © [The MCP-UI Authors](LICENSE)

## Disclaimer

This project is provided "as is", without warranty of any kind. The `mcp-ui` authors and contributors shall not be held liable for any damages, losses, or issues arising from the use of this software. Use at your own risk.


================================================
FILE: SECURITY.md
================================================
# Security Policy

MCP-UI is committed to maintaining the highest security standards, and actively works with web security experts to improve the spec and implementations. We welcome disclosures, suggestions, and feedback that can improve it.

## Disclosing an Issue

Please report any issues using this private [form](https://forms.gle/6WbAJU7m2LSxfY6K6). All disclosures will be handled as soon as possible.


================================================
FILE: docs/README.md
================================================
# MCP-UI Documentation

This directory contains the enhanced documentation for MCP UI, built with VitePress and featuring a professional, modern design.

## 🎨 Design Enhancements

The documentation has been significantly improved with:

### Visual Design
- **Modern Color Scheme**: Blue to green gradient branding with excellent contrast
- **Professional Typography**: Inter font family with proper font weights and spacing
- **Enhanced Shadows**: Subtle depth and visual hierarchy
- **Smooth Animations**: Fade-in effects and hover transitions
- **Responsive Design**: Mobile-first approach with breakpoint optimizations

### Content Improvements
- **Video Integration**: Demo video from README prominently featured on landing page
- **Rich Feature Cards**: Six detailed feature cards with icons and descriptions
- **Code Examples**: Syntax-highlighted examples with proper formatting
- **Call-to-Action Buttons**: Professional buttons with hover effects
- **Better Navigation**: Improved sidebar with collapsible sections

### Technical Features
- **Local Search**: Built-in search functionality
- **Dark Mode**: Full dark mode support with proper color schemes
- **SEO Optimization**: Meta tags, OpenGraph, and Twitter cards
- **Performance**: Optimized loading and rendering
- **Accessibility**: Proper ARIA labels and keyboard navigation

## 🚀 Getting Started

To run the documentation locally:

```bash
cd docs
npm install
npm run dev
```

To build for production:

```bash
npm run build
```

## 📁 Structure

```
docs/
├── src/
│   ├── .vitepress/
│   │   ├── config.ts          # VitePress configuration
│   │   └── theme/
│   │       ├── index.ts       # Custom theme setup
│   │       └── custom.css     # Enhanced styling
│   ├── guide/                 # Documentation pages
│   ├── public/                # Static assets
│   │   ├── logo.svg          # Brand logo
│   │   └── favicon.png       # Site favicon
│   └── index.md              # Enhanced landing page
└── README.md                 # This file
```

## 🎯 Key Features

### Landing Page
- Hero section with gradient text and compelling tagline
- Demo video integration from the main README
- Six feature cards highlighting key capabilities
- Code examples showing quick usage
- Call-to-action buttons linking to guides and demos

### Navigation
- Clean, organized sidebar with collapsible sections
- Breadcrumb navigation
- "Edit on GitHub" links
- Social media links (GitHub, npm)

### Content
- Professional typography with proper hierarchy
- Enhanced code blocks with syntax highlighting
- Improved tables with hover effects
- Styled blockquotes and badges
- Responsive images and media

### Performance
- Optimized bundle size
- Fast loading times
- Efficient caching
- Mobile-optimized assets

## 🔧 Customization

The documentation uses CSS custom properties for easy theming:

```css
:root {
  --vp-c-brand-1: #3c82f6;      /* Primary brand color */
  --vp-c-brand-2: #2563eb;      /* Secondary brand color */
  --vp-c-accent-1: #10b981;     /* Accent color */
  /* ... more variables */
}
```

## 📝 Content Guidelines

When adding new content:

1. Use proper markdown headers (##, ###) for structure
2. Include code examples with language tags
3. Add screenshots or diagrams where helpful
4. Keep paragraphs concise and scannable
5. Use callouts for important information

## 🤝 Contributing

To contribute to the documentation:

1. Edit files in the `src/` directory
2. Test locally with `npm run dev`
3. Build with `npm run build` to verify
4. Submit a pull request

The documentation automatically rebuilds on changes to the main branch. 

================================================
FILE: docs/package.json
================================================
{
  "name": "@mcp-ui/docs",
  "version": "0.1.0",
  "private": false,
  "type": "module",
  "scripts": {
    "dev": "vitepress dev src",
    "build": "vitepress build src",
    "preview": "vitepress preview src"
  },
  "devDependencies": {
    "mermaid": "^11.9.0",
    "vitepress": "^1.0.0-rc.44",
    "vitepress-plugin-mermaid": "^2.0.17",
    "vue": "^3.3.0"
  }
}


================================================
FILE: docs/src/.vitepress/config.ts
================================================
import { defineConfig } from 'vitepress';
import { withMermaid } from 'vitepress-plugin-mermaid';

export default withMermaid(
  defineConfig({
    lang: 'en-US',
    title: 'MCP-UI',
    description: 'Interactive UI for MCP - Build rich, dynamic interfaces with MCP-UI',
    base: '/',
    cleanUrls: true,

    head: [
      ['meta', { name: 'theme-color', content: '#3c82f6' }],
      ['meta', { name: 'og:type', content: 'website' }],
      ['meta', { name: 'og:locale', content: 'en' }],
      [
        'meta',
        {
          name: 'og:title',
          content: 'MCP-UI | Interactive UI for MCP',
        },
      ],
      ['meta', { name: 'og:site_name', content: 'MCP-UI' }],
      ['meta', { name: 'og:image', content: 'https://mcpui.dev/og-image.png' }],
      ['meta', { name: 'og:url', content: 'https://mcpui.dev/' }],
      ['meta', { name: 'twitter:card', content: 'summary_large_image' }],
      ['meta', { name: 'twitter:site', content: '@idosal1' }],
      ['meta', { name: 'twitter:url', content: 'https://mcpui.dev/' }],
      ['meta', { name: 'twitter:domain', content: 'mcpui.dev' }],
      ['meta', { name: 'twitter:image', content: 'https://mcpui.dev/og-image.png' }],
      [
        'meta',
        {
          name: 'twitter:description',
          content: 'Interactive UI for MCP - Build rich, dynamic interfaces with MCP-UI',
        },
      ],
      ['link', { rel: 'icon', type: 'image/png', href: '/logo.png' }],
      ['link', { rel: 'icon', type: 'image/png', href: '/favicon.png' }],
      [
        'style',
        {},
        `.VPNavBar .VPNavBarSocialLinks a[href*="npmjs.com/package/@mcp-ui/server"] { border-left: 1px solid var(--vp-c-divider); margin-left: 8px; padding-left: 12px; }`,
      ],
    ],

    vite: {
      plugins: [],
      optimizeDeps: {
        include: ['vue', '@vue/shared', 'dayjs', 'mermaid'],
      },
    },

    themeConfig: {
      logo: {
        light: '/logo-black.png',
        dark: '/logo.png',
        alt: 'MCP-UI Logo',
      },

      nav: [
        { text: 'Home', link: '/' },
        { text: 'Guide', link: '/guide/introduction' },
        { text: 'Team', link: '/team' },
        {
          text: 'Examples',
          items: [
            {
              text: 'UI Inspector',
              link: 'https://github.com/idosal/ui-inspector',
            },
            {
              text: 'Server Examples',
              items: [
                {
                  text: 'TypeScript',
                  link: '/guide/server/typescript/usage-examples',
                },
                { text: 'Ruby', link: '/guide/server/ruby/usage-examples' },
                { text: 'Python', link: '/guide/server/python/usage-examples' },
              ],
            },
            {
              text: 'Client Examples',
              items: [
                { text: 'Overview', link: '/guide/client/overview' },
              ],
            },
          ],
        },
        {
          text: 'Packages',
          items: [
            {
              text: '@mcp-ui/client',
              link: 'https://www.npmjs.com/package/@mcp-ui/client',
            },
            {
              text: '@mcp-ui/server',
              link: 'https://www.npmjs.com/package/@mcp-ui/server',
            },
            {
              text: 'mcp_ui_server Gem',
              link: 'https://rubygems.org/gems/mcp_ui_server',
            },
            {
              text: 'mcp-ui-server (PyPI)',
              link: 'https://pypi.org/project/mcp-ui-server/',
            },
          ],
        },
      ],

      sidebar: {
        '/guide/': [
          {
            text: 'Getting Started',
            items: [
              { text: 'Introduction', link: '/guide/introduction' },
              { text: 'Installation', link: '/guide/getting-started' },
              { text: 'Core Concepts', link: '/guide/protocol-details' },
              { text: 'Embeddable UI', link: '/guide/embeddable-ui' },
              { text: 'Supported Hosts', link: '/guide/supported-hosts' },
            ],
          },
          {
            text: 'Protocol Integrations',
            collapsed: false,
            items: [
              { text: 'MCP Apps', link: '/guide/mcp-apps' },
              { text: 'Apps SDK (ChatGPT)', link: '/guide/apps-sdk' },
            ],
          },
          {
            text: 'Server SDKs',
            collapsed: false,
            items: [
              {
                text: 'TypeScript',
                collapsed: false,
                items: [
                  {
                    text: 'Overview',
                    link: '/guide/server/typescript/overview',
                  },
                  {
                    text: 'Walkthrough',
                    link: '/guide/server/typescript/walkthrough',
                  },
                  {
                    text: 'Usage & Examples',
                    link: '/guide/server/typescript/usage-examples',
                  },
                ],
              },
              {
                text: 'Ruby',
                collapsed: false,
                items: [
                  { text: 'Overview', link: '/guide/server/ruby/overview' },
                  {
                    text: 'Walkthrough',
                    link: '/guide/server/ruby/walkthrough',
                  },
                  {
                    text: 'Usage & Examples',
                    link: '/guide/server/ruby/usage-examples',
                  },
                ],
              },
              {
                text: 'Python',
                collapsed: false,
                items: [
                  { text: 'Overview', link: '/guide/server/python/overview' },
                  { text: 'Walkthrough', link: '/guide/server/python/walkthrough' },
                  { text: 'Usage & Examples', link: '/guide/server/python/usage-examples' },
                ],
              },
            ],
          },
          {
            text: 'Client SDK',
            collapsed: false,
            items: [
              { text: 'Overview', link: '/guide/client/overview' },
              { text: 'Walkthrough', link: '/guide/client/walkthrough' },
              {
                text: 'AppRenderer',
                link: '/guide/client/app-renderer',
              },
            ],
          },
        ],
      },

      editLink: {
        pattern: 'https://github.com/idosal/mcp-ui/edit/main/docs/src/:path',
        text: 'Edit this page on GitHub',
      },

      search: {
        provider: 'local',
        options: {
          locales: {
            root: {
              translations: {
                button: {
                  buttonText: 'Search',
                  buttonAriaLabel: 'Search',
                },
                modal: {
                  displayDetails: 'Display detailed list',
                  resetButtonTitle: 'Reset search',
                  backButtonTitle: 'Close search',
                  noResultsText: 'No results for',
                  footer: {
                    selectText: 'to select',
                    navigateText: 'to navigate',
                    closeText: 'to close',
                  },
                },
              },
            },
          },
        },
      },

      socialLinks: [
        { icon: 'github', link: 'https://github.com/idosal/mcp-ui' },
        { icon: 'discord', link: 'https://discord.gg/CEAG4KW7ZH' },
        {
          icon: 'npm',
          link: 'https://www.npmjs.com/package/@mcp-ui/server',
        },
        {
          icon: {
            svg: '<svg viewBox="0 0 256 293" xmlns="http://www.w3.org/2000/svg" preserveAspectRatio="xMinYMin meet"><g fill="currentColor"><path d="M76.748 97.434l-.163-.163-36.11 36.11 87.674 87.512 36.11-35.948 51.564-51.563-36.11-36.11v-.164H76.584l.163.326z"/><path d="M127.823.976L.135 74.173v146.395l127.688 73.197 127.689-73.197V74.173L127.823.976zm103.29 205.603l-103.29 59.534-103.29-59.534V87.837l103.29-59.534 103.29 59.534v118.742z"/></g></svg>',
          },
          link: 'https://rubygems.org/gems/mcp_ui_server',
        },
        {
          icon: 'pypi',
          link: 'https://pypi.org/project/mcp-ui-server/',
        },
      ],

      footer: {
        message:
          'Released under the <a href="https://github.com/idosal/mcp-ui/blob/main/LICENSE">Apache 2.0 License</a>.',
        copyright: 'Copyright © 2025-present <a href="https://github.com/idosal">Ido Salomon</a>',
      },

      lastUpdated: {
        text: 'Last updated',
        formatOptions: {
          dateStyle: 'short',
          timeStyle: 'medium',
        },
      },

      outline: {
        level: [2, 3],
        label: 'On this page',
      },

      docFooter: {
        prev: 'Previous page',
        next: 'Next page',
      },

      darkModeSwitchLabel: 'Appearance',
      lightModeSwitchTitle: 'Switch to light theme',
      darkModeSwitchTitle: 'Switch to dark theme',
      sidebarMenuLabel: 'Menu',
      returnToTopLabel: 'Return to top',
      langMenuLabel: 'Change language',

      externalLinkIcon: true,
    },

    markdown: {
      theme: {
        light: 'github-light',
        dark: 'github-dark',
      },
      lineNumbers: true,
      config: (md) => {
        // Add any markdown-it plugins here
      },
    },

    sitemap: {
      hostname: 'https://mcpui.dev',
    },

    // Mermaid configuration
    mermaid: {
      // Refer to https://mermaid.js.org/config/setup/modules/mermaidAPI.html#mermaidapi-configuration-defaults for options
      theme: 'default',
    },
    // Optional plugin configuration
    mermaidPlugin: {
      class: 'mermaid', // Set additional CSS classes for parent container
    },
  }),
);


================================================
FILE: docs/src/.vitepress/theme/custom.css
================================================
/**
 * Custom styles for MCP UI documentation
 * These styles enhance the default VitePress theme
 */

/* CSS Variables for consistent theming */
:root {
  --vp-c-brand-1: #3c82f6;
  --vp-c-brand-2: #2563eb;
  --vp-c-brand-3: #1d4ed8;
  --vp-c-brand-soft: rgba(60, 130, 246, 0.14);
  --vp-c-brand-softer: rgba(60, 130, 246, 0.08);

  /* Custom accent colors */
  --vp-c-accent-1: #10b981;
  --vp-c-accent-2: #059669;
  --vp-c-accent-soft: rgba(16, 185, 129, 0.14);

  /* Enhanced typography */
  --vp-font-family-base:
    'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu',
    'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif;
  --vp-font-family-mono: 'JetBrains Mono', 'Fira Code', 'Monaco', 'Menlo', 'Ubuntu Mono', monospace;

  /* Custom shadows */
  --vp-shadow-1: 0 1px 2px rgba(0, 0, 0, 0.04);
  --vp-shadow-2: 0 3px 12px rgba(0, 0, 0, 0.07);
  --vp-shadow-3: 0 12px 32px rgba(0, 0, 0, 0.1);
  --vp-shadow-4: 0 14px 44px rgba(0, 0, 0, 0.12);
  --vp-shadow-5: 0 18px 56px rgba(0, 0, 0, 0.16);

  /* Custom sidebar spacing */
  --vp-sidebar-width: 310px;
  --active-item-left-padding: 8px;
  --items-left-padding: 18px;
}

/* Dark mode adjustments */
.dark {
  --vp-c-brand-1: #60a5fa;
  --vp-c-brand-2: #3b82f6;
  --vp-c-brand-3: #2563eb;
  --vp-c-brand-soft: rgba(96, 165, 250, 0.16);
  --vp-c-brand-softer: rgba(96, 165, 250, 0.1);

  --vp-c-accent-1: #34d399;
  --vp-c-accent-2: #10b981;
  --vp-c-accent-soft: rgba(52, 211, 153, 0.16);
}

/* Fix top bar overlap - Enhanced hero section */
.VPHero {
  padding-top: 120px !important;
  padding-bottom: 64px !important;
}

.VPHome {
  margin-bottom: 16px !important;
}

.VPHero .container {
  margin-top: 0 !important;
}

.VPHero .name {
  background: linear-gradient(
    -45deg,
    #3b82f6 0%,
    #10b981 25%,
    #8b5cf6 50%,
    #3b82f6 75%,
    #10b981 100%
  );
  background-size: 400% 400%;
  -webkit-background-clip: text;
  -webkit-text-fill-color: transparent;
  background-clip: text;
  font-weight: 800;
  letter-spacing: -0.02em;
  animation: gradientShift 10s ease-in-out infinite;
}

.VPHero .text {
  font-weight: 600;
  letter-spacing: -0.01em;
}

.VPHero .tagline {
  font-size: 1.25rem;
  line-height: 1.6;
  color: var(--vp-c-text-2);
  max-width: 600px;
  margin: 0 auto;
}

/* Animated gradient keyframes */
@keyframes gradientShift {
  0%,
  100% {
    background-position: 0% 50%;
  }
  50% {
    background-position: 100% 50%;
  }
}

/* Animated gradient text utility class */
.animated-gradient-text {
  background: linear-gradient(
    -45deg,
    #3b82f6 0%,
    #10b981 25%,
    #8b5cf6 50%,
    #3b82f6 75%,
    #10b981 100%
  );
  background-size: 400% 400%;
  -webkit-background-clip: text;
  -webkit-text-fill-color: transparent;
  background-clip: text;
  animation: gradientShift 10s ease-in-out infinite;
}

/* Enhanced feature cards */
.VPFeatures {
  padding-top: 48px;
  padding-bottom: 48px;
}

.VPFeature {
  background: var(--vp-c-bg-soft);
  border: 1px solid var(--vp-c-divider);
  border-radius: 12px;
  padding: 28px;
  height: 100%;
  transition: all 0.3s ease;
  position: relative;
  overflow: hidden;
}

.VPFeature::before {
  content: '';
  position: absolute;
  top: 0;
  left: 0;
  right: 0;
  height: 3px;
  background: linear-gradient(90deg, var(--vp-c-brand-1), var(--vp-c-accent-1));
  opacity: 0;
  transition: opacity 0.3s ease;
}

.VPFeature:hover {
  border-color: var(--vp-c-brand-1);
  box-shadow: var(--vp-shadow-3);
  transform: translateY(-2px);
}

.VPFeature:hover::before {
  opacity: 1;
}

/* Fix feature card icons - target the correct VitePress classes */
.VPFeature .icon,
.VPFeature .VPImage,
.VPFeature .box .icon {
  font-size: 2.5rem !important;
  line-height: 1 !important;
  margin-bottom: 16px !important;
  display: block !important;
  text-align: center !important;
  width: 100% !important;
  height: auto !important;
}

/* Ensure emoji icons are properly sized */
.VPFeature .box .icon {
  font-size: 2.5rem !important;
  line-height: 1.2 !important;
  margin: 0 0 16px 0 !important;
  padding: 0 !important;
  position: static !important;
  top: auto !important;
  left: auto !important;
  transform: none !important;
}

.VPFeature .title {
  font-size: 1.25rem;
  font-weight: 600;
  margin-bottom: 12px;
  color: var(--vp-c-text-1);
}

.VPFeature .details {
  color: var(--vp-c-text-2);
  line-height: 1.6;
  font-size: 0.95rem;
}

/* Enhanced code blocks */
.vp-code-group {
  margin: 24px 0;
  border-radius: 12px;
  overflow: hidden;
  box-shadow: var(--vp-shadow-2);
}

div[class*='language-'] {
  border-radius: 8px;
  margin: 16px 0;
  overflow: hidden;
  box-shadow: var(--vp-shadow-2);
}

div[class*='language-'] pre {
  padding: 20px 24px;
  background: var(--vp-code-bg);
  overflow-x: auto;
}

div[class*='language-'] code {
  font-family: var(--vp-font-family-mono);
  font-size: 0.9em;
  line-height: 1.7;
}

/* Enhanced buttons and links */
.VPButton {
  border-radius: 8px;
  font-weight: 600;
  transition: all 0.3s ease;
  box-shadow: var(--vp-shadow-1);
}

.VPButton:hover {
  transform: translateY(-1px);
  box-shadow: var(--vp-shadow-2);
}

.VPButton.brand {
  background: linear-gradient(135deg, var(--vp-c-brand-1), var(--vp-c-brand-2));
  border: none;
}

.VPButton.brand:hover {
  background: linear-gradient(135deg, var(--vp-c-brand-2), var(--vp-c-brand-3));
}

/* Enhanced navigation */
.VPNavBar {
  backdrop-filter: blur(12px);
  background: rgba(255, 255, 255, 0.85);
  border-bottom: 1px solid var(--vp-c-divider);
  box-shadow: var(--vp-shadow-1);
}

.dark .VPNavBar {
  background: rgba(26, 26, 26, 0.85);
}

/* Enhanced sidebar */
.VPSidebar {
  background: var(--vp-c-bg-soft);
  border-right: 1px solid var(--vp-c-divider);
}

.VPSidebarItem[class*='level-']:not(.level-0) .items {
  padding-left: var(--items-left-padding) !important;
}

.VPSidebarItem.level-0 > .item > .link {
  font-weight: 600;
  color: var(--vp-c-text-1);
}

.VPSidebarItem.is-active > .item > .indicator {
  left: calc(calc(var(--items-left-padding) * -1) - 1px);
}

.VPSidebarItem.is-active > .item > .link {
  background: var(--vp-c-brand-soft);
  color: var(--vp-c-brand-1);
  border-radius: 6px;
  padding-left: var(--active-item-left-padding);
  margin-left: calc(var(--active-item-left-padding) * -1);
}

/* Enhanced content area */
.vp-doc h1 {
  font-size: 2.5rem;
  font-weight: 800;
  letter-spacing: -0.02em;
  line-height: 1.2;
  margin-bottom: 24px;
  margin-top: 24px;
  background: linear-gradient(135deg, var(--vp-c-text-1) 0%, var(--vp-c-brand-1) 100%);
  -webkit-background-clip: text;
  -webkit-text-fill-color: transparent;
  background-clip: text;
}

.vp-doc h2 {
  font-size: 1.875rem;
  font-weight: 700;
  margin-top: 12px;
  margin-bottom: 16px;
  padding-bottom: 8px;
  border-bottom: 2px solid var(--vp-c-divider);
}

.vp-doc h3 {
  font-size: 1.5rem;
  font-weight: 600;
  margin-top: 32px;
  margin-bottom: 12px;
  color: var(--vp-c-brand-1);
}

.vp-doc p {
  line-height: 1.7;
  margin: 16px 0;
}

.vp-doc a {
  color: var(--vp-c-brand-1);
  text-decoration: none;
  font-weight: 500;
  transition: all 0.2s ease;
}

.vp-doc a:hover {
  color: var(--vp-c-brand-2);
  text-decoration: underline;
}

/* Enhanced tables */
.vp-doc table {
  border-collapse: collapse;
  margin: 24px 0;
  width: 100%;
  border-radius: 8px;
  overflow: hidden;
  box-shadow: var(--vp-shadow-2);
}

.vp-doc th {
  background: var(--vp-c-bg-soft);
  font-weight: 600;
  padding: 16px;
  text-align: left;
  border-bottom: 2px solid var(--vp-c-divider);
}

.vp-doc td {
  padding: 12px 16px;
  border-bottom: 1px solid var(--vp-c-divider-light);
}

.vp-doc tr:hover {
  background: var(--vp-c-bg-softer);
}

/* Enhanced blockquotes */
.vp-doc blockquote {
  border-left: 4px solid var(--vp-c-brand-1);
  background: var(--vp-c-brand-softer);
  padding: 16px 20px;
  margin: 24px 0;
  border-radius: 0 8px 8px 0;
}

.vp-doc blockquote p {
  margin: 0;
  color: var(--vp-c-text-2);
  font-style: italic;
}

/* Enhanced badges */
.vp-doc .badge {
  display: inline-block;
  background: var(--vp-c-brand-soft);
  color: var(--vp-c-brand-1);
  padding: 4px 8px;
  border-radius: 4px;
  font-size: 0.8rem;
  font-weight: 600;
  margin-left: 8px;
}

/* Custom utility classes */
.text-gradient {
  background: linear-gradient(135deg, var(--vp-c-brand-1), var(--vp-c-accent-1));
  -webkit-background-clip: text;
  -webkit-text-fill-color: transparent;
  background-clip: text;
}

.card {
  background: var(--vp-c-bg-soft);
  border: 1px solid var(--vp-c-divider);
  border-radius: 12px;
  padding: 24px;
  margin: 16px 0;
  transition: all 0.3s ease;
}

.card:hover {
  border-color: var(--vp-c-brand-1);
  box-shadow: var(--vp-shadow-2);
}

/* Responsive improvements */
@media (max-width: 768px) {
  .VPHero {
    padding-top: 60px !important;
    padding-bottom: 48px !important;
  }

  .VPHero .name {
    font-size: 2.5rem;
  }

  .VPHero .text {
    font-size: 1.5rem;
  }

  .VPHero .tagline {
    font-size: 1.125rem;
  }

  .vp-doc h1 {
    font-size: 2rem;
  }

  .vp-doc h2 {
    font-size: 1.5rem;
  }

  .VPFeature {
    padding: 20px;
  }

  .VPFeature .icon,
  .VPFeature .VPImage,
  .VPFeature .box .icon {
    font-size: 2rem !important;
  }

  /* Responsive animated gradient text */
  .animated-gradient-text {
    font-size: 2.5rem !important;
    line-height: 1.1 !important;
    margin-bottom: 1.5rem !important;
  }
}

/* Animation enhancements */
@keyframes fadeInUp {
  from {
    opacity: 0;
    transform: translateY(20px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

.VPFeature {
  animation: fadeInUp 0.6s ease-out;
}

.VPFeature:nth-child(1) {
  animation-delay: 0.1s;
}
.VPFeature:nth-child(2) {
  animation-delay: 0.2s;
}
.VPFeature:nth-child(3) {
  animation-delay: 0.3s;
}
.VPFeature:nth-child(4) {
  animation-delay: 0.4s;
}
.VPFeature:nth-child(5) {
  animation-delay: 0.5s;
}
.VPFeature:nth-child(6) {
  animation-delay: 0.6s;
}

/* Announcement Banner */
.announcement-banner {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  color: white;
  text-align: center;
  padding: 12px 24px;
  font-size: 14px;
  font-weight: 500;
  line-height: 1.5;
  position: relative;
  z-index: 1;
  margin-bottom: 0;
  border-radius: 0 0 8px 8px; /* Rounded bottom corners just for style */
  width: 100%;
  max-width: 1152px; /* Match typical container width */
  margin-left: auto;
  margin-right: auto;
}

.announcement-banner a:hover {
  text-decoration: none !important;
  opacity: 0.9;
}

/* Adjust VPHero top padding when banner is present (Home page) */
.VPHome .VPHero {
  padding-top: 80px !important;
}

@media (max-width: 960px) {
  .VPHome .VPHero {
    padding-top: 64px !important;
  }

  /* Fix overlap by resetting layout shifts on image */
  .VPHome .VPHero .image,
  .VPHome .VPHero .image-container {
    margin-top: 0 !important;
    transform: none !important;
  }
}

@media (max-width: 768px) {
  .VPHome .VPHero {
    padding-top: 32px !important;
  }

  .announcement-banner {
    margin-bottom: 0;
  }
}

/* Fix hero image overlap on tablet/mobile by removing negative margin */
@media (max-width: 960px) {
  .VPHome .VPHero .image-container {
    margin-top: 0 !important;
  }
}


================================================
FILE: docs/src/.vitepress/theme/index.ts
================================================
import DefaultTheme from 'vitepress/theme';
import { h } from 'vue';
import type { Theme } from 'vitepress';
import './custom.css';

export default {
  extends: DefaultTheme,
  Layout() {
    return h(DefaultTheme.Layout, null, {
      'home-hero-before': () =>
        h('div', { class: 'announcement-banner' }, [
          h('span', '🎉 '),
          h('span', { style: 'font-weight: bold;' }, 'MCP-UI is now standardized into MCP Apps!'),
          h('span', ' '),
          h(
            'a',
            {
              href: 'https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1865',
              style: 'text-decoration: underline; color: inherit;',
            },
            'Learn more →',
          ),
        ]),
    });
  },
  enhanceApp({ app, router, siteData }) {
    // Custom app enhancements can go here
  },
} satisfies Theme;


================================================
FILE: docs/src/about.md
================================================
# About

## About

`mcp-ui` pioneered the concept of interactive UI over the [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP). When MCP was first introduced, tools could only return plain text responses. MCP-UI took the opportunity to transform how users interact with AI tools by enabling rich, dynamic interfaces delivered seamlessly through the protocol.

What started as an experimental project to bring web UIs to MCP tools has helped shape the ecosystem. The patterns we developed - embedding HTML resources in tool responses, secure sandboxed rendering, and bidirectional communication between UIs and hosts - directly influenced the creation of the [MCP Apps specification](https://github.com/modelcontextprotocol/ext-apps).

Today, `mcp-ui` implements the MCP Apps standard while continuing to push the boundaries of what's possible with UI over MCP. The `@mcp-ui/*` packages provide production-ready SDKs for both servers and clients, making it easy for developers to build interactive experiences for their MCP tools.

## What's Included

- **Client SDK** with React components for rendering tool UIs securely
- **Server SDKs** for TypeScript, Python, and Ruby to create UI resources
- **Documentation and examples** to help you get started quickly
- **Active community** pushing the MCP Apps standard forward

## Team

`mcp-ui` is a project by [Ido Salomon](https://x.com/idosal1), in collaboration with [Liad Yosef](https://x.com/liadyosef).

## Get Involved

- [GitHub Repository](https://github.com/idosal/mcp-ui)
- [Discord Community](https://discord.gg/CEAG4KW7ZH)


================================================
FILE: docs/src/guide/apps-sdk.md
================================================
# OpenAI Apps SDK Integration

::: warning ChatGPT-Specific
This page covers the **OpenAI Apps SDK** adapter for **ChatGPT** integration. This is separate from the **MCP Apps** standard.

- **MCP Apps**: The open standard for tool UIs (`_meta.ui.resourceUri`) - see [Getting Started](./getting-started)
- **Apps SDK**: ChatGPT's proprietary protocol (`openai/outputTemplate`) - covered on this page
:::

The Apps SDK adapter in `@mcp-ui/server` enables your MCP-UI HTML widget to run inside ChatGPT. However, for now, you still need to manually serve the resource according to the Apps SDK spec. This guide walks through the manual flow the adapter expects today to support both MCP-UI hosts and ChatGPT.

## Why two resources?

- **Static template for Apps SDK** – referenced from your tool descriptor via `_meta["openai/outputTemplate"]`. This version must enable the Apps SDK adapter so ChatGPT injects the bridge script and uses the `text/html+skybridge` MIME type.
- **Embedded resource in tool results** – returned each time your tool runs. This version should *not* enable the adapter so MCP-native hosts continue to receive standard MCP-UI HTML.

## Step-by-step walkthrough

### 1. Register the Apps SDK template

Use `createUIResource` with `adapters.appsSdk.enabled: true` and expose it through the MCP Resources API so both Apps SDK and traditional MCP hosts can fetch it.

```ts
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { createUIResource } from '@mcp-ui/server';

const server = new McpServer({ name: 'weather-bot', version: '1.0.0' });
const TEMPLATE_URI = 'ui://widgets/weather';

const appsSdkTemplate = await createUIResource({
  uri: TEMPLATE_URI,
  encoding: 'text',
  content: {
    type: 'rawHtml',
    htmlString: renderForecastWidget(),
  },
  metadata: {
    'openai/widgetDescription': widget.description,
    'openai/widgetPrefersBorder': true,
  },
});

server.registerResource(TEMPLATE_URI, async () => appsSdkTemplate.resource);
```

> **Note:** The adapter switches the MIME type to `text/html+skybridge` and injects the Apps bridge script automatically. The bridge translates MCP-UI primitives to Apps SDK compatible code so no HTML changes are required.

### Add Apps SDK widget metadata

Apps SDK surfaces a handful of `_meta` keys on the resource itself (description, CSP, borders, etc.). Provide them via the `metadata` option when you build the template so ChatGPT can present the widget correctly. For example:

```ts
const appsSdkTemplate = await createUIResource({
  uri: TEMPLATE_URI,
  encoding: 'text',
  content: {
    type: 'rawHtml',
    htmlString: renderForecastWidget(),
  },
  metadata: {
    'openai/widgetDescription': 'Interactive calculator',
    'openai/widgetCSP': {
      connect_domains: [],
      resource_domains: [],
    },
    'openai/widgetPrefersBorder': true,
  },
});
```

### 2. Reference the template in your tool descriptor

The Apps SDK looks for `_meta["openai/outputTemplate"]` to know which resource to render. Mirror the rest of the Apps-specific metadata you need (status text, accessibility hints, security schemes, etc.).

```ts
// Partial example (see Step 3 for complete example)
server.registerTool(
  'forecast',
  {
    title: 'Get the forecast',
    description: 'Returns a UI that displays the current weather.',
    inputSchema: {
      type: 'object',
      properties: { city: { type: 'string' } },
      required: ['city'],
    },
    _meta: {
      'openai/outputTemplate': TEMPLATE_URI,
      'openai/toolInvocation/invoking': 'Fetching forecast…',
      'openai/toolInvocation/invoked': 'Forecast ready',
      'openai/widgetAccessible': true,
    },
  },
  async ({ city }) => {
    const forecast = await fetchForecast(city);

    return {
      content: [
        {
          type: 'text',
          text: `Forecast prepared for ${city}.`,
        },
      ],
      structuredContent: {
        forecast,
      },
    };
  },
);
```

### 3. Add the MCP-UI embedded resource to the tool response

To support MCP-UI hosts, also return a standard `createUIResource` result (without the Apps adapter) alongside the Apps SDK payloads.

```ts
server.registerTool(
  'forecast',
  {
    title: 'Get the forecast',
    description: 'Returns a UI that displays the current weather.',
    inputSchema: {
      type: 'object',
      properties: { city: { type: 'string' } },
      required: ['city'],
    },
    _meta: {
      'openai/outputTemplate': TEMPLATE_URI,
      'openai/toolInvocation/invoking': 'Fetching forecast…',
      'openai/toolInvocation/invoked': 'Forecast ready',
      'openai/widgetAccessible': true,
    },
  },
  async ({ city }) => {
    const forecast = await fetchForecast(city);

    // MCP-UI embedded UI resource
    const uiResource = await createUIResource({
        uri: `ui://widgets/weather/${city}`,
        encoding: 'text',
        content: {
        type: 'rawHtml',
        htmlString: renderForecastWidget(forecast),
        },
    });

    return {
      content: [
        {
          type: 'text',
          text: `Forecast prepared for ${city}.`,
        },
        uiResource
      ],
      structuredContent: {
        forecast,
      },
    };
  },
);
```

> **Important:** The MCP-UI resource should **not** enable the Apps SDK adapter. It is for hosts that expect embedded resources. ChatGPT will ignore it and use the template registered in step 1 instead.

For the complete list of supported metadata fields, refer to the official documentation. [Apps SDK Reference](https://developers.openai.com/apps-sdk/reference)



================================================
FILE: docs/src/guide/client/app-renderer.md
================================================
# AppRenderer Component

`AppRenderer` is the recommended component for rendering MCP tool UIs in your host application. It implements the [MCP Apps](../mcp-apps) standard, handling the complete lifecycle: resource fetching, sandbox setup, JSON-RPC communication, and tool input/result delivery.

For lower-level control or when you already have HTML and an `AppBridge` instance, use [`AppFrame`](../mcp-apps#appframe-component) instead.

## Quick Example

```tsx
import { AppRenderer, type AppRendererHandle } from '@mcp-ui/client';

function ToolUI({ client, toolName, toolInput, toolResult }) {
  const appRef = useRef<AppRendererHandle>(null);

  return (
    <AppRenderer
      ref={appRef}
      client={client}
      toolName={toolName}
      sandbox={{ url: new URL('http://localhost:8765/sandbox_proxy.html') }}
      toolInput={toolInput}
      toolResult={toolResult}
      hostContext={{ theme: 'dark' }}
      onOpenLink={async ({ url }) => {
        window.open(url, '_blank');
        return {};
      }}
      onMessage={async (params) => {
        console.log('Message from tool UI:', params);
        return {};
      }}
      onError={(error) => console.error('Tool UI error:', error)}
    />
  );
}
```

## Props Reference

### Core Props

| Prop | Type | Description |
|------|------|-------------|
| `client` | `Client` | Optional MCP client for automatic resource fetching and MCP request forwarding. Omit to use custom handlers instead. |
| `toolName` | `string` | Name of the MCP tool to render UI for. |
| `sandbox` | `SandboxConfig` | Sandbox configuration with the proxy URL and optional CSP. |
| `html` | `string` | Optional pre-fetched HTML. If provided, skips all resource fetching. |
| `toolResourceUri` | `string` | Optional pre-fetched resource URI. If not provided, fetched via the client. |
| `toolInput` | `Record<string, unknown>` | Tool arguments to pass to the guest UI once it initializes. |
| `toolResult` | `CallToolResult` | Tool execution result to pass to the guest UI. |
| `toolInputPartial` | `object` | Partial/streaming tool input to send progressively. |
| `toolCancelled` | `boolean` | Set to `true` to notify the guest UI that tool execution was cancelled. |
| `hostContext` | `McpUiHostContext` | Host context (theme, locale, viewport, etc.) to pass to the guest UI. |

### Event Handlers

| Prop | Type | Description |
|------|------|-------------|
| `onOpenLink` | `(params, extra) => Promise<McpUiOpenLinkResult>` | Handler for open-link requests from the guest UI. |
| `onMessage` | `(params, extra) => Promise<McpUiMessageResult>` | Handler for message requests from the guest UI. |
| `onLoggingMessage` | `(params) => void` | Handler for logging messages from the guest UI. |
| `onSizeChanged` | `(params) => void` | Handler for size change notifications from the guest UI. |
| `onError` | `(error: Error) => void` | Callback invoked when an error occurs during setup or message handling. |
| `onFallbackRequest` | `(request, extra) => Promise<Record<string, unknown>>` | Catch-all for JSON-RPC requests not handled by built-in handlers. See [Handling Custom Requests](#handling-custom-requests). |

### MCP Request Handlers

These override the automatic forwarding to the MCP client when provided:

| Prop | Type | Description |
|------|------|-------------|
| `onCallTool` | `(params, extra) => Promise<CallToolResult>` | Handler for `tools/call` requests. |
| `onListResources` | `(params, extra) => Promise<ListResourcesResult>` | Handler for `resources/list` requests. |
| `onListResourceTemplates` | `(params, extra) => Promise<ListResourceTemplatesResult>` | Handler for `resources/templates/list` requests. |
| `onReadResource` | `(params, extra) => Promise<ReadResourceResult>` | Handler for `resources/read` requests. |
| `onListPrompts` | `(params, extra) => Promise<ListPromptsResult>` | Handler for `prompts/list` requests. |

### Ref Methods

Access via `useRef<AppRendererHandle>`:

| Method | Description |
|--------|-------------|
| `sendToolListChanged()` | Notify guest UI that the server's tool list has changed. |
| `sendResourceListChanged()` | Notify guest UI that the server's resource list has changed. |
| `sendPromptListChanged()` | Notify guest UI that the server's prompt list has changed. |
| `teardownResource()` | Notify the guest UI before unmounting (graceful shutdown). |

## Using Without an MCP Client

You can use `AppRenderer` without a full MCP client by providing custom handlers:

```tsx
<AppRenderer
  // No client - use callbacks instead
  toolName="my-tool"
  toolResourceUri="ui://my-server/my-tool"
  sandbox={{ url: sandboxUrl }}
  onReadResource={async ({ uri }) => {
    return myMcpProxy.readResource({ uri });
  }}
  onCallTool={async (params) => {
    return myMcpProxy.callTool(params);
  }}
/>
```

Or provide pre-fetched HTML directly:

```tsx
<AppRenderer
  toolName="my-tool"
  sandbox={{ url: sandboxUrl }}
  html={preloadedHtml}  // Skip all resource fetching
  toolInput={args}
/>
```

## Handling Custom Requests

AppRenderer includes built-in handlers for standard MCP Apps methods (`tools/call`, `ui/message`, `ui/open-link`, etc.). The `onFallbackRequest` prop lets you handle **any JSON-RPC request that doesn't match a built-in handler**. This is useful for:

- **Experimental methods** -- prototype new capabilities (e.g., `x/clipboard/write`, `x/analytics/track`)
- **MCP methods not yet in the Apps spec** -- support standard MCP methods like `sampling/createMessage` before they're officially added to MCP Apps

Under the hood, this is wired to `AppBridge`'s `fallbackRequestHandler` from the MCP SDK `Protocol` class. The guest UI sends a standard JSON-RPC request via `postMessage`, and if AppBridge has no registered handler for the method, it delegates to `onFallbackRequest`.

### Host-side handler

```tsx
import { AppRenderer, type JSONRPCRequest } from '@mcp-ui/client';
import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';

<AppRenderer
  client={client}
  toolName="my-tool"
  sandbox={sandboxConfig}
  onFallbackRequest={async (request, extra) => {
    switch (request.method) {
      case 'x/clipboard/write':
        await navigator.clipboard.writeText(request.params?.text as string);
        return { success: true };
      case 'sampling/createMessage':
        // Forward to MCP server
        return client.createMessage(request.params);
      default:
        throw new McpError(ErrorCode.MethodNotFound, `Unknown method: ${request.method}`);
    }
  }}
/>
```

### Guest-side (inside tool UI HTML)

```ts
import { sendExperimentalRequest } from '@mcp-ui/server';

// Send a custom request to the host -- returns a Promise with the response
const result = await sendExperimentalRequest('x/clipboard/write', { text: 'hello' });
```

The `sendExperimentalRequest` helper sends a properly formatted JSON-RPC request via `window.parent.postMessage`. The full request/response cycle flows through `PostMessageTransport` and the sandbox proxy, just like built-in methods.

::: tip Method Naming Convention
Use the `x/<namespace>/<action>` prefix for experimental methods (e.g., `x/clipboard/write`). Standard MCP methods not yet in the Apps spec (e.g., `sampling/createMessage`) should use their canonical method names. When an experimental method proves useful, it can be promoted to a standard method in the [ext-apps spec](https://github.com/modelcontextprotocol/ext-apps).
:::

## Sandbox Proxy

AppRenderer requires a sandbox proxy HTML file to be served. This provides security isolation for the guest UI by running it inside a double-iframe architecture. The sandbox proxy URL should point to a page that loads the MCP Apps sandbox proxy script.

See the [Client SDK Walkthrough](./walkthrough#_3-set-up-a-sandbox-proxy) for setup instructions.

## Related

- [Client SDK Walkthrough](./walkthrough) -- Step-by-step guide to building an MCP Apps client
- [MCP Apps Overview](../mcp-apps) -- Protocol details and server-side setup
- [Protocol Details](../protocol-details) -- Wire format reference
- [AppFrame Component](../mcp-apps#appframe-component) -- Lower-level rendering component


================================================
FILE: docs/src/guide/client/overview.md
================================================
# @mcp-ui/client Overview

The `@mcp-ui/client` package provides components for rendering MCP tool UIs in your host application using the MCP Apps standard.

## What's Included?

### MCP Apps Components
- **`<AppRenderer />`**: High-level component for MCP Apps hosts. Fetches resources, handles lifecycle, renders tool UIs.
- **`<AppFrame />`**: Lower-level component for when you have pre-fetched HTML and an AppBridge instance.
- **`AppBridge`**: Handles JSON-RPC communication between host and guest UI.

### Utility Functions
- **`getResourceMetadata(resource)`**: Extracts the resource's `_meta` content (standard MCP metadata)
- **`getUIResourceMetadata(resource)`**: Extracts only the MCP-UI specific metadata keys (prefixed with `mcpui.dev/ui-`) from the resource's `_meta` content
- **`isUIResource()`**: Utility function to check if content is a UI resource
- **`UI_EXTENSION_CAPABILITIES`**: Declares UI extension support for your MCP client

## Purpose
- **MCP Apps Compliance**: Implements the MCP Apps standard for UI over MCP
- **Simplified Rendering**: AppRenderer handles resource fetching, lifecycle, and rendering automatically
- **Security**: All UIs render in sandboxed iframes
- **Interactivity**: JSON-RPC communication between host and guest UI

## Quick Example: AppRenderer

```tsx
import { AppRenderer } from '@mcp-ui/client';

function ToolUI({ client, toolName, toolInput, toolResult }) {
  return (
    <AppRenderer
      client={client}
      toolName={toolName}
      sandbox={{ url: sandboxUrl }}
      toolInput={toolInput}
      toolResult={toolResult}
      onOpenLink={async ({ url }) => {
        if (url.startsWith('https://') || url.startsWith('http://')) {
          window.open(url);
        }
      }}
      onMessage={async (params) => console.log('Message:', params)}
    />
  );
}
```

## Building

This package uses Vite in library mode. It outputs ESM (`.mjs`) and UMD (`.js`) formats, plus TypeScript declarations (`.d.ts`). `react` is externalized.

To build just this package from the monorepo root:

```bash
pnpm build --filter @mcp-ui/client
```

## Utility Functions Reference

### `getResourceMetadata(resource)`

Extracts the standard MCP metadata from a resource's `_meta` property.

```typescript
import { getResourceMetadata } from '@mcp-ui/client';

const resource = {
  uri: 'ui://example/demo',
  mimeType: 'text/html',
  text: '<div>Hello</div>',
  _meta: {
    title: 'Demo Component',
    version: '1.0.0',
    'mcpui.dev/ui-preferred-frame-size': ['800px', '600px'],
    'mcpui.dev/ui-initial-render-data': { theme: 'dark' },
    author: 'Development Team'
  }
};

const metadata = getResourceMetadata(resource);
console.log(metadata);
// Output: {
//   title: 'Demo Component',
//   version: '1.0.0',
//   'mcpui.dev/ui-preferred-frame-size': ['800px', '600px'],
//   'mcpui.dev/ui-initial-render-data': { theme: 'dark' },
//   author: 'Development Team'
// }
```

### `getUIResourceMetadata(resource)`

Extracts only the MCP-UI specific metadata keys (those prefixed with `mcpui.dev/ui-`) from a resource's `_meta` property, with the prefixes removed for easier access.

```typescript
import { getUIResourceMetadata } from '@mcp-ui/client';

const resource = {
  uri: 'ui://example/demo',
  mimeType: 'text/html',
  text: '<div>Hello</div>',
  _meta: {
    title: 'Demo Component',
    version: '1.0.0',
    'mcpui.dev/ui-preferred-frame-size': ['800px', '600px'],
    'mcpui.dev/ui-initial-render-data': { theme: 'dark' },
    author: 'Development Team'
  }
};

const uiMetadata = getUIResourceMetadata(resource);
console.log(uiMetadata);
// Output: {
//   'preferred-frame-size': ['800px', '600px'],
//   'initial-render-data': { theme: 'dark' },
// }
```

## See More

See the following pages for more details:

- [Client SDK Walkthrough](./walkthrough.md) - **Step-by-step guide to building an MCP Apps client**
- [AppRenderer Component](./app-renderer.md) - **Full API reference for the MCP Apps renderer**


================================================
FILE: docs/src/guide/client/walkthrough.md
================================================
# Client SDK Walkthrough

This guide provides a step-by-step walkthrough for building an MCP Apps client that can render tool UIs using the `@mcp-ui/client` package.

For a complete example, see the [`mcp-apps-demo`](https://github.com/idosal/mcp-ui/tree/main/examples/mcp-apps-demo) (server) and test it with the [ui-inspector](https://github.com/idosal/ui-inspector) (client).

## Prerequisites

- Node.js (v18+)
- An MCP server with tools that have `_meta.ui.resourceUri` (see [Server Walkthrough](../server/typescript/walkthrough))
- A React project (this guide uses Vite)

## 1. Set up a React Project

If you don't have an existing React project, create one with Vite:

```bash
npm create vite@latest my-mcp-client -- --template react-ts
cd my-mcp-client
npm install
```

## 2. Install Dependencies

Install the MCP SDK, client package, and ext-apps:

```bash
npm install @mcp-ui/client @modelcontextprotocol/sdk @modelcontextprotocol/ext-apps
```

## 3. Set Up a Sandbox Proxy

MCP Apps renders tool UIs in sandboxed iframes for security. You need a sandbox proxy HTML file that will host the guest content. Create `public/sandbox_proxy.html`:

```html
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>Sandbox Proxy</title>
  <style>
    html, body { margin: 0; padding: 0; width: 100%; height: 100%; }
  </style>
</head>
<body>
  <script>
    // Sandbox proxy implementation for MCP Apps
    // This receives HTML content from the host and renders it securely

    // Listen for messages from the host
    window.addEventListener('message', (event) => {
      const data = event.data;
      if (!data || typeof data !== 'object') return;

      // Handle resource ready notification (HTML content to render)
      if (data.method === 'ui/notifications/sandbox-resource-ready') {
        const { html } = data.params || {};
        if (html) {
          // Replace the entire document with the received HTML
          document.open();
          document.write(html);
          document.close();
        }
      }
    });

    // Signal that the sandbox proxy is ready
    window.parent.postMessage({
      method: 'ui/notifications/sandbox-proxy-ready',
      params: {}
    }, '*');
  </script>
</body>
</html>
```

::: tip Production Setup
For production, consider implementing Content Security Policy (CSP) headers and additional security measures. See [@modelcontextprotocol/ext-apps](https://github.com/modelcontextprotocol/ext-apps) for more details on secure sandbox proxy implementation.
:::

## 4. Create an MCP Client

Create a file `src/mcp-client.ts` to handle the MCP connection:

```typescript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
import {
  type ClientCapabilitiesWithExtensions,
  UI_EXTENSION_CAPABILITIES,
} from '@mcp-ui/client';

export async function createMcpClient(serverUrl: string): Promise<Client> {
  // Create the client with UI extension capabilities
  const capabilities: ClientCapabilitiesWithExtensions = {
    roots: { listChanged: true },
    extensions: UI_EXTENSION_CAPABILITIES,
  };

  const client = new Client(
    { name: 'my-mcp-client', version: '1.0.0' },
    { capabilities }
  );

  // Connect to the MCP server
  const transport = new StreamableHTTPClientTransport(new URL(serverUrl));
  await client.connect(transport);

  console.log('Connected to MCP server');
  return client;
}
```

## 5. Create the Tool UI Component

Create a component that uses `AppRenderer` to render tool UIs. Create `src/ToolUI.tsx`:

```tsx
import { useState, useEffect, useRef } from 'react';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { AppRenderer, type AppRendererHandle } from '@mcp-ui/client';

interface ToolUIProps {
  client: Client;
  toolName: string;
  toolInput?: Record<string, unknown>;
}

export function ToolUI({ client, toolName, toolInput }: ToolUIProps) {
  const [toolResult, setToolResult] = useState<any>(null);
  const [error, setError] = useState<string | null>(null);
  const appRef = useRef<AppRendererHandle>(null);

  // Call the tool when input changes
  useEffect(() => {
    if (!toolInput) return;

    const callTool = async () => {
      try {
        const result = await client.callTool({
          name: toolName,
          arguments: toolInput,
        });
        setToolResult(result);
      } catch (err) {
        setError(err instanceof Error ? err.message : String(err));
      }
    };

    callTool();
  }, [client, toolName, toolInput]);

  // Get the sandbox URL
  const sandboxUrl = new URL('/sandbox_proxy.html', window.location.origin);

  if (error) {
    return <div style={{ color: 'red' }}>Error: {error}</div>;
  }

  return (
    <div style={{ width: '100%', height: '600px' }}>
      <AppRenderer
        ref={appRef}
        client={client}
        toolName={toolName}
        sandbox={{ url: sandboxUrl }}
        toolInput={toolInput}
        toolResult={toolResult}
        onOpenLink={async ({ url }) => {
          // Handle link requests from the UI
          window.open(url, '_blank');
          return { isError: false };
        }}
        onMessage={async (params) => {
          // Handle message requests from the UI (e.g., follow-up prompts)
          console.log('Message from UI:', params);
          return { isError: false };
        }}
        onSizeChanged={(params) => {
          // Handle size change notifications
          console.log('Size changed:', params);
        }}
        onError={(error) => {
          console.error('UI Error:', error);
          setError(error.message);
        }}
      />
    </div>
  );
}
```

## 6. Create the Main App

Update `src/App.tsx` to connect to the MCP server and render tool UIs:

```tsx
import { useState, useEffect } from 'react';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { createMcpClient } from './mcp-client';
import { ToolUI } from './ToolUI';
import './App.css';

function App() {
  const [client, setClient] = useState<Client | null>(null);
  const [tools, setTools] = useState<any[]>([]);
  const [selectedTool, setSelectedTool] = useState<string | null>(null);
  const [toolInput, setToolInput] = useState<Record<string, unknown>>({});
  const [error, setError] = useState<string | null>(null);

  // Connect to MCP server on mount
  useEffect(() => {
    const connect = async () => {
      try {
        // Replace with your MCP server URL
        const mcpClient = await createMcpClient('http://localhost:3001/mcp');
        setClient(mcpClient);

        // List available tools
        const toolsResult = await mcpClient.listTools({});
        setTools(toolsResult.tools);
      } catch (err) {
        setError(err instanceof Error ? err.message : String(err));
      }
    };

    connect();
  }, []);

  // Filter tools that have UI resources
  const toolsWithUI = tools.filter((tool) =>
    tool._meta?.ui?.resourceUri
  );

  if (error) {
    return <div style={{ color: 'red', padding: '20px' }}>Error: {error}</div>;
  }

  if (!client) {
    return <div style={{ padding: '20px' }}>Connecting to MCP server...</div>;
  }

  return (
    <div style={{ padding: '20px' }}>
      <h1>MCP Apps Client Demo</h1>

      <div style={{ marginBottom: '20px' }}>
        <h2>Available Tools with UI</h2>
        {toolsWithUI.length === 0 ? (
          <p>No tools with UI found. Make sure your server has tools with _meta.ui.resourceUri.</p>
        ) : (
          <ul>
            {toolsWithUI.map((tool) => (
              <li key={tool.name}>
                <button
                  onClick={() => {
                    setSelectedTool(tool.name);
                    setToolInput({ query: 'Hello from client!' });
                  }}
                  style={{
                    fontWeight: selectedTool === tool.name ? 'bold' : 'normal',
                  }}
                >
                  {tool.name}
                </button>
                <span style={{ marginLeft: '10px', color: '#666' }}>
                  {tool.description}
                </span>
              </li>
            ))}
          </ul>
        )}
      </div>

      {selectedTool && client && (
        <div style={{ border: '1px solid #ccc', padding: '20px', borderRadius: '8px' }}>
          <h2>Tool UI: {selectedTool}</h2>
          <ToolUI
            client={client}
            toolName={selectedTool}
            toolInput={toolInput}
          />
        </div>
      )}
    </div>
  );
}

export default App;
```

## 7. Run the Application

Start your React development server:

```bash
npm run dev
```

Make sure your MCP server is running (e.g., the `mcp-apps-demo` example on port 3001):

```bash
# In the mcp-apps-demo directory
npm run build && npm start
```

Open your browser to `http://localhost:5173` (or the Vite dev server URL). You should see:
1. A list of tools with UI from the connected MCP server
2. Click a tool to render its UI in the sandboxed iframe
3. The UI can send messages back to your client via the `onMessage` callback

## 8. Handle Custom Tool Calls from UI

Tool UIs can request to call other tools. Add a custom handler:

```tsx
<AppRenderer
  client={client}
  toolName={selectedTool}
  sandbox={{ url: sandboxUrl }}
  // ... other props
  onCallTool={async (params) => {
    // Custom handling for tool calls from the UI
    console.log('UI requested tool call:', params);

    // You can filter, modify, or intercept tool calls here
    const result = await client.callTool(params);
    return result;
  }}
/>
```

## 9. Using AppRenderer Without a Client

If you don't have direct access to an MCP client (e.g., the MCP connection is managed by a backend), you can use callbacks instead:

```tsx
<AppRenderer
  toolName="my-tool"
  toolResourceUri="ui://my-server/widget"
  sandbox={{ url: sandboxUrl }}
  onReadResource={async ({ uri }) => {
    // Fetch the resource from your backend
    const response = await fetch(`/api/mcp/resources?uri=${encodeURIComponent(uri)}`);
    return response.json();
  }}
  onCallTool={async (params) => {
    // Proxy tool calls through your backend
    const response = await fetch('/api/mcp/tools/call', {
      method: 'POST',
      body: JSON.stringify(params),
    });
    return response.json();
  }}
  toolInput={{ query: 'hello' }}
/>
```

Or provide pre-fetched HTML directly:

```tsx
<AppRenderer
  toolName="my-tool"
  sandbox={{ url: sandboxUrl }}
  html={preloadedHtml}  // Skip resource fetching entirely
  toolInput={{ query: 'hello' }}
/>
```

## Next Steps

- [AppRenderer Reference](./app-renderer.md) - Complete API documentation for AppRenderer
- [Protocol Details](../protocol-details.md) - Understanding the MCP Apps protocol
- [MCP Apps Overview](../mcp-apps.md) - Protocol details and server-side setup
- [Supported Hosts](../supported-hosts.md) - See which hosts support MCP Apps


================================================
FILE: docs/src/guide/embeddable-ui.md
================================================
# Embeddable UI

::: tip MCP Apps Standard
This page documents the **legacy MCP-UI `postMessage` protocol** for embedded iframes. For MCP Apps hosts, see the [MCP Apps JSON-RPC protocol](./protocol-details#mcp-apps-protocol) instead.

For new apps, we recommend using the MCP Apps pattern with `_meta.ui.resourceUri`. See [Getting Started](./getting-started).
:::

> This document describes the general communication protocol for any embeddable UIs.
> This is implemented by the mcp-ui iframe based solution, in the context of UI over MCP.

# Concepts

- Embedded iframes communicate with the parent window via `postMessage`.
- The parent window can send messages to the iframe.
- The iframe can send messages to the parent window.

# Communication Protocol

## Message Structure

```typescript
type Message = {
  type: string;
  messageId?: string; // optional, used for tracking the message
  payload: Record<string, unknown>;
};
```

## Message Types

- [`intent`](#intent) - the user has interacted with the UI and expressed an intent, and the host should act on it
- [`notify`](#notify) - the iframe already acted upon the user interaction, and is notifying the host to trigger any side effects
- [`prompt`](#prompt) - the iframe asks the host to run a prompt
- [`tool`](#tool) - the iframe asks the host to run a tool call
- [`link`](#link) - the iframe asks the host to navigate to a link

### `intent`

- indicates that the user has interacted with the UI and expressed an intent, and the host should act on it
- the payload is an object with the following properties:
  - `intent` - the intent that the user expressed
  - `params` - the parameters to pass to the intent

**Example:**

```typescript
window.parent.postMessage(
  {
    type: "intent",
    payload: {
      intent: "create-task",
      params: {
        title: "Buy groceries",
        description: "Buy groceries for the week",
      },
    },
  },
  "*"
);
```

### `notify`

- indicates that the iframe already acted upon the user interaction, and is notifying the host to trigger any side effects
- the payload is an object with the following properties:
  - `message` - the message to notify the host with

**Example:**

```typescript
window.parent.postMessage(
  {
    type: "notify",
    payload: {
      message: "cart-updated",
    },
  },
  "*"
);
```

### `prompt`

- indicates that the iframe asks the host to run a prompt
- the payload is an object with the following properties:
  - `prompt` - the prompt to run

**Example:**

```typescript
window.parent.postMessage(
  {
    type: "prompt",
    payload: {
      prompt: "What is the weather in Tokyo?",
    },
  },
  "*"
);
```

### `tool`

- indicates that the iframe asks the host to run a tool call
- the payload is an object with the following properties:
  - `toolName` - the name of the tool to run
  - `params` - the parameters to pass to the tool

**Example:**

```typescript
window.parent.postMessage(
  {
    type: "tool",
    payload: {
      toolName: "get-weather",
      params: {
        city: "Tokyo",
      },
    },
  },
  "*"
);
```

### `link`

- indicates that the iframe asks the host to navigate to a link
- the payload is an object with the following properties:
  - `url` - the URL to navigate to

**Example:**

```typescript
window.parent.postMessage(
  {
    type: "link",
    payload: {
      url: "https://www.google.com",
    },
  },
  "*"
);
```

## Reserved Message Types (iframe to host)

- [`ui-lifecycle-iframe-ready`](#ui-lifecycle-iframe-ready) - the iframe is ready to receive messages
- [`ui-size-change`](#ui-size-change) - the iframe's size has changed and the host should adjust the iframe's size
- [`ui-request-data`](#ui-request-data) - the iframe sends a request to the host to request data
- [`ui-request-render-data`](#ui-request-render-data) - the iframe requests render data from the host

### `ui-lifecycle-iframe-ready`

- indicates that the iframe is ready to receive messages

**Example:**
See [Render Data](#passing-render-data-to-the-iframe)

### `ui-size-change`

- indicates that the iframe's size has changed and the host should adjust the iframe's size
- the payload is an object with the following properties:
  - `width` - the new width of the iframe
  - `height` - the new height of the iframe

**Example:**

```typescript
const resizeObserver = new ResizeObserver((entries) => {
  entries.forEach((entry) => {
    window.parent.postMessage(
      {
        type: "ui-size-change",
        payload: {
          height: entry.contentRect.height,
        },
      },
      "*"
    );
  });
});

resizeObserver.observe(document.documentElement);
```

### `ui-request-data`

- a message that the iframe sends to the host to request data. The message must include a `messageId` to allow the iframe to track the response.
- the payload is an object with the following properties:
  - `requestType` - the type of the request
  - `params` - the parameters to pass to the request

**Example:**

```typescript
window.parent.postMessage(
  {
    type: "ui-request-data",
    messageId: "123",
    payload: {
      requestType: "get-payment-methods",
      params: {
        // any params needed for the request
      },
    },
  },
  "*"
);
```

See also [Asynchronous Data Requests with Message IDs](#asynchronous-data-requests-with-message-ids)

### `ui-request-render-data`

- a message that the iframe sends to the host to request render data. The message can optionally include a `messageId` to allow the iframe to track the response.
- this message has no payload
- the host responds with a [`ui-lifecycle-iframe-render-data`](#ui-lifecycle-iframe-render-data) message containing the render data

**Example:**

```typescript
window.parent.postMessage(
  {
    type: "ui-request-render-data",
    messageId: "render-data-123", // optional
  },
  "*"
);
```

## Reserved Message Types (host to iframe)

- [`ui-lifecycle-iframe-render-data`](#ui-lifecycle-iframe-render-data) - the host sends the iframe render data
- [`ui-message-received`](#ui-message-received) - the host sends the iframe to indicate that the action has been received
- [`ui-message-response`](#ui-message-response) - the iframe sends the host to indicate that the action has been processed or failed

### `ui-lifecycle-iframe-render-data`

- a message that the host sends to the iframe to pass any relevant render data
- the payload is an object with the following properties:
  - `renderData` - the render data to pass to the iframe

**Example:**
See [Render Data](#render-data)

### `ui-message-received`

- a message that the host sends to the iframe to indicate that the action has been received. The original messageId is passed back to the host to allow the host to track the action. This is useful for `request-data` messages, but is not limited to this type.
  **Example:**
  See [Asynchronous Data Requests with Message IDs](#asynchronous-data-requests-with-message-ids)

### `ui-message-response`

- a message that the iframe sends to the host to indicate that the action has been processed. The original messageId is passed back to the host to allow the host to track the action. This is useful for `request-data` messages, but is not limited to this type.
- the payload is an object with the following properties:
  - `response` - the response to the action
  - `error` - the error, if any, that occurred

**Example:**
See [Asynchronous Data Requests with Message IDs](#asynchronous-data-requests-with-message-ids)

## Query Parameters

### `waitForRenderData`

- a query parameter that can be passed to the iframe to indicate that the iframe should wait for the render data to be passed before sending any messages
- the value of the query parameter is a boolean
- if the query parameter is present, the iframe will wait for the render data to be passed before sending any messages

**Example:**
See [Render Data](#render-data)

# Usage Examples

## Passing Render Data to the Iframe

### In the host:

```typescript
iframeSrc = "https://my-embeddable-ui.com?waitForRenderData=true";
iframe = document.createElement("iframe");
iframe.src = iframeSrc; // the iframe will wait for the render data to be passed before rendering
document.body.appendChild(iframe);

window.addEventListener("message", (event) => {
  if (event.data.type === "ui-lifecycle-iframe-ready") {
    iframe.contentWindow.postMessage(
      {
        type: "ui-lifecycle-iframe-render-data",
        payload: { renderData: { theme: "dark" } },
      },
      "*"
    );
  }
});
```

### In the iframe:

```typescript
// In the iframe's script
const urlParams = new URLSearchParams(window.location.search);
if (urlParams.get("waitForRenderData") === "true") {
  let customRenderData = null;

  // The parent will send this message on load or when we notify it we're ready
  window.addEventListener("message", (event) => {
    // Add origin checks for security
    if (event.data.type === "ui-lifecycle-iframe-render-data") {
      // If the iframe has already received data, we don't need to do anything
      if (customRenderData) {
        return;
      } else {
        customRenderData = event.data.payload.renderData;
        // Now you can render the UI with the received data
        renderUI(customRenderData);
      }
    }
  });
  // We can let the parent know we're ready to receive data
  window.parent.postMessage({ type: "ui-lifecycle-iframe-ready" }, "*");
} else {
  // If the iframe doesn't need to wait for data, we can render the default UI immediately
  renderUI();
}
```

### Alternative: Requesting Render Data On-Demand

Instead of relying on the `ui-lifecycle-iframe-ready` lifecycle event, you can explicitly request render data when needed using `ui-request-render-data`:

#### In the iframe:

```typescript
// Request render data when ready
async function requestRenderData() {
  return new Promise((resolve, reject) => {
    const messageId = crypto.randomUUID();
    
    window.parent.postMessage(
      { type: "ui-request-render-data", messageId },
      "*"
    );

    function handleMessage(event) {
      if (event.data?.type !== "ui-lifecycle-iframe-render-data") return;
      if (event.data.messageId !== messageId) return;
      
      window.removeEventListener("message", handleMessage);
      
      const { renderData, error } = event.data.payload;
      if (error) return reject(error);
      return resolve(renderData);
    }

    window.addEventListener("message", handleMessage);
  });
}

// Use it when your iframe is ready
const renderData = await requestRenderData();
renderUI(renderData);
```

## Asynchronous Data Requests with Message IDs

Actions initiated from the iframe are handled by the host asynchronously (e.g., data requests, tool calls, etc.). It's useful for the iframe to get feedback on the status of the request and its result. This is achieved using a `messageId` to track the request through its lifecycle. Example use cases include fetching additional information, displaying a progress bar in the iframe, signaling success or failure, and more.

The primary message types are:
- `ui-request-data`: Sent from the iframe to the host to request some data or action.
- `ui-message-received`: Sent from the host to the iframe to acknowledge that the request is being processed.
- `ui-message-response`: Sent from the host to the iframe with the final result (success or error).

While this example uses `ui-request-data`, any message from the iframe can include a `messageId` to leverage this asynchronous flow (e.g., `tool`, `intent`).

```mermaid
sequenceDiagram
    participant Iframe
    participant Host

    Iframe->>Host: postMessage({ type: 'ui-request-data', messageId: '123', ... })
    Note right of Iframe: 1. Iframe initiates request<br>with a unique messageId.

    Host->>Iframe: postMessage({ type: 'ui-message-received', messageId: '123' })
    Note left of Host: 2. Host acknowledges receipt (optional).

    Note over Host: Process request...

    alt Request succeeds
        Host->>Iframe: postMessage({ type: 'ui-message-response', messageId: '123', payload: { response: ... } })
    else Request fails
        Host->>Iframe: postMessage({ type: 'ui-message-response', messageId: '123', payload: { error: ... } })
    end
    Note left of Host: 3. Host sends final response.

    Note right of Iframe: 4. Iframe uses messageId to handle<br>the specific response.
```


================================================
FILE: docs/src/guide/getting-started.md
================================================
# Getting Started

This guide will help you get started with building MCP Apps using the `@mcp-ui/*` packages.

## Prerequisites

- Node.js (v22.x recommended for the TypeScript SDK)
- pnpm (v9 or later recommended for the TypeScript SDK)
- Ruby (v3.x recommended for the Ruby SDK)
- Python (v3.10+ recommended for the Python SDK)

## Installation

### For TypeScript

```bash
# Server SDK
npm install @mcp-ui/server @modelcontextprotocol/ext-apps

# Client SDK
npm install @mcp-ui/client
```

### For Ruby

```bash
gem install mcp_ui_server
```

### For Python

```bash
pip install mcp-ui-server
```

## Quick Start: MCP Apps Pattern

### Server Side

Create a tool with an interactive UI using `registerAppTool` and `_meta.ui.resourceUri`:

```typescript
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { registerAppTool, registerAppResource } from '@modelcontextprotocol/ext-apps/server';
import { createUIResource } from '@mcp-ui/server';
import { z } from 'zod';

// 1. Create your MCP server
const server = new McpServer({ name: 'my-server', version: '1.0.0' });

// 2. Create the UI resource with interactive HTML
const widgetUI = await createUIResource({
  uri: 'ui://my-server/widget',
  content: {
    type: 'rawHtml',
    htmlString: `
      <html>
        <body>
          <h1>Interactive Widget</h1>
          <button onclick="sendMessage()">Send Message</button>
          <div id="status">Ready</div>
          <script type="module">
            import { App } from 'https://esm.sh/@modelcontextprotocol/ext-apps@0.4.1';

            // Initialize the MCP Apps client
            const app = new App({ name: 'widget', version: '1.0.0' });

            // Listen for tool input
            app.ontoolinput = (params) => {
              document.getElementById('status').textContent =
                'Received: ' + JSON.stringify(params.input);
            };

            // Send a message to the conversation
            window.sendMessage = async () => {
              await app.sendMessage({
                role: 'user',
                content: [{ type: 'text', text: 'Tell me more about this widget' }]
              });
            };

            // Connect to the host
            await app.connect();
          </script>
        </body>
      </html>
    `,
  },
  encoding: 'text',
});

// 3. Register the resource handler
registerAppResource(
  server,
  'widget_ui',
  widgetUI.resource.uri,
  {},
  async () => ({
    contents: [widgetUI.resource]
  })
);

// 4. Register the tool with _meta.ui.resourceUri
registerAppTool(
  server,
  'show_widget',
  {
    description: 'Show an interactive widget',
    inputSchema: {
      query: z.string().describe('User query'),
    },
    _meta: {
      ui: {
        resourceUri: widgetUI.resource.uri  // Links tool to UI
      }
    }
  },
  async ({ query }) => {
    return {
      content: [{ type: 'text', text: `Processing: ${query}` }]
    };
  }
);
```

::: tip MCP Apps Protocol
The example above uses the [`@modelcontextprotocol/ext-apps`](https://github.com/modelcontextprotocol/ext-apps) `App` class for communication. See [Protocol Details](./protocol-details) for the full JSON-RPC API.
:::

### Client Side

Render tool UIs with `AppRenderer`:

```tsx
import { AppRenderer } from '@mcp-ui/client';

function ToolUI({ client, toolName, toolInput, toolResult }) {
  return (
    <AppRenderer
      client={client}
      toolName={toolName}
      sandbox={{ url: new URL('/sandbox_proxy.html', window.location.origin) }}
      toolInput={toolInput}
      toolResult={toolResult}
      onOpenLink={async ({ url }) => {
        // Validate URL scheme before opening
        if (url.startsWith('https://') || url.startsWith('http://')) {
          window.open(url);
        }
        return { isError: false };
      }}
      onMessage={async (params) => {
        console.log('Message from UI:', params);
        // Handle the message (e.g., send to AI conversation)
        return { isError: false };
      }}
      onError={(error) => console.error('UI error:', error)}
    />
  );
}
```

### Using Without an MCP Client

You can use `AppRenderer` without a full MCP client by providing callbacks:

```tsx
<AppRenderer
  toolName="show_widget"
  toolResourceUri="ui://my-server/widget"
  sandbox={{ url: sandboxUrl }}
  onReadResource={async ({ uri }) => {
    // Fetch resource from your backend
    return myBackend.readResource({ uri });
  }}
  onCallTool={async (params) => {
    return myBackend.callTool(params);
  }}
  toolInput={{ query: 'hello' }}
/>
```

Or provide pre-fetched HTML directly:

```tsx
<AppRenderer
  toolName="show_widget"
  sandbox={{ url: sandboxUrl }}
  html={preloadedHtml}  // Skip resource fetching
  toolInput={{ query: 'hello' }}
/>
```

## Resource Types

MCP Apps supports several UI content types:

### 1. HTML Resources

Direct HTML content rendered in a sandboxed iframe:

```typescript
const htmlResource = await createUIResource({
  uri: 'ui://my-tool/widget',
  content: { type: 'rawHtml', htmlString: '<h1>Hello World</h1>' },
  encoding: 'text',
});
```

### 2. External URLs

Fetch an external page's HTML and serve it as a UI resource. The SDK fetches the URL's contents server-side and injects a `<base>` tag so relative paths (CSS, JS, images) resolve correctly:

```typescript
const urlResource = await createUIResource({
  uri: 'ui://my-tool/external',
  content: { type: 'externalUrl', iframeUrl: 'https://example.com' },
  encoding: 'text',
});
// The resource now contains the fetched HTML with a <base href="https://example.com"> tag
```

## Declaring UI Extension Support

When creating your MCP client, declare UI extension support:

```typescript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import {
  type ClientCapabilitiesWithExtensions,
  UI_EXTENSION_CAPABILITIES,
} from '@mcp-ui/client';

const capabilities: ClientCapabilitiesWithExtensions = {
  roots: { listChanged: true },
  extensions: UI_EXTENSION_CAPABILITIES,
};

const client = new Client(
  { name: 'my-app', version: '1.0.0' },
  { capabilities }
);
```

## Building from Source

### Clone and Install

```bash
git clone https://github.com/idosal/mcp-ui.git
cd mcp-ui
pnpm install
```

### Build All Packages

```bash
pnpm --filter=!@mcp-ui/docs build
```

### Run Tests

```bash
pnpm test
```

## Next Steps

- **Server SDKs**: Learn how to create resources with our server-side packages.
  - [TypeScript SDK Usage & Examples](./server/typescript/usage-examples.md)
  - [Ruby SDK Usage & Examples](./server/ruby/usage-examples.md)
  - [Python SDK Usage & Examples](./server/python/usage-examples.md)
- **Client SDK**: Learn how to render resources.
  - [Client Overview](./client/overview.md)
- **Protocol & Components**:
  - [Protocol Details](./protocol-details.md)


================================================
FILE: docs/src/guide/introduction.md
================================================
# Introduction

Welcome to the MCP Apps SDK documentation!

The `@mcp-ui/*` packages provide tools for building [MCP Apps](https://github.com/modelcontextprotocol/ext-apps) - interactive UI components for Model Context Protocol (MCP) tools. This SDK implements the MCP Apps standard, enabling rich HTML interfaces within AI applications.

You can use [GitMCP](https://gitmcp.io/idosal/mcp-ui) to give your IDE access to `mcp-ui`'s latest documentation!
<a href="https://gitmcp.io/idosal/mcp-ui"><img src="https://img.shields.io/endpoint?url=https://gitmcp.io/badge/idosal/mcp-ui" alt="MCP Documentation"></a>

## Background

MCP-UI pioneered the concept of interactive UI over the Model Context Protocol. Before MCP Apps existed as a standard, this project demonstrated how MCP tools could return rich, interactive HTML interfaces instead of plain text, enabling UI components within AI applications.

The patterns and ideas explored in MCP-UI directly influenced the development of the [MCP Apps specification](https://github.com/modelcontextprotocol/ext-apps), which standardized UI delivery over MCP. Today, the `@mcp-ui/*` packages implement this standard while maintaining the project's original vision: making it simple to build beautiful, interactive experiences for AI tools.

## What are MCP Apps?

MCP Apps is a standard for attaching interactive UIs to MCP tools. When a tool has an associated UI, hosts can render it alongside the tool's results, enabling rich user experiences like forms, charts, and interactive widgets.

### The Core Pattern

The MCP Apps pattern uses three key concepts:

1. **Tool with `_meta.ui.resourceUri`** - Links a tool to its UI resource
2. **Resource Handler** - Serves the UI content when the host requests it
3. **AppRenderer** - Client component that fetches and renders the UI

```typescript
// 1. Create UI content
const widgetUI = await createUIResource({
  uri: 'ui://my-server/widget',
  content: { type: 'rawHtml', htmlString: '<h1>Widget</h1>' },
  encoding: 'text',
});

// 2. Register resource handler
registerAppResource(server, 'widget_ui', widgetUI.resource.uri, {}, async () => ({
  contents: [widgetUI.resource]
}));

// 3. Register tool with _meta linking
registerAppTool(server, 'show_widget', {
  description: 'Show interactive widget',
  inputSchema: { query: z.string() },
  _meta: { ui: { resourceUri: widgetUI.resource.uri } }  // This links tool → UI
}, async ({ query }) => {
  return { content: [{ type: 'text', text: `Result: ${query}` }] };
});
```

When a host calls `show_widget`, it sees the `_meta.ui.resourceUri` and fetches the UI from that resource URI to render alongside the tool result.

## SDK Packages

The `@mcp-ui/*` packages provide everything needed to build and render MCP Apps:

### Server SDK (`@mcp-ui/server`)
- **`createUIResource`**: Creates UI resource objects with HTML content or fetched external URLs
- Works with `registerAppTool` and `registerAppResource` from `@modelcontextprotocol/ext-apps/server`

### Client SDK (`@mcp-ui/client`)
- **`AppRenderer`**: High-level component for rendering tool UIs (fetches resources, handles lifecycle)
- **`AppFrame`**: Lower-level component for when you have pre-fetched HTML

### Additional Language SDKs
- **`mcp_ui_server`** (Ruby): Helper methods for creating UI resources
- **`mcp-ui-server`** (Python): Helper methods for creating UI resources

## How It Works

```
┌─────────────────────────────────────────────────────────────────┐
│                          MCP Host                                │
│  1. Calls tool                                                  │
│  2. Sees _meta.ui.resourceUri in tool definition               │
│  3. Fetches resource via resources/read                        │
│  4. Renders UI in sandboxed iframe (AppRenderer)               │
└─────────────────────────────────────────────────────────────────┘
         │                                    ▲
         ▼                                    │
┌─────────────────────────────────────────────────────────────────┐
│                         MCP Server                               │
│  - registerAppTool with _meta.ui.resourceUri                    │
│  - registerAppResource to serve UI content                      │
│  - createUIResource to build UI payloads                        │
└─────────────────────────────────────────────────────────────────┘
```

### Example Flow

**Server (MCP Tool):**
::: code-group

```typescript [TypeScript]
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { registerAppTool, registerAppResource } from '@modelcontextprotocol/ext-apps/server';
import { createUIResource } from '@mcp-ui/server';
import { z } from 'zod';

const server = new McpServer({ name: 'my-server', version: '1.0.0' });

const dashboardUI = await createUIResource({
  uri: 'ui://my-tool/dashboard',
  content: { type: 'rawHtml', htmlString: '<h1>Dashboard</h1>' },
  encoding: 'text'
});

registerAppResource(server, 'dashboard_ui', dashboardUI.resource.uri, {}, async () => ({
  contents: [dashboardUI.resource]
}));

registerAppTool(server, 'show_dashboard', {
  description: 'Show dashboard',
  inputSchema: {},
  _meta: { ui: { resourceUri: dashboardUI.resource.uri } }
}, async () => {
  return { content: [{ type: 'text', text: 'Dashboard loaded' }] };
});
```

```ruby [Ruby]
require 'mcp_ui_server'

resource = McpUiServer.create_ui_resource(
  uri: 'ui://my-tool/dashboard',
  content: { type: :raw_html, htmlString: '<h1>Dashboard</h1>' },
  encoding: :text
)

# Return in MCP response
{ content: [resource] }
```

:::

**Client (Frontend App):**
```tsx
import { AppRenderer } from '@mcp-ui/client';

function ToolUI({ client, toolName, toolInput, toolResult }) {
  return (
    <AppRenderer
      client={client}
      toolName={toolName}
      sandbox={{ url: new URL('http://localhost:8765/sandbox_proxy.html') }}
      toolInput={toolInput}
      toolResult={toolResult}
      onOpenLink={async ({ url }) => {
        if (url.startsWith('https://') || url.startsWith('http://')) {
          window.open(url);
        }
      }}
      onMessage={async (params) => {
        console.log('Message from UI:', params);
        return { isError: false };
      }}
    />
  );
}
```

## Key Benefits

- **Standardized**: Implements the MCP Apps specification for consistent behavior across hosts
- **Secure**: Sandboxed iframe execution prevents malicious code from affecting the host
- **Interactive**: Two-way communication between UI and host via JSON-RPC
- **Flexible**: Supports HTML content with the MCP Apps standard MIME type

## Wire Format: UIResource

The underlying data format for UI content is the `UIResource` object:

```typescript
interface UIResource {
  type: 'resource';
  resource: {
    uri: string;       // ui://component/id
    mimeType: 'text/html;profile=mcp-app';  // MCP Apps standard
    text?: string;      // Inline HTML content
    blob?: string;      // Base64-encoded content
  };
}
```

The MIME type `text/html;profile=mcp-app` is the MCP Apps standard for UI resources.

### Key Field Details:

- **`uri`**: Unique identifier using `ui://` scheme (e.g., `ui://my-tool/widget-01`)
- **`mimeType`**: `text/html;profile=mcp-app` — MCP Apps-compliant HTML
- **`text` or `blob`**: The actual content, either as plain text or Base64 encoded

## Next Steps

- [Getting Started](./getting-started.md) - Set up your development environment
- [Server Walkthroughs](./server/typescript/walkthrough.md) - Step-by-step guides
- [Client SDK](./client/overview.md) - Learn to render tool UIs with AppRenderer
- [TypeScript Server SDK](./server/typescript/overview.md) - Create tools with UI
- [Ruby Server SDK](./server/ruby/overview.md) - Ruby implementation
- [Protocol Details](./protocol-details.md) - Understand the underlying protocol


================================================
FILE: docs/src/guide/mcp-apps.md
================================================
# Legacy MCP-UI Adapter

::: tip For New Apps
**Building a new app?** Use the MCP Apps patterns directly - see [Getting Started](./getting-started) for the recommended approach with `registerAppTool`, `_meta.ui.resourceUri`, and `AppRenderer`.

This page is for **migrating existing MCP-UI widgets** to work in MCP Apps hosts.
:::

The MCP Apps adapter in `@mcp-ui/server` enables **existing MCP-UI HTML widgets** to run inside MCP Apps-compliant hosts. This is a backward-compatibility layer for apps that were built using the legacy MCP-UI `postMessage` protocol.

## When to Use This Adapter

- **Existing MCP-UI widgets**: You have HTML widgets using the `ui-lifecycle-*` message format
- **Gradual migration**: You want your existing widgets to work in both legacy MCP-UI hosts and new MCP Apps hosts
- **Protocol translation**: Your widget uses `postMessage` calls that need to be translated to JSON-RPC

## Overview

The adapter automatically translates between the MCP-UI `postMessage` protocol and MCP Apps JSON-RPC, allowing your existing widgets to work in MCP Apps hosts without code changes.

## How It Works

```
┌─────────────────────────────────────────────────────────────────┐
│                        MCP Apps Host                            │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                     Sandbox Iframe                        │  │
│  │  ┌─────────────────────────────────────────────────────┐  │  │
│  │  │                  Tool UI Iframe                     │  │  │
│  │  │  ┌───────────────┐    ┌──────────────────────────┐  │  │  │
│  │  │  │  MCP-UI       │───▶│  MCP Apps Adapter        │  │  │  │
│  │  │  │  Widget       │◀───│  (injected script)       │  │  │  │
│  │  │  └───────────────┘    └──────────────────────────┘  │  │  │
│  │  │         │                        │                  │  │  │
│  │  │         │ MCP-UI Protocol        │ JSON-RPC         │  │  │
│  │  │         ▼                        ▼                  │  │  │
│  │  │   postMessage              postMessage              │  │  │
│  │  └─────────────────────────────────────────────────────┘  │  │
│  └───────────────────────────────────────────────────────────┘  │
│                              │                                   │
│                              ▼                                   │
│                    MCP Apps SEP Protocol                         │
└─────────────────────────────────────────────────────────────────┘
```

The adapter:
1. Intercepts MCP-UI messages from your widget
2. Translates them to MCP Apps SEP JSON-RPC format
3. Sends them to the host via postMessage
4. Receives host responses and translates them back to MCP-UI format

## Quick Start

### 1. Create a UI Resource with the MCP Apps Adapter

```typescript
import { createUIResource } from '@mcp-ui/server';

const widgetUI = await createUIResource({
  uri: 'ui://my-server/widget',
  encoding: 'text',
  content: {
    type: 'rawHtml',
    htmlString: `
      <html>
        <body>
          <div id="app">Loading...</div>
          <script>
            // Listen for render data from the adapter
            window.addEventListener('message', (event) => {
              if (event.data.type === 'ui-lifecycle-iframe-render-data') {
                const { toolInput, toolOutput } = event.data.payload.renderData;
                document.getElementById('app').textContent =
                  JSON.stringify({ toolInput, toolOutput }, null, 2);
              }
            });

            // Signal that the widget is ready
            window.parent.postMessage({ type: 'ui-lifecycle-iframe-ready' }, '*');
          </script>
        </body>
      </html>
    `,
  },
});
```

### 2. Register the Resource and Tool

```typescript
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { createUIResource } from '@mcp-ui/server';
import { registerAppTool, registerAppResource } from '@modelcontextprotocol/ext-apps/server';
import { z } from 'zod';

const server = new McpServer({ name: 'my-server', version: '1.0.0' });

// Create the UI resource (from step 1)
const widgetUI = await createUIResource({
  uri: 'ui://my-server/widget',
  // ... (same as above)
});

// Register the resource so the host can fetch it
registerAppResource(
  server,
  'widget_ui',           // Resource name
  widgetUI.resource.uri, // Resource URI
  {},                    // Resource metadata
  async () => ({
    contents: [widgetUI.resource]
  })
);

// Register the tool with _meta linking to the UI resource
registerAppTool(
  server,
  'my_widget',
  {
    description: 'An interactive widget',
    inputSchema: {
      query: z.string().describe('User query'),
    },
    // This tells MCP Apps hosts where to find the UI
    _meta: {
      ui: {
        resourceUri: widgetUI.resource.uri
      }
    }
  },
  async ({ query }) => {
    return {
      content: [{ type: 'text', text: `Processing: ${query}` }],
    };
  }
);
```

The key requirement for MCP Apps hosts is that the tool's `_meta.ui.resourceUri` points to the UI resource URI. This tells the host where to fetch the widget HTML.

### 3. Add the MCP-UI Embedded Resource to Tool Responses

To support **MCP-UI hosts** (which expect embedded resources in tool responses), also return a `createUIResource` result:

```typescript
registerAppTool(
  server,
  'my_widget',
  {
    description: 'An interactive widget',
    inputSchema: {
      query: z.string().describe('User query'),
    },
    // For MCP Apps hosts - points to the registered resource
    _meta: {
      ui: {
        resourceUri: widgetUI.resource.uri
      }
    }
  },
  async ({ query }) => {
    // Create an embedded UI resource for MCP-UI hosts
    const embeddedResource = await createUIResource({
      uri: `ui://my-server/widget/${query}`,
      encoding: 'text',
      content: {
        type: 'rawHtml',
        htmlString: renderWidget(query),  // Your widget HTML
      },
    });

    return {
      content: [
        { type: 'text', text: `Processing: ${query}` },
        embeddedResource  // Include for MCP-UI hosts
      ],
    };
  }
);
```

> **Important:** The embedded MCP-UI resource should **not** enable the MCP Apps adapter. It is for hosts that expect embedded resources in tool responses. MCP Apps hosts will ignore the embedded resource and instead fetch the UI from the registered resource URI in `_meta`.

## Protocol Translation Reference

### Widget → Host (Outgoing)

| MCP-UI Action | MCP Apps Method | Description |
|--------------|-----------------|-------------|
| `tool` | `tools/call` | Call another tool |
| `prompt` | `ui/message` | Send a follow-up message to the conversation |
| `link` | `ui/open-link` | Open a URL in a new tab |
| `notify` | `notifications/message` | Log a message to the host |
| `intent` | `ui/message` | Send an intent (translated to message) |
| `ui-size-change` | `ui/notifications/size-changed` | Request widget resize |

### Host → Widget (Incoming)

| MCP Apps Notification | MCP-UI Message | Description |
|----------------------|----------------|-------------|
| `ui/notifications/tool-input` | `ui-lifecycle-iframe-render-data` | Complete tool arguments |
| `ui/notifications/tool-input-partial` | `ui-lifecycle-iframe-render-data` | Streaming partial arguments |
| `ui/notifications/tool-result` | `ui-lifecycle-iframe-render-data` | Tool execution result |
| `ui/notifications/host-context-changed` | `ui-lifecycle-iframe-render-data` | Theme, locale, viewport changes |
| `ui/notifications/size-changed` | `ui-lifecycle-iframe-render-data` | Host informs of size constraints |
| `ui/notifications/tool-cancelled` | `ui-lifecycle-tool-cancelled` | Tool execution was cancelled |
| `ui/resource-teardown` | `ui-lifecycle-teardown` | Host notifies UI before teardown |

## Configuration Options

```typescript
createUIResource({
  // ...
  adapters: {
    mcpApps: {
      enabled: true,
      config: {
        // Timeout for async operations (default: 30000ms)
        timeout: 60000,
      },
    },
  },
});
```

## MIME Type

When the MCP Apps adapter is enabled, the resource MIME type is automatically set to `text/html;profile=mcp-app`, the MCP Apps equivalent to `text/html`.

## Receiving Data in Your Widget

The adapter sends data to your widget via the standard MCP-UI `ui-lifecycle-iframe-render-data` message:

```typescript
window.addEventListener('message', (event) => {
  if (event.data.type === 'ui-lifecycle-iframe-render-data') {
    const { renderData } = event.data.payload;
    
    // Tool input arguments
    const toolInput = renderData.toolInput;
    
    // Tool execution result (if available)
    const toolOutput = renderData.toolOutput;
    
    // Widget state (if supported by host)
    const widgetState = renderData.widgetState;
    
    // Host context
    const theme = renderData.theme;      // 'light' | 'dark' | 'system'
    const locale = renderData.locale;    // e.g., 'en-US'
    const displayMode = renderData.displayMode; // 'inline' | 'fullscreen' | 'pip'
    const maxHeight = renderData.maxHeight;
    
    // Update your UI with the data
    updateWidget(renderData);
  }
});
```

## Sending Actions from Your Widget

Use standard MCP-UI postMessage calls - the adapter translates them automatically:

```typescript
// Send a prompt to the conversation
window.parent.postMessage({
  type: 'prompt',
  payload: { prompt: 'What is the weather like today?' }
}, '*');

// Open a link
window.parent.postMessage({
  type: 'link',
  payload: { url: 'https://example.com' }
}, '*');

// Call another tool
window.parent.postMessage({
  type: 'tool',
  payload: { 
    toolName: 'get_weather',
    params: { city: 'San Francisco' }
  }
}, '*');

// Send a notification
window.parent.postMessage({
  type: 'notify',
  payload: { message: 'Widget loaded successfully' }
}, '*');

// Request resize
window.parent.postMessage({
  type: 'ui-size-change',
  payload: { width: 500, height: 400 }
}, '*');
```

## Mutual Exclusivity with Apps SDK Adapter

Only one adapter can be enabled at a time. The TypeScript types enforce this:

```typescript
// ✅ Valid: MCP Apps adapter only
adapters: { mcpApps: { enabled: true } }

// ✅ Valid: Apps SDK adapter only (for ChatGPT)
adapters: { appsSdk: { enabled: true } }

// ❌ TypeScript error: Cannot enable both
adapters: { mcpApps: { enabled: true }, appsSdk: { enabled: true } }
```

If you need to support both MCP Apps hosts and ChatGPT, create separate resources:

```typescript
// For MCP Apps hosts
const mcpAppsResource = await createUIResource({
  uri: 'ui://my-server/widget-mcp-apps',
  content: { type: 'rawHtml', htmlString: widgetHtml },
});

// For ChatGPT/Apps SDK hosts
const appsSdkResource = await createUIResource({
  uri: 'ui://my-server/widget-apps-sdk',
  content: { type: 'rawHtml', htmlString: widgetHtml },
});
```

## Complete Example

See the [mcp-apps-demo](https://github.com/idosal/mcp-ui/tree/main/examples/mcp-apps-demo) example for a complete working implementation.

```typescript
import express from 'express';
import cors from 'cors';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import { createUIResource } from '@mcp-ui/server';
import { registerAppTool, registerAppResource } from '@modelcontextprotocol/ext-apps/server';
import { z } from 'zod';

const app = express();
app.use(cors({ origin: '*', exposedHeaders: ['Mcp-Session-Id'] }));
app.use(express.json());

// ... (transport setup)

const server = new McpServer({ name: 'demo', version: '1.0.0' });

const graphUI = await createUIResource({
  uri: 'ui://demo/graph',
  encoding: 'text',
  content: {
    type: 'rawHtml',
    htmlString: `
      <!DOCTYPE html>
      <html>
      <head>
        <style>
          body { font-family: system-ui; padding: 20px; }
          .data { background: #f5f5f5; padding: 10px; border-radius: 8px; }
        </style>
      </head>
      <body>
        <h1>graph</h1>
        <div class="data" id="data">Waiting for data...</div>
        <button onclick="sendPrompt()">Ask Follow-up</button>

        <script>
          window.addEventListener('message', (e) => {
            if (e.data.type === 'ui-lifecycle-iframe-render-data') {
              document.getElementById('data').textContent =
                JSON.stringify(e.data.payload.renderData, null, 2);
            }
          });

          function sendPrompt() {
            window.parent.postMessage({
              type: 'prompt',
              payload: { prompt: 'Tell me more about this data' }
            }, '*');
          }

          window.parent.postMessage({ type: 'ui-lifecycle-iframe-ready' }, '*');
        </script>
      </body>
      </html>
    `,
  },
});

// Register the UI resource
registerAppResource(
  server,
  'graph_ui',
  graphUI.resource.uri,
  {},
  async () => ({
    contents: [graphUI.resource]
  })
);

// Register the tool with _meta linking to the UI resource
registerAppTool(
  server,
  'show_graph',
  {
    description: 'Display an interactive graph',
    inputSchema: {
      title: z.string().describe('Graph title'),
    },
    // For MCP Apps hosts - points to the registered resource
    _meta: {
      ui: {
        resourceUri: graphUI.resource.uri
      }
    }
  },
  async ({ title }) => {
    // Create embedded resource for MCP-UI hosts
    const embeddedResource = await createUIResource({
      uri: `ui://demo/graph/${encodeURIComponent(title)}`,
      encoding: 'text',
      content: {
        type: 'rawHtml',
        htmlString: `<html><body><h1>Graph: ${title}</h1></body></html>`,
      },
    });

    return {
      content: [
        { type: 'text', text: `Graph: ${title}` },
        embeddedResource  // Included for MCP-UI hosts
      ],
    };
  }
);

// ... (server setup)
```

## Debugging

The adapter logs debug information to the browser console. Look for messages prefixed with `[MCP Apps Adapter]`:

```
[MCP Apps Adapter] Initializing adapter...
[MCP Apps Adapter] Sending ui/initialize request
[MCP Apps Adapter] Received JSON-RPC message: {...}
[MCP Apps Adapter] Intercepted MCP-UI message: prompt
```

## Host-Side Rendering (Client SDK)

The `@mcp-ui/client` package provides React components for rendering MCP Apps tool UIs in your host application.

### AppRenderer Component

`AppRenderer` is the high-level component that handles the complete lifecycle of rendering an MCP tool's UI:

```tsx
import { AppRenderer, type AppRendererHandle } from '@mcp-ui/client';

function ToolUI({ client, toolName, toolInput, toolResult }) {
  const appRef = useRef<AppRendererHandle>(null);

  return (
    <AppRenderer
      ref={appRef}
      client={client}
      toolName={toolName}
      sandbox={{ url: new URL('http://localhost:8765/sandbox_proxy.html') }}
      toolInput={toolInput}
      toolResult={toolResult}
      hostContext={{ theme: 'dark' }}
      onOpenLink={async ({ url }) => {
        if (url.startsWith('https://') || url.startsWith('http://')) {
          window.open(url);
        }
      }}
      onMessage={async (params) => {
        console.log('Message from tool UI:', params);
        return { isError: false };
      }}
      onError={(error) => console.error('Tool UI error:', error)}
    />
  );
}
```

**Key Props:**
- `client` - Optional MCP client for automatic resource fetching and MCP request forwarding
- `toolName` - Name of the tool to render UI for
- `sandbox` - Sandbox configuration with the sandbox proxy URL
- `html` - Optional pre-fetched HTML (skips resource fetching)
- `toolResourceUri` - Optional pre-fetched resource URI
- `toolInput` / `toolResult` - Tool arguments and results to pass to the UI
- `hostContext` - Theme, locale, viewport info for the guest UI
- `onOpenLink` / `onMessage` / `onLoggingMessage` - Handlers for guest UI requests
- `onFallbackRequest` - Catch-all for JSON-RPC requests not handled by the built-in handlers (see [Handling Custom Requests](#handling-custom-requests-onfallbackrequest))

**Ref Methods:**
- `sendToolListChanged()` - Notify guest when tools change
- `sendResourceListChanged()` - Notify guest when resources change
- `sendPromptListChanged()` - Notify guest when prompts change
- `teardownResource()` - Clean up before unmounting

### Handling Custom Requests (`onFallbackRequest`)

AppRenderer includes built-in handlers for standard MCP Apps methods (`tools/call`, `ui/message`, `ui/open-link`, etc.). The `onFallbackRequest` prop lets you handle **any JSON-RPC request that doesn't match a built-in handler**. This is useful for:

- **Experimental methods** — prototype new capabilities (e.g., `x/clipboard/write`, `x/analytics/track`)
- **MCP methods not yet in the Apps spec** — support standard MCP methods like `sampling/createMessage` before they're officially added to MCP Apps

Under the hood, this is wired to `AppBridge`'s `fallbackRequestHandler` from the MCP SDK `Protocol` class. The guest UI sends a standard JSON-RPC request via `postMessage`, and if AppBridge has no registered handler for the method, it delegates to `onFallbackRequest`.

**Host-side handler:**

```tsx
import { AppRenderer, type JSONRPCRequest } from '@mcp-ui/client';
import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';

<AppRenderer
  client={client}
  toolName="my-tool"
  sandbox={sandboxConfig}
  onFallbackRequest={async (request, extra) => {
    switch (request.method) {
      case 'x/clipboard/write':
        await navigator.clipboard.writeText(request.params?.text as string);
        return { success: true };
      case 'sampling/createMessage':
        // Forward to MCP server
        return client.createMessage(request.params);
      default:
        throw new McpError(ErrorCode.MethodNotFound, `Unknown method: ${request.method}`);
    }
  }}
/>
```

**Guest-side (inside tool UI HTML):**

```ts
import { sendExperimentalRequest } from '@mcp-ui/server';

// Send a custom request to the host — returns a Promise with the response
const result = await sendExperimentalRequest('x/clipboard/write', { text: 'hello' });
```

The `sendExperimentalRequest` helper sends a properly formatted JSON-RPC request via `window.parent.postMessage`. The full request/response cycle flows through `PostMessageTransport` and the sandbox proxy, just like built-in methods.

::: tip Method Naming Convention
Use the `x/<namespace>/<action>` prefix for experimental methods (e.g., `x/clipboard/write`). Standard MCP methods not yet in the Apps spec (e.g., `sampling/createMessage`) should use their canonical method names. When an experimental method proves useful, it can be promoted to a standard method in the [ext-apps spec](https://github.com/modelcontextprotocol/ext-apps).
:::

### Using Without an MCP Client

You can use `AppRenderer` without a full MCP client by providing custom handlers:

```tsx
<AppRenderer
  // No client - use callbacks instead
  toolName="my-tool"
  toolResourceUri="ui://my-server/my-tool"
  sandbox={{ url: sandboxUrl }}
  onReadResource={async ({ uri }) => {
    // Proxy to your MCP client in a different context
    return myMcpProxy.readResource({ uri });
  }}
  onCallTool={async (params) => {
    return myMcpProxy.callTool(params);
  }}
/>
```

Or provide pre-fetched HTML directly:

```tsx
<AppRenderer
  toolName="my-tool"
  sandbox={{ url: sandboxUrl }}
  html={preloadedHtml}  // Skip all resource fetching
  toolInput={args}
/>
```

### AppFrame Component

`AppFrame` is the lower-level component for when you already have the HTML content and an `AppBridge` instance:

```tsx
import { AppFrame, AppBridge } from '@mcp-ui/client';

function LowLevelToolUI({ html, client }) {
  const bridge = useMemo(() => new AppBridge(client, hostInfo, capabilities), [client]);

  return (
    <AppFrame
      html={html}
      sandbox={{ url: sandboxUrl }}
      appBridge={bridge}
      toolInput={{ query: 'test' }}
      onSizeChanged={(size) => console.log('Size changed:', size)}
    />
  );
}
```

### Sandbox Proxy

Both components require a sandbox proxy HTML file to be served. This provides security isolation for the guest UI. The sandbox proxy URL should point to a page that loads the MCP Apps sandbox proxy script.

## Declaring UI Extension Support

When creating your MCP client, declare UI extension support using the provided type and capabilities:

```typescript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import {
  type ClientCapabilitiesWithExtensions,
  UI_EXTENSION_CAPABILITIES,
} from '@mcp-ui/client';

const capabilities: ClientCapabilitiesWithExtensions = {
  // Standard capabilities
  roots: { listChanged: true },
  // UI extension support (SEP-1724 pattern)
  extensions: UI_EXTENSION_CAPABILITIES,
};

const client = new Client(
  { name: 'my-app', version: '1.0.0' },
  { capabilities }
);
```

This tells MCP servers that your client can render UI resources with MIME type `text/html;profile=mcp-app`.

> **Note:** This uses the `extensions` field pattern from [SEP-1724](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1724), which is not yet part of the official MCP protocol.

## Related Resources

- [Getting Started](./getting-started) - Recommended patterns for new MCP Apps
- [MCP Apps SEP Specification](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx)
- [@modelcontextprotocol/ext-apps](https://github.com/modelcontextprotocol/ext-apps)
- [Apps SDK Integration](./apps-sdk.md) - For ChatGPT integration (separate from MCP Apps)
- [Protocol Details](./protocol-details.md) - MCP-UI wire format reference



================================================
FILE: docs/src/guide/protocol-details.md
================================================
# Protocol Details

This section covers the wire protocols for MCP Apps and legacy MCP-UI.

## MCP Apps Protocol

MCP Apps uses JSON-RPC over `postMessage` for communication between host and guest UI.

### Tool → UI Linking

Tools declare their associated UI via `_meta.ui.resourceUri`:

```typescript
// Tool definition
{
  name: 'show_widget',
  description: 'Show an interactive widget',
  inputSchema: { ... },
  _meta: {
    ui: {
      resourceUri: 'ui://my-server/widget'  // Points to registered resource
    }
  }
}
```

### Host → Guest Communication

The host sends JSON-RPC notifications to the guest UI:

| Notification | Description |
|-------------|-------------|
| `ui/notifications/tool-input` | Complete tool arguments |
| `ui/notifications/tool-input-partial` | Streaming partial arguments |
| `ui/notifications/tool-result` | Tool execution result |
| `ui/notifications/host-context-changed` | Theme, locale, viewport changes |
| `ui/notifications/size-changed` | Host informs of size constraints |
| `ui/notifications/tool-cancelled` | Tool execution was cancelled |
| `ui/resource-teardown` | Host notifies UI before teardown |

### Guest → Host Communication

The guest UI sends JSON-RPC requests to the host:

| Method | Description |
|--------|-------------|
| `tools/call` | Call another MCP tool |
| `ui/message` | Send a follow-up message to the conversation |
| `ui/open-link` | Open a URL in a new tab |
| `notifications/message` | Log a message to the host |
| `ui/notifications/size-changed` | Request widget resize |

### MIME Type

MCP Apps resources use `text/html;profile=mcp-app` to indicate MCP Apps compliance.

## UIResource Wire Format

```typescript
export interface UIResource {
  type: 'resource';
  resource: {
    uri: string;
    mimeType: 'text/html;profile=mcp-app';
    text?: string;
    blob?: string;
  };
}
```

## URI Schemes

- **`ui://<component-name>/<instance-id>`**

  - **Purpose**: For all UI resources.
  - **Content**: `text` or `blob` contains HTML content.
  - **Client Action**: Render in a sandboxed iframe
  - **Examples**: A custom button, a small form, a data visualization snippet, a fetched external page

## Content encoding: `text` vs. `blob`

- **`text`**: Simple, direct string. Good for smaller, less complex content.
- **`blob`**: Base64 encoded string.
  - **Pros**: Handles special characters robustly, can be better for larger payloads, ensures integrity during JSON transport.
  - **Cons**: Requires Base64 decoding on the client, slightly increases payload size.

## External URL Handling

When using `createUIResource` with `content.type: 'externalUrl'`, the behavior depends on the SDK:

- **TypeScript SDK**: Fetches the URL's HTML content server-side, injects a `<base>` tag so relative paths (CSS, JS, images) resolve against the original URL, and returns the resulting HTML as the resource content. It also validates the URL (http/https only, blocks private/localhost addresses) and enforces a timeout and response size limit. The SDK automatically populates `_meta.csp.baseUriDomains` with the external URL's origin, so the host's sandbox iframe can set appropriate CSP headers.
- **Python and Ruby SDKs**: Store the URL string directly as the resource content without fetching it. The host client is responsible for fetching and rendering the external page.

> **Note:** Not all hosts support `baseUriDomains`. Those that don't will ignore this field, which may cause the `<base>` tag to be blocked by the sandbox CSP.
>
> **Security:** The TypeScript SDK's server-side fetch introduces SSRF risk if the URL is derived from untrusted user input. The SDK blocks private IP ranges and localhost by default, but server developers should apply additional validation (e.g., URL allowlists) when the URL originates from user input. DNS rebinding attacks are not mitigated at the SDK level.

## Recommended Client-Side Pattern

Client-side hosts should check for the `ui://` URI scheme to identify MCP-UI resources:

```tsx
if (
  mcpResource.type === 'resource' &&
  mcpResource.resource.uri?.startsWith('ui://')
) {
  return <AppRenderer client={client} toolName={toolName} ... />;
}
```

## Communication (Client <-> Iframe)

For `ui://` resources, you can use `window.parent.postMessage` to send data or actions from the iframe back to the host client application. The client application should set up an event listener for `message` events.

### Basic Communication

**Iframe Script Example:**

```html
<button onclick="handleAction()">Submit Data</button>
<script>
  function handleAction() {
    const data = { action: 'formData', value: 'someValue' };
    // IMPORTANT: Always specify the targetOrigin for security!
    // Use '*' only if the parent origin is unknown or variable and security implications are understood.
    window.parent.postMessage(
      { type: 'tool', payload: { toolName: 'myCustomTool', params: data } },
      '*',
    );
  }
</script>
```

**Client-Side Handler:**

```typescript
window.addEventListener('message', (event) => {
  // Add origin check for security: if (event.origin !== "expectedOrigin") return;
  if (event.data && event.data.tool) {
    // Call the onUIAction prop of UIResourceRenderer
  }
});
```

### Asynchronous Communication with Message IDs

For iframe content that needs to handle asynchronous responses, you can include a `messageId` field in your UI action messages. When the host provides an `onUIAction` callback, the iframe will receive acknowledgment and response messages.

**Message Flow:**

1. **Iframe sends message with `messageId`:**
   ```javascript
   window.parent.postMessage({
     type: 'tool',
     messageId: 'unique-request-id-123',
     payload: { toolName: 'myAsyncTool', params: { data: 'some data' } }
   }, '*');
   ```

2. **Host responds with acknowledgment:**
   ```javascript
   // The iframe receives this message back
   {
     type: 'ui-message-received',
     messageId: 'unique-request-id-123',
   }
   ```

3. **When `onUIAction` completes successfully:**
   ```javascript
   // The iframe receives the actual response
   {
     type: 'ui-message-response',
     messageId: 'unique-request-id-123',
     payload: {
       response: { /* the result from onUIAction */ }
     }
   }
   ```

4. **If `onUIAction` encounters an error:**
   ```javascript
   // The iframe receives the error
   {
     type: 'ui-message-response',
     messageId: 'unique-request-id-123',
     payload: {
       error: { /* the error object */ }
     }
   }
   ```

**Complete Iframe Example with Async Handling:**

```html
<button onclick="handleAsyncAction()">Async Action</button>
<div id="status">Ready</div>
<div id="result"></div>

<script>
  let messageCounter = 0;
  const pendingRequests = new Map();

  function generateMessageId() {
    return `msg-${Date.now()}-${++messageCounter}`;
  }

  function handleAsyncAction() {
    const messageId = generateMessageId();
    const statusEl = document.getElementById('status');
    const resultEl = document.getElementById('result');
    
    statusEl.textContent = 'Sending request...';
    
    // Store the request context
    pendingRequests.set(messageId, { 
      startTime: Date.now(),
      action: 'async-tool-call'
    });
    
    // Send the message with messageId
    window.parent.postMessage({
      type: 'tool',
      messageId: messageId,
      payload: { 
        toolName: 'processData', 
        params: { data: 'example data', timestamp: Date.now() }
      }
    }, '*');
  }

  // Listen for responses from the host
  window.addEventListener('message', (event) => {
    const message = event.data;
    
    if (!message.messageId || !pendingRequests.has(message.messageId)) {
      return; // Not for us or unknown request
    }
    
    const statusEl = document.getElementById('status');
    const resultEl = document.getElementById('result');
    const request = pendingRequests.get(message.messageId);
    
    switch (message.type) {
      case 'ui-message-received':
        statusEl.textContent = 'Request acknowledged, processing...';
        break;
        
      case 'ui-message-response':
        if (message.payload.error) {
          statusEl.textContent = 'Error occurred!';
          resultEl.innerHTML = `<div style="color: red;">Error: ${JSON.stringify(message.payload.error)}</div>`;
          pendingRequests.delete(message.messageId);
          break;
        }
        statusEl.textContent = 'Completed successfully!';
        resultEl.innerHTML = `<pre>${JSON.stringify(message.payload.response, null, 2)}</pre>`;
        pendingRequests.delete(message.messageId);
        break;
    }
  });
</script>
```

### Message Types

The following internal message types are available as constants:

- `InternalMessageType.UI_MESSAGE_RECEIVED` (`'ui-message-received'`)
- `InternalMessageType.UI_MESSAGE_RESPONSE` (`'ui-message-response'`)

These types are exported from both `@mcp-ui/client` and `@mcp-ui/server` packages.

**Important Notes:**

- **Message ID is optional**: If you don't provide a `messageId`, the iframe will not receive response messages.
- **Only with `onUIAction`**: Response messages are only sent when the host provides an `onUIAction` callback.
- **Unique IDs**: Ensure `messageId` values are unique to avoid conflicts between multiple pending requests.
- **Cleanup**: Always clean up pending request tracking when you receive responses to avoid memory leaks.


================================================
FILE: docs/src/guide/server/python/overview.md
================================================
# mcp-ui-server Overview

The `mcp-ui-server` package provides utilities to generate UI resources (`UIResource`) on your MCP server. It allows you to define UI snippets on the server-side, which can then be seamlessly and securely rendered on the client.

::: tip MCP Apps Compatibility
The `create_ui_resource` function creates UIResource objects that work with both MCP Apps hosts (via `_meta.ui.resourceUri`) and legacy MCP-UI hosts.

For the recommended MCP Apps pattern with TypeScript, see [Getting Started](../../getting-started).
:::

For a complete example, see the [`python-server-demo`](https://github.com/idosal/mcp-ui/tree/main/examples/python-server-demo).

## Key Exports

- **`create_ui_resource(options_dict: dict[str, Any]) -> UIResource`**:
  The primary function for creating UI snippets. It takes a dictionary of options to define the URI, content (direct HTML or external URL), and encoding method (text or blob).

## Purpose

- **Ease of Use**: Simplifies the creation of valid `UIResource` objects.
- **Validation**: Includes basic validation (e.g., URI prefixes matching content type).
- **Encoding**: Handles Base64 encoding when `encoding: 'blob'` is specified.
- **MCP Integration**: Proper integration with the MCP Python SDK using `EmbeddedResource`.

## Installation

Install the package using pip or your preferred package manager:

```bash
pip install mcp-ui-server
```

Or with uv:

```bash
uv add mcp-ui-server
```

## Building

This package is built using Python's standard build tools and distributed via PyPI. It includes full type annotations and is compatible with Python 3.10+.

To build the package from source:

```bash
uv build
```

See the [Server SDK Usage & Examples](./usage-examples.md) page for practical examples.

================================================
FILE: docs/src/guide/server/python/usage-examples.md
================================================
# mcp-ui-server Usage & Examples

This page provides practical examples for using the `mcp-ui-server` package.

For a complete example, see the [`python-server-demo`](https://github.com/idosal/mcp-ui/tree/main/examples/python-server-demo).

## Basic Setup

First, ensure you have `mcp-ui-server` available in your project:

```bash
pip install mcp-ui-server
```

Or with uv:

```bash
uv add mcp-ui-server
```

## Basic Usage

The core function is `create_ui_resource`.

```python
from mcp_ui_server import create_ui_resource

# Example 1: Direct HTML, delivered as text
resource1 = create_ui_resource({
    "uri": "ui://my-component/instance-1",
    "content": {
        "type": "rawHtml", 
        "htmlString": "<p>Hello World</p>"
    },
    "encoding": "text"
})

print("Resource 1:", resource1.model_dump_json(indent=2))
# Output for Resource 1:
# {
#   "type": "resource",
#   "resource": {
#     "uri": "ui://my-component/instance-1",
#     "mimeType": "text/html;profile=mcp-app",
#     "text": "<p>Hello World</p>"
#   }
# }

# Example 2: Direct HTML, delivered as a Base64 blob
resource2 = create_ui_resource({
    "uri": "ui://my-component/instance-2",
    "content": {
        "type": "rawHtml", 
        "htmlString": "<h1>Complex HTML</h1>"
    },
    "encoding": "blob"
})

print("Resource 2 (blob will be Base64):", resource2.model_dump_json(indent=2))
# Output for Resource 2:
# {
#   "type": "resource",
#   "resource": {
#     "uri": "ui://my-component/instance-2",
#     "mimeType": "text/html;profile=mcp-app",
#     "blob": "PGgxPkNvbXBsZXggSFRNTDwvaDE+"
#   }
# }

# Example 3: External URL, text encoding
dashboard_url = "https://my.analytics.com/dashboard/123"
resource3 = create_ui_resource({
    "uri": "ui://analytics-dashboard/main",
    "content": {
        "type": "externalUrl", 
        "iframeUrl": dashboard_url
    },
    "encoding": "text"
})

print("Resource 3:", resource3.model_dump_json(indent=2))
# Output for Resource 3:
# {
#   "type": "resource",
#   "resource": {
#     "uri": "ui://analytics-dashboard/main",
#     "mimeType": "text/html;profile=mcp-app",
#     "text": "https://my.analytics.com/dashboard/123"
#   }
# }

# Example 4: External URL, blob encoding (URL is Base64 encoded)
chart_api_url = "https://charts.example.com/api?type=pie&data=1,2,3"
resource4 = create_ui_resource({
    "uri": "ui://live-chart/session-xyz",
    "content": {
        "type": "externalUrl", 
        "iframeUrl": chart_api_url
    },
    "encoding": "blob"
})

print("Resource 4 (blob will be Base64 of URL):", resource4.model_dump_json(indent=2))
# Output for Resource 4:
# {
#   "type": "resource",
#   "resource": {
#     "uri": "ui://live-chart/session-xyz",
#     "mimeType": "text/html;profile=mcp-app",
#     "blob": "aHR0cHM6Ly9jaGFydHMuZXhhbXBsZS5jb20vYXBpP3R5cGU9cGllJmRhdGE9MSwyLDM="
#   }
# }

# These resource objects would then be included in the 'content' array
# of a toolResult in an MCP interaction.
```

## Using with FastMCP

Here's how to use `create_ui_resource` with the FastMCP framework:

```python
import argparse
from mcp.server.fastmcp import FastMCP
from mcp_ui_server import create_ui_resource
from mcp_ui_server.core import UIResource

# Create FastMCP instance
mcp = FastMCP("my-server")

@mcp.tool()
def show_dashboard() -> list[UIResource]:
    """Display an analytics dashboard."""
    ui_resource = create_ui_resource({
        "uri": "ui://dashboard/analytics",
        "content": {
            "type": "externalUrl",
            "iframeUrl": "https://my.analytics.com/dashboard"
        },
        "encoding": "text"
    })
    return [ui_resource]

@mcp.tool()
def show_welcome() -> list[UIResource]:
    """Display a welcome message."""
    ui_resource = create_ui_resource({
        "uri": "ui://welcome/main",
        "content": {
            "type": "rawHtml",
            "htmlString": "<h1>Welcome to My MCP Server!</h1><p>How can I help you today?</p>"
        },
        "encoding": "text"
    })
    return [ui_resource]

if __name__ == "__main__":
    mcp.run()
```

## Error Handling

The `create_ui_resource` function will raise exceptions if invalid combinations are provided, for example:

- URI not starting with `ui://` for any content type
- Invalid content type specified

```python
from mcp_ui_server.exceptions import InvalidURIError

try:
    create_ui_resource({
        "uri": "invalid://should-be-ui",
        "content": {
            "type": "externalUrl", 
            "iframeUrl": "https://example.com"
        },
        "encoding": "text"
    })
except InvalidURIError as e:
    print(f"Caught expected error: {e}")
    # URI must start with 'ui://' but got: invalid://should-be-ui
```


================================================
FILE: docs/src/guide/server/python/walkthrough.md
================================================
# Python Server Walkthrough

This guide provides a step-by-step walkthrough for creating an MCP server with UI resources using `mcp-ui-server` and FastMCP.

For a complete, runnable example, see the [`python-server-demo`](https://github.com/idosal/mcp-ui/tree/main/examples/python-server-demo).

## 1. Set up Your Python Environment

First, create a new Python project and set up your dependencies:

```bash
# Create a new directory
mkdir my-mcp-server
cd my-mcp-server

# Initialize with uv (recommended) or pip
uv init
# or: python -m venv venv && source venv/bin/activate
```

## 2. Install Dependencies

Install the necessary packages:

```bash
uv add mcp mcp-ui-server
```

Or with pip:

```bash
pip install mcp mcp-ui-server
```

The `mcp` package provides FastMCP and core MCP functionality, while `mcp-ui-server` includes helpers for creating UI resources.

## 3. Create Your MCP Server

Create a file called `server.py`:

```python
import argparse
from mcp.server.fastmcp import FastMCP
from mcp_ui_server import create_ui_resource
from mcp_ui_server.core import UIResource

# Create FastMCP instance
mcp = FastMCP("my-mcp-server")

@mcp.tool()
def greet() -> list[UIResource]:
    """A simple greeting tool that returns a UI resource."""
    ui_resource = create_ui_resource({
        "uri": "ui://greeting/simple",
        "content": {
            "type": "rawHtml",
            "htmlString": """
                <div style="padding: 20px; text-align: center; font-family: Arial, sans-serif;">
                    <h1 style="color: #2563eb;">Hello from Python MCP Server!</h1>
                    <p>This UI resource was generated server-side using mcp-ui-server.</p>
                </div>
            """
        },
        "encoding": "text"
    })
    return [ui_resource]

if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="My MCP Server")
    parser.add_argument("--http", action="store_true", help="Use HTTP transport instead of stdio")
    parser.add_argument("--port", type=int, default=3000, help="Port for HTTP transport (default: 3000)")
    args = parser.parse_args()

    if args.http:
        print("🚀 Starting MCP server on HTTP (SSE transport)")
        mcp.settings.port = args.port
        mcp.run(transport="sse")
    else:
        print("🚀 Starting MCP server with stdio transport")
        mcp.run()
```

## 4. Add More UI Tools

Let's add more sophisticated tools with different types of UI resources:

```python
@mcp.tool()
def show_dashboard() -> list[UIResource]:
    """Display a sample dashboard with metrics."""
    dashboard_html = """
    <div style="padding: 20px; font-family: Arial, sans-serif;">
        <h1>Server Dashboard</h1>
        <div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); gap: 16px; margin-top: 20px;">
            <div style="background: #f0f9ff; border: 1px solid #0ea5e9; border-radius: 8px; padding: 16px;">
                <h3 style="margin-top: 0; color: #0369a1;">Active Connections</h3>
                <p style="font-size: 24px; font-weight: bold; margin: 0; color: #0c4a6e;">42</p>
            </div>
            <div style="background: #f0fdf4; border: 1px solid #22c55e; border-radius: 8px; padding: 16px;">
                <h3 style="margin-top: 0; color: #15803d;">CPU Usage</h3>
                <p style="font-size: 24px; font-weight: bold; margin: 0; color: #14532d;">23%</p>
            </div>
            <div style="background: #fefce8; border: 1px solid #eab308; border-radius: 8px; padding: 16px;">
                <h3 style="margin-top: 0; color: #a16207;">Memory Usage</h3>
                <p style="font-size: 24px; font-weight: bold; margin: 0; color: #713f12;">67%</p>
            </div>
        </div>
    </div>
    """
    
    ui_resource = create_ui_resource({
        "uri": "ui://dashboard/main",
        "content": {
            "type": "rawHtml",
            "htmlString": dashboard_html
        },
        "encoding": "text"
    })
    return [ui_resource]

@mcp.tool()
def show_external_site() -> list[UIResource]:
    """Display an external website in an iframe."""
    ui_resource = create_ui_resource({
        "uri": "ui://external/example",
        "content": {
            "type": "externalUrl",
            "iframeUrl": "https://example.com"
        },
        "encoding": "text"
    })
    return [ui_resource]

@mcp.tool()
def show_interactive_demo() -> list[UIResource]:
    """Show an interactive demo with buttons that send intents."""
    interactive_html = """
    <div style="padding: 20px; font-family: Arial, sans-serif;">
        <h2>Interactive Demo</h2>
        <p>Click the buttons below to send different types of actions back to the parent:</p>
        
        <div style="margin: 10px 0;">
            <button onclick="sendIntent('user_action', {type: 'button_click', id: 'demo'})" 
                    style="background: #2563eb; color: white; padding: 8px 16px; border: none; border-radius: 4px; margin: 5px; cursor: pointer;">
                Send Intent
            </button>
            <button onclick="sendToolCall('get_data', {source: 'ui'})" 
                    style="background: #059669; color: white; padding: 8px 16px; border: none; border-radius: 4px; margin: 5px; cursor: pointer;">
                Call Tool
            </button>
        </div>
        
        <div id="status" style="margin-top: 20px; padding: 10px; background: #f3f4f6; border-radius: 4px;">
            Ready - click a button to see the action
        </div>
    </div>
    
    <script>
        function sendIntent(intent, params) {
            const status = document.getElementById('status');
            status.innerHTML = `<strong>Intent sent:</strong> ${intent}<br><strong>Params:</strong> ${JSON.stringify(params)}`;
            
            if (window.parent) {
                window.parent.postMessage({
                    type: 'intent',
                    payload: { intent: intent, params: params }
                }, '*');
            }
        }
        
        function sendToolCall(toolName, params) {
            const status = document.getElementById('status');
            status.innerHTML = `<strong>Tool call:</strong> ${toolName}<br><strong>Params:</strong> ${JSON.stringify(params)}`;
            
            if (window.parent) {
                window.parent.postMessage({
                    type: 'tool',
                    payload: { toolName: toolName, params: params }
                }, '*');
            }
        }
    </script>
    """
    
    ui_resource = create_ui_resource({
        "uri": "ui://demo/interactive",
        "content": {
            "type": "rawHtml",
            "htmlString": interactive_html
        },
        "encoding": "text"
    })
    return [ui_resource]
```

## 5. Complete Server Example

Here's your complete `server.py` file:

```python
import argparse
from mcp.server.fastmcp import FastMCP
from mcp_ui_server import create_ui_resource
from mcp_ui_server.core import UIResource

# Create FastMCP instance
mcp = FastMCP("my-mcp-server")

@mcp.tool()
def greet() -> list[UIResource]:
    """A simple greeting tool that returns a UI resource."""
    ui_resource = create_ui_resource({
        "uri": "ui://greeting/simple",
        "content": {
            "type": "rawHtml",
            "htmlString": """
                <div style="padding: 20px; text-align: center; font-family: Arial, sans-serif;">
                    <h1 style="color: #2563eb;">Hello from Python MCP Server!</h1>
                    <p>This UI resource was generated server-side using mcp-ui-server.</p>
                </div>
            """
        },
        "encoding": "text"
    })
    return [ui_resource]

@mcp.tool()
def show_dashboard() -> list[UIResource]:
    """Display a sample dashboard with metrics."""
    dashboard_html = """
    <div style="padding: 20px; font-family: Arial, sans-serif;">
        <h1>Server Dashboard</h1>
        <div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); gap: 16px; margin-top: 20px;">
            <div style="background: #f0f9ff; border: 1px solid #0ea5e9; border-radius: 8px; padding: 16px;">
                <h3 style="margin-top: 0; color: #0369a1;">Active Connections</h3>
                <p style="font-size: 24px; font-weight: bold; margin: 0; color: #0c4a6e;">42</p>
            </div>
            <div style="background: #f0fdf4; border: 1px solid #22c55e; border-radius: 8px; padding: 16px;">
                <h3 style="margin-top: 0; color: #15803d;">CPU Usage</h3>
                <p style="font-size: 24px; font-weight: bold; margin: 0; color: #14532d;">23%</p>
            </div>
        </div>
    </div>
    """
    
    ui_resource = create_ui_resource({
        "uri": "ui://dashboard/main",
        "content": {
            "type": "rawHtml",
            "htmlString": dashboard_html
        },
        "encoding": "text"
    })
    return [ui_resource]

@mcp.tool()
def show_external_site() -> list[UIResource]:
    """Display an external website in an iframe."""
    ui_resource = create_ui_resource({
        "uri": "ui://external/example",
        "content": {
            "type": "externalUrl",
            "iframeUrl": "https://example.com"
        },
        "encoding": "text"
    })
    return [ui_resource]

@mcp.tool()
def show_interactive_demo() -> list[UIResource]:
    """Show an interactive demo with buttons that send intents."""
    interactive_html = """
    <div style="padding: 20px; font-family: Arial, sans-serif;">
        <h2>Interactive Demo</h2>
        <p>Click the button below to send an intent back to the parent:</p>
        
        <button onclick="sendIntent()" 
                style="background: #2563eb; color: white; padding: 10px 20px; border: none; border-radius: 4px; cursor: pointer;">
            Send Intent
        </button>
        
        <div id="status" style="margin-top: 20px; padding: 10px; background: #f3f4f6; border-radius: 4px;">
            Ready
        </div>
    </div>
    
    <script>
        function sendIntent() {
            const status = document.getElementById('status');
            status.innerHTML = 'Intent sent!';
            
            if (window.parent) {
                window.parent.postMessage({
                    type: 'intent',
                    payload: {
                        intent: 'demo_interaction',
                        params: { source: 'python-server', timestamp: new Date().toISOString() }
                    }
                }, '*');
            }
        }
    </script>
    """
    
    ui_resource = create_ui_resource({
        "uri": "ui://demo/interactive",
        "content": {
            "type": "rawHtml",
            "htmlString": interactive_html
        },
        "encoding": "text"
    })
    return [ui_resource]

if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="My MCP Server")
    parser.add_argument("--http", action="store_true", help="Use HTTP transport instead of stdio")
    parser.add_argument("--port", type=int, default=3000, help="Port for HTTP transport (default: 3000)")
    args = parser.parse_args()

    if args.http:
        print("🚀 Starting MCP server on HTTP (SSE transport)")
        print("📡 Server will use SSE transport settings")
        mcp.settings.port = args.port
        mcp.run(transport="sse")
    else:
        print("🚀 Starting MCP server with stdio transport")
        mcp.run()
```

## 6. Run Your Server

You can run your server in two modes:

**Stdio Mode (for command-line clients):**
```bash
python server.py
```

**HTTP Mode (for web clients):**
```bash
python server.py --http --port 3000
```

## 7. Test with UI Inspector

To test your server with a visual interface:

1. Go to the [ui-inspector repository](https://github.com/idosal/ui-inspector) and run it locally
2. Open the inspector in your browser (usually `http://localhost:6274`)
3. Configure the connection:
   - **Transport Type**: "SSE" (for HTTP mode) or "Stdio" (for stdio mode)
   - **Server URL**: `http://localhost:3000/sse` (for HTTP mode)
4. Click "Connect"

The inspector will show your tools:
- **greet**: Simple HTML greeting
- **show_dashboard**: Dashboard with metrics
- **show_external_site**: External website iframe
- **show_interactive_demo**: Interactive buttons with intents

When you call these tools, the UI resources will be rendered in the inspector's Tool Results panel.

## 8. Next Steps

Now that you have a working MCP server with UI resources, you can:

1. **Add more tools** with different types of content
2. **Handle user interactions** by implementing tools that respond to intents
3. **Create dynamic content** based on tool parameters
4. **Integrate with external APIs** to display live data
5. **Use blob encoding** for larger or binary content

For more examples and advanced usage, see the [Usage Examples](./usage-examples.md) documentation.

## Tips for Development

- Use `encoding: "text"` for simple HTML content
- Use `encoding: "blob"` for larger content or when you need Base64 encoding
- Always prefix URIs with `ui://` followed by your component identifier
- Test both stdio and HTTP transports depending on your use case
- Use the ui-inspector for visual testing and debugging

You've successfully created a Python MCP server with UI resources! The FastMCP framework makes it easy to create tools that return rich, interactive UI content to MCP clients.

================================================
FILE: docs/src/guide/server/ruby/overview.md
================================================
# mcp_ui_server Overview

The `mcp_ui_server` gem provides server-side utilities in Ruby to help construct `UIResource` objects, which can then be sent to a client as part of an MCP response.

::: tip MCP Apps Compatibility
The `create_ui_resource` method creates UIResource objects that work with both MCP Apps hosts (via `_meta.ui.resourceUri`) and legacy MCP-UI hosts.

For the recommended MCP Apps pattern with TypeScript, see [Getting Started](../../getting-started).
:::

## Key Methods

- **`McpUiServer.create_ui_resource(options)`**:
  The primary method for creating UI snippets. It takes an options hash to define the URI, content (direct HTML or external URL), and encoding method.

## Purpose

- **Ease of Use**: Simplifies the creation of valid `UIResource` objects in Ruby.
- **Validation**: Includes basic validation (e.g., URI prefixes matching content type).
- **Encoding**: Handles Base64 encoding automatically.

## Installation

Add this line to your application's Gemfile:

```ruby
gem 'mcp_ui_server'
```

And then execute:

```bash
$ bundle install
```

Or install it yourself as:

```bash
$ gem install mcp_ui_server
```

See the [Server SDK Usage & Examples](./usage-examples.md) page for practical examples.


================================================
FILE: docs/src/guide/server/ruby/usage-examples.md
================================================
# mcp_ui_server Usage & Examples

This page provides practical examples for using the `mcp_ui_server` gem.

For a complete, runnable server implementation that demonstrates how to use these resources within an MCP tool, see the Ruby server demo (`/examples/ruby-server-demo/server.rb`).

## Basic Setup

First, ensure you have `mcp_ui_server` available in your project by adding it to your Gemfile and running `bundle install`.

```ruby
require 'mcp_ui_server'
require 'json'

# Example 1: Direct HTML, delivered as text
resource1 = McpUiServer.create_ui_resource(
  uri: 'ui://my-component/instance-1',
  content: { type: :raw_html, htmlString: '<p>Hello World</p>' },
  encoding: :text
)
puts "Resource 1: #{JSON.pretty_generate(resource1)}"
# Output for Resource 1:
# {
#   "type": "resource",
#   "resource": {
#     "uri": "ui://my-component/instance-1",
#     "mimeType": "text/html;profile=mcp-app",
#     "text": "<p>Hello World</p>"
#   }
# }

# Example 2: Direct HTML, delivered as a Base64 blob
resource2 = McpUiServer.create_ui_resource(
  uri: 'ui://my-component/instance-2',
  content: { type: :raw_html, htmlString: '<h1>Complex HTML</h1>' },
  encoding: :blob
)
puts "Resource 2 (blob will be Base64): #{JSON.pretty_generate(resource2)}"
# Output for Resource 2:
# {
#   "type": "resource",
#   "resource": {
#     "uri": "ui://my-component/instance-2",
#     "mimeType": "text/html;profile=mcp-app",
#     "blob": "PGgxPkNvbXBsZXggSFRNTDwvaDE+"
#   }
# }

# Example 3: External URL, text encoding
dashboard_url = 'https://my.analytics.com/dashboard/123'
resource3 = McpUiServer.create_ui_resource(
  uri: 'ui://analytics-dashboard/main',
  content: { type: :external_url, iframeUrl: dashboard_url },
  encoding: :text
)
puts "Resource 3: #{JSON.pretty_generate(resource3)}"
# Output for Resource 3:
# {
#   "type": "resource",
#   "resource": {
#     "uri": "ui://analytics-dashboard/main",
#     "mimeType": "text/html;profile=mcp-app",
#     "text": "https://my.analytics.com/dashboard/123"
#   }
# }

# Example 4: External URL, blob encoding (URL is Base64 encoded)
chart_api_url = 'https://charts.example.com/api?type=pie&data=1,2,3'
resource4 = McpUiServer.create_ui_resource(
  uri: 'ui://live-chart/session-xyz',
  content: { type: :external_url, iframeUrl: chart_api_url },
  encoding: :blob
)
puts "Resource 4 (blob will be Base64 of URL): #{JSON.pretty_generate(resource4)}"
# Output for Resource 4:
# {
#   "type": "resource",
#   "resource": {
#     "uri": "ui://live-chart/session-xyz",
#     "mimeType": "text/html;profile=mcp-app",
#     "blob": "aHR0cHM6Ly9jaGFydHMuZXhhbXBsZS5jb20vYXBpP3R5cGU9cGllJmRhdGE9MSwyLDM="
#   }
# }

# These resource objects would then be included in the 'content' array
# of a toolResult in an MCP interaction.
```

## Error Handling

The `create_ui_resource` method will raise an `ArgumentError` if invalid combinations are provided.

```ruby
begin
  McpUiServer.create_ui_resource(
    uri: 'invalid://should-be-ui',
    content: { type: :external_url, iframeUrl: 'https://example.com' },
    encoding: :text
  )
rescue ArgumentError => e
  puts "Caught expected error: #{e.message}"
  # => Caught expected error: URI must start with 'ui://' for externalUrl content type.
end
```


================================================
FILE: docs/src/guide/server/ruby/walkthrough.md
================================================
# Ruby Server Walkthrough

This guide provides a step-by-step walkthrough for creating a barebones MCP UI server using Ruby's built-in WEBrick library.

For a complete, runnable example, see the [`ruby-server-demo`](https://github.com/idosal/mcp-ui/tree/main/examples/ruby-server-demo).

## 1. Project Setup

First, set up your project directory and dependencies.

Create a `Gemfile` with the necessary gems:

```ruby
source "https://rubygems.org"

gem "mcp", git: "https://github.com/modelcontextprotocol/ruby-sdk"
gem "mcp_ui_server"
```

The `mcp` gem is the core Model Context Protocol SDK, while `mcp_ui_server` provides helpers for creating UI resources.

Install the dependencies:

```sh
bundle install
```

Create an empty `server.rb` file. We will add code to it in the next steps.

```sh
touch server.rb
```

## 2. Create an MCP Tool

In MCP, a "tool" is a class that can be invoked by a client. For this example, we'll create a tool that returns a `UIResource` containing an external URL.

Add the following to your `server.rb`:

```ruby
require 'mcp'
require 'mcp_ui_server'
require 'webrick'
require 'json'

class ExternalUrlTool < MCP::Tool
  description 'A simple tool that returns an external URL resource'
  input_schema(
    type: 'object',
    properties: {}
  )

  def self.call(server_context:)
    ui_resource_object = McpUiServer.create_ui_resource(
      uri: 'ui://my-external-site',
      content: { type: :external_url, iframeUrl: 'https://example.com' },
      encoding: :text
    )

    MCP::Tool::Response.new([ui_resource_object])
  end
end
```

The `require 'mcp_ui_server'` line imports the mcp-ui library. The `ExternalUrlTool` is a standard MCP `Tool`, but it uses `McpUiServer.create_ui_resource` to return a `UIResource`, which is the primary integration point with `mcp-ui`. The following sections describe how to set up a standard MCP server and expose it over HTTP.

## 3. Set Up the MCP Server

Next, instantiate the MCP server and register the tool with it.

Add this to `server.rb`:

```ruby
# --- MCP Server Setup ---
mcp_server = MCP::Server.new(tools: [ExternalUrlTool])
```

## 4. Set Up an HTTP Server

We'll use WEBrick to create a simple HTTP server to handle MCP requests.

Add the following to `server.rb` to create an HTTP server that listens on port 8081 and handles requests at the `/mcp` endpoint:

```ruby
# --- WEBrick HTTP Server Setup ---
http_server = WEBrick::HTTPServer.new(Port: 8081)

# Create a servlet to handle requests to /mcp
class MCPServlet < WEBrick::HTTPServlet::AbstractServlet
  def initialize(server, mcp_instance)
    super(server)
    @mcp = mcp_instance
  end

  # Handle pre-flight CORS requests
  def do_OPTIONS(_request, response)
    response.status = 200
    response['Access-Control-Allow-Origin'] = '*'
    response['Access-Control-Allow-Methods'] = 'POST, OPTIONS'
    response['Access-Control-Allow-Headers'] = 'Content-Type, Accept'
  end

  def do_POST(request, response)
    response['Access-control-Allow-Origin'] = '*'
    response.status = 200
    response['Content-Type'] = 'application/json'
    response.body = @mcp.handle_json(request.body)
  end
end

# Mount the servlet at the /mcp endpoint
http_server.mount('/mcp', MCPServlet, mcp_server)
```

The `MCPServlet` processes incoming `POST` requests, passes them to the MCP server instance, and returns the JSON response. It also handles CORS `OPTIONS` requests to allow cross-origin communication with a web client.

## 5. Run and Test

Finally, add the code to start the server.

```ruby
# Start the server and handle shutdown
trap('INT') { http_server.shutdown }
puts 'MCP server running on http://localhost:8081/mcp'
http_server.start
```

Your `server.rb` is now complete. You can run it with:

```sh
ruby server.rb
```

The server will be available at `http://localhost:8081/mcp`.

To test your new endpoint, you can use the [`ui-inspector`](https://github.com/idosal/ui-inspector):

1. Go to the [ui-inspector repo](https://github.com/idosal/ui-inspector/) and run locally.
2. Open the local client in a browser (usually `http://localhost:6274`)
3. Change the Transport Type to "Streamable HTTP".
4. Enter your server's MCP endpoint URL: `http://localhost:8081/mcp`.
5. Click "Connect".

The inspector will show tools for the different content types. When you call them, the UI resource will be rendered in the inspector's Tool Results.

You've now successfully integrated `mcp-ui` into your Ruby server! You can now create more complex tools that return different types of UI resources. 

================================================
FILE: docs/src/guide/server/typescript/overview.md
================================================
# @mcp-ui/server Overview

The `@mcp-ui/server` package provides utilities to build MCP Apps - tools with interactive UIs. It works with `@modelcontextprotocol/ext-apps` to implement the MCP Apps standard.

For a complete example, see the [`typescript-server-demo`](https://github.com/idosal/mcp-ui/tree/docs/ts-example/examples/typescript-server-demo).

## MCP Apps Pattern (Recommended)

```typescript
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { registerAppTool, registerAppResource } from '@modelcontextprotocol/ext-apps/server';
import { createUIResource } from '@mcp-ui/server';
import { z } from 'zod';

// 1. Create UI content
const widgetUI = await createUIResource({
  uri: 'ui://my-server/widget',
  content: { type: 'rawHtml', htmlString: '<h1>Widget</h1>' },
  encoding: 'text',
});

// 2. Register resource handler
registerAppResource(server, 'widget_ui', widgetUI.resource.uri, {}, async () => ({
  contents: [widgetUI.resource]
}));

// 3. Register tool with _meta.ui.resourceUri
registerAppTool(server, 'show_widget', {
  description: 'Show widget',
  inputSchema: { query: z.string() },
  _meta: { ui: { resourceUri: widgetUI.resource.uri } }
}, async ({ query }) => {
  return { content: [{ type: 'text', text: `Query: ${query}` }] };
});
```

## Key Exports

- **`createUIResource(options: CreateUIResourceOptions): Promise<UIResource>`**:
  Creates UI resource objects. For `externalUrl` content, fetches the URL, injects a `<base>` tag, and auto-populates `_meta.csp.baseUriDomains` with the external origin. Use with `registerAppTool` and `registerAppResource` from `@modelcontextprotocol/ext-apps/server`.

## Purpose

- **MCP Apps Compliance**: Implements the MCP Apps standard for tool UIs
- **Ease of Use**: Simplifies the creation of valid `UIResource` objects
- **Validation**: Includes basic validation (e.g., URI prefixes matching content type)
- **Encoding**: Handles Base64 encoding when `encoding: 'blob'` is specified
- **Metadata Support**: Provides flexible metadata configuration for enhanced client-side rendering

## Metadata Features

The `createUIResource()` function supports three types of metadata configuration to enhance resource functionality:

### `metadata`
Standard MCP resource metadata that becomes the `_meta` property on the resource. This follows the MCP specification for resource metadata.

### `uiMetadata`
MCP-UI specific configuration options. These keys are automatically prefixed with `mcpui.dev/ui-` in the resource metadata:

- **`preferred-frame-size`**: Define the resource's preferred initial frame size (e.g., `{ width: 800, height: 600 }`)
- **`initial-render-data`**: Provide data that should be passed to the iframe when rendering

### `resourceProps`
Additional properties that are spread directly onto the actual resource definition, allowing you to add/override any MCP specification-supported properties.

### `embeddedResourceProps`
Additional properties that are spread directly onto the embedded resource top-level definition, allowing you to add any MCP embedded resource [specification-supported](https://modelcontextprotocol.io/specification/2025-06-18/schema#embeddedresource) properties, like `annotations`.

## Building

This package is built using Vite in library mode, targeting Node.js environments. It outputs ESM (`.mjs`) and CJS (`.js`) formats, along with TypeScript declaration files (`.d.ts`).

To build specifically this package from the monorepo root:

```bash
pnpm build --filter @mcp-ui/server
```

See the [Server SDK Usage & Examples](./usage-examples.md) page for practical examples.


================================================
FILE: docs/src/guide/server/typescript/usage-examples.md
================================================
# @mcp-ui/server Usage & Examples

This page provides practical examples for using the `@mcp-ui/server` package.

For a complete example, see the [`typescript-server-demo`](https://github.com/idosal/mcp-ui/tree/docs/ts-example/examples/typescript-server-demo).

## Installation

```bash
npm i @mcp-ui/server @modelcontextprotocol/ext-apps
```

## MCP Apps Pattern (Recommended)

The MCP Apps pattern uses `registerAppTool` with `_meta.ui.resourceUri` to link tools to their UIs:

```typescript
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { registerAppTool, registerAppResource } from '@modelcontextprotocol/ext-apps/server';
import { createUIResource } from '@mcp-ui/server';
import { z } from 'zod';

const server = new McpServer({ name: 'my-server', version: '1.0.0' });

// Create UI resource with MCP Apps protocol
const widgetUI = await createUIResource({
  uri: 'ui://my-server/widget',
  content: {
    type: 'rawHtml',
    htmlString: `
      <html>
        <body>
          <h1>Interactive Widget</h1>
          <button onclick="sendMessage()">Send Message</button>
          <div id="status">Ready</div>
          <script type="module">
            import { App } from 'https://esm.sh/@modelcontextprotocol/ext-apps@0.4.1';

            const app = new App({ name: 'widget', version: '1.0.0' });

            // Listen for tool input
            app.ontoolinput = (params) => {
              document.getElementById('status').textContent =
                'Received: ' + JSON.stringify(params.input);
            };

            // Send a message to the conversation
            window.sendMessage = async () => {
              await app.sendMessage({
                role: 'user',
                content: [{ type: 'text', text: 'Tell me more' }]
              });
            };

            await app.connect();
          </script>
        </body>
      </html>
    `,
  },
  encoding: 'text',
});

// Register resource handler
registerAppResource(server, 'widget_ui', widgetUI.resource.uri, {}, async () => ({
  contents: [widgetUI.resource]
}));

// Register tool with _meta.ui.resourceUri
registerAppTool(server, 'show_widget', {
  description: 'Show an interactive widget',
  inputSchema: {
    query: z.string().describe('User query'),
  },
  _meta: {
    ui: {
      resourceUri: widgetUI.resource.uri  // Links tool to UI
    }
  }
}, async ({ query }) => {
  return {
    content: [{ type: 'text', text: `Processing: ${query}` }]
  };
});
```

::: tip MCP Apps Protocol
The HTML uses the [`@modelcontextprotocol/ext-apps`](https://github.com/modelcontextprotocol/ext-apps) `App` class for communication with the host. See [Protocol Details](/guide/protocol-details) for the full JSON-RPC API. For legacy MCP-UI hosts, see the [MCP Apps Adapter](/guide/mcp-apps).
:::

## Creating UI Resources

The core function is `createUIResource`.

```typescript
import {
  createUIResource,
} from '@mcp-ui/server';

// Using a shared enum value (just for demonstration)
console.log('Shared Enum from server usage:', PlaceholderEnum.FOO);

// Example 1: Direct HTML, delivered as text
const resource1 = await createUIResource({
  uri: 'ui://my-component/instance-1',
  content: { type: 'rawHtml', htmlString: '<p>Hello World</p>' },
  encoding: 'text',
});
console.log('Resource 1:', JSON.stringify(resource1, null, 2));
/* Output for Resource 1:
{
  "type": "resource",
  "resource": {
    "uri": "ui://my-component/instance-1",
    "mimeType": "text/html;profile=mcp-app",
    "text": "<p>Hello World</p>"
  }
}
*/

// Example 2: Direct HTML, delivered as a Base64 blob
const resource2 = await createUIResource({
  uri: 'ui://my-component/instance-2',
  content: { type: 'rawHtml', htmlString: '<h1>Complex HTML</h1>' },
  encoding: 'blob',
});
console.log(
  'Resource 2 (blob will be Base64):',
  JSON.stringify(resource2, null, 2),
);
/* Output for Resource 2:
{
  "type": "resource",
  "resource": {
    "uri": "ui://my-component/instance-2",
    "mimeType": "text/html;profile=mcp-app",
    "blob": "PGgxPkNvbXBsZXggSFRNTDwvaDE+"
  }
}
*/

// Example 3: External URL — fetches the page HTML and injects a <base> tag
const dashboardUrl = 'https://my.analytics.com/dashboard/123';
const resource3 = await createUIResource({
  uri: 'ui://analytics-dashboard/main',
  content: { type: 'externalUrl', iframeUrl: dashboardUrl },
  encoding: 'text',
});
// resource3.resource.text contains the fetched HTML with:
//   <base href="https://my.analytics.com/dashboard/123">
// injected so relative paths resolve correctly.

// Example 4: External URL, blob encoding (fetched HTML is Base64 encoded)
const chartApiUrl = 'https://charts.example.com/api?type=pie&data=1,2,3';
const resource4 = await createUIResource({
  uri: 'ui://live-chart/session-xyz',
  content: { type: 'externalUrl', iframeUrl: chartApiUrl },
  encoding: 'blob',
});
// resource4.resource.blob contains the Base64-encoded fetched HTML.

// These resource objects would then be included in the 'content' array
// of a toolResult in an MCP interaction.
```

## Metadata Configuration Examples

The `createUIResource` function supports several types of metadata configuration to enhance your UI resources:

```typescript
import { createUIResource } from '@mcp-ui/server';

// Example 7: Using standard metadata
const resourceWithMetadata = await createUIResource({
  uri: 'ui://analytics/dashboard',
  content: { type: 'rawHtml', htmlString: '<div id="dashboard">Loading...</div>' },
  encoding: 'text',
  metadata: {
    title: 'Analytics Dashboard',
    description: 'Real-time analytics and metrics',
    created: '2024-01-15T10:00:00Z',
    author: 'Analytics Team',
    preferredRenderContext: 'sidebar'
  }
});
console.log('Resource with metadata:', JSON.stringify(resourceWithMetadata, null, 2));
/* Output includes:
{
  "type": "resource",
  "resource": {
    "uri": "ui://analytics/dashboard",
    "mimeType": "text/html;profile=mcp-app",
    "text": "<div id=\"dashboard\">Loading...</div>",
    "_meta": {
      "title": "Analytics Dashboard",
      "description": "Real-time analytics and metrics",
      "created": "2024-01-15T10:00:00Z",
      "author": "Analytics Team",
      "preferredRenderContext": "sidebar"
    }
  }
}
*/

// Example 8: Using uiMetadata for client-side configuration
const resourceWithUIMetadata = await createUIResource({
  uri: 'ui://chart/interactive',
  content: { type: 'rawHtml', htmlString: '<div id="chart">Loading...</div>' },
  encoding: 'text',
  uiMetadata: {
    'preferred-frame-size': ['800px', '600px'],
    'initial-render-data': {
      theme: 'dark',
      chartType: 'bar',
      dataSet: 'quarterly-sales'
    },
  }
});
console.log('Resource with UI metadata:', JSON.stringify(resourceWithUIMetadata, null, 2));
/* Output includes:
{
  "type": "resource",
  "resource": {
    "uri": "ui://chart/interactive",
    "mimeType": "text/html;profile=mcp-app",
    "text": "<div id=\"chart\">Loading...</div>",
    "_meta": {
      "mcpui.dev/ui-preferred-frame-size": ["800px", "600px"],
      "mcpui.dev/ui-initial-render-data": {
        "theme": "dark",
        "chartType": "bar",
        "dataSet": "quarterly-sales"
      },
    }
  }
}
*/

// Example 9: Using embeddedResourceProps for additional MCP properties
const resourceWithProps = await createUIResource({
  uri: 'ui://form/user-profile',
  content: { type: 'rawHtml', htmlString: '<form id="profile">...</form>' },
  encoding: 'text',
  embeddedResourceProps: {
    annotations: {
      audience: ['user'],
      priority: 'high'
    }
  }
});
console.log('Resource with additional props:', JSON.stringify(resourceWithProps, null, 2));
/* Output includes:
{
  "type": "resource",
  "resource": {
    "uri": "ui://form/user-profile",
    "mimeType": "text/html;profile=mcp-app",
    "text": "<form id=\"profile\">...</form>",
  },
  "annotations": {
    "audience": ["user"],
    "priority": "high"
  }
}
*/
```

### Metadata Best Practices

- **Use `metadata` for standard MCP resource information** like titles, descriptions, timestamps, and authorship
- **Use `uiMetadata` for client rendering hints** like preferred sizes, initial data, and context preferences  
- **Use `resourceProps` for MCP specification properties**, descriptions at the resource level, and other standard fields
- **Use `embeddedResourceProps` for MCP embedded resource properties** like annotations.

## Error Handling

The `createUIResource` function will throw errors if invalid combinations are provided, for example:

- URI not starting with `ui://` for any content type
- Invalid content type specified

```typescript
try {
  await createUIResource({
    uri: 'invalid://should-be-ui',
    content: { type: 'externalUrl', iframeUrl: 'https://example.com' },
    encoding: 'text',
  });
} catch (e: any) {
  console.error('Caught expected error:', e.message);
  // MCP-UI SDK: URI must start with 'ui://'.
}
```

================================================
FILE: docs/src/guide/server/typescript/walkthrough.md
================================================
# TypeScript Server Walkthrough

This guide provides a step-by-step walkthrough for integrating `@mcp-ui/server` into a an existing Node.js server using the [Express.js](https://expressjs.com) framework.

For a complete, runnable example, see the [`typescript-server-demo`](https://github.com/idosal/mcp-ui/tree/main/examples/typescript-server-demo).

## 1. Set up an Express Server

If you don't have an existing server, you can create a simple one.

First, install the necessary dependencies:

```bash
npm install express cors @types/express @types/cors
```

Then, create a basic server file (e.g., `server.ts`):

```typescript
import express from 'express';
import cors from 'cors';

const app = express();
const port = 3000;

app.use(cors());
app.use(express.json());

app.get('/', (req, res) => {
  res.send('Hello, world!');
});

app.listen(port, () => {
  console.log(`Server listening at http://localhost:${port}`);
});
```

## 2. Install MCP and mcp-ui Dependencies

Next, add the Model Context Protocol SDK and the `mcp-ui` server package to your project:

```bash
npm install @modelcontextprotocol/sdk @mcp-ui/server
```

The `@modelcontextprotocol/sdk` package provides the core functionality for creating an MCP server, while `@mcp-ui/server` includes helpers specifically for creating UI resources.

## 3. Set up the MCP Server Handler

In MCP, tools are functions that the client can invoke. For this example, we'll create a tool that returns a `UIResource`.
Now, let's create an MCP server instance and an endpoint to handle MCP requests using a streaming transport. This allows for more complex, stateful interactions.

Modify your `server.ts` file to include the following:

```typescript
import express from 'express';
import cors from 'cors';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
import { createUIResource } from '@mcp-ui/server';
import { randomUUID } from 'crypto';

const app = express();
const port = 3000;

app.use(cors({
  origin: '*',
  exposedHeaders: ['Mcp-Session-Id'],
  allowedHeaders: ['Content-Type', 'mcp-session-id'],
}));
app.use(express.json());

// Map to store transports by session ID
const transports: { [sessionId: string]: StreamableHTTPServerTransport } = {};

// Handle POST requests for client-to-server communication.
app.post('/mcp', async (req, res) => {
  const sessionId = req.headers['mcp-session-id'] as string | undefined;
  let transport: StreamableHTTPServerTransport;

  if (sessionId && transports[sessionId]) {
    // A session already exists; reuse the existing transport.
    transport = transports[sessionId];
  } else if (!sessionId && isInitializeRequest(req.body)) {
    // This is a new initialization request. Create a new transport.
    transport = new StreamableHTTPServerTransport({
      sessionIdGenerator: () => randomUUID(),
      onsessioninitialized: (sid) => {
        transports[sid] = transport;
        console.log(`MCP Session initialized: ${sid}`);
      },
    });

    // Clean up the transport from our map when the session closes.
    transport.onclose = () => {
      if (transport.sessionId) {
        console.log(`MCP Session closed: ${transport.sessionId}`);
        delete transports[transport.sessionId];
      }
    };
    
    // Create a new server instance for this specific session.
    const server = new McpServer({
      name: "typescript-server-walkthrough",
      version: "1.0.0"
    });

    // Register our MCP-UI tool on the new server instance.
    server.registerTool('greet', {
      title: 'Greet',
      description: 'A simple tool that returns a UI resource.',
      inputSchema: {},
    }, async () => {
      // Create the UI resource to be returned to the client (this is the only part specific to MCP-UI)
      // For externalUrl, the SDK fetches the page HTML and injects a <base> tag
      const uiResource = await createUIResource({
        uri: 'ui://greeting',
        content: { type: 'externalUrl', iframeUrl: 'https://example.com' },
        encoding: 'text',
      });

      return {
        content: [uiResource],
      };
    });
  
    // Connect the server instance to the transport for this session.
    await server.connect(transport);
  } else {
    return res.status(400).json({
      error: { message: 'Bad Request: No valid session ID provided' },
    });
  }

  // Handle the client's request using the session's transport.
  await transport.handleRequest(req, res, req.body);
});

// A separate, reusable handler for GET and DELETE requests.
const handleSessionRequest = async (req: express.Request, res: express.Response) => {
  const sessionId = req.headers['mcp-session-id'] as string | undefined;
  if (!sessionId || !transports[sessionId]) {
    return res.status(404).send('Session not found');
  }
  
  const transport = transports[sessionId];
  await transport.handleRequest(req, res);
};

// GET handles the long-lived stream for server-to-client messages.
app.get('/mcp', handleSessionRequest);

// DELETE handles explicit session termination from the client.
app.delete('/mcp', handleSessionRequest);

app.listen(port, () => {
  console.log(`Server listening at http://localhost:${port}`);
  console.log(`MCP endpoint available at http://localhost:${port}/mcp`);
});
```

## 4. Run and Test

You can now run your server:

```bash
npx ts-node server.ts
```

To test your new endpoint, you can use the [`ui-inspector`](https://github.com/idosal/ui-inspector):

1. Go to the [ui-inspector repo](https://github.com/idosal/ui-inspector/) and run locally.
2. Open the local client in a browser (usually `http://localhost:6274`)
3. Change the Transport Type to "Streamable HTTP".
4. Enter your server's MCP endpoint URL: `http://localhost:3000/mcp`.
5. Click "Connect".

The inspector will show the "Greet" tool. When you call it, the UI resource will be rendered in the inspector's Tool Results.

You've now successfully integrated `mcp-ui` into your TypeScript server! You can now create more complex tools that return different types of UI resources.


================================================
FILE: docs/src/guide/supported-hosts.md
================================================
# Supported Hosts

The `@mcp-ui/*` packages work with both MCP Apps hosts and legacy MCP-UI hosts.

## MCP Apps Hosts

These hosts implement the [MCP Apps SEP protocol](https://github.com/modelcontextprotocol/ext-apps) and support tools with `_meta.ui.resourceUri`:

| Host | Support | Notes |
| :--- | :-------: | :---- |
| [Claude](https://www.claude.ai/) | ✅ | ✅ |
| [VSCode](https://github.com/microsoft/vscode/issues/260218) | ✅ | |
| [Postman](https://www.postman.com/) | ✅ | |
| [Goose](https://block.github.io/goose/) | ✅ | |
| [MCPJam](https://www.mcpjam.com/) | ✅ | |
| [LibreChat](https://www.librechat.ai/) | ✅ | |
| [mcp-use](https://mcp-use.com/) | ✅ | |
| [Smithery](https://smithery.ai/playground) | ✅ | |

For MCP Apps hosts, use `AppRenderer` on the client side:

```tsx
import { AppRenderer } from '@mcp-ui/client';

<AppRenderer
  client={client}
  toolName={toolName}
  sandbox={{ url: sandboxUrl }}
  toolInput={toolInput}
  toolResult={toolResult}
/>
```

## Other Hosts

| Host | Rendering | UI Actions | Notes |
| :--- | :-------: | :--------: | :---- |
| [ChatGPT](https://chatgpt.com/) | ✅ | ⚠️ | [Apps SDK Guide](./apps-sdk.md) |
| [Nanobot](https://www.nanobot.ai/) | ✅ | ✅ |
| [fast-agent](https://fast-agent.ai/mcp/mcp-ui/) | ✅ | ❌ | |

## Legend

- ✅: Fully Supported
- ⚠️: Partial Support
- ❌: Not Supported (yet)


================================================
FILE: docs/src/index.md
================================================
---
layout: home

hero:
  name: MCP-UI -> MCP Apps
  text: Interactive UI Components over MCP
  tagline: Build rich, dynamic interfaces for AI tools using the MCP Apps standard.
  image:
    light: /logo-lg-black.png
    dark: /logo-lg.png
    alt: MCP-UI Logo
  actions:
    - theme: brand
      text: Get Started
      link: /guide/introduction
    - theme: alt
      text: GitHub
      link: https://github.com/idosal/mcp-ui
    - theme: alt
      text: About
      link: /about

features:
  - title: 🌐 MCP Apps Standard
    details: MCP Apps is the official standard for interactive UI in MCP. The MCP-UI packages implement the spec, and serve as a community playground for future enhancements.
  - title: 🛠️ Client & Server SDKs
    details: The recommended MCP Apps Client SDK, with components for seamless integration. Includes server SDK with utilities.
  - title: 🔒 Secure
    details: All remote code executes in sandboxed iframes, ensuring host and user security while maintaining rich interactivity.
  - title: 🎨 Flexible
    details: Supports HTML content. Works with MCP Apps hosts and legacy MCP-UI hosts alike.
---

<!-- ## See MCP-UI in Action -->
<div style="display: flex; flex-direction: column; align-items: center; margin: 3rem 0 2rem 0;">
<span class="text animated-gradient-text" style="font-size: 30px; font-family: var(--vp-font-family-base); font-weight: 600;
    letter-spacing: -0.01em; margin-bottom: 0.5rem; text-align: center; line-height: 1.2;">See it in action</span>
<div class="video-container" style="display: flex; justify-content: center; align-items: center;">
  <video controls width="100%" style="max-width: 800px; border-radius: 8px; box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);">
    <source src="https://github.com/user-attachments/assets/7180c822-2dd9-4f38-9d3e-b67679509483" type="video/mp4">
    Your browser does not support the video tag.
  </video>
</div>
</div>

## Quick Example

**Client Side** - Render tool UIs with `AppRenderer`:

```tsx
import { AppRenderer } from '@mcp-ui/client';

function ToolUI({ client, toolName, toolInput, toolResult }) {
  return (
    <AppRenderer
      client={client}
      toolName={toolName}
      sandbox={{ url: sandboxUrl }}
      toolInput={toolInput}
      toolResult={toolResult}
      onOpenLink={async ({ url }) => {
        // Validate URL scheme before opening
        if (url.startsWith('https://') || url.startsWith('http://')) {
          window.open(url);
        }
      }}
      onMessage={async (params) => console.log('Message:', params)}
    />
  );
}
```

**Server Side** - Create a tool with an interactive UI using `_meta.ui.resourceUri`:

```typescript
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { registerAppTool, registerAppResource } from '@modelcontextprotocol/ext-apps/server';
import { createUIResource } from '@mcp-ui/server';
import { z } from 'zod';

const server = new McpServer({ name: 'my-server', version: '1.0.0' });

// Create the UI resource
const widgetUI = createUIResource({
  uri: 'ui://my-server/widget',
  content: { type: 'rawHtml', htmlString: '<h1>Interactive Widget</h1>' },
  encoding: 'text',
});

// Register the resource handler
registerAppResource(server, 'widget_ui', widgetUI.resource.uri, {}, async () => ({
  contents: [widgetUI.resource]
}));

// Register the tool with _meta.ui.resourceUri
registerAppTool(server, 'show_widget', {
  description: 'Show interactive widget',
  inputSchema: { query: z.string() },
  _meta: { ui: { resourceUri: widgetUI.resource.uri } }  // Links tool to UI
}, async ({ query }) => {
  return { content: [{ type: 'text', text: `Query: ${query}` }] };
});
```

::: tip Legacy MCP-UI Support
For existing MCP-UI apps or hosts that don't support MCP Apps yet, see the [Legacy MCP-UI Adapter](./guide/mcp-apps) guide.
:::


<style>
.video-container {
  text-align: center;
  margin: 2rem 0;
}

.action-buttons {
  display: flex;
  gap: 1rem;
  justify-content: center;
  margin: 2rem 0;
  flex-wrap: wrap;
}

.action-button {
  display: inline-block;
  padding: 0.75rem 1.5rem;
  border-radius: 6px;
  text-decoration: none;
  font-weight: 500;
  transition: all 0.3s ease;
}

.action-button.primary {
  background: var(--vp-c-brand-1);
  color: var(--vp-c-white);
}

.action-button.primary:hover {
  background: var(--vp-c-brand-2);
}

.action-button.secondary {
  background: var(--vp-c-bg-soft);
  color: var(--vp-c-text-1);
  border: 1px solid var(--vp-c-divider);
}

.action-button.secondary:hover {
  background: var(--vp-c-bg-mute);
}

@media (max-width: 768px) {
  .action-buttons {
    flex-direction: column;
    align-items: center;
  }
  
  .action-button {
    width: 200px;
    text-align: center;
  }
}

a.VPButton.medium[href="/about"] {
  background-color: var(--vp-c-bg-soft);
  border: 1px solid var(--vp-c-divider);
  color: var(--vp-c-text-1);
}

a.VPButton.medium[href="/about"]:hover {
  background-color: var(--vp-c-bg-mute);
}
</style>


================================================
FILE: docs/src/team.md
================================================
# Team

`mcp-ui` is a project by [Ido Salomon](https://x.com/idosal1), in collaboration with [Liad Yosef](https://x.com/liadyosef). 

================================================
FILE: eslint.config.mjs
================================================
import js from '@eslint/js';
import tseslint from 'typescript-eslint';
import react from 'eslint-plugin-react';
import reactHooks from 'eslint-plugin-react-hooks';
import jsxA11y from 'eslint-plugin-jsx-a11y';
import prettier from 'eslint-config-prettier';
import globals from 'globals';

export default tseslint.config(
  // Global ignores (replaces .eslintignore)
  {
    ignores: [
      '**/node_modules/**',
      '**/dist/**',
      '**/coverage/**',
      '**/*.log',
      '**/*.js',
      '**/*.mjs',
      '**/*.cjs',
      'examples/**',
      'docs/**',
    ],
  },

  // Base configs
  js.configs.recommended,
  ...tseslint.configs.recommended,

  // React config
  {
    files: ['**/*.tsx', '**/*.jsx'],
    ...react.configs.flat.recommended,
    ...react.configs.flat['jsx-runtime'],
    settings: {
      react: {
        version: 'detect',
      },
    },
  },

  // React Hooks
  {
    files: ['**/*.tsx', '**/*.jsx'],
    ...reactHooks.configs['flat/recommended'],
  },

  // Accessibility
  {
    files: ['**/*.tsx', '**/*.jsx'],
    ...jsxA11y.flatConfigs.recommended,
  },

  // TypeScript and general config
  {
    files: ['**/*.ts', '**/*.tsx'],
    languageOptions: {
      ecmaVersion: 'latest',
      sourceType: 'module',
      globals: {
        ...globals.node,
        ...globals.browser,
        ...globals.es2025,
      },
      parserOptions: {
        ecmaFeatures: {
          jsx: true,
        },
      },
    },
    rules: {
      'react/prop-types': 'off',
      '@typescript-eslint/consistent-type-imports': [
        'error',
        {
          prefer: 'type-imports',
          fixStyle: 'inline-type-imports',
        },
      ],
      '@typescript-eslint/no-unused-vars': [
        'error',
        {
          argsIgnorePattern: '^_',
          varsIgnorePattern: '^_',
          caughtErrorsIgnorePattern: '^_',
        },
      ],
    },
  },

  // Prettier must be last to override other formatting rules
  prettier
);


================================================
FILE: examples/external-url-demo/index.html
================================================
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta
      http-equiv="Content-Security-Policy"
      content="frame-src 'self' https://proxy.mcpui.dev;"
    />
    <title>MCP-UI Proxy Demo</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>


================================================
FILE: examples/external-url-demo/package.json
================================================
{
  "name": "external-url-demo",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "tsc -b && vite build",
    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
    "preview": "vite preview"
  },
  "dependencies": {
    "@mcp-ui/client": "workspace:*",
    "react": "^18.3.1",
    "react-dom": "^18.3.1"
  },
  "devDependencies": {
    "@types/react": "^18.3.23",
    "@types/react-dom": "^18.3.7",
    "@typescript-eslint/eslint-plugin": "^7.18.0",
    "@typescript-eslint/parser": "^7.18.0",
    "@vitejs/plugin-react": "^4.6.0",
    "eslint": "^9.29.0",
    "eslint-plugin-react-hooks": "^5.2.0",
    "eslint-plugin-react-refresh": "0.4.7",
    "typescript": "~5.8.3",
    "vite": "^6.3.5"
  }
}


================================================
FILE: examples/external-url-demo/src/App.css
================================================
body {
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
  max-width: 1200px;
  margin: 0 auto;
  padding: 2rem;
  line-height: 1.6;
}
.demo-section {
  margin: 2rem 0;
  padding: 1rem;
  border: 1px solid #ddd;
  border-radius: 8px;
}
.demo-section h2 {
  margin-top: 0;
  color: #333;
}
iframe {
  width: 100%;
  min-height: 400px;
  border: 1px solid #ccc;
  border-radius: 4px;
}
.code {
  background: #f5f5f5;
  padding: 1rem;
  border-radius: 4px;
  font-family: 'Courier New', monospace;
  font-size: 0.9em;
  margin: 1rem 0;
}
.toggle {
  background: #007bff;
  color: white;
  border: none;
  padding: 0.5rem 1rem;
  border-radius: 4px;
  cursor: pointer;
  margin: 1rem 0;
}
.toggle:hover {
  background: #0056b3;
}


================================================
FILE: examples/external-url-demo/src/App.tsx
================================================
import { useState } from 'react';
import './App.css';
import { UIResourceRenderer } from '@mcp-ui/client';

function App() {
  const [useProxy, setUseProxy] = useState(false);
  const resource = {
    mimeType: 'text/uri-list',
    text: 'https://example.com',
  };
  const proxy = 'https://proxy.mcpui.dev/';

  return (
    <div>
      <h1>MCP-UI Proxy Demo</h1>
      <p>This demo shows how the proxy functionality works for external URLs in MCP-UI.</p>
      <p>
        <strong>CSP Simulation:</strong> This page includes a Content Security Policy (
        <code>frame-src 'self' https://proxy.mcpui.dev;</code>) that only allows iframes from this
        origin and <code>https://proxy.mcpui.dev</code>. This demonstrates how the{' '}
        <code>proxy</code> prop can be used to display external content on hosts with strict
        security policies.
      </p>
      <p>
        <code>proxy.mcpui.dev</code> hosts a simple script that renders the provided URL in a nested
        iframe. Hosts can use this script or host their own to achieve the same result.
      </p>

      <div className="demo-section">
        <h2>Direct URL (No Proxy)</h2>
        <p>
          This iframe attempts to load an external URL directly.{' '}
          <strong>It should be blocked by the browser's Content Security Policy.</strong>
        </p>
        <div className="code">
          Resource: {`{ mimeType: 'text/uri-list', text: 'https://example.com' }`}
        </div>
        <UIResourceRenderer resource={{ mimeType: 'text/uri-list', text: 'https://example.com' }} />
      </div>

      <div className="demo-section">
        <h2>Proxied URL</h2>
        <p>This iframe loads the external URL through the proxy:</p>
        <div className="code">
          Resource: {`{ mimeType: 'text/uri-list', text: 'https://example.com' }`}
          <br />
          Proxy: https://proxy.mcpui.dev/
          <br />
          Final URL: {`${proxy}?url=${encodeURIComponent(resource.text)}`}
        </div>
        <UIResourceRenderer
          resource={resource}
          htmlProps={{ proxy, style: { width: '500px', height: '500px' } }}
        />
      </div>

      <div className="demo-section">
        <h2>Interactive Demo</h2>
        <p>Toggle between direct and proxied loading:</p>
        <div style={{ display: 'flex', alignItems: 'center', gap: '20px' }}>
          <button className="toggle" onClick={() => setUseProxy(!useProxy)}>
            Toggle Proxy
          </button>
          <h1>{useProxy ? 'Proxied' : 'Direct (no proxy)'}</h1>
        </div>
        <div id="demo-container">
          <UIResourceRenderer resource={resource} htmlProps={useProxy ? { proxy } : {}} />
        </div>
        <div className="code" id="url-display">
          Current URL:{' '}
          {useProxy ? `${proxy}?url=${encodeURIComponent(resource.text)}` : resource.text}
        </div>
      </div>
    </div>
  );
}

export default App;


================================================
FILE: examples/external-url-demo/src/index.css
================================================
body {
  margin: 0;
  font-family:
    -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell',
    'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}

code {
  font-family: source-code-pro, Menlo, Monaco, Consolas, 'Courier New', monospace;
}


================================================
FILE: examples/external-url-demo/src/main.tsx
================================================
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App.tsx';
import './index.css';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
);


================================================
FILE: examples/external-url-demo/tsconfig.app.json
================================================
{
  "compilerOptions": {
    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
    "target": "ES2020",
    "useDefineForClassFields": true,
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "skipLibCheck": true,

    /* Bundler mode */
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "verbatimModuleSyntax": true,
    "moduleDetection": "force",
    "noEmit": true,
    "jsx": "react-jsx",

    /* Linting */
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}


================================================
FILE: examples/external-url-demo/tsconfig.json
================================================
{
  "files": [],
  "references": [{ "path": "./tsconfig.app.json" }, { "path": "./tsconfig.node.json" }]
}


================================================
FILE: examples/external-url-demo/tsconfig.node.json
================================================
{
  "compilerOptions": {
    "composite": true,
    "skipLibCheck": true,
    "module": "ESNext",
    "moduleResolution": "bundler",
    "allowSyntheticDefaultImports": true,
    "strict": true
  },
  "include": ["vite.config.ts"]
}


================================================
FILE: examples/external-url-demo/vite.config.ts
================================================
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [react()],
});


================================================
FILE: examples/mcp-apps-demo/package.json
================================================
{
  "name": "mcp-apps-demo",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "start": "node dist/index.js",
    "build": "tsc"
  },
  "dependencies": {
    "@mcp-ui/server": "workspace:*",
    "@modelcontextprotocol/ext-apps": "^0.2.2",
    "@modelcontextprotocol/sdk": "^1.25.1",
    "cors": "^2.8.5",
    "express": "^4.18.2",
    "zod": "^3.22.4"
  },
  "devDependencies": {
    "@types/cors": "^2.8.17",
    "@types/express": "^4.17.21",
    "@types/node": "^20.11.24",
    "ts-node": "^10.9.2",
    "typescript": "^5.3.3"
  }
}


================================================
FILE: examples/mcp-apps-demo/src/index.ts
================================================
import express from 'express';
import cors from 'cors';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
import { createUIResource } from '@mcp-ui/server';
import { registerAppTool, registerAppResource } from '@modelcontextprotocol/ext-apps/server';

import { randomUUID } from 'crypto';
import { z } from 'zod';

const app = express();
const port = 3001;

app.use(
  cors({
    origin: '*',
    exposedHeaders: ['Mcp-Session-Id'],
    allowedHeaders: ['*'],
  }),
);
app.use(express.json());

// Map to store transports by session ID, as shown in the documentation.
const transports: { [sessionId: string]: StreamableHTTPServerTransport } = {};

// Handle POST requests for client-to-server communication.
app.post('/mcp', async (req, res) => {
  const sessionId = req.headers['mcp-session-id'] as string | undefined;
  let transport: StreamableHTTPServerTransport;

  if (sessionId && transports[sessionId]) {
    // A session already exists; reuse the existing transport.
    transport = transports[sessionId];
  } else if (!sessionId && isInitializeRequest(req.body)) {
    // This is a new initialization request. Create a new transport.
    transport = new StreamableHTTPServerTransport({
      sessionIdGenerator: () => randomUUID(),
      onsessioninitialized: (sid) => {
        transports[sid] = transport;
        console.log(`MCP Session initialized: ${sid}`);
      },
    });

    // Clean up the transport from our map when the session closes.
    transport.onclose = () => {
      if (transport.sessionId) {
        console.log(`MCP Session closed: ${transport.sessionId}`);
        delete transports[transport.sessionId];
      }
    };

    // Create a new server instance for this specific session.
    const server = new McpServer({
      name: 'mcp-apps-demo',
      version: '1.0.0',
    });

    // Register a tool with a UI interface using the MCP Apps adapter
    const weatherDashboardUI = await createUIResource({
      uri: 'ui://weather-server/dashboard-template',
      encoding: 'text',
      content: {
        type: 'rawHtml',
        htmlString: `
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>MCP Apps Adapter Demo</title>
  <style>
    * { box-sizing: border-box; }
    body {
      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
      padding: 16px;
      margin: 0;
      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
      min-height: 100vh;
      color: #333;
    }
    .container {
      max-width: 500px;
      margin: 0 auto;
    }
    .card {
      background: white;
      border-radius: 16px;
      padding: 24px;
      box-shadow: 0 10px 40px rgba(0, 0, 0, 0.2);
      margin-bottom: 16px;
    }
    h1 { 
      margin: 0 0 8px 0; 
      color: #667eea;
      font-size: 24px;
    }
    h2 {
      margin: 0 0 16px 0;
      color: #333;
      font-size: 18px;
      font-weight: 600;
    }
    .subtitle {
      color: #64748b;
      font-size: 14px;
      margin-bottom: 20px;
    }
    .data-display {
      background: #f8fafc;
      border-radius: 12px;
      padding: 16px;
      margin-bottom: 20px;
    }
    .data-row {
      display: flex;
      justify-content: space-between;
      padding: 8px 0;
      border-bottom: 1px solid #e2e8f0;
    }
    .data-row:last-child { border-bottom: none; }
    .data-label { color: #64748b; font-size: 14px; }
    .data-value { color: #1e293b; font-weight: 600; }
    .actions-grid {
      display: grid;
      grid-template-columns: 1fr 1fr;
      gap: 12px;
    }
    button {
      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
      color: white;
      border: none;
      padding: 12px 16px;
      border-radius: 8px;
      cursor: pointer;
      font-size: 14px;
      font-weight: 500;
      transition: transform 0.2s, box-shadow 0.2s;
    }
    button:hover { 
      transform: translateY(-2px);
      box-shadow: 0 4px 12px rgba(102, 126, 234, 0.4);
    }
    button:active { transform: translateY(0); }
    button.secondary {
      background: #f1f5f9;
      color: #475569;
    }
    button.secondary:hover {
      background: #e2e8f0;
      box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
    }
    .full-width { grid-column: 1 / -1; }
    .log-area {
      background: #1e293b;
      border-radius: 8px;
      padding: 12px;
      font-family: 'SF Mono', Monaco, 'Courier New', monospace;
      font-size: 12px;
      color: #94a3b8;
      max-height: 150px;
      overflow-y: auto;
    }
    .log-entry { margin-bottom: 4px; }
    .log-entry.success { color: #4ade80; }
    .log-entry.info { color: #60a5fa; }
    .log-entry.warn { color: #fbbf24; }
    .status-badge {
      display: inline-block;
      padding: 4px 12px;
      border-radius: 20px;
      font-size: 12px;
      font-weight: 600;
    }
    .status-badge.connected {
      background: #dcfce7;
      color: #166534;
    }
    .status-badge.disconnected {
      background: #fee2e2;
      color: #991b1b;
    }
  </style>
</head>
<body>
  <div class="container">
    <div class="card">
      <h1>🔌 MCP Apps Adapter Demo</h1>
      <p class="subtitle">Testing MCP-UI actions through the MCP Apps adapter</p>
      
      <div class="data-display">
        <div class="data-row">
          <span class="data-label">Status</span>
          <span id="status" class="status-badge disconnected">Waiting...</span>
        </div>
        <div class="data-row">
          <span class="data-label">Tool Input</span>
          <span id="toolInput" class="data-value">--</span>
        </div>
        <div class="data-row">
          <span class="data-label">Tool Output</span>
          <span id="toolOutput" class="data-value">--</span>
        </div>
      </div>
    </div>

    <div class="card">
      <h2>📤 MCP-UI Actions</h2>
      <div class="actions-grid">
        <button onclick="sendNotify()">
          📢 Send Notify
        </button>
        <button onclick="sendLink()">
          🔗 Open Link
        </button>
        <button onclick="sendPrompt()">
          💬 Send Prompt
        </button>
        <button onclick="sendIntent()">
          🎯 Send Intent
        </button>
        <button onclick="sendSizeChange()" class="secondary">
          📐 Resize Widget
        </button>
        <button onclick="callTool()" class="secondary">
          🔧 Call Tool
        </button>
        <button onclick="refreshData()" class="full-width">
          🔄 Request Render Data
        </button>
      </div>
    </div>

    <div class="card">
      <h2>📋 Event Log</h2>
      <div id="log" class="log-area">
        <div class="log-entry info">Waiting for adapter initialization...</div>
      </div>
    </div>
  </div>

  <script>
    // Log helper
    function log(message, type = 'info') {
      const logEl = document.getElementById('log');
      const entry = document.createElement('div');
      entry.className = 'log-entry ' + type;
      entry.textContent = new Date().toLocaleTimeString() + ' - ' + message;
      logEl.appendChild(entry);
      logEl.scrollTop = logEl.scrollHeight;
    }

    // Update status
    function setStatus(connected) {
      const el = document.getElementById('status');
      el.textContent = connected ? 'Connected' : 'Disconnected';
      el.className = 'status-badge ' + (connected ? 'connected' : 'disconnected');
    }

    // Listen for messages from adapter
    window.addEventListener('message', (event) => {
      const data = event.data;
      if (!data || !data.type) return;

      log('Received: ' + data.type, 'info');

      switch (data.type) {
        case 'ui-lifecycle-iframe-render-data':
          setStatus(true);
          const renderData = data.payload?.renderData || {};
          
          if (renderData.toolInput) {
            document.getElementById('toolInput').textContent = 
              JSON.stringify(renderData.toolInput).substring(0, 30) + '...';
            log('Tool input received: ' + JSON.stringify(renderData.toolInput), 'success');
          }
          
          if (renderData.toolOutput) {
            document.getElementById('toolOutput').textContent = 
              JSON.stringify(renderData.toolOutput).substring(0, 30) + '...';
            log('Tool output received', 'success');
          }
          break;

        case 'ui-message-received':
          log('Message acknowledged: ' + data.payload?.messageId, 'info');
          break;

        case 'ui-message-response':
          if (data.payload?.error) {
            log('Response error: ' + JSON.stringify(data.payload.error), 'warn');
          } else {
            log('Response received: ' + JSON.stringify(data.payload?.response || {}), 'success');
          }
          break;
      }
    });

    // Helper to send MCP-UI messages
    function sendMessage(type, payload) {
      const messageId = 'msg-' + Date.now();
      log('Sending: ' + type, 'info');
      window.parent.postMessage({ type, messageId, payload }, '*');
      return messageId;
    }

    // Action handlers
    function sendNotify() {
      sendMessage('notify', { 
        message: 'Hello from MCP-UI widget! Time: ' + new Date().toLocaleTimeString() 
      });
    }

    function sendLink() {
      sendMessage('link', { 
        url: 'https://github.com/modelcontextprotocol/ext-apps' 
      });
    }

    function sendPrompt() {
      sendMessage('prompt', { 
        prompt: 'What is the weather like today?' 
      });
    }

    function sendIntent() {
      sendMessage('intent', { 
        intent: 'get_forecast',
        params: { days: 7, location: 'San Francisco' }
      });
    }

    function sendSizeChange() {
      const height = 300 + Math.floor(Math.random() * 200);
      sendMessage('ui-size-change', { 
        width: 500,
        height: height
      });
      log('Requested size: 500x' + height, 'info');
    }

    function callTool() {
      sendMessage('tool', { 
        toolName: 'weather_dashboard',
        params: { location: 'New York' }
      });
    }

    function refreshData() {
      sendMessage('ui-request-render-data', {});
    }

    // Signal ready state
    log('Sending ready signal...', 'info');
    window.parent.postMessage({ type: 'ui-lifecycle-iframe-ready' }, '*');
  </script>
</body>
</html>
        `,
      },
      adapters: {
        // Enable the MCP Apps adapter
        mcpApps: {
          enabled: true,
        },
      },
    });

    // Register the UI resource so the host can fetch it
    registerAppResource(
      server,
      'weather_dashboard_ui',
      weatherDashboardUI.resource.uri,
      {},
      async () => ({
        contents: [weatherDashboardUI.resource],
      }),
    );

    // Register the tool with _meta linking to the UI resource
    registerAppTool(
      server,
      'weather_dashboard',
      {
        description: 'Interactive weather dashboard widget',
        inputSchema: {
          location: z.string().describe('City name'),
        },
        // This tells MCP Apps hosts where to find the UI
        _meta: {
          ui: {
            resourceUri: weatherDashboardUI.resource.uri,
          },
        },
      },
      async ({ location }) => {
        // In a real app, we might fetch data here
        return {
          content: [{ type: 'text', text: `Weather dashboard for ${location}` }],
        };
      },
    );

    // Connect the server instance to the transport for this session.
    await server.connect(transport);
  } else {
    return res.status(400).json({
      error: { message: 'Bad Request: No valid session ID provided' },
    });
  }

  // Handle the client's request using the session's transport.
  await transport.handleRequest(req, res, req.body);
});

// A separate, reusable handler for GET and DELETE requests.
const handleSessionRequest = async (req: express.Request, res: express.Response) => {
  const sessionId = req.headers['mcp-session-id'] as string | undefined;
  console.log('sessionId', sessionId);
  if (!sessionId || !transports[sessionId]) {
    return res.status(404).send('Session not found');
  }

  const transport = transports[sessionId];
  await transport.handleRequest(req, res);
};

// GET handles the long-lived stream for server-to-client messages.
app.get('/mcp', handleSessionRequest);

// DELETE handles explicit session termination from the client.
app.delete('/mcp', handleSessionRequest);

app.listen(port, () => {
  console.log(`MCP Apps Demo Server running at http://localhost:${port}`);
});


================================================
FILE: examples/mcp-apps-demo/tsconfig.json
================================================
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"]
}


================================================
FILE: examples/python-server-demo/README.md
================================================
# Python MCP Server Demo

A Python MCP server implementation inspired by the TypeScript server demo. This server demonstrates how to create MCP UI resources using the MCP UI Server SDK.

## Features

This server provides multiple tools that demonstrate different types of UI resources and metadata capabilities:

### Basic UI Resources
- **show_external_url** - Creates a UI resource displaying an external URL (example.com) with preferred frame size metadata
- **show_raw_html** - Creates a UI resource with raw HTML content
- **show_remote_dom** - Creates a UI resource with remote DOM script using React framework
- **show_action_html** - Creates a UI resource with interactive buttons demonstrating intent actions

## Installation

This project uses [uv](https://github.com/astral-sh/uv) for dependency management.

```bash
# Install dependencies
uv sync

# Or install manually
uv add mcp mcp-ui-server
```

## Running the Server

```bash
# Using uv
uv run python_server_demo.py

# Or directly with Python
python python_server_demo.py
```

The server uses stdio transport and communicates via stdin/stdout using the MCP protocol.

## Usage with MCP Clients

This server can be connected to by any MCP client that supports stdio transport. The server will:

1. Initialize the MCP connection
2. List the three available tools
3. Handle tool calls and return UI resources

### Example Tool Calls

Each tool returns an MCP resource that can be rendered by MCP UI clients:

- **External URL**: Returns a resource that displays example.com in an iframe
- **Raw HTML**: Returns a resource with HTML content `<h1>Hello from Raw HTML</h1>`
- **Remote DOM**: Returns a resource with JavaScript that creates UI elements dynamically

## UI Metadata

The SDK supports UI metadata through the `uiMetadata` parameter in `create_ui_resource()`.

### Metadata Keys

Use the `UIMetadataKey` constants for type-safe metadata keys:

- **`UIMetadataKey.PREFERRED_FRAME_SIZE`**: CSS dimensions for the iframe
  - Type: `list[str, str]` - [width, height] as CSS dimension strings
  - Examples: `["800px", "600px"]`, `["100%", "50vh"]`, `["50rem", "80%"]`
  - Must include CSS units (px, %, vh, vw, rem, em, etc.)

- **`UIMetadataKey.INITIAL_RENDER_DATA`**: Initial data for the UI component
  - Type: `dict[str, Any]` - Any JSON-serializable dictionary

### How It Works

1. All `uiMetadata` keys are automatically prefixed with `mcpui.dev/ui-`
2. Prefixed metadata is merged with any custom `metadata`
3. The combined metadata is added to the resource's `_meta` field
4. Custom metadata keys are preserved as-is (not prefixed)

### Example Usage

```python
from mcp_ui_server import create_ui_resource, UIMetadataKey

ui_resource = create_ui_resource({
    "uri": "ui://my-component",
    "content": {
        "type": "rawHtml",
        "htmlString": "<h1>Hello</h1>"
    },
    "encoding": "text",
    "uiMetadata": {
        UIMetadataKey.PREFERRED_FRAME_SIZE: ["1200px", "800px"],
        # Or use string literal: "preferred-frame-size": ["1200px", "800px"]
    },
    # Optional: custom metadata (not prefixed)
    "metadata": {
        "custom.author": "My Server",
        "custom.version": "1.0.0"
    }
})
```


## Development

```bash
# Install dev dependencies
uv sync --dev

# Run linting
uv run ruff check .

# Run tests (if any)
uv run pytest
```

## Architecture

- **Transport**: stdio (standard input/output)
- **Framework**: MCP Python SDK
- **UI Resources**: Created using mcp-ui-server SDK
- **Session Management**: Handled by MCP SDK

## Comparison to TypeScript Demo

| Feature | TypeScript Demo | Python Demo |
|---------|----------------|-------------|
| Transport | HTTP | stdio |
| Framework | Express.js | MCP Python SDK |
| Tools | 3 UI tools | Same 3 UI tools |
| Session Management | Manual | SDK handled |
| Deployment | Web server | CLI/Desktop integration |

================================================
FILE: examples/python-server-demo/pyproject.toml
================================================
[project]
name = "python-server-demo"
version = "0.1.0"
description = "Python MCP server demo inspired by the TypeScript version"
readme = "README.md"
requires-python = ">=3.10"
dependencies = [
    "mcp>=1.0.0",
    "mcp-ui-server",
]
authors = [
    {name = "MCP UI Contributors"}
]
license = {text = "Apache-2.0"}

[project.urls]
Homepage = "https://mcpui.dev"
Repository = "https://github.com/idosal/mcp-ui"
Documentation = "https://mcpui.dev"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.metadata]
allow-direct-references = true

[dependency-groups]
dev = [
    "pytest>=7.0.0",
    "ruff>=0.1.0"
]

[tool.uv.sources]
mcp-ui-server = { path = "../../sdks/python/server" }

[project.scripts]
python-server-demo = "python_server_demo:main"


================================================
FILE: examples/python-server-demo/python_server_demo.py
================================================
#!/usr/bin/env python3
"""Python MCP server demo inspired by the TypeScript version.

This server demonstrates how to create an MCP server with UI resources
using FastMCP for both stdio and HTTP transports.

Usage:
    python python_server_demo.py                    # stdio transport  
    python python_server_demo.py --http --port 3000 # HTTP transport
"""

import argparse
from mcp.server.fastmcp import FastMCP

from mcp_ui_server import create_ui_resource, UIMetadataKey
from mcp_ui_server.core import UIResource

# Create FastMCP instance
mcp = FastMCP("python-server-demo")

@mcp.tool()
def show_external_url() -> list[UIResource]:
    """Creates a UI resource displaying an external URL (example.com) with preferred frame size."""
    ui_resource = create_ui_resource({
        "uri": "ui://greeting",
        "content": {
            "type": "externalUrl",
            "iframeUrl": "https://example.com"
        },
        "encoding": "text",
        "uiMetadata": {
            UIMetadataKey.PREFERRED_FRAME_SIZE: ["800px", "600px"]  # CSS dimension strings (can be px, %, vh, etc.)
        }
    })
    return [ui_resource]


@mcp.tool()
def show_raw_html() -> list[UIResource]:
    """Creates a UI resource displaying raw HTML."""
    ui_resource = create_ui_resource({
        "uri": "ui://raw-html-demo",
        "content": {
            "type": "rawHtml",
            "htmlString": "<h1>Hello from Raw HTML</h1>"
        },
        "encoding": "text"
    })
    return [ui_resource]


@mcp.tool()
def show_action_html() -> list[UIResource]:
    """Creates a UI resource with interactive buttons that demonstrate intent actions."""
    interactive_html = """
    <div style="padding: 20px; font-family: Arial, sans-serif;">
        <h2>Intent Action Demo</h2>
        <p>Click the buttons below to trigger different intent actions:</p>
        
        <div style="margin: 10px 0;">
            <button onclick="sendIntent('user_profile', {userId: '123', action: 'view'})" 
                    style="background: #007cba; color: white; padding: 8px 16px; border: none; border-radius: 4px; margin: 5px; cursor: pointer;">
                View User Profile
            </button>
        </div>
        
        <div style="margin: 10px 0;">
            <button onclick="sendIntent('navigation', {page: 'dashboard', section: 'analytics'})" 
                    style="background: #28a745; color: white; padding: 8px 16px; border: none; border-radius: 4px; margin: 5px; cursor: pointer;">
                Navigate to Dashboard
            </button>
        </div>
        
        <div style="margin: 10px 0;">
            <button onclick="sendIntent('data_export', {format: 'csv', dateRange: '30days'})" 
                    style="background: #ffc107; color: black; padding: 8px 16px; border: none; border-radius: 4px; margin: 5px; cursor: pointer;">
                Export Data
            </button>
        </div>
        
        <div style="margin: 10px 0;">
            <button onclick="sendIntent('notification_settings', {type: 'email', enabled: true})" 
                    style="background: #dc3545; color: white; padding: 8px 16px; border: none; border-radius: 4px; margin: 5px; cursor: pointer;">
                Update Notifications
            </button>
        </div>
        
        <div id="status" style="margin-top: 20px; padding: 10px; background: #f8f9fa; border: 1px solid #dee2e6; border-radius: 4px;">
            Click a button to see the intent action in action!
        </div>
    </div>
    
    <script>
        function sendIntent(intent, params) {
            const status = document.getElementById('status');
            status.innerHTML = `<strong>Intent Sent:</strong> ${intent}<br><strong>Parameters:</strong> ${JSON.stringify(params, null, 2)}`;
            
            // Send the intent to the parent frame
            if (window.parent) {
                window.parent.postMessage({
                    type: 'intent',
                    payload: {
                        intent: intent,
                        params: params
                    }
                }, '*');
            }
        }
    </script>
    """

    ui_resource = create_ui_resource({
        "uri": "ui://action-html-demo",
        "content": {
            "type": "rawHtml",
            "htmlString": interactive_html
        },
        "encoding": "text"
    })

    return [ui_resource]


if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="Python MCP Server Demo")
    parser.add_argument("--http", action="store_true", help="Use HTTP transport instead of stdio")
    parser.add_argument("--port", type=int, default=3000, help="Port for HTTP transport (default: 3000)")
    args = parser.parse_args()

    if args.http:
        print("🚀 Starting Python MCP server on HTTP (SSE transport)")
        print("📡 Server will use SSE transport settings")
        mcp.settings.port=args.port
        mcp.run(transport="sse")
    else:
        print("🚀 Starting Python MCP server with stdio transport")
        mcp.run()


================================================
FILE: examples/ruby-server-demo/Gemfile
================================================
source "https://rubygems.org"

gem "mcp", git: "https://github.com/modelcontextprotocol/ruby-sdk"
gem "mcp_ui_server", path: "../../sdks/ruby"
gem "webrick" 

================================================
FILE: examples/ruby-server-demo/README.md
================================================
# ruby-server-demo

This barebones server demonstrates how to use `mcp_ui_server` to generate three types of UI resources: `externalUrl`, `rawHtml`, and `remoteDom`.

Each resource type has a dedicated tool:
- `ExternalUrlTool`: Returns a resource that renders an external webpage (`https://example.com`) in an iframe.
- `RawHtmlTool`: Returns a resource containing a simple raw HTML string.
- `RemoteDomTool`: Returns a resource with a JavaScript snippet that manipulates the DOM of the client application.

For a detailed explanation of how this server works, see the [Ruby Server Walkthrough](https://mcpui.dev/guide/server/ruby/walkthrough).

## Running the server

1. **Install dependencies:**
   ```sh
   bundle install
   ```
2. **Start the server:**
   ```sh
   ruby server.rb
   ```
   The server will be running at `http://localhost:8081/mcp`.

You can view the UI resources from this server by connecting to it with the [`ui-inspector`](https://github.com/idosal/ui-inspector) (target `http://localhost:8081/mcp`).

================================================
FILE: examples/ruby-server-demo/server.rb
================================================
require 'mcp'
require 'mcp_ui_server'
require 'webrick'
require 'json'

# --- Define MCP Tools ---
class ExternalUrlTool < MCP::Tool
  description 'A simple tool that returns an external URL resource'
  input_schema(
    type: 'object',
    properties: {}
  )

  class << self
    def call(server_context:)
      # create_ui_resource returns a UI Resource object of the form:
      # { type: 'resource', resource: { ... } }
      ui_resource_object = McpUiServer.create_ui_resource(
        uri: 'ui://my-external-site',
        content: { type: :external_url, iframeUrl: 'https://example.com' },
        encoding: :text
      )

      MCP::Tool::Response.new([ui_resource_object])
    end
  end
end

class RawHtmlTool < MCP::Tool
  description 'A simple tool that returns a raw HTML resource'
  input_schema(
    type: 'object',
    properties: {}
  )

  class << self
    def call(server_context:)
      ui_resource_object = McpUiServer.create_ui_resource(
        uri: 'ui://my-raw-html',
        content: { type: :raw_html, htmlString: '<p>This is some raw HTML content.</p>' },
        encoding: :text
      )

      MCP::Tool::Response.new([ui_resource_object])
    end
  end
end

# --- MCP Server Setup ---
mcp_server = MCP::Server.new(tools: [ExternalUrlTool, RawHtmlTool])

# --- WEBrick HTTP Server Setup ---
http_server = WEBrick::HTTPServer.new(Port: 8081)

# Create a servlet to handle requests to /mcp
class MCPServlet < WEBrick::HTTPServlet::AbstractServlet
  def initialize(server, mcp_instance)
    super(server)
    @mcp = mcp_instance
  end

  def do_OPTIONS(_request, response)
    response.status = 200
    response['Access-Control-Allow-Origin'] = '*'
    response['Access-Control-Allow-Methods'] = 'POST, OPTIONS'
    response['Access-Control-Allow-Headers'] = 'Content-Type, Accept'
  end

  def do_POST(request, response)
    response['Access-Control-Allow-Origin'] = '*'
    response.status = 200
    response['Content-Type'] = 'application/json'
    response.body = @mcp.handle_json(request.body)
  end
end

# Mount the servlet at the /mcp endpoint
http_server.mount('/mcp', MCPServlet, mcp_server)

# Start the server and handle shutdown
trap('INT') { http_server.shutdown }
puts 'MCP server running on http://localhost:8081/mcp'
http_server.start

================================================
FILE: examples/server/.react-router/types/+future.ts
================================================
// Generated by React Router

import 'react-router';

declare module 'react-router' {
  interface Future {
    unstable_middleware: false;
  }
}


================================================
FILE: examples/server/.react-router/types/+routes.ts
================================================
// Generated by React Router

import 'react-router';

declare module 'react-router' {
  interface Register {
    pages: Pages;
    routeFiles: RouteFiles;
  }
}

type Pages = {
  '/': {
    params: {};
  };
  '/task': {
    params: {};
  };
  '/user': {
    params: {};
  };
};

type RouteFiles = {
  'root.tsx': {
    id: 'root';
    page: '/' | '/task' | '/user';
  };
  'routes/home.tsx': {
    id: 'routes/home';
    page: '/';
  };
  'routes/task.tsx': {
    id: 'routes/task';
    page: '/task';
  };
  'routes/user.tsx': {
    id: 'routes/user';
    page: '/user';
  };
};


================================================
FILE: examples/server/.react-router/types/+server-build.d.ts
================================================
// Generated by React Router

declare module 'virtual:react-router/server-build' {
  import { ServerBuild } from 'react-router';
  export const assets: ServerBuild['assets'];
  export const assetsBuildDirectory: ServerBuild['assetsBuildDirectory'];
  export const basename: ServerBuild['basename'];
  export const entry: ServerBuild['entry'];
  export const future: ServerBuild['future'];
  export const isSpaMode: ServerBuild['isSpaMode'];
  export const prerender: ServerBuild['prerender'];
  export const publicPath: ServerBuild['publicPath'];
  export const routeDiscovery: ServerBuild['routeDiscovery'];
  export const routes: ServerBuild['routes'];
  export const ssr: ServerBuild['ssr'];
  export const unstable_getCriticalCss: ServerBuild['unstable_getCriticalCss'];
}


================================================
FILE: examples/server/.react-router/types/app/+types/root.ts
================================================
// Generated by React Router

import type { GetInfo, GetAnnotations } from 'react-router/internal';

type Module = typeof import('../root.js');

type Info = GetInfo<{
  file: 'root.tsx';
  module: Module;
}>;

type Matches = [
  {
    id: 'root';
    module: typeof import('../root.js');
  },
];

type Annotations = GetAnnotations<Info & { module: Module; matches: Matches }>;

export namespace Route {
  // links
  export type LinkDescriptors = Annotations['LinkDescriptors'];
  export type LinksFunction = Annotations['LinksFunction'];

  // meta
  export type MetaArgs = Annotations['MetaArgs'];
  export type MetaDescriptors = Annotations['MetaDescriptors'];
  export type MetaFunction = Annotations['MetaFunction'];

  // headers
  export type HeadersArgs = Annotations['HeadersArgs'];
  export type HeadersFunction = Annotations['HeadersFunction'];

  // unstable_middleware
  export type unstable_MiddlewareFunction = Annotations['unstable_MiddlewareFunction'];

  // unstable_clientMiddleware
  export type unstable_ClientMiddlewareFunction = Annotations['unstable_ClientMiddlewareFunction'];

  // loader
  export type LoaderArgs = Annotations['LoaderArgs'];

  // clientLoader
  export type ClientLoaderArgs = Annotations['ClientLoaderArgs'];

  // action
  export type ActionArgs = Annotations['ActionArgs'];

  // clientAction
  export type ClientActionArgs = Annotations['ClientActionArgs'];

  // HydrateFallback
  export type HydrateFallbackProps = Annotations['HydrateFallbackProps'];

  // Component
  export type ComponentProps = Annotations['ComponentProps'];

  // ErrorBoundary
  export type ErrorBoundaryProps = Annotations['ErrorBoundaryProps'];
}


================================================
FILE: examples/server/.react-router/types/app/routes/+types/home.ts
================================================
// Generated by React Router

import type { GetInfo, GetAnnotations } from 'react-router/internal';

type Module = typeof import('../home.js');

type Info = GetInfo<{
  file: 'routes/home.tsx';
  module: Module;
}>;

type Matches = [
  {
    id: 'root';
    module: typeof import('../../root.js');
  },
  {
    id: 'routes/home';
    module: typeof import('../home.js');
  },
];

type Annotations = GetAnnotations<Info & { module: Module; matches: Matches }>;

export namespace Route {
  // links
  export type LinkDescriptors = Annotations['LinkDescriptors'];
  export type LinksFunction = Annotations['LinksFunction'];

  // meta
  export type MetaArgs = Annotations['MetaArgs'];
  export type MetaDescriptors = Annotations['MetaDescriptors'];
  export type MetaFunction = Annotations['MetaFunction'];

  // headers
  export type HeadersArgs = Annotations['HeadersArgs'];
  export type HeadersFunction = Annotations['HeadersFunction'];

  // unstable_middleware
  export type unstable_MiddlewareFunction = Annotations['unstable_MiddlewareFunction'];

  // unstable_clientMiddleware
  export type unstable_ClientMiddlewareFunction = Annotations['unstable_ClientMiddlewareFunction'];

  // loader
  export type LoaderArgs = Annotations['LoaderArgs'];

  // clientLoader
  export type ClientLoaderArgs = Annotations['ClientLoaderArgs'];

  // action
  export type ActionArgs = Annotations['ActionArgs'];

  // clientAction
  export type ClientActionArgs = Annotations['ClientActionArgs'];

  // HydrateFallback
  export type HydrateFallbackProps = Annotations['HydrateFallbackProps'];

  // Component
  export type ComponentProps = Annotations['ComponentProps'];

  // ErrorBoundary
  export type ErrorBoundaryProps = Annotations['ErrorBoundaryProps'];
}


================================================
FILE: examples/server/.react-router/types/app/routes/+types/task.ts
================================================
// Generated by React Router

import type { GetInfo, GetAnnotations } from 'react-router/internal';

type Module = typeof import('../task.js');

type Info = GetInfo<{
  file: 'routes/task.tsx';
  module: Module;
}>;

type Matches = [
  {
    id: 'root';
    module: typeof import('../../root.js');
  },
  {
    id: 'routes/task';
    module: typeof import('../task.js');
  },
];

type Annotations = GetAnnotations<Info & { module: Module; matches: Matches }>;

export namespace Route {
  // links
  export type LinkDescriptors = Annotations['LinkDescriptors'];
  export type LinksFunction = Annotations['LinksFunction'];

  // meta
  export type MetaArgs = Annotations['MetaArgs'];
  export type MetaDescriptors = Annotations['MetaDescriptors'];
  export type MetaFunction = Annotations['MetaFunction'];

  // headers
  export type HeadersArgs = Annotations['HeadersArgs'];
  export type HeadersFunction = Annotations['HeadersFunction'];

  // unstable_middleware
  export type unstable_MiddlewareFunction = Annotations['unstable_MiddlewareFunction'];

  // unstable_clientMiddleware
  export type unstable_ClientMiddlewareFunction = Annotations['unstable_ClientMiddlewareFunction'];

  // loader
  export type LoaderArgs = Annotations['LoaderArgs'];

  // clientLoader
  export type ClientLoaderArgs = Annotations['ClientLoaderArgs'];

  // action
  export type ActionArgs = Annotations['ActionArgs'];

  // clientAction
  export type ClientActionArgs = Annotations['ClientActionArgs'];

  // HydrateFallback
  export type HydrateFallbackProps = Annotations['HydrateFallbackProps'];

  // Component
  export type ComponentProps = Annotations['ComponentProps'];

  // ErrorBoundary
  export type ErrorBoundaryProps = Annotations['ErrorBoundaryProps'];
}


================================================
FILE: examples/server/.react-router/types/app/routes/+types/user.ts
================================================
// Generated by React Router

import type { GetInfo, GetAnnotations } from 'react-router/internal';

type Module = typeof import('../user.js');

type Info = GetInfo<{
  file: 'routes/user.tsx';
  module: Module;
}>;

type Matches = [
  {
    id: 'root';
    module: typeof import('../../root.js');
  },
  {
    id: 'routes/user';
    module: typeof import('../user.js');
  },
];

type Annotations = GetAnnotations<Info & { module: Module; matches: Matches }>;

export namespace Route {
  // links
  export type LinkDescriptors = Annotations['LinkDescriptors'];
  export type LinksFunction = Annotations['LinksFunction'];

  // meta
  export type MetaArgs = Annotations['MetaArgs'];
  export type MetaDescriptors = Annotations['MetaDescriptors'];
  export type MetaFunction = Annotations['MetaFunction'];

  // headers
  export type HeadersArgs = Annotations['HeadersArgs'];
  export type HeadersFunction = Annotations['HeadersFunction'];

  // unstable_middleware
  export type unstable_MiddlewareFunction = Annotations['unstable_MiddlewareFunction'];

  // unstable_clientMiddleware
  export type unstable_ClientMiddlewareFunction = Annotations['unstable_ClientMiddlewareFunction'];

  // loader
  export type LoaderArgs = Annotations['LoaderArgs'];

  // clientLoader
  export type ClientLoaderArgs = Annotations['ClientLoaderArgs'];

  // action
  export type ActionArgs = Annotations['ActionArgs'];

  // clientAction
  export type ClientActionArgs = Annotations['ClientActionArgs'];

  // HydrateFallback
  export type HydrateFallbackProps = Annotations['HydrateFallbackProps'];

  // Component
  export type ComponentProps = Annotations['ComponentProps'];

  // ErrorBoundary
  export type ErrorBoundaryProps = Annotations['ErrorBoundaryProps'];
}


================================================
FILE: examples/server/README.md
================================================
This example features a complete MCP remote server hosted on Cloudflare.

The server is the standard Cloudflare auth-less boilerplate. The only part relevant to `mcp-ui` is in the tool definitions (`src/index.ts`), where we return a UI resource created using `createUIResource` instead of a string.

================================================
FILE: examples/server/app/app.css
================================================
@import 'tailwindcss' source('.');

@theme {
  --font-sans:
    'Inter', ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji',
    'Segoe UI Symbol', 'Noto Color Emoji';
}

html,
body {
  @apply bg-white dark:bg-gray-950;

  @media (prefers-color-scheme: dark) {
    color-scheme: dark;
  }
}


================================================
FILE: examples/server/app/entry.server.tsx
================================================
import type { EntryContext } from 'react-router';
import { ServerRouter } from 'react-router';
import { isbot } from 'isbot';
import { renderToReadableStream } from 'react-dom/server';

export default async function handleRequest(
  request: Request,
  responseStatusCode: number,
  responseHeaders: Headers,
  routerContext: EntryContext,
) {
  let shellRendered = false;
  const userAgent = request.headers.get('user-agent');

  const body = await renderToReadableStream(
    <ServerRouter context={routerContext} url={request.url} />,
    {
      onError(error: unknown) {
        responseStatusCode = 500;
        // Log streaming rendering errors from inside the shell.  Don't log
        // errors encountered during initial shell rendering since they'll
        // reject and get logged in handleDocumentRequest.
        if (shellRendered) {
          console.error(error);
        }
      },
    },
  );
  shellRendered = true;

  // Ensure requests from bots and SPA Mode renders wait for all content to load before responding
  // https://react.dev/reference/react-dom/server/renderToPipeableStream#waiting-for-all-content-to-load-for-crawlers-and-static-generation
  if ((userAgent && isbot(userAgent)) || routerContext.isSpaMode) {
    await body.allReady;
  }

  responseHeaders.set('Content-Type', 'text/html');
  return new Response(body, {
    headers: responseHeaders,
    status: responseStatusCode,
  });
}


================================================
FILE: examples/server/app/graph/graph.tsx
================================================
import { useState, useMemo } from 'react';
import {
  BarChart,
  Bar,
  XAxis,
  YAxis,
  CartesianGrid,
  Tooltip,
  ResponsiveContainer,
  Legend,
} from 'recharts';
import { postMessageToParent } from '../utils/messageUtils';

interface TaskDetails {
  remaining: number;
  toDo: number;
  inProgress: number;
  blocked: number;
}

type TeamMemberId = 'alice' | 'bob' | 'charlie';

interface TeamMemberInfo {
  id: TeamMemberId;
  name: string;
  color: string;
  gradientId: string;
  avatarUrl: string;
}

interface SprintDayDataEntry {
  date: string;
  alice: TaskDetails;
  bob: TaskDetails;
  charlie: TaskDetails;
  [key: string]: TaskDetails | string;
}

interface ProcessedChartItemFullView {
  date: string;
  toDo: number;
  inProgress: number;
  blocked: number;
}

interface ProcessedChartItemZoomedView {
  teamMemberId: TeamMemberId;
  teamMemberName: string;
  toDo: number;
  inProgress: number;
  blocked: number;
  originalColor: string;
}

const teamMembers: TeamMemberInfo[] = [
  {
    id: 'alice',
    name: 'Alice',
    color: '#26A69A',
    gradientId: 'gradAlice',
    avatarUrl: '/avatar1.png',
  },
  {
    id: 'bob',
    name: 'Bob',
    color: '#42A5F5',
    gradientId: 'gradBob',
    avatarUrl: '/avatar2.png',
  },
  {
    id: 'charlie',
    name: 'Charlie',
    color: '#D32F2F',
    gradientId: 'gradCharlie',
    avatarUrl: '/avatar3.png',
  },
];

const statusMeta = {
  toDo: { name: 'To Do', color: '#B0BEC5' }, // Light Grey/Blue - Neutral
  inProgress: { name: 'In Progress', color: '#FFCA28' }, // Amber - Active
  blocked: { name: 'Blocked', color: '#EF5350' }, // Soft Red - Urgent
};
const statusKeys = ['toDo', 'inProgress', 'blocked'] as const;

// Original full sprint data
const sprintDataFull: SprintDayDataEntry[] = [
  {
    date: '5/10',
    alice: { remaining: 8, toDo: 3, inProgress: 3, blocked: 2 },
    bob: { remaining: 7, toDo: 2, inProgress: 3, blocked: 2 },
    charlie: { remaining: 9, toDo: 4, inProgress: 3, blocked: 2 },
  },
  {
    date: '5/11',
    alice: { remaining: 7, toDo: 2, inProgress: 3, blocked: 2 },
    bob: { remaining: 6, toDo: 2, inProgress: 2, blocked: 2 },
    charlie: { remaining: 8, toDo: 3, inProgress: 3, blocked: 2 },
  },
  {
    date: '5/12',
    alice: { remaining: 9, toDo: 3, inProgress: 4, blocked: 2 },
    bob: { remaining: 8, toDo: 3, inProgress: 3, blocked: 2 },
    charlie: { remaining: 10, toDo: 4, inProgress: 4, blocked: 2 },
  },
  {
    date: '5/13',
    alice: { remaining: 6, toDo: 1, inProgress: 2, blocked: 3 },
    bob: { remaining: 9, toDo: 3, inProgress: 3, blocked: 3 },
    charlie: { remaining: 11, toDo: 5, inProgress: 3, blocked: 3 },
  },
  {
    date: '5/14',
    alice: { remaining: 10, toDo: 4, inProgress: 3, blocked: 3 },
    bob: { remaining: 9, toDo: 3, inProgress: 3, blocked: 3 },
    charlie: { remaining: 12, toDo: 5, inProgress: 4, blocked: 3 },
  },
  {
    date: '5/15',
    alice: { remaining: 11, toDo: 4, inProgress: 4, blocked: 3 },
    bob: { remaining: 10, toDo: 3, inProgress: 4, blocked: 3 },
    charlie: { remaining: 13, toDo: 6, inProgress: 4, blocked: 3 },
  },
  {
    date: '5/16',
    alice: { remaining: 12, toDo: 5, inProgress: 4, blocked: 3 },
    bob: { remaining: 18, toDo: 11, inProgress: 4, blocked: 3 },
    charlie: { remaining: 14, toDo: 6, inProgress: 5, blocked: 3 },
  },
];

// Process data for the full view (stacked by STATUS, grouped by date)
const originalProcessedDataFullView: ProcessedChartItemFullView[] = sprintDataFull.map((day) => {
  let dayTotalToDo = 0;
  let dayTotalInProgress = 0;
  let dayTotalBlocked = 0;
  teamMembers.forEach((member) => {
    dayTotalToDo += day[member.id]?.toDo || 0;
    dayTotalInProgress += day[member.id]?.inProgress || 0;
    dayTotalBlocked += day[member.id]?.blocked || 0;
  });
  return {
    date: day.date,
    toDo: dayTotalToDo,
    inProgress: dayTotalInProgress,
    blocked: dayTotalBlocked,
  };
});

// Mapping statuses to team member gradients for the full view bar colors
const fullViewStatusToGradientMapping: Record<(typeof statusKeys)[number], string> = {
  toDo: teamMembers[0].gradientId, // Alice's gradient (Teal)
  inProgress: teamMembers[1].gradientId, // Bob's gradient (Blue)
  blocked: teamMembers[2].gradientId, // Charlie's gradient (Red)
};

// --- Custom Rounded Bar Shape (used for both views) ---
const RoundedBar = (props: {
  fill: string;
  x: number;
  y: number;
  width: number;
  height: number;
}) => {
  // Reverted to any to match recharts expectations for now
  const { fill, x, y, width, height } = props;
  // Use the existing radius calculation. This radius will be applied to all four corners.
  const radius = Math.min(Math.abs(width), Math.abs(height)) / 6;

  if (height === 0) return <g />;

  // Fallback for very small bars where path calculations might lead to visual glitches.
  // This condition remains the same.
  if (Math.abs(height) < radius * 1.5 || Math.abs(width) < radius * 1.5) {
    return <rect x={x} y={y} width={width} height={height} fill={fill} />;
  }

  if (height < 0) {
    // Handle negative values - path unchanged as not currently used and not specified in request
    const absHeight = Math.abs(height);
    // This existing path rounds the two corners at the "bottom" (y + absHeight) of the negative bar.
    // For full consistency, if negative bars were used and needed all 4 corners rounded, this would also need changing.
    const path = `
      M ${x},${y}
      L ${x + width},${y}
      A ${radius},${radius} 0 0 0 ${x + width - radius},${y + absHeight}
      L ${x + radius},${y + absHeight}
      A ${radius},${radius} 0 0 0 ${x},${y}
      Z
    `;
    return <path d={path} fill={fill} />;
  }

  const path = `
    M ${x + radius},${y}
    L ${x + width - radius},${y}
    A ${radius},${radius} 0 0 1 ${x + width},${y + radius}
    L ${x + width},${y + height - radius}
    A ${radius},${radius} 0 0 1 ${x + width - radius},${y + height}
    L ${x + radius},${y + height}
    A ${radius},${radius} 0 0 1 ${x},${y + height - radius}
    L ${x},${y + radius}
    A ${radius},${radius} 0 0 1 ${x + radius},${y}
    Z
  `;
  return <path d={path} fill={fill} />;
};

// --- Custom Tooltip ---
interface CustomTooltipProps {
  active?: boolean;
  payload?: Array<{
    name: string; // Status name like "To Do", "In Progress", "Blocked"
    value: number; // Count for that status
    color?: string; // Bar segment color (e.g., from 'fill' prop of Bar)
    dataKey?: (typeof statusKeys)[number]; // 'toDo', 'inProgress', 'blocked'
    payload?: any; // The raw data item for the bar
  }>;
  label?: string; // Date in full view, teamMemberName in zoomed view
  isZoomedView: boolean; // Manually passed prop
}

const CustomTooltip = ({ active, payload, label, isZoomedView }: CustomTooltipProps) => {
  if (active && payload && payload.length && label) {
    const commonStyle = {
      backgroundColor: 'rgba(40, 40, 40, 0.92)',
      padding: '10px 14px',
      border: 'none',
      borderRadius: '8px',
      boxShadow: '0 4px 12px rgba(0,0,0,0.25)',
      fontFamily: "'Segoe UI', Tahoma, Geneva, Verdana, sans-serif",
      fontSize: '13px',
      color: '#FFFFFF',
      minWidth: '150px',
    };

    if (isZoomedView) {
      // Zoomed-in view: label is teamMemberName
      // Payload contains { name: "Status Name", value: count, dataKey: "statusKey" } for that team member
      const teamMemberName = label;

      return (
        <div style={commonStyle}>
          <p
            style={{
              margin: 0,
              fontWeight: '600',
              opacity: 0.85,
              fontSize: '0.9em',
              marginBottom: '6px',
            }}
          >
            {teamMemberName}
          </p>
          <ul
            style={{
              listStyleType: 'none',
              paddingLeft: 0,
              margin: 0,
              fontSize: '0.9em',
            }}
          >
            {payload.map((entry, index) => {
              const statusKey = entry.dataKey;
              if (!statusKey || !statusMeta[statusKey]) return null; // Should not happen with current setup

              const fontWeight = statusKey === 'blocked' ? 'bold' : '500';
              return (
                <li
                  key={`item-${index}-${entry.name}`}
                  style={{
                    marginBottom: '4px',
                    display: 'flex',
                    justifyContent: 'space-between',
                  }}
                >
                  <span
                    style={{
                      color: statusMeta[statusKey].color,
                      fontWeight: fontWeight,
                    }}
                  >
                    {entry.name}:
                  </span>
                  <span style={{ fontWeight: 'bold', marginLeft: '10px' }}>{entry.value}</span>
                </li>
              );
            })}
          </ul>
        </div>
      );
    } else {
      // Original full view logic: label is date
      const dayData = sprintDataFull.find((d) => d.date === label);
      if (!dayData) return null;

      let totalDayToDo = 0;
      let totalDayInProgress = 0;
      let totalDayBlocked = 0;

      teamMembers.forEach((member) => {
        totalDayToDo += dayData[member.id]?.toDo || 0;
        totalDayInProgress += dayData[member.id]?.inProgress || 0;
        totalDayBlocked += dayData[member.id]?.blocked || 0;
      });

      return (
        <div style={commonStyle}>
          <p
            style={{
              margin: 0,
              fontWeight: '600',
              opacity: 0.85,
              fontSize: '0.9em',
              marginBottom: '6px',
            }}
          >
            {label}
          </p>
          <ul
            style={{
              listStyleType: 'none',
              paddingLeft: 0,
              margin: 0,
              fontSize: '0.9em',
            }}
          >
            <li
              style={{
                marginBottom: '4px',
                display: 'flex',
                justifyContent: 'space-between',
              }}
            >
              <span style={{ color: statusMeta.toDo.color, fontWeight: '500' }}>
                {statusMeta.toDo.name}:
              </span>
              <span style={{ fontWeight: 'bold', marginLeft: '10px' }}>{totalDayToDo}</span>
            </li>
            <li
              style={{
                marginBottom: '4px',
                display: 'flex',
                justifyContent: 'space-between',
              }}
            >
              <span
                style={{
                  color: statusMeta.inProgress.color,
                  fontWeight: '500',
                }}
              >
                {statusMeta.inProgress.name}:
              </span>
              <span style={{ fontWeight: 'bold', marginLeft: '10px' }}>{totalDayInProgress}</span>
            </li>
            <li style={{ display: 'flex', justifyContent: 'space-between' }}>
              <span style={{ color: statusMeta.blocked.color, fontWeight: 'bold' }}>
                {statusMeta.blocked.name}:
              </span>
              <span style={{ fontWeight: 'bold', marginLeft: '10px' }}>{totalDayBlocked}</span>
            </li>
          </ul>
        </div>
      );
    }
  }
  return null;
};

const CustomAvatarXAxisTick = (props: { x: number; y: number; payload: { value: string } }) => {
  const { x, y, payload } = props;
  const teamMemberName = payload.value;
  const memberInfo = teamMembers.find((member) => member.name === teamMemberName);
  const [isHovered, setIsHovered] = useState(false); // State for hover effect

  const handleAvatarClick = () => {
    if (memberInfo) {
      const message = {
        type: 'tool',
        payload: {
          toolName: 'show_user_status',
          params: {
            id: memberInfo.id,
            name: memberInfo.name,
            avatarUrl: memberInfo.avatarUrl,
          },
        },
      };
      postMessageToParent(message);
    }
  };

  if (memberInfo && memberInfo.avatarUrl) {
    const baseAvatarSize = 24; // Diameter of the avatar
    const yPositionOffset = 8; // Determines vertical placement relative to Recharts y

    const scale = isHovered ? 1.15 : 1.0; // Scale factor for hover effect

    // Transform to:
    // 1. Translate to the intended center of the avatar (x, y + yPositionOffset).
    // 2. Apply scaling.
    // 3. Translate back by half of the base size, so the image (drawn at 0,0) is centered before scaling.
    const transformValue = `translate(${x}, ${y + yPositionOffset}) scale(${scale}) translate(${-baseAvatarSize / 2}, ${-baseAvatarSize / 2})`;

    return (
      <g
        transform={transformValue}
        onClick={handleAvatarClick}
        style={{ cursor: 'pointer', transition: 'transform 0.1s ease-out' }} // Added transition
        onMouseEnter={() => setIsHovered(true)}
        onMouseLeave={() => setIsHovered(false)}
      >
        <image
          href={memberInfo.avatarUrl}
          x={0} // Image is drawn from the (0,0) of the transformed <g>
          y={0}
          height={baseAvatarSize} // Image base size is constant
          width={baseAvatarSize} // Image base size is constant
          clipPath="url(#clipCircle)" // Clip path is for a 24x24 image starting at 0,0
        />
        {isHovered && (
          <g>
            <rect
              x={baseAvatarSize + 8} // Position 8px to the right of the avatar (increased from 4px)
              y={(baseAvatarSize - 16) / 2} // Vertically center with the avatar
              width={70} // Width of the tooltip background (increased from 44px)
              height={16} // Height of the tooltip background
              rx={3} // Rounded corners for the background
              ry={3}
              fill="rgb(50, 50, 50)" // Solid dark background
            />
            <text
              x={baseAvatarSize + 8 + 70 / 2} // Horizontally center text in the rect (increased x offset and width)
              y={baseAvatarSize / 2} // Vertically center text with the avatar
              fill="#FFFFFF"
              fontSize="10px"
              textAnchor="middle"
              dominantBaseline="middle" // Ensure proper vertical alignment of text
              style={{ pointerEvents: 'none' }} // Ensure text doesn't interfere with mouse events on avatar
            >
              Show profile
            </text>
          </g>
        )}
      </g>
    );
  }
  // Fallback to text if no avatar
  return <div>name</div>;
};

// --- Graph Component ---
export function Graph() {
  const [zoomedDate, setZoomedDate] = useState<string | null>(null);

  const isZoomed = !!zoomedDate;

  const chartData = useMemo(() => {
    if (isZoomed && zoomedDate) {
      const dayEntry = sprintDataFull.find((d) => d.date === zoomedDate);
      if (!dayEntry) return [];
      return teamMembers.map((member) => ({
        teamMemberId: member.id,
        teamMemberName: member.name,
        toDo: dayEntry[member.id]?.toDo || 0,
        inProgress: dayEntry[member.id]?.inProgress || 0,
        blocked: dayEntry[member.id]?.blocked || 0,
        originalColor: member.color,
      })) as ProcessedChartItemZoomedView[];
    }
    return originalProcessedDataFullView;
  }, [isZoomed, zoomedDate]);

  const handleChartClick = (clickEventData?: { activeLabel?: string }) => {
    if (isZoomed || !clickEventData || !clickEventData.activeLabel) {
      return;
    }
    const clickedDate = clickEventData.activeLabel;
    setZoomedDate(clickedDate); // Directly set zoomedDate on single click
  };

  return (
    <div
      style={{
        fontFamily:
          "'Segoe UI', -apple-system, BlinkMacSystemFont, Roboto, 'Helvetica Neue', sans-serif",
        backgroundColor: '#F8F9FA',
        boxShadow: '0 6px 18px rgba(0,0,0,0.08)',
        margin: 'auto',
        position: 'relative',
      }}
    >
      <div style={{ width: '100%', height: 425 }}>
        <ResponsiveContainer width="100%" height="100%">
          <BarChart
            data={
              chartData as {
                date: string;
                toDo: number;
                inProgress: number;
                blocked: number;
              }[]
            }
            margin={{
              top: 5,
              right: isZoomed ? 20 : 5,
              left: isZoomed ? 5 : 10,
              bottom: isZoomed ? 25 : 20,
            }} // Increased bottom margin for zoomed view avatars
            onClick={isZoomed ? undefined : handleChartClick}
            barCategoryGap={isZoomed ? '25%' : '30%'}
            barGap={isZoomed ? 0 : 4}
          >
            <defs>
              {/* Gradients */}
              {teamMembers.map((member) => (
                <linearGradient
                  id={member.gradientId}
                  x1="0"
                  y1="0"
                  x2="0"
                  y2="1"
                  key={member.gradientId}
                >
                  <stop offset="5%" stopColor={member.color} stopOpacity={0.9} />
                  <stop offset="95%" stopColor={member.color} stopOpacity={0.6} />
                </linearGradient>
              ))}
              {/* ClipPath for Avatar */}
              <clipPath id="clipCircle">
                <circle r="12" cx="12" cy="12" /> {/* Radius is half of avatarSize */}
              </clipPath>
            </defs>
            <CartesianGrid strokeDasharray="4 4" stroke="#E0E0E0" vertical={false} />
            <XAxis
              dataKey={isZoomed ? 'teamMemberName' : 'date'}
              stroke="#78909C"
              fontSize="11px"
              axisLine={false}
              tickLine={false}
              padding={{ left: 0, right: 0 }}
              interval={0}
              // @ts-expect-error - CustomAvatarXAxisTick is not typed correctly
              {...(isZoomed && { tick: <CustomAvatarXAxisTick />, dy: 10 })}
            />
            <YAxis
              stroke="#78909C"
              fontSize="11px"
              axisLine={false}
              tickLine={false}
              tickCount={5}
              width={35}
              allowDecimals={false}
            />
            <Tooltip
              content={<CustomTooltip isZoomedView={isZoomed} />}
              cursor={{ fill: 'rgba(176, 190, 197, 0.08)' }}
            />

            {isZoomed
              ? // Zoomed View: Bars are statuses, stacked, NOW COLORED by mapped team member GRADIENTS
                statusKeys.map((statusKey) => (
                  <Bar
                    key={statusKey}
                    dataKey={statusKey}
                    stackId="zoomedDayStack"
                    name={statusMeta[statusKey].name}
                    fill={`url(#${fullViewStatusToGradientMapping[statusKey]})`} // Use team member GRADIENTS
                    // @ts-expect-error - RoundedBar is not typed correctly
                    shape={<RoundedBar />}
                    barSize={50}
                  />
                ))
              : statusKeys.map((statusKey) => (
                  <Bar
                    key={statusKey}
                    dataKey={statusKey}
                    stackId="fullViewStack"
                    name={statusMeta[statusKey].name} // Name is status (e.g. "To Do") for tooltip payload if it were used
                    fill={`url(#${fullViewStatusToGradientMapping[statusKey]})`} // Color from team member gradients
                    // @ts-expect-error - RoundedBar is not typed correctly
                    shape={<RoundedBar />}
                  />
                ))}
            {isZoomed ? (
              <Legend
                payload={statusKeys.map((key, index) => ({
                  value: statusMeta[key].name,
                  type: 'square',
                  color: teamMembers[index % teamMembers.length].color, // Use team member colors in order
                }))}
                wrapperStyle={{
                  fontSize: '11px',
                  paddingTop: '10px',
                  paddingBottom: '0px',
                }}
              />
            ) : (
              <Legend // Legend for Full View (zoomed-out graph) - NOW WITH UPDATED COLORS
                payload={statusKeys.map((key, index) => ({
                  value: statusMeta[key].name,
                  type: 'square',
                  color: teamMembers[index % teamMembers.length].color, // Use team member colors in order
                }))}
                wrapperStyle={{
                  fontSize: '11px',
                  paddingTop: '10px',
                  paddingBottom: '0px',
                }}
                align="center"
                verticalAlign="bottom"
              />
            )}
          </BarChart>
        </ResponsiveContainer>
      </div>
      {!isZoomed && (
        <p
          style={{
            textAlign: 'center',
            marginTop: '5px',
            fontSize: '10px',
            color: '#90A4AE',
          }}
        ></p>
      )}
    </div>
  );
}


================================================
FILE: examples/server/app/images.d.ts
================================================
declare module '*.svg' {
  const content: unknown;
  export default content;
}


================================================
FILE: examples/server/app/root.tsx
================================================
import {
  isRouteErrorResponse,
  Links,
  Meta,
  Outlet,
  Scripts,
  ScrollRestoration,
} from 'react-router';

import type { Route } from './+types/root';
import './app.css';

export const links: Route.LinksFunction = () => [
  { rel: 'preconnect', href: 'https://fonts.googleapis.com' },
  {
    rel: 'preconnect',
    href: 'https://fonts.gstatic.com',
    crossOrigin: 'anonymous',
  },
  {
    rel: 'stylesheet',
    href: 'https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,100..900;1,14..32,100..900&display=swap',
  },
];

export function Layout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <Meta />
        <Links />
      </head>
      <body>
        {children}
        <ScrollRestoration />
        <Scripts />
      </body>
    </html>
  );
}

export default function App() {
  return <Outlet />;
}

export function ErrorBoundary({ error }: Route.ErrorBoundaryProps) {
  let message = 'Oops!';
  let details = 'An unexpected error occurred.';
  let stack: string | undefined;

  if (isRouteErrorResponse(error)) {
    message = error.status === 404 ? '404' : 'Error';
    details =
      error.status === 404 ? 'The requested page could not be found.' : error.statusText || details;
  } else if (import.meta.env.DEV && error && error instanceof Error) {
    details = error.message;
    stack = error.stack;
  }

  return (
    <main className="container mx-auto p-4 pt-16">
      <h1>{message}</h1>
      <p>{details}</p>
      {stack && (
        <pre className="w-full overflow-x-auto p-4">
          <code>{stack}</code>
        </pre>
      )}
    </main>
  );
}


================================================
FILE: examples/server/app/routes/home.tsx
================================================
export function meta() {
  return [
    { title: 'New React Router App' },
    { name: 'description', content: 'Welcome to React Router!' },
  ];
}

export default function Home() {
  return <div>Welcome</div>;
}


================================================
FILE: examples/server/app/routes/task.tsx
================================================
import { Graph } from '../graph/graph';

export function meta() {
  return [{ title: 'Task Status' }];
}

export const loader = async ({ request }: { request: Request }) => {
  const url = new URL(request.url);
  const host = url.host;
  const pathname = url.pathname;

  return { url: request.url, host, pathname };
};

export default function Task() {
  return <Graph />;
}


================================================
FILE: examples/server/app/routes/user.tsx
================================================
import { User } from '../user/user';

export function meta() {
  return [{ title: 'User' }];
}

export const loader = async ({ request }: { request: Request }) => {
  const url = new URL(request.url);
  const queryParams = url.searchParams;

  return {
    user: {
      id: queryParams.get('id') || '',
      name: queryParams.get('name') || '',
      avatarUrl: queryParams.get('avatarUrl') || '',
    },
  };
};

export default function UserProfile({
  loaderData,
}: {
  loaderData: Awaited<ReturnType<typeof loader>>;
}) {
  const { user } = loaderData;
  return <User user={user} />;
}


================================================
FILE: examples/server/app/routes.ts
================================================
import { type RouteConfig, index, route } from '@react-router/dev/routes';

export default [
  index('routes/home.tsx'),
  route('task', 'routes/task.tsx'),
  route('user', 'routes/user.tsx'),
] satisfies RouteConfig;


================================================
FILE: examples/server/app/user/user.tsx
================================================
import React from 'react';
import {
  AreaChart,
  Area,
  XAxis,
  YAxis,
  CartesianGrid,
  Tooltip,
  ResponsiveContainer,
} from 'recharts';
import { postMessageToParent } from '../utils/messageUtils';

interface UserInfo {
  id: string;
  name: string;
  avatarUrl: string;
  location?: string;
}

export function User({ user }: { user: UserInfo }) {
  const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'];
  const taskCounts = [80, 140, 110, 170, 95, 155];
  const data = months.map((m, i) => ({ month: m, tasks: taskCounts[i] }));

  const avg = Math.round(taskCounts.reduce((sum, v) => sum + v, 0) / taskCounts.length);
  const reachPct = Math.round((taskCounts[taskCounts.length - 1] / Math.max(...taskCounts)) * 100);

  const handleNudge = () => {
    if (user.id) {
      const message = {
        type: 'tool',
        payload: {
          toolName: 'nudge_team_member',
          params: {
            name: user.name,
          },
        },
      };
      postMessageToParent(message);
    }
  };

  const handleAskChat = (taskTitle: string) => {
    const message = {
      type: 'prompt',
      payload: {
        prompt: `How do I ${taskTitle}?`,
      },
    };
    postMessageToParent(message);
  };

  return (
    <div style={styles.card}>
      {/* header */}
      <div style={styles.header}>
        <img src={user.avatarUrl} alt={`${user.name}’s avatar`} style={styles.avatar} />
        <div>
          <h2 style={styles.name}>{user.name}</h2>
          {user.location && <div style={styles.location}>{user.location}</div>}
        </div>
      </div>

      {/* performance overview */}
      <div style={{ padding: '0 16px', width: '100%' }}>
        <h3 style={styles.sectionTitle}>Performance Overview</h3>
        <div style={styles.statsRow}>
          <div>
            <span style={styles.statLabel}>Average&nbsp;</span>
            <span style={styles.statValueGreen}>{avg}</span>
          </div>
          <div>
            <span style={styles.statLabel}>Reach&nbsp;</span>
            <span style={styles.statValueRed}>{reachPct}%</span>
          </div>
        </div>
        <div style={{ height: 120, width: '100%' }}>
          <ResponsiveContainer>
            <AreaChart data={data} margin={{ top: 0, right: 0, left: 0, bottom: 0 }}>
              <defs>
                <linearGradient id="colorTasks" x1="0" y1="0" x2="0" y2="1">
                  <stop offset="5%" stopColor="#1976d2" stopOpacity={0.4} />
                  <stop offset="95%" stopColor="#1976d2" stopOpacity={0.05} />
                </linearGradient>
              </defs>
              <CartesianGrid stroke="#eee" strokeDasharray="3 3" />
              <XAxis dataKey="month" tick={{ fill: '#666' }} />
              <YAxis hide domain={[0, 'dataMax + 20']} />
              <Tooltip
                contentStyle={{ borderRadius: 8 }}
                formatter={(value: number) => [`${value}`, 'Tasks']}
              />
              <Area
                type="monotone"
                dataKey="tasks"
                stroke="#1976d2"
                fill="url(#colorTasks)"
                strokeWidth={2}
                activeDot={{ r: 5 }}
              />
            </AreaChart>
          </ResponsiveContainer>
        </div>
      </div>

      {/* summary tiles */}
      <div style={styles.tiles}>
        {[
          { label: 'Completed', value: 1243, gradient: ['#FF8A65', '#FF7043'] },
          { label: 'Pending', value: 289, gradient: ['#4FC3F7', '#29B6F6'] },
          { label: 'Blocked', value: 67, gradient: ['#E57373', '#EF5350'] },
        ].map((tile) => (
          <div
            key={tile.label}
            style={{
              ...styles.tile,
              background: `linear-gradient(135deg, ${tile.gradient[0]}, ${tile.gradient[1]})`,
            }}
          >
            <div style={styles.tileValue}>{tile.value}</div>
            <div style={styles.tileLabel}>{tile.label}</div>
          </div>
        ))}
      </div>

      {/* blocked tasks */}
      <div style={styles.blockedSection}>
        <h3 style={styles.sectionTitle}>Blocked Tasks</h3>
        <div style={styles.tasksList}>
          {[
            {
              id: 1,
              title: 'Add a route to React Router app',
              priority: 'High',
            },
            {
              id: 2,
              title: 'Fix database connection timeout issue',
              priority: 'Medium',
            },
            {
              id: 3,
              title: 'Turn on Vision Mode in Playwright MCP',
              priority: 'High',
            },
          ].map((task) => (
            <div key={task.id} style={styles.taskItem}>
              <div style={styles.taskContent}>
                <div style={styles.taskPriority}>
                  <span
                    style={{
                      ...styles.priorityBadge,
                      ...(task.priority === 'High' ? styles.priorityHigh : styles.priorityMedium),
                    }}
                  >
                    {task.priority}
                  </span>
                </div>
                <div style={styles.taskTitle}>{task.title}</div>
              </div>
              <button style={styles.askChatButton} onClick={() => handleAskChat(task.title)}>
                Ask Chat
              </button>
            </div>
          ))}
        </div>
      </div>

      {/* nudge button */}
      <button onClick={handleNudge} style={styles.button}>
        Nudge
      </button>
    </div>
  );
}

const styles: Record<string, React.CSSProperties> = {
  card: {
    // maxWidth: 500,
    borderRadius: 8,
    background: '#fff',
    boxShadow: '0 4px 12px rgba(0,0,0,0.08)',
    overflow: 'hidden',
    fontFamily: 'system-ui, sans-serif',
  },
  header: {
    display: 'flex',
    alignItems: 'center',
    padding: '16px',
    background: '#E3F2FD',
    color: '#1E88E5',
    gap: 12,
  },
  avatar: {
    width: 48,
    height: 48,
    borderRadius: '50%',
    objectFit: 'cover',
    border: '2px solid #fff',
  },
  name: {
    margin: 0,
    fontSize: '1.2rem',
  },
  location: {
    fontSize: '0.85rem',
    opacity: 0.85,
  },
  sectionTitle: {
    margin: '16px 0 4px',
    fontSize: '1rem',
    color: '#333',
  },
  statsRow: {
    display: 'flex',
    justifyContent: 'space-between',
    paddingBottom: 8,
    fontSize: '0.9rem',
  },
  statLabel: {
    color: '#555',
  },
  statValueGreen: {
    color: '#388E3C',
    fontWeight: 600,
  },
  statValueRed: {
    color: '#D32F2F',
    fontWeight: 600,
  },
  tiles: {
    display: 'flex',
    gap: 8,
    padding: '16px',
  },
  tile: {
    flex: 1,
    borderRadius: 6,
    padding: 12,
    color: '#fff',
    textAlign: 'center' as const,
  },
  tileValue: {
    fontSize: '1.1rem',
    fontWeight: 600,
  },
  tileLabel: {
    fontSize: '0.85rem',
    marginTop: 4,
  },
  button: {
    width: '100%',
    padding: '10px 0',
    border: 'none',
    background: '#BBDEFB',
    color: '#1565C0',
    fontSize: '1rem',
    fontWeight: 500,
    cursor: 'pointer',
  },
  blockedSection: {
    padding: '0 16px',
    borderTop: '1px solid #f0f0f0',
    paddingTop: 16,
  },
  tasksList: {
    display: 'flex',
    flexDirection: 'column' as const,
    gap: 8,
    marginBottom: 16,
  },
  taskItem: {
    display: 'flex',
    alignItems: 'center',
    justifyContent: 'space-between',
    padding: 12,
    background: '#FAFAFA',
    borderRadius: 6,
    border: '1px solid #E0E0E0',
  },
  taskContent: {
    flex: 1,
    display: 'flex',
    flexDirection: 'row' as const,
    gap: 4,
  },
  taskTitle: {
    fontSize: '0.9rem',
    color: '#333',
    fontWeight: 500,
  },
  taskPriority: {
    display: 'flex',
    alignItems: 'center',
  },
  priorityBadge: {
    fontSize: '0.75rem',
    fontWeight: 600,
    padding: '2px 6px',
    borderRadius: 3,
    textTransform: 'uppercase' as const,
  },
  priorityHigh: {
    background: '#FFEBEE',
    color: '#C62828',
    marginRight: '30px',
  },
  priorityMedium: {
    background: '#FFF3E0',
    color: '#E65100',
    marginRight: '10px',
  },
  askChatButton: {
    padding: '6px 12px',
    border: 'none',
    background: '#E3F2FD',
    color: '#1976D2',
    fontSize: '0.8rem',
    fontWeight: 500,
    borderRadius: 4,
    cursor: 'pointer',
    marginLeft: 12,
  },
};


================================================
FILE: examples/server/app/utils/messageUtils.ts
================================================
export function postMessageToParent(message: any) {
  console.log('Sending message:', message);
  // @ts-expect-error - window is not typed correctly
  if (window.parent) {
    // @ts-expect-error - window is not typed correctly
    window.parent.postMessage(message, '*');
  }
}


================================================
FILE: examples/server/biome.json
================================================
{
  "$schema": "https://biomejs.dev/schemas/1.6.2/schema.json",
  "organizeImports": {
    "enabled": true
  },
  "files": {
    "ignore": ["worker-configuration.d.ts"]
  },
  "vcs": {
    "enabled": true,
    "clientKind": "git",
    "useIgnoreFile": true
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "suspicious": {
        "noExplicitAny": "off",
        "noDebugger": "off",
        "noConsoleLog": "off",
        "noConfusingVoidType": "off"
      },
      "style": {
        "noNonNullAssertion": "off"
      }
    }
  },
  "formatter": {
    "enabled": true,
    "indentWidth": 4,
    "lineWidth": 100
  }
}


================================================
FILE: examples/server/package.json
================================================
{
  "name": "remote-mcp-server-authless",
  "private": true,
  "type": "module",
  "scripts": {
    "build": "react-router build",
    "cf-typegen": "wrangler types",
    "deploy": "pnpm run build && wrangler deploy",
    "dev": "react-router dev",
    "preview": "pnpm run build && vite preview",
    "typecheck": "npm run cf-typegen && react-router typegen && tsc -b"
  },
  "packageManager": "pnpm@10.11.0+sha512.6540583f41cc5f628eb3d9773ecee802f4f9ef9923cc45b69890fb47991d4b092964694ec3a4f738a420c918a333062c8b925d312f42e4f0c263eb603551f977",
  "dependencies": {
    "@mcp-ui/server": "^5.2.0",
    "@modelcontextprotocol/sdk": "^1.22.0",
    "@vis.gl/react-google-maps": "^1.5.2",
    "agents": "^0.0.80",
    "isbot": "^5.1.27",
    "leaflet": "^1.9.4",
    "react": "^19.1.0",
    "react-dom": "^19.1.0",
    "react-leaflet": "^5.0.0",
    "react-router": "^7.5.3",
    "recharts": "^2.15.3",
    "zod": "^3.24.4"
  },
  "devDependencies": {
    "@cloudflare/vite-plugin": "^1.0.12",
    "@cloudflare/workers-types": "^4.20250515.0",
    "@react-router/dev": "^7.5.3",
    "@tailwindcss/vite": "^4.1.4",
    "@types/google.maps": "^3.58.1",
    "@types/leaflet": "^1.9.17",
    "@types/node": "^20",
    "@types/react": "^19.1.2",
    "@types/react-dom": "^19.1.2",
    "@types/recharts": "^2.0.1",
    "prettier": "^3.5.3",
    "tailwindcss": "^4.1.4",
    "typescript": "^5.8.3",
    "vite": "^6.3.3",
    "vite-tsconfig-paths": "^5.1.4",
    "wrangler": "^4.15.1"
  }
}


================================================
FILE: examples/server/pnpm-workspace.yaml
================================================
packages: []


================================================
FILE: examples/server/react-router.config.ts
================================================
import type { Config } from '@react-router/dev/config';

export default {
  ssr: true,
  future: {
    unstable_viteEnvironmentApi: true,
  },
} satisfies Config;


================================================
FILE: examples/server/src/index.ts
================================================
import { McpAgent } from 'agents/mcp';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';
import { createRequestHandler } from 'react-router';
import { createUIResource } from '@mcp-ui/server';

declare module 'react-router' {
  export interface AppLoadContext {
    cloudflare: {
      env: CloudflareEnvironment;
      ctx: ExecutionContext;
    };
  }
}

const requestHandler = createRequestHandler(
  () => import('virtual:react-router/server-build'),
  import.meta.env.MODE,
);

// Define our MCP agent with tools
export class MyMCP extends McpAgent {
  server = new McpServer({
    name: 'MCP-UI Example',
    version: '1.0.0',
  });

  async init() {
    const requestUrl = this.props.requestUrl as string;
    const url = new URL(requestUrl);
    const requestHost = url.host;

    this.server.tool(
      'get_tasks_status',
      'The main way to get a textual representation of the status of all tasks',
      async () => {
        const todayData = {
          alice: { remaining: 12, toDo: 5, inProgress: 4, blocked: 3 },
          bob: { remaining: 18, toDo: 11, inProgress: 4, blocked: 3 },
          charlie: { remaining: 14, toDo: 6, inProgress: 5, blocked: 3 },
        };

        // Full sprint data for weekly summary
        const sprintDataFull = [
          {
            date: '5/10',
            alice: { remaining: 8, toDo: 3, inProgress: 3, blocked: 2 },
            bob: { remaining: 7, toDo: 2, inProgress: 3, blocked: 2 },
            charlie: { remaining: 9, toDo: 4, inProgress: 3, blocked: 2 },
          },
          {
            date: '5/11',
            alice: { remaining: 7, toDo: 2, inProgress: 3, blocked: 2 },
            bob: { remaining: 6, toDo: 2, inProgress: 2, blocked: 2 },
            charlie: { remaining: 8, toDo: 3, inProgress: 3, blocked: 2 },
          },
          {
            date: '5/12',
            alice: { remaining: 9, toDo: 3, inProgress: 4, blocked: 2 },
            bob: { remaining: 8, toDo: 3, inProgress: 3, blocked: 2 },
            charlie: { remaining: 10, toDo: 4, inProgress: 4, blocked: 2 },
          },
          {
            date: '5/13',
            alice: { remaining: 6, toDo: 1, inProgress: 2, blocked: 3 },
            bob: { remaining: 9, toDo: 3, inProgress: 3, blocked: 3 },
            charlie: { remaining: 11, toDo: 5, inProgress: 3, blocked: 3 },
          },
          {
            date: '5/14',
            alice: { remaining: 10, toDo: 4, inProgress: 3, blocked: 3 },
            bob: { remaining: 9, toDo: 3, inProgress: 3, blocked: 3 },
            charlie: { remaining: 12, toDo: 5, inProgress: 4, blocked: 3 },
          },
          {
            date: '5/15',
            alice: { remaining: 11, toDo: 4, inProgress: 4, blocked: 3 },
            bob: { remaining: 10, toDo: 3, inProgress: 4, blocked: 3 },
            charlie: { remaining: 13, toDo: 6, inProgress: 4, blocked: 3 },
          },
          {
            date: '5/16',
            alice: { remaining: 12, toDo: 5, inProgress: 4, blocked: 3 },
            bob: { remaining: 11, toDo: 4, inProgress: 4, blocked: 3 },
            charlie: { remaining: 14, toDo: 6, inProgress: 5, blocked: 3 },
          },
        ];
        const teamMembers = ['alice', 'bob', 'charlie'];

        let statusText = "Today's Task Status:\n\n";

        statusText += 'Alice:\n';
        statusText += `  To Do: ${todayData.alice.toDo}\n`;
        statusText += `  In Progress: ${todayData.alice.inProgress}\n`;
        statusText += `  Blocked: ${todayData.alice.blocked}\n`;
        statusText += `  Remaining: ${todayData.alice.remaining}\n\n`;

        statusText += 'Bob:\n';
        statusText += `  To Do: ${todayData.bob.toDo}\n`;
        statusText += `  In Progress: ${todayData.bob.inProgress}\n`;
        statusText += `  Blocked: ${todayData.bob.blocked}\n`;
        statusText += `  Remaining: ${todayData.bob.remaining}\n\n`;

        statusText += 'Charlie:\n';
        statusText += `  To Do: ${todayData.charlie.toDo}\n`;
        statusText += `  In Progress: ${todayData.charlie.inProgress}\n`;
        statusText += `  Blocked: ${todayData.charlie.blocked}\n`;
        statusText += `  Remaining: ${todayData.charlie.remaining}\n`;

        // Calculate weekly totals
        let weeklyTotalToDo = 0;
        let weeklyTotalInProgress = 0;
        let weeklyTotalBlocked = 0;

        sprintDataFull.forEach((day) => {
          teamMembers.forEach((member) => {
            // @ts-expect-error - member is a string, but it's used as an index type for day
            weeklyTotalToDo += day[member]?.toDo || 0;
            // @ts-expect-error - member is a string, but it's used as an index type for day
            weeklyTotalInProgress += day[member]?.inProgress || 0;
            // @ts-expect-error - member is a string, but it's used as an index type for day
            weeklyTotalBlocked += day[member]?.blocked || 0;
          });
        });

        statusText += '\n\nSummary for the past week:\n';
        statusText += `Total tasks To Do: ${weeklyTotalToDo}\n`;
        statusText += `Total tasks In Progress: ${weeklyTotalInProgress}\n`;
        statusText += `Total tasks Blocked: ${weeklyTotalBlocked}\n`;

        return {
          content: [{ type: 'text', text: statusText }],
        };
      },
    );

    this.server.tool('nudge_team_member', { name: z.string() }, async ({ name }) => ({
      content: [{ type: 'text', text: 'Nudged ' + name + '!' }],
    }));

    this.server.tool(
      'show_task_status',
      'Displays a UI for the user to see the status of tasks. Use get_tasks_status unless asked to SHOW the status',
      async () => {
        const scheme =
          requestHost.includes('localhost') || requestHost.includes('127.0.0.1') ? 'http' : 'https';

        const pickerPageUrl = `${scheme}://${requestHost}/task`;

        // Generate a unique URI for this specific invocation of the file picker UI.
        // This URI identifies the resource block itself, not the content of the iframe.
        const uniqueUIAppUri = `ui://task-manager/${Date.now()}` as `ui://${string}`;
        const resourceBlock = await createUIResource({
          uri: uniqueUIAppUri,
          content: { type: 'externalUrl', iframeUrl: pickerPageUrl },
          encoding: 'text',
        });

        return {
          content: [resourceBlock],
        };
      },
    );
    this.server.tool(
      'show_user_status',
      'Displays a UI for the user to see the status of a user and their tasks',
      { id: z.string(), name: z.string(), avatarUrl: z.string() },
      async ({ id, name, avatarUrl }) => {
        const scheme =
          requestHost.includes('localhost') || requestHost.includes('127.0.0.1') ? 'http' : 'https';

        const pickerPageUrl = `${scheme}://${requestHost}/user?id=${id}&name=${name}&avatarUrl=${avatarUrl}`;

        // Generate a unique URI for this specific invocation of the file picker UI.
        // This URI identifies the resource block itself, not the content of the iframe.
        const uniqueUIAppUri = `ui://user-profile/${Date.now()}` as `ui://${string}`;
        const resourceBlock = await createUIResource({
          uri: uniqueUIAppUri,
          content: { type: 'externalUrl', iframeUrl: pickerPageUrl },
          encoding: 'text',
        });

        return {
          content: [resourceBlock],
        };
      },
    );

  }
}

export default {
  fetch(request: Request, env: Env, ctx: ExecutionContext) {
    if (request.method === 'OPTIONS') {
      return new Response(null, {
        headers: {
          'Access-Control-Allow-Origin': '*',
          'Access-Control-Allow-Methods': 'GET,HEAD,OPTIONS',
          'Access-Control-Allow-Headers': '*',
        },
      });
    }

    const url = new URL(request.url);
    ctx.props.requestUrl = request.url;

    if (url.pathname === '/sse' || url.pathname === '/sse/message') {
      return MyMCP.serveSSE('/sse').fetch(request, env, ctx);
    }

    if (url.pathname === '/mcp') {
      return MyMCP.serve('/mcp').fetch(request, env, ctx);
    }

    return requestHandler(request, {
      cloudflare: { env, ctx },
    });
    // return new Response("Not found", { status: 404 });
  },
};


================================================
FILE: examples/server/tsconfig.cloudflare.json
================================================
{
  "extends": "./tsconfig.json",
  "include": [
    ".react-router/types/**/*",
    "app/**/*",
    "app/**/.server/**/*",
    "app/**/.client/**/*",
    "workers/**/*",
    "worker-configuration.d.ts"
  ],
  "compilerOptions": {
    "composite": true,
    "strict": true,
    "lib": ["DOM", "DOM.Iterable", "ES2022"],
    "types": ["@cloudflare/workers-types", "vite/client"],
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "baseUrl": ".",
    "rootDirs": [".", "./.react-router/types"],
    "paths": {
      "~/*": ["./app/*"]
    },
    "esModuleInterop": true,
    "resolveJsonModule": true
  }
}


================================================
FILE: examples/server/tsconfig.json
================================================
{
  "compilerOptions": {
    "target": "es2021",
    "lib": ["es2021"],
    "jsx": "react-jsx",
    "module": "es2022",
    "moduleResolution": "Bundler",
    "resolveJsonModule": true,
    "allowJs": true,
    "checkJs": false,
    "noEmit": true,
    "isolatedModules": true,
    "allowSyntheticDefaultImports": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true
  },
  "include": ["worker-configuration.d.ts", "src/**/*.ts", "app/**/*.ts", "app/**/*.tsx"]
}


================================================
FILE: examples/server/tsconfig.node.json
================================================
{
  "extends": "./tsconfig.json",
  "include": ["vite.config.ts"],
  "compilerOptions": {
    "composite": true,
    "strict": true,
    "types": ["node"],
    "lib": ["ES2022"],
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler"
  }
}


================================================
FILE: examples/server/vite.config.ts
================================================
import { reactRouter } from '@react-router/dev/vite';
import { cloudflare } from '@cloudflare/vite-plugin';
import tailwindcss from '@tailwindcss/vite';
import { defineConfig } from 'vite';
import tsconfigPaths from 'vite-tsconfig-paths';

export default defineConfig({
  plugins: [
    cloudflare({ viteEnvironment: { name: 'ssr' } }),
    tailwindcss(),
    reactRouter(),
    tsconfigPaths(),
  ],
});


================================================
FILE: examples/server/worker-configuration.d.ts
================================================
/* eslint-disable */
// Generated by Wrangler by running `wrangler types` (hash: 15dd420dfccac8afafeb181790b9eddb)
// Runtime types generated with workerd@1.20250508.0 2025-03-10 nodejs_compat
declare namespace Cloudflare {
  interface Env {
    MCP_OBJECT: DurableObjectNamespace<import('./src/index').MyMCP>;
  }
}
interface Env extends Cloudflare.Env {}

// Begin runtime types
/*! *****************************************************************************
Copyright (c) Cloudflare. All rights reserved.
Copyright (c) Microsoft Corporation. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use
this file except in compliance with the License. You may obtain a copy of the
License at http://www.apache.org/licenses/LICENSE-2.0
THIS CODE IS PROVIDED ON AN *AS IS* BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION ANY IMPLIED
WARRANTIES OR CONDITIONS OF TITLE, FITNESS FOR A PARTICULAR PURPOSE,
MERCHANTABLITY OR NON-INFRINGEMENT.
See the Apache Version 2.0 License for specific language governing permissions
and limitations under the License.
***************************************************************************** */
/* eslint-disable */
// noinspection JSUnusedGlobalSymbols
declare var onmessage: never;
/**
 * An abnormal event (called an exception) which occurs as a result of calling a method or accessing a property of a web API.
 *
 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMException)
 */
declare class DOMException extends Error {
  constructor(message?: string, name?: string);
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMException/message) */
  readonly message: string;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMException/name) */
  readonly name: string;
  /**
   * @deprecated
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMException/code)
   */
  readonly code: number;
  static readonly INDEX_SIZE_ERR: number;
  static readonly DOMSTRING_SIZE_ERR: number;
  static readonly HIERARCHY_REQUEST_ERR: number;
  static readonly WRONG_DOCUMENT_ERR: number;
  static readonly INVALID_CHARACTER_ERR: number;
  static readonly NO_DATA_ALLOWED_ERR: number;
  static readonly NO_MODIFICATION_ALLOWED_ERR: number;
  static readonly NOT_FOUND_ERR: number;
  static readonly NOT_SUPPORTED_ERR: number;
  static readonly INUSE_ATTRIBUTE_ERR: number;
  static readonly INVALID_STATE_ERR: number;
  static readonly SYNTAX_ERR: number;
  static readonly INVALID_MODIFICATION_ERR: number;
  static readonly NAMESPACE_ERR: number;
  static readonly INVALID_ACCESS_ERR: number;
  static readonly VALIDATION_ERR: number;
  static readonly TYPE_MISMATCH_ERR: number;
  static readonly SECURITY_ERR: number;
  static readonly NETWORK_ERR: number;
  static readonly ABORT_ERR: number;
  static readonly URL_MISMATCH_ERR: number;
  static readonly QUOTA_EXCEEDED_ERR: number;
  static readonly TIMEOUT_ERR: number;
  static readonly INVALID_NODE_TYPE_ERR: number;
  static readonly DATA_CLONE_ERR: number;
  get stack(): any;
  set stack(value: any);
}
type WorkerGlobalScopeEventMap = {
  fetch: FetchEvent;
  scheduled: ScheduledEvent;
  queue: QueueEvent;
  unhandledrejection: PromiseRejectionEvent;
  rejectionhandled: PromiseRejectionEvent;
};
declare abstract class WorkerGlobalScope extends EventTarget<WorkerGlobalScopeEventMap> {
  EventTarget: typeof EventTarget;
}
/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/console) */
interface Console {
  'assert'(condition?: boolean, ...data: any[]): void;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/clear_static) */
  clear(): void;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/count_static) */
  count(label?: string): void;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/countReset_static) */
  countReset(label?: string): void;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/debug_static) */
  debug(...data: any[]): void;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/dir_static) */
  dir(item?: any, options?: any): void;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/dirxml_static) */
  dirxml(...data: any[]): void;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/error_static) */
  error(...data: any[]): void;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/group_static) */
  group(...data: any[]): void;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/groupCollapsed_static) */
  groupCollapsed(...data: any[]): void;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/groupEnd_static) */
  groupEnd(): void;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/info_static) */
  info(...data: any[]): void;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/log_static) */
  log(...data: any[]): void;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/table_static) */
  table(tabularData?: any, properties?: string[]): void;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/time_static) */
  time(label?: string): void;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/timeEnd_static) */
  timeEnd(label?: string): void;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/timeLog_static) */
  timeLog(label?: string, ...data: any[]): void;
  timeStamp(label?: string): void;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/trace_static) */
  trace(...data: any[]): void;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/warn_static) */
  warn(...data: any[]): void;
}
declare const console: Console;
type BufferSource = ArrayBufferView | ArrayBuffer;
type TypedArray =
  | Int8Array
  | Uint8Array
  | Uint8ClampedArray
  | Int16Array
  | Uint16Array
  | Int32Array
  | Uint32Array
  | Float32Array
  | Float64Array
  | BigInt64Array
  | BigUint64Array;
declare namespace WebAssembly {
  class CompileError extends Error {
    constructor(message?: string);
  }
  class RuntimeError extends Error {
    constructor(message?: string);
  }
  type ValueType = 'anyfunc' | 'externref' | 'f32' | 'f64' | 'i32' | 'i64' | 'v128';
  interface GlobalDescriptor {
    value: ValueType;
    mutable?: boolean;
  }
  class Global {
    constructor(descriptor: GlobalDescriptor, value?: any);
    value: any;
    valueOf(): any;
  }
  type ImportValue = ExportValue | number;
  type ModuleImports = Record<string, ImportValue>;
  type Imports = Record<string, ModuleImports>;
  type ExportValue = Function | Global | Memory | Table;
  type Exports = Record<string, ExportValue>;
  class Instance {
    constructor(module: Module, imports?: Imports);
    readonly exports: Exports;
  }
  interface MemoryDescriptor {
    initial: number;
    maximum?: number;
    shared?: boolean;
  }
  class Memory {
    constructor(descriptor: MemoryDescriptor);
    readonly buffer: ArrayBuffer;
    grow(delta: number): number;
  }
  type ImportExportKind = 'function' | 'global' | 'memory' | 'table';
  interface ModuleExportDescriptor {
    kind: ImportExportKind;
    name: string;
  }
  interface ModuleImportDescriptor {
    kind: ImportExportKind;
    module: string;
    name: string;
  }
  abstract class Module {
    static customSections(module: Module, sectionName: string): ArrayBuffer[];
    static exports(module: Module): ModuleExportDescriptor[];
    static imports(module: Module): ModuleImportDescriptor[];
  }
  type TableKind = 'anyfunc' | 'externref';
  interface TableDescriptor {
    element: TableKind;
    initial: number;
    maximum?: number;
  }
  class Table {
    constructor(descriptor: TableDescriptor, value?: any);
    readonly length: number;
    get(index: number): any;
    grow(delta: number, value?: any): number;
    set(index: number, value?: any): void;
  }
  function instantiate(module: Module, imports?: Imports): Promise<Instance>;
  function validate(bytes: BufferSource): boolean;
}
/**
 * This ServiceWorker API interface represents the global execution context of a service worker.
 * Available only in secure contexts.
 *
 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ServiceWorkerGlobalScope)
 */
interface ServiceWorkerGlobalScope extends WorkerGlobalScope {
  DOMException: typeof DOMException;
  WorkerGlobalScope: typeof WorkerGlobalScope;
  btoa(data: string): string;
  atob(data: string): string;
  setTimeout(callback: (...args: any[]) => void, msDelay?: number): number;
  setTimeout<Args extends any[]>(
    callback: (...args: Args) => void,
    msDelay?: number,
    ...args: Args
  ): number;
  clearTimeout(timeoutId: number | null): void;
  setInterval(callback: (...args: any[]) => void, msDelay?: number): number;
  setInterval<Args extends any[]>(
    callback: (...args: Args) => void,
    msDelay?: number,
    ...args: Args
  ): number;
  clearInterval(timeoutId: number | null): void;
  queueMicrotask(task: Function): void;
  structuredClone<T>(value: T, options?: StructuredSerializeOptions): T;
  reportError(error: any): void;
  fetch(input: RequestInfo | URL, init?: RequestInit<RequestInitCfProperties>): Promise<Response>;
  self: ServiceWorkerGlobalScope;
  crypto: Crypto;
  caches: CacheStorage;
  scheduler: Scheduler;
  performance: Performance;
  Cloudflare: Cloudflare;
  readonly origin: string;
  Event: typeof Event;
  ExtendableEvent: typeof ExtendableEvent;
  CustomEvent: typeof CustomEvent;
  PromiseRejectionEvent: typeof PromiseRejectionEvent;
  FetchEvent: typeof FetchEvent;
  TailEvent: typeof TailEvent;
  TraceEvent: typeof TailEvent;
  ScheduledEvent: typeof ScheduledEvent;
  MessageEvent: typeof MessageEvent;
  CloseEvent: typeof CloseEvent;
  ReadableStreamDefaultReader: typeof ReadableStreamDefaultReader;
  ReadableStreamBYOBReader: typeof ReadableStreamBYOBReader;
  ReadableStream: typeof ReadableStream;
  WritableStream: typeof WritableStream;
  WritableStreamDefaultWriter: typeof WritableStreamDefaultWriter;
  TransformStream: typeof TransformStream;
  ByteLengthQueuingStrategy: typeof ByteLengthQueuingStrategy;
  CountQueuingStrategy: typeof CountQueuingStrategy;
  ErrorEvent: typeof ErrorEvent;
  EventSource: typeof EventSource;
  ReadableStreamBYOBRequest: typeof ReadableStreamBYOBRequest;
  ReadableStreamDefaultController: typeof ReadableStreamDefaultController;
  ReadableByteStreamController: typeof ReadableByteStreamController;
  WritableStreamDefaultController: typeof WritableStreamDefaultController;
  TransformStreamDefaultController: typeof TransformStreamDefaultController;
  CompressionStream: typeof CompressionStream;
  DecompressionStream: typeof DecompressionStream;
  TextEncoderStream: typeof TextEncoderStream;
  TextDecoderStream: typeof TextDecoderStream;
  Headers: typeof Headers;
  Body: typeof Body;
  Request: typeof Request;
  Response: typeof Response;
  WebSocket: typeof WebSocket;
  WebSocketPair: typeof WebSocketPair;
  WebSocketRequestResponsePair: typeof WebSocketRequestResponsePair;
  AbortController: typeof AbortController;
  AbortSignal: typeof AbortSignal;
  TextDecoder: typeof TextDecoder;
  TextEncoder: typeof TextEncoder;
  navigator: Navigator;
  Navigator: typeof Navigator;
  URL: typeof URL;
  URLSearchParams: typeof URLSearchParams;
  URLPattern: typeof URLPattern;
  Blob: typeof Blob;
  File: typeof File;
  FormData: typeof FormData;
  Crypto: typeof Crypto;
  SubtleCrypto: typeof SubtleCrypto;
  CryptoKey: typeof CryptoKey;
  CacheStorage: typeof CacheStorage;
  Cache: typeof Cache;
  FixedLengthStream: typeof FixedLengthStream;
  IdentityTransformStream: typeof IdentityTransformStream;
  HTMLRewriter: typeof HTMLRewriter;
}
declare function addEventListener<Type extends keyof WorkerGlobalScopeEventMap>(
  type: Type,
  handler: EventListenerOrEventListenerObject<WorkerGlobalScopeEventMap[Type]>,
  options?: EventTargetAddEventListenerOptions | boolean,
): void;
declare function removeEventListener<Type extends keyof WorkerGlobalScopeEventMap>(
  type: Type,
  handler: EventListenerOrEventListenerObject<WorkerGlobalScopeEventMap[Type]>,
  options?: EventTargetEventListenerOptions | boolean,
): void;
/**
 * Dispatches a synthetic event event to target and returns true if either event's cancelable attribute value is false or its preventDefault() method was not invoked, and false otherwise.
 *
 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventTarget/dispatchEvent)
 */
declare function dispatchEvent(
  event: WorkerGlobalScopeEventMap[keyof WorkerGlobalScopeEventMap],
): boolean;
/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/btoa) */
declare function btoa(data: string): string;
/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/atob) */
declare function atob(data: string): string;
/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/setTimeout) */
declare function setTimeout(callback: (...args: any[]) => void, msDelay?: number): number;
/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/setTimeout) */
declare function setTimeout<Args extends any[]>(
  callback: (...args: Args) => void,
  msDelay?: number,
  ...args: Args
): number;
/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/clearTimeout) */
declare function clearTimeout(timeoutId: number | null): void;
/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/setInterval) */
declare function setInterval(callback: (...args: any[]) => void, msDelay?: number): number;
/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/setInterval) */
declare function setInterval<Args extends any[]>(
  callback: (...args: Args) => void,
  msDelay?: number,
  ...args: Args
): number;
/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/clearInterval) */
declare function clearInterval(timeoutId: number | null): void;
/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/queueMicrotask) */
declare function queueMicrotask(task: Function): void;
/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/structuredClone) */
declare function structuredClone<T>(value: T, options?: StructuredSerializeOptions): T;
/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/reportError) */
declare function reportError(error: any): void;
/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/fetch) */
declare function fetch(
  input: RequestInfo | URL,
  init?: RequestInit<RequestInitCfProperties>,
): Promise<Response>;
declare const self: ServiceWorkerGlobalScope;
/**
 * The Web Crypto API provides a set of low-level functions for common cryptographic tasks.
 * The Workers runtime implements the full surface of this API, but with some differences in
 * the [supported algorithms](https://developers.cloudflare.com/workers/runtime-apis/web-crypto/#supported-algorithms)
 * compared to those implemented in most browsers.
 *
 * [Cloudflare Docs Reference](https://developers.cloudflare.com/workers/runtime-apis/web-crypto/)
 */
declare const crypto: Crypto;
/**
 * The Cache API allows fine grained control of reading and writing from the Cloudflare global network cache.
 *
 * [Cloudflare Docs Reference](https://developers.cloudflare.com/workers/runtime-apis/cache/)
 */
declare const caches: CacheStorage;
declare const scheduler: Scheduler;
/**
 * The Workers runtime supports a subset of the Performance API, used to measure timing and performance,
 * as well as timing of subrequests and other operations.
 *
 * [Cloudflare Docs Reference](https://developers.cloudflare.com/workers/runtime-apis/performance/)
 */
declare const performance: Performance;
declare const Cloudflare: Cloudflare;
declare const origin: string;
declare const navigator: Navigator;
interface TestController {}
interface ExecutionContext {
  waitUntil(promise: Promise<any>): void;
  passThroughOnException(): void;
  props: any;
}
type ExportedHandlerFetchHandler<Env = unknown, CfHostMetadata = unknown> = (
  request: Request<CfHostMetadata, IncomingRequestCfProperties<CfHostMetadata>>,
  env: Env,
  ctx: ExecutionContext,
) => Response | Promise<Response>;
type ExportedHandlerTailHandler<Env = unknown> = (
  events: TraceItem[],
  env: Env,
  ctx: ExecutionContext,
) => void | Promise<void>;
type ExportedHandlerTraceHandler<Env = unknown> = (
  traces: TraceItem[],
  env: Env,
  ctx: ExecutionContext,
) => void | Promise<void>;
type ExportedHandlerTailStreamHandler<Env = unknown> = (
  event: TailStream.TailEvent,
  env: Env,
  ctx: ExecutionContext,
) => TailStream.TailEventHandlerType | Promise<TailStream.TailEventHandlerType>;
type ExportedHandlerScheduledHandler<Env = unknown> = (
  controller: ScheduledController,
  env: Env,
  ctx: ExecutionContext,
) => void | Promise<void>;
type ExportedHandlerQueueHandler<Env = unknown, Message = unknown> = (
  batch: MessageBatch<Message>,
  env: Env,
  ctx: ExecutionContext,
) => void | Promise<void>;
type ExportedHandlerTestHandler<Env = unknown> = (
  controller: TestController,
  env: Env,
  ctx: ExecutionContext,
) => void | Promise<void>;
interface ExportedHandler<Env = unknown, QueueHandlerMessage = unknown, CfHostMetadata = unknown> {
  fetch?: ExportedHandlerFetchHandler<Env, CfHostMetadata>;
  tail?: ExportedHandlerTailHandler<Env>;
  trace?: ExportedHandlerTraceHandler<Env>;
  tailStream?: ExportedHandlerTailStreamHandler<Env>;
  scheduled?: ExportedHandlerScheduledHandler<Env>;
  test?: ExportedHandlerTestHandler<Env>;
  email?: EmailExportedHandler<Env>;
  queue?: ExportedHandlerQueueHandler<Env, QueueHandlerMessage>;
}
interface StructuredSerializeOptions {
  transfer?: any[];
}
/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/PromiseRejectionEvent) */
declare abstract class PromiseRejectionEvent extends Event {
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/PromiseRejectionEvent/promise) */
  readonly promise: Promise<any>;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/PromiseRejectionEvent/reason) */
  readonly reason: any;
}
declare abstract class Navigator {
  sendBeacon(
    url: string,
    body?:
      | ReadableStream
      | string
      | (ArrayBuffer | ArrayBufferView)
      | Blob
      | FormData
      | URLSearchParams
      | URLSearchParams,
  ): boolean;
  readonly userAgent: string;
  readonly hardwareConcurrency: number;
}
/**
 * The Workers runtime supports a subset of the Performance API, used to measure timing and performance,
 * as well as timing of subrequests and other operations.
 *
 * [Cloudflare Docs Reference](https://developers.cloudflare.com/workers/runtime-apis/performance/)
 */
interface Performance {
  /* [Cloudflare Docs Reference](https://developers.cloudflare.com/workers/runtime-apis/performance/#performancetimeorigin) */
  readonly timeOrigin: number;
  /* [Cloudflare Docs Reference](https://developers.cloudflare.com/workers/runtime-apis/performance/#performancenow) */
  now(): number;
}
interface AlarmInvocationInfo {
  readonly isRetry: boolean;
  readonly retryCount: number;
}
interface Cloudflare {
  readonly compatibilityFlags: Record<string, boolean>;
}
interface DurableObject {
  fetch(request: Request): Response | Promise<Response>;
  alarm?(alarmInfo?: AlarmInvocationInfo): void | Promise<void>;
  webSocketMessage?(ws: WebSocket, message: string | ArrayBuffer): void | Promise<void>;
  webSocketClose?(
    ws: WebSocket,
    code: number,
    reason: string,
    wasClean: boolean,
  ): void | Promise<void>;
  webSocketError?(ws: WebSocket, error: unknown): void | Promise<void>;
}
type DurableObjectStub<T extends Rpc.DurableObjectBranded | undefined = undefined> = Fetcher<
  T,
  'alarm' | 'webSocketMessage' | 'webSocketClose' | 'webSocketError'
> & {
  readonly id: DurableObjectId;
  readonly name?: string;
};
interface DurableObjectId {
  toString(): string;
  equals(other: DurableObjectId): boolean;
  readonly name?: string;
}
interface DurableObjectNamespace<T extends Rpc.DurableObjectBranded | undefined = undefined> {
  newUniqueId(options?: DurableObjectNamespaceNewUniqueIdOptions): DurableObjectId;
  idFromName(name: string): DurableObjectId;
  idFromString(id: string): DurableObjectId;
  get(
    id: DurableObjectId,
    options?: DurableObjectNamespaceGetDurableObjectOptions,
  ): DurableObjectStub<T>;
  jurisdiction(jurisdiction: DurableObjectJurisdiction): DurableObjectNamespace<T>;
}
type DurableObjectJurisdiction = 'eu' | 'fedramp';
interface DurableObjectNamespaceNewUniqueIdOptions {
  jurisdiction?: DurableObjectJurisdiction;
}
type DurableObjectLocationHint =
  | 'wnam'
  | 'enam'
  | 'sam'
  | 'weur'
  | 'eeur'
  | 'apac'
  | 'oc'
  | 'afr'
  | 'me';
interface DurableObjectNamespaceGetDurableObjectOptions {
  locationHint?: DurableObjectLocationHint;
}
interface DurableObjectState {
  waitUntil(promise: Promise<any>): void;
  readonly id: DurableObjectId;
  readonly storage: DurableObjectStorage;
  container?: Container;
  blockConcurrencyWhile<T>(callback: () => Promise<T>): Promise<T>;
  acceptWebSocket(ws: WebSocket, tags?: string[]): void;
  getWebSockets(tag?: string): WebSocket[];
  setWebSocketAutoResponse(maybeReqResp?: WebSocketRequestResponsePair): void;
  getWebSocketAutoResponse(): WebSocketRequestResponsePair | null;
  getWebSocketAutoResponseTimestamp(ws: WebSocket): Date | null;
  setHibernatableWebSocketEventTimeout(timeoutMs?: number): void;
  getHibernatableWebSocketEventTimeout(): number | null;
  getTags(ws: WebSocket): string[];
  abort(reason?: string): void;
}
interface DurableObjectTransaction {
  get<T = unknown>(key: string, options?: DurableObjectGetOptions): Promise<T | undefined>;
  get<T = unknown>(keys: string[], options?: DurableObjectGetOptions): Promise<Map<string, T>>;
  list<T = unknown>(options?: DurableObjectListOptions): Promise<Map<string, T>>;
  put<T>(key: string, value: T, options?: DurableObjectPutOptions): Promise<void>;
  put<T>(entries: Record<string, T>, options?: DurableObjectPutOptions): Promise<void>;
  delete(key: string, options?: DurableObjectPutOptions): Promise<boolean>;
  delete(keys: string[], options?: DurableObjectPutOptions): Promise<number>;
  rollback(): void;
  getAlarm(options?: DurableObjectGetAlarmOptions): Promise<number | null>;
  setAlarm(scheduledTime: number | Date, options?: DurableObjectSetAlarmOptions): Promise<void>;
  deleteAlarm(options?: DurableObjectSetAlarmOptions): Promise<void>;
}
interface DurableObjectStorage {
  get<T = unknown>(key: string, options?: DurableObjectGetOptions): Promise<T | undefined>;
  get<T = unknown>(keys: string[], options?: DurableObjectGetOptions): Promise<Map<string, T>>;
  list<T = unknown>(options?: DurableObjectListOptions): Promise<Map<string, T>>;
  put<T>(key: string, value: T, options?: DurableObjectPutOptions): Promise<void>;
  put<T>(entries: Record<string, T>, options?: DurableObjectPutOptions): Promise<void>;
  delete(key: string, options?: DurableObjectPutOptions): Promise<boolean>;
  delete(keys: string[], options?: DurableObjectPutOptions): Promise<number>;
  deleteAll(options?: DurableObjectPutOptions): Promise<void>;
  transaction<T>(closure: (txn: DurableObjectTransaction) => Promise<T>): Promise<T>;
  getAlarm(options?: DurableObjectGetAlarmOptions): Promise<number | null>;
  setAlarm(scheduledTime: number | Date, options?: DurableObjectSetAlarmOptions): Promise<void>;
  deleteAlarm(options?: DurableObjectSetAlarmOptions): Promise<void>;
  sync(): Promise<void>;
  sql: SqlStorage;
  transactionSync<T>(closure: () => T): T;
  getCurrentBookmark(): Promise<string>;
  getBookmarkForTime(timestamp: number | Date): Promise<string>;
  onNextSessionRestoreBookmark(bookmark: string): Promise<string>;
}
interface DurableObjectListOptions {
  start?: string;
  startAfter?: string;
  end?: string;
  prefix?: string;
  reverse?: boolean;
  limit?: number;
  allowConcurrency?: boolean;
  noCache?: boolean;
}
interface DurableObjectGetOptions {
  allowConcurrency?: boolean;
  noCache?: boolean;
}
interface DurableObjectGetAlarmOptions {
  allowConcurrency?: boolean;
}
interface DurableObjectPutOptions {
  allowConcurrency?: boolean;
  allowUnconfirmed?: boolean;
  noCache?: boolean;
}
interface DurableObjectSetAlarmOptions {
  allowConcurrency?: boolean;
  allowUnconfirmed?: boolean;
}
declare class WebSocketRequestResponsePair {
  constructor(request: string, response: string);
  get request(): string;
  get response(): string;
}
interface AnalyticsEngineDataset {
  writeDataPoint(event?: AnalyticsEngineDataPoint): void;
}
interface AnalyticsEngineDataPoint {
  indexes?: ((ArrayBuffer | string) | null)[];
  doubles?: number[];
  blobs?: ((ArrayBuffer | string) | null)[];
}
/**
 * An event which takes place in the DOM.
 *
 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event)
 */
declare class Event {
  constructor(type: string, init?: EventInit);
  /**
   * Returns the type of event, e.g. "click", "hashchange", or "submit".
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/type)
   */
  get type(): string;
  /**
   * Returns the event's phase, which is one of NONE, CAPTURING_PHASE, AT_TARGET, and BUBBLING_PHASE.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/eventPhase)
   */
  get eventPhase(): number;
  /**
   * Returns true or false depending on how event was initialized. True if event invokes listeners past a ShadowRoot node that is the root of its target, and false otherwise.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/composed)
   */
  get composed(): boolean;
  /**
   * Returns true or false depending on how event was initialized. True if event goes through its target's ancestors in reverse tree order, and false otherwise.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/bubbles)
   */
  get bubbles(): boolean;
  /**
   * Returns true or false depending on how event was initialized. Its return value does not always carry meaning, but true can indicate that part of the operation during which event was dispatched, can be canceled by invoking the preventDefault() method.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/cancelable)
   */
  get cancelable(): boolean;
  /**
   * Returns true if preventDefault() was invoked successfully to indicate cancelation, and false otherwise.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/defaultPrevented)
   */
  get defaultPrevented(): boolean;
  /**
   * @deprecated
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/returnValue)
   */
  get returnValue(): boolean;
  /**
   * Returns the object whose event listener's callback is currently being invoked.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/currentTarget)
   */
  get currentTarget(): EventTarget | undefined;
  /**
   * Returns the object to which event is dispatched (its target).
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/target)
   */
  get target(): EventTarget | undefined;
  /**
   * @deprecated
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/srcElement)
   */
  get srcElement(): EventTarget | undefined;
  /**
   * Returns the event's timestamp as the number of milliseconds measured relative to the time origin.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/timeStamp)
   */
  get timeStamp(): number;
  /**
   * Returns true if event was dispatched by the user agent, and false otherwise.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/isTrusted)
   */
  get isTrusted(): boolean;
  /**
   * @deprecated
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/cancelBubble)
   */
  get cancelBubble(): boolean;
  /**
   * @deprecated
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/cancelBubble)
   */
  set cancelBubble(value: boolean);
  /**
   * Invoking this method prevents event from reaching any registered event listeners after the current one finishes running and, when dispatched in a tree, also prevents event from reaching any other objects.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/stopImmediatePropagation)
   */
  stopImmediatePropagation(): void;
  /**
   * If invoked when the cancelable attribute value is true, and while executing a listener for the event with passive set to false, signals to the operation that caused event to be dispatched that it needs to be canceled.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/preventDefault)
   */
  preventDefault(): void;
  /**
   * When dispatched in a tree, invoking this method prevents event from reaching any objects other than the current object.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/stopPropagation)
   */
  stopPropagation(): void;
  /**
   * Returns the invocation target objects of event's path (objects on which listeners will be invoked), except for any nodes in shadow trees of which the shadow root's mode is "closed" that are not reachable from event's currentTarget.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/composedPath)
   */
  composedPath(): EventTarget[];
  static readonly NONE: number;
  static readonly CAPTURING_PHASE: number;
  static readonly AT_TARGET: number;
  static readonly BUBBLING_PHASE: number;
}
interface EventInit {
  bubbles?: boolean;
  cancelable?: boolean;
  composed?: boolean;
}
type EventListener<EventType extends Event = Event> = (event: EventType) => void;
interface EventListenerObject<EventType extends Event = Event> {
  handleEvent(event: EventType): void;
}
type EventListenerOrEventListenerObject<EventType extends Event = Event> =
  | EventListener<EventType>
  | EventListenerObject<EventType>;
/**
 * EventTarget is a DOM interface implemented by objects that can receive events and may have listeners for them.
 *
 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventTarget)
 */
declare class EventTarget<EventMap extends Record<string, Event> = Record<string, Event>> {
  constructor();
  /**
   * Appends an event listener for events whose type attribute value is type. The callback argument sets the callback that will be invoked when the event is dispatched.
   *
   * The options argument sets listener-specific options. For compatibility this can be a boolean, in which case the method behaves exactly as if the value was specified as options's capture.
   *
   * When set to true, options's capture prevents callback from being invoked when the event's eventPhase attribute value is BUBBLING_PHASE. When false (or not present), callback will not be invoked when event's eventPhase attribute value is CAPTURING_PHASE. Either way, callback will be invoked if event's eventPhase attribute value is AT_TARGET.
   *
   * When set to true, options's passive indicates that the callback will not cancel the event by invoking preventDefault(). This is used to enable performance optimizations described in § 2.8 Observing event listeners.
   *
   * When set to true, options's once indicates that the callback will only be invoked once after which the event listener will be removed.
   *
   * If an AbortSignal is passed for options's signal, then the event listener will be removed when signal is aborted.
   *
   * The event listener is appended to target's event listener list and is not appended if it has the same type, callback, and capture.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventTarget/addEventListener)
   */
  addEventListener<Type extends keyof EventMap>(
    type: Type,
    handler: EventListenerOrEventListenerObject<EventMap[Type]>,
    options?: EventTargetAddEventListenerOptions | boolean,
  ): void;
  /**
   * Removes the event listener in target's event listener list with the same type, callback, and options.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventTarget/removeEventListener)
   */
  removeEventListener<Type extends keyof EventMap>(
    type: Type,
    handler: EventListenerOrEventListenerObject<EventMap[Type]>,
    options?: EventTargetEventListenerOptions | boolean,
  ): void;
  /**
   * Dispatches a synthetic event event to target and returns true if either event's cancelable attribute value is false or its preventDefault() method was not invoked, and false otherwise.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventTarget/dispatchEvent)
   */
  dispatchEvent(event: EventMap[keyof EventMap]): boolean;
}
interface EventTargetEventListenerOptions {
  capture?: boolean;
}
interface EventTargetAddEventListenerOptions {
  capture?: boolean;
  passive?: boolean;
  once?: boolean;
  signal?: AbortSignal;
}
interface EventTargetHandlerObject {
  handleEvent: (event: Event) => any | undefined;
}
/**
 * A controller object that allows you to abort one or more DOM requests as and when desired.
 *
 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortController)
 */
declare class AbortController {
  constructor();
  /**
   * Returns the AbortSignal object associated with this object.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortController/signal)
   */
  get signal(): AbortSignal;
  /**
   * Invoking this method will set this object's AbortSignal's aborted flag and signal to any observers that the associated activity is to be aborted.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortController/abort)
   */
  abort(reason?: any): void;
}
/**
 * A signal object that allows you to communicate with a DOM request (such as a Fetch) and abort it if required via an AbortController object.
 *
 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal)
 */
declare abstract class AbortSignal extends EventTarget {
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal/abort_static) */
  static abort(reason?: any): AbortSignal;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal/timeout_static) */
  static timeout(delay: number): AbortSignal;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal/any_static) */
  static any(signals: AbortSignal[]): AbortSignal;
  /**
   * Returns true if this AbortSignal's AbortController has signaled to abort, and false otherwise.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal/aborted)
   */
  get aborted(): boolean;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal/reason) */
  get reason(): any;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal/abort_event) */
  get onabort(): any | null;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal/abort_event) */
  set onabort(value: any | null);
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal/throwIfAborted) */
  throwIfAborted(): void;
}
interface Scheduler {
  wait(delay: number, maybeOptions?: SchedulerWaitOptions): Promise<void>;
}
interface SchedulerWaitOptions {
  signal?: AbortSignal;
}
/**
 * Extends the lifetime of the install and activate events dispatched on the global scope as part of the service worker lifecycle. This ensures that any functional events (like FetchEvent) are not dispatched until it upgrades database schemas and deletes the outdated cache entries.
 *
 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ExtendableEvent)
 */
declare abstract class ExtendableEvent extends Event {
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/ExtendableEvent/waitUntil) */
  waitUntil(promise: Promise<any>): void;
}
/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomEvent) */
declare class CustomEvent<T = any> extends Event {
  constructor(type: string, init?: CustomEventCustomEventInit);
  /**
   * Returns any custom data event was created with. Typically used for synthetic events.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomEvent/detail)
   */
  get detail(): T;
}
interface CustomEventCustomEventInit {
  bubbles?: boolean;
  cancelable?: boolean;
  composed?: boolean;
  detail?: any;
}
/**
 * A file-like object of immutable, raw data. Blobs represent data that isn't necessarily in a JavaScript-native format. The File interface is based on Blob, inheriting blob functionality and expanding it to support files on the user's system.
 *
 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob)
 */
declare class Blob {
  constructor(type?: ((ArrayBuffer | ArrayBufferView) | string | Blob)[], options?: BlobOptions);
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/size) */
  get size(): number;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/type) */
  get type(): string;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/slice) */
  slice(start?: number, end?: number, type?: string): Blob;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/arrayBuffer) */
  arrayBuffer(): Promise<ArrayBuffer>;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/bytes) */
  bytes(): Promise<Uint8Array>;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/text) */
  text(): Promise<string>;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/stream) */
  stream(): ReadableStream;
}
interface BlobOptions {
  type?: string;
}
/**
 * Provides information about files and allows JavaScript in a web page to access their content.
 *
 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/File)
 */
declare class File extends Blob {
  constructor(
    bits: ((ArrayBuffer | ArrayBufferView) | string | Blob)[] | undefined,
    name: string,
    options?: FileOptions,
  );
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/File/name) */
  get name(): string;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/File/lastModified) */
  get lastModified(): number;
}
interface FileOptions {
  type?: string;
  lastModified?: number;
}
/**
 * The Cache API allows fine grained control of reading and writing from the Cloudflare global network cache.
 *
 * [Cloudflare Docs Reference](https://developers.cloudflare.com/workers/runtime-apis/cache/)
 */
declare abstract class CacheStorage {
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/CacheStorage/open) */
  open(cacheName: string): Promise<Cache>;
  readonly default: Cache;
}
/**
 * The Cache API allows fine grained control of reading and writing from the Cloudflare global network cache.
 *
 * [Cloudflare Docs Reference](https://developers.cloudflare.com/workers/runtime-apis/cache/)
 */
declare abstract class Cache {
  /* [Cloudflare Docs Reference](https://developers.cloudflare.com/workers/runtime-apis/cache/#delete) */
  delete(request: RequestInfo | URL, options?: CacheQueryOptions): Promise<boolean>;
  /* [Cloudflare Docs Reference](https://developers.cloudflare.com/workers/runtime-apis/cache/#match) */
  match(request: RequestInfo | URL, options?: CacheQueryOptions): Promise<Response | undefined>;
  /* [Cloudflare Docs Reference](https://developers.cloudflare.com/workers/runtime-apis/cache/#put) */
  put(request: RequestInfo | URL, response: Response): Promise<void>;
}
interface CacheQueryOptions {
  ignoreMethod?: boolean;
}
/**
 * The Web Crypto API provides a set of low-level functions for common cryptographic tasks.
 * The Workers runtime implements the full surface of this API, but with some differences in
 * the [supported algorithms](https://developers.cloudflare.com/workers/runtime-apis/web-crypto/#supported-algorithms)
 * compared to those implemented in most browsers.
 *
 * [Cloudflare Docs Reference](https://developers.cloudflare.com/workers/runtime-apis/web-crypto/)
 */
declare abstract class Crypto {
  /**
   * Available only in secure contexts.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Crypto/subtle)
   */
  get subtle(): SubtleCrypto;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Crypto/getRandomValues) */
  getRandomValues<
    T extends
      | Int8Array
      | Uint8Array
      | Int16Array
      | Uint16Array
      | Int32Array
      | Uint32Array
      | BigInt64Array
      | BigUint64Array,
  >(buffer: T): T;
  /**
   * Available only in secure contexts.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Crypto/randomUUID)
   */
  randomUUID(): string;
  DigestStream: typeof DigestStream;
}
/**
 * This Web Crypto API interface provides a number of low-level cryptographic functions. It is accessed via the Crypto.subtle properties available in a window context (via Window.crypto).
 * Available only in secure contexts.
 *
 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/SubtleCrypto)
 */
declare abstract class SubtleCrypto {
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/SubtleCrypto/encrypt) */
  encrypt(
    algorithm: string | SubtleCryptoEncryptAlgorithm,
    key: CryptoKey,
    plainText: ArrayBuffer | ArrayBufferView,
  ): Promise<ArrayBuffer>;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/SubtleCrypto/decrypt) */
  decrypt(
    algorithm: string | SubtleCryptoEncryptAlgorithm,
    key: CryptoKey,
    cipherText: ArrayBuffer | ArrayBufferView,
  ): Promise<ArrayBuffer>;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/SubtleCrypto/sign) */
  sign(
    algorithm: string | SubtleCryptoSignAlgorithm,
    key: CryptoKey,
    data: ArrayBuffer | ArrayBufferView,
  ): Promise<ArrayBuffer>;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/SubtleCrypto/verify) */
  verify(
    algorithm: string | SubtleCryptoSignAlgorithm,
    key: CryptoKey,
    signature: ArrayBuffer | ArrayBufferView,
    data: ArrayBuffer | ArrayBufferView,
  ): Promise<boolean>;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/SubtleCrypto/digest) */
  digest(
    algorithm: string | SubtleCryptoHashAlgorithm,
    data: ArrayBuffer | ArrayBufferView,
  ): Promise<ArrayBuffer>;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/SubtleCrypto/generateKey) */
  generateKey(
    algorithm: string | SubtleCryptoGenerateKeyAlgorithm,
    extractable: boolean,
    keyUsages: string[],
  ): Promise<CryptoKey | CryptoKeyPair>;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/SubtleCrypto/deriveKey) */
  deriveKey(
    algorithm: string | SubtleCryptoDeriveKeyAlgorithm,
    baseKey: CryptoKey,
    derivedKeyAlgorithm: string | SubtleCryptoImportKeyAlgorithm,
    extractable: boolean,
    keyUsages: string[],
  ): Promise<CryptoKey>;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/SubtleCrypto/deriveBits) */
  deriveBits(
    algorithm: string | SubtleCryptoDeriveKeyAlgorithm,
    baseKey: CryptoKey,
    length?: number | null,
  ): Promise<ArrayBuffer>;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/SubtleCrypto/importKey) */
  importKey(
    format: string,
    keyData: (ArrayBuffer | ArrayBufferView) | JsonWebKey,
    algorithm: string | SubtleCryptoImportKeyAlgorithm,
    extractable: boolean,
    keyUsages: string[],
  ): Promise<CryptoKey>;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/SubtleCrypto/exportKey) */
  exportKey(format: string, key: CryptoKey): Promise<ArrayBuffer | JsonWebKey>;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/SubtleCrypto/wrapKey) */
  wrapKey(
    format: string,
    key: CryptoKey,
    wrappingKey: CryptoKey,
    wrapAlgorithm: string | SubtleCryptoEncryptAlgorithm,
  ): Promise<ArrayBuffer>;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/SubtleCrypto/unwrapKey) */
  unwrapKey(
    format: string,
    wrappedKey: ArrayBuffer | ArrayBufferView,
    unwrappingKey: CryptoKey,
    unwrapAlgorithm: string | SubtleCryptoEncryptAlgorithm,
    unwrappedKeyAlgorithm: string | SubtleCryptoImportKeyAlgorithm,
    extractable: boolean,
    keyUsages: string[],
  ): Promise<CryptoKey>;
  timingSafeEqual(a: ArrayBuffer | ArrayBufferView, b: ArrayBuffer | ArrayBufferView): boolean;
}
/**
 * The CryptoKey dictionary of the Web Crypto API represents a cryptographic key.
 * Available only in secure contexts.
 *
 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CryptoKey)
 */
declare abstract class CryptoKey {
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/CryptoKey/type) */
  readonly type: string;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/CryptoKey/extractable) */
  readonly extractable: boolean;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/CryptoKey/algorithm) */
  readonly algorithm:
    | CryptoKeyKeyAlgorithm
    | CryptoKeyAesKeyAlgorithm
    | CryptoKeyHmacKeyAlgorithm
    | CryptoKeyRsaKeyAlgorithm
    | CryptoKeyEllipticKeyAlgorithm
    | CryptoKeyArbitraryKeyAlgorithm;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/CryptoKey/usages) */
  readonly usages: string[];
}
interface CryptoKeyPair {
  publicKey: CryptoKey;
  privateKey: CryptoKey;
}
interface JsonWebKey {
  kty: string;
  use?: string;
  key_ops?: string[];
  alg?: string;
  ext?: boolean;
  crv?: string;
  x?: string;
  y?: string;
  d?: string;
  n?: string;
  e?: string;
  p?: string;
  q?: string;
  dp?: string;
  dq?: string;
  qi?: string;
  oth?: RsaOtherPrimesInfo[];
  k?: string;
}
interface RsaOtherPrimesInfo {
  r?: string;
  d?: string;
  t?: string;
}
interface SubtleCryptoDeriveKeyAlgorithm {
  name: string;
  salt?: ArrayBuffer | ArrayBufferView;
  iterations?: number;
  hash?: string | SubtleCryptoHashAlgorithm;
  $public?: CryptoKey;
  info?: ArrayBuffer | ArrayBufferView;
}
interface SubtleCryptoEncryptAlgorithm {
  name: string;
  iv?: ArrayBuffer | ArrayBufferView;
  additionalData?: ArrayBuffer | ArrayBufferView;
  tagLength?: number;
  counter?: ArrayBuffer | ArrayBufferView;
  length?: number;
  label?: ArrayBuffer | ArrayBufferView;
}
interface SubtleCryptoGenerateKeyAlgorithm {
  name: string;
  hash?: string | SubtleCryptoHashAlgorithm;
  modulusLength?: number;
  publicExponent?: ArrayBuffer | ArrayBufferView;
  length?: number;
  namedCurve?: string;
}
interface SubtleCryptoHashAlgorithm {
  name: string;
}
interface SubtleCryptoImportKeyAlgorithm {
  name: string;
  hash?: string | SubtleCryptoHashAlgorithm;
  length?: number;
  namedCurve?: string;
  compressed?: boolean;
}
interface SubtleCryptoSignAlgorithm {
  name: string;
  hash?: string | SubtleCryptoHashAlgorithm;
  dataLength?: number;
  saltLength?: number;
}
interface CryptoKeyKeyAlgorithm {
  name: string;
}
interface CryptoKeyAesKeyAlgorithm {
  name: string;
  length: number;
}
interface CryptoKeyHmacKeyAlgorithm {
  name: string;
  hash: CryptoKeyKeyAlgorithm;
  length: number;
}
interface CryptoKeyRsaKeyAlgorithm {
  name: string;
  modulusLength: number;
  publicExponent: ArrayBuffer | ArrayBufferView;
  hash?: CryptoKeyKeyAlgorithm;
}
interface CryptoKeyEllipticKeyAlgorithm {
  name: string;
  namedCurve: string;
}
interface CryptoKeyArbitraryKeyAlgorithm {
  name: string;
  hash?: CryptoKeyKeyAlgorithm;
  namedCurve?: string;
  length?: number;
}
declare class DigestStream extends WritableStream<ArrayBuffer | ArrayBufferView> {
  constructor(algorithm: string | SubtleCryptoHashAlgorithm);
  readonly digest: Promise<ArrayBuffer>;
  get bytesWritten(): number | bigint;
}
/**
 * A decoder for a specific method, that is a specific character encoding, like utf-8, iso-8859-2, koi8, cp1261, gbk, etc. A decoder takes a stream of bytes as input and emits a stream of code points. For a more scalable, non-native library, see StringView – a C-like representation of strings based on typed arrays.
 *
 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/TextDecoder)
 */
declare class TextDecoder {
  constructor(label?: string, options?: TextDecoderConstructorOptions);
  /**
   * Returns the result of running encoding's decoder. The method can be invoked zero or more times with options's stream set to true, and then once without options's stream (or set to false), to process a fragmented input. If the invocation without options's stream (or set to false) has no input, it's clearest to omit both arguments.
   *
   * ```
   * var string = "", decoder = new TextDecoder(encoding), buffer;
   * while(buffer = next_chunk()) {
   *   string += decoder.decode(buffer, {stream:true});
   * }
   * string += decoder.decode(); // end-of-queue
   * ```
   *
   * If the error mode is "fatal" and encoding's decoder returns error, throws a TypeError.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/TextDecoder/decode)
   */
  decode(input?: ArrayBuffer | ArrayBufferView, options?: TextDecoderDecodeOptions): string;
  get encoding(): string;
  get fatal(): boolean;
  get ignoreBOM(): boolean;
}
/**
 * TextEncoder takes a stream of code points as input and emits a stream of bytes. For a more scalable, non-native library, see StringView – a C-like representation of strings based on typed arrays.
 *
 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/TextEncoder)
 */
declare class TextEncoder {
  constructor();
  /**
   * Returns the result of running UTF-8's encoder.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/TextEncoder/encode)
   */
  encode(input?: string): Uint8Array;
  /**
   * Runs the UTF-8 encoder on source, stores the result of that operation into destination, and returns the progress made as an object wherein read is the number of converted code units of source and written is the number of bytes modified in destination.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/TextEncoder/encodeInto)
   */
  encodeInto(input: string, buffer: ArrayBuffer | ArrayBufferView): TextEncoderEncodeIntoResult;
  get encoding(): string;
}
interface TextDecoderConstructorOptions {
  fatal: boolean;
  ignoreBOM: boolean;
}
interface TextDecoderDecodeOptions {
  stream: boolean;
}
interface TextEncoderEncodeIntoResult {
  read: number;
  written: number;
}
/**
 * Events providing information related to errors in scripts or in files.
 *
 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ErrorEvent)
 */
declare class ErrorEvent extends Event {
  constructor(type: string, init?: ErrorEventErrorEventInit);
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/ErrorEvent/filename) */
  get filename(): string;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/ErrorEvent/message) */
  get message(): string;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/ErrorEvent/lineno) */
  get lineno(): number;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/ErrorEvent/colno) */
  get colno(): number;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/ErrorEvent/error) */
  get error(): any;
}
interface ErrorEventErrorEventInit {
  message?: string;
  filename?: string;
  lineno?: number;
  colno?: number;
  error?: any;
}
/**
 * Provides a way to easily construct a set of key/value pairs representing form fields and their values, which can then be easily sent using the XMLHttpRequest.send() method. It uses the same format a form would use if the encoding type were set to "multipart/form-data".
 *
 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FormData)
 */
declare class FormData {
  constructor();
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/FormData/append) */
  append(name: string, value: string): void;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/FormData/append) */
  append(name: string, value: Blob, filename?: string): void;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/FormData/delete) */
  delete(name: string): void;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/FormData/get) */
  get(name: string): (File | string) | null;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/FormData/getAll) */
  getAll(name: string): (File | string)[];
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/FormData/has) */
  has(name: string): boolean;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/FormData/set) */
  set(name: string, value: string): void;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/FormData/set) */
  set(name: string, value: Blob, filename?: string): void;
  /* Returns an array of key, value pairs for every entry in the list. */
  entries(): IterableIterator<[key: string, value: File | string]>;
  /* Returns a list of keys in the list. */
  keys(): IterableIterator<string>;
  /* Returns a list of values in the list. */
  values(): IterableIterator<File | string>;
  forEach<This = unknown>(
    callback: (this: This, value: File | string, key: string, parent: FormData) => void,
    thisArg?: This,
  ): void;
  [Symbol.iterator](): IterableIterator<[key: string, value: File | string]>;
}
interface ContentOptions {
  html?: boolean;
}
declare class HTMLRewriter {
  constructor();
  on(selector: string, handlers: HTMLRewriterElementContentHandlers): HTMLRewriter;
  onDocument(handlers: HTMLRewriterDocumentContentHandlers): HTMLRewriter;
  transform(response: Response): Response;
}
interface HTMLRewriterElementContentHandlers {
  element?(element: Element): void | Promise<void>;
  comments?(comment: Comment): void | Promise<void>;
  text?(element: Text): void | Promise<void>;
}
interface HTMLRewriterDocumentContentHandlers {
  doctype?(doctype: Doctype): void | Promise<void>;
  comments?(comment: Comment): void | Promise<void>;
  text?(text: Text): void | Promise<void>;
  end?(end: DocumentEnd): void | Promise<void>;
}
interface Doctype {
  readonly name: string | null;
  readonly publicId: string | null;
  readonly systemId: string | null;
}
interface Element {
  tagName: string;
  readonly attributes: IterableIterator<string[]>;
  readonly removed: boolean;
  readonly namespaceURI: string;
  getAttribute(name: string): string | null;
  hasAttribute(name: string): boolean;
  setAttribute(name: string, value: string): Element;
  removeAttribute(name: string): Element;
  before(content: string | ReadableStream | Response, options?: ContentOptions): Element;
  after(content: string | ReadableStream | Response, options?: ContentOptions): Element;
  prepend(content: string | ReadableStream | Response, options?: ContentOptions): Element;
  append(content: string | ReadableStream | Response, options?: ContentOptions): Element;
  replace(content: string | ReadableStream | Response, options?: ContentOptions): Element;
  remove(): Element;
  removeAndKeepContent(): Element;
  setInnerContent(content: string | ReadableStream | Response, options?: ContentOptions): Element;
  onEndTag(handler: (tag: EndTag) => void | Promise<void>): void;
}
interface EndTag {
  name: string;
  before(content: string | ReadableStream | Response, options?: ContentOptions): EndTag;
  after(content: string | ReadableStream | Response, options?: ContentOptions): EndTag;
  remove(): EndTag;
}
interface Comment {
  text: string;
  readonly removed: boolean;
  before(content: string, options?: ContentOptions): Comment;
  after(content: string, options?: ContentOptions): Comment;
  replace(content: string, options?: ContentOptions): Comment;
  remove(): Comment;
}
interface Text {
  readonly text: string;
  readonly lastInTextNode: boolean;
  readonly removed: boolean;
  before(content: string | ReadableStream | Response, options?: ContentOptions): Text;
  after(content: string | ReadableStream | Response, options?: ContentOptions): Text;
  replace(content: string | ReadableStream | Response, options?: ContentOptions): Text;
  remove(): Text;
}
interface DocumentEnd {
  append(content: string, options?: ContentOptions): DocumentEnd;
}
/**
 * This is the event type for fetch events dispatched on the service worker global scope. It contains information about the fetch, including the request and how the receiver will treat the response. It provides the event.respondWith() method, which allows us to provide a response to this fetch.
 *
 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FetchEvent)
 */
declare abstract class FetchEvent extends ExtendableEvent {
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/FetchEvent/request) */
  readonly request: Request;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/FetchEvent/respondWith) */
  respondWith(promise: Response | Promise<Response>): void;
  passThroughOnException(): void;
}
type HeadersInit = Headers | Iterable<Iterable<string>> | Record<string, string>;
/**
 * This Fetch API interface allows you to perform various actions on HTTP request and response headers. These actions include retrieving, setting, adding to, and removing. A Headers object has an associated header list, which is initially empty and consists of zero or more name and value pairs.  You can add to this using methods like append() (see Examples.) In all methods of this interface, header names are matched by case-insensitive byte sequence.
 *
 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Headers)
 */
declare class Headers {
  constructor(init?: HeadersInit);
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Headers/get) */
  get(name: string): string | null;
  getAll(name: string): string[];
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Headers/getSetCookie) */
  getSetCookie(): string[];
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Headers/has) */
  has(name: string): boolean;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Headers/set) */
  set(name: string, value: string): void;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Headers/append) */
  append(name: string, value: string): void;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Headers/delete) */
  delete(name: string): void;
  forEach<This = unknown>(
    callback: (this: This, value: string, key: string, parent: Headers) => void,
    thisArg?: This,
  ): void;
  /* Returns an iterator allowing to go through all key/value pairs contained in this object. */
  entries(): IterableIterator<[key: string, value: string]>;
  /* Returns an iterator allowing to go through all keys of the key/value pairs contained in this object. */
  keys(): IterableIterator<string>;
  /* Returns an iterator allowing to go through all values of the key/value pairs contained in this object. */
  values(): IterableIterator<string>;
  [Symbol.iterator](): IterableIterator<[key: string, value: string]>;
}
type BodyInit =
  | ReadableStream<Uint8Array>
  | string
  | ArrayBuffer
  | ArrayBufferView
  | Blob
  | URLSearchParams
  | FormData;
declare abstract class Body {
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/body) */
  get body(): ReadableStream | null;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/bodyUsed) */
  get bodyUsed(): boolean;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/arrayBuffer) */
  arrayBuffer(): Promise<ArrayBuffer>;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/bytes) */
  bytes(): Promise<Uint8Array>;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/text) */
  text(): Promise<string>;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/json) */
  json<T>(): Promise<T>;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/formData) */
  formData(): Promise<FormData>;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/blob) */
  blob(): Promise<Blob>;
}
/**
 * This Fetch API interface represents the response to a request.
 *
 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response)
 */
declare var Response: {
  prototype: Response;
  new (body?: BodyInit | null, init?: ResponseInit): Response;
  error(): Response;
  redirect(url: string, status?: number): Response;
  json(any: any, maybeInit?: ResponseInit | Response): Response;
};
/**
 * This Fetch API interface represents the response to a request.
 *
 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response)
 */
interface Response extends Body {
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response/clone) */
  clone(): Response;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response/status) */
  status: number;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response/statusText) */
  statusText: string;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response/headers) */
  headers: Headers;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response/ok) */
  ok: boolean;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response/redirected) */
  redirected: boolean;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response/url) */
  url: string;
  webSocket: WebSocket | null;
  cf: any | undefined;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Response/type) */
  type: 'default' | 'error';
}
interface ResponseInit {
  status?: number;
  statusText?: string;
  headers?: HeadersInit;
  cf?: any;
  webSocket?: WebSocket | null;
  encodeBody?: 'automatic' | 'manual';
}
type RequestInfo<CfHostMetadata = unknown, Cf = CfProperties<CfHostMetadata>> =
  | Request<CfHostMetadata, Cf>
  | string;
/**
 * This Fetch API interface represents a resource request.
 *
 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request)
 */
declare var Request: {
  prototype: Request;
  new <CfHostMetadata = unknown, Cf = CfProperties<CfHostMetadata>>(
    input: RequestInfo<CfProperties> | URL,
    init?: RequestInit<Cf>,
  ): Request<CfHostMetadata, Cf>;
};
/**
 * This Fetch API interface represents a resource request.
 *
 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request)
 */
interface Request<CfHostMetadata = unknown, Cf = CfProperties<CfHostMetadata>> extends Body {
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/clone) */
  clone(): Request<CfHostMetadata, Cf>;
  /**
   * Returns request's HTTP method, which is "GET" by default.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/method)
   */
  method: string;
  /**
   * Returns the URL of request as a string.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/url)
   */
  url: string;
  /**
   * Returns a Headers object consisting of the headers associated with request. Note that headers added in the network layer by the user agent will not be accounted for in this object, e.g., the "Host" header.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/headers)
   */
  headers: Headers;
  /**
   * Returns the redirect mode associated with request, which is a string indicating how redirects for the request will be handled during fetching. A request will follow redirects by default.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/redirect)
   */
  redirect: string;
  fetcher: Fetcher | null;
  /**
   * Returns the signal associated with request, which is an AbortSignal object indicating whether or not request has been aborted, and its abort event handler.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/signal)
   */
  signal: AbortSignal;
  cf: Cf | undefined;
  /**
   * Returns request's subresource integrity metadata, which is a cryptographic hash of the resource being fetched. Its value consists of multiple hashes separated by whitespace. [SRI]
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/integrity)
   */
  integrity: string;
  /**
   * Returns a boolean indicating whether or not request can outlive the global in which it was created.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/keepalive)
   */
  keepalive: boolean;
  /**
   * Returns the cache mode associated with request, which is a string indicating how the request will interact with the browser's cache when fetching.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/cache)
   */
  cache?: 'no-store';
}
interface RequestInit<Cf = CfProperties> {
  /* A string to set request's method. */
  method?: string;
  /* A Headers object, an object literal, or an array of two-item arrays to set request's headers. */
  headers?: HeadersInit;
  /* A BodyInit object or null to set request's body. */
  body?: BodyInit | null;
  /* A string indicating whether request follows redirects, results in an error upon encountering a redirect, or returns the redirect (in an opaque fashion). Sets request's redirect. */
  redirect?: string;
  fetcher?: Fetcher | null;
  cf?: Cf;
  /* A string indicating how the request will interact with the browser's cache to set request's cache. */
  cache?: 'no-store';
  /* A cryptographic hash of the resource to be fetched by request. Sets request's integrity. */
  integrity?: string;
  /* An AbortSignal to set request's signal. */
  signal?: AbortSignal | null;
  encodeResponseBody?: 'automatic' | 'manual';
}
type Service<T extends Rpc.WorkerEntrypointBranded | undefined = undefined> = Fetcher<T>;
type Fetcher<
  T extends Rpc.EntrypointBranded | undefined = undefined,
  Reserved extends string = never,
> = (T extends Rpc.EntrypointBranded
  ? Rpc.Provider<T, Reserved | 'fetch' | 'connect'>
  : unknown) & {
  fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
  connect(address: SocketAddress | string, options?: SocketOptions): Socket;
};
interface KVNamespaceListKey<Metadata, Key extends string = string> {
  name: Key;
  expiration?: number;
  metadata?: Metadata;
}
type KVNamespaceListResult<Metadata, Key extends string = string> =
  | {
      list_complete: false;
      keys: KVNamespaceListKey<Metadata, Key>[];
      cursor: string;
      cacheStatus: string | null;
    }
  | {
      list_complete: true;
      keys: KVNamespaceListKey<Metadata, Key>[];
      cacheStatus: string | null;
    };
interface KVNamespace<Key extends string = string> {
  get(key: Key, options?: Partial<KVNamespaceGetOptions<undefined>>): Promise<string | null>;
  get(key: Key, type: 'text'): Promise<string | null>;
  get<ExpectedValue = unknown>(key: Key, type: 'json'): Promise<ExpectedValue | null>;
  get(key: Key, type: 'arrayBuffer'): Promise<ArrayBuffer | null>;
  get(key: Key, type: 'stream'): Promise<ReadableStream | null>;
  get(key: Key, options?: KVNamespaceGetOptions<'text'>): Promise<string | null>;
  get<ExpectedValue = unknown>(
    key: Key,
    options?: KVNamespaceGetOptions<'json'>,
  ): Promise<ExpectedValue | null>;
  get(key: Key, options?: KVNamespaceGetOptions<'arrayBuffer'>): Promise<ArrayBuffer | null>;
  get(key: Key, options?: KVNamespaceGetOptions<'stream'>): Promise<ReadableStream | null>;
  get(key: Array<Key>, type: 'text'): Promise<Map<string, string | null>>;
  get<ExpectedValue = unknown>(
    key: Array<Key>,
    type: 'json',
  ): Promise<Map<string, ExpectedValue | null>>;
  get(
    key: Array<Key>,
    options?: Partial<KVNamespaceGetOptions<undefined>>,
  ): Promise<Map<string, string | null>>;
  get(
    key: Array<Key>,
    options?: KVNamespaceGetOptions<'text'>,
  ): Promise<Map<string, string | null>>;
  get<ExpectedValue = unknown>(
    key: Array<Key>,
    options?: KVNamespaceGetOptions<'json'>,
  ): Promise<Map<string, ExpectedValue | null>>;
  list<Metadata = unknown>(
    options?: KVNamespaceListOptions,
  ): Promise<KVNamespaceListResult<Metadata, Key>>;
  put(
    key: Key,
    value: string | ArrayBuffer | ArrayBufferView | ReadableStream,
    options?: KVNamespacePutOptions,
  ): Promise<void>;
  getWithMetadata<Metadata = unknown>(
    key: Key,
    options?: Partial<KVNamespaceGetOptions<undefined>>,
  ): Promise<KVNamespaceGetWithMetadataResult<string, Metadata>>;
  getWithMetadata<Metadata = unknown>(
    key: Key,
    type: 'text',
  ): Promise<KVNamespaceGetWithMetadataResult<string, Metadata>>;
  getWithMetadata<ExpectedValue = unknown, Metadata = unknown>(
    key: Key,
    type: 'json',
  ): Promise<KVNamespaceGetWithMetadataResult<ExpectedValue, Metadata>>;
  getWithMetadata<Metadata = unknown>(
    key: Key,
    type: 'arrayBuffer',
  ): Promise<KVNamespaceGetWithMetadataResult<ArrayBuffer, Metadata>>;
  getWithMetadata<Metadata = unknown>(
    key: Key,
    type: 'stream',
  ): Promise<KVNamespaceGetWithMetadataResult<ReadableStream, Metadata>>;
  getWithMetadata<Metadata = unknown>(
    key: Key,
    options: KVNamespaceGetOptions<'text'>,
  ): Promise<KVNamespaceGetWithMetadataResult<string, Metadata>>;
  getWithMetadata<ExpectedValue = unknown, Metadata = unknown>(
    key: Key,
    options: KVNamespaceGetOptions<'json'>,
  ): Promise<KVNamespaceGetWithMetadataResult<ExpectedValue, Metadata>>;
  getWithMetadata<Metadata = unknown>(
    key: Key,
    options: KVNamespaceGetOptions<'arrayBuffer'>,
  ): Promise<KVNamespaceGetWithMetadataResult<ArrayBuffer, Metadata>>;
  getWithMetadata<Metadata = unknown>(
    key: Key,
    options: KVNamespaceGetOptions<'stream'>,
  ): Promise<KVNamespaceGetWithMetadataResult<ReadableStream, Metadata>>;
  getWithMetadata<Metadata = unknown>(
    key: Array<Key>,
    type: 'text',
  ): Promise<Map<string, KVNamespaceGetWithMetadataResult<string, Metadata>>>;
  getWithMetadata<ExpectedValue = unknown, Metadata = unknown>(
    key: Array<Key>,
    type: 'json',
  ): Promise<Map<string, KVNamespaceGetWithMetadataResult<ExpectedValue, Metadata>>>;
  getWithMetadata<Metadata = unknown>(
    key: Array<Key>,
    options?: Partial<KVNamespaceGetOptions<undefined>>,
  ): Promise<Map<string, KVNamespaceGetWithMetadataResult<string, Metadata>>>;
  getWithMetadata<Metadata = unknown>(
    key: Array<Key>,
    options?: KVNamespaceGetOptions<'text'>,
  ): Promise<Map<string, KVNamespaceGetWithMetadataResult<string, Metadata>>>;
  getWithMetadata<ExpectedValue = unknown, Metadata = unknown>(
    key: Array<Key>,
    options?: KVNamespaceGetOptions<'json'>,
  ): Promise<Map<string, KVNamespaceGetWithMetadataResult<ExpectedValue, Metadata>>>;
  delete(key: Key): Promise<void>;
}
interface KVNamespaceListOptions {
  limit?: number;
  prefix?: string | null;
  cursor?: string | null;
}
interface KVNamespaceGetOptions<Type> {
  type: Type;
  cacheTtl?: number;
}
interface KVNamespacePutOptions {
  expiration?: number;
  expirationTtl?: number;
  metadata?: any | null;
}
interface KVNamespaceGetWithMetadataResult<Value, Metadata> {
  value: Value | null;
  metadata: Metadata | null;
  cacheStatus: string | null;
}
type QueueContentType = 'text' | 'bytes' | 'json' | 'v8';
interface Queue<Body = unknown> {
  send(message: Body, options?: QueueSendOptions): Promise<void>;
  sendBatch(
    messages: Iterable<MessageSendRequest<Body>>,
    options?: QueueSendBatchOptions,
  ): Promise<void>;
}
interface QueueSendOptions {
  contentType?: QueueContentType;
  delaySeconds?: number;
}
interface QueueSendBatchOptions {
  delaySeconds?: number;
}
interface MessageSendRequest<Body = unknown> {
  body: Body;
  contentType?: QueueContentType;
  delaySeconds?: number;
}
interface QueueRetryOptions {
  delaySeconds?: number;
}
interface Message<Body = unknown> {
  readonly id: string;
  readonly timestamp: Date;
  readonly body: Body;
  readonly attempts: number;
  retry(options?: QueueRetryOptions): void;
  ack(): void;
}
interface QueueEvent<Body = unknown> extends ExtendableEvent {
  readonly messages: readonly Message<Body>[];
  readonly queue: string;
  retryAll(options?: QueueRetryOptions): void;
  ackAll(): void;
}
interface MessageBatch<Body = unknown> {
  readonly messages: readonly Message<Body>[];
  readonly queue: string;
  retryAll(options?: QueueRetryOptions): void;
  ackAll(): void;
}
interface R2Error extends Error {
  readonly name: string;
  readonly code: number;
  readonly message: string;
  readonly action: string;
  readonly stack: any;
}
interface R2ListOptions {
  limit?: number;
  prefix?: string;
  cursor?: string;
  delimiter?: string;
  startAfter?: string;
  include?: ('httpMetadata' | 'customMetadata')[];
}
declare abstract class R2Bucket {
  head(key: string): Promise<R2Object | null>;
  get(
    key: string,
    options: R2GetOptions & {
      onlyIf: R2Conditional | Headers;
    },
  ): Promise<R2ObjectBody | R2Object | null>;
  get(key: string, options?: R2GetOptions): Promise<R2ObjectBody | null>;
  put(
    key: string,
    value: ReadableStream | ArrayBuffer | ArrayBufferView | string | null | Blob,
    options?: R2PutOptions & {
      onlyIf: R2Conditional | Headers;
    },
  ): Promise<R2Object | null>;
  put(
    key: string,
    value: ReadableStream | ArrayBuffer | ArrayBufferView | string | null | Blob,
    options?: R2PutOptions,
  ): Promise<R2Object>;
  createMultipartUpload(key: string, options?: R2MultipartOptions): Promise<R2MultipartUpload>;
  resumeMultipartUpload(key: string, uploadId: string): R2MultipartUpload;
  delete(keys: string | string[]): Promise<void>;
  list(options?: R2ListOptions): Promise<R2Objects>;
}
interface R2MultipartUpload {
  readonly key: string;
  readonly uploadId: string;
  uploadPart(
    partNumber: number,
    value: ReadableStream | (ArrayBuffer | ArrayBufferView) | string | Blob,
    options?: R2UploadPartOptions,
  ): Promise<R2UploadedPart>;
  abort(): Promise<void>;
  complete(uploadedParts: R2UploadedPart[]): Promise<R2Object>;
}
interface R2UploadedPart {
  partNumber: number;
  etag: string;
}
declare abstract class R2Object {
  readonly key: string;
  readonly version: string;
  readonly size: number;
  readonly etag: string;
  readonly httpEtag: string;
  readonly checksums: R2Checksums;
  readonly uploaded: Date;
  readonly httpMetadata?: R2HTTPMetadata;
  readonly customMetadata?: Record<string, string>;
  readonly range?: R2Range;
  readonly storageClass: string;
  readonly ssecKeyMd5?: string;
  writeHttpMetadata(headers: Headers): void;
}
interface R2ObjectBody extends R2Object {
  get body(): ReadableStream;
  get bodyUsed(): boolean;
  arrayBuffer(): Promise<ArrayBuffer>;
  text(): Promise<string>;
  json<T>(): Promise<T>;
  blob(): Promise<Blob>;
}
type R2Range =
  | {
      offset: number;
      length?: number;
    }
  | {
      offset?: number;
      length: number;
    }
  | {
      suffix: number;
    };
interface R2Conditional {
  etagMatches?: string;
  etagDoesNotMatch?: string;
  uploadedBefore?: Date;
  uploadedAfter?: Date;
  secondsGranularity?: boolean;
}
interface R2GetOptions {
  onlyIf?: R2Conditional | Headers;
  range?: R2Range | Headers;
  ssecKey?: ArrayBuffer | string;
}
interface R2PutOptions {
  onlyIf?: R2Conditional | Headers;
  httpMetadata?: R2HTTPMetadata | Headers;
  customMetadata?: Record<string, string>;
  md5?: (ArrayBuffer | ArrayBufferView) | string;
  sha1?: (ArrayBuffer | ArrayBufferView) | string;
  sha256?: (ArrayBuffer | ArrayBufferView) | string;
  sha384?: (ArrayBuffer | ArrayBufferView) | string;
  sha512?: (ArrayBuffer | ArrayBufferView) | string;
  storageClass?: string;
  ssecKey?: ArrayBuffer | string;
}
interface R2MultipartOptions {
  httpMetadata?: R2HTTPMetadata | Headers;
  customMetadata?: Record<string, string>;
  storageClass?: string;
  ssecKey?: ArrayBuffer | string;
}
interface R2Checksums {
  readonly md5?: ArrayBuffer;
  readonly sha1?: ArrayBuffer;
  readonly sha256?: ArrayBuffer;
  readonly sha384?: ArrayBuffer;
  readonly sha512?: ArrayBuffer;
  toJSON(): R2StringChecksums;
}
interface R2StringChecksums {
  md5?: string;
  sha1?: string;
  sha256?: string;
  sha384?: string;
  sha512?: string;
}
interface R2HTTPMetadata {
  contentType?: string;
  contentLanguage?: string;
  contentDisposition?: string;
  contentEncoding?: string;
  cacheControl?: string;
  cacheExpiry?: Date;
}
type R2Objects = {
  objects: R2Object[];
  delimitedPrefixes: string[];
} & (
  | {
      truncated: true;
      cursor: string;
    }
  | {
      truncated: false;
    }
);
interface R2UploadPartOptions {
  ssecKey?: ArrayBuffer | string;
}
declare abstract class ScheduledEvent extends ExtendableEvent {
  readonly scheduledTime: number;
  readonly cron: string;
  noRetry(): void;
}
interface ScheduledController {
  readonly scheduledTime: number;
  readonly cron: string;
  noRetry(): void;
}
interface QueuingStrategy<T = any> {
  highWaterMark?: number | bigint;
  size?: (chunk: T) => number | bigint;
}
interface UnderlyingSink<W = any> {
  type?: string;
  start?: (controller: WritableStreamDefaultController) => void | Promise<void>;
  write?: (chunk: W, controller: WritableStreamDefaultController) => void | Promise<void>;
  abort?: (reason: any) => void | Promise<void>;
  close?: () => void | Promise<void>;
}
interface UnderlyingByteSource {
  type: 'bytes';
  autoAllocateChunkSize?: number;
  start?: (controller: ReadableByteStreamController) => void | Promise<void>;
  pull?: (controller: ReadableByteStreamController) => void | Promise<void>;
  cancel?: (reason: any) => void | Promise<void>;
}
interface UnderlyingSource<R = any> {
  type?: '' | undefined;
  start?: (controller: ReadableStreamDefaultController<R>) => void | Promise<void>;
  pull?: (controller: ReadableStreamDefaultController<R>) => void | Promise<void>;
  cancel?: (reason: any) => void | Promise<void>;
  expectedLength?: number | bigint;
}
interface Transformer<I = any, O = any> {
  readableType?: string;
  writableType?: string;
  start?: (controller: TransformStreamDefaultController<O>) => void | Promise<void>;
  transform?: (chunk: I, controller: TransformStreamDefaultController<O>) => void | Promise<void>;
  flush?: (controller: TransformStreamDefaultController<O>) => void | Promise<void>;
  cancel?: (reason: any) => void | Promise<void>;
  expectedLength?: number;
}
interface StreamPipeOptions {
  /**
   * Pipes this readable stream to a given writable stream destination. The way in which the piping process behaves under various error conditions can be customized with a number of passed options. It returns a promise that fulfills when the piping process completes successfully, or rejects if any errors were encountered.
   *
   * Piping a stream will lock it for the duration of the pipe, preventing any other consumer from acquiring a reader.
   *
   * Errors and closures of the source and destination streams propagate as follows:
   *
   * An error in this source readable stream will abort destination, unless preventAbort is truthy. The returned promise will be rejected with the source's error, or with any error that occurs during aborting the destination.
   *
   * An error in destination will cancel this source readable stream, unless preventCancel is truthy. The returned promise will be rejected with the destination's error, or with any error that occurs during canceling the source.
   *
   * When this source readable stream closes, destination will be closed, unless preventClose is truthy. The returned promise will be fulfilled once this process completes, unless an error is encountered while closing the destination, in which case it will be rejected with that error.
   *
   * If destination starts out closed or closing, this source readable stream will be canceled, unless preventCancel is true. The returned promise will be rejected with an error indicating piping to a closed stream failed, or with any error that occurs during canceling the source.
   *
   * The signal option can be set to an AbortSignal to allow aborting an ongoing pipe operation via the corresponding AbortController. In this case, this source readable stream will be canceled, and destination aborted, unless the respective options preventCancel or preventAbort are set.
   */
  preventClose?: boolean;
  preventAbort?: boolean;
  preventCancel?: boolean;
  signal?: AbortSignal;
}
type ReadableStreamReadResult<R = any> =
  | {
      done: false;
      value: R;
    }
  | {
      done: true;
      value?: undefined;
    };
/**
 * This Streams API interface represents a readable stream of byte data. The Fetch API offers a concrete instance of a ReadableStream through the body property of a Response object.
 *
 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStream)
 */
interface ReadableStream<R = any> {
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStream/locked) */
  get locked(): boolean;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStream/cancel) */
  cancel(reason?: any): Promise<void>;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStream/getReader) */
  getReader(): ReadableStreamDefaultReader<R>;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStream/getReader) */
  getReader(options: ReadableStreamGetReaderOptions): ReadableStreamBYOBReader;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStream/pipeThrough) */
  pipeThrough<T>(
    transform: ReadableWritablePair<T, R>,
    options?: StreamPipeOptions,
  ): ReadableStream<T>;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStream/pipeTo) */
  pipeTo(destination: WritableStream<R>, options?: StreamPipeOptions): Promise<void>;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStream/tee) */
  tee(): [ReadableStream<R>, ReadableStream<R>];
  values(options?: ReadableStreamValuesOptions): AsyncIterableIterator<R>;
  [Symbol.asyncIterator](options?: ReadableStreamValuesOptions): AsyncIterableIterator<R>;
}
/**
 * This Streams API interface represents a readable stream of byte data. The Fetch API offers a concrete instance of a ReadableStream through the body property of a Response object.
 *
 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStream)
 */
declare const ReadableStream: {
  prototype: ReadableStream;
  new (
    underlyingSource: UnderlyingByteSource,
    strategy?: QueuingStrategy<Uint8Array>,
  ): ReadableStream<Uint8Array>;
  new <R = any>(
    underlyingSource?: UnderlyingSource<R>,
    strategy?: QueuingStrategy<R>,
  ): ReadableStream<R>;
};
/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamDefaultReader) */
declare class ReadableStreamDefaultReader<R = any> {
  constructor(stream: ReadableStream);
  get closed(): Promise<void>;
  cancel(reason?: any): Promise<void>;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamDefaultReader/read) */
  read(): Promise<ReadableStreamReadResult<R>>;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamDefaultReader/releaseLock) */
  releaseLock(): void;
}
/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamBYOBReader) */
declare class ReadableStreamBYOBReader {
  constructor(stream: ReadableStream);
  get closed(): Promise<void>;
  cancel(reason?: any): Promise<void>;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamBYOBReader/read) */
  read<T extends ArrayBufferView>(view: T): Promise<ReadableStreamReadResult<T>>;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamBYOBReader/releaseLock) */
  releaseLock(): void;
  readAtLeast<T extends ArrayBufferView>(
    minElements: number,
    view: T,
  ): Promise<ReadableStreamReadResult<T>>;
}
interface ReadableStreamBYOBReaderReadableStreamBYOBReaderReadOptions {
  min?: number;
}
interface ReadableStreamGetReaderOptions {
  /**
   * Creates a ReadableStreamBYOBReader and locks the stream to the new reader.
   *
   * This call behaves the same way as the no-argument variant, except that it only works on readable byte streams, i.e. streams which were constructed specifically with the ability to handle "bring your own buffer" reading. The returned BYOB reader provides the ability to directly read individual chunks from the stream via its read() method, into developer-supplied buffers, allowing more precise control over allocation.
   */
  mode: 'byob';
}
/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamBYOBRequest) */
declare abstract class ReadableStreamBYOBRequest {
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamBYOBRequest/view) */
  get view(): Uint8Array | null;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamBYOBRequest/respond) */
  respond(bytesWritten: number): void;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamBYOBRequest/respondWithNewView) */
  respondWithNewView(view: ArrayBuffer | ArrayBufferView): void;
  get atLeast(): number | null;
}
/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamDefaultController) */
declare abstract class ReadableStreamDefaultController<R = any> {
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamDefaultController/desiredSize) */
  get desiredSize(): number | null;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamDefaultController/close) */
  close(): void;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamDefaultController/enqueue) */
  enqueue(chunk?: R): void;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamDefaultController/error) */
  error(reason: any): void;
}
/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableByteStreamController) */
declare abstract class ReadableByteStreamController {
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableByteStreamController/byobRequest) */
  get byobRequest(): ReadableStreamBYOBRequest | null;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableByteStreamController/desiredSize) */
  get desiredSize(): number | null;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableByteStreamController/close) */
  close(): void;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableByteStreamController/enqueue) */
  enqueue(chunk: ArrayBuffer | ArrayBufferView): void;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableByteStreamController/error) */
  error(reason: any): void;
}
/**
 * This Streams API interface represents a controller allowing control of a WritableStream's state. When constructing a WritableStream, the underlying sink is given a corresponding WritableStreamDefaultController instance to manipulate.
 *
 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WritableStreamDefaultController)
 */
declare abstract class WritableStreamDefaultController {
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/WritableStreamDefaultController/signal) */
  get signal(): AbortSignal;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/WritableStreamDefaultController/error) */
  error(reason?: any): void;
}
/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/TransformStreamDefaultController) */
declare abstract class TransformStreamDefaultController<O = any> {
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/TransformStreamDefaultController/desiredSize) */
  get desiredSize(): number | null;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/TransformStreamDefaultController/enqueue) */
  enqueue(chunk?: O): void;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/TransformStreamDefaultController/error) */
  error(reason: any): void;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/TransformStreamDefaultController/terminate) */
  terminate(): void;
}
interface ReadableWritablePair<R = any, W = any> {
  /**
   * Provides a convenient, chainable way of piping this readable stream through a transform stream (or any other { writable, readable } pair). It simply pipes the stream into the writable side of the supplied pair, and returns the readable side for further use.
   *
   * Piping a stream will lock it for the duration of the pipe, preventing any other consumer from acquiring a reader.
   */
  writable: WritableStream<W>;
  readable: ReadableStream<R>;
}
/**
 * This Streams API interface provides a standard abstraction for writing streaming data to a destination, known as a sink. This object comes with built-in backpressure and queuing.
 *
 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WritableStream)
 */
declare class WritableStream<W = any> {
  constructor(underlyingSink?: UnderlyingSink, queuingStrategy?: QueuingStrategy);
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/WritableStream/locked) */
  get locked(): boolean;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/WritableStream/abort) */
  abort(reason?: any): Promise<void>;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/WritableStream/close) */
  close(): Promise<void>;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/WritableStream/getWriter) */
  getWriter(): WritableStreamDefaultWriter<W>;
}
/**
 * This Streams API interface is the object returned by WritableStream.getWriter() and once created locks the < writer to the WritableStream ensuring that no other streams can write to the underlying sink.
 *
 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WritableStreamDefaultWriter)
 */
declare class WritableStreamDefaultWriter<W = any> {
  constructor(stream: WritableStream);
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/WritableStreamDefaultWriter/closed) */
  get closed(): Promise<void>;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/WritableStreamDefaultWriter/ready) */
  get ready(): Promise<void>;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/WritableStreamDefaultWriter/desiredSize) */
  get desiredSize(): number | null;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/WritableStreamDefaultWriter/abort) */
  abort(reason?: any): Promise<void>;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/WritableStreamDefaultWriter/close) */
  close(): Promise<void>;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/WritableStreamDefaultWriter/write) */
  write(chunk?: W): Promise<void>;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/WritableStreamDefaultWriter/releaseLock) */
  releaseLock(): void;
}
/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/TransformStream) */
declare class TransformStream<I = any, O = any> {
  constructor(
    transformer?: Transformer<I, O>,
    writableStrategy?: QueuingStrategy<I>,
    readableStrategy?: QueuingStrategy<O>,
  );
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/TransformStream/readable) */
  get readable(): ReadableStream<O>;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/TransformStream/writable) */
  get writable(): WritableStream<I>;
}
declare class FixedLengthStream extends IdentityTransformStream {
  constructor(
    expectedLength: number | bigint,
    queuingStrategy?: IdentityTransformStreamQueuingStrategy,
  );
}
declare class IdentityTransformStream extends TransformStream<
  ArrayBuffer | ArrayBufferView,
  Uint8Array
> {
  constructor(queuingStrategy?: IdentityTransformStreamQueuingStrategy);
}
interface IdentityTransformStreamQueuingStrategy {
  highWaterMark?: number | bigint;
}
interface ReadableStreamValuesOptions {
  preventCancel?: boolean;
}
/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/CompressionStream) */
declare class CompressionStream extends TransformStream<ArrayBuffer | ArrayBufferView, Uint8Array> {
  constructor(format: 'gzip' | 'deflate' | 'deflate-raw');
}
/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/DecompressionStream) */
declare class DecompressionStream extends TransformStream<
  ArrayBuffer | ArrayBufferView,
  Uint8Array
> {
  constructor(format: 'gzip' | 'deflate' | 'deflate-raw');
}
/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/TextEncoderStream) */
declare class TextEncoderStream extends TransformStream<string, Uint8Array> {
  constructor();
  get encoding(): string;
}
/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/TextDecoderStream) */
declare class TextDecoderStream extends TransformStream<ArrayBuffer | ArrayBufferView, string> {
  constructor(label?: string, options?: TextDecoderStreamTextDecoderStreamInit);
  get encoding(): string;
  get fatal(): boolean;
  get ignoreBOM(): boolean;
}
interface TextDecoderStreamTextDecoderStreamInit {
  fatal?: boolean;
  ignoreBOM?: boolean;
}
/**
 * This Streams API interface provides a built-in byte length queuing strategy that can be used when constructing streams.
 *
 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ByteLengthQueuingStrategy)
 */
declare class ByteLengthQueuingStrategy implements QueuingStrategy<ArrayBufferView> {
  constructor(init: QueuingStrategyInit);
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/ByteLengthQueuingStrategy/highWaterMark) */
  get highWaterMark(): number;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/ByteLengthQueuingStrategy/size) */
  get size(): (chunk?: any) => number;
}
/**
 * This Streams API interface provides a built-in byte length queuing strategy that can be used when constructing streams.
 *
 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CountQueuingStrategy)
 */
declare class CountQueuingStrategy implements QueuingStrategy {
  constructor(init: QueuingStrategyInit);
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/CountQueuingStrategy/highWaterMark) */
  get highWaterMark(): number;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/CountQueuingStrategy/size) */
  get size(): (chunk?: any) => number;
}
interface QueuingStrategyInit {
  /**
   * Creates a new ByteLengthQueuingStrategy with the provided high water mark.
   *
   * Note that the provided high water mark will not be validated ahead of time. Instead, if it is negative, NaN, or not a number, the resulting ByteLengthQueuingStrategy will cause the corresponding stream constructor to throw.
   */
  highWaterMark: number;
}
interface ScriptVersion {
  id?: string;
  tag?: string;
  message?: string;
}
declare abstract class TailEvent extends ExtendableEvent {
  readonly events: TraceItem[];
  readonly traces: TraceItem[];
}
interface TraceItem {
  readonly event:
    | (
        | TraceItemFetchEventInfo
        | TraceItemJsRpcEventInfo
        | TraceItemScheduledEventInfo
        | TraceItemAlarmEventInfo
        | TraceItemQueueEventInfo
        | TraceItemEmailEventInfo
        | TraceItemTailEventInfo
        | TraceItemCustomEventInfo
        | TraceItemHibernatableWebSocketEventInfo
      )
    | null;
  readonly eventTimestamp: number | null;
  readonly logs: TraceLog[];
  readonly exceptions: TraceException[];
  readonly diagnosticsChannelEvents: TraceDiagnosticChannelEvent[];
  readonly scriptName: string | null;
  readonly entrypoint?: string;
  readonly scriptVersion?: ScriptVersion;
  readonly dispatchNamespace?: string;
  readonly scriptTags?: string[];
  readonly outcome: string;
  readonly executionModel: string;
  readonly truncated: boolean;
  readonly cpuTime: number;
  readonly wallTime: number;
}
interface TraceItemAlarmEventInfo {
  readonly scheduledTime: Date;
}
interface TraceItemCustomEventInfo {}
interface TraceItemScheduledEventInfo {
  readonly scheduledTime: number;
  readonly cron: string;
}
interface TraceItemQueueEventInfo {
  readonly queue: string;
  readonly batchSize: number;
}
interface TraceItemEmailEventInfo {
  readonly mailFrom: string;
  readonly rcptTo: string;
  readonly rawSize: number;
}
interface TraceItemTailEventInfo {
  readonly consumedEvents: TraceItemTailEventInfoTailItem[];
}
interface TraceItemTailEventInfoTailItem {
  readonly scriptName: string | null;
}
interface TraceItemFetchEventInfo {
  readonly response?: TraceItemFetchEventInfoResponse;
  readonly request: TraceItemFetchEventInfoRequest;
}
interface TraceItemFetchEventInfoRequest {
  readonly cf?: any;
  readonly headers: Record<string, string>;
  readonly method: string;
  readonly url: string;
  getUnredacted(): TraceItemFetchEventInfoRequest;
}
interface TraceItemFetchEventInfoResponse {
  readonly status: number;
}
interface TraceItemJsRpcEventInfo {
  readonly rpcMethod: string;
}
interface TraceItemHibernatableWebSocketEventInfo {
  readonly getWebSocketEvent:
    | TraceItemHibernatableWebSocketEventInfoMessage
    | TraceItemHibernatableWebSocketEventInfoClose
    | TraceItemHibernatableWebSocketEventInfoError;
}
interface TraceItemHibernatableWebSocketEventInfoMessage {
  readonly webSocketEventType: string;
}
interface TraceItemHibernatableWebSocketEventInfoClose {
  readonly webSocketEventType: string;
  readonly code: number;
  readonly wasClean: boolean;
}
interface TraceItemHibernatableWebSocketEventInfoError {
  readonly webSocketEventType: string;
}
interface TraceLog {
  readonly timestamp: number;
  readonly level: string;
  readonly message: any;
}
interface TraceException {
  readonly timestamp: number;
  readonly message: string;
  readonly name: string;
  readonly stack?: string;
}
interface TraceDiagnosticChannelEvent {
  readonly timestamp: number;
  readonly channel: string;
  readonly message: any;
}
interface TraceMetrics {
  readonly cpuTime: number;
  readonly wallTime: number;
}
interface UnsafeTraceMetrics {
  fromTrace(item: TraceItem): TraceMetrics;
}
/**
 * The URL interface represents an object providing static methods used for creating object URLs.
 *
 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL)
 */
declare class URL {
  constructor(url: string | URL, base?: string | URL);
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/origin) */
  get origin(): string;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/href) */
  get href(): string;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/href) */
  set href(value: string);
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/protocol) */
  get protocol(): string;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/protocol) */
  set protocol(value: string);
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/username) */
  get username(): string;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/username) */
  set username(value: string);
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/password) */
  get password(): string;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/password) */
  set password(value: string);
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/host) */
  get host(): string;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/host) */
  set host(value: string);
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/hostname) */
  get hostname(): string;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/hostname) */
  set hostname(value: string);
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/port) */
  get port(): string;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/port) */
  set port(value: string);
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/pathname) */
  get pathname(): string;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/pathname) */
  set pathname(value: string);
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/search) */
  get search(): string;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/search) */
  set search(value: string);
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/hash) */
  get hash(): string;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/hash) */
  set hash(value: string);
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/searchParams) */
  get searchParams(): URLSearchParams;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/toJSON) */
  toJSON(): string;
  /*function toString() { [native code] }*/
  toString(): string;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/canParse_static) */
  static canParse(url: string, base?: string): boolean;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/parse_static) */
  static parse(url: string, base?: string): URL | null;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/createObjectURL_static) */
  static createObjectURL(object: File | Blob): string;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/URL/revokeObjectURL_static) */
  static revokeObjectURL(object_url: string): void;
}
/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/URLSearchParams) */
declare class URLSearchParams {
  constructor(init?: Iterable<Iterable<string>> | Record<string, string> | string);
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/URLSearchParams/size) */
  get size(): number;
  /**
   * Appends a specified key/value pair as a new search parameter.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URLSearchParams/append)
   */
  append(name: string, value: string): void;
  /**
   * Deletes the given search parameter, and its associated value, from the list of all search parameters.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URLSearchParams/delete)
   */
  delete(name: string, value?: string): void;
  /**
   * Returns the first value associated to the given search parameter.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URLSearchParams/get)
   */
  get(name: string): string | null;
  /**
   * Returns all the values association with a given search parameter.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URLSearchParams/getAll)
   */
  getAll(name: string): string[];
  /**
   * Returns a Boolean indicating if such a search parameter exists.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URLSearchParams/has)
   */
  has(name: string, value?: string): boolean;
  /**
   * Sets the value associated to a given search parameter to the given value. If there were several values, delete the others.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/URLSearchParams/set)
   */
  set(name: string, value: string): void;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/URLSearchParams/sort) */
  sort(): void;
  /* Returns an array of key, value pairs for every entry in the search params. */
  entries(): IterableIterator<[key: string, value: string]>;
  /* Returns a list of keys in the search params. */
  keys(): IterableIterator<string>;
  /* Returns a list of values in the search params. */
  values(): IterableIterator<string>;
  forEach<This = unknown>(
    callback: (this: This, value: string, key: string, parent: URLSearchParams) => void,
    thisArg?: This,
  ): void;
  /*function toString() { [native code] } Returns a string containing a query string suitable for use in a URL. Does not include the question mark. */
  toString(): string;
  [Symbol.iterator](): IterableIterator<[key: string, value: string]>;
}
declare class URLPattern {
  constructor(
    input?: string | URLPatternInit,
    baseURL?: string | URLPatternOptions,
    patternOptions?: URLPatternOptions,
  );
  get protocol(): string;
  get username(): string;
  get password(): string;
  get hostname(): string;
  get port(): string;
  get pathname(): string;
  get search(): string;
  get hash(): string;
  test(input?: string | URLPatternInit, baseURL?: string): boolean;
  exec(input?: string | URLPatternInit, baseURL?: string): URLPatternResult | null;
}
interface URLPatternInit {
  protocol?: string;
  username?: string;
  password?: string;
  hostname?: string;
  port?: string;
  pathname?: string;
  search?: string;
  hash?: string;
  baseURL?: string;
}
interface URLPatternComponentResult {
  input: string;
  groups: Record<string, string>;
}
interface URLPatternResult {
  inputs: (string | URLPatternInit)[];
  protocol: URLPatternComponentResult;
  username: URLPatternComponentResult;
  password: URLPatternComponentResult;
  hostname: URLPatternComponentResult;
  port: URLPatternComponentResult;
  pathname: URLPatternComponentResult;
  search: URLPatternComponentResult;
  hash: URLPatternComponentResult;
}
interface URLPatternOptions {
  ignoreCase?: boolean;
}
/**
 * A CloseEvent is sent to clients using WebSockets when the connection is closed. This is delivered to the listener indicated by the WebSocket object's onclose attribute.
 *
 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CloseEvent)
 */
declare class CloseEvent extends Event {
  constructor(type: string, initializer?: CloseEventInit);
  /**
   * Returns the WebSocket connection close code provided by the server.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CloseEvent/code)
   */
  readonly code: number;
  /**
   * Returns the WebSocket connection close reason provided by the server.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CloseEvent/reason)
   */
  readonly reason: string;
  /**
   * Returns true if the connection closed cleanly; false otherwise.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CloseEvent/wasClean)
   */
  readonly wasClean: boolean;
}
interface CloseEventInit {
  code?: number;
  reason?: string;
  wasClean?: boolean;
}
/**
 * A message received by a target object.
 *
 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/MessageEvent)
 */
declare class MessageEvent extends Event {
  constructor(type: string, initializer: MessageEventInit);
  /**
   * Returns the data of the message.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/MessageEvent/data)
   */
  readonly data: ArrayBuffer | string;
}
interface MessageEventInit {
  data: ArrayBuffer | string;
}
type WebSocketEventMap = {
  close: CloseEvent;
  message: MessageEvent;
  open: Event;
  error: ErrorEvent;
};
/**
 * Provides the API for creating and managing a WebSocket connection to a server, as well as for sending and receiving data on the connection.
 *
 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WebSocket)
 */
declare var WebSocket: {
  prototype: WebSocket;
  new (url: string, protocols?: string[] | string): WebSocket;
  readonly READY_STATE_CONNECTING: number;
  readonly CONNECTING: number;
  readonly READY_STATE_OPEN: number;
  readonly OPEN: number;
  readonly READY_STATE_CLOSING: number;
  readonly CLOSING: number;
  readonly READY_STATE_CLOSED: number;
  readonly CLOSED: number;
};
/**
 * Provides the API for creating and managing a WebSocket connection to a server, as well as for sending and receiving data on the connection.
 *
 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WebSocket)
 */
interface WebSocket extends EventTarget<WebSocketEventMap> {
  accept(): void;
  /**
   * Transmits data using the WebSocket connection. data can be a string, a Blob, an ArrayBuffer, or an ArrayBufferView.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WebSocket/send)
   */
  send(message: (ArrayBuffer | ArrayBufferView) | string): void;
  /**
   * Closes the WebSocket connection, optionally using code as the the WebSocket connection close code and reason as the the WebSocket connection close reason.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WebSocket/close)
   */
  close(code?: number, reason?: string): void;
  serializeAttachment(attachment: any): void;
  deserializeAttachment(): any | null;
  /**
   * Returns the state of the WebSocket object's connection. It can have the values described below.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WebSocket/readyState)
   */
  readyState: number;
  /**
   * Returns the URL that was used to establish the WebSocket connection.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WebSocket/url)
   */
  url: string | null;
  /**
   * Returns the subprotocol selected by the server, if any. It can be used in conjunction with the array form of the constructor's second argument to perform subprotocol negotiation.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WebSocket/protocol)
   */
  protocol: string | null;
  /**
   * Returns the extensions selected by the server, if any.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/WebSocket/extensions)
   */
  extensions: string | null;
}
declare const WebSocketPair: {
  new (): {
    0: WebSocket;
    1: WebSocket;
  };
};
interface SqlStorage {
  exec<T extends Record<string, SqlStorageValue>>(
    query: string,
    ...bindings: any[]
  ): SqlStorageCursor<T>;
  get databaseSize(): number;
  Cursor: typeof SqlStorageCursor;
  Statement: typeof SqlStorageStatement;
}
declare abstract class SqlStorageStatement {}
type SqlStorageValue = ArrayBuffer | string | number | null;
declare abstract class SqlStorageCursor<T extends Record<string, SqlStorageValue>> {
  next():
    | {
        done?: false;
        value: T;
      }
    | {
        done: true;
        value?: never;
      };
  toArray(): T[];
  one(): T;
  raw<U extends SqlStorageValue[]>(): IterableIterator<U>;
  columnNames: string[];
  get rowsRead(): number;
  get rowsWritten(): number;
  [Symbol.iterator](): IterableIterator<T>;
}
interface Socket {
  get readable(): ReadableStream;
  get writable(): WritableStream;
  get closed(): Promise<void>;
  get opened(): Promise<SocketInfo>;
  get upgraded(): boolean;
  get secureTransport(): 'on' | 'off' | 'starttls';
  close(): Promise<void>;
  startTls(options?: TlsOptions): Socket;
}
interface SocketOptions {
  secureTransport?: string;
  allowHalfOpen: boolean;
  highWaterMark?: number | bigint;
}
interface SocketAddress {
  hostname: string;
  port: number;
}
interface TlsOptions {
  expectedServerHostname?: string;
}
interface SocketInfo {
  remoteAddress?: string;
  localAddress?: string;
}
/* [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventSource) */
declare class EventSource extends EventTarget {
  constructor(url: string, init?: EventSourceEventSourceInit);
  /**
   * Aborts any instances of the fetch algorithm started for this EventSource object, and sets the readyState attribute to CLOSED.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventSource/close)
   */
  close(): void;
  /**
   * Returns the URL providing the event stream.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventSource/url)
   */
  get url(): string;
  /**
   * Returns true if the credentials mode for connection requests to the URL providing the event stream is set to "include", and false otherwise.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventSource/withCredentials)
   */
  get withCredentials(): boolean;
  /**
   * Returns the state of this EventSource object's connection. It can have the values described below.
   *
   * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventSource/readyState)
   */
  get readyState(): number;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventSource/open_event) */
  get onopen(): any | null;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventSource/open_event) */
  set onopen(value: any | null);
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventSource/message_event) */
  get onmessage(): any | null;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventSource/message_event) */
  set onmessage(value: any | null);
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventSource/error_event) */
  get onerror(): any | null;
  /* [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventSource/error_event) */
  set onerror(value: any | null);
  static readonly CONNECTING: number;
  static readonly OPEN: number;
  static readonly CLOSED: number;
  static from(stream: ReadableStream): EventSource;
}
interface EventSourceEventSourceInit {
  withCredentials?: boolean;
  fetcher?: Fetcher;
}
interface Container {
  get running(): boolean;
  start(options?: ContainerStartupOptions): void;
  monitor(): Promise<void>;
  destroy(error?: any): Promise<void>;
  signal(signo: number): void;
  getTcpPort(port: number): Fetcher;
}
interface ContainerStartupOptions {
  entrypoint?: string[];
  enableInternet: boolean;
  env?: Record<string, string>;
}
type AiImageClassificationInput = {
  image: number[];
};
type AiImageClassificationOutput = {
  score?: number;
  label?: string;
}[];
declare abstract class BaseAiImageClassification {
  inputs: AiImageClassificationInput;
  postProcessedOutputs: AiImageClassificationOutput;
}
type AiImageToTextInput = {
  image: number[];
  prompt?: string;
  max_tokens?: number;
  temperature?: number;
  top_p?: number;
  top_k?: number;
  seed?: number;
  repetition_penalty?: number;
  frequency_penalty?: number;
  presence_penalty?: number;
  raw?: boolean;
  messages?: RoleScopedChatInput[];
};
type AiImageToTextOutput = {
  description: string;
};
declare abstract class BaseAiImageToText {
  inputs: AiImageToTextInput;
  postProcessedOutputs: AiImageToTextOutput;
}
type AiImageTextToTextInput = {
  image: string;
  prompt?: string;
  max_tokens?: number;
  temperature?: number;
  ignore_eos?: boolean;
  top_p?: number;
  top_k?: number;
  seed?: number;
  repetition_penalty?: number;
  frequency_penalty?: number;
  presence_penalty?: number;
  raw?: boolean;
  messages?: RoleScopedChatInput[];
};
type AiImageTextToTextOutput = {
  description: string;
};
declare abstract class BaseAiImageTextToText {
  inputs: AiImageTextToTextInput;
  postProcessedOutputs: AiImageTextToTextOutput;
}
type AiObjectDetectionInput = {
  image: number[];
};
type AiObjectDetectionOutput = {
  score?: number;
  label?: string;
}[];
declare abstract class BaseAiObjectDetection {
  inputs: AiObjectDetectionInput;
  postProcessedOutputs: AiObjectDetectionOutput;
}
type AiSentenceSimilarityInput = {
  source: string;
  sentences: string[];
};
type AiSentenceSimilarityOutput = number[];
declare abstract class BaseAiSentenceSimilarity {
  inputs: AiSentenceSimilarityInput;
  postProcessedOutputs: AiSentenceSimilarityOutput;
}
type AiAutomaticSpeechRecognitionInput = {
  audio: number[];
};
type AiAutomaticSpeechRecognitionOutput = {
  text?: string;
  words?: {
    word: string;
    start: number;
    end: number;
  }[];
  vtt?: string;
};
declare abstract class BaseAiAutomaticSpeechRecognition {
  inputs: AiAutomaticSpeechRecognitionInput;
  postProcessedOutputs: AiAutomaticSpeechRecognitionOutput;
}
type AiSummarizationInput = {
  input_text: string;
  max_length?: number;
};
type AiSummarizationOutput = {
  summary: string;
};
declare abstract class BaseAiSummarization {
  inputs: AiSummarizationInput;
  postProcessedOutputs: AiSummarizationOutput;
}
type AiTextClassificationInput = {
  text: string;
};
type AiTextClassificationOutput = {
  score?: number;
  label?: string;
}[];
declare abstract class BaseAiTextClassification {
  inputs: AiTextClassificationInput;
  postProcessedOutputs: AiTextClassificationOutput;
}
type AiTextEmbeddingsInput = {
  text: string | string[];
};
type AiTextEmbeddingsOutput = {
  shape: number[];
  data: number[][];
};
declare abstract class BaseAiTextEmbeddings {
  inputs: AiTextEmbeddingsInput;
  postProcessedOutputs: AiTextEmbeddingsOutput;
}
type RoleScopedChatInput = {
  role: 'user' | 'assistant' | 'system' | 'tool' | (string & NonNullable<unknown>);
  content: string;
  name?: string;
};
type AiTextGenerationToolLegacyInput = {
  name: string;
  description: string;
  parameters?: {
    type: 'object' | (string & NonNullable<unknown>);
    properties: {
      [key: string]: {
        type: string;
        description?: string;
      };
    };
    required: string[];
  };
};
type AiTextGenerationToolInput = {
  type: 'function' | (string & NonNullable<unknown>);
  function: {
    name: string;
    description: string;
    parameters?: {
      type: 'object' | (string & NonNullable<unknown>);
      properties: {
        [key: string]: {
          type: string;
          description?: string;
        };
      };
      required: string[];
    };
  };
};
type AiTextGenerationFunctionsInput = {
  name: string;
  code: string;
};
type AiTextGenerationResponseFormat = {
  type: string;
  json_schema?: any;
};
type AiTextGenerationInput = {
  prompt?: string;
  raw?: boolean;
  stream?: boolean;
  max_tokens?: number;
  temperature?: number;
  top_p?: number;
  top_k?: number;
  seed?: number;
  repetition_penalty?: number;
  frequency_penalty?: number;
  presence_penalty?: number;
  messages?: RoleScopedChatInput[];
  response_format?: AiTextGenerationResponseFormat;
  tools?:
    | AiTextGenerationToolInput[]
    | AiTextGenerationToolLegacyInput[]
    | (object & NonNullable<unknown>);
  functions?: AiTextGenerationFunctionsInput[];
};
type AiTextGenerationOutput =
  | {
      response?: string;
      tool_calls?: {
        name: string;
        arguments: unknown;
      }[];
    }
  | ReadableStream;
declare abstract class BaseAiTextGeneration {
  inputs: AiTextGenerationInput;
  postProcessedOutputs: AiTextGenerationOutput;
}
type AiTextToSpeechInput = {
  prompt: string;
  lang?: string;
};
type AiTextToSpeechOutput =
  | Uint8Array
  | {
      audio: string;
    };
declare abstract class BaseAiTextToSpeech {
  inputs: AiTextToSpeechInput;
  postProcessedOutputs: AiTextToSpeechOutput;
}
type AiTextToImageInput = {
  prompt: string;
  negative_prompt?: string;
  height?: number;
  width?: number;
  image?: number[];
  image_b64?: string;
  mask?: number[];
  num_steps?: number;
  strength?: number;
  guidance?: number;
  seed?: number;
};
type AiTextToImageOutput = ReadableStream<Uint8Array>;
declare abstract class BaseAiTextToImage {
  inputs: AiTextToImageInput;
  postProcessedOutputs: AiTextToImageOutput;
}
type AiTranslationInput = {
  text: string;
  target_lang: string;
  source_lang?: string;
};
type AiTranslationOutput = {
  translated_text?: string;
};
declare abstract class BaseAiTranslation {
  inputs: AiTranslationInput;
  postProcessedOutputs: AiTranslationOutput;
}
type Ai_Cf_Openai_Whisper_Input =
  | string
  | {
      /**
       * An array of integers that represent the audio data constrained to 8-bit unsigned integer values
       */
      audio: number[];
    };
interface Ai_Cf_Openai_Whisper_Output {
  /**
   * The transcription
   */
  text: string;
  word_count?: number;
  words?: {
    word?: string;
    /**
     * The second this word begins in the recording
     */
    start?: number;
    /**
     * The ending second when the word completes
     */
    end?: number;
  }[];
  vtt?: string;
}
declare abstract class Base_Ai_Cf_Openai_Whisper {
  inputs: Ai_Cf_Openai_Whisper_Input;
  postProcessedOutputs: Ai_Cf_Openai_Whisper_Output;
}
type Ai_Cf_Unum_Uform_Gen2_Qwen_500M_Input =
  | string
  | {
      /**
       * The input text prompt for the model to generate a response.
       */
      prompt?: string;
      /**
       * If true, a chat template is not applied and you must adhere to the specific model's expected formatting.
       */
      raw?: boolean;
      /**
       * Controls the creativity of the AI's responses by adjusting how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses.
       */
      top_p?: number;
      /**
       * Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises.
       */
      top_k?: number;
      /**
       * Random seed for reproducibility of the generation.
       */
      seed?: number;
      /**
       * Penalty for repeated tokens; higher values discourage repetition.
       */
      repetition_penalty?: number;
      /**
       * Decreases the likelihood of the model repeating the same lines verbatim.
       */
      frequency_penalty?: number;
      /**
       * Increases the likelihood of the model introducing new topics.
       */
      presence_penalty?: number;
      image: number[] | (string & NonNullable<unknown>);
      /**
       * The maximum number of tokens to generate in the response.
       */
      max_tokens?: number;
    };
interface Ai_Cf_Unum_Uform_Gen2_Qwen_500M_Output {
  description?: string;
}
declare abstract class Base_Ai_Cf_Unum_Uform_Gen2_Qwen_500M {
  inputs: Ai_Cf_Unum_Uform_Gen2_Qwen_500M_Input;
  postProcessedOutputs: Ai_Cf_Unum_Uform_Gen2_Qwen_500M_Output;
}
type Ai_Cf_Openai_Whisper_Tiny_En_Input =
  | string
  | {
      /**
       * An array of integers that represent the audio data constrained to 8-bit unsigned integer values
       */
      audio: number[];
    };
interface Ai_Cf_Openai_Whisper_Tiny_En_Output {
  /**
   * The transcription
   */
  text: string;
  word_count?: number;
  words?: {
    word?: string;
    /**
     * The second this word begins in the recording
     */
    start?: number;
    /**
     * The ending second when the word completes
     */
    end?: number;
  }[];
  vtt?: string;
}
declare abstract class Base_Ai_Cf_Openai_Whisper_Tiny_En {
  inputs: Ai_Cf_Openai_Whisper_Tiny_En_Input;
  postProcessedOutputs: Ai_Cf_Openai_Whisper_Tiny_En_Output;
}
interface Ai_Cf_Openai_Whisper_Large_V3_Turbo_Input {
  /**
   * Base64 encoded value of the audio data.
   */
  audio: string;
  /**
   * Supported tasks are 'translate' or 'transcribe'.
   */
  task?: string;
  /**
   * The language of the audio being transcribed or translated.
   */
  language?: string;
  /**
   * Preprocess the audio with a voice activity detection model.
   */
  vad_filter?: string;
  /**
   * A text prompt to help provide context to the model on the contents of the audio.
   */
  initial_prompt?: string;
  /**
   * The prefix it appended the the beginning of the output of the transcription and can guide the transcription result.
   */
  prefix?: string;
}
interface Ai_Cf_Openai_Whisper_Large_V3_Turbo_Output {
  transcription_info?: {
    /**
     * The language of the audio being transcribed or translated.
     */
    language?: string;
    /**
     * The confidence level or probability of the detected language being accurate, represented as a decimal between 0 and 1.
     */
    language_probability?: number;
    /**
     * The total duration of the original audio file, in seconds.
     */
    duration?: number;
    /**
     * The duration of the audio after applying Voice Activity Detection (VAD) to remove silent or irrelevant sections, in seconds.
     */
    duration_after_vad?: number;
  };
  /**
   * The complete transcription of the audio.
   */
  text: string;
  /**
   * The total number of words in the transcription.
   */
  word_count?: number;
  segments?: {
    /**
     * The starting time of the segment within the audio, in seconds.
     */
    start?: number;
    /**
     * The ending time of the segment within the audio, in seconds.
     */
    end?: number;
    /**
     * The transcription of the segment.
     */
    text?: string;
    /**
     * The temperature used in the decoding process, controlling randomness in predictions. Lower values result in more deterministic outputs.
     */
    temperature?: number;
    /**
     * The average log probability of the predictions for the words in this segment, indicating overall confidence.
     */
    avg_logprob?: number;
    /**
     * The compression ratio of the input to the output, measuring how much the text was compressed during the transcription process.
     */
    compression_ratio?: number;
    /**
     * The probability that the segment contains no speech, represented as a decimal between 0 and 1.
     */
    no_speech_prob?: number;
    words?: {
      /**
       * The individual word transcribed from the audio.
       */
      word?: string;
      /**
       * The starting time of the word within the audio, in seconds.
       */
      start?: number;
      /**
       * The ending time of the word within the audio, in seconds.
       */
      end?: number;
    }[];
  }[];
  /**
   * The transcription in WebVTT format, which includes timing and text information for use in subtitles.
   */
  vtt?: string;
}
declare abstract class Base_Ai_Cf_Openai_Whisper_Large_V3_Turbo {
  inputs: Ai_Cf_Openai_Whisper_Large_V3_Turbo_Input;
  postProcessedOutputs: Ai_Cf_Openai_Whisper_Large_V3_Turbo_Output;
}
type Ai_Cf_Baai_Bge_M3_Input = BGEM3InputQueryAndContexts | BGEM3InputEmbedding;
interface BGEM3InputQueryAndContexts {
  /**
   * A query you wish to perform against the provided contexts. If no query is provided the model with respond with embeddings for contexts
   */
  query?: string;
  /**
   * List of provided contexts. Note that the index in this array is important, as the response will refer to it.
   */
  contexts: {
    /**
     * One of the provided context content
     */
    text?: string;
  }[];
  /**
   * When provided with too long context should the model error out or truncate the context to fit?
   */
  truncate_inputs?: boolean;
}
interface BGEM3InputEmbedding {
  text: string | string[];
  /**
   * When provided with too long context should the model error out or truncate the context to fit?
   */
  truncate_inputs?: boolean;
}
type Ai_Cf_Baai_Bge_M3_Output =
  | BGEM3OuputQuery
  | BGEM3OutputEmbeddingForContexts
  | BGEM3OuputEmbedding;
interface BGEM3OuputQuery {
  response?: {
    /**
     * Index of the context in the request
     */
    id?: number;
    /**
     * Score of the context under the index.
     */
    score?: number;
  }[];
}
interface BGEM3OutputEmbeddingForContexts {
  response?: number[][];
  shape?: number[];
  /**
   * The pooling method used in the embedding process.
   */
  pooling?: 'mean' | 'cls';
}
interface BGEM3OuputEmbedding {
  shape?: number[];
  /**
   * Embeddings of the requested text values
   */
  data?: number[][];
  /**
   * The pooling method used in the embedding process.
   */
  pooling?: 'mean' | 'cls';
}
declare abstract class Base_Ai_Cf_Baai_Bge_M3 {
  inputs: Ai_Cf_Baai_Bge_M3_Input;
  postProcessedOutputs: Ai_Cf_Baai_Bge_M3_Output;
}
interface Ai_Cf_Black_Forest_Labs_Flux_1_Schnell_Input {
  /**
   * A text description of the image you want to generate.
   */
  prompt: string;
  /**
   * The number of diffusion steps; higher values can improve quality but take longer.
   */
  steps?: number;
}
interface Ai_Cf_Black_Forest_Labs_Flux_1_Schnell_Output {
  /**
   * The generated image in Base64 format.
   */
  image?: string;
}
declare abstract class Base_Ai_Cf_Black_Forest_Labs_Flux_1_Schnell {
  inputs: Ai_Cf_Black_Forest_Labs_Flux_1_Schnell_Input;
  postProcessedOutputs: Ai_Cf_Black_Forest_Labs_Flux_1_Schnell_Output;
}
type Ai_Cf_Meta_Llama_3_2_11B_Vision_Instruct_Input = Prompt | Messages;
interface Prompt {
  /**
   * The input text prompt for the model to generate a response.
   */
  prompt: string;
  image?: number[] | (string & NonNullable<unknown>);
  /**
   * If true, a chat template is not applied and you must adhere to the specific model's expected formatting.
   */
  raw?: boolean;
  /**
   * If true, the response will be streamed back incrementally using SSE, Server Sent Events.
   */
  stream?: boolean;
  /**
   * The maximum number of tokens to generate in the response.
   */
  max_tokens?: number;
  /**
   * Controls the randomness of the output; higher values produce more random results.
   */
  temperature?: number;
  /**
   * Adjusts the creativity of the AI's responses by controlling how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses.
   */
  top_p?: number;
  /**
   * Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises.
   */
  top_k?: number;
  /**
   * Random seed for reproducibility of the generation.
   */
  seed?: number;
  /**
   * Penalty for repeated tokens; higher values discourage repetition.
   */
  repetition_penalty?: number;
  /**
   * Decreases the likelihood of the model repeating the same lines verbatim.
   */
  frequency_penalty?: number;
  /**
   * Increases the likelihood of the model introducing new topics.
   */
  presence_penalty?: number;
  /**
   * Name of the LoRA (Low-Rank Adaptation) model to fine-tune the base model.
   */
  lora?: string;
}
interface Messages {
  /**
   * An array of message objects representing the conversation history.
   */
  messages: {
    /**
     * The role of the message sender (e.g., 'user', 'assistant', 'system', 'tool').
     */
    role: string;
    /**
     * The content of the message as a string.
     */
    content: string;
  }[];
  image?: number[] | string;
  functions?: {
    name: string;
    code: string;
  }[];
  /**
   * A list of tools available for the assistant to use.
   */
  tools?: (
    | {
        /**
         * The name of the tool. More descriptive the better.
         */
        name: string;
        /**
         * A brief description of what the tool does.
         */
        description: string;
        /**
         * Schema defining the parameters accepted by the tool.
         */
        parameters: {
          /**
           * The type of the parameters object (usually 'object').
           */
          type: string;
          /**
           * List of required parameter names.
           */
          required?: string[];
          /**
           * Definitions of each parameter.
           */
          properties: {
            [k: string]: {
              /**
               * The data type of the parameter.
               */
              type: string;
              /**
               * A description of the expected parameter.
               */
              description: string;
            };
          };
        };
      }
    | {
        /**
         * Specifies the type of tool (e.g., 'function').
         */
        type: string;
        /**
         * Details of the function tool.
         */
        function: {
          /**
           * The name of the function.
           */
          name: string;
          /**
           * A brief description of what the function does.
           */
          description: string;
          /**
           * Schema defining the parameters accepted by the function.
           */
          parameters: {
            /**
             * The type of the parameters object (usually 'object').
             */
            type: string;
            /**
             * List of required parameter names.
             */
            required?: string[];
            /**
             * Definitions of each parameter.
             */
            properties: {
              [k: string]: {
                /**
                 * The data type of the parameter.
                 */
                type: string;
                /**
                 * A description of the expected parameter.
                 */
                description: string;
              };
            };
          };
        };
      }
  )[];
  /**
   * If true, the response will be streamed back incrementally.
   */
  stream?: boolean;
  /**
   * The maximum number of tokens to generate in the response.
   */
  max_tokens?: number;
  /**
   * Controls the randomness of the output; higher values produce more random results.
   */
  temperature?: number;
  /**
   * Controls the creativity of the AI's responses by adjusting how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses.
   */
  top_p?: number;
  /**
   * Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises.
   */
  top_k?: number;
  /**
   * Random seed for reproducibility of the generation.
   */
  seed?: number;
  /**
   * Penalty for repeated tokens; higher values discourage repetition.
   */
  repetition_penalty?: number;
  /**
   * Decreases the likelihood of the model repeating the same lines verbatim.
   */
  frequency_penalty?: number;
  /**
   * Increases the likelihood of the model introducing new topics.
   */
  presence_penalty?: number;
}
type Ai_Cf_Meta_Llama_3_2_11B_Vision_Instruct_Output =
  | {
      /**
       * The generated text response from the model
       */
      response?: string;
      /**
       * An array of tool calls requests made during the response generation
       */
      tool_calls?: {
        /**
         * The arguments passed to be passed to the tool call request
         */
        arguments?: object;
        /**
         * The name of the tool to be called
         */
        name?: string;
      }[];
    }
  | ReadableStream;
declare abstract class Base_Ai_Cf_Meta_Llama_3_2_11B_Vision_Instruct {
  inputs: Ai_Cf_Meta_Llama_3_2_11B_Vision_Instruct_Input;
  postProcessedOutputs: Ai_Cf_Meta_Llama_3_2_11B_Vision_Instruct_Output;
}
interface Ai_Cf_Meta_Llama_Guard_3_8B_Input {
  /**
   * An array of message objects representing the conversation history.
   */
  messages: {
    /**
     * The role of the message sender must alternate between 'user' and 'assistant'.
     */
    role: 'user' | 'assistant';
    /**
     * The content of the message as a string.
     */
    content: string;
  }[];
  /**
   * The maximum number of tokens to generate in the response.
   */
  max_tokens?: number;
  /**
   * Controls the randomness of the output; higher values produce more random results.
   */
  temperature?: number;
  /**
   * Dictate the output format of the generated response.
   */
  response_format?: {
    /**
     * Set to json_object to process and output generated text as JSON.
     */
    type?: string;
  };
}
interface Ai_Cf_Meta_Llama_Guard_3_8B_Output {
  response?:
    | string
    | {
        /**
         * Whether the conversation is safe or not.
         */
        safe?: boolean;
        /**
         * A list of what hazard categories predicted for the conversation, if the conversation is deemed unsafe.
         */
        categories?: string[];
      };
  /**
   * Usage statistics for the inference request
   */
  usage?: {
    /**
     * Total number of tokens in input
     */
    prompt_tokens?: number;
    /**
     * Total number of tokens in output
     */
    completion_tokens?: number;
    /**
     * Total number of input and output tokens
     */
    total_tokens?: number;
  };
}
declare abstract class Base_Ai_Cf_Meta_Llama_Guard_3_8B {
  inputs: Ai_Cf_Meta_Llama_Guard_3_8B_Input;
  postProcessedOutputs: Ai_Cf_Meta_Llama_Guard_3_8B_Output;
}
interface Ai_Cf_Baai_Bge_Reranker_Base_Input {
  /**
   * A query you wish to perform against the provided contexts.
   */
  /**
   * Number of returned results starting with the best score.
   */
  top_k?: number;
  /**
   * List of provided contexts. Note that the index in this array is important, as the response will refer to it.
   */
  contexts: {
    /**
     * One of the provided context content
     */
    text?: string;
  }[];
}
interface Ai_Cf_Baai_Bge_Reranker_Base_Output {
  response?: {
    /**
     * Index of the context in the request
     */
    id?: number;
    /**
     * Score of the context under the index.
     */
    score?: number;
  }[];
}
declare abstract class Base_Ai_Cf_Baai_Bge_Reranker_Base {
  inputs: Ai_Cf_Baai_Bge_Reranker_Base_Input;
  postProcessedOutputs: Ai_Cf_Baai_Bge_Reranker_Base_Output;
}
type Ai_Cf_Meta_Llama_4_Scout_17B_16E_Instruct_Input =
  | Ai_Cf_Meta_Llama_4_Prompt
  | Ai_Cf_Meta_Llama_4_Messages;
interface Ai_Cf_Meta_Llama_4_Prompt {
  /**
   * The input text prompt for the model to generate a response.
   */
  prompt: string;
  /**
   * JSON schema that should be fulfilled for the response.
   */
  guided_json?: object;
  /**
   * If true, a chat template is not applied and you must adhere to the specific model's expected formatting.
   */
  raw?: boolean;
  /**
   * If true, the response will be streamed back incrementally using SSE, Server Sent Events.
   */
  stream?: boolean;
  /**
   * The maximum number of tokens to generate in the response.
   */
  max_tokens?: number;
  /**
   * Controls the randomness of the output; higher values produce more random results.
   */
  temperature?: number;
  /**
   * Adjusts the creativity of the AI's responses by controlling how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses.
   */
  top_p?: number;
  /**
   * Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises.
   */
  top_k?: number;
  /**
   * Random seed for reproducibility of the generation.
   */
  seed?: number;
  /**
   * Penalty for repeated tokens; higher values discourage repetition.
   */
  repetition_penalty?: number;
  /**
   * Decreases the likelihood of the model repeating the same lines verbatim.
   */
  frequency_penalty?: number;
  /**
   * Increases the likelihood of the model introducing new topics.
   */
  presence_penalty?: number;
}
interface Ai_Cf_Meta_Llama_4_Messages {
  /**
   * An array of message objects representing the conversation history.
   */
  messages: {
    /**
     * The role of the message sender (e.g., 'user', 'assistant', 'system', 'tool').
     */
    role?: string;
    /**
     * The tool call id. Must be supplied for tool calls for Mistral-3. If you don't know what to put here you can fall back to 000000001
     */
    tool_call_id?: string;
    content?:
      | string
      | {
          /**
           * Type of the content provided
           */
          type?: string;
          text?: string;
          image_url?: {
            /**
             * image uri with data (e.g. data:image/jpeg;base64,/9j/...). HTTP URL will not be accepted
             */
            url?: string;
          };
        }[]
      | {
          /**
           * Type of the content provided
           */
          type?: string;
          text?: string;
          image_url?: {
            /**
             * image uri with data (e.g. data:image/jpeg;base64,/9j/...). HTTP URL will not be accepted
             */
            url?: string;
          };
        };
  }[];
  functions?: {
    name: string;
    code: string;
  }[];
  /**
   * A list of tools available for the assistant to use.
   */
  tools?: (
    | {
        /**
         * The name of the tool. More descriptive the better.
         */
        name: string;
        /**
         * A brief description of what the tool does.
         */
        description: string;
        /**
         * Schema defining the parameters accepted by the tool.
         */
        parameters: {
          /**
           * The type of the parameters object (usually 'object').
           */
          type: string;
          /**
           * List of required parameter names.
           */
          required?: string[];
          /**
           * Definitions of each parameter.
           */
          properties: {
            [k: string]: {
              /**
               * The data type of the parameter.
               */
              type: string;
              /**
               * A description of the expected parameter.
               */
              description: string;
            };
          };
        };
      }
    | {
        /**
         * Specifies the type of tool (e.g., 'function').
         */
        type: string;
        /**
         * Details of the function tool.
         */
        function: {
          /**
           * The name of the function.
           */
          name: string;
          /**
           * A brief description of what the function does.
           */
          description: string;
          /**
           * Schema defining the parameters accepted by the function.
           */
          parameters: {
            /**
             * The type of the parameters object (usually 'object').
             */
            type: string;
            /**
             * List of required parameter names.
             */
            required?: string[];
            /**
             * Definitions of each parameter.
             */
            properties: {
              [k: string]: {
                /**
                 * The data type of the parameter.
                 */
                type: string;
                /**
                 * A description of the expected parameter.
                 */
                description: string;
              };
            };
          };
        };
      }
  )[];
  /**
   * JSON schema that should be fufilled for the response.
   */
  guided_json?: object;
  /**
   * If true, a chat template is not applied and you must adhere to the specific model's expected formatting.
   */
  raw?: boolean;
  /**
   * If true, the response will be streamed back incrementally using SSE, Server Sent Events.
   */
  stream?: boolean;
  /**
   * The maximum number of tokens to generate in the response.
   */
  max_tokens?: number;
  /**
   * Controls the randomness of the output; higher values produce more random results.
   */
  temperature?: number;
  /**
   * Adjusts the creativity of the AI's responses by controlling how many possible words it considers. Lower values make outputs more predictable; higher values allow for more varied and creative responses.
   */
  top_p?: number;
  /**
   * Limits the AI to choose from the top 'k' most probable words. Lower values make responses more focused; higher values introduce more variety and potential surprises.
   */
  top_k?: number;
  /**
   * Random seed for reproducibility of the generation.
   */
  seed?: number;
  /**
   * Penalty for repeated tokens; higher values discourage repetition.
   */
  repetition_penalty?: number;
  /**
   * Decreases the likelihood of the model repeating the same lines verbatim.
   */
  frequency_penalty?: number;
  /**
   * Increases the likelihood of the model introducing new topics.
   */
  presence_penalty?: number;
}
type Ai_Cf_Meta_Llama_4_Scout_17B_16E_Instruct_Output =
  | {
      /**
       * The generated text response from the model
       */
      response: string;
      /**
       * Usage statistics for the inference request
       */
      usage?: {
        /**
         * Total number of tokens in input
         */
        prompt_tokens?: number;
        /**
         * Total number of tokens in output
         */
        completion_tokens?: number;
        /**
         * Total number of input and output tokens
         */
        total_tokens?: number;
      };
      /**
       * An array of tool calls requests made during the response generation
       */
      tool_calls?: {
        /**
         * The arguments passed to be passed to the tool call request
         */
        arguments?: object;
        /**
         * The name of the tool to be called
         */
        name?: string;
      }[];
    }
  | string;
declare abstract class Base_Ai_Cf_Meta_Llama_4_Scout_17B_16E_Instruct {
  inputs: Ai_Cf_Meta_Llama_4_Scout_17B_16E_Instruct_Input;
  postProcessedOutputs: Ai_Cf_Meta_Llama_4_Scout_17B_16E_Instruct_Output;
}
interface AiModels {
  '@cf/huggingface/distilbert-sst-2-int8': BaseAiTextClassification;
  '@cf/stabilityai/stable-diffusion-xl-base-1.0': BaseAiTextToImage;
  '@cf/runwayml/stable-diffusion-v1-5-inpainting': BaseAiTextToImage;
  '@cf/runwayml/stable-diffusion-v1-5-img2img': BaseAiTextToImage;
  '@cf/lykon/dreamshaper-8-lcm': BaseAiTextToImage;
  '@cf/bytedance/stable-diffusion-xl-lightning': BaseAiTextToImage;
  '@cf/myshell-ai/melotts': BaseAiTextToSpeech;
  '@cf/baai/bge-base-en-v1.5': BaseAiTextEmbeddings;
  '@cf/baai/bge-small-en-v1.5': BaseAiTextEmbeddings;
  '@cf/baai/bge-large-en-v1.5': BaseAiTextEmbeddings;
  '@cf/microsoft/resnet-50': BaseAiImageClassification;
  '@cf/facebook/detr-resnet-50': BaseAiObjectDetection;
  '@cf/meta/llama-2-7b-chat-int8': BaseAiTextGeneration;
  '@cf/mistral/mistral-7b-instruct-v0.1': BaseAiTextGeneration;
  '@cf/meta/llama-2-7b-chat-fp16': BaseAiTextGeneration;
  '@hf/thebloke/llama-2-13b-chat-awq': BaseAiTextGeneration;
  '@hf/thebloke/mistral-7b-instruct-v0.1-awq': BaseAiTextGeneration;
  '@hf/thebloke/zephyr-7b-beta-awq': BaseAiTextGeneration;
  '@hf/thebloke/openhermes-2.5-mistral-7b-awq': BaseAiTextGeneration;
  '@hf/thebloke/neural-chat-7b-v3-1-awq': BaseAiTextGeneration;
  '@hf/thebloke/llamaguard-7b-awq': BaseAiTextGeneration;
  '@hf/thebloke/deepseek-coder-6.7b-base-awq': BaseAiTextGeneration;
  '@hf/thebloke/deepseek-coder-6.7b-instruct-awq': BaseAiTextGeneration;
  '@cf/deepseek-ai/deepseek-math-7b-instruct': BaseAiTextGeneration;
  '@cf/defog/sqlcoder-7b-2': BaseAiTextGeneration;
  '@cf/openchat/openchat-3.5-0106': BaseAiTextGeneration;
  '@cf/tiiuae/falcon-7b-instruct': BaseAiTextGeneration;
  '@cf/thebloke/discolm-german-7b-v1-awq': BaseAiTextGeneration;
  '@cf/qwen/qwen1.5-0.5b-chat': BaseAiTextGeneration;
  '@cf/qwen/qwen1.5-7b-chat-awq': BaseAiTextGeneration;
  '@cf/qwen/qwen1.5-14b-chat-awq': BaseAiTextGeneration;
  '@cf/tinyllama/tinyllama-1.1b-chat-v1.0': BaseAiTextGeneration;
  '@cf/microsoft/phi-2': BaseAiTextGeneration;
  '@cf/qwen/qwen1.5-1.8b-chat': BaseAiTextGeneration;
  '@cf/mistral/mistral-7b-instruct-v0.2-lora': BaseAiTextGeneration;
  '@hf/nousresearch/hermes-2-pro-mistral-7b': BaseAiTextGeneration;
  '@hf/nexusflow/starling-lm-7b-beta': BaseAiTextGeneration;
  '@hf/google/gemma-7b-it': BaseAiTextGeneration;
  '@cf/meta-llama/llama-2-7b-chat-hf-lora': BaseAiTextGeneration;
  '@cf/google/gemma-2b-it-lora': BaseAiTextGeneration;
  '@cf/google/gemma-7b-it-lora': BaseAiTextGeneration;
  '@hf/mistral/mistral-7b-instruct-v0.2': BaseAiTextGeneration;
  '@cf/meta/llama-3-8b-instruct': BaseAiTextGeneration;
  '@cf/fblgit/una-cybertron-7b-v2-bf16': BaseAiTextGeneration;
  '@cf/meta/llama-3-8b-instruct-awq': BaseAiTextGeneration;
  '@hf/meta-llama/meta-llama-3-8b-instruct': BaseAiTextGeneration;
  '@cf/meta/llama-3.1-8b-instruct': BaseAiTextGeneration;
  '@cf/meta/llama-3.1-8b-instruct-fp8': BaseAiTextGeneration;
  '@cf/meta/llama-3.1-8b-instruct-awq': BaseAiTextGeneration;
  '@cf/meta/llama-3.2-3b-instruct': BaseAiTextGeneration;
  '@cf/meta/llama-3.2-1b-instruct': BaseAiTextGeneration;
  '@cf/meta/llama-3.3-70b-instruct-fp8-fast': BaseAiTextGeneration;
  '@cf/deepseek-ai/deepseek-r1-distill-qwen-32b': BaseAiTextGeneration;
  '@cf/meta/m2m100-1.2b': BaseAiTranslation;
  '@cf/facebook/bart-large-cnn': BaseAiSummarization;
  '@cf/llava-hf/llava-1.5-7b-hf': BaseAiImageToText;
  '@cf/openai/whisper': Base_Ai_Cf_Openai_Whisper;
  '@cf/unum/uform-gen2-qwen-500m': Base_Ai_Cf_Unum_Uform_Gen2_Qwen_500M;
  '@cf/openai/whisper-tiny-en': Base_Ai_Cf_Openai_Whisper_Tiny_En;
  '@cf/openai/whisper-large-v3-turbo': Base_Ai_Cf_Openai_Whisper_Large_V3_Turbo;
  '@cf/baai/bge-m3': Base_Ai_Cf_Baai_Bge_M3;
  '@cf/black-forest-labs/flux-1-schnell': Base_Ai_Cf_Black_Forest_Labs_Flux_1_Schnell;
  '@cf/meta/llama-3.2-11b-vision-instruct': Base_Ai_Cf_Meta_Llama_3_2_11B_Vision_Instruct;
  '@cf/meta/llama-guard-3-8b': Base_Ai_Cf_Meta_Llama_Guard_3_8B;
  '@cf/baai/bge-reranker-base': Base_Ai_Cf_Baai_Bge_Reranker_Base;
  '@cf/meta/llama-4-scout-17b-16e-instruct': Base_Ai_Cf_Meta_Llama_4_Scout_17B_16E_Instruct;
}
type AiOptions = {
  gateway?: GatewayOptions;
  returnRawResponse?: boolean;
  prefix?: string;
  extraHeaders?: object;
};
type ConversionResponse = {
  name: string;
  mimeType: string;
  format: 'markdown';
  tokens: number;
  data: string;
};
type AiModelsSearchParams = {
  author?: string;
  hide_experimental?: boolean;
  page?: number;
  per_page?: number;
  search?: string;
  source?: number;
  task?: string;
};
type AiModelsSearchObject = {
  id: string;
  source: number;
  name: string;
  description: string;
  task: {
    id: string;
    name: string;
    description: string;
  };
  tags: string[];
  properties: {
    property_id: string;
    value: string;
  }[];
};
interface InferenceUpstreamError extends Error {}
interface AiInternalError extends Error {}
type AiModelListType = Record<string, any>;
declare abstract class Ai<AiModelList extends AiModelListType = AiModels> {
  aiGatewayLogId: string | null;
  gateway(gatewayId: string): AiGateway;
  autorag(autoragId: string): AutoRAG;
  run<Name extends keyof AiModelList, Options extends AiOptions>(
    model: Name,
    inputs: AiModelList[Name]['inputs'],
    options?: Options,
  ): Promise<
    Options extends {
      returnRawResponse: true;
    }
      ? Response
      : AiModelList[Name]['postProcessedOutputs']
  >;
  models(params?: AiModelsSearchParams): Promise<AiModelsSearchObject[]>;
  toMarkdown(
    files: {
      name: string;
      blob: Blob;
    }[],
    options?: {
      gateway?: GatewayOptions;
      extraHeaders?: object;
    },
  ): Promise<ConversionResponse[]>;
  toMarkdown(
    files: {
      name: string;
      blob: Blob;
    },
    options?: {
      gateway?: GatewayOptions;
      extraHeaders?: object;
    },
  ): Promise<ConversionResponse>;
}
type GatewayRetries = {
  maxAttempts?: 1 | 2 | 3 | 4 | 5;
  retryDelayMs?: number;
  backoff?: 'constant' | 'linear' | 'exponential';
};
type GatewayOptions = {
  id: string;
  cacheKey?: string;
  cacheTtl?: number;
  skipCache?: boolean;
  metadata?: Record<string, number | string | boolean | null | bigint>;
  collectLog?: boolean;
  eventId?: string;
  requestTimeoutMs?: number;
  retries?: GatewayRetries;
};
type AiGatewayPatchLog = {
  score?: number | null;
  feedback?: -1 | 1 | null;
  metadata?: Record<string, number | string | boolean | null | bigint> | null;
};
type AiGatewayLog = {
  id: string;
  provider: string;
  model: string;
  model_type?: string;
  path: string;
  duration: number;
  request_type?: string;
  request_content_type?: string;
  status_code: number;
  response_content_type?: string;
  success: boolean;
  cached: boolean;
  tokens_in?: number;
  tokens_out?: number;
  metadata?: Record<string, number | string | boolean | null | bigint>;
  step?: number;
  cost?: number;
  custom_cost?: boolean;
  request_size: number;
  request_head?: string;
  request_head_complete: boolean;
  response_size: number;
  response_head?: string;
  response_head_complete: boolean;
  created_at: Date;
};
type AIGatewayProviders =
  | 'workers-ai'
  | 'anthropic'
  | 'aws-bedrock'
  | 'azure-openai'
  | 'google-vertex-ai'
  | 'huggingface'
  | 'openai'
  | 'perplexity-ai'
  | 'replicate'
  | 'groq'
  | 'cohere'
  | 'google-ai-studio'
  | 'mistral'
  | 'grok'
  | 'openrouter'
  | 'deepseek'
  | 'cerebras'
  | 'cartesia'
  | 'elevenlabs'
  | 'adobe-firefly';
type AIGatewayHeaders = {
  'cf-aig-metadata': Record<string, number | string | boolean | null | bigint> | string;
  'cf-aig-custom-cost':
    | {
        per_token_in?: number;
        per_token_out?: number;
      }
    | {
        total_cost?: number;
      }
    | string;
  'cf-aig-cache-ttl': number | string;
  'cf-aig-skip-cache': boolean | string;
  'cf-aig-cache-key': string;
  'cf-aig-event-id': string;
  'cf-aig-request-timeout': number | string;
  'cf-aig-max-attempts': number | string;
  'cf-aig-retry-delay': number | string;
  'cf-aig-backoff': string;
  'cf-aig-collect-log': boolean | string;
  Authorization: string;
  'Content-Type': string;
  [key: string]: string | number | boolean | object;
};
type AIGatewayUniversalRequest = {
  provider: AIGatewayProviders | string; // eslint-disable-line
  endpoint: string;
  headers: Partial<AIGatewayHeaders>;
  query: unknown;
};
interface AiGatewayInternalError extends Error {}
interface AiGatewayLogNotFound extends Error {}
declare abstract class AiGateway {
  patchLog(logId: string, data: AiGatewayPatchLog): Promise<void>;
  getLog(logId: string): Promise<AiGatewayLog>;
  run(
    data: AIGatewayUniversalRequest | AIGatewayUniversalRequest[],
    options?: {
      gateway?: GatewayOptions;
      extraHeaders?: object;
    },
  ): Promise<Response>;
  getUrl(provider?: AIGatewayProviders | string): Promise<string>; // eslint-disable-line
}
interface AutoRAGInternalError extends Error {}
interface AutoRAGNotFoundError extends Error {}
interface AutoRAGUnauthorizedError extends Error {}
type ComparisonFilter = {
  key: string;
  type: 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte';
  value: string | number | boolean;
};
type CompoundFilter = {
  type: 'and' | 'or';
  filters: ComparisonFilter[];
};
type AutoRagSearchRequest = {
  query: string;
  filters?: CompoundFilter | ComparisonFilter;
  max_num_results?: number;
  ranking_options?: {
    ranker?: string;
    score_threshold?: number;
  };
  rewrite_query?: boolean;
};
type AutoRagAiSearchRequest = AutoRagSearchRequest & {
  stream?: boolean;
};
type AutoRagAiSearchRequestStreaming = Omit<AutoRagAiSearchRequest, 'stream'> & {
  stream: true;
};
type AutoRagSearchResponse = {
  object: 'vector_store.search_results.page';
  search_query: string;
  data: {
    file_id: string;
    filename: string;
    score: number;
    attributes: Record<string, string | number | boolean | null>;
    content: {
      type: 'text';
      text: string;
    }[];
  }[];
  has_more: boolean;
  next_page: string | null;
};
type AutoRagAiSearchResponse = AutoRagSearchResponse & {
  response: string;
};
declare abstract class AutoRAG {
  search(params: AutoRagSearchRequest): Promise<AutoRagSearchResponse>;
  aiSearch(params: AutoRagAiSearchRequestStreaming): Promise<Response>;
  aiSearch(params: AutoRagAiSearchRequest): Promise<AutoRagAiSearchResponse>;
  aiSearch(params: AutoRagAiSearchRequest): Promise<AutoRagAiSearchResponse | Response>;
}
interface BasicImageTransformations {
  /**
   * Maximum width in image pixels. The value must be an integer.
   */
  width?: number;
  /**
   * Maximum height in image pixels. The value must be an integer.
   */
  height?: number;
  /**
   * Resizing mode as a string. It affects interpretation of width and height
   * options:
   *  - scale-down: Similar to contain, but the image is never enlarged. If
   *    the image is larger than given width or height, it will be resized.
   *    Otherwise its original size will be kept.
   *  - contain: Resizes to maximum size that fits within the given width and
   *    height. If only a single dimension is given (e.g. only width), the
   *    image will be shrunk or enlarged to exactly match that dimension.
   *    Aspect ratio is always preserved.
   *  - cover: Resizes (shrinks or enlarges) to fill the entire area of width
   *    and height. If the image has an aspect ratio different from the ratio
   *    of width and height, it will be cropped to fit.
   *  - crop: The image will be shrunk and cropped to fit within the area
   *    specified by width and height. The image will not be enlarged. For images
   *    smaller than the given dimensions it's the same as scale-down. For
   *    images larger than the given dimensions, it's the same as cover.
   *    See also trim.
   *  - pad: Resizes to the maximum size that fits within the given width and
   *    height, and then fills the remaining area with a background color
   *    (white by default). Use of this mode is not recommended, as the same
   *    effect can be more efficiently achieved with the contain mode and the
   *    CSS object-fit: contain property.
   *  - squeeze: Stretches and deforms to the width and height given, even if it
   *    breaks aspect ratio
   */
  fit?: 'scale-down' | 'contain' | 'cover' | 'crop' | 'pad' | 'squeeze';
  /**
   * When cropping with fit: "cover", this defines the side or point that should
   * be left uncropped. The value is either a string
   * "left", "right", "top", "bottom", "auto", or "center" (the default),
   * or an object {x, y} containing focal point coordinates in the original
   * image expressed as fractions ranging from 0.0 (top or left) to 1.0
   * (bottom or right), 0.5 being the center. {fit: "cover", gravity: "top"} will
   * crop bottom or left and right sides as necessary, but won’t crop anything
   * from the top. {fit: "cover", gravity: {x:0.5, y:0.2}} will crop each side to
   * preserve as much as possible around a point at 20% of the height of the
   * source image.
   */
  gravity?:
    | 'left'
    | 'right'
    | 'top'
    | 'bottom'
    | 'center'
    | 'auto'
    | 'entropy'
    | BasicImageTransformationsGravityCoordinates;
  /**
   * Background color to add underneath the image. Applies only to images with
   * transparency (such as PNG). Accepts any CSS color (#RRGGBB, rgba(…),
   * hsl(…), etc.)
   */
  background?: string;
  /**
   * Number of degrees (90, 180, 270) to rotate the image by. width and height
   * options refer to axes after rotation.
   */
  rotate?: 0 | 90 | 180 | 270 | 360;
}
interface BasicImageTransformationsGravityCoordinates {
  x?: number;
  y?: number;
  mode?: 'remainder' | 'box-center';
}
/**
 * In addition to the properties you can set in the RequestInit dict
 * that you pass as an argument to the Request constructor, you can
 * set certain properties of a `cf` object to control how Cloudflare
 * features are applied to that new Request.
 *
 * Note: Currently, these properties cannot be tested in the
 * playground.
 */
interface RequestInitCfProperties extends Record<string, unknown> {
  cacheEverything?: boolean;
  /**
   * A request's cache key is what determines if two requests are
   * "the same" for caching purposes. If a request has the same cache key
   * as some previous request, then we can serve the same cached response for
   * both. (e.g. 'some-key')
   *
   * Only available for Enterprise customers.
   */
  cacheKey?: string;
  /**
   * This allows you to append additional Cache-Tag response headers
   * to the origin response without modifications to the origin server.
   * This will allow for greater control over the Purge by Cache Tag feature
   * utilizing changes only in the Workers process.
   *
   * Only available for Enterprise customers.
   */
  cacheTags?: string[];
  /**
   * Force response to be cached for a given number of seconds. (e.g. 300)
   */
  cacheTtl?: number;
  /**
   * Force response to be cached for a given number of seconds based on the Origin status code.
   * (e.g. { '200-299': 86400, '404': 1, '500-599': 0 })
   */
  cacheTtlByStatus?: Record<string, number>;
  scrapeShield?: boolean;
  apps?: boolean;
  image?: RequestInitCfPropertiesImage;
  minify?: RequestInitCfPropertiesImageMinify;
  mirage?: boolean;
  polish?: 'lossy' | 'lossless' | 'off';
  r2?: RequestInitCfPropertiesR2;
  /**
   * Redirects the request to an alternate origin server. You can use this,
   * for example, to implement load balancing across several origins.
   * (e.g.us-east.example.com)
   *
   * Note - For security reasons, the hostname set in resolveOverride must
   * be proxied on the same Cloudflare zone of the incoming request.
   * Otherwise, the setting is ignored. CNAME hosts are allowed, so to
   * resolve to a host under a different domain or a DNS only domain first
   * declare a CNAME record within your own zone’s DNS mapping to the
   * external hostname, set proxy on Cloudflare, then set resolveOverride
   * to point to that CNAME record.
   */
  resolveOverride?: string;
}
interface RequestInitCfPropertiesImageDraw extends BasicImageTransformations {
  /**
   * Absolute URL of the image file to use for the drawing. It can be any of
   * the supported file formats. For drawing of watermarks or non-rectangular
   * overlays we recommend using PNG or WebP images.
   */
  url: string;
  /**
   * Floating-point number between 0 (transparent) and 1 (opaque).
   * For example, opacity: 0.5 makes overlay semitransparent.
   */
  opacity?: number;
  /**
   * - If set to true, the overlay image will be tiled to cover the entire
   *   area. This is useful for stock-photo-like watermarks.
   * - If set to "x", the overlay image will be tiled horizontally only
   *   (form a line).
   * - If set to "y", the overlay image will be tiled vertically only
   *   (form a line).
   */
  repeat?: true | 'x' | 'y';
  /**
   * Position of the overlay image relative to a given edge. Each property is
   * an offset in pixels. 0 aligns exactly to the edge. For example, left: 10
   * positions left side of the overlay 10 pixels from the left edge of the
   * image it's drawn over. bottom: 0 aligns bottom of the overlay with bottom
   * of the background image.
   *
   * Setting both left & right, or both top & bottom is an error.
   *
   * If no position is specified, the image will be centered.
   */
  top?: number;
  left?: number;
  bottom?: number;
  right?: number;
}
interface RequestInitCfPropertiesImage extends BasicImageTransformations {
  /**
   * Device Pixel Ratio. Default 1. Multiplier for width/height that makes it
   * easier to specify higher-DPI sizes in <img srcset>.
   */
  dpr?: number;
  /**
   * Allows you to trim your image. Takes dpr into account and is performed before
   * resizing or rotation.
   *
   * It can be used as:
   * - left, top, right, bottom - it will specify the number of pixels to cut
   *   off each side
   * - width, height - the width/height you'd like to end up with - can be used
   *   in combination with the properties above
   * - border - this will automatically trim the surroundings of an image based on
   *   it's color. It consists of three properties:
   *    - color: rgb or hex representation of the color you wish to trim (todo: verify the rgba bit)
   *    - tolerance: difference from color to treat as color
   *    - keep: the number of pixels of border to keep
   */
  trim?:
    | 'border'
    | {
        top?: number;
        bottom?: number;
        left?: number;
        right?: number;
        width?: number;
        height?: number;
        border?:
          | boolean
          | {
              color?: string;
              tolerance?: number;
              keep?: number;
            };
      };
  /**
   * Quality setting from 1-100 (useful values are in 60-90 range). Lower values
   * make images look worse, but load faster. The default is 85. It applies only
   * to JPEG and WebP images. It doesn’t have any effect on PNG.
   */
  quality?: number | 'low' | 'medium-low' | 'medium-high' | 'high';
  /**
   * Output format to generate. It can be:
   *  - avif: generate images in AVIF format.
   *  - webp: generate images in Google WebP format. Set quality to 100 to get
   *    the WebP-lossless format.
   *  - json: instead of generating an image, outputs information about the
   *    image, in JSON format. The JSON object will contain image size
   *    (before and after resizing), source image’s MIME type, file size, etc.
   * - jpeg: generate images in JPEG format.
   * - png: generate images in PNG format.
   */
  format?: 'avif' | 'webp' | 'json' | 'jpeg' | 'png' | 'baseline-jpeg' | 'png-force' | 'svg';
  /**
   * Whether to preserve animation frames from input files. Default is true.
   * Setting it to false reduces animations to still images. This setting is
   * recommended when enlarging images or processing arbitrary user content,
   * because large GIF animations can weigh tens or even hundreds of megabytes.
   * It is also useful to set anim:false when using format:"json" to get the
   * response quicker without the number of frames.
   */
  anim?: boolean;
  /**
   * What EXIF data should be preserved in the output image. Note that EXIF
   * rotation and embedded color profiles are always applied ("baked in" into
   * the image), and aren't affected by this option. Note that if the Polish
   * feature is enabled, all metadata may have been removed already and this
   * option may have no effect.
   *  - keep: Preserve most of EXIF metadata, including GPS location if there's
   *    any.
   *  - copyright: Only keep the copyright tag, and discard everything else.
   *    This is the default behavior for JPEG files.
   *  - none: Discard all invisible EXIF metadata. Currently WebP and PNG
   *    output formats always discard metadata.
   */
  metadata?: 'keep' | 'copyright' | 'none';
  /**
   * Strength of sharpening filter to apply to the image. Floating-point
   * number between 0 (no sharpening, default) and 10 (maximum). 1.0 is a
   * recommended value for downscaled images.
   */
  sharpen?: number;
  /**
   * Radius of a blur filter (approximate gaussian). Maximum supported radius
   * is 250.
   */
  blur?: number;
  /**
   * Overlays are drawn in the order they appear in the array (last array
   * entry is the topmost layer).
   */
  draw?: RequestInitCfPropertiesImageDraw[];
  /**
   * Fetching image from authenticated origin. Setting this property will
   * pass authentication headers (Authorization, Cookie, etc.) through to
   * the origin.
   */
  'origin-auth'?: 'share-publicly';
  /**
   * Adds a border around the image. The border is added after resizing. Border
   * width takes dpr into account, and can be specified either using a single
   * width property, or individually for each side.
   */
  border?:
    | {
        color: string;
        width: number;
      }
    | {
        color: string;
        top: number;
        right: number;
        bottom: number;
        left: number;
      };
  /**
   * Increase brightness by a factor. A value of 1.0 equals no change, a value
   * of 0.5 equals half brightness, and a value of 2.0 equals twice as bright.
   * 0 is ignored.
   */
  brightness?: number;
  /**
   * Increase contrast by a factor. A value of 1.0 equals no change, a value of
   * 0.5 equals low contrast, and a value of 2.0 equals high contrast. 0 is
   * ignored.
   */
  contrast?: number;
  /**
   * Increase exposure by a factor. A value of 1.0 equals no change, a value of
   * 0.5 darkens the image, and a value of 2.0 lightens the image. 0 is ignored.
   */
  gamma?: number;
  /**
   * Increase contrast by a factor. A value of 1.0 equals no change, a value of
   * 0.5 equals low contrast, and a value of 2.0 equals high contrast. 0 is
   * ignored.
   */
  saturation?: number;
  /**
   * Flips the images horizontally, vertically, or both. Flipping is applied before
   * rotation, so if you apply flip=h,rotate=90 then the image will be flipped
   * horizontally, then rotated by 90 degrees.
   */
  flip?: 'h' | 'v' | 'hv';
  /**
   * Slightly reduces latency on a cache miss by selecting a
   * quickest-to-compress file format, at a cost of increased file size and
   * lower image quality. It will usually override the format option and choose
   * JPEG over WebP or AVIF. We do not recommend using this option, except in
   * unusual circumstances like resizing uncacheable dynamically-generated
   * images.
   */
  compression?: 'fast';
}
interface RequestInitCfPropertiesImageMinify {
  javascript?: boolean;
  css?: boolean;
  html?: boolean;
}
interface RequestInitCfPropertiesR2 {
  /**
   * Colo id of bucket that an object is stored in
   */
  bucketColoId?: number;
}
/**
 * Request metadata provided by Cloudflare's edge.
 */
type IncomingRequestCfProperties<HostMetadata = unknown> = IncomingRequestCfPropertiesBase &
  IncomingRequestCfPropertiesBotManagementEnterprise &
  IncomingRequestCfPropertiesCloudflareForSaaSEnterprise<HostMetadata> &
  IncomingRequestCfPropertiesGeographicInformation &
  IncomingRequestCfPropertiesCloudflareAccessOrApiShield;
interface IncomingRequestCfPropertiesBase extends Record<string, unknown> {
  /**
   * [ASN](https://www.iana.org/assignments/as-numbers/as-numbers.xhtml) of the incoming request.
   *
   * @example 395747
   */
  asn: number;
  /**
   * The organization which owns the ASN of the incoming request.
   *
   * @example "Google Cloud"
   */
  asOrganization: string;
  /**
   * The original value of the `Accept-Encoding` header if Cloudflare modified it.
   *
   * @example "gzip, deflate, br"
   */
  clientAcceptEncoding?: string;
  /**
   * The number of milliseconds it took for the request to reach your worker.
   *
   * @example 22
   */
  clientTcpRtt?: number;
  /**
   * The three-letter [IATA](https://en.wikipedia.org/wiki/IATA_airport_code)
   * airport code of the data center that the request hit.
   *
   * @example "DFW"
   */
  colo: string;
  /**
   * Represents the upstream's response to a
   * [TCP `keepalive` message](https://tldp.org/HOWTO/TCP-Keepalive-HOWTO/overview.html)
   * from cloudflare.
   *
   * For workers with no upstream, this will always be `1`.
   *
   * @example 3
   */
  edgeRequestKeepAliveStatus: IncomingRequestCfPropertiesEdgeRequestKeepAliveStatus;
  /**
   * The HTTP Protocol the request used.
   *
   * @example "HTTP/2"
   */
  httpProtocol: string;
  /**
   * The browser-requested prioritization information in the request object.
   *
   * If no information was set, defaults to the empty string `""`
   *
   * @example "weight=192;exclusive=0;group=3;group-weight=127"
   * @default ""
   */
  requestPriority: string;
  /**
   * The TLS version of the connection to Cloudflare.
   * In requests served over plaintext (without TLS), this property is the empty string `""`.
   *
   * @example "TLSv1.3"
   */
  tlsVersion: string;
  /**
   * The cipher for the connection to Cloudflare.
   * In requests served over plaintext (without TLS), this property is the empty string `""`.
   *
   * @example "AEAD-AES128-GCM-SHA256"
   */
  tlsCipher: string;
  /**
   * Metadata containing the [`HELLO`](https://www.rfc-editor.org/rfc/rfc5246#section-7.4.1.2) and [`FINISHED`](https://www.rfc-editor.org/rfc/rfc5246#section-7.4.9) messages from this request's TLS handshake.
   *
   * If the incoming request was served over plaintext (without TLS) this field is undefined.
   */
  tlsExportedAuthenticator?: IncomingRequestCfPropertiesExportedAuthenticatorMetadata;
}
interface IncomingRequestCfPropertiesBotManagementBase {
  /**
   * Cloudflare’s [level of certainty](https://developers.cloudflare.com/bots/concepts/bot-score/) that a request comes from a bot,
   * represented as an integer percentage between `1` (almost certainly a bot) and `99` (almost certainly human).
   *
   * @example 54
   */
  score: number;
  /**
   * A boolean value that is true if the request comes from a good bot, like Google or Bing.
   * Most customers choose to allow this traffic. For more details, see [Traffic from known bots](https://developers.cloudflare.com/firewall/known-issues-and-faq/#how-does-firewall-rules-handle-traffic-from-known-bots).
   */
  verifiedBot: boolean;
  /**
   * A boolean value that is true if the request originates from a
   * Cloudflare-verified proxy service.
   */
  corporateProxy: boolean;
  /**
   * A boolean value that's true if the request matches [file extensions](https://developers.cloudflare.com/bots/reference/static-resources/) for many types of static resources.
   */
  staticResource: boolean;
  /**
   * List of IDs that correlate to the Bot Management heuristic detections made on a request (you can have multiple heuristic detections on the same request).
   */
  detectionIds: number[];
}
interface IncomingRequestCfPropertiesBotManagement {
  /**
   * Results of Cloudflare's Bot Management analysis
   */
  botManagement: IncomingRequestCfPropertiesBotManagementBase;
  /**
   * Duplicate of `botManagement.score`.
   *
   * @deprecated
   */
  clientTrustScore: number;
}
interface IncomingRequestCfPropertiesBotManagementEnterprise extends IncomingRequestCfPropertiesBotManagement {
  /**
   * Results of Cloudflare's Bot Management analysis
   */
  botManagement: IncomingRequestCfPropertiesBotManagementBase & {
    /**
     * A [JA3 Fingerprint](https://developers.cloudflare.com/bots/concepts/ja3-fingerprint/) to help profile specific SSL/TLS clients
     * across different destination IPs, Ports, and X509 certificates.
     */
    ja3Hash: string;
  };
}
interface IncomingRequestCfPropertiesCloudflareForSaaSEnterprise<HostMetadata> {
  /**
   * Custom metadata set per-host in [Cloudflare for SaaS](https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/).
   *
   * This field is only present if you have Cloudflare for SaaS enabled on your account
   * and you have followed the [required steps to enable it]((https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/domain-support/custom-metadata/)).
   */
  hostMetadata: HostMetadata;
}
interface IncomingRequestCfPropertiesCloudflareAccessOrApiShield {
  /**
   * Information about the client certificate presented to Cloudflare.
   *
   * This is populated when the incoming request is served over TLS using
   * either Cloudflare Access or API Shield (mTLS)
   * and the presented SSL certificate has a valid
   * [Certificate Serial Number](https://ldapwiki.com/wiki/Certificate%20Serial%20Number)
   * (i.e., not `null` or `""`).
   *
   * Otherwise, a set of placeholder values are used.
   *
   * The property `certPresented` will be set to `"1"` when
   * the object is populated (i.e. the above conditions were met).
   */
  tlsClientAuth:
    | IncomingRequestCfPropertiesTLSClientAuth
    | IncomingRequestCfPropertiesTLSClientAuthPlaceholder;
}
/**
 * Metadata about the request's TLS handshake
 */
interface IncomingRequestCfPropertiesExportedAuthenticatorMetadata {
  /**
   * The client's [`HELLO` message](https://www.rfc-editor.org/rfc/rfc5246#section-7.4.1.2), encoded in hexadecimal
   *
   * @example "44372ba35fa1270921d318f34c12f155dc87b682cf36a790cfaa3ba8737a1b5d"
   */
  clientHandshake: string;
  /**
   * The server's [`HELLO` message](https://www.rfc-editor.org/rfc/rfc5246#section-7.4.1.2), encoded in hexadecimal
   *
   * @example "44372ba35fa1270921d318f34c12f155dc87b682cf36a790cfaa3ba8737a1b5d"
   */
  serverHandshake: string;
  /**
   * The client's [`FINISHED` message](https://www.rfc-editor.org/rfc/rfc5246#section-7.4.9), encoded in hexadecimal
   *
   * @example "084ee802fe1348f688220e2a6040a05b2199a761f33cf753abb1b006792d3f8b"
   */
  clientFinished: string;
  /**
   * The server's [`FINISHED` message](https://www.rfc-editor.org/rfc/rfc5246#section-7.4.9), encoded in hexadecimal
   *
   * @example "084ee802fe1348f688220e2a6040a05b2199a761f33cf753abb1b006792d3f8b"
   */
  serverFinished: string;
}
/**
 * Geographic data about the request's origin.
 */
interface IncomingRequestCfPropertiesGeographicInformation {
  /**
   * The [ISO 3166-1 Alpha 2](https://www.iso.org/iso-3166-country-codes.html) country code the request originated from.
   *
   * If your worker is [configured to accept TOR connections](https://support.cloudflare.com/hc/en-us/articles/203306930-Understanding-Cloudflare-Tor-support-and-Onion-Routing), this may also be `"T1"`, indicating a request that originated over TOR.
   *
   * If Cloudflare is unable to determine where the request originated this property is omitted.
   *
   * The country code `"T1"` is used for requests originating on TOR.
   *
   * @example "GB"
   */
  country?: Iso3166Alpha2Code | 'T1';
  /**
   * If present, this property indicates that the request originated in the EU
   *
   * @example "1"
   */
  isEUCountry?: '1';
  /**
   * A two-letter code indicating the continent the request originated from.
   *
   * @example "AN"
   */
  continent?: ContinentCode;
  /**
   * The city the request originated from
   *
   * @example "Austin"
   */
  city?: string;
  /**
   * Postal code of the incoming request
   *
   * @example "78701"
   */
  postalCode?: string;
  /**
   * Latitude of the incoming request
   *
   * @example "30.27130"
   */
  latitude?: string;
  /**
   * Longitude of the incoming request
   *
   * @example "-97.74260"
   */
  longitude?: string;
  /**
   * Timezone of the incoming request
   *
   * @example "America/Chicago"
   */
  timezone?: string;
  /**
   * If known, the ISO 3166-2 name for the first level region associated with
   * the IP address of the incoming request
   *
   * @example "Texas"
   */
  region?: string;
  /**
   * If known, the ISO 3166-2 code for the first-level region associated with
   * the IP address of the incoming request
   *
   * @example "TX"
   */
  regionCode?: string;
  /**
   * Metro code (DMA) of the incoming request
   *
   * @example "635"
   */
  metroCode?: string;
}
/** Data about the incoming request's TLS certificate */
interface IncomingRequestCfPropertiesTLSClientAuth {
  /** Always `"1"`, indicating that the certificate was presented */
  certPresented: '1';
  /**
   * Result of certificate verification.
   *
   * @example "FAILED:self signed certificate"
   */
  certVerified: Exclude<CertVerificationStatus, 'NONE'>;
  /** The presented certificate's revokation status.
   *
   * - A value of `"1"` indicates the certificate has been revoked
   * - A value of `"0"` indicates the certificate has not been revoked
   */
  certRevoked: '1' | '0';
  /**
   * The certificate issuer's [distinguished name](https://knowledge.digicert.com/generalinformation/INFO1745.html)
   *
   * @example "CN=cloudflareaccess.com, C=US, ST=Texas, L=Austin, O=Cloudflare"
   */
  certIssuerDN: string;
  /**
   * The certificate subject's [distinguished name](https://knowledge.digicert.com/generalinformation/INFO1745.html)
   *
   * @example "CN=*.cloudflareaccess.com, C=US, ST=Texas, L=Austin, O=Cloudflare"
   */
  certSubjectDN: string;
  /**
   * The certificate issuer's [distinguished name](https://knowledge.digicert.com/generalinformation/INFO1745.html) ([RFC 2253](https://www.rfc-editor.org/rfc/rfc2253.html) formatted)
   *
   * @example "CN=cloudflareaccess.com, C=US, ST=Texas, L=Austin, O=Cloudflare"
   */
  certIssuerDNRFC2253: string;
  /**
   * The certificate subject's [distinguished name](https://knowledge.digicert.com/generalinformation/INFO1745.html) ([RFC 2253](https://www.rfc-editor.org/rfc/rfc2253.html) formatted)
   *
   * @example "CN=*.cloudflareaccess.com, C=US, ST=Texas, L=Austin, O=Cloudflare"
   */
  certSubjectDNRFC2253: string;
  /** The certificate issuer's distinguished name (legacy policies) */
  certIssuerDNLegacy: string;
  /** The certificate subject's distinguished name (legacy policies) */
  certSubjectDNLegacy: string;
  /**
   * The certificate's serial number
   *
   * @example "00936EACBE07F201DF"
   */
  certSerial: string;
  /**
   * The certificate issuer's serial number
   *
   * @example "2489002934BDFEA34"
   */
  certIssuerSerial: string;
  /**
   * The certificate's Subject Key Identifier
   *
   * @example "BB:AF:7E:02:3D:FA:A6:F1:3C:84:8E:AD:EE:38:98:EC:D9:32:32:D4"
   */
  certSKI: string;
  /**
   * The certificate issuer's Subject Key Identifier
   *
   * @example "BB:AF:7E:02:3D:FA:A6:F1:3C:84:8E:AD:EE:38:98:EC:D9:32:32:D4"
   */
  certIssuerSKI: string;
  /**
   * The certificate's SHA-1 fingerprint
   *
   * @example "6b9109f323999e52259cda7373ff0b4d26bd232e"
   */
  certFingerprintSHA1: string;
  /**
   * The certificate's SHA-256 fingerprint
   *
   * @example "acf77cf37b4156a2708e34c4eb755f9b5dbbe5ebb55adfec8f11493438d19e6ad3f157f81fa3b98278453d5652b0c1fd1d71e5695ae4d709803a4d3f39de9dea"
   */
  certFingerprintSHA256: string;
  /**
   * The effective starting date of the certificate
   *
   * @example "Dec 22 19:39:00 2018 GMT"
   */
  certNotBefore: string;
  /**
   * The effective expiration date of the certificate
   *
   * @example "Dec 22 19:39:00 2018 GMT"
   */
  certNotAfter: string;
}
/** Placeholder values for TLS Client Authorization */
interface IncomingRequestCfPropertiesTLSClientAuthPlaceholder {
  certPresented: '0';
  certVerified: 'NONE';
  certRevoked: '0';
  certIssuerDN: '';
  certSubjectDN: '';
  certIssuerDNRFC2253: '';
  certSubjectDNRFC2253: '';
  certIssuerDNLegacy: '';
  certSubjectDNLegacy: '';
  certSerial: '';
  certIssuerSerial: '';
  certSKI: '';
  certIssuerSKI: '';
  certFingerprintSHA1: '';
  certFingerprintSHA256: '';
  certNotBefore: '';
  certNotAfter: '';
}
/** Possible outcomes of TLS verification */
declare type CertVerificationStatus =
  /** Authentication succeeded */
  | 'SUCCESS'
  /** No certificate was presented */
  | 'NONE'
  /** Failed because the certificate was self-signed */
  | 'FAILED:self signed certificate'
  /** Failed because the certificate failed a trust chain check */
  | 'FAILED:unable to verify the first certificate'
  /** Failed because the certificate not yet valid */
  | 'FAILED:certificate is not yet valid'
  /** Failed because the certificate is expired */
  | 'FAILED:certificate has expired'
  /** Failed for another unspecified reason */
  | 'FAILED';
/**
 * An upstream endpoint's response to a TCP `keepalive` message from Cloudflare.
 */
declare type IncomingRequestCfPropertiesEdgeRequestKeepAliveStatus =
  | 0 /** Unknown */
  | 1 /** no keepalives (not found) */
  | 2 /** no connection re-use, opening keepalive connection failed */
  | 3 /** no connection re-use, keepalive accepted and saved */
  | 4 /** connection re-use, refused by the origin server (`TCP FIN`) */
  | 5; /** connection re-use, accepted by the origin server */
/** ISO 3166-1 Alpha-2 codes */
declare type Iso3166Alpha2Code =
  | 'AD'
  | 'AE'
  | 'AF'
  | 'AG'
  | 'AI'
  | 'AL'
  | 'AM'
  | 'AO'
  | 'AQ'
  | 'AR'
  | 'AS'
  | 'AT'
  | 'AU'
  | 'AW'
  | 'AX'
  | 'AZ'
  | 'BA'
  | 'BB'
  | 'BD'
  | 'BE'
  | 'BF'
  | 'BG'
  | 'BH'
  | 'BI'
  | 'BJ'
  | 'BL'
  | 'BM'
  | 'BN'
  | 'BO'
  | 'BQ'
  | 'BR'
  | 'BS'
  | 'BT'
  | 'BV'
  | 'BW'
  | 'BY'
  | 'BZ'
  | 'CA'
  | 'CC'
  | 'CD'
  | 'CF'
  | 'CG'
  | 'CH'
  | 'CI'
  | 'CK'
  | 'CL'
  | 'CM'
  | 'CN'
  | 'CO'
  | 'CR'
  | 'CU'
  | 'CV'
  | 'CW'
  | 'CX'
  | 'CY'
  | 'CZ'
  | 'DE'
  | 'DJ'
  | 'DK'
  | 'DM'
  | 'DO'
  | 'DZ'
  | 'EC'
  | 'EE'
  | 'EG'
  | 'EH'
  | 'ER'
  | 'ES'
  | 'ET'
  | 'FI'
  | 'FJ'
  | 'FK'
  | 'FM'
  | 'FO'
  | 'FR'
  | 'GA'
  | 'GB'
  | 'GD'
  | 'GE'
  | 'GF'
  | 'GG'
  | 'GH'
  | 'GI'
  | 'GL'
  | 'GM'
  | 'GN'
  | 'GP'
  | 'GQ'
  | 'GR'
  | 'GS'
  | 'GT'
  | 'GU'
  | 'GW'
  | 'GY'
  | 'HK'
  | 'HM'
  | 'HN'
  | 'HR'
  | 'HT'
  | 'HU'
  | 'ID'
  | 'IE'
  | 'IL'
  | 'IM'
  | 'IN'
  | 'IO'
  | 'IQ'
  | 'IR'
  | 'IS'
  | 'IT'
  | 'JE'
  | 'JM'
  | 'JO'
  | 'JP'
  | 'KE'
  | 'KG'
  | 'KH'
  | 'KI'
  | 'KM'
  | 'KN'
  | 'KP'
  | 'KR'
  | 'KW'
  | 'KY'
  | 'KZ'
  | 'LA'
  | 'LB'
  | 'LC'
  | 'LI'
  | 'LK'
  | 'LR'
  | 'LS'
  | 'LT'
  | 'LU'
  | 'LV'
  | 'LY'
  | 'MA'
  | 'MC'
  | 'MD'
  | 'ME'
  | 'MF'
  | 'MG'
  | 'MH'
  | 'MK'
  | 'ML'
  | 'MM'
  | 'MN'
  | 'MO'
  | 'MP'
  | 'MQ'
  | 'MR'
  | 'MS'
  | 'MT'
  | 'MU'
  | 'MV'
  | 'MW'
  | 'MX'
  | 'MY'
  | 'MZ'
  | 'NA'
  | 'NC'
  | 'NE'
  | 'NF'
  | 'NG'
  | 'NI'
  | 'NL'
  | 'NO'
  | 'NP'
  | 'NR'
  | 'NU'
  | 'NZ'
  | 'OM'
  | 'PA'
  | 'PE'
  | 'PF'
  | 'PG'
  | 'PH'
  | 'PK'
  | 'PL'
  | 'PM'
  | 'PN'
  | 'PR'
  | 'PS'
  | 'PT'
  | 'PW'
  | 'PY'
  | 'QA'
  | 'RE'
  | 'RO'
  | 'RS'
  | 'RU'
  | 'RW'
  | 'SA'
  | 'SB'
  | 'SC'
  | 'SD'
  | 'SE'
  | 'SG'
  | 'SH'
  | 'SI'
  | 'SJ'
  | 'SK'
  | 'SL'
  | 'SM'
  | 'SN'
  | 'SO'
  | 'SR'
  | 'SS'
  | 'ST'
  | 'SV'
  | 'SX'
  | 'SY'
  | 'SZ'
  | 'TC'
  | 'TD'
  | 'TF'
  | 'TG'
  | 'TH'
  | 'TJ'
  | 'TK'
  | 'TL'
  | 'TM'
  | 'TN'
  | 'TO'
  | 'TR'
  | 'TT'
  | 'TV'
  | 'TW'
  | 'TZ'
  | 'UA'
  | 'UG'
  | 'UM'
  | 'US'
  | 'UY'
  | 'UZ'
  | 'VA'
  | 'VC'
  | 'VE'
  | 'VG'
  | 'VI'
  | 'VN'
  | 'VU'
  | 'WF'
  | 'WS'
  | 'YE'
  | 'YT'
  | 'ZA'
  | 'ZM'
  | 'ZW';
/** The 2-letter continent codes Cloudflare uses */
declare type ContinentCode = 'AF' | 'AN' | 'AS' | 'EU' | 'NA' | 'OC' | 'SA';
type CfProperties<HostMetadata = unknown> =
  | IncomingRequestCfProperties<HostMetadata>
  | RequestInitCfProperties;
interface D1Meta {
  duration: number;
  size_after: number;
  rows_read: number;
  rows_written: number;
  last_row_id: number;
  changed_db: boolean;
  changes: number;
  /**
   * The region of the database instance that executed the query.
   */
  served_by_region?: string;
  /**
   * True if-and-only-if the database instance that executed the query was the primary.
   */
  served_by_primary?: boolean;
  timings?: {
    /**
     * The duration of the SQL query execution by the database instance. It doesn't include any network time.
     */
    sql_duration_ms: number;
  };
}
interface D1Response {
  success: true;
  meta: D1Meta & Record<string, unknown>;
  error?: never;
}
type D1Result<T = unknown> = D1Response & {
  results: T[];
};
interface D1ExecResult {
  count: number;
  duration: number;
}
type D1SessionConstraint =
  // Indicates that the first query should go to the primary, and the rest queries
  // using the same D1DatabaseSession will go to any replica that is consistent with
  // the bookmark maintained by the session (returned by the first query).
  | 'first-primary'
  // Indicates that the first query can go anywhere (primary or replica), and the rest queries
  // using the same D1DatabaseSession will go to any replica that is consistent with
  // the bookmark maintained by the session (returned by the first query).
  | 'first-unconstrained';
type D1SessionBookmark = string;
declare abstract class D1Database {
  prepare(query: string): D1PreparedStatement;
  batch<T = unknown>(statements: D1PreparedStatement[]): Promise<D1Result<T>[]>;
  exec(query: string): Promise<D1ExecResult>;
  /**
   * Creates a new D1 Session anchored at the given constraint or the bookmark.
   * All queries executed using the created session will have sequential consistency,
   * meaning that all writes done through the session will be visible in subsequent reads.
   *
   * @param constraintOrBookmark Either the session constraint or the explicit bookmark to anchor the created session.
   */
  withSession(constraintOrBookmark?: D1SessionBookmark | D1SessionConstraint): D1DatabaseSession;
  /**
   * @deprecated dump() will be removed soon, only applies to deprecated alpha v1 databases.
   */
  dump(): Promise<ArrayBuffer>;
}
declare abstract class D1DatabaseSession {
  prepare(query: string): D1PreparedStatement;
  batch<T = unknown>(statements: D1PreparedStatement[]): Promise<D1Result<T>[]>;
  /**
   * @returns The latest session bookmark across all executed queries on the session.
   *          If no query has been executed yet, `null` is returned.
   */
  getBookmark(): D1SessionBookmark | null;
}
declare abstract class D1PreparedStatement {
  bind(...values: unknown[]): D1PreparedStatement;
  first<T = unknown>(colName: string): Promise<T | null>;
  first<T = Record<string, unknown>>(): Promise<T | null>;
  run<T = Record<string, unknown>>(): Promise<D1Result<T>>;
  all<T = Record<string, unknown>>(): Promise<D1Result<T>>;
  raw<T = unknown[]>(options: { columnNames: true }): Promise<[string[], ...T[]]>;
  raw<T = unknown[]>(options?: { columnNames?: false }): Promise<T[]>;
}
// `Disposable` was added to TypeScript's standard lib types in version 5.2.
// To support older TypeScript versions, define an empty `Disposable` interface.
// Users won't be able to use `using`/`Symbol.dispose` without upgrading to 5.2,
// but this will ensure type checking on older versions still passes.
// TypeScript's interface merging will ensure our empty interface is effectively
// ignored when `Disposable` is included in the standard lib.
interface Disposable {}
/**
 * An email message that can be sent from a Worker.
 */
interface EmailMessage {
  /**
   * Envelope From attribute of the email message.
   */
  readonly from: string;
  /**
   * Envelope To attribute of the email message.
   */
  readonly to: string;
}
/**
 * An email message that is sent to a consumer Worker and can be rejected/forwarded.
 */
interface ForwardableEmailMessage extends EmailMessage {
  /**
   * Stream of the email message content.
   */
  readonly raw: ReadableStream<Uint8Array>;
  /**
   * An [Headers object](https://developer.mozilla.org/en-US/docs/Web/API/Headers).
   */
  readonly headers: Headers;
  /**
   * Size of the email message content.
   */
  readonly rawSize: number;
  /**
   * Reject this email message by returning a permanent SMTP error back to the connecting client including the given reason.
   * @param reason The reject reason.
   * @returns void
   */
  setReject(reason: string): void;
  /**
   * Forward this email message to a verified destination address of the account.
   * @param rcptTo Verified destination address.
   * @param headers A [Headers object](https://developer.mozilla.org/en-US/docs/Web/API/Headers).
   * @returns A promise that resolves when the email message is forwarded.
   */
  forward(rcptTo: string, headers?: Headers): Promise<void>;
  /**
   * Reply to the sender of this email message with a new EmailMessage object.
   * @param message The reply message.
   * @returns A promise that resolves when the email message is replied.
   */
  reply(message: EmailMessage): Promise<void>;
}
/**
 * A binding that allows a Worker to send email messages.
 */
interface SendEmail {
  send(message: EmailMessage): Promise<void>;
}
declare abstract class EmailEvent extends ExtendableEvent {
  readonly message: ForwardableEmailMessage;
}
declare type EmailExportedHandler<Env = unknown> = (
  message: ForwardableEmailMessage,
  env: Env,
  ctx: ExecutionContext,
) => void | Promise<void>;
declare module 'cloudflare:email' {
  let _EmailMessage: {
    prototype: EmailMessage;
    new (from: string, to: string, raw: ReadableStream | string): EmailMessage;
  };
  export { _EmailMessage as EmailMessage };
}
interface Hyperdrive {
  /**
   * Connect directly to Hyperdrive as if it's your database, returning a TCP socket.
   *
   * Calling this method returns an idential socket to if you call
   * `connect("host:port")` using the `host` and `port` fields from this object.
   * Pick whichever approach works better with your preferred DB client library.
   *
   * Note that this socket is not yet authenticated -- it's expected that your
   * code (or preferably, the client library of your choice) will authenticate
   * using the information in this class's readonly fields.
   */
  connect(): Socket;
  /**
   * A valid DB connection string that can be passed straight into the typical
   * client library/driver/ORM. This will typically be the easiest way to use
   * Hyperdrive.
   */
  readonly connectionString: string;
  /*
   * A randomly generated hostname that is only valid within the context of the
   * currently running Worker which, when passed into `connect()` function from
   * the "cloudflare:sockets" module, will connect to the Hyperdrive instance
   * for your database.
   */
  readonly host: string;
  /*
   * The port that must be paired the the host field when connecting.
   */
  readonly port: number;
  /*
   * The username to use when authenticating to your database via Hyperdrive.
   * Unlike the host and password, this will be the same every time
   */
  readonly user: string;
  /*
   * The randomly generated password to use when authenticating to your
   * database via Hyperdrive. Like the host field, this password is only valid
   * within the context of the currently running Worker instance from which
   * it's read.
   */
  readonly password: string;
  /*
   * The name of the database to connect to.
   */
  readonly database: string;
}
// Copyright (c) 2024 Cloudflare, Inc.
// Licensed under the Apache 2.0 license found in the LICENSE file or at:
//     https://opensource.org/licenses/Apache-2.0
type ImageInfoResponse =
  | {
      format: 'image/svg+xml';
    }
  | {
      format: string;
      fileSize: number;
      width: number;
      height: number;
    };
type ImageTransform = {
  width?: number;
  height?: number;
  background?: string;
  blur?: number;
  border?:
    | {
        color?: string;
        width?: number;
      }
    | {
        top?: number;
        bottom?: number;
        left?: number;
        right?: number;
      };
  brightness?: number;
  contrast?: number;
  fit?: 'scale-down' | 'contain' | 'pad' | 'squeeze' | 'cover' | 'crop';
  flip?: 'h' | 'v' | 'hv';
  gamma?: number;
  gravity?:
    | 'left'
    | 'right'
    | 'top'
    | 'bottom'
    | 'center'
    | 'auto'
    | 'entropy'
    | {
        x?: number;
        y?: number;
        mode: 'remainder' | 'box-center';
      };
  rotate?: 0 | 90 | 180 | 270;
  saturation?: number;
  sharpen?: number;
  trim?:
    | 'border'
    | {
        top?: number;
        bottom?: number;
        left?: number;
        right?: number;
        width?: number;
        height?: number;
        border?:
          | boolean
          | {
              color?: string;
              tolerance?: number;
              keep?: number;
            };
      };
};
type ImageDrawOptions = {
  opacity?: number;
  repeat?: boolean | string;
  top?: number;
  left?: number;
  bottom?: number;
  right?: number;
};
type ImageOutputOptions = {
  format: 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp' | 'image/avif' | 'rgb' | 'rgba';
  quality?: number;
  background?: string;
};
interface ImagesBinding {
  /**
   * Get image metadata (type, width and height)
   * @throws {@link ImagesError} with code 9412 if input is not an image
   * @param stream The image bytes
   */
  info(stream: ReadableStream<Uint8Array>): Promise<ImageInfoResponse>;
  /**
   * Begin applying a series of transformations to an image
   * @param stream The image bytes
   * @returns A transform handle
   */
  input(stream: ReadableStream<Uint8Array>): ImageTransformer;
}
interface ImageTransformer {
  /**
   * Apply transform next, returning a transform handle.
   * You can then apply more transformations, draw, or retrieve the output.
   * @param transform
   */
  transform(transform: ImageTransform): ImageTransformer;
  /**
   * Draw an image on this transformer, returning a transform handle.
   * You can then apply more transformations, draw, or retrieve the output.
   * @param image The image (or transformer that will give the image) to draw
   * @param options The options configuring how to draw the image
   */
  draw(
    image: ReadableStream<Uint8Array> | ImageTransformer,
    options?: ImageDrawOptions,
  ): ImageTransformer;
  /**
   * Retrieve the image that results from applying the transforms to the
   * provided input
   * @param options Options that apply to the output e.g. output format
   */
  output(options: ImageOutputOptions): Promise<ImageTransformationResult>;
}
interface ImageTransformationResult {
  /**
   * The image as a response, ready to store in cache or return to users
   */
  response(): Response;
  /**
   * The content type of the returned image
   */
  contentType(): string;
  /**
   * The bytes of the response
   */
  image(): ReadableStream<Uint8Array>;
}
interface ImagesError extends Error {
  readonly code: number;
  readonly message: string;
  readonly stack?: string;
}
type Params<P extends string = any> = Record<P, string | string[]>;
type EventContext<Env, P extends string, Data> = {
  request: Request<unknown, IncomingRequestCfProperties<unknown>>;
  functionPath: string;
  waitUntil: (promise: Promise<any>) => void;
  passThroughOnException: () => void;
  next: (input?: Request | string, init?: RequestInit) => Promise<Response>;
  env: Env & {
    ASSETS: {
      fetch: typeof fetch;
    };
  };
  params: Params<P>;
  data: Data;
};
type PagesFunction<
  Env = unknown,
  Params extends string = any,
  Data extends Record<string, unknown> = Record<string, unknown>,
> = (context: EventContext<Env, Params, Data>) => Response | Promise<Response>;
type EventPluginContext<Env, P extends string, Data, PluginArgs> = {
  request: Request<unknown, IncomingRequestCfProperties<unknown>>;
  functionPath: string;
  waitUntil: (promise: Promise<any>) => void;
  passThroughOnException: () => void;
  next: (input?: Request | string, init?: RequestInit) => Promise<Response>;
  env: Env & {
    ASSETS: {
      fetch: typeof fetch;
    };
  };
  params: Params<P>;
  data: Data;
  pluginArgs: PluginArgs;
};
type PagesPluginFunction<
  Env = unknown,
  Params extends string = any,
  Data extends Record<string, unknown> = Record<string, unknown>,
  PluginArgs = unknown,
> = (context: EventPluginContext<Env, Params, Data, PluginArgs>) => Response | Promise<Response>;
declare module 'assets:*' {
  export const onRequest: PagesFunction;
}
// Copyright (c) 2022-2023 Cloudflare, Inc.
// Licensed under the Apache 2.0 license found in the LICENSE file or at:
//     https://opensource.org/licenses/Apache-2.0
declare module 'cloudflare:pipelines' {
  export abstract class PipelineTransformationEntrypoint<
    Env = unknown,
    I extends PipelineRecord = PipelineRecord,
    O extends PipelineRecord = PipelineRecord,
  > {
    protected env: Env;
    protected ctx: ExecutionContext;
    constructor(ctx: ExecutionContext, env: Env);
    /**
     * run recieves an array of PipelineRecord which can be
     * transformed and returned to the pipeline
     * @param records Incoming records from the pipeline to be transformed
     * @param metadata Information about the specific pipeline calling the transformation entrypoint
     * @returns A promise containing the transformed PipelineRecord array
     */
    public run(records: I[], metadata: PipelineBatchMetadata): Promise<O[]>;
  }
  export type PipelineRecord = Record<string, unknown>;
  export type PipelineBatchMetadata = {
    pipelineId: string;
    pipelineName: string;
  };
  export interface Pipeline<T extends PipelineRecord = PipelineRecord> {
    /**
     * The Pipeline interface represents the type of a binding to a Pipeline
     *
     * @param records The records to send to the pipeline
     */
    send(records: T[]): Promise<void>;
  }
}
// PubSubMessage represents an incoming PubSub message.
// The message includes metadata about the broker, the client, and the payload
// itself.
// https://developers.cloudflare.com/pub-sub/
interface PubSubMessage {
  // Message ID
  readonly mid: number;
  // MQTT broker FQDN in the form mqtts://BROKER.NAMESPACE.cloudflarepubsub.com:PORT
  readonly broker: string;
  // The MQTT topic the message was sent on.
  readonly topic: string;
  // The client ID of the client that published this message.
  readonly clientId: string;
  // The unique identifier (JWT ID) used by the client to authenticate, if token
  // auth was used.
  readonly jti?: string;
  // A Unix timestamp (seconds from Jan 1, 1970), set when the Pub/Sub Broker
  // received the message from the client.
  readonly receivedAt: number;
  // An (optional) string with the MIME type of the payload, if set by the
  // client.
  readonly contentType: string;
  // Set to 1 when the payload is a UTF-8 string
  // https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901063
  readonly payloadFormatIndicator: number;
  // Pub/Sub (MQTT) payloads can be UTF-8 strings, or byte arrays.
  // You can use payloadFormatIndicator to inspect this before decoding.
  payload: string | Uint8Array;
}
// JsonWebKey extended by kid parameter
interface JsonWebKeyWithKid extends JsonWebKey {
  // Key Identifier of the JWK
  readonly kid: string;
}
interface RateLimitOptions {
  key: string;
}
interface RateLimitOutcome {
  success: boolean;
}
interface RateLimit {
  /**
   * Rate limit a request based on the provided options.
   * @see https://developers.cloudflare.com/workers/runtime-apis/bindings/rate-limit/
   * @returns A promise that resolves with the outcome of the rate limit.
   */
  limit(options: RateLimitOptions): Promise<RateLimitOutcome>;
}
// Namespace for RPC utility types. Unfortunately, we can't use a `module` here as these types need
// to referenced by `Fetcher`. This is included in the "importable" version of the types which
// strips all `module` blocks.
declare namespace Rpc {
  // Branded types for identifying `WorkerEntrypoint`/`DurableObject`/`Target`s.
  // TypeScript uses *structural* typing meaning anything with the same shape as type `T` is a `T`.
  // For the classes exported by `cloudflare:workers` we want *nominal* typing (i.e. we only want to
  // accept `WorkerEntrypoint` from `cloudflare:workers`, not any other class with the same shape)
  export const __RPC_STUB_BRAND: '__RPC_STUB_BRAND';
  export const __RPC_TARGET_BRAND: '__RPC_TARGET_BRAND';
  export const __WORKER_ENTRYPOINT_BRAND: '__WORKER_ENTRYPOINT_BRAND';
  export const __DURABLE_OBJECT_BRAND: '__DURABLE_OBJECT_BRAND';
  export const __WORKFLOW_ENTRYPOINT_BRAND: '__WORKFLOW_ENTRYPOINT_BRAND';
  export interface RpcTargetBranded {
    [__RPC_TARGET_BRAND]: never;
  }
  export interface WorkerEntrypointBranded {
    [__WORKER_ENTRYPOINT_BRAND]: never;
  }
  export interface DurableObjectBranded {
    [__DURABLE_OBJECT_BRAND]: never;
  }
  export interface WorkflowEntrypointBranded {
    [__WORKFLOW_ENTRYPOINT_BRAND]: never;
  }
  export type EntrypointBranded =
    | WorkerEntrypointBranded
    | DurableObjectBranded
    | WorkflowEntrypointBranded;
  // Types that can be used through `Stub`s
  export type Stubable = RpcTargetBranded | ((...args: any[]) => any);
  // Types that can be passed over RPC
  // The reason for using a generic type here is to build a serializable subset of structured
  //   cloneable composite types. This allows types defined with the "interface" keyword to pass the
  //   serializable check as well. Otherwise, only types defined with the "type" keyword would pass.
  type Serializable<T> =
    // Structured cloneables
    | BaseType
    // Structured cloneable composites
    | Map<
        T extends Map<infer U, unknown> ? Serializable<U> : never,
        T extends Map<unknown, infer U> ? Serializable<U> : never
      >
    | Set<T extends Set<infer U> ? Serializable<U> : never>
    | ReadonlyArray<T extends ReadonlyArray<infer U> ? Serializable<U> : never>
    | {
        [K in keyof T]: K extends number | string ? Serializable<T[K]> : never;
      }
    // Special types
    | Stub<Stubable>
    // Serialized as stubs, see `Stubify`
    | Stubable;
  // Base type for all RPC stubs, including common memory management methods.
  // `T` is used as a marker type for unwrapping `Stub`s later.
  interface StubBase<T extends Stubable> extends Disposable {
    [__RPC_STUB_BRAND]: T;
    dup(): this;
  }
  export type Stub<T extends Stubable> = Provider<T> & StubBase<T>;
  // This represents all the types that can be sent as-is over an RPC boundary
  type BaseType =
    | void
    | undefined
    | null
    | boolean
    | number
    | bigint
    | string
    | TypedArray
    | ArrayBuffer
    | DataView
    | Date
    | Error
    | RegExp
    | ReadableStream<Uint8Array>
    | WritableStream<Uint8Array>
    | Request
    | Response
    | Headers;
  // Recursively rewrite all `Stubable` types with `Stub`s
  // prettier-ignore
  type Stubify<T> = T extends Stubable ? Stub<T> : T extends Map<infer K, infer V> ? Map<Stubify<K>, Stubify<V>> : T extends Set<infer V> ? Set<Stubify<V>> : T extends Array<infer V> ? Array<Stubify<V>> : T extends ReadonlyArray<infer V> ? ReadonlyArray<Stubify<V>> : T extends BaseType ? T : T extends {
        [key: string | number]: any;
    } ? {
        [K in keyof T]: Stubify<T[K]>;
    } : T;
  // Recursively rewrite all `Stub<T>`s with the corresponding `T`s.
  // Note we use `StubBase` instead of `Stub` here to avoid circular dependencies:
  // `Stub` depends on `Provider`, which depends on `Unstubify`, which would depend on `Stub`.
  // prettier-ignore
  type Unstubify<T> = T extends StubBase<infer V> ? V : T extends Map<infer K, infer V> ? Map<Unstubify<K>, Unstubify<V>> : T extends Set<infer V> ? Set<Unstubify<V>> : T extends Array<infer V> ? Array<Unstubify<V>> : T extends ReadonlyArray<infer V> ? ReadonlyArray<Unstubify<V>> : T extends BaseType ? T : T extends {
        [key: string | number]: unknown;
    } ? {
        [K in keyof T]: Unstubify<T[K]>;
    } : T;
  type UnstubifyAll<A extends any[]> = {
    [I in keyof A]: Unstubify<A[I]>;
  };
  // Utility type for adding `Provider`/`Disposable`s to `object` types only.
  // Note `unknown & T` is equivalent to `T`.
  type MaybeProvider<T> = T extends object ? Provider<T> : unknown;
  type MaybeDisposable<T> = T extends object ? Disposable : unknown;
  // Type for method return or property on an RPC interface.
  // - Stubable types are replaced by stubs.
  // - Serializable types are passed by value, with stubable types replaced by stubs
  //   and a top-level `Disposer`.
  // Everything else can't be passed over PRC.
  // Technically, we use custom thenables here, but they quack like `Promise`s.
  // Intersecting with `(Maybe)Provider` allows pipelining.
  // prettier-ignore
  type Result<R> = R extends Stubable ? Promise<Stub<R>> & Provider<R> : R extends Serializable<R> ? Promise<Stubify<R> & MaybeDisposable<R>> & MaybeProvider<R> : never;
  // Type for method or property on an RPC interface.
  // For methods, unwrap `Stub`s in parameters, and rewrite returns to be `Result`s.
  // Unwrapping `Stub`s allows calling with `Stubable` arguments.
  // For properties, rewrite types to be `Result`s.
  // In each case, unwrap `Promise`s.
  type MethodOrProperty<V> = V extends (...args: infer P) => infer R
    ? (...args: UnstubifyAll<P>) => Result<Awaited<R>>
    : Result<Awaited<V>>;
  // Type for the callable part of an `Provider` if `T` is callable.
  // This is intersected with methods/properties.
  type MaybeCallableProvider<T> = T extends (...args: any[]) => any ? MethodOrProperty<T> : unknown;
  // Base type for all other types providing RPC-like interfaces.
  // Rewrites all methods/properties to be `MethodOrProperty`s, while preserving callable types.
  // `Reserved` names (e.g. stub method names like `dup()`) and symbols can't be accessed over RPC.
  export type Provider<
    T extends object,
    Reserved extends string = never,
  > = MaybeCallableProvider<T> & {
    [K in Exclude<keyof T, Reserved | symbol | keyof StubBase<never>>]: MethodOrProperty<T[K]>;
  };
}
declare namespace Cloudflare {
  interface Env {}
}
declare module 'cloudflare:workers' {
  export type RpcStub<T extends Rpc.Stubable> = Rpc.Stub<T>;
  export const RpcStub: {
    new <T extends Rpc.Stubable>(value: T): Rpc.Stub<T>;
  };
  export abstract class RpcTarget implements Rpc.RpcTargetBranded {
    [Rpc.__RPC_TARGET_BRAND]: never;
  }
  // `protected` fields don't appear in `keyof`s, so can't be accessed over RPC
  export abstract class WorkerEntrypoint<Env = unknown> implements Rpc.WorkerEntrypointBranded {
    [Rpc.__WORKER_ENTRYPOINT_BRAND]: never;
    protected ctx: ExecutionContext;
    protected env: Env;
    constructor(ctx: ExecutionContext, env: Env);
    fetch?(request: Request): Response | Promise<Response>;
    tail?(events: TraceItem[]): void | Promise<void>;
    trace?(traces: TraceItem[]): void | Promise<void>;
    scheduled?(controller: ScheduledController): void | Promise<void>;
    queue?(batch: MessageBatch<unknown>): void | Promise<void>;
    test?(controller: TestController): void | Promise<void>;
  }
  export abstract class DurableObject<Env = unknown> implements Rpc.DurableObjectBranded {
    [Rpc.__DURABLE_OBJECT_BRAND]: never;
    protected ctx: DurableObjectState;
    protected env: Env;
    constructor(ctx: DurableObjectState, env: Env);
    fetch?(request: Request): Response | Promise<Response>;
    alarm?(alarmInfo?: AlarmInvocationInfo): void | Promise<void>;
    webSocketMessage?(ws: WebSocket, message: string | ArrayBuffer): void | Promise<void>;
    webSocketClose?(
      ws: WebSocket,
      code: number,
      reason: string,
      wasClean: boolean,
    ): void | Promise<void>;
    webSocketError?(ws: WebSocket, error: unknown): void | Promise<void>;
  }
  export type WorkflowDurationLabel =
    | 'second'
    | 'minute'
    | 'hour'
    | 'day'
    | 'week'
    | 'month'
    | 'year';
  export type WorkflowSleepDuration = `${number} ${WorkflowDurationLabel}${'s' | ''}` | number;
  export type WorkflowDelayDuration = WorkflowSleepDuration;
  export type WorkflowTimeoutDuration = WorkflowSleepDuration;
  export type WorkflowBackoff = 'constant' | 'linear' | 'exponential';
  export type WorkflowStepConfig = {
    retries?: {
      limit: number;
      delay: WorkflowDelayDuration | number;
      backoff?: WorkflowBackoff;
    };
    timeout?: WorkflowTimeoutDuration | number;
  };
  export type WorkflowEvent<T> = {
    payload: Readonly<T>;
    timestamp: Date;
    instanceId: string;
  };
  export type WorkflowStepEvent<T> = {
    payload: Readonly<T>;
    timestamp: Date;
    type: string;
  };
  export abstract class WorkflowStep {
    do<T extends Rpc.Serializable<T>>(name: string, callback: () => Promise<T>): Promise<T>;
    do<T extends Rpc.Serializable<T>>(
      name: string,
      config: WorkflowStepConfig,
      callback: () => Promise<T>,
    ): Promise<T>;
    sleep: (name: string, duration: WorkflowSleepDuration) => Promise<void>;
    sleepUntil: (name: string, timestamp: Date | number) => Promise<void>;
    waitForEvent<T extends Rpc.Serializable<T>>(
      name: string,
      options: {
        type: string;
        timeout?: WorkflowTimeoutDuration | number;
      },
    ): Promise<WorkflowStepEvent<T>>;
  }
  export abstract class WorkflowEntrypoint<
    Env = unknown,
    T extends Rpc.Serializable<T> | unknown = unknown,
  >
    implements Rpc.WorkflowEntrypointBranded
  {
    [Rpc.__WORKFLOW_ENTRYPOINT_BRAND]: never;
    protected ctx: ExecutionContext;
    protected env: Env;
    constructor(ctx: ExecutionContext, env: Env);
    run(event: Readonly<WorkflowEvent<T>>, step: WorkflowStep): Promise<unknown>;
  }
  export const env: Cloudflare.Env;
}
interface SecretsStoreSecret {
  /**
   * Get a secret from the Secrets Store, returning a string of the secret value
   * if it exists, or throws an error if it does not exist
   */
  get(): Promise<string>;
}
declare module 'cloudflare:sockets' {
  function _connect(address: string | SocketAddress, options?: SocketOptions): Socket;
  export { _connect as connect };
}
declare namespace TailStream {
  interface Header {
    readonly name: string;
    readonly value: string;
  }
  interface FetchEventInfo {
    readonly type: 'fetch';
    readonly method: string;
    readonly url: string;
    readonly cfJson: string;
    readonly headers: Header[];
  }
  interface JsRpcEventInfo {
    readonly type: 'jsrpc';
    readonly methodName: string;
  }
  interface ScheduledEventInfo {
    readonly type: 'scheduled';
    readonly scheduledTime: Date;
    readonly cron: string;
  }
  interface AlarmEventInfo {
    readonly type: 'alarm';
    readonly scheduledTime: Date;
  }
  interface QueueEventInfo {
    readonly type: 'queue';
    readonly queueName: string;
    readonly batchSize: number;
  }
  interface EmailEventInfo {
    readonly type: 'email';
    readonly mailFrom: string;
    readonly rcptTo: string;
    readonly rawSize: number;
  }
  interface TraceEventInfo {
    readonly type: 'trace';
    readonly traces: (string | null)[];
  }
  interface HibernatableWebSocketEventInfoMessage {
    readonly type: 'message';
  }
  interface HibernatableWebSocketEventInfoError {
    readonly type: 'error';
  }
  interface HibernatableWebSocketEventInfoClose {
    readonly type: 'close';
    readonly code: number;
    readonly wasClean: boolean;
  }
  interface HibernatableWebSocketEventInfo {
    readonly type: 'hibernatableWebSocket';
    readonly info:
      | HibernatableWebSocketEventInfoClose
      | HibernatableWebSocketEventInfoError
      | HibernatableWebSocketEventInfoMessage;
  }
  interface Resume {
    readonly type: 'resume';
    readonly attachment?: any;
  }
  interface CustomEventInfo {
    readonly type: 'custom';
  }
  interface FetchResponseInfo {
    readonly type: 'fetch';
    readonly statusCode: number;
  }
  type EventOutcome =
    | 'ok'
    | 'canceled'
    | 'exception'
    | 'unknown'
    | 'killSwitch'
    | 'daemonDown'
    | 'exceededCpu'
    | 'exceededMemory'
    | 'loadShed'
    | 'responseStreamDisconnected'
    | 'scriptNotFound';
  interface ScriptVersion {
    readonly id: string;
    readonly tag?: string;
    readonly message?: string;
  }
  interface Trigger {
    readonly traceId: string;
    readonly invocationId: string;
    readonly spanId: string;
  }
  interface Onset {
    readonly type: 'onset';
    readonly dispatchNamespace?: string;
    readonly entrypoint?: string;
    readonly scriptName?: string;
    readonly scriptTags?: string[];
    readonly scriptVersion?: ScriptVersion;
    readonly trigger?: Trigger;
    readonly info:
      | FetchEventInfo
      | JsRpcEventInfo
      | ScheduledEventInfo
      | AlarmEventInfo
      | QueueEventInfo
      | EmailEventInfo
      | TraceEventInfo
      | HibernatableWebSocketEventInfo
      | Resume
      | CustomEventInfo;
  }
  interface Outcome {
    readonly type: 'outcome';
    readonly outcome: EventOutcome;
    readonly cpuTime: number;
    readonly wallTime: number;
  }
  interface Hibernate {
    readonly type: 'hibernate';
  }
  interface SpanOpen {
    readonly type: 'spanOpen';
    readonly name: string;
    readonly info?: FetchEventInfo | JsRpcEventInfo | Attributes;
  }
  interface SpanClose {
    readonly type: 'spanClose';
    readonly outcome: EventOutcome;
  }
  interface DiagnosticChannelEvent {
    readonly type: 'diagnosticChannel';
    readonly channel: string;
    readonly message: any;
  }
  interface Exception {
    readonly type: 'exception';
    readonly name: string;
    readonly message: string;
    readonly stack?: string;
  }
  interface Log {
    readonly type: 'log';
    readonly level: 'debug' | 'error' | 'info' | 'log' | 'warn';
    readonly message: string;
  }
  interface Return {
    readonly type: 'return';
    readonly info?: FetchResponseInfo | Attributes;
  }
  interface Link {
    readonly type: 'link';
    readonly label?: string;
    readonly traceId: string;
    readonly invocationId: string;
    readonly spanId: string;
  }
  interface Attribute {
    readonly name: string;
    readonly value: string | string[] | boolean | boolean[] | number | number[] | bigint | bigint[];
  }
  interface Attributes {
    readonly type: 'attributes';
    readonly info: Attribute[];
  }
  interface TailEvent {
    readonly traceId: string;
    readonly invocationId: string;
    readonly spanId: string;
    readonly timestamp: Date;
    readonly sequence: number;
    readonly event:
      | Onset
      | Outcome
      | Hibernate
      | SpanOpen
      | SpanClose
      | DiagnosticChannelEvent
      | Exception
      | Log
      | Return
      | Link
      | Attributes;
  }
  type TailEventHandler = (event: TailEvent) => void | Promise<void>;
  type TailEventHandlerName =
    | 'outcome'
    | 'hibernate'
    | 'spanOpen'
    | 'spanClose'
    | 'diagnosticChannel'
    | 'exception'
    | 'log'
    | 'return'
    | 'link'
    | 'attributes';
  type TailEventHandlerObject = Record<TailEventHandlerName, TailEventHandler>;
  type TailEventHandlerType = TailEventHandler | TailEventHandlerObject;
}
// Copyright (c) 2022-2023 Cloudflare, Inc.
// Licensed under the Apache 2.0 license found in the LICENSE file or at:
//     https://opensource.org/licenses/Apache-2.0
/**
 * Data types supported for holding vector metadata.
 */
type VectorizeVectorMetadataValue = string | number | boolean | string[];
/**
 * Additional information to associate with a vector.
 */
type VectorizeVectorMetadata =
  | VectorizeVectorMetadataValue
  | Record<string, VectorizeVectorMetadataValue>;
type VectorFloatArray = Float32Array | Float64Array;
interface VectorizeError {
  code?: number;
  error: string;
}
/**
 * Comparison logic/operation to use for metadata filtering.
 *
 * This list is expected to grow as support for more operations are released.
 */
type VectorizeVectorMetadataFilterOp = '$eq' | '$ne';
/**
 * Filter criteria for vector metadata used to limit the retrieved query result set.
 */
type VectorizeVectorMetadataFilter = {
  [field: string]:
    | Exclude<VectorizeVectorMetadataValue, string[]>
    | null
    | {
        [Op in VectorizeVectorMetadataFilterOp]?: Exclude<
          VectorizeVectorMetadataValue,
          string[]
        > | null;
      };
};
/**
 * Supported distance metrics for an index.
 * Distance metrics determine how other "similar" vectors are determined.
 */
type VectorizeDistanceMetric = 'euclidean' | 'cosine' | 'dot-product';
/**
 * Metadata return levels for a Vectorize query.
 *
 * Default to "none".
 *
 * @property all      Full metadata for the vector return set, including all fields (including those un-indexed) without truncation. This is a more expensive retrieval, as it requires additional fetching & reading of un-indexed data.
 * @property indexed  Return all metadata fields configured for indexing in the vector return set. This level of retrieval is "free" in that no additional overhead is incurred returning this data. However, note that indexed metadata is subject to truncation (especially for larger strings).
 * @property none     No indexed metadata will be returned.
 */
type VectorizeMetadataRetrievalLevel = 'all' | 'indexed' | 'none';
interface VectorizeQueryOptions {
  topK?: number;
  namespace?: string;
  returnValues?: boolean;
  returnMetadata?: boolean | VectorizeMetadataRetrievalLevel;
  filter?: VectorizeVectorMetadataFilter;
}
/**
 * Information about the configuration of an index.
 */
type VectorizeIndexConfig =
  | {
      dimensions: number;
      metric: VectorizeDistanceMetric;
    }
  | {
      preset: string; // keep this generic, as we'll be adding more presets in the future and this is only in a read capacity
    };
/**
 * Metadata about an existing index.
 *
 * This type is exclusively for the Vectorize **beta** and will be deprecated once Vectorize RC is released.
 * See {@link VectorizeIndexInfo} for its post-beta equivalent.
 */
interface VectorizeIndexDetails {
  /** The unique ID of the index */
  readonly id: string;
  /** The name of the index. */
  name: string;
  /** (optional) A human readable description for the index. */
  description?: string;
  /** The index configuration, including the dimension size and distance metric. */
  config: VectorizeIndexConfig;
  /** The number of records containing vectors within the index. */
  vectorsCount: number;
}
/**
 * Metadata about an existing index.
 */
interface VectorizeIndexInfo {
  /** The number of records containing vectors within the index. */
  vectorCount: number;
  /** Number of dimensions the index has been configured for. */
  dimensions: number;
  /** ISO 8601 datetime of the last processed mutation on in the index. All changes before this mutation will be reflected in the index state. */
  processedUpToDatetime: number;
  /** UUIDv4 of the last mutation processed by the index. All changes before this mutation will be reflected in the index state. */
  processedUpToMutation: number;
}
/**
 * Represents a single vector value set along with its associated metadata.
 */
interface VectorizeVector {
  /** The ID for the vector. This can be user-defined, and must be unique. It should uniquely identify the object, and is best set based on the ID of what the vector represents. */
  id: string;
  /** The vector values */
  values: VectorFloatArray | number[];
  /** The namespace this vector belongs to. */
  namespace?: string;
  /** Metadata associated with the vector. Includes the values of other fields and potentially additional details. */
  metadata?: Record<string, VectorizeVectorMetadata>;
}
/**
 * Represents a matched vector for a query along with its score and (if specified) the matching vector information.
 */
type VectorizeMatch = Pick<Partial<VectorizeVector>, 'values'> &
  Omit<VectorizeVector, 'values'> & {
    /** The score or rank for similarity, when returned as a result */
    score: number;
  };
/**
 * A set of matching {@link VectorizeMatch} for a particular query.
 */
interface VectorizeMatches {
  matches: VectorizeMatch[];
  count: number;
}
/**
 * Results of an operation that performed a mutation on a set of vectors.
 * Here, `ids` is a list of vectors that were successfully processed.
 *
 * This type is exclusively for the Vectorize **beta** and will be deprecated once Vectorize RC is released.
 * See {@link VectorizeAsyncMutation} for its post-beta equivalent.
 */
interface VectorizeVectorMutation {
  /* List of ids of vectors that were successfully processed. */
  ids: string[];
  /* Total count of the number of processed vectors. */
  count: number;
}
/**
 * Result type indicating a mutation on the Vectorize Index.
 * Actual mutations are processed async where the `mutationId` is the unique identifier for the operation.
 */
interface VectorizeAsyncMutation {
  /** The unique identifier for the async mutation operation containing the changeset. */
  mutationId: string;
}
/**
 * A Vectorize Vector Search Index for querying vectors/embeddings.
 *
 * This type is exclusively for the Vectorize **beta** and will be deprecated once Vectorize RC is released.
 * See {@link Vectorize} for its new implementation.
 */
declare abstract class VectorizeIndex {
  /**
   * Get information about the currently bound index.
   * @returns A promise that resolves with information about the current index.
   */
  public describe(): Promise<VectorizeIndexDetails>;
  /**
   * Use the provided vector to perform a similarity search across the index.
   * @param vector Input vector that will be used to drive the similarity search.
   * @param options Configuration options to massage the returned data.
   * @returns A promise that resolves with matched and scored vectors.
   */
  public query(
    vector: VectorFloatArray | number[],
    options?: VectorizeQueryOptions,
  ): Promise<VectorizeMatches>;
  /**
   * Insert a list of vectors into the index dataset. If a provided id exists, an error will be thrown.
   * @param vectors List of vectors that will be inserted.
   * @returns A promise that resolves with the ids & count of records that were successfully processed.
   */
  public insert(vectors: VectorizeVector[]): Promise<VectorizeVectorMutation>;
  /**
   * Upsert a list of vectors into the index dataset. If a provided id exists, it will be replaced with the new values.
   * @param vectors List of vectors that will be upserted.
   * @returns A promise that resolves with the ids & count of records that were successfully processed.
   */
  public upsert(vectors: VectorizeVector[]): Promise<VectorizeVectorMutation>;
  /**
   * Delete a list of vectors with a matching id.
   * @param ids List of vector ids that should be deleted.
   * @returns A promise that resolves with the ids & count of records that were successfully processed (and thus deleted).
   */
  public deleteByIds(ids: string[]): Promise<VectorizeVectorMutation>;
  /**
   * Get a list of vectors with a matching id.
   * @param ids List of vector ids that should be returned.
   * @returns A promise that resolves with the raw unscored vectors matching the id set.
   */
  public getByIds(ids: string[]): Promise<VectorizeVector[]>;
}
/**
 * A Vectorize Vector Search Index for querying vectors/embeddings.
 *
 * Mutations in this version are async, returning a mutation id.
 */
declare abstract class Vectorize {
  /**
   * Get information about the currently bound index.
   * @returns A promise that resolves with information about the current index.
   */
  public describe(): Promise<VectorizeIndexInfo>;
  /**
   * Use the provided vector to perform a similarity search across the index.
   * @param vector Input vector that will be used to drive the similarity search.
   * @param options Configuration options to massage the returned data.
   * @returns A promise that resolves with matched and scored vectors.
   */
  public query(
    vector: VectorFloatArray | number[],
    options?: VectorizeQueryOptions,
  ): Promise<VectorizeMatches>;
  /**
   * Use the provided vector-id to perform a similarity search across the index.
   * @param vectorId Id for a vector in the index against which the index should be queried.
   * @param options Configuration options to massage the returned data.
   * @returns A promise that resolves with matched and scored vectors.
   */
  public queryById(vectorId: string, options?: VectorizeQueryOptions): Promise<VectorizeMatches>;
  /**
   * Insert a list of vectors into the index dataset. If a provided id exists, an error will be thrown.
   * @param vectors List of vectors that will be inserted.
   * @returns A promise that resolves with a unique identifier of a mutation containing the insert changeset.
   */
  public insert(vectors: VectorizeVector[]): Promise<VectorizeAsyncMutation>;
  /**
   * Upsert a list of vectors into the index dataset. If a provided id exists, it will be replaced with the new values.
   * @param vectors List of vectors that will be upserted.
   * @returns A promise that resolves with a unique identifier of a mutation containing the upsert changeset.
   */
  public upsert(vectors: VectorizeVector[]): Promise<VectorizeAsyncMutation>;
  /**
   * Delete a list of vectors with a matching id.
   * @param ids List of vector ids that should be deleted.
   * @returns A promise that resolves with a unique identifier of a mutation containing the delete changeset.
   */
  public deleteByIds(ids: string[]): Promise<VectorizeAsyncMutation>;
  /**
   * Get a list of vectors with a matching id.
   * @param ids List of vector ids that should be returned.
   * @returns A promise that resolves with the raw unscored vectors matching the id set.
   */
  public getByIds(ids: string[]): Promise<VectorizeVector[]>;
}
/**
 * The interface for "version_metadata" binding
 * providing metadata about the Worker Version using this binding.
 */
type WorkerVersionMetadata = {
  /** The ID of the Worker Version using this binding */
  id: string;
  /** The tag of the Worker Version using this binding */
  tag: string;
  /** The timestamp of when the Worker Version was uploaded */
  timestamp: string;
};
interface DynamicDispatchLimits {
  /**
   * Limit CPU time in milliseconds.
   */
  cpuMs?: number;
  /**
   * Limit number of subrequests.
   */
  subRequests?: number;
}
interface DynamicDispatchOptions {
  /**
   * Limit resources of invoked Worker script.
   */
  limits?: DynamicDispatchLimits;
  /**
   * Arguments for outbound Worker script, if configured.
   */
  outbound?: {
    [key: string]: any;
  };
}
interface DispatchNamespace {
  /**
   * @param name Name of the Worker script.
   * @param args Arguments to Worker script.
   * @param options Options for Dynamic Dispatch invocation.
   * @returns A Fetcher object that allows you to send requests to the Worker script.
   * @throws If the Worker script does not exist in this dispatch namespace, an error will be thrown.
   */
  get(
    name: string,
    args?: {
      [key: string]: any;
    },
    options?: DynamicDispatchOptions,
  ): Fetcher;
}
declare module 'cloudflare:workflows' {
  /**
   * NonRetryableError allows for a user to throw a fatal error
   * that makes a Workflow instance fail immediately without triggering a retry
   */
  export class NonRetryableError extends Error {
    public constructor(message: string, name?: string);
  }
}
declare abstract class Workflow<PARAMS = unknown> {
  /**
   * Get a handle to an existing instance of the Workflow.
   * @param id Id for the instance of this Workflow
   * @returns A promise that resolves with a handle for the Instance
   */
  public get(id: string): Promise<WorkflowInstance>;
  /**
   * Create a new instance and return a handle to it. If a provided id exists, an error will be thrown.
   * @param options Options when creating an instance including id and params
   * @returns A promise that resolves with a handle for the Instance
   */
  public create(options?: WorkflowInstanceCreateOptions<PARAMS>): Promise<WorkflowInstance>;
  /**
   * Create a batch of instances and return handle for all of them. If a provided id exists, an error will be thrown.
   * `createBatch` is limited at 100 instances at a time or when the RPC limit for the batch (1MiB) is reached.
   * @param batch List of Options when creating an instance including name and params
   * @returns A promise that resolves with a list of handles for the created instances.
   */
  public createBatch(batch: WorkflowInstanceCreateOptions<PARAMS>[]): Promise<WorkflowInstance[]>;
}
interface WorkflowInstanceCreateOptions<PARAMS = unknown> {
  /**
   * An id for your Workflow instance. Must be unique within the Workflow.
   */
  id?: string;
  /**
   * The event payload the Workflow instance is triggered with
   */
  params?: PARAMS;
}
type InstanceStatus = {
  status:
    | 'queued' // means that instance is waiting to be started (see concurrency limits)
    | 'running'
    | 'paused'
    | 'errored'
    | 'terminated' // user terminated the instance while it was running
    | 'complete'
    | 'waiting' // instance is hibernating and waiting for sleep or event to finish
    | 'waitingForPause' // instance is finishing the current work to pause
    | 'unknown';
  error?: string;
  output?: object;
};
interface WorkflowError {
  code?: number;
  message: string;
}
declare abstract class WorkflowInstance {
  public id: string;
  /**
   * Pause the instance.
   */
  public pause(): Promise<void>;
  /**
   * Resume the instance. If it is already running, an error will be thrown.
   */
  public resume(): Promise<void>;
  /**
   * Terminate the instance. If it is errored, terminated or complete, an error will be thrown.
   */
  public terminate(): Promise<void>;
  /**
   * Restart the instance.
   */
  public restart(): Promise<void>;
  /**
   * Returns the current status of the instance.
   */
  public status(): Promise<InstanceStatus>;
  /**
   * Send an event to this instance.
   */
  public sendEvent({ type, payload }: { type: string; payload: unknown }): Promise<void>;
}


================================================
FILE: examples/server/wrangler.jsonc
================================================
/**
 * For more details on how to configure Wrangler, refer to:
 * https://developers.cloudflare.com/workers/wrangler/configuration/
 */
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "remote-mcp-server-authless",
  "main": "src/index.ts",
  "compatibility_date": "2025-05-16",
  "compatibility_flags": ["nodejs_compat"],
  "migrations": [
    {
      "new_sqlite_classes": ["MyMCP"],
      "tag": "v1",
    },
  ],
  "durable_objects": {
    "bindings": [
      {
        "class_name": "MyMCP",
        "name": "MCP_OBJECT",
      },
    ],
  },
  "observability": {
    "enabled": true,
  },
}


================================================
FILE: examples/typescript-server-demo/README.md
================================================
# typescript-server-demo

This barebones server demonstrates how to use `@mcp-ui/server` to generate all three types of UI resources via three separate tools:

- `showExternalUrl`: Renders an `<iframe>` pointing to an external URL.
- `showRawHtml`: Renders a static block of HTML.
- `showRemoteDom`: Executes a script that uses a custom component (`<ui-text>`) to render content, demonstrating how to leverage a client-side component library.

For a detailed explanation of how this server works, see the [TypeScript Server Walkthrough](https://mcpui.dev/guide/server/typescript/walkthrough.html).

## Running the server

To run the server in development mode, first install the dependencies, then run the `dev` command:

```bash
pnpm install
pnpm dev
```

The server will be available at `http://localhost:3000`.

You can view the UI resources from this server by connecting to it with the [`ui-inspector`](https://github.com/idosal/ui-inspector) (target `http://localhost:3000/mcp` with Streamable HTTP Transport Type).



================================================
FILE: examples/typescript-server-demo/package.json
================================================
{
  "name": "typescript-server-demo",
  "version": "1.0.0",
  "type": "module",
  "description": "Barebones TypeScript Model Context Protocol server demo.",
  "main": "dist/index.js",
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js",
    "dev": "vite-node src/index.ts"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "@mcp-ui/server": "^5.2.0",
    "@modelcontextprotocol/sdk": "^1.22.0",
    "cors": "^2.8.5",
    "express": "^4.17.1"
  },
  "devDependencies": {
    "@types/cors": "^2.8.12",
    "@types/express": "^4.17.13",
    "@types/node": "^20.0.0",
    "ts-node": "^10.4.0",
    "typescript": "^5.2.0",
    "vite": "^5.0.0",
    "vite-node": "^1.0.0"
  }
}


================================================
FILE: examples/typescript-server-demo/src/index.ts
================================================
import express from 'express';
import cors from 'cors';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
import { createUIResource } from '@mcp-ui/server';
import { randomUUID } from 'crypto';

const app = express();
const port = 3000;

app.use(
  cors({
    origin: '*',
    exposedHeaders: ['Mcp-Session-Id'],
    allowedHeaders: ['Content-Type', 'mcp-session-id'],
  }),
);
app.use(express.json());

// Map to store transports by session ID, as shown in the documentation.
const transports: { [sessionId: string]: StreamableHTTPServerTransport } = {};

// Handle POST requests for client-to-server communication.
app.post('/mcp', async (req, res) => {
  const sessionId = req.headers['mcp-session-id'] as string | undefined;
  let transport: StreamableHTTPServerTransport;

  if (sessionId && transports[sessionId]) {
    // A session already exists; reuse the existing transport.
    transport = transports[sessionId];
  } else if (!sessionId && isInitializeRequest(req.body)) {
    // This is a new initialization request. Create a new transport.
    transport = new StreamableHTTPServerTransport({
      sessionIdGenerator: () => randomUUID(),
      onsessioninitialized: (sid) => {
        transports[sid] = transport;
        console.log(`MCP Session initialized: ${sid}`);
      },
    });

    // Clean up the transport from our map when the session closes.
    transport.onclose = () => {
      if (transport.sessionId) {
        console.log(`MCP Session closed: ${transport.sessionId}`);
        delete transports[transport.sessionId];
      }
    };

    // Create a new server instance for this specific session.
    const server = new McpServer({
      name: 'typescript-server-demo',
      version: '1.0.0',
    });

    // Register our tools on the new server instance.
    server.registerTool(
      'showExternalUrl',
      {
        title: 'Show External URL',
        description: 'Creates a UI resource displaying an external URL (example.com).',
        inputSchema: {},
      },
      async () => {
        // Create the UI resource to be returned to the client
        // This is the only MCP-UI specific code in this example
        const uiResource = await createUIResource({
          uri: 'ui://greeting',
          content: { type: 'externalUrl', iframeUrl: 'https://example.com' },
          encoding: 'text',
        });

        return {
          content: [uiResource],
        };
      },
    );

    server.registerTool(
      'showRawHtml',
      {
        title: 'Show Raw HTML',
        description: 'Creates a UI resource displaying raw HTML.',
        inputSchema: {},
      },
      async () => {
        const uiResource = await createUIResource({
          uri: 'ui://raw-html-demo',
          content: { type: 'rawHtml', htmlString: '<h1>Hello from Raw HTML</h1>' },
          encoding: 'text',
        });

        return {
          content: [uiResource],
        };
      },
    );

    // Connect the server instance to the transport for this session.
    await server.connect(transport);
  } else {
    return res.status(400).json({
      error: { message: 'Bad Request: No valid session ID provided' },
    });
  }

  // Handle the client's request using the session's transport.
  await transport.handleRequest(req, res, req.body);
});

// A separate, reusable handler for GET and DELETE requests.
const handleSessionRequest = async (req: express.Request, res: express.Response) => {
  const sessionId = req.headers['mcp-session-id'] as string | undefined;
  console.log('sessionId', sessionId);
  if (!sessionId || !transports[sessionId]) {
    return res.status(404).send('Session not found');
  }

  const transport = transports[sessionId];
  await transport.handleRequest(req, res);
};

// GET handles the long-lived stream for server-to-client messages.
app.get('/mcp', handleSessionRequest);

// DELETE handles explicit session termination from the client.
app.delete('/mcp', handleSessionRequest);

app.listen(port, () => {
  console.log(`TypeScript MCP server listening at http://localhost:${port}`);
});


================================================
FILE: examples/typescript-server-demo/tsconfig.json
================================================
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src"]
}


================================================
FILE: lefthook.yml
================================================
pre-commit:
  parallel: true
  stage_fixed: true
  jobs:
    - name: lint typescript
      glob: '*.{ts,tsx}'
      run: pnpm eslint --fix --max-warnings=0 --no-warn-ignored {staged_files} && pnpm prettier --write {staged_files}

    - name: format js
      glob: '*.{js,jsx,mjs,cjs}'
      run: pnpm prettier --write {staged_files}

    - name: format json/css
      glob: '*.{json,css,scss}'
      run: pnpm prettier --write {staged_files}

    - name: format yaml
      glob: '*.{yaml,yml}'
      run: pnpm prettier --write {staged_files}


================================================
FILE: package.json
================================================
{
  "name": "mcp-ui",
  "private": true,
  "scripts": {
    "preinstall": "npx only-allow pnpm",
    "dev": "pnpm --filter=\"./sdks/typescript/*\" --parallel dev",
    "build": "pnpm --filter=\"./sdks/typescript/*\" build",
    "preview": "pnpm --filter=\"./sdks/typescript/*\" --parallel preview",
    "test": "pnpm test:ts && pnpm test:ruby",
    "test:ts": "vitest run",
    "test:ruby": "cd sdks/ruby && bundle install && bundle exec rake spec",
    "test:watch": "vitest watch",
    "coverage": "vitest run --coverage",
    "lint": "eslint .",
    "lint:fix": "eslint . --fix",
    "format": "prettier --write \"**/*.{ts,tsx,js,jsx,json,md,yaml,yml,css,scss}\"",
    "version:patch": "echo \"Versioning with Changesets, then run pnpm install\" && pnpm changeset version && pnpm install --lockfile-only",
    "publish-packages": "pnpm build && pnpm changeset publish",
    "docs:dev": "vitepress dev docs/src",
    "docs:build": "vitepress build docs/src",
    "docs:preview": "vitepress preview docs/src"
  },
  "devDependencies": {
    "@eslint/js": "^9.25.0",
    "@semantic-release/changelog": "^6.0.3",
    "@semantic-release/commit-analyzer": "^13.0.1",
    "@semantic-release/exec": "^7.1.0",
    "@semantic-release/git": "^10.0.1",
    "@semantic-release/github": "^12.0.2",
    "@semantic-release/npm": "^13.1.2",
    "@semantic-release/release-notes-generator": "^14.1.0",
    "@swc/core": "^1.4.0",
    "@testing-library/jest-dom": "^6.1.5",
    "@testing-library/react": "^14.1.2",
    "@types/jest": "^29.5.11",
    "@types/node": "^22.15.18",
    "@vitejs/plugin-react-swc": "^4.2.2",
    "c8": "^10.1.3",
    "eslint": "^9.39.1",
    "eslint-config-prettier": "^10.1.8",
    "eslint-plugin-jsx-a11y": "^6.8.0",
    "eslint-plugin-react": "^7.37.5",
    "eslint-plugin-react-hooks": "^7.0.1",
    "globals": "^16.0.0",
    "jsdom": "^25.0.1",
    "prettier": "^3.7.4",
    "prettier-plugin-tailwindcss": "^0.7.2",
    "semantic-release": "^25.0.2",
    "ts-jest": "^29.1.1",
    "ts-node": "^10.9.2",
    "typescript": "^5.9.3",
    "typescript-eslint": "^8.30.1",
    "vite": "^7.2.7",
    "vite-plugin-dts": "^4.5.4",
    "vitepress": "^1.6.4",
    "vitest": "^4.0.15"
  },
  "packageManager": "pnpm@10.11.0+sha512.6540583f41cc5f628eb3d9773ecee802f4f9ef9923cc45b69890fb47991d4b092964694ec3a4f738a420c918a333062c8b925d312f42e4f0c263eb603551f977",
  "license": "Apache-2.0",
  "version": "5.2.0"
}


================================================
FILE: pnpm-workspace.yaml
================================================
packages:
  # all packages in subdirs of sdks/typescript/
  - 'sdks/typescript/*'
  - 'examples/*'
  - 'docs'


================================================
FILE: sdks/python/server/CHANGELOG.md
================================================
# 1.0.0 (2025-11-04)


### Bug Fixes

* add a bridge to pass messages in and out of the proxy ([#38](https://github.com/idosal/mcp-ui/issues/38)) ([30ccac0](https://github.com/idosal/mcp-ui/commit/30ccac0706ad8e02ebcd8960924ed1d58ddedf85))
* bump client version ([75c9236](https://github.com/idosal/mcp-ui/commit/75c923689654b4443ad1093fafc0bad16902e4cc))
* **client:** specify iframe ([fd0b70a](https://github.com/idosal/mcp-ui/commit/fd0b70a84948d3aa5d7a79269ff7c3bcd0946689))
* **client:** styling ([6ff9b68](https://github.com/idosal/mcp-ui/commit/6ff9b685fd1be770fd103943e45275e9ec86905c))
* dependencies ([887f61f](https://github.com/idosal/mcp-ui/commit/887f61f827b4585c17493d4fa2dfb251ea598587))
* Enable bidirectional message relay in rawhtml proxy mode ([#138](https://github.com/idosal/mcp-ui/issues/138)) ([f0bdefb](https://github.com/idosal/mcp-ui/commit/f0bdefb818aca5a3bfbdfe28fc4fe057b1818cb5))
* ensure Apps SDK adapter is bundled properly and initialized wth config ([#137](https://github.com/idosal/mcp-ui/issues/137)) ([4f7c25c](https://github.com/idosal/mcp-ui/commit/4f7c25ce7e6f25e36cfc188016b012d31d722204))
* export RemoteDomResource ([2b86f2d](https://github.com/idosal/mcp-ui/commit/2b86f2dd4506de49c69908e23d84a2a323170446))
* export ResourceRenderer and HtmlResource ([2b841a5](https://github.com/idosal/mcp-ui/commit/2b841a556c1111ed70ccb3d3987afd21fe7df897))
* exports ([3a93a16](https://github.com/idosal/mcp-ui/commit/3a93a16e1b7438ba7b2ef49ca854479f755abcc6))
* fix file extension reference in package.json ([927989c](https://github.com/idosal/mcp-ui/commit/927989c4f81742106b6f5e2f68343fb7ea7d016a))
* iframe handle ([#15](https://github.com/idosal/mcp-ui/issues/15)) ([66bd4fd](https://github.com/idosal/mcp-ui/commit/66bd4fd3d04f82e3e4557f064e701b68e1d8af11))
* lint ([4487820](https://github.com/idosal/mcp-ui/commit/44878203a71c3c9173d463b809be36769e996ba9))
* lint ([d0a91f9](https://github.com/idosal/mcp-ui/commit/d0a91f9a07ec0042690240c3d8d0bad620f8c765))
* minor typo ([a0bee9c](https://github.com/idosal/mcp-ui/commit/a0bee9c85e5ee02e021ba687940ced38220445fe))
* move react dependencies to be peer dependencies ([#91](https://github.com/idosal/mcp-ui/issues/91)) ([f672f3e](https://github.com/idosal/mcp-ui/commit/f672f3efc1c2ba2fbae16f9dcdc2142c2b4bd920)), closes [#90](https://github.com/idosal/mcp-ui/issues/90)
* package config ([8dc1e53](https://github.com/idosal/mcp-ui/commit/8dc1e5358c3c8e641206a5e6851427d360cc1955))
* packaging ([9e6babd](https://github.com/idosal/mcp-ui/commit/9e6babd3a587213452ea7aec4cc9ae3a50fa1965))
* pass ref explicitly using iframeProps ([#33](https://github.com/idosal/mcp-ui/issues/33)) ([d01b5d1](https://github.com/idosal/mcp-ui/commit/d01b5d1e4cdaedc436ba2fa8984d866d93d59087))
* publish ([0943e7a](https://github.com/idosal/mcp-ui/commit/0943e7acaf17f32aae085c2313bfbec47bc59f1f))
* ref passing to UIResourceRenderer ([#32](https://github.com/idosal/mcp-ui/issues/32)) ([d28c23f](https://github.com/idosal/mcp-ui/commit/d28c23f9b8ee320f4e361200ae02a23f0d2a1c0c))
* remove shared dependency ([e66e8f4](https://github.com/idosal/mcp-ui/commit/e66e8f49b1ba46090db6e4682060488566f4fe41))
* rename components and methods to fit new scope ([#22](https://github.com/idosal/mcp-ui/issues/22)) ([6bab1fe](https://github.com/idosal/mcp-ui/commit/6bab1fe3a168a18e7ba4762e23478abf4e0cc84c))
* rename delivery -> encoding and flavor -> framework ([#36](https://github.com/idosal/mcp-ui/issues/36)) ([9a509ed](https://github.com/idosal/mcp-ui/commit/9a509ed80d051b0a8042b36958b401a0a7c1e138))
* Ruby comment ([b22dc2e](https://github.com/idosal/mcp-ui/commit/b22dc2e0a0db20d98ada884649ad408ebaf72d22))
* support react-router ([21ffb95](https://github.com/idosal/mcp-ui/commit/21ffb95fe6d77a348b95b38dbf3741ba6442894e))
* text and blob support in RemoteDOM resources ([ec68eb9](https://github.com/idosal/mcp-ui/commit/ec68eb90df984da8b492cc25eafdafdeda79f299))
* trigger release ([aaca831](https://github.com/idosal/mcp-ui/commit/aaca83125c3f7825ccdebf0f04f8553e953c5249))
* typescript ci publish ([e7c0ebf](https://github.com/idosal/mcp-ui/commit/e7c0ebfa7f7b552f9763743fda659d1441f21692))
* typescript types to be compatible with MCP SDK ([#10](https://github.com/idosal/mcp-ui/issues/10)) ([74365d7](https://github.com/idosal/mcp-ui/commit/74365d7ed6422beef6cd9ee0f5a97c847bd9827b))
* update deps ([4091ef4](https://github.com/idosal/mcp-ui/commit/4091ef47da048fab3c4feb002f5287b2ff295744))
* update isUIResource to use EmbeddedResource type ([#122](https://github.com/idosal/mcp-ui/issues/122)) ([5a65a0b](https://github.com/idosal/mcp-ui/commit/5a65a0b1ba63e6cfda26b8da41239a532f00d60a)), closes [#117](https://github.com/idosal/mcp-ui/issues/117)
* use targetOrigin in the proxy message relay ([#40](https://github.com/idosal/mcp-ui/issues/40)) ([b3fb54e](https://github.com/idosal/mcp-ui/commit/b3fb54e28ca7b8eeda896b5bcf478b6343dbba47))
* validate URL ([b7c994d](https://github.com/idosal/mcp-ui/commit/b7c994dfdd947b3dfbb903fc8cb896d61004c8d8))
* wc dist overwrite ([#63](https://github.com/idosal/mcp-ui/issues/63)) ([9e46c56](https://github.com/idosal/mcp-ui/commit/9e46c56c7a8908410fad6d08a5d845139e93f80f))


### Documentation

* bump ([#4](https://github.com/idosal/mcp-ui/issues/4)) ([ad4d163](https://github.com/idosal/mcp-ui/commit/ad4d1632cc1f9c99072349a8f0cdaac343236132))


### Features

* add convenience function isUIResource to client SDK ([#86](https://github.com/idosal/mcp-ui/issues/86)) ([607c6ad](https://github.com/idosal/mcp-ui/commit/607c6add3567bb60c45accf3e1b25a38ed284a6f))
* add embeddedResourceProps for annotations ([#99](https://github.com/idosal/mcp-ui/issues/99)) ([b96ec44](https://github.com/idosal/mcp-ui/commit/b96ec442ec319a1944393ada0bdcccb93b7ffc62))
* add proxy option to externalUrl ([#37](https://github.com/idosal/mcp-ui/issues/37)) ([7b95cd0](https://github.com/idosal/mcp-ui/commit/7b95cd0b3873fc1cde28748ec463e81c6ff1c494))
* add remote-dom content type ([#18](https://github.com/idosal/mcp-ui/issues/18)) ([5dacf37](https://github.com/idosal/mcp-ui/commit/5dacf37c22b5ee6ae795049a8d573fc073b8a1f5))
* add Ruby server SDK ([#31](https://github.com/idosal/mcp-ui/issues/31)) ([5ffcde4](https://github.com/idosal/mcp-ui/commit/5ffcde4a373accdd063fa6c3b1b3d4df13c91b53))
* add sandbox permissions instead of an override ([#83](https://github.com/idosal/mcp-ui/issues/83)) ([b1068e9](https://github.com/idosal/mcp-ui/commit/b1068e9e87caa2b4302bf145a33efdfd1af05c1d))
* add ui-request-render-data message type ([#111](https://github.com/idosal/mcp-ui/issues/111)) ([26135ce](https://github.com/idosal/mcp-ui/commit/26135ce2c7f7d586b0b81a03623cd77dc1bc7f90))
* add UIResourceRenderer Web Component ([#58](https://github.com/idosal/mcp-ui/issues/58)) ([ec8f299](https://github.com/idosal/mcp-ui/commit/ec8f2994ecf36774e6ad5191654ba22946d0ee49))
* auto resize with the autoResizeIframe prop ([#56](https://github.com/idosal/mcp-ui/issues/56)) ([76c867a](https://github.com/idosal/mcp-ui/commit/76c867a569b72aed892290aa84e1194ab8eb79ce))
* change onGenericMcpAction to optional onUiAction ([1913b59](https://github.com/idosal/mcp-ui/commit/1913b5977c30811f9e67659949e2d961f2eda983))
* **client:** allow setting supportedContentTypes for HtmlResource ([#17](https://github.com/idosal/mcp-ui/issues/17)) ([e009ef1](https://github.com/idosal/mcp-ui/commit/e009ef10010134ba3d9893314cc4d8e1274f1f07))
* consolidate ui:// and ui-app:// ([#8](https://github.com/idosal/mcp-ui/issues/8)) ([2e08035](https://github.com/idosal/mcp-ui/commit/2e08035676bb6a46ef3c94dba916bc895f1fa3cc))
* pass iframe props down ([#14](https://github.com/idosal/mcp-ui/issues/14)) ([112539d](https://github.com/idosal/mcp-ui/commit/112539d28640a96e8375a6b416f2ba559370b312))
* refactor UTFtoB64 (bump server version) ([#95](https://github.com/idosal/mcp-ui/issues/95)) ([2d5e16b](https://github.com/idosal/mcp-ui/commit/2d5e16bf39073ee890586f458412f0c3b474c2b8))
* send render data to the iframe ([#51](https://github.com/idosal/mcp-ui/issues/51)) ([d38cfc7](https://github.com/idosal/mcp-ui/commit/d38cfc7925061c1ae1911bdee408033c8e9f283d))
* separate html and remote-dom props ([#24](https://github.com/idosal/mcp-ui/issues/24)) ([a7f0529](https://github.com/idosal/mcp-ui/commit/a7f05299dc9cc40184f9ab25c5b648ee7077be64))
* support adapters ([#127](https://github.com/idosal/mcp-ui/issues/127)) ([d4bd152](https://github.com/idosal/mcp-ui/commit/d4bd152db0a1bd27081502098f3cd9aa54ca359e))
* support generic messages response ([#35](https://github.com/idosal/mcp-ui/issues/35)) ([10b407b](https://github.com/idosal/mcp-ui/commit/10b407b279b3ee9608ef077445f4d714f88343c5))
* support metadata in Python SDK ([#134](https://github.com/idosal/mcp-ui/issues/134)) ([9bc3c64](https://github.com/idosal/mcp-ui/commit/9bc3c646c2638e16ac62edf9faca2dbee2b8cb7e))
* support passing resource metadata ([#87](https://github.com/idosal/mcp-ui/issues/87)) ([f1c1c9b](https://github.com/idosal/mcp-ui/commit/f1c1c9b62dd74c63045b295eb388181843ac772a))
* support proxy for rawHtml ([#132](https://github.com/idosal/mcp-ui/issues/132)) ([1bbeb09](https://github.com/idosal/mcp-ui/commit/1bbeb093bc9c389f4ccfd9e8df06dc7f1eaadde0))
* support ui action result types ([#6](https://github.com/idosal/mcp-ui/issues/6)) ([899d152](https://github.com/idosal/mcp-ui/commit/899d1527286a281a23fbb8f3a207d435dfc3fe96))
* switch to ResourceRenderer ([#21](https://github.com/idosal/mcp-ui/issues/21)) ([6fe3166](https://github.com/idosal/mcp-ui/commit/6fe316682675e27db914d60696754677e3783448))


### BREAKING CHANGES

* The existing naming is ambiguous. Renaming delivery to encoding and flavor to framework should clarify the intent.
* exported names have changed
* removed deprecated client API
* (previous one didn't take due to semantic-release misalignment)

# Changelog

All notable changes to the MCP UI Python Server SDK will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [0.1.0](https://github.com/idosal/mcp-ui/releases/tag/python-server-sdk/v0.1.0) (2025-10-25)

Initial release of the MCP UI Python Server SDK.

### Features

* Initial implementation of MCP UI Server SDK for Python
* Support for HTML and Remote DOM resource types
* Type-safe API using Pydantic models
* Comprehensive resource creation and management utilities


================================================
FILE: sdks/python/server/README.md
================================================
# MCP UI Server SDK for Python

A Python SDK for creating MCP UI resources on the server side, enabling rich interactive experiences in MCP applications.

## Installation

```bash
pip install mcp-ui-server
```

## Quick Start

```python
from mcp_ui_server import create_ui_resource

# Create an HTML resource
resource = create_ui_resource({
    "uri": "ui://my-component",
    "content": {
        "type": "rawHtml",
        "htmlString": "<h1>Hello MCP UI!</h1>"
    },
    "encoding": "text"
})

# Use in MCP tool result
tool_result = {
    "content": [resource.to_dict()]
}
```

## Features

### Resource Types

The SDK supports three main content types:

#### 1. Raw HTML
Direct HTML content for embedding in the UI:

```python
html_resource = create_ui_resource({
    "uri": "ui://html-example",
    "content": {
        "type": "rawHtml", 
        "htmlString": "<div><h1>Dynamic Content</h1><p>Generated server-side</p></div>"
    },
    "encoding": "text"  # or "blob" for base64 encoding
})
```

#### 2. External URLs
Embed external websites via iframe:

```python
url_resource = create_ui_resource({
    "uri": "ui://external-site",
    "content": {
        "type": "externalUrl",
        "iframeUrl": "https://example.com"
    },
    "encoding": "text"
})
```

#### 3. Remote DOM Components
Interactive components using React or Web Components:

```python
# React component
react_resource = create_ui_resource({
    "uri": "ui://react-component",
    "content": {
        "type": "remoteDom",
        "script": """
            function WeatherWidget({ location }) {
                return (
                    <div>
                        <h3>Weather for {location}</h3>
                        <p>Temperature: 72°F</p>
                    </div>
                );
            }
        """,
        "framework": "react"
    },
    "encoding": "text"
})

# Web Components
wc_resource = create_ui_resource({
    "uri": "ui://web-component", 
    "content": {
        "type": "remoteDom",
        "script": """
            class StatusIndicator extends HTMLElement {
                connectedCallback() {
                    this.innerHTML = `
                        <div style="color: green;">
                            ✅ System Online
                        </div>
                    `;
                }
            }
            customElements.define('status-indicator', StatusIndicator);
        """,
        "framework": "webcomponents"
    },
    "encoding": "blob"
})
```

### Encoding Options

Choose between text and blob encoding:

- **text**: Direct string content (recommended for development)
- **blob**: Base64-encoded content (recommended for production)

```python
# Text encoding - content stored as plain text
text_resource = create_ui_resource({
    "uri": "ui://text-example",
    "content": {"type": "rawHtml", "htmlString": "<p>Text content</p>"},
    "encoding": "text"
})

# Blob encoding - content base64 encoded
blob_resource = create_ui_resource({
    "uri": "ui://blob-example", 
    "content": {"type": "rawHtml", "htmlString": "<p>Blob content</p>"},
    "encoding": "blob"
})
```

### UI Metadata

Enhance resources with metadata for client-side handling. The SDK automatically prefixes UI-specific metadata with `mcpui.dev/ui-` to distinguish it from custom metadata.

#### Preferred Frame Size

Specify preferred dimensions for UI rendering:

```python
resource = create_ui_resource({
    "uri": "ui://chart",
    "content": {
        "type": "externalUrl",
        "iframeUrl": "https://charts.example.com/widget"
    },
    "encoding": "text",
    "uiMetadata": {
        "preferred-frame-size": [800, 600]  # width, height in pixels or css units
    }
})
```

#### Initial Render Data

Provide data to components at initialization:

```python
resource = create_ui_resource({
    "uri": "ui://dashboard",
    "content": {
        "type": "remoteDom",
        "script": """
            function Dashboard({ theme, userId }) {
                // Component receives initial data
                return <div>Dashboard for user {userId}</div>;
            }
        """,
        "framework": "react"
    },
    "encoding": "text",
    "uiMetadata": {
        "initial-render-data": {
            "theme": "dark",
            "userId": "123"
        }
    }
})
```

#### Multiple Metadata Fields

Combine multiple metadata fields:

```python
resource = create_ui_resource({
    "uri": "ui://data-viz",
    "content": {
        "type": "rawHtml",
        "htmlString": "<canvas id='chart'></canvas>"
    },
    "encoding": "text",
    "uiMetadata": {
        "preferred-frame-size": ["800px", "600px"],
        "initial-render-data": {
            "chartType": "bar",
            "dataSet": "quarterly-sales"
        }
    }
})
```

#### Custom Metadata

Add custom metadata alongside UI metadata:

```python
resource = create_ui_resource({
    "uri": "ui://custom-widget",
    "content": {
        "type": "rawHtml",
        "htmlString": "<div>Widget</div>"
    },
    "encoding": "text",
    "uiMetadata": {
        "preferred-frame-size": [640, 480]
    },
    "metadata": {
        "customKey": "customValue",
        "version": "1.0.0"
    }
})

# Result includes both prefixed UI metadata and custom metadata:
# {
#   "resource": {
#     "meta": {
#       "mcpui.dev/ui-preferred-frame-size": [640, 480],
#       "customKey": "customValue",
#       "version": "1.0.0"
#     }
#   }
# }
```

### UI Actions

Create action results for user interactions:

```python
from mcp_ui_server import (
    ui_action_result_tool_call,
    ui_action_result_prompt,
    ui_action_result_link,
    ui_action_result_intent,
    ui_action_result_notification
)

# Tool execution
tool_action = ui_action_result_tool_call("search_database", {
    "query": "user input",
    "limit": 10
})

# User prompt
prompt_action = ui_action_result_prompt("Enter search query:")

# External link
link_action = ui_action_result_link("https://docs.example.com")

# Intent trigger
intent_action = ui_action_result_intent("show_details", {
    "item_id": "123"
})

# Notification
notify_action = ui_action_result_notification("Search completed!")
```

## Advanced Usage

### MCP Integration

Convert UI resources for MCP tool results:

```python
from mcp_ui_server.utils import create_mcp_tool_result_content

# Create resource
resource = create_ui_resource({...})

# Convert to MCP format
mcp_content = create_mcp_tool_result_content(resource)

# Use in tool result
return {
    "content": [mcp_content],
    "isError": False
}
```

### HTML Enhancement

Automatically enhance HTML with communication capabilities:

```python
from mcp_ui_server.utils import wrap_html_with_communication

# Basic HTML
html = "<div>My content</div>"

# Enhanced with MCP UI communication
enhanced_html = wrap_html_with_communication(html)

# Use in resource
resource = create_ui_resource({
    "uri": "ui://enhanced-html",
    "content": {"type": "rawHtml", "htmlString": enhanced_html},
    "encoding": "text"
})
```

### Error Handling

The SDK provides specific exception types:

```python
from mcp_ui_server.exceptions import (
    MCPUIServerError,
    InvalidURIError,
    InvalidContentError,
    EncodingError
)

try:
    resource = create_ui_resource({
        "uri": "invalid://test",  # Must start with ui://
        "content": {"type": "rawHtml", "htmlString": "<p>Test</p>"},
        "encoding": "text"
    })
except InvalidURIError as e:
    print(f"URI validation failed: {e}")
except InvalidContentError as e:
    print(f"Content validation failed: {e}")
except MCPUIServerError as e:
    print(f"General SDK error: {e}")
```

## API Reference

### Core Functions

#### `create_ui_resource(options: CreateUIResourceOptions) -> UIResource`

Creates a UI resource from the given options.

**Parameters:**
- `options`: Configuration dictionary with `uri`, `content`, and `encoding`

**Returns:**
- `UIResource` instance ready for use in MCP tool results

#### Action Result Functions

- `ui_action_result_tool_call(tool_name: str, params: dict) -> UIActionResultToolCall`
- `ui_action_result_prompt(prompt: str) -> UIActionResultPrompt`
- `ui_action_result_link(url: str) -> UIActionResultLink`
- `ui_action_result_intent(intent: str, params: dict) -> UIActionResultIntent`
- `ui_action_result_notification(message: str) -> UIActionResultNotification`

### Types

#### `CreateUIResourceOptions`

```python
{
    "uri": str,  # Must start with "ui://"
    "content": Union[RawHtmlPayload, ExternalUrlPayload, RemoteDomPayload],
    "encoding": Literal["text", "blob"],
    "uiMetadata": Optional[dict[str, Any]],  # UI-specific metadata (auto-prefixed)
    "metadata": Optional[dict[str, Any]]     # Custom metadata
}
```

#### Content Payloads

```python
# Raw HTML
{
    "type": "rawHtml",
    "htmlString": str
}

# External URL
{
    "type": "externalUrl", 
    "iframeUrl": str
}

# Remote DOM
{
    "type": "remoteDom",
    "script": str,
    "framework": Literal["react", "webcomponents"]
}
```

## Examples

See the `examples/` directory for complete usage examples:

- `basic_server_usage.py`: Basic resource creation and action results
- `advanced_features.py`: Advanced patterns and integrations
- `mcp_tool_integration.py`: Complete MCP tool implementation

## Development

### Setup

```bash
# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
ruff check .
black .

# Type checking
mypy src/
```

### Project Structure

```
src/mcp_ui_server/
├── __init__.py          # Main exports
├── types.py             # Type definitions
├── core.py              # Core functionality
├── utils.py             # Utility functions
└── exceptions.py        # Custom exceptions
```

## License

Apache 2.0

## Contributing

See [CONTRIBUTING.md](../../CONTRIBUTING.md) for contribution guidelines.

================================================
FILE: sdks/python/server/pyproject.toml
================================================
[project]
name = "mcp-ui-server"
version = "1.0.0"
description = "mcp-ui Server SDK for Python"
readme = "README.md"
requires-python = ">=3.10"
dependencies = [
    "mcp>=1.0.0",
    "pydantic>=2.0.0",
    "typing-extensions>=4.0.0"
]
authors = [
    {name = "MCP UI Contributors"}
]
license = {text = "Apache-2.0"}
classifiers = [
    "Development Status :: 4 - Beta",
    "Intended Audience :: Developers",
    "License :: OSI Approved :: Apache Software License",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
]

[project.urls]
Homepage = "https://mcpui.dev"
Repository = "https://github.com/idosal/mcp-ui"
Documentation = "https://mcpui.dev/guide/introduction"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["src/mcp_ui_server"]

[tool.hatch.build.targets.sdist]
exclude = [
    "/.gitignore",
    "*.publish.attestation",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "ruff>=0.1.0",
    "pyright>=1.1.0",
]

[tool.ruff]
line-length = 120
target-version = "py310"
exclude = [
    "README.md"
]

[tool.ruff.lint]
select = ["C4", "E", "F", "I", "PERF", "UP"]
ignore = ["PERF203"]

[tool.ruff.lint.per-file-ignores]
"__init__.py" = ["F401"]

[tool.pyright]
include = ["src"]
exclude = ["**/__pycache__"]
pythonVersion = "3.10"
pythonPlatform = "All"
typeCheckingMode = "strict"

[dependency-groups]
dev = [
    "pyright>=1.1.403",
    "ruff>=0.12.9",
    "pytest>=7.0.0",
    "pytest-snapshot>=0.9.0",
    "twine>=5.0.0",
]

[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = "test_*.py"
python_classes = "Test*"
python_functions = "test_*"
addopts = "-v --tb=short"


================================================
FILE: sdks/python/server/release.config.js
================================================
module.exports = {
  branches: [
    'main',
    {
      name: 'alpha',
      prerelease: true,
    },
  ],
  repositoryUrl: 'https://github.com/idosal/mcp-ui',
  tagFormat: 'python-server-sdk/v${version}',
  plugins: [
    '@semantic-release/commit-analyzer',
    '@semantic-release/release-notes-generator',
    [
      '@semantic-release/changelog',
      {
        changelogFile: 'CHANGELOG.md',
      },
    ],
    [
      '@semantic-release/exec',
      {
        prepareCmd:
          'sed -i \'s/^version = ".*"/version = "${nextRelease.version}"/\' pyproject.toml && rm -f pyproject.toml.bak && uv sync && uv build',
        publishCmd: 'uv run twine upload --skip-existing dist/*',
      },
    ],
    '@semantic-release/github',
    [
      '@semantic-release/git',
      {
        assets: ['CHANGELOG.md', 'pyproject.toml', 'uv.lock'],
        message: 'chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}',
      },
    ],
  ],
};


================================================
FILE: sdks/python/server/src/mcp_ui_server/__init__.py
================================================
"""MCP UI Server SDK for Python.

This package provides server-side functionality for creating MCP UI resources.
"""

from .core import (
    UIResource,
    create_ui_resource,
    ui_action_result_intent,
    ui_action_result_link,
    ui_action_result_notification,
    ui_action_result_prompt,
    ui_action_result_tool_call,
)
from .types import (
    RESOURCE_MIME_TYPE,
    URI,
    CreateUIResourceOptions,
    MimeType,
    ResourceContentPayload,
    UIActionResult,
    UIActionResultIntent,
    UIActionResultLink,
    UIActionResultNotification,
    UIActionResultPrompt,
    UIActionResultToolCall,
    UIActionType,
    UIMetadataKey,
)

__version__ = "5.2.0"

__all__ = [
    "URI",
    "MimeType",
    "RESOURCE_MIME_TYPE",
    "ResourceContentPayload",
    "CreateUIResourceOptions",
    "UIActionType",
    "UIActionResult",
    "UIActionResultToolCall",
    "UIActionResultPrompt",
    "UIActionResultLink",
    "UIActionResultIntent",
    "UIActionResultNotification",
    "UIMetadataKey",
    "UIResource",
    "create_ui_resource",
    "ui_action_result_tool_call",
    "ui_action_result_prompt",
    "ui_action_result_link",
    "ui_action_result_intent",
    "ui_action_result_notification",
]

================================================
FILE: sdks/python/server/src/mcp_ui_server/core.py
================================================
"""Core functionality for MCP UI Server SDK."""

import base64
from typing import Any

from mcp.types import BlobResourceContents, EmbeddedResource, TextResourceContents
from pydantic import AnyUrl

from .exceptions import InvalidContentError, InvalidURIError
from .types import (
    RESOURCE_MIME_TYPE,
    UI_METADATA_PREFIX,
    CreateUIResourceOptions,
    ExternalUrlPayload,
    RawHtmlPayload,
    UIActionResultIntent,
    UIActionResultLink,
    UIActionResultNotification,
    UIActionResultPrompt,
    UIActionResultToolCall,
)


class UIResource(EmbeddedResource):
    """Represents a UI resource that can be included in tool results."""

    def __init__(self, resource: TextResourceContents | BlobResourceContents, **kwargs: Any):
        # Initialize with resource content
        super().__init__(
            type="resource",
            resource=resource,
            **kwargs
        )


def _get_additional_resource_props(options: CreateUIResourceOptions) -> dict[str, Any]:
    """Get additional resource properties including metadata.

    Prefixes UI-specific metadata with the UI metadata prefix to be recognized by the client.

    Args:
        options: The UI resource options

    Returns:
        Dictionary of additional properties to merge into the resource
    """
    additional_props: dict[str, Any] = {}

    # Prefix ui specific metadata with the prefix to be recognized by the client
    if options.uiMetadata or options.metadata:
        ui_prefixed_metadata: dict[str, Any] = {}

        if options.uiMetadata:
            for key, value in options.uiMetadata.items():
                ui_prefixed_metadata[f"{UI_METADATA_PREFIX}{key}"] = value

        # Allow user defined metadata to override ui metadata
        _meta: dict[str, Any] = {
            **ui_prefixed_metadata,
            **(options.metadata or {}),
        }

        if _meta:
            additional_props["_meta"] = _meta

    return additional_props


def create_ui_resource(options_dict: dict[str, Any]) -> UIResource:
    """Create a UIResource.

    This is the object that should be included in the 'content' array of a toolResult.

    Args:
        options_dict: Configuration dictionary for the interactive resource. Keys:
            - uri (str): Resource identifier starting with 'ui://'
            - content (dict): Content payload (type: rawHtml or externalUrl)
            - encoding (str): 'text' or 'blob'
            - uiMetadata (dict, optional): UI metadata. Use UIMetadataKey constants:
                * UIMetadataKey.PREFERRED_FRAME_SIZE: list[str, str] - CSS dimensions like ["800px", "600px"]
                * UIMetadataKey.INITIAL_RENDER_DATA: dict - Initial data for the UI
            - metadata (dict, optional): Custom metadata (not prefixed)

    Returns:
        A UIResource instance ready to be included in tool results

    Raises:
        InvalidURIError: If the URI doesn't start with 'ui://'
        InvalidContentError: If content validation fails
        MCPUIServerError: For other errors

    Example:
        >>> from mcp_ui_server import create_ui_resource, UIMetadataKey
        >>> resource = create_ui_resource({
        ...     "uri": "ui://my-widget",
        ...     "content": {"type": "rawHtml", "htmlString": "<h1>Hello</h1>"},
        ...     "encoding": "text",
        ...     "uiMetadata": {
        ...         UIMetadataKey.PREFERRED_FRAME_SIZE: ["800px", "600px"]
        ...     }
        ... })
    """
    options = CreateUIResourceOptions.model_validate(options_dict)
    # Validate URI
    if not options.uri.startswith("ui://"):
        raise InvalidURIError(f"URI must start with 'ui://' but got: {options.uri}")

    content = options.content
    content_type = content.type

    # Determine content string and MIME type based on content type
    if content_type == "rawHtml":
        if not isinstance(content, RawHtmlPayload):
            raise InvalidContentError("Content must be RawHtmlPayload when type is 'rawHtml'")
        htmlString = content.htmlString
        if not htmlString:
            raise InvalidContentError(
                "htmlString must be provided as a non-empty string when content.type is 'rawHtml'"
            )
        actual_content_string = htmlString
        mime_type = RESOURCE_MIME_TYPE

    elif content_type == "externalUrl":
        if not isinstance(content, ExternalUrlPayload):
            raise InvalidContentError("Content must be ExternalUrlPayload when type is 'externalUrl'")
        iframe_url = content.iframeUrl
        if not iframe_url:
            raise InvalidContentError(
                "content.iframeUrl must be provided as a non-empty string when content.type is 'externalUrl'"
            )
        actual_content_string = iframe_url
        mime_type = RESOURCE_MIME_TYPE

    else:
        # This should be prevented by TypeScript/mypy, but handle gracefully
        raise InvalidContentError(f"Invalid content.type specified: {content_type}")

    # Create resource based on encoding type
    encoding = options.encoding

    # Get additional properties including metadata
    additional_props = _get_additional_resource_props(options)

    if encoding == "text":
        resource: TextResourceContents | BlobResourceContents = TextResourceContents(
            uri=AnyUrl(options.uri),
            mimeType=mime_type,
            text=actual_content_string,
            **additional_props,
        )
    elif encoding == "blob":
        resource = BlobResourceContents(
            uri=AnyUrl(options.uri),
            mimeType=mime_type,
            blob=base64.b64encode(actual_content_string.encode('utf-8')).decode('ascii'),
            **additional_props,
        )
    else:
        raise InvalidContentError(f"Invalid encoding type: {encoding}")

    return UIResource(resource=resource)



# UI Action Result Helper Functions

def ui_action_result_tool_call(
    tool_name: str, params: dict[str, Any]
) -> UIActionResultToolCall:
    """Create a tool call UI action result.

    Args:
        tool_name: Name of the tool to call
        params: Parameters for the tool call

    Returns:
        UIActionResultToolCall instance
    """
    return UIActionResultToolCall(
        type="tool",
        payload=UIActionResultToolCall.ToolCallPayload(
            toolName=tool_name,
            params=params,
        ),
    )


def ui_action_result_prompt(prompt: str) -> UIActionResultPrompt:
    """Create a prompt UI action result.

    Args:
        prompt: The prompt message

    Returns:
        UIActionResultPrompt instance
    """
    return UIActionResultPrompt(
        type="prompt",
        payload=UIActionResultPrompt.PromptPayload(
            prompt=prompt,
        ),
    )


def ui_action_result_link(url: str) -> UIActionResultLink:
    """Create a link UI action result.

    Args:
        url: The URL to link to

    Returns:
        UIActionResultLink instance
    """
    return UIActionResultLink(
        type="link",
        payload=UIActionResultLink.LinkPayload(
            url=url,
        ),
    )


def ui_action_result_intent(
    intent: str, params: dict[str, Any]
) -> UIActionResultIntent:
    """Create an intent UI action result.

    Args:
        intent: The intent identifier
        params: Parameters for the intent

    Returns:
        UIActionResultIntent instance
    """
    return UIActionResultIntent(
        type="intent",
        payload=UIActionResultIntent.IntentPayload(
            intent=intent,
            params=params,
        ),
    )


def ui_action_result_notification(message: str) -> UIActionResultNotification:
    """Create a notification UI action result.

    Args:
        message: The notification message

    Returns:
        UIActionResultNotification instance
    """
    return UIActionResultNotification(
        type="notify",
        payload=UIActionResultNotification.NotificationPayload(
            message=message,
        ),
    )


================================================
FILE: sdks/python/server/src/mcp_ui_server/exceptions.py
================================================
"""Custom exceptions for MCP UI Server SDK."""


class MCPUIServerError(Exception):
    """Base exception for MCP UI Server SDK errors."""
    pass


class InvalidURIError(MCPUIServerError):
    """Error raised when URI validation fails."""
    pass


class InvalidContentError(MCPUIServerError):
    """Error raised when content validation fails."""
    pass


class EncodingError(MCPUIServerError):
    """Error raised when encoding operations fail."""
    pass

================================================
FILE: sdks/python/server/src/mcp_ui_server/types.py
================================================
"""Type definitions for MCP UI Server SDK."""

from typing import Any, Literal

from pydantic import BaseModel

# Primary identifier for the resource. Starts with ui://
URI = str  # In TypeScript: `ui://${string}`, but Python doesn't have template literal types

# MIME type for MCP Apps resources (used for both HTML and URL content)
RESOURCE_MIME_TYPE = "text/html;profile=mcp-app"

MimeType = Literal["text/html;profile=mcp-app"]

UIActionType = Literal["tool", "prompt", "link", "intent", "notify"]


class RawHtmlPayload(BaseModel):
    """Raw HTML content payload."""
    type: Literal["rawHtml"]
    htmlString: str


class ExternalUrlPayload(BaseModel):
    """External URL content payload."""
    type: Literal["externalUrl"]
    iframeUrl: str


ResourceContentPayload = RawHtmlPayload | ExternalUrlPayload


# UI Metadata constants
UI_METADATA_PREFIX = "mcpui.dev/ui-"


class UIMetadataKey:
    """Keys for UI metadata with their expected value types.

    These constants should be used as keys in the uiMetadata dictionary to avoid typos
    and improve code maintainability.

    Attributes:
        PREFERRED_FRAME_SIZE: Key for specifying preferred iframe dimensions.
            - Expected value type: list[str, str] or tuple[str, str]
            - Format: [width, height] as CSS dimension strings
            - Examples:
                * ["800px", "600px"] - Fixed pixel dimensions
                * ["100%", "50vh"] - Responsive with percentage and viewport height
                * ["50rem", "80%"] - Relative and percentage units
            - Important: Must be strings with CSS units (px, %, vh, vw, rem, em, etc.)
            - Applied directly to iframe's CSS width and height properties

        INITIAL_RENDER_DATA: Key for passing initial data to the UI component.
            - Expected value type: dict[str, Any]
            - Format: Any JSON-serializable dictionary
            - Examples:
                * {"user": {"id": "123", "name": "John"}}
                * {"config": {"theme": "dark", "language": "en"}}
            - Data is passed to the iframe on initial render

    Example usage:
        ```python
        from mcp_ui_server import create_ui_resource, UIMetadataKey

        ui_resource = create_ui_resource({
            "uri": "ui://my-component",
            "content": {"type": "rawHtml", "htmlString": "<h1>Hello</h1>"},
            "encoding": "text",
            "uiMetadata": {
                UIMetadataKey.PREFERRED_FRAME_SIZE: ["800px", "600px"],
                UIMetadataKey.INITIAL_RENDER_DATA: {"user": {"id": "123"}}
            }
        })
        ```
    """
    PREFERRED_FRAME_SIZE = "preferred-frame-size"
    INITIAL_RENDER_DATA = "initial-render-data"


class CreateUIResourceOptions(BaseModel):
    """Options for creating a UI resource.

    Attributes:
        uri: The resource identifier. Must start with 'ui://'
        content: The resource content payload (rawHtml or externalUrl)
        encoding: Whether to encode as 'text' or 'blob' (base64)
        uiMetadata: UI-specific metadata that will be prefixed with 'mcpui.dev/ui-'
            Use UIMetadataKey constants for type-safe keys:
            - UIMetadataKey.PREFERRED_FRAME_SIZE: list[str, str] - CSS dimensions
            - UIMetadataKey.INITIAL_RENDER_DATA: dict[str, Any] - Initial data
        metadata: Custom metadata (not prefixed). Merged with prefixed uiMetadata.
            Example: {"custom.author": "Server Name", "custom.version": "1.0.0"}
    """
    uri: URI
    content: ResourceContentPayload
    encoding: Literal["text", "blob"]
    uiMetadata: dict[str, Any] | None = None
    metadata: dict[str, Any] | None = None


class GenericActionMessage(BaseModel):
    """Base message structure for UI actions."""
    messageId: str | None = None


class UIActionResultToolCall(GenericActionMessage):
    """Tool call action result."""

    class ToolCallPayload(BaseModel):
        """Payload for tool call actions."""
        toolName: str

        params: dict[str, Any]

    type: Literal["tool"]
    payload: ToolCallPayload


class UIActionResultPrompt(GenericActionMessage):
    """Prompt action result."""

    class PromptPayload(BaseModel):
        """Payload for prompt actions."""
        prompt: str

    type: Literal["prompt"]
    payload: PromptPayload


class UIActionResultLink(GenericActionMessage):
    """Link action result."""

    class LinkPayload(BaseModel):
        """Payload for link actions."""
        url: str

    type: Literal["link"]
    payload: LinkPayload


class UIActionResultIntent(GenericActionMessage):
    """Intent action result."""

    class IntentPayload(BaseModel):
        """Payload for intent actions."""
        intent: str
        params: dict[str, Any]

    type: Literal["intent"]
    payload: IntentPayload


class UIActionResultNotification(GenericActionMessage):
    """Notification action result."""

    class NotificationPayload(BaseModel):
        """Payload for notification actions."""
        message: str

    type: Literal["notify"]
    payload: NotificationPayload


UIActionResult = (
    UIActionResultToolCall
    | UIActionResultPrompt
    | UIActionResultLink
    | UIActionResultIntent
    | UIActionResultNotification
)


================================================
FILE: sdks/python/server/src/mcp_ui_server/utils.py
================================================
"""Utility functions for MCP UI Server SDK."""

import json
from typing import TYPE_CHECKING, Any, cast

from .types import UIActionResult

if TYPE_CHECKING:
    from .core import UIResource


def validate_uri(uri: str) -> bool:
    """Validate that a URI starts with 'ui://'.
    
    Args:
        uri: The URI to validate
        
    Returns:
        True if valid, False otherwise
    """
    return uri.startswith("ui://")


def serialize_ui_resource(ui_resource: "UIResource") -> dict[str, Any]:
    """Serialize a UIResource to a dictionary.
    
    Args:
        ui_resource: The UIResource instance
        
    Returns:
        Dictionary representation suitable for JSON serialization
    """
    return ui_resource.model_dump()


def serialize_ui_action_result(action_result: UIActionResult) -> str:
    """Serialize a UI action result to JSON.
    
    Args:
        action_result: The action result to serialize
        
    Returns:
        JSON string representation
    """
    return action_result.model_dump_json()


def deserialize_ui_action_result(json_str: str) -> UIActionResult:
    """Deserialize a UI action result from JSON.
    
    Args:
        json_str: JSON string to deserialize
        
    Returns:
        UIActionResult instance
        
    Raises:
        ValueError: If JSON is invalid or doesn't match expected format
    """
    from .types import (
        UIActionResultIntent,
        UIActionResultLink,
        UIActionResultNotification,
        UIActionResultPrompt,
        UIActionResultToolCall,
    )
    
    try:
        data = json.loads(json_str)
        
        # Basic validation
        if not isinstance(data, dict) or "type" not in data or "payload" not in data:
            raise ValueError("Invalid UI action result format")
        
        action_type = cast(str, data["type"])
        
        # Deserialize based on type
        if action_type == "tool":
            return UIActionResultToolCall.model_validate(data)
        elif action_type == "prompt":
            return UIActionResultPrompt.model_validate(data)
        elif action_type == "link":
            return UIActionResultLink.model_validate(data)
        elif action_type == "intent":
            return UIActionResultIntent.model_validate(data)
        elif action_type == "notify":
            return UIActionResultNotification.model_validate(data)
        else:
            raise ValueError(f"Invalid action type: {action_type}")
        
    except json.JSONDecodeError as e:
        raise ValueError(f"Invalid JSON: {e}") from e


class ReservedUrlParams:
    """Reserved URL parameters for MCP UI."""
    WAIT_FOR_RENDER_DATA = "waitForRenderData"


class InternalMessageType:
    """Internal message types for MCP UI communication."""
    UI_MESSAGE_RECEIVED = "ui-message-received"
    UI_MESSAGE_RESPONSE = "ui-message-response"
    UI_SIZE_CHANGE = "ui-size-change"
    UI_LIFECYCLE_IFRAME_READY = "ui-lifecycle-iframe-ready"
    UI_LIFECYCLE_IFRAME_RENDER_DATA = "ui-lifecycle-iframe-render-data"


def create_iframe_communication_script() -> str:
    """Create JavaScript code for iframe communication.
    
    This generates the JavaScript needed for UI resources to communicate
    with the parent frame.
    
    Returns:
        JavaScript code as a string
    """
    return """
// MCP UI communication script
(function() {
    window.mcpUI = {
        postMessage: function(data) {
            if (window.parent) {
                window.parent.postMessage(data, '*');
            }
        },
        
        onMessage: function(callback) {
            window.addEventListener('message', function(event) {
                callback(event.data);
            });
        }
    };
})();
"""

def wrap_html_with_communication(html_content: str, include_script: bool = True) -> str:
    """Wrap HTML content with MCP UI communication capabilities.
    
    Args:
        html_content: The HTML content to wrap
        include_script: Whether to include the communication script
        
    Returns:
        Enhanced HTML with communication capabilities
    """
    if not include_script:
        return html_content
    
    script = create_iframe_communication_script()
    
    # If HTML already has a head tag, insert script there
    if "<head>" in html_content:
        return html_content.replace(
            "<head>",
            f"<head><script>{script}</script>"
        )
    
    # If HTML has html tag but no head, add head
    if "<html>" in html_content:
        return html_content.replace(
            "<html>",
            f"<html><head><script>{script}</script></head>"
        )
    
    # Otherwise, wrap the entire content
    return f"""<!DOCTYPE html>
<html>
<head>
    <script>{script}</script>
</head>
<body>
{html_content}
</body>
</html>"""

================================================
FILE: sdks/python/server/tests/__init__.py
================================================
"""Test suite for MCP UI Server SDK."""

================================================
FILE: sdks/python/server/tests/test_create_ui_resource.py
================================================
"""Tests for create_ui_resource functionality."""

import base64

import pytest
from pydantic import AnyUrl, ValidationError

from mcp_ui_server import create_ui_resource
from mcp_ui_server.exceptions import InvalidContentError, InvalidURIError


@pytest.fixture
def raw_html_text_options():
    """Fixture for raw HTML text-based options."""
    return {
        "uri": "ui://test-html",
        "content": {"type": "rawHtml", "htmlString": "<p>Test</p>"},
        "encoding": "text",
    }


@pytest.fixture
def raw_html_blob_options():
    """Fixture for raw HTML blob-based options."""
    return {
        "uri": "ui://test-html-blob",
        "content": {"type": "rawHtml", "htmlString": "<h1>Blob</h1>"},
        "encoding": "blob",
    }


@pytest.fixture
def external_url_text_options():
    """Fixture for external URL text-based options."""
    return {
        "uri": "ui://test-url",
        "content": {
            "type": "externalUrl",
            "iframeUrl": "https://example.com",
        },
        "encoding": "text",
    }


@pytest.fixture
def external_url_blob_options():
    """Fixture for external URL blob-based options."""
    return {
        "uri": "ui://test-url-blob",
        "content": {
            "type": "externalUrl",
            "iframeUrl": "https://example.com/blob",
        },
        "encoding": "blob",
    }


class TestCreateUIResource:
    """Test suite for create_ui_resource function."""

    def test_create_text_based_raw_html_resource(self, raw_html_text_options):
        """Test creating a text-based raw HTML resource."""
        resource = create_ui_resource(raw_html_text_options)
        expected = {
            "meta": None,
            "annotations": None,
            "type": "resource",
            "resource": {
                "meta": None,
                "uri": AnyUrl("ui://test-html"),
                "mimeType": "text/html;profile=mcp-app",
                "text": "<p>Test</p>",
            }
        }
        assert resource.model_dump() == expected

    def test_create_blob_based_raw_html_resource(self, raw_html_blob_options):
        """Test creating a blob-based raw HTML resource."""
        resource = create_ui_resource(raw_html_blob_options)
        expected = {
            "meta": None,
            "annotations": None,
            "type": "resource",
            "resource": {
                "meta": None,
                "uri": AnyUrl("ui://test-html-blob"),
                "mimeType": "text/html;profile=mcp-app",
                "blob": base64.b64encode(b"<h1>Blob</h1>").decode("ascii"),
            }
        }
        assert resource.model_dump() == expected

    def test_create_text_based_external_url_resource(self, external_url_text_options):
        """Test creating a text-based external URL resource."""
        resource = create_ui_resource(external_url_text_options)
        expected = {
            "meta": None,
            "annotations": None,
            "type": "resource",
            "resource": {
                "meta": None,
                "uri": AnyUrl("ui://test-url"),
                "mimeType": "text/html;profile=mcp-app",
                "text": "https://example.com",
            }
        }
        assert resource.model_dump() == expected

    def test_create_blob_based_external_url_resource(self, external_url_blob_options):
        """Test creating a blob-based external URL resource."""
        resource = create_ui_resource(external_url_blob_options)
        expected = {
            "meta": None,
            "annotations": None,
            "type": "resource",
            "resource": {
                "meta": None,
                "uri": AnyUrl("ui://test-url-blob"),
                "mimeType": "text/html;profile=mcp-app",
                "blob": base64.b64encode(b"https://example.com/blob").decode("ascii"),
            }
        }
        assert resource.model_dump() == expected


class TestCreateUIResourceValidationErrors:
    """Test suite for create_ui_resource validation errors."""

    def test_invalid_uri_prefix_with_raw_html(self):
        """Test error for invalid URI prefix with rawHtml."""
        options = {
            "uri": "invalid://test-html",
            "content": {"type": "rawHtml", "htmlString": "<p>Test</p>"},
            "encoding": "text",
        }
        with pytest.raises(InvalidURIError, match="URI must start with 'ui://'"):
            create_ui_resource(options)

    def test_invalid_uri_prefix_with_external_url(self):
        """Test error for invalid URI prefix with externalUrl."""
        options = {
            "uri": "invalid://test-url",
            "content": {
                "type": "externalUrl",
                "iframeUrl": "https://example.com",
            },
            "encoding": "text",
        }
        with pytest.raises(InvalidURIError, match="URI must start with 'ui://'"):
            create_ui_resource(options)

    def test_empty_html_string_error(self):
        """Test error when htmlString is empty for rawHtml."""
        options = {
            "uri": "ui://test",
            "content": {"type": "rawHtml", "htmlString": ""},
            "encoding": "text",
        }
        with pytest.raises(InvalidContentError, match="htmlString must be provided as a non-empty string"):
            create_ui_resource(options)

    def test_empty_iframe_url_error(self):
        """Test error when iframeUrl is empty for externalUrl."""
        options = {
            "uri": "ui://test",
            "content": {"type": "externalUrl", "iframeUrl": ""},
            "encoding": "text",
        }
        with pytest.raises(InvalidContentError, match="content.iframeUrl must be provided as a non-empty string"):
            create_ui_resource(options)

    def test_invalid_encoding_error(self):
        """Test error when encoding is invalid."""
        options = {
            "uri": "ui://test",
            "content": {"type": "rawHtml", "htmlString": "<p>Test</p>"},
            "encoding": "base64",
        }
        with pytest.raises(ValidationError, match="Input should be 'text' or 'blob'"):
            create_ui_resource(options)


================================================
FILE: sdks/python/server/tests/test_metadata.py
================================================
"""Tests for UI metadata functionality."""

import pytest

from mcp_ui_server import create_ui_resource
from mcp_ui_server.types import UI_METADATA_PREFIX


@pytest.fixture
def basic_raw_html_options():
    """Fixture for basic raw HTML options."""
    return {
        "uri": "ui://test-html",
        "content": {"type": "rawHtml", "htmlString": "<p>Test</p>"},
        "encoding": "text",
    }


class TestUIMetadata:
    """Test suite for UI metadata functionality."""

    def test_create_resource_with_ui_metadata(self, basic_raw_html_options):
        """Test creating a resource with uiMetadata."""
        options = {
            **basic_raw_html_options,
            "uiMetadata": {
                "preferred-frame-size": [800, 600],
            }
        }
        resource = create_ui_resource(options)

        result = resource.model_dump()

        # Check that metadata is properly prefixed and included (meta field, serializes to _meta with by_alias=True)
        assert result["resource"]["meta"] is not None
        assert f"{UI_METADATA_PREFIX}preferred-frame-size" in result["resource"]["meta"]
        assert result["resource"]["meta"][f"{UI_METADATA_PREFIX}preferred-frame-size"] == [800, 600]

        # Also verify by_alias=True serialization produces _meta
        result_with_alias = resource.model_dump(by_alias=True)
        assert "_meta" in result_with_alias["resource"]
        assert result_with_alias["resource"]["_meta"][f"{UI_METADATA_PREFIX}preferred-frame-size"] == [800, 600]

    def test_create_resource_with_multiple_ui_metadata_fields(self, basic_raw_html_options):
        """Test creating a resource with multiple uiMetadata fields."""
        options = {
            **basic_raw_html_options,
            "uiMetadata": {
                "preferred-frame-size": ["800px", "600px"],
                "initial-render-data": {
                    "theme": "dark",
                    "chartType": "bar",
                }
            }
        }
        resource = create_ui_resource(options)

        result = resource.model_dump()

        # Check that all metadata fields are properly prefixed and included
        assert result["resource"]["meta"] is not None
        assert f"{UI_METADATA_PREFIX}preferred-frame-size" in result["resource"]["meta"]
        assert result["resource"]["meta"][f"{UI_METADATA_PREFIX}preferred-frame-size"] == ["800px", "600px"]
        assert f"{UI_METADATA_PREFIX}initial-render-data" in result["resource"]["meta"]
        assert result["resource"]["meta"][f"{UI_METADATA_PREFIX}initial-render-data"] == {
            "theme": "dark",
            "chartType": "bar",
        }

    def test_create_resource_with_custom_metadata(self, basic_raw_html_options):
        """Test creating a resource with custom metadata (non-UI)."""
        options = {
            **basic_raw_html_options,
            "metadata": {
                "customKey": "customValue",
                "anotherKey": 123,
            }
        }
        resource = create_ui_resource(options)

        result = resource.model_dump()

        # Check that custom metadata is included without prefix
        assert result["resource"]["meta"] is not None
        assert result["resource"]["meta"]["customKey"] == "customValue"
        assert result["resource"]["meta"]["anotherKey"] == 123

    def test_create_resource_with_both_ui_and_custom_metadata(self, basic_raw_html_options):
        """Test creating a resource with both uiMetadata and custom metadata."""
        options = {
            **basic_raw_html_options,
            "uiMetadata": {
                "preferred-frame-size": [800, 600],
            },
            "metadata": {
                "customKey": "customValue",
            }
        }
        resource = create_ui_resource(options)

        result = resource.model_dump()

        # Check that both types of metadata are included
        assert result["resource"]["meta"] is not None
        assert f"{UI_METADATA_PREFIX}preferred-frame-size" in result["resource"]["meta"]
        assert result["resource"]["meta"][f"{UI_METADATA_PREFIX}preferred-frame-size"] == [800, 600]
        assert result["resource"]["meta"]["customKey"] == "customValue"

    def test_metadata_override_behavior(self, basic_raw_html_options):
        """Test that custom metadata can override ui metadata if keys conflict."""
        options = {
            **basic_raw_html_options,
            "uiMetadata": {
                "preferred-frame-size": [800, 600],
            },
            "metadata": {
                f"{UI_METADATA_PREFIX}preferred-frame-size": [1024, 768],
            }
        }
        resource = create_ui_resource(options)

        result = resource.model_dump()

        # Custom metadata should override UI metadata
        assert result["resource"]["meta"] is not None
        assert result["resource"]["meta"][f"{UI_METADATA_PREFIX}preferred-frame-size"] == [1024, 768]

    def test_create_resource_without_metadata(self, basic_raw_html_options):
        """Test creating a resource without any metadata."""
        resource = create_ui_resource(basic_raw_html_options)

        result = resource.model_dump()

        # No metadata should be present
        assert result["resource"]["meta"] is None

    def test_metadata_with_external_url_content(self):
        """Test metadata with external URL content type."""
        options = {
            "uri": "ui://test-url",
            "content": {
                "type": "externalUrl",
                "iframeUrl": "https://example.com",
            },
            "encoding": "text",
            "uiMetadata": {
                "preferred-frame-size": ["100%", "500px"],
            }
        }
        resource = create_ui_resource(options)

        result = resource.model_dump()

        assert result["resource"]["meta"] is not None
        assert f"{UI_METADATA_PREFIX}preferred-frame-size" in result["resource"]["meta"]
        assert result["resource"]["meta"][f"{UI_METADATA_PREFIX}preferred-frame-size"] == ["100%", "500px"]

    def test_metadata_with_blob_encoding(self):
        """Test metadata with blob encoding."""
        options = {
            "uri": "ui://test-blob",
            "content": {"type": "rawHtml", "htmlString": "<h1>Blob</h1>"},
            "encoding": "blob",
            "uiMetadata": {
                "preferred-frame-size": [640, 480],
            }
        }
        resource = create_ui_resource(options)

        result = resource.model_dump()

        # Verify metadata is present with blob encoding
        assert result["resource"]["meta"] is not None
        assert f"{UI_METADATA_PREFIX}preferred-frame-size" in result["resource"]["meta"]
        assert result["resource"]["meta"][f"{UI_METADATA_PREFIX}preferred-frame-size"] == [640, 480]
        # Verify blob is also present
        assert "blob" in result["resource"]

    def test_empty_ui_metadata_dict(self, basic_raw_html_options):
        """Test creating a resource with empty uiMetadata dict."""
        options = {
            **basic_raw_html_options,
            "uiMetadata": {}
        }
        resource = create_ui_resource(options)

        result = resource.model_dump()

        # Empty metadata dict should not create meta field
        assert result["resource"]["meta"] is None

    def test_empty_custom_metadata_dict(self, basic_raw_html_options):
        """Test creating a resource with empty custom metadata dict."""
        options = {
            **basic_raw_html_options,
            "metadata": {}
        }
        resource = create_ui_resource(options)

        result = resource.model_dump()

        # Empty metadata dict should not create meta field
        assert result["resource"]["meta"] is None


================================================
FILE: sdks/python/server/tests/test_ui_action_results.py
================================================
"""Tests for UI action result helper functions."""


from mcp_ui_server import (
    ui_action_result_intent,
    ui_action_result_link,
    ui_action_result_notification,
    ui_action_result_prompt,
    ui_action_result_tool_call,
)


class TestUIActionResultHelpers:
    """Test suite for UI action result helper functions."""

    def test_ui_action_result_tool_call(self):
        """Test creating a tool call action result."""
        result = ui_action_result_tool_call("testTool", {"param1": "value1"})
        expected = {
            "type": "tool",
            "payload": {
                "toolName": "testTool",
                "params": {"param1": "value1"},
            },
            "messageId": None,
        }
        assert result.model_dump() == expected

    def test_ui_action_result_prompt(self):
        """Test creating a prompt action result."""
        result = ui_action_result_prompt("Enter your name")
        expected = {
            "type": "prompt",
            "payload": {
                "prompt": "Enter your name",
            },
            "messageId": None,
        }
        assert result.model_dump() == expected

    def test_ui_action_result_link(self):
        """Test creating a link action result."""
        result = ui_action_result_link("https://example.com")
        expected = {
            "type": "link",
            "payload": {
                "url": "https://example.com",
            },
            "messageId": None,
        }
        assert result.model_dump() == expected

    def test_ui_action_result_intent(self):
        """Test creating an intent action result."""
        result = ui_action_result_intent("doSomething", {"data": "abc"})
        expected = {
            "type": "intent",
            "payload": {
                "intent": "doSomething",
                "params": {"data": "abc"},
            },
            "messageId": None,
        }
        assert result.model_dump() == expected

    def test_ui_action_result_notification(self):
        """Test creating a notification action result."""
        result = ui_action_result_notification("Success!")
        expected = {
            "type": "notify",
            "payload": {
                "message": "Success!",
            },
            "messageId": None,
        }
        assert result.model_dump() == expected

    def test_ui_action_result_tool_call_with_complex_params(self):
        """Test tool call action result with complex parameters."""
        complex_params = {
            "nested": {"key": "value"},
            "list": [1, 2, 3],
            "boolean": True,
            "number": 42,
        }
        result = ui_action_result_tool_call("complexTool", complex_params)
        expected = {
            "type": "tool",
            "payload": {
                "toolName": "complexTool",
                "params": complex_params,
            },
            "messageId": None,
        }
        assert result.model_dump() == expected

    def test_ui_action_result_intent_with_empty_params(self):
        """Test intent action result with empty parameters."""
        result = ui_action_result_intent("simpleIntent", {})
        expected = {
            "type": "intent",
            "payload": {
                "intent": "simpleIntent",
                "params": {},
            },
            "messageId": None,
        }
        assert result.model_dump() == expected

================================================
FILE: sdks/ruby/.rspec
================================================
--require spec_helper
--color
--format documentation

================================================
FILE: sdks/ruby/.rubocop.yml
================================================
AllCops:
  NewCops: enable
  Exclude:
    - 'bin/*'
    - 'vendor/**/*'
    - 'tmp/**/*'

plugins:
  - rubocop-rake
  - rubocop-rspec

Style/StringLiterals:
  EnforcedStyle: single_quotes

Style/Documentation:
  Enabled: false

Gemspec/DevelopmentDependencies:
  Enabled: false

Metrics/BlockLength:
  Exclude:
    - 'spec/**/*.rb'
    - '*.gemspec'

RSpec/MultipleExpectations:
  Enabled: false


================================================
FILE: sdks/ruby/CHANGELOG.md
================================================
## [1.0.1](https://github.com/idosal/mcp-ui/compare/ruby-server-sdk/v1.0.0...ruby-server-sdk/v1.0.1) (2025-07-19)


### Bug Fixes

* Ruby comment ([b22dc2e](https://github.com/idosal/mcp-ui/commit/b22dc2e0a0db20d98ada884649ad408ebaf72d22))


================================================
FILE: sdks/ruby/Gemfile
================================================
# frozen_string_literal: true

source 'https://rubygems.org'

gemspec


================================================
FILE: sdks/ruby/README.md
================================================
# MCP UI Server SDK for Ruby

This is the Ruby server-side SDK for MCP UI. It provides helper methods to create UI resources that can be sent to the mcp-ui client.

## Installation

Add this line to your application's Gemfile:

```ruby
gem 'mcp_ui_server', git: 'https://github.com/idosal/mcp-ui'
```

And then execute:

    $ bundle install

## Usage

The main method is `McpUiServer.create_ui_resource`. It helps you construct a valid UIResource hash.

### URI Requirements

All UI resources must use the `ui://` URI scheme. The SDK will validate it and raise a `McpUiServer::Error` if an invalid URI is provided.

```ruby
# Valid URI
McpUiServer.create_ui_resource(uri: 'ui://my-app/greeting', ...)

# Invalid URI - will raise McpUiServer::Error
McpUiServer.create_ui_resource(uri: 'http://example.com', ...)
```

### Content Type Support

The Ruby SDK follows Ruby conventions by using snake_case symbols for content types:

- `:raw_html` - Raw HTML content
- `:external_url` - External URL content  
- `:remote_dom` - Remote DOM content

The SDK maintains protocol consistency by internally mapping these to the camelCase format used in the MCP-UI specification.

### Creating a `raw_html` resource

```ruby
require 'mcp_ui_server'

resource = McpUiServer.create_ui_resource(
  uri: 'ui://my-app/greeting',
  content: {
    type: :raw_html,
    htmlString: '<h1>Hello, World!</h1>'
  }
)

# The resulting resource hash can be serialized to JSON and sent in your API response.
# {
#   "type": "resource",
#   "resource": {
#     "uri": "ui://my-app/greeting",
#     "mimeType": "text/html;profile=mcp-app",
#     "text": "<h1>Hello, World!</h1>"
#   }
# }
```

### Creating an `external_url` resource

```ruby
require 'mcp_ui_server'

resource = McpUiServer.create_ui_resource(
  uri: 'ui://my-app/external-page',
  content: {
    type: :external_url,
    iframeUrl: 'https://example.com'
  }
)

# Results in:
# {
#   "type": "resource",
#   "resource": {
#     "uri": "ui://my-app/external-page",
#     "mimeType": "text/html;profile=mcp-app",
#     "text": "https://example.com"
#   }
# }
```

### Creating a `remote_dom` resource

```ruby
require 'mcp_ui_server'

script = "..." # Your javascript bundle for the remote-dom

resource = McpUiServer.create_ui_resource(
  uri: 'ui://my-app/complex-view',
  content: {
    type: :remote_dom,
    script: script,
    framework: :react # or :webcomponents
  }
)
```

### Using `blob` encoding

For binary content or to avoid encoding issues, you can use `blob` encoding, which will Base64 encode the content.

```ruby
resource = McpUiServer.create_ui_resource(
  uri: 'ui://my-app/greeting',
  content: {
    type: :raw_html,
    htmlString: '<h1>Hello, World!</h1>'
  },
  encoding: :blob
)
```

## Error Handling

The SDK uses a custom `McpUiServer::Error` class for all SDK-specific errors. This makes it easy to rescue and handle SDK errors separately from other application errors.

```ruby
begin
  resource = McpUiServer.create_ui_resource(
    uri: 'http://invalid-scheme',
    content: { type: :raw_html, htmlString: '<h1>Hello</h1>' }
  )
rescue McpUiServer::Error => e
  puts "MCP UI SDK Error: #{e.message}"
  # Handle SDK-specific errors
rescue => e
  puts "Other error: #{e.message}"
  # Handle other errors
end
```

Common error scenarios:
- Invalid URI scheme (not starting with `ui://`)
- Unknown content type (only `:raw_html`, `:external_url`, `:remote_dom` are supported)
- Missing required content keys (e.g., `htmlString` for `raw_html`)
- Unknown encoding type

## Constants

The SDK provides constants for MIME types and content types:

```ruby
# MIME type constant (MCP Apps standard; used for both HTML and URL content)
McpUiServer::RESOURCE_MIME_TYPE     # 'text/html;profile=mcp-app'
McpUiServer::MIME_TYPE_HTML          # alias for RESOURCE_MIME_TYPE
McpUiServer::MIME_TYPE_URI_LIST      # alias for RESOURCE_MIME_TYPE
McpUiServer::MIME_TYPE_REMOTE_DOM    # 'application/vnd.mcp-ui.remote-dom; framework=%s'

# Content type constants (Ruby snake_case)
McpUiServer::CONTENT_TYPE_RAW_HTML      # :raw_html
McpUiServer::CONTENT_TYPE_EXTERNAL_URL  # :external_url
McpUiServer::CONTENT_TYPE_REMOTE_DOM    # :remote_dom

# Protocol mapping (for internal use)
McpUiServer::PROTOCOL_CONTENT_TYPES     # { raw_html: 'rawHtml', ... }

# URI scheme constant
McpUiServer::UI_URI_SCHEME           # 'ui://'
```

## Development

After checking out the repo, run `bundle install` to install dependencies. Then, run `bundle exec rspec` to run the tests. You can also run `bundle exec rubocop` to check for code style.

To install this gem onto your local machine, run `bundle exec rake install`.

## Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/idosal/mcp-ui.

## License

The gem is available as open source under the terms of the [Apache-2.0 License](https://www.apache.org/licenses/LICENSE-2.0). 

================================================
FILE: sdks/ruby/Rakefile
================================================
# frozen_string_literal: true

require 'bundler/gem_tasks'
require 'rspec/core/rake_task'

RSpec::Core::RakeTask.new(:spec)

task default: :spec


================================================
FILE: sdks/ruby/lib/mcp_ui_server/version.rb
================================================
# frozen_string_literal: true

module McpUiServer
  VERSION = '0.1.0'
end


================================================
FILE: sdks/ruby/lib/mcp_ui_server.rb
================================================
# frozen_string_literal: true

require_relative 'mcp_ui_server/version'
require 'base64'

# The McpUiServer module provides helper methods for creating UI resources
# compatible with the Model Context Protocol UI (mcp-ui) client.
module McpUiServer
  class Error < StandardError; end

  # MIME type for MCP Apps resources
  RESOURCE_MIME_TYPE = 'text/html;profile=mcp-app'
  # Convenience aliases
  MIME_TYPE_HTML = RESOURCE_MIME_TYPE
  MIME_TYPE_URI_LIST = RESOURCE_MIME_TYPE

  # Content type constants
  CONTENT_TYPE_RAW_HTML = :raw_html
  CONTENT_TYPE_EXTERNAL_URL = :external_url

  # Protocol mapping (snake_case to camelCase for protocol consistency)
  PROTOCOL_CONTENT_TYPES = {
    raw_html: 'rawHtml',
    external_url: 'externalUrl'
  }.freeze

  # Required content keys for each content type
  REQUIRED_CONTENT_KEYS = {
    CONTENT_TYPE_RAW_HTML => :htmlString,
    CONTENT_TYPE_EXTERNAL_URL => :iframeUrl
  }.freeze

  # URI scheme constant
  UI_URI_SCHEME = 'ui://'

  # Creates a UIResource hash structure for an MCP response.
  # This structure can then be serialized to JSON by your web framework.
  #
  # @param uri [String] The unique identifier for the resource (e.g., 'ui://greeting/1').
  # @param content [Hash] A hash describing the UI content.
  #   - :type [Symbol] The type of content. One of :raw_html or :external_url.
  #   - :htmlString [String] The raw HTML content (required if type is :raw_html).
  #   - :iframeUrl [String] The URL for an external page (required if type is :external_url).
  # @param encoding [Symbol] The encoding method. :text for plain string, :blob for base64 encoded.
  #
  # @return [Hash] A UIResource hash ready to be included in an MCP response.
  #
  # @raise [McpUiServer::Error] if URI scheme is invalid, content type is unknown,
  #   encoding type is unknown, or required content keys are missing.
  def self.create_ui_resource(uri:, content:, encoding: :text)
    validate_uri_scheme(uri)

    resource = { uri: uri }

    content_value = process_content(content, resource)
    process_encoding(encoding, resource, content_value)

    {
      type: 'resource',
      resource: resource
    }
  end

  # private

  def self.validate_uri_scheme(uri)
    raise Error, "URI must start with '#{UI_URI_SCHEME}' but got: #{uri}" unless uri.start_with?(UI_URI_SCHEME)
  end
  private_class_method :validate_uri_scheme

  def self.validate_content_type(content_type)
    return if PROTOCOL_CONTENT_TYPES.key?(content_type)

    supported_types = PROTOCOL_CONTENT_TYPES.keys.join(', ')
    raise Error, "Unknown content type: #{content_type}. Supported types: #{supported_types}"
  end
  private_class_method :validate_content_type

  def self.process_content(content, resource)
    content_type = content.fetch(:type)
    validate_content_type(content_type)

    case content_type
    when CONTENT_TYPE_RAW_HTML
      process_raw_html_content(content, resource)
    when CONTENT_TYPE_EXTERNAL_URL
      process_external_url_content(content, resource)
    end
  end
  private_class_method :process_content

  def self.process_raw_html_content(content, resource)
    resource[:mimeType] = RESOURCE_MIME_TYPE
    required_key = REQUIRED_CONTENT_KEYS[CONTENT_TYPE_RAW_HTML]
    content.fetch(required_key) { raise Error, "Missing required key :#{required_key} for raw_html content" }
  end
  private_class_method :process_raw_html_content

  def self.process_external_url_content(content, resource)
    resource[:mimeType] = RESOURCE_MIME_TYPE
    required_key = REQUIRED_CONTENT_KEYS[CONTENT_TYPE_EXTERNAL_URL]
    content.fetch(required_key) { raise Error, "Missing required key :#{required_key} for external_url content" }
  end
  private_class_method :process_external_url_content

  def self.process_encoding(encoding, resource, content_value)
    case encoding
    when :text
      resource[:text] = content_value
    when :blob
      resource[:blob] = Base64.strict_encode64(content_value)
    else
      raise Error, "Unknown encoding type: #{encoding}. Supported types: :text, :blob"
    end
  end
  private_class_method :process_encoding
end


================================================
FILE: sdks/ruby/mcp_ui_server.gemspec
================================================
# frozen_string_literal: true

require_relative 'lib/mcp_ui_server/version'

Gem::Specification.new do |spec|
  spec.name        = 'mcp_ui_server'
  spec.version     = McpUiServer::VERSION
  spec.authors     = ['Ido Salomon']
  spec.email       = ['idosalomon@gmail.com']
  spec.summary     = 'Ruby Server SDK for MCP UI'
  spec.description = 'A Ruby server SDK for MCP UI.'
  spec.homepage    = 'https://github.com/idosal/mcp-ui'
  spec.license     = 'Apache-2.0'
  spec.required_ruby_version = '>= 2.6.0'

  spec.metadata['rubygems_mfa_required'] = 'true'

  spec.files = Dir['{lib}/**/*.rb', 'README.md']

  spec.require_paths = ['lib']

  # Add any runtime dependencies here
  # spec.add_dependency "http"

  # Add any development dependencies here
  spec.add_development_dependency 'bundler'
  spec.add_development_dependency 'rake'
  spec.add_development_dependency 'rspec'
  spec.add_development_dependency 'rubocop'
  spec.add_development_dependency 'rubocop-rake'
  spec.add_development_dependency 'rubocop-rspec'
end


================================================
FILE: sdks/ruby/release.config.js
================================================
module.exports = {
  branches: [
    'main',
    {
      name: 'alpha',
      prerelease: true,
    },
  ],
  repositoryUrl: 'https://github.com/idosal/mcp-ui',
  tagFormat: 'ruby-server-sdk/v${version}',
  plugins: [
    '@semantic-release/commit-analyzer',
    '@semantic-release/release-notes-generator',
    [
      '@semantic-release/changelog',
      {
        changelogFile: 'CHANGELOG.md',
      },
    ],
    [
      '@semantic-release/exec',
      {
        prepareCmd:
          'sed -i \'s/VERSION = ".*"/VERSION = "${nextRelease.version}"/\' lib/mcp_ui_server/version.rb && bundle install && gem build mcp_ui_server.gemspec',
        publishCmd: 'gem push *.gem',
      },
    ],
    [
      '@semantic-release/github',
      {
        assets: '*.gem',
      },
    ],
    [
      '@semantic-release/git',
      {
        assets: ['CHANGELOG.md', 'lib/mcp_ui_server/version.rb', 'Gemfile.lock'],
        message: 'chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}',
      },
    ],
  ],
};


================================================
FILE: sdks/ruby/spec/mcp_ui_server_spec.rb
================================================
# frozen_string_literal: true

require 'mcp_ui_server'
require 'base64'

RSpec.describe McpUiServer do
  it 'has a version number' do
    expect(McpUiServer::VERSION).not_to be_nil
  end

  describe '.create_ui_resource' do
    let(:uri) { 'ui://test/1' }

    context 'with raw_html content' do
      let(:content) { { type: :raw_html, htmlString: '<h1>Hello</h1>' } }

      it 'creates a resource with text/html;profile=mcp-app mimetype and text encoding' do
        resource = described_class.create_ui_resource(uri: uri, content: content)
        expect(resource[:type]).to eq('resource')
        expect(resource[:resource][:uri]).to eq(uri)
        expect(resource[:resource][:mimeType]).to eq('text/html;profile=mcp-app')
        expect(resource[:resource][:text]).to eq('<h1>Hello</h1>')
      end

      it 'creates a resource with blob encoding' do
        resource = described_class.create_ui_resource(uri: uri, content: content, encoding: :blob)
        expect(resource[:resource][:blob]).to eq(Base64.strict_encode64('<h1>Hello</h1>'))
      end
    end

    context 'with external_url content' do
      let(:content) { { type: :external_url, iframeUrl: 'https://example.com' } }

      it 'creates a resource with text/html;profile=mcp-app mimetype' do
        resource = described_class.create_ui_resource(uri: uri, content: content)
        expect(resource[:resource][:mimeType]).to eq('text/html;profile=mcp-app')
        expect(resource[:resource][:text]).to eq('https://example.com')
      end

      it 'creates a resource with blob encoding' do
        resource = described_class.create_ui_resource(uri: uri, content: content, encoding: :blob)
        expect(resource[:resource][:blob]).to eq(Base64.strict_encode64('https://example.com'))
      end
    end

    context 'with invalid input' do
      it 'raises McpUiServer::Error for invalid URI scheme' do
        invalid_uri = 'http://test/1'
        content = { type: :raw_html, htmlString: '<h1>Hello</h1>' }
        expect do
          described_class.create_ui_resource(uri: invalid_uri, content: content)
        end.to raise_error(McpUiServer::Error, "URI must start with 'ui://' but got: #{invalid_uri}")
      end

      it 'raises McpUiServer::Error for unknown content type' do
        content = { type: :invalid, data: 'foo' }
        expect do
          described_class.create_ui_resource(uri: uri, content: content)
        end.to raise_error(McpUiServer::Error, /Unknown content type: invalid/)
      end

      it 'raises McpUiServer::Error for camelCase string content type' do
        content = { type: 'rawHtml', htmlString: '<h1>Hello</h1>' }
        expect do
          described_class.create_ui_resource(uri: uri, content: content)
        end.to raise_error(McpUiServer::Error, /Unknown content type: rawHtml/)
      end

      it 'raises McpUiServer::Error for unknown encoding type' do
        content = { type: :raw_html, htmlString: '<h1>Hello</h1>' }
        expect do
          described_class.create_ui_resource(uri: uri, content: content, encoding: :invalid)
        end.to raise_error(McpUiServer::Error, /Unknown encoding type: invalid/)
      end

      it 'raises McpUiServer::Error if htmlString is missing' do
        content = { type: :raw_html }
        expect do
          described_class.create_ui_resource(uri: uri, content: content)
        end.to raise_error(McpUiServer::Error, /Missing required key :htmlString for raw_html content/)
      end

      it 'raises McpUiServer::Error if iframeUrl is missing' do
        content = { type: :external_url }
        expect do
          described_class.create_ui_resource(uri: uri, content: content)
        end.to raise_error(McpUiServer::Error, /Missing required key :iframeUrl for external_url content/)
      end
    end

    context 'with constants' do
      it 'defines expected MIME type constants' do
        expect(McpUiServer::RESOURCE_MIME_TYPE).to eq('text/html;profile=mcp-app')
        expect(McpUiServer::MIME_TYPE_HTML).to eq('text/html;profile=mcp-app')
        expect(McpUiServer::MIME_TYPE_URI_LIST).to eq('text/html;profile=mcp-app')
      end

      it 'defines expected content type constants' do
        expect(McpUiServer::CONTENT_TYPE_RAW_HTML).to eq(:raw_html)
        expect(McpUiServer::CONTENT_TYPE_EXTERNAL_URL).to eq(:external_url)
      end

      it 'defines protocol content type mapping' do
        expect(McpUiServer::PROTOCOL_CONTENT_TYPES).to include(
          raw_html: 'rawHtml',
          external_url: 'externalUrl'
        )
      end

      it 'defines URI scheme constant' do
        expect(McpUiServer::UI_URI_SCHEME).to eq('ui://')
      end
    end
  end
end


================================================
FILE: sdks/ruby/spec/spec_helper.rb
================================================
# frozen_string_literal: true

# This file was generated by the `rspec --init` command. Conventionally, all
# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
# The generated `.rspec` file contains `--require spec_helper` which will cause
# this file to be loaded before any of your specs are run.
#
# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
RSpec.configure do |config|
  # rspec-expectations config goes here. You can use an alternate
  # assertion/expectation library such as wrong or the stdlib/minitest
  # assertions if you prefer.
  config.expect_with :rspec do |expectations|
    # This option will default to `true` in RSpec 4. It makes the `description`
    # and `failure_message` of custom matchers include text argument names
    # that match what was passed in an expectation. For example:
    #     be_bigger_than(2).and(be_smaller_than(4)).description
    #     # => "be bigger than 2 and be smaller than 4"
    # ...rather than:
    #     # => "be bigger than and be smaller than"
    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
  end

  # rspec-mocks config goes here. You can use an alternate test double
  # library (such as bogus or mocha) by changing the `mock_with` option here.
  config.mock_with :rspec do |mocks|
    # Prevents you from mocking or stubbing a method that does not exist on
    # a real object. This is generally recommended, and will default to
    # `true` in RSpec 4.
    mocks.verify_partial_doubles = true
  end

  # This option will default to `:apply_to_host_groups` in RSpec 4 (and will
  # have no way to turn it off -- the option exists only for backwards
  # compatibility in RSpec 3). It causes shared context metadata to be
  # inherited by the metadata hash of host groups and examples, rather than
  # triggering implicit auto-inclusion in groups with matching metadata.
  config.shared_context_metadata_behavior = :apply_to_host_groups
end


================================================
FILE: sdks/typescript/client/CHANGELOG.md
================================================
# [7.0.0](https://github.com/MCP-UI-Org/mcp-ui/compare/client/v6.1.1...client/v7.0.0) (2026-03-12)


### Bug Fixes

* bump major for breaking change ([#187](https://github.com/MCP-UI-Org/mcp-ui/issues/187)) ([2223e76](https://github.com/MCP-UI-Org/mcp-ui/commit/2223e76b229559ae6f39d63dd581a08b52e35acd))


### BREAKING CHANGES

* failed to bump major in the last commit because of semantic release

## [6.1.1](https://github.com/MCP-UI-Org/mcp-ui/compare/client/v6.1.0...client/v6.1.1) (2026-03-12)


### Bug Fixes

* bump version for legacy removal ([#186](https://github.com/MCP-UI-Org/mcp-ui/issues/186)) ([0a75453](https://github.com/MCP-UI-Org/mcp-ui/commit/0a754533c92b6e9e317bda03383fc2c2745b37c7))

# [6.1.0](https://github.com/MCP-UI-Org/mcp-ui/compare/client/v6.0.0...client/v6.1.0) (2026-02-13)


### Features

* support experimental messages ([#176](https://github.com/MCP-UI-Org/mcp-ui/issues/176)) ([327e4d9](https://github.com/MCP-UI-Org/mcp-ui/commit/327e4d9e6771eceb42f8823ae864e6758f371970))

# [6.0.0](https://github.com/MCP-UI-Org/mcp-ui/compare/client/v5.18.0...client/v6.0.0) (2026-01-26)


### Bug Fixes

* trigger MCP Apps client release ([#173](https://github.com/MCP-UI-Org/mcp-ui/issues/173)) ([b0c0659](https://github.com/MCP-UI-Org/mcp-ui/commit/b0c0659700b493a0083d0de12958f276e4c37715))


### Features

* mcp-ui -> mcp apps! ([#172](https://github.com/MCP-UI-Org/mcp-ui/issues/172)) ([93a6e22](https://github.com/MCP-UI-Org/mcp-ui/commit/93a6e225808894cac3206504cf15c481f88ed540))


### BREAKING CHANGES

* removed discarded content types, changed mimetype, updated docs, etc.

# [5.18.0](https://github.com/MCP-UI-Org/mcp-ui/compare/client/v5.17.3...client/v5.18.0) (2026-01-25)


### Features

* React renderer for MCP Apps ([#147](https://github.com/MCP-UI-Org/mcp-ui/issues/147)) ([fbc918d](https://github.com/MCP-UI-Org/mcp-ui/commit/fbc918d713861396703ede124c5676cf3d1164dd))

## [5.17.3](https://github.com/MCP-UI-Org/mcp-ui/compare/client/v5.17.2...client/v5.17.3) (2025-12-20)


### Bug Fixes

* add connectedMoveCallback to the WC implementation ([#170](https://github.com/MCP-UI-Org/mcp-ui/issues/170)) ([5ac4734](https://github.com/MCP-UI-Org/mcp-ui/commit/5ac4734078ff56e213e7a57029fd612638abb0b4))

## [5.17.2](https://github.com/MCP-UI-Org/mcp-ui/compare/client/v5.17.1...client/v5.17.2) (2025-12-20)


### Bug Fixes

* **client:** use type-only imports for @modelcontextprotocol/sdk types ([#157](https://github.com/MCP-UI-Org/mcp-ui/issues/157)) ([d84cb3e](https://github.com/MCP-UI-Org/mcp-ui/commit/d84cb3e217dfa90f038a8fbe64b4ffd0e0a1bc3f))
* revert externalUrl adapter for compatibility ([#159](https://github.com/MCP-UI-Org/mcp-ui/issues/159)) ([3c5289a](https://github.com/MCP-UI-Org/mcp-ui/commit/3c5289a5e59812f556bc2bb9e67c3ce2e3ce764e))
* trigger TS release ([e28d1f6](https://github.com/MCP-UI-Org/mcp-ui/commit/e28d1f65cd5f26e46801480995e178ee50c31e51))
* update adapter to latest MCP Apps spec ([#163](https://github.com/MCP-UI-Org/mcp-ui/issues/163)) ([e342034](https://github.com/MCP-UI-Org/mcp-ui/commit/e3420348098fe716f45b2182bc8c8d3358714035))
* update MCP Apps adapter mimetype ([#162](https://github.com/MCP-UI-Org/mcp-ui/issues/162)) ([c91e533](https://github.com/MCP-UI-Org/mcp-ui/commit/c91e5331b68c65de2347b16766a5711e05985e68))
* update ui/message to pass an array ([#167](https://github.com/MCP-UI-Org/mcp-ui/issues/167)) ([80cf222](https://github.com/MCP-UI-Org/mcp-ui/commit/80cf22290ff5e2f981be839f74705454483c21b5))

## [5.17.1](https://github.com/MCP-UI-Org/mcp-ui/compare/client/v5.17.0...client/v5.17.1) (2025-12-01)


### Bug Fixes

* use document.write in proxy sandbox ([#156](https://github.com/MCP-UI-Org/mcp-ui/issues/156)) ([447f582](https://github.com/MCP-UI-Org/mcp-ui/commit/447f582105a0889ee47d912925d7f02034fc39a9))

# [5.17.0](https://github.com/MCP-UI-Org/mcp-ui/compare/client/v5.16.0...client/v5.17.0) (2025-11-30)


### Features

* externalUrl adapter ([5a1e4de](https://github.com/MCP-UI-Org/mcp-ui/commit/5a1e4deeeda9ae0120d17b5abdf9096edf52054f))

# [5.16.0](https://github.com/MCP-UI-Org/mcp-ui/compare/client/v5.15.0...client/v5.16.0) (2025-11-29)


### Features

* add MCP Apps adapter ([#154](https://github.com/MCP-UI-Org/mcp-ui/issues/154)) ([986fd63](https://github.com/MCP-UI-Org/mcp-ui/commit/986fd634448637aa6488a18ad80ee9cd6b8de318))

# [5.15.0](https://github.com/MCP-UI-Org/mcp-ui/compare/client/v5.14.1...client/v5.15.0) (2025-11-29)


### Bug Fixes

* ensure Apps SDK adapter is bundled properly and initialized wth config ([#137](https://github.com/MCP-UI-Org/mcp-ui/issues/137)) ([4f7c25c](https://github.com/MCP-UI-Org/mcp-ui/commit/4f7c25ce7e6f25e36cfc188016b012d31d722204))


### Features

* support metadata in Python SDK ([#134](https://github.com/MCP-UI-Org/mcp-ui/issues/134)) ([9bc3c64](https://github.com/MCP-UI-Org/mcp-ui/commit/9bc3c646c2638e16ac62edf9faca2dbee2b8cb7e))

## [5.14.1](https://github.com/idosal/mcp-ui/compare/client/v5.14.0...client/v5.14.1) (2025-10-24)


### Bug Fixes

* Enable bidirectional message relay in rawhtml proxy mode ([#138](https://github.com/idosal/mcp-ui/issues/138)) ([f0bdefb](https://github.com/idosal/mcp-ui/commit/f0bdefb818aca5a3bfbdfe28fc4fe057b1818cb5))

# [5.14.0](https://github.com/idosal/mcp-ui/compare/client/v5.13.1...client/v5.14.0) (2025-10-22)


### Features

* support proxy for rawHtml ([#132](https://github.com/idosal/mcp-ui/issues/132)) ([1bbeb09](https://github.com/idosal/mcp-ui/commit/1bbeb093bc9c389f4ccfd9e8df06dc7f1eaadde0))

## [5.13.1](https://github.com/idosal/mcp-ui/compare/client/v5.13.0...client/v5.13.1) (2025-10-21)


### Bug Fixes

* fix file extension reference in package.json ([927989c](https://github.com/idosal/mcp-ui/commit/927989c4f81742106b6f5e2f68343fb7ea7d016a))

# [5.13.0](https://github.com/idosal/mcp-ui/compare/client/v5.12.1...client/v5.13.0) (2025-10-13)


### Features

* support adapters ([#127](https://github.com/idosal/mcp-ui/issues/127)) ([d4bd152](https://github.com/idosal/mcp-ui/commit/d4bd152db0a1bd27081502098f3cd9aa54ca359e))

# [5.13.0-alpha.4](https://github.com/idosal/mcp-ui/compare/client/v5.13.0-alpha.3...client/v5.13.0-alpha.4) (2025-10-12)


### Bug Fixes

* exports vite ([4de2b0c](https://github.com/idosal/mcp-ui/commit/4de2b0cfae91813ad68fb1ce68b1cf7c2a161baf))

# [5.13.0-alpha.3](https://github.com/idosal/mcp-ui/compare/client/v5.13.0-alpha.2...client/v5.13.0-alpha.3) (2025-10-11)


### Bug Fixes

* exports ([0018c17](https://github.com/idosal/mcp-ui/commit/0018c17dd8b184ee549327f1742d9da71edfd576))
* version ([767a245](https://github.com/idosal/mcp-ui/commit/767a245d2374f05e27ece090dc5af8613a9a6b96))

# [5.13.0-alpha.2](https://github.com/idosal/mcp-ui/compare/client/v5.13.0-alpha.1...client/v5.13.0-alpha.2) (2025-10-10)


### Bug Fixes

* set the mime type as text/html+skybridge for apps SDK ([bc47423](https://github.com/idosal/mcp-ui/commit/bc474232a249e5cc40f348e3a26f93c806fcc602))

# [5.13.0-alpha.1](https://github.com/idosal/mcp-ui/compare/client/v5.12.1...client/v5.13.0-alpha.1) (2025-10-10)


### Bug Fixes

* adapter version ([259c842](https://github.com/idosal/mcp-ui/commit/259c84247a00933575e1fff08674cce52be59973))
* release ([420efc0](https://github.com/idosal/mcp-ui/commit/420efc0a82bf8de2731514648268cad1209320e2))
* server alpha versioning ([7f35d3b](https://github.com/idosal/mcp-ui/commit/7f35d3be2cfa6a535d3fbd5f86fbec1b20432dca))
* server versioning ([2324371](https://github.com/idosal/mcp-ui/commit/2324371ed636381bb44a1feae1b59a87c84c6666))


### Features

* add adapters infra (appssdk) ([#125](https://github.com/idosal/mcp-ui/issues/125)) ([2e016cd](https://github.com/idosal/mcp-ui/commit/2e016cdc05d08c2f7c2e4a40efbec2b0704e7ef6))

# [1.0.0-alpha.2](https://github.com/idosal/mcp-ui/compare/client/v1.0.0-alpha.1...client/v1.0.0-alpha.2) (2025-10-10)


### Bug Fixes

* server versioning ([2324371](https://github.com/idosal/mcp-ui/commit/2324371ed636381bb44a1feae1b59a87c84c6666))

# 1.0.0-alpha.1 (2025-10-10)


### Bug Fixes

* adapter version ([259c842](https://github.com/idosal/mcp-ui/commit/259c84247a00933575e1fff08674cce52be59973))
* add a bridge to pass messages in and out of the proxy ([#38](https://github.com/idosal/mcp-ui/issues/38)) ([30ccac0](https://github.com/idosal/mcp-ui/commit/30ccac0706ad8e02ebcd8960924ed1d58ddedf85))
* bump client version ([75c9236](https://github.com/idosal/mcp-ui/commit/75c923689654b4443ad1093fafc0bad16902e4cc))
* **client:** specify iframe ([fd0b70a](https://github.com/idosal/mcp-ui/commit/fd0b70a84948d3aa5d7a79269ff7c3bcd0946689))
* **client:** styling ([6ff9b68](https://github.com/idosal/mcp-ui/commit/6ff9b685fd1be770fd103943e45275e9ec86905c))
* dependencies ([887f61f](https://github.com/idosal/mcp-ui/commit/887f61f827b4585c17493d4fa2dfb251ea598587))
* export RemoteDomResource ([2b86f2d](https://github.com/idosal/mcp-ui/commit/2b86f2dd4506de49c69908e23d84a2a323170446))
* export ResourceRenderer and HtmlResource ([2b841a5](https://github.com/idosal/mcp-ui/commit/2b841a556c1111ed70ccb3d3987afd21fe7df897))
* exports ([3a93a16](https://github.com/idosal/mcp-ui/commit/3a93a16e1b7438ba7b2ef49ca854479f755abcc6))
* iframe handle ([#15](https://github.com/idosal/mcp-ui/issues/15)) ([66bd4fd](https://github.com/idosal/mcp-ui/commit/66bd4fd3d04f82e3e4557f064e701b68e1d8af11))
* lint ([4487820](https://github.com/idosal/mcp-ui/commit/44878203a71c3c9173d463b809be36769e996ba9))
* lint ([d0a91f9](https://github.com/idosal/mcp-ui/commit/d0a91f9a07ec0042690240c3d8d0bad620f8c765))
* minor typo ([a0bee9c](https://github.com/idosal/mcp-ui/commit/a0bee9c85e5ee02e021ba687940ced38220445fe))
* move react dependencies to be peer dependencies ([#91](https://github.com/idosal/mcp-ui/issues/91)) ([f672f3e](https://github.com/idosal/mcp-ui/commit/f672f3efc1c2ba2fbae16f9dcdc2142c2b4bd920)), closes [#90](https://github.com/idosal/mcp-ui/issues/90)
* package config ([8dc1e53](https://github.com/idosal/mcp-ui/commit/8dc1e5358c3c8e641206a5e6851427d360cc1955))
* packaging ([9e6babd](https://github.com/idosal/mcp-ui/commit/9e6babd3a587213452ea7aec4cc9ae3a50fa1965))
* pass ref explicitly using iframeProps ([#33](https://github.com/idosal/mcp-ui/issues/33)) ([d01b5d1](https://github.com/idosal/mcp-ui/commit/d01b5d1e4cdaedc436ba2fa8984d866d93d59087))
* publish ([0943e7a](https://github.com/idosal/mcp-ui/commit/0943e7acaf17f32aae085c2313bfbec47bc59f1f))
* ref passing to UIResourceRenderer ([#32](https://github.com/idosal/mcp-ui/issues/32)) ([d28c23f](https://github.com/idosal/mcp-ui/commit/d28c23f9b8ee320f4e361200ae02a23f0d2a1c0c))
* release ([420efc0](https://github.com/idosal/mcp-ui/commit/420efc0a82bf8de2731514648268cad1209320e2))
* remove shared dependency ([e66e8f4](https://github.com/idosal/mcp-ui/commit/e66e8f49b1ba46090db6e4682060488566f4fe41))
* rename components and methods to fit new scope ([#22](https://github.com/idosal/mcp-ui/issues/22)) ([6bab1fe](https://github.com/idosal/mcp-ui/commit/6bab1fe3a168a18e7ba4762e23478abf4e0cc84c))
* rename delivery -> encoding and flavor -> framework ([#36](https://github.com/idosal/mcp-ui/issues/36)) ([9a509ed](https://github.com/idosal/mcp-ui/commit/9a509ed80d051b0a8042b36958b401a0a7c1e138))
* Ruby comment ([b22dc2e](https://github.com/idosal/mcp-ui/commit/b22dc2e0a0db20d98ada884649ad408ebaf72d22))
* support react-router ([21ffb95](https://github.com/idosal/mcp-ui/commit/21ffb95fe6d77a348b95b38dbf3741ba6442894e))
* text and blob support in RemoteDOM resources ([ec68eb9](https://github.com/idosal/mcp-ui/commit/ec68eb90df984da8b492cc25eafdafdeda79f299))
* trigger release ([aaca831](https://github.com/idosal/mcp-ui/commit/aaca83125c3f7825ccdebf0f04f8553e953c5249))
* typescript ci publish ([e7c0ebf](https://github.com/idosal/mcp-ui/commit/e7c0ebfa7f7b552f9763743fda659d1441f21692))
* typescript types to be compatible with MCP SDK ([#10](https://github.com/idosal/mcp-ui/issues/10)) ([74365d7](https://github.com/idosal/mcp-ui/commit/74365d7ed6422beef6cd9ee0f5a97c847bd9827b))
* update deps ([4091ef4](https://github.com/idosal/mcp-ui/commit/4091ef47da048fab3c4feb002f5287b2ff295744))
* update isUIResource to use EmbeddedResource type ([#122](https://github.com/idosal/mcp-ui/issues/122)) ([5a65a0b](https://github.com/idosal/mcp-ui/commit/5a65a0b1ba63e6cfda26b8da41239a532f00d60a)), closes [#117](https://github.com/idosal/mcp-ui/issues/117)
* use targetOrigin in the proxy message relay ([#40](https://github.com/idosal/mcp-ui/issues/40)) ([b3fb54e](https://github.com/idosal/mcp-ui/commit/b3fb54e28ca7b8eeda896b5bcf478b6343dbba47))
* validate URL ([b7c994d](https://github.com/idosal/mcp-ui/commit/b7c994dfdd947b3dfbb903fc8cb896d61004c8d8))
* wc dist overwrite ([#63](https://github.com/idosal/mcp-ui/issues/63)) ([9e46c56](https://github.com/idosal/mcp-ui/commit/9e46c56c7a8908410fad6d08a5d845139e93f80f))


### Documentation

* bump ([#4](https://github.com/idosal/mcp-ui/issues/4)) ([ad4d163](https://github.com/idosal/mcp-ui/commit/ad4d1632cc1f9c99072349a8f0cdaac343236132))


### Features

* add adapters infra (appssdk) ([#125](https://github.com/idosal/mcp-ui/issues/125)) ([2e016cd](https://github.com/idosal/mcp-ui/commit/2e016cdc05d08c2f7c2e4a40efbec2b0704e7ef6))
* add convenience function isUIResource to client SDK ([#86](https://github.com/idosal/mcp-ui/issues/86)) ([607c6ad](https://github.com/idosal/mcp-ui/commit/607c6add3567bb60c45accf3e1b25a38ed284a6f))
* add embeddedResourceProps for annotations ([#99](https://github.com/idosal/mcp-ui/issues/99)) ([b96ec44](https://github.com/idosal/mcp-ui/commit/b96ec442ec319a1944393ada0bdcccb93b7ffc62))
* add proxy option to externalUrl ([#37](https://github.com/idosal/mcp-ui/issues/37)) ([7b95cd0](https://github.com/idosal/mcp-ui/commit/7b95cd0b3873fc1cde28748ec463e81c6ff1c494))
* add remote-dom content type ([#18](https://github.com/idosal/mcp-ui/issues/18)) ([5dacf37](https://github.com/idosal/mcp-ui/commit/5dacf37c22b5ee6ae795049a8d573fc073b8a1f5))
* add Ruby server SDK ([#31](https://github.com/idosal/mcp-ui/issues/31)) ([5ffcde4](https://github.com/idosal/mcp-ui/commit/5ffcde4a373accdd063fa6c3b1b3d4df13c91b53))
* add sandbox permissions instead of an override ([#83](https://github.com/idosal/mcp-ui/issues/83)) ([b1068e9](https://github.com/idosal/mcp-ui/commit/b1068e9e87caa2b4302bf145a33efdfd1af05c1d))
* add ui-request-render-data message type ([#111](https://github.com/idosal/mcp-ui/issues/111)) ([26135ce](https://github.com/idosal/mcp-ui/commit/26135ce2c7f7d586b0b81a03623cd77dc1bc7f90))
* add UIResourceRenderer Web Component ([#58](https://github.com/idosal/mcp-ui/issues/58)) ([ec8f299](https://github.com/idosal/mcp-ui/commit/ec8f2994ecf36774e6ad5191654ba22946d0ee49))
* auto resize with the autoResizeIframe prop ([#56](https://github.com/idosal/mcp-ui/issues/56)) ([76c867a](https://github.com/idosal/mcp-ui/commit/76c867a569b72aed892290aa84e1194ab8eb79ce))
* change onGenericMcpAction to optional onUiAction ([1913b59](https://github.com/idosal/mcp-ui/commit/1913b5977c30811f9e67659949e2d961f2eda983))
* **client:** allow setting supportedContentTypes for HtmlResource ([#17](https://github.com/idosal/mcp-ui/issues/17)) ([e009ef1](https://github.com/idosal/mcp-ui/commit/e009ef10010134ba3d9893314cc4d8e1274f1f07))
* consolidate ui:// and ui-app:// ([#8](https://github.com/idosal/mcp-ui/issues/8)) ([2e08035](https://github.com/idosal/mcp-ui/commit/2e08035676bb6a46ef3c94dba916bc895f1fa3cc))
* pass iframe props down ([#14](https://github.com/idosal/mcp-ui/issues/14)) ([112539d](https://github.com/idosal/mcp-ui/commit/112539d28640a96e8375a6b416f2ba559370b312))
* refactor UTFtoB64 (bump server version) ([#95](https://github.com/idosal/mcp-ui/issues/95)) ([2d5e16b](https://github.com/idosal/mcp-ui/commit/2d5e16bf39073ee890586f458412f0c3b474c2b8))
* send render data to the iframe ([#51](https://github.com/idosal/mcp-ui/issues/51)) ([d38cfc7](https://github.com/idosal/mcp-ui/commit/d38cfc7925061c1ae1911bdee408033c8e9f283d))
* separate html and remote-dom props ([#24](https://github.com/idosal/mcp-ui/issues/24)) ([a7f0529](https://github.com/idosal/mcp-ui/commit/a7f05299dc9cc40184f9ab25c5b648ee7077be64))
* support generic messages response ([#35](https://github.com/idosal/mcp-ui/issues/35)) ([10b407b](https://github.com/idosal/mcp-ui/commit/10b407b279b3ee9608ef077445f4d714f88343c5))
* support passing resource metadata ([#87](https://github.com/idosal/mcp-ui/issues/87)) ([f1c1c9b](https://github.com/idosal/mcp-ui/commit/f1c1c9b62dd74c63045b295eb388181843ac772a))
* support ui action result types ([#6](https://github.com/idosal/mcp-ui/issues/6)) ([899d152](https://github.com/idosal/mcp-ui/commit/899d1527286a281a23fbb8f3a207d435dfc3fe96))
* switch to ResourceRenderer ([#21](https://github.com/idosal/mcp-ui/issues/21)) ([6fe3166](https://github.com/idosal/mcp-ui/commit/6fe316682675e27db914d60696754677e3783448))


### BREAKING CHANGES

* The existing naming is ambiguous. Renaming delivery to encoding and flavor to framework should clarify the intent.
* exported names have changed
* removed deprecated client API
* (previous one didn't take due to semantic-release misalignment)

# [5.13.0-alpha.2](https://github.com/idosal/mcp-ui/compare/v5.13.0-alpha.1...v5.13.0-alpha.2) (2025-10-10)


### Bug Fixes

* adapter version ([259c842](https://github.com/idosal/mcp-ui/commit/259c84247a00933575e1fff08674cce52be59973))

# [5.13.0-alpha.1](https://github.com/idosal/mcp-ui/compare/v5.12.1...v5.13.0-alpha.1) (2025-10-10)


### Features

* add adapters infra (appssdk) ([#125](https://github.com/idosal/mcp-ui/issues/125)) ([2e016cd](https://github.com/idosal/mcp-ui/commit/2e016cdc05d08c2f7c2e4a40efbec2b0704e7ef6))

## [5.12.1](https://github.com/idosal/mcp-ui/compare/v5.12.0...v5.12.1) (2025-10-08)


### Bug Fixes

* update isUIResource to use EmbeddedResource type ([#122](https://github.com/idosal/mcp-ui/issues/122)) ([5a65a0b](https://github.com/idosal/mcp-ui/commit/5a65a0b1ba63e6cfda26b8da41239a532f00d60a)), closes [#117](https://github.com/idosal/mcp-ui/issues/117)

# [5.12.0](https://github.com/idosal/mcp-ui/compare/v5.11.0...v5.12.0) (2025-09-23)


### Features

* add ui-request-render-data message type ([#111](https://github.com/idosal/mcp-ui/issues/111)) ([26135ce](https://github.com/idosal/mcp-ui/commit/26135ce2c7f7d586b0b81a03623cd77dc1bc7f90))

# [5.9.0](https://github.com/idosal/mcp-ui/compare/v5.8.1...v5.9.0) (2025-08-20)


### Features

* support passing resource metadata ([#87](https://github.com/idosal/mcp-ui/issues/87)) ([f1c1c9b](https://github.com/idosal/mcp-ui/commit/f1c1c9b62dd74c63045b295eb388181843ac772a))

## [5.8.1](https://github.com/idosal/mcp-ui/compare/v5.8.0...v5.8.1) (2025-08-20)


### Bug Fixes

* move react dependencies to be peer dependencies ([#91](https://github.com/idosal/mcp-ui/issues/91)) ([f672f3e](https://github.com/idosal/mcp-ui/commit/f672f3efc1c2ba2fbae16f9dcdc2142c2b4bd920)), closes [#90](https://github.com/idosal/mcp-ui/issues/90)

# [5.8.0](https://github.com/idosal/mcp-ui/compare/v5.7.0...v5.8.0) (2025-08-19)


### Bug Fixes

* minor typo ([a0bee9c](https://github.com/idosal/mcp-ui/commit/a0bee9c85e5ee02e021ba687940ced38220445fe))


### Features

* add convenience function isUIResource to client SDK ([#86](https://github.com/idosal/mcp-ui/issues/86)) ([607c6ad](https://github.com/idosal/mcp-ui/commit/607c6add3567bb60c45accf3e1b25a38ed284a6f))

# [5.7.0](https://github.com/idosal/mcp-ui/compare/v5.6.2...v5.7.0) (2025-08-15)


### Features

* add sandbox permissions instead of an override ([#83](https://github.com/idosal/mcp-ui/issues/83)) ([b1068e9](https://github.com/idosal/mcp-ui/commit/b1068e9e87caa2b4302bf145a33efdfd1af05c1d))

## [5.6.2](https://github.com/idosal/mcp-ui/compare/v5.6.1...v5.6.2) (2025-08-05)


### Bug Fixes

* bump client version ([75c9236](https://github.com/idosal/mcp-ui/commit/75c923689654b4443ad1093fafc0bad16902e4cc))

## [5.6.1](https://github.com/idosal/mcp-ui/compare/v5.6.0...v5.6.1) (2025-08-05)


### Bug Fixes

* wc dist overwrite ([#63](https://github.com/idosal/mcp-ui/issues/63)) ([9e46c56](https://github.com/idosal/mcp-ui/commit/9e46c56c7a8908410fad6d08a5d845139e93f80f))

# [5.6.0](https://github.com/idosal/mcp-ui/compare/v5.5.0...v5.6.0) (2025-08-03)


### Features

* add UIResourceRenderer Web Component ([#58](https://github.com/idosal/mcp-ui/issues/58)) ([ec8f299](https://github.com/idosal/mcp-ui/commit/ec8f2994ecf36774e6ad5191654ba22946d0ee49))

# [5.5.0](https://github.com/idosal/mcp-ui/compare/v5.4.0...v5.5.0) (2025-08-02)


### Features

* auto resize with the autoResizeIframe prop ([#56](https://github.com/idosal/mcp-ui/issues/56)) ([76c867a](https://github.com/idosal/mcp-ui/commit/76c867a569b72aed892290aa84e1194ab8eb79ce))

# [5.4.0](https://github.com/idosal/mcp-ui/compare/v5.3.1...v5.4.0) (2025-08-01)


### Features

* send render data to the iframe ([#51](https://github.com/idosal/mcp-ui/issues/51)) ([d38cfc7](https://github.com/idosal/mcp-ui/commit/d38cfc7925061c1ae1911bdee408033c8e9f283d))

## [5.3.1](https://github.com/idosal/mcp-ui/compare/v5.3.0...v5.3.1) (2025-07-19)


### Bug Fixes

* Ruby comment ([b22dc2e](https://github.com/idosal/mcp-ui/commit/b22dc2e0a0db20d98ada884649ad408ebaf72d22))
* typescript ci publish ([e7c0ebf](https://github.com/idosal/mcp-ui/commit/e7c0ebfa7f7b552f9763743fda659d1441f21692))

# [5.3.0](https://github.com/idosal/mcp-ui/compare/v5.2.0...v5.3.0) (2025-07-19)


### Features

* add Ruby server SDK ([#31](https://github.com/idosal/mcp-ui/issues/31)) ([5ffcde4](https://github.com/idosal/mcp-ui/commit/5ffcde4a373accdd063fa6c3b1b3d4df13c91b53))


================================================
FILE: sdks/typescript/client/README.md
================================================
## 📦 Model Context Protocol UI SDK

<p align="center">
  <img width="250" alt="image" src="https://github.com/user-attachments/assets/65b9698f-990f-4846-9b2d-88de91d53d4d" />
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@mcp-ui/server"><img src="https://img.shields.io/npm/v/@mcp-ui/server?label=server&color=green" alt="Server Version"></a>
  <a href="https://www.npmjs.com/package/@mcp-ui/client"><img src="https://img.shields.io/npm/v/@mcp-ui/client?label=client&color=blue" alt="Client Version"></a>
  <a href="https://rubygems.org/gems/mcp_ui_server"><img src="https://img.shields.io/gem/v/mcp_ui_server" alt="Ruby Server SDK Version"></a>
  <a href="https://pypi.org/project/mcp-ui-server/"><img src="https://img.shields.io/pypi/v/mcp-ui-server?label=python&color=yellow" alt="Python Server SDK Version"></a>
  <a href="https://discord.gg/CEAG4KW7ZH"><img src="https://img.shields.io/discord/1401195140436983879?logo=discord&label=discord" alt="Discord"></a>
  <a href="https://gitmcp.io/idosal/mcp-ui"><img src="https://img.shields.io/endpoint?url=https://gitmcp.io/badge/idosal/mcp-ui" alt="MCP Documentation"></a>
</p>

<p align="center">
  <a href="#-whats-mcp-ui">What's mcp-ui?</a> •
  <a href="#-core-concepts">Core Concepts</a> •
  <a href="#-installation">Installation</a> •
  <a href="#-getting-started">Getting Started</a> •
  <a href="#-walkthrough">Walkthrough</a> •
  <a href="#-examples">Examples</a> •
  <a href="#-supported-hosts">Supported Hosts</a> •
  <a href="#-security">Security</a> •
  <a href="#-roadmap">Roadmap</a> •
  <a href="#-contributing">Contributing</a> •
  <a href="#-license">License</a>
</p>

----

**`mcp-ui`** brings interactive web components to the [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP). Deliver rich, dynamic UI resources directly from your MCP server to be rendered by the client. Take AI interaction to the next level!

> *This project is an experimental community playground for MCP UI ideas. Expect rapid iteration and enhancements!*

<p align="center">
  <video src="https://github.com/user-attachments/assets/7180c822-2dd9-4f38-9d3e-b67679509483"></video>
</p>

## 💡 What's `mcp-ui`?

`mcp-ui` is a playground for the open spec of UI over MCP. It offers a collection of community SDKs comprising:

* **`@mcp-ui/server` (TypeScript)**: Utilities to generate UI resources (`UIResource`) on your MCP server.
* **`@mcp-ui/client` (TypeScript)**: UI components (e.g., `<AppRenderer />`) to render the UI resources and handle their events.
* **`mcp_ui_server` (Ruby)**: Utilities to generate UI resources on your MCP server in a Ruby environment.
* **`mcp-ui-server` (Python)**: Utilities to generate UI resources on your MCP server in a Python environment.

Together, they let you define reusable UI snippets on the server side, seamlessly and securely render them in the client, and react to their actions in the MCP host environment.

## ✨ Core Concepts

In essence, by using `mcp-ui` SDKs, servers and hosts can agree on contracts that enable them to create and render interactive UI snippets (as a path to a standardized UI approach in MCP).

### UI Resource
The primary payload returned from the server to the client is the `UIResource`:

```ts
interface UIResource {
  type: 'resource';
  resource: {
    uri: string;       // e.g., ui://component/id
    mimeType: 'text/html;profile=mcp-app';
    text?: string;      // HTML content
    blob?: string;      // Base64-encoded HTML content
  };
}
```

* **`uri`**: Unique identifier for caching and routing
  * `ui://…` — UI resources
* **`mimeType`**: `text/html;profile=mcp-app` — the MCP Apps standard MIME type
* **`text` vs. `blob`**: Choose `text` for simple strings; use `blob` for larger or encoded content.

### AppRenderer

For MCP Apps hosts, use `AppRenderer` to render tool UIs:

```tsx
import { AppRenderer } from '@mcp-ui/client';

function ToolUI({ client, toolName, toolInput, toolResult }) {
  return (
    <AppRenderer
      client={client}
      toolName={toolName}
      sandbox={{ url: sandboxUrl }}
      toolInput={toolInput}
      toolResult={toolResult}
    />
  );
}
```

#### Advanced Usage

You can manually wrap HTML with adapters or access adapter scripts directly:

```ts
import { wrapHtmlWithAdapters, getAppsSdkAdapterScript } from '@mcp-ui/server';

// Manually wrap HTML with adapters
const wrappedHtml = wrapHtmlWithAdapters(
  '<button>Click me</button>',
  {
    appsSdk: {
      enabled: true,
      config: { intentHandling: 'ignore' }
    }
  }
);

// Get a specific adapter script
const appsSdkScript = getAppsSdkAdapterScript({ timeout: 60000 });
```

## 🏗️ Installation

### TypeScript

```bash
# using npm
npm install @mcp-ui/server @mcp-ui/client

# or pnpm
pnpm add @mcp-ui/server @mcp-ui/client

# or yarn
yarn add @mcp-ui/server @mcp-ui/client
```

### Ruby

```bash
gem install mcp_ui_server
```

### Python

```bash
# using pip
pip install mcp-ui-server

# or uv
uv add mcp-ui-server
```

## 🚀 Getting Started

You can use [GitMCP](https://gitmcp.io/idosal/mcp-ui) to give your IDE access to `mcp-ui`'s latest documentation! 

### TypeScript

1. **Server-side**: Build your UI resources

   ```ts
   import { createUIResource } from '@mcp-ui/server';
   import {
    createRemoteComponent,
    createRemoteDocument,
    createRemoteText,
   } from '@remote-dom/core';

   // Inline HTML
   const htmlResource = createUIResource({
     uri: 'ui://greeting/1',
     content: { type: 'rawHtml', htmlString: '<p>Hello, MCP UI!</p>' },
     encoding: 'text',
   });

   // External URL
   const externalUrlResource = createUIResource({
     uri: 'ui://greeting/1',
     content: { type: 'externalUrl', iframeUrl: 'https://example.com' },
     encoding: 'text',
   });

   // remote-dom
   const remoteDomResource = createUIResource({
     uri: 'ui://remote-component/action-button',
     content: {
       type: 'remoteDom',
       script: `
        const button = document.createElement('ui-button');
        button.setAttribute('label', 'Click me for a tool call!');
        button.addEventListener('press', () => {
          window.parent.postMessage({ type: 'tool', payload: { toolName: 'uiInteraction', params: { action: 'button-click', from: 'remote-dom' } } }, '*');
        });
        root.appendChild(button);
        `,
       framework: 'react', // or 'webcomponents'
     },
     encoding: 'text',
   });
   ```

2. **Client-side**: Render in your MCP host

   ```tsx
   import React from 'react';
   import { UIResourceRenderer } from '@mcp-ui/client';

   function App({ mcpResource }) {
     if (
       mcpResource.type === 'resource' &&
       mcpResource.resource.uri?.startsWith('ui://')
     ) {
       return (
         <UIResourceRenderer
           resource={mcpResource.resource}
           onUIAction={(result) => {
             console.log('Action:', result);
           }}
         />
       );
     }
     return <p>Unsupported resource</p>;
   }
   ```

### Python

**Server-side**: Build your UI resources

   ```python
   from mcp_ui_server import create_ui_resource

   # Inline HTML
   html_resource = create_ui_resource({
     "uri": "ui://greeting/1",
     "content": { "type": "rawHtml", "htmlString": "<p>Hello, from Python!</p>" },
     "encoding": "text",
   })

   # External URL
   external_url_resource = create_ui_resource({
     "uri": "ui://greeting/2",
     "content": { "type": "externalUrl", "iframeUrl": "https://example.com" },
     "encoding": "text",
   })
   ```

### Ruby

**Server-side**: Build your UI resources

   ```ruby
   require 'mcp_ui_server'

   # Inline HTML
   html_resource = McpUiServer.create_ui_resource(
     uri: 'ui://greeting/1',
     content: { type: :raw_html, htmlString: '<p>Hello, from Ruby!</p>' },
     encoding: :text
   )

   # External URL
   external_url_resource = McpUiServer.create_ui_resource(
     uri: 'ui://greeting/2',
     content: { type: :external_url, iframeUrl: 'https://example.com' },
     encoding: :text
   )

   # remote-dom
   remote_dom_resource = McpUiServer.create_ui_resource(
     uri: 'ui://remote-component/action-button',
     content: {
       type: :remote_dom,
       script: "
        const button = document.createElement('ui-button');
        button.setAttribute('label', 'Click me from Ruby!');
        button.addEventListener('press', () => {
          window.parent.postMessage({ type: 'tool', payload: { toolName: 'uiInteraction', params: { action: 'button-click', from: 'ruby-remote-dom' } } }, '*');
        });
        root.appendChild(button);
        ",
       framework: :react,
     },
     encoding: :text
   )
   ```

## 🚶 Walkthrough

For a detailed, simple, step-by-step guide on how to integrate `mcp-ui` into your own server, check out the full server walkthroughs on the [mcp-ui documentation site](https://mcpui.dev):

- **[TypeScript Server Walkthrough](https://mcpui.dev/guide/server/typescript/walkthrough)**
- **[Ruby Server Walkthrough](https://mcpui.dev/guide/server/ruby/walkthrough)**
- **[Python Server Walkthrough](https://mcpui.dev/guide/server/python/walkthrough)**

These guides will show you how to add a `mcp-ui` endpoint to an existing server, create tools that return UI resources, and test your setup with the `ui-inspector`!

## 🌍 Examples

**Client Examples**
* [Goose](https://github.com/block/goose) - open source AI agent that supports `mcp-ui`.
* [LibreChat](https://github.com/danny-avila/LibreChat) - enhanced ChatGPT clone that supports `mcp-ui`.
* [ui-inspector](https://github.com/idosal/ui-inspector) - inspect local `mcp-ui`-enabled servers.
* [MCP-UI Chat](https://github.com/idosal/scira-mcp-ui-chat) - interactive chat built with the `mcp-ui` client. Check out the [hosted version](https://scira-mcp-chat-git-main-idosals-projects.vercel.app/)!
* MCP-UI RemoteDOM Playground (`examples/remote-dom-demo`) - local demo app to test RemoteDOM resources
* MCP-UI Web Component Demo (`examples/wc-demo`) - local demo app to test the Web Component integration in hosts

**Server Examples**
* **TypeScript**: A [full-featured server](examples/server) that is deployed to a hosted environment for easy testing.
  * **[`typescript-server-demo`](./examples/typescript-server-demo)**: A simple Typescript server that demonstrates how to generate UI resources.
  * **server**: A [full-featured Typescript server](examples/server) that is deployed to a hosted Cloudflare environment for easy testing.
    * **HTTP Streaming**: `https://remote-mcp-server-authless.idosalomon.workers.dev/mcp`
    * **SSE**: `https://remote-mcp-server-authless.idosalomon.workers.dev/sse`
* **Ruby**: A barebones [demo server](/examples/ruby-server-demo) that shows how to use `mcp_ui_server` and `mcp` gems together.
* **Python**: A simple [demo server](/examples/python-server-demo) that shows how to use the `mcp-ui-server` Python package.
* [XMCP](https://github.com/basementstudio/xmcp/tree/main/examples/mcp-ui) - Typescript MCP framework with `mcp-ui` starter example.

Drop those URLs into any MCP-compatible host to see `mcp-ui` in action. For a supported local inspector, see the [ui-inspector](https://github.com/idosal/ui-inspector).

## 💻 Supported Hosts

`mcp-ui` is supported by a growing number of MCP-compatible clients. Feature support varies by host:

| Host      | Rendering | UI Actions | Notes
| :-------- | :-------: | :--------: | :--------: |
| [Nanobot](https://www.nanobot.ai/)    |     ✅    |     ✅     |
| [ChatGPT](https://chatgpt.com/)    |     ✅    |     ⚠️     | [Guide](https://mcpui.dev/guide/apps-sdk)
| [Postman](https://www.postman.com/)   |     ✅    |     ⚠️      |
| [Goose](https://block.github.io/goose/)     |     ✅    |     ⚠️      |
| [LibreChat](https://www.librechat.ai/)    |     ✅    |     ⚠️     |
| [Smithery](https://smithery.ai/playground)  |     ✅    |     ❌     |
| [MCPJam](https://www.mcpjam.com/)    |     ✅    |     ❌     |
| [fast-agent](https://fast-agent.ai/mcp/mcp-ui/) | ✅ | ❌ |
| [VSCode](https://github.com/microsoft/vscode/issues/260218) (TBA)    |    ?    |    ?     |

**Legend:**
- ✅: Supported
- ⚠️: Partial Support
- ❌: Not Supported (yet)

## 🔒 Security
Host and user security is one of `mcp-ui`'s primary concerns. In all content types, the remote code is executed in a sandboxed iframe.

## 🛣️ Roadmap

- [X] Add online playground
- [X] Expand UI Action API (beyond tool calls)
- [X] Support Web Components
- [X] Support Remote-DOM
- [ ] Add component libraries (in progress)
- [ ] Add SDKs for additional programming languages (in progress; Ruby, Python available)
- [ ] Support additional frontend frameworks
- [ ] Add declarative UI content type
- [ ] Support generative UI?
      
## Core Team
`mcp-ui` is a project by [Ido Salomon](https://x.com/idosal1), in collaboration with [Liad Yosef](https://x.com/liadyosef).

## 🤝 Contributing

Contributions, ideas, and bug reports are welcome! See the [contribution guidelines](https://github.com/idosal/mcp-ui/blob/main/.github/CONTRIBUTING.md) to get started.

## 📄 License

Apache License 2.0 © [The MCP-UI Authors](LICENSE)

## Disclaimer

This project is provided "as is", without warranty of any kind. The `mcp-ui` authors and contributors shall not be held liable for any damages, losses, or issues arising from the use of this software. Use at your own risk.


================================================
FILE: sdks/typescript/client/package.json
================================================
{
  "name": "@mcp-ui/client",
  "version": "7.0.0",
  "description": "mcp-ui Client SDK",
  "private": false,
  "type": "module",
  "main": "./dist/index.js",
  "module": "./dist/index.mjs",
  "types": "./dist/src/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/src/index.d.ts",
      "import": "./dist/index.mjs",
      "require": "./dist/index.js"
    }
  },
  "files": [
    "dist"
  ],
  "dependencies": {
    "@modelcontextprotocol/ext-apps": "^1.2.0",
    "@modelcontextprotocol/sdk": "^1.27.1",
    "zod": "^3.23.8"
  },
  "devDependencies": {
    "@testing-library/jest-dom": "^6.0.0",
    "@testing-library/react": "^14.0.0",
    "@types/jsdom": "^27.0.0",
    "@types/react": "^18.2.0",
    "@vitejs/plugin-react": "^4.0.0",
    "jsdom": "^22.0.0",
    "react": "^18.3.1",
    "react-dom": "^18.3.1",
    "rimraf": "^6.0.1",
    "typescript": "^5.0.0",
    "vite": "^5.0.0",
    "vite-plugin-dts": "^3.6.0",
    "vite-tsconfig-paths": "^5.1.4",
    "vitest": "^1.0.0"
  },
  "peerDependencies": {
    "react": "^18 || ^19",
    "react-dom": "^18 || ^19"
  },
  "scripts": {
    "prepublishOnly": "pnpm run build",
    "build": "pnpm run clean && tsc && vite build",
    "clean": "rimraf dist",
    "dev": "vite",
    "test": "vitest run",
    "test:watch": "vitest watch",
    "lint": "eslint ."
  },
  "publishConfig": {
    "access": "public"
  },
  "release": {
    "branches": [
      "main",
      {
        "name": "alpha",
        "prerelease": true
      }
    ],
    "tagFormat": "client/v${version}",
    "plugins": [
      "@semantic-release/commit-analyzer",
      "@semantic-release/release-notes-generator",
      [
        "@semantic-release/changelog",
        {
          "changelogFile": "CHANGELOG.md"
        }
      ],
      "@semantic-release/npm",
      "@semantic-release/github",
      [
        "@semantic-release/git",
        {
          "assets": [
            "CHANGELOG.md",
            "package.json"
          ],
          "message": "chore(release): ${nextRelease.version} [skip ci]\\n\\n${nextRelease.notes}"
        }
      ]
    ]
  },
  "license": "Apache-2.0"
}


================================================
FILE: sdks/typescript/client/scripts/proxy/index.html
================================================
<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>MCP-UI Proxy</title>
    <style>
      html,
      body {
        margin: 0;
        height: 100vh;
        width: 100vw;
      }
      body {
        display: flex;
        flex-direction: column;
      }
      * {
        box-sizing: border-box;
      }
      iframe {
        background-color: transparent;
        border: 0px none transparent;
        padding: 0px;
        overflow: hidden;
        flex-grow: 1;
      }
    </style>
  </head>
  <body>
    <script>
      const params = new URLSearchParams(location.search);
      const contentType = params.get('contentType');
      const target = params.get('url');

      // Validate that the URL is a valid HTTP or HTTPS URL
      function isValidHttpUrl(string) {
        try {
          const url = new URL(string);
          return url.protocol === 'http:' || url.protocol === 'https:';
        } catch (error) {
          return false;
        }
      }

      if (contentType === 'rawhtml') {
        // Double-iframe raw HTML mode (HTML sent via postMessage)
        const inner = document.createElement('iframe');

        inner.id = 'root';
        let pendingHtml = null;

        // Helper function to write HTML using document.write
        const renderHtmlInIframe = (markup) => {
          const doc = inner.contentDocument || inner.contentWindow?.document;
          if (!doc) return false;
          try {
            doc.open();
            doc.write(markup);
            doc.close();
            return true;
          } catch (error) {
            console.error('Failed to write HTML to iframe:', error);
            return false;
          }
        };

        // Retry writing pending HTML when iframe finishes loading
        inner.addEventListener('load', () => {
          if (pendingHtml !== null && renderHtmlInIframe(pendingHtml)) {
            pendingHtml = null;
          }
        });

        inner.style = 'width:100%; height:100%; border:none;';
        // Set src to about:blank so browser initializes contentDocument
        inner.src = 'about:blank';
        document.body.appendChild(inner);

        // Wait for HTML content from parent
        window.addEventListener('message', (event) => {
          if (event.source === window.parent && event.data && event.data.type === 'ui-html-content') {
            const payload = event.data.payload || {};
            const html = payload.html;
            if (typeof html === 'string') {
              // Try to write immediately; if contentDocument isn't ready, queue for retry
              if (!renderHtmlInIframe(html)) {
                pendingHtml = html;
              }
            }
          } else if (event.source === window.parent) {
            // Forward other messages from parent to inner iframe
            if (inner && inner.contentWindow) {
              inner.contentWindow.postMessage(event.data, '*');
            }
          } else if (event.source === inner.contentWindow) {
            // Relay messages from inner to parent
            window.parent.postMessage(event.data, '*');
          }
        });

        // Notify parent that proxy is ready to receive HTML (distinct event)
        window.parent.postMessage({ type: 'ui-proxy-iframe-ready' }, '*');
      } else if (target) {
        if (!isValidHttpUrl(target)) {
          document.body.textContent = 'Error: invalid URL. Only HTTP and HTTPS URLs are allowed.';
        } else {
          const inner = document.createElement('iframe');
          inner.src = target;
          inner.style = 'width:100%; height:100%; border:none;';
          // Default external URL sandbox; can be adjusted later by protocol if needed
          inner.setAttribute('sandbox', 'allow-same-origin allow-scripts');
          document.body.appendChild(inner);
          const urlOrigin = new URL(target).origin;

          window.addEventListener('message', (event) => {
            if (event.source === window.parent) {
              // listen for messages from the parent and send them to the iframe
              inner.contentWindow.postMessage(event.data, urlOrigin);
            } else if (event.source === inner.contentWindow) {
              // listen for messages from the iframe and send them to the parent
              window.parent.postMessage(event.data, '*');
            }
          });
        }
      } else {
        document.body.textContent = 'Error: missing url or html parameter';
      }
    </script>
  </body>
</html>


================================================
FILE: sdks/typescript/client/src/__tests__/capabilities.test.ts
================================================
import { describe, it, expect } from 'vitest';
import {
  type ClientCapabilitiesWithExtensions,
  UI_EXTENSION_NAME,
  UI_EXTENSION_CONFIG,
  UI_EXTENSION_CAPABILITIES,
} from '../capabilities';
import { RESOURCE_MIME_TYPE } from '@modelcontextprotocol/ext-apps/app-bridge';

describe('UI Extension Capabilities', () => {
  it('should have correct extension name', () => {
    expect(UI_EXTENSION_NAME).toBe('io.modelcontextprotocol/ui');
  });

  it('should include RESOURCE_MIME_TYPE in mimeTypes', () => {
    expect(UI_EXTENSION_CONFIG.mimeTypes).toContain(RESOURCE_MIME_TYPE);
    expect(UI_EXTENSION_CONFIG.mimeTypes).toEqual(['text/html;profile=mcp-app']);
  });

  it('should structure capabilities with extension name as key', () => {
    expect(UI_EXTENSION_CAPABILITIES[UI_EXTENSION_NAME]).toEqual(UI_EXTENSION_CONFIG);
  });

  it('should work with ClientCapabilitiesWithExtensions type', () => {
    const capabilities: ClientCapabilitiesWithExtensions = {
      roots: { listChanged: true },
      extensions: UI_EXTENSION_CAPABILITIES,
    };

    expect(capabilities.roots).toEqual({ listChanged: true });
    expect(capabilities.extensions?.[UI_EXTENSION_NAME]).toEqual(UI_EXTENSION_CONFIG);
  });

  it('should allow combining with other MCP capabilities', () => {
    const capabilities: ClientCapabilitiesWithExtensions = {
      roots: { listChanged: true },
      sampling: {},
      extensions: {
        ...UI_EXTENSION_CAPABILITIES,
        'custom/extension': { customKey: 'customValue' },
      },
    };

    expect(capabilities.roots).toEqual({ listChanged: true });
    expect(capabilities.sampling).toEqual({});
    expect(capabilities.extensions?.[UI_EXTENSION_NAME]).toEqual(UI_EXTENSION_CONFIG);
    expect(capabilities.extensions?.['custom/extension']).toEqual({ customKey: 'customValue' });
  });

  it('should allow extensions field to be optional', () => {
    const capabilities: ClientCapabilitiesWithExtensions = {
      roots: { listChanged: true },
    };

    expect(capabilities.extensions).toBeUndefined();
  });
});


================================================
FILE: sdks/typescript/client/src/capabilities.ts
================================================
import type { ClientCapabilities } from '@modelcontextprotocol/sdk/types.js';
import { RESOURCE_MIME_TYPE } from '@modelcontextprotocol/ext-apps/app-bridge';

/**
 * Extended ClientCapabilities type that includes the `extensions` field.
 *
 * This type is a forward-compatible extension of the MCP SDK's ClientCapabilities,
 * adding support for the `extensions` field pattern proposed in SEP-1724.
 *
 * @see https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1724
 */
export interface ClientCapabilitiesWithExtensions extends ClientCapabilities {
  extensions?: {
    [extensionName: string]: unknown;
  };
}

/**
 * Extension identifier for MCP UI support.
 *
 * Follows the pattern from SEP-1724: `{vendor-prefix}/{extension-name}`
 *
 * @see https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1724
 */
export const UI_EXTENSION_NAME = 'io.modelcontextprotocol/ui' as const;

/**
 * UI extension capability configuration.
 *
 * Declares support for rendering UI resources with specific MIME types.
 */
export const UI_EXTENSION_CONFIG = {
  mimeTypes: [RESOURCE_MIME_TYPE],
} as const;

/**
 * UI extension capabilities object to use in the `extensions` field.
 *
 * Use this when creating an MCP Client to declare support for rendering
 * UI resources.
 *
 * @example
 * ```typescript
 * import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 * import {
 *   type ClientCapabilitiesWithExtensions,
 *   UI_EXTENSION_CAPABILITIES,
 * } from '@mcp-ui/client';
 *
 * const capabilities: ClientCapabilitiesWithExtensions = {
 *   // Standard MCP capabilities
 *   roots: { listChanged: true },
 *   // UI extension support (SEP-1724 pattern)
 *   extensions: UI_EXTENSION_CAPABILITIES,
 * };
 *
 * const client = new Client(
 *   { name: 'my-app', version: '1.0.0' },
 *   { capabilities }
 * );
 * ```
 *
 * @see https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1724
 */
export const UI_EXTENSION_CAPABILITIES = {
  [UI_EXTENSION_NAME]: UI_EXTENSION_CONFIG,
} as const;


================================================
FILE: sdks/typescript/client/src/components/AppFrame.tsx
================================================
import { useEffect, useRef, useState } from 'react';

import type { CallToolResult, Implementation } from '@modelcontextprotocol/sdk/types.js';

import {
  type AppBridge,
  PostMessageTransport,
  type McpUiSizeChangedNotification,
  type McpUiResourceCsp,
  type McpUiAppCapabilities,
} from '@modelcontextprotocol/ext-apps/app-bridge';

import { setupSandboxProxyIframe } from '../utils/app-host-utils';

/**
 * Build sandbox URL with CSP query parameter for HTTP header-based CSP enforcement.
 *
 * When the proxy server supports it, CSP passed via query parameter allows the server
 * to set CSP via HTTP headers (tamper-proof) rather than relying on meta tags or
 * postMessage-based CSP injection (which can be bypassed by malicious content).
 *
 * @see https://github.com/modelcontextprotocol/ext-apps/pull/234
 */
function buildSandboxUrl(baseUrl: URL, csp?: McpUiResourceCsp): URL {
  const url = new URL(baseUrl.href);
  if (csp && Object.keys(csp).length > 0) {
    url.searchParams.set('csp', JSON.stringify(csp));
  }
  return url;
}

/**
 * Information about the guest app, available after initialization.
 */
export interface AppInfo {
  /** Guest app's name and version */
  appVersion?: Implementation;
  /** Guest app's declared capabilities */
  appCapabilities?: McpUiAppCapabilities;
}

/**
 * Sandbox configuration for the iframe.
 */
export interface SandboxConfig {
  /** URL to the sandbox proxy HTML */
  url: URL;
  /** Override iframe sandbox attribute (default: "allow-scripts allow-same-origin allow-forms") */
  permissions?: string;
  /**
   * CSP metadata for the sandbox.
   *
   * This CSP is passed to the sandbox proxy in two ways:
   * 1. Via URL query parameter (`?csp=<json>`) - allows servers that support it to set
   *    CSP via HTTP headers (tamper-proof, recommended)
   * 2. Via postMessage after sandbox loads - fallback for proxies that don't parse query params
   *
   * For maximum security, use a proxy server that reads the `csp` query parameter and sets
   * Content-Security-Policy HTTP headers accordingly.
   *
   * @see https://github.com/modelcontextprotocol/ext-apps/pull/234
   */
  csp?: McpUiResourceCsp;
}

/**
 * Props for the AppFrame component.
 */
export interface AppFrameProps {
  /** Pre-fetched HTML content to render in the sandbox */
  html: string;

  /** Sandbox configuration */
  sandbox: SandboxConfig;

  /** Pre-configured AppBridge for MCP communication (required) */
  appBridge: AppBridge;

  /** Callback when guest reports size change */
  onSizeChanged?: (params: McpUiSizeChangedNotification['params']) => void;

  /** Callback when app initialization completes, with app info */
  onInitialized?: (appInfo: AppInfo) => void;

  /** Tool input arguments to send when app initializes */
  toolInput?: Record<string, unknown>;

  /** Tool result to send when app initializes */
  toolResult?: CallToolResult;

  /** Callback when an error occurs */
  onError?: (error: Error) => void;
}

/**
 * Low-level component that renders pre-fetched HTML in a sandboxed iframe.
 *
 * This component requires a pre-configured AppBridge for MCP communication.
 * For automatic AppBridge creation and resource fetching, use the higher-level
 * AppRenderer component instead.
 *
 * @example With pre-configured AppBridge
 * ```tsx
 * const appBridge = new AppBridge(client, hostInfo, capabilities);
 * // ... configure appBridge handlers ...
 *
 * <AppFrame
 *   html={htmlContent}
 *   sandbox={{ url: sandboxUrl }}
 *   appBridge={appBridge}
 *   toolInput={args}
 *   toolResult={result}
 *   onSizeChanged={({ width, height }) => console.log('Size:', width, height)}
 * />
 * ```
 */
export const AppFrame = (props: AppFrameProps) => {
  const { html, sandbox, appBridge, onSizeChanged, onInitialized, toolInput, toolResult, onError } =
    props;

  const [iframeReady, setIframeReady] = useState(false);
  const [bridgeConnected, setBridgeConnected] = useState(false);
  const [error, setError] = useState<Error | null>(null);
  const containerRef = useRef<HTMLDivElement | null>(null);
  const iframeRef = useRef<HTMLIFrameElement | null>(null);
  // Track the current sandbox URL to detect when it changes
  const currentSandboxUrlRef = useRef<string | null>(null);
  // Track the current appBridge to detect when it changes (for isolation)
  const currentAppBridgeRef = useRef<AppBridge | null>(null);

  // Refs for callbacks to avoid effect re-runs
  const onSizeChangedRef = useRef(onSizeChanged);
  const onInitializedRef = useRef(onInitialized);
  const onErrorRef = useRef(onError);

  useEffect(() => {
    onSizeChangedRef.current = onSizeChanged;
    onInitializedRef.current = onInitialized;
    onErrorRef.current = onError;
  });

  // Effect 1: Set up sandbox iframe and connect AppBridge
  useEffect(() => {
    // Build sandbox URL with CSP query parameter for HTTP header-based CSP enforcement.
    // Servers that support this will parse the CSP from the query param and set it via
    // HTTP headers (tamper-proof). The CSP is also sent via postMessage as fallback.
    const sandboxUrl = buildSandboxUrl(sandbox.url, sandbox.csp);
    const sandboxUrlString = sandboxUrl.href;

    // If we already have an iframe set up for this sandbox URL AND the same appBridge, skip setup
    // This preserves the iframe state across React re-renders (including StrictMode)
    // but ensures isolation when switching to a different app/resource (different appBridge)
    if (
      currentSandboxUrlRef.current === sandboxUrlString &&
      currentAppBridgeRef.current === appBridge &&
      iframeRef.current
    ) {
      return;
    }

    // Reset state when setting up a new iframe/bridge to ensure isolation
    // between different apps/resources
    setIframeReady(false);
    setBridgeConnected(false);
    setError(null);

    let mounted = true;

    const setup = async () => {
      try {
        // If switching to a different sandbox URL or appBridge, clean up the old iframe first
        if (iframeRef.current && containerRef.current?.contains(iframeRef.current)) {
          containerRef.current.removeChild(iframeRef.current);
          iframeRef.current = null;
          currentSandboxUrlRef.current = null;
          currentAppBridgeRef.current = null;
        }

        const { iframe, onReady } = await setupSandboxProxyIframe(sandboxUrl);

        if (!mounted) return;

        iframeRef.current = iframe;
        currentSandboxUrlRef.current = sandboxUrlString;
        currentAppBridgeRef.current = appBridge;
        if (containerRef.current) {
          containerRef.current.appendChild(iframe);
        }

        await onReady;

        if (!mounted) return;

        // Register size change handler
        appBridge.onsizechange = async (params) => {
          onSizeChangedRef.current?.(params);
          // Also update iframe size
          if (iframeRef.current) {
            if (params.width !== undefined) {
              iframeRef.current.style.width = `${params.width}px`;
            }
            if (params.height !== undefined) {
              iframeRef.current.style.height = `${params.height}px`;
            }
          }
        };

        // Hook into initialization
        appBridge.oninitialized = () => {
          if (!mounted) return;
          console.log('[AppFrame] App initialized');
          setIframeReady(true);
          onInitializedRef.current?.({
            appVersion: appBridge.getAppVersion(),
            appCapabilities: appBridge.getAppCapabilities(),
          });
        };

        // Connect the bridge
        await appBridge.connect(
          new PostMessageTransport(iframe.contentWindow!, iframe.contentWindow!),
        );

        if (!mounted) return;

        setBridgeConnected(true);
      } catch (err) {
        console.error('[AppFrame] Error:', err);
        if (!mounted) return;
        const error = err instanceof Error ? err : new Error(String(err));
        setError(error);
        onErrorRef.current?.(error);
      }
    };

    setup();

    return () => {
      mounted = false;
    };
  }, [sandbox.url, sandbox.csp, appBridge]);

  // Effect 2: Send HTML to sandbox when bridge is connected
  useEffect(() => {
    // Ensure we only send HTML to the correct appBridge that's currently connected
    // This prevents race conditions when switching between apps
    if (!bridgeConnected || !html || currentAppBridgeRef.current !== appBridge) return;

    const sendHtml = async () => {
      try {
        console.log('[AppFrame] Sending HTML to sandbox');
        await appBridge.sendSandboxResourceReady({
          html,
          csp: sandbox.csp,
        });
      } catch (err) {
        const error = err instanceof Error ? err : new Error(String(err));
        setError(error);
        onErrorRef.current?.(error);
      }
    };

    sendHtml();
  }, [bridgeConnected, html, appBridge, sandbox.csp]);

  // Effect 3: Send tool input when ready
  useEffect(() => {
    // Ensure we only send to the correct appBridge that's currently connected
    if (bridgeConnected && iframeReady && toolInput && currentAppBridgeRef.current === appBridge) {
      console.log('[AppFrame] Sending tool input:', toolInput);
      appBridge.sendToolInput({ arguments: toolInput });
    }
  }, [appBridge, bridgeConnected, iframeReady, toolInput]);

  // Effect 4: Send tool result when ready
  useEffect(() => {
    // Ensure we only send to the correct appBridge that's currently connected
    if (bridgeConnected && iframeReady && toolResult && currentAppBridgeRef.current === appBridge) {
      console.log('[AppFrame] Sending tool result:', toolResult);
      appBridge.sendToolResult(toolResult);
    }
  }, [appBridge, bridgeConnected, iframeReady, toolResult]);

  return (
    <div
      ref={containerRef}
      style={{
        width: '100%',
        height: '100%',
        display: 'flex',
        flexDirection: 'column',
      }}
    >
      {error && <div style={{ color: 'red', padding: '1rem' }}>Error: {error.message}</div>}
    </div>
  );
};


================================================
FILE: sdks/typescript/client/src/components/AppRenderer.tsx
================================================
import { useEffect, useRef, useState, useImperativeHandle, forwardRef } from 'react';

import { type Client } from '@modelcontextprotocol/sdk/client/index.js';
import {
  type CallToolRequest,
  type CallToolResult,
  type JSONRPCRequest,
  type ListPromptsRequest,
  type ListPromptsResult,
  type ListResourcesRequest,
  type ListResourcesResult,
  type ListResourceTemplatesRequest,
  type ListResourceTemplatesResult,
  type LoggingMessageNotification,
  type ReadResourceRequest,
  type ReadResourceResult,
  McpError,
  ErrorCode,
} from '@modelcontextprotocol/sdk/types.js';

import {
  AppBridge,
  RESOURCE_MIME_TYPE,
  type McpUiMessageRequest,
  type McpUiMessageResult,
  type McpUiOpenLinkRequest,
  type McpUiOpenLinkResult,
  type McpUiSizeChangedNotification,
  type McpUiToolInputPartialNotification,
  type McpUiHostContext,
} from '@modelcontextprotocol/ext-apps/app-bridge';

import { AppFrame, type SandboxConfig } from './AppFrame';
import { getToolUiResourceUri, readToolUiResourceHtml } from '../utils/app-host-utils';

/**
 * Extra metadata passed to request handlers (from AppBridge).
 */
export type RequestHandlerExtra = Parameters<Parameters<AppBridge['setRequestHandler']>[1]>[1];

/**
 * Handle to access AppRenderer methods for sending notifications to the Guest UI.
 * Obtained via ref on AppRenderer.
 */
export interface AppRendererHandle {
  /** Notify the Guest UI that the server's tool list has changed */
  sendToolListChanged: () => void;
  /** Notify the Guest UI that the server's resource list has changed */
  sendResourceListChanged: () => void;
  /** Notify the Guest UI that the server's prompt list has changed */
  sendPromptListChanged: () => void;
  /** Notify the Guest UI that the resource is being torn down / cleaned up */
  teardownResource: () => void;
}

/**
 * Props for the AppRenderer component.
 */
export interface AppRendererProps {
  /** MCP client connected to the server providing the tool. Omit to disable automatic MCP forwarding and use custom handlers instead. */
  client?: Client;

  /** Name of the MCP tool to render UI for */
  toolName: string;

  /** Sandbox configuration */
  sandbox: SandboxConfig;

  /** Optional pre-fetched resource URI. If not provided, will be fetched via getToolUiResourceUri() */
  toolResourceUri?: string;

  /** Optional pre-fetched HTML. If provided, skips all resource fetching */
  html?: string;

  /** Optional input arguments to pass to the tool UI once it's ready */
  toolInput?: Record<string, unknown>;

  /** Optional result from tool execution to pass to the tool UI once it's ready */
  toolResult?: CallToolResult;

  /** Partial/streaming tool input to send to the guest UI */
  toolInputPartial?: McpUiToolInputPartialNotification['params'];

  /** Set to true to notify the guest UI that the tool execution was cancelled */
  toolCancelled?: boolean;

  /** Host context (theme, viewport, locale, etc.) to pass to the guest UI */
  hostContext?: McpUiHostContext;

  /** Handler for open-link requests from the guest UI */
  onOpenLink?: (
    params: McpUiOpenLinkRequest['params'],
    extra: RequestHandlerExtra,
  ) => Promise<McpUiOpenLinkResult>;

  /** Handler for message requests from the guest UI */
  onMessage?: (
    params: McpUiMessageRequest['params'],
    extra: RequestHandlerExtra,
  ) => Promise<McpUiMessageResult>;

  /** Handler for logging messages from the guest UI */
  onLoggingMessage?: (params: LoggingMessageNotification['params']) => void;

  /** Handler for size change notifications from the guest UI */
  onSizeChanged?: (params: McpUiSizeChangedNotification['params']) => void;

  /** Callback invoked when an error occurs during setup or message handling */
  onError?: (error: Error) => void;

  // --- MCP Request Handlers (override automatic forwarding) ---

  /**
   * Handler for tools/call requests from the guest UI.
   * If provided, overrides the automatic forwarding to the MCP client.
   */
  onCallTool?: (
    params: CallToolRequest['params'],
    extra: RequestHandlerExtra,
  ) => Promise<CallToolResult>;

  /**
   * Handler for resources/list requests from the guest UI.
   * If provided, overrides the automatic forwarding to the MCP client.
   */
  onListResources?: (
    params: ListResourcesRequest['params'],
    extra: RequestHandlerExtra,
  ) => Promise<ListResourcesResult>;

  /**
   * Handler for resources/templates/list requests from the guest UI.
   * If provided, overrides the automatic forwarding to the MCP client.
   */
  onListResourceTemplates?: (
    params: ListResourceTemplatesRequest['params'],
    extra: RequestHandlerExtra,
  ) => Promise<ListResourceTemplatesResult>;

  /**
   * Handler for resources/read requests from the guest UI.
   * If provided, overrides the automatic forwarding to the MCP client.
   */
  onReadResource?: (
    params: ReadResourceRequest['params'],
    extra: RequestHandlerExtra,
  ) => Promise<ReadResourceResult>;

  /**
   * Handler for prompts/list requests from the guest UI.
   * If provided, overrides the automatic forwarding to the MCP client.
   */
  onListPrompts?: (
    params: ListPromptsRequest['params'],
    extra: RequestHandlerExtra,
  ) => Promise<ListPromptsResult>;

  /**
   * Handler for JSON-RPC requests from the guest UI that don't match any
   * built-in handler (e.g., experimental methods like "x/clipboard/write",
   * or standard MCP methods not yet in the Apps spec like "sampling/createMessage").
   *
   * This is wired to AppBridge's `fallbackRequestHandler` from the MCP SDK Protocol class.
   * It receives the full JSON-RPC request and should return a result object or throw
   * a McpError for unsupported methods.
   *
   * @example
   * ```tsx
   * <AppRenderer
   *   onFallbackRequest={async (request, extra) => {
   *     switch (request.method) {
   *       case 'x/clipboard/write':
   *         await navigator.clipboard.writeText(request.params?.text);
   *         return { success: true };
   *       case 'sampling/createMessage':
   *         return mcpClient.createMessage(request.params);
   *       default:
   *         throw new McpError(ErrorCode.MethodNotFound, `Unknown method: ${request.method}`);
   *     }
   *   }}
   * />
   * ```
   */
  onFallbackRequest?: (
    request: JSONRPCRequest,
    extra: RequestHandlerExtra,
  ) => Promise<Record<string, unknown>>;
}

/**
 * React component that renders an MCP tool's custom UI in a sandboxed iframe.
 *
 * This component manages the complete lifecycle of an MCP Apps tool:
 * 1. Creates AppBridge for MCP communication
 * 2. Fetches the tool's UI resource (HTML) if not provided
 * 3. Delegates rendering to AppFrame
 * 4. Handles UI actions (intents, link opening, prompts, notifications)
 *
 * For lower-level control or when you already have the HTML content,
 * use the AppFrame component directly.
 *
 * @example Basic usage
 * ```tsx
 * <AppRenderer
 *   sandbox={{ url: new URL('http://localhost:8765/sandbox_proxy.html') }}
 *   client={mcpClient}
 *   toolName="create-chart"
 *   toolInput={{ data: [1, 2, 3], type: 'bar' }}
 *   onOpenLink={async ({ url }) => window.open(url)}
 *   onError={(error) => console.error('UI Error:', error)}
 * />
 * ```
 *
 * @example With pre-fetched HTML (skips resource fetching)
 * ```tsx
 * <AppRenderer
 *   sandbox={{ url: sandboxUrl }}
 *   client={mcpClient}
 *   toolName="my-tool"
 *   html={preloadedHtml}
 *   toolInput={args}
 * />
 * ```
 *
 * @example Using ref to access AppBridge methods
 * ```tsx
 * const appRef = useRef<AppRendererHandle>(null);
 *
 * // Notify guest UI when tools change
 * useEffect(() => {
 *   appRef.current?.sendToolListChanged();
 * }, [toolsVersion]);
 *
 * <AppRenderer ref={appRef} ... />
 * ```
 *
 * @example With custom MCP request handlers (no client)
 * ```tsx
 * <AppRenderer
 *   // client omitted - use toolResourceUri + onReadResource to fetch HTML
 *   sandbox={{ url: sandboxUrl }}
 *   toolName="my-tool"
 *   toolResourceUri="ui://my-server/my-tool"
 *   onReadResource={async ({ uri }) => {
 *     // Proxy to your MCP client (e.g., in a different context)
 *     return myMcpProxy.readResource({ uri });
 *   }}
 *   onCallTool={async (params) => {
 *     // Custom tool call handling with caching/filtering
 *     return myCustomToolCall(params);
 *   }}
 *   onListResources={async () => {
 *     // Aggregate resources from multiple servers
 *     return { resources: [...server1Resources, ...server2Resources] };
 *   }}
 * />
 * ```
 */
export const AppRenderer = forwardRef<AppRendererHandle, AppRendererProps>((props, ref) => {
  const {
    client,
    toolName,
    sandbox,
    toolResourceUri,
    html: htmlProp,
    toolInput,
    toolResult,
    toolInputPartial,
    toolCancelled,
    hostContext,
    onMessage,
    onOpenLink,
    onLoggingMessage,
    onSizeChanged,
    onError,
    onCallTool,
    onListResources,
    onListResourceTemplates,
    onReadResource,
    onListPrompts,
    onFallbackRequest,
  } = props;

  // State
  const [appBridge, setAppBridge] = useState<AppBridge | null>(null);
  const [html, setHtml] = useState<string | null>(htmlProp ?? null);
  const [error, setError] = useState<Error | null>(null);

  // Refs for callbacks
  const onMessageRef = useRef(onMessage);
  const onOpenLinkRef = useRef(onOpenLink);
  const onLoggingMessageRef = useRef(onLoggingMessage);
  const onSizeChangedRef = useRef(onSizeChanged);
  const onErrorRef = useRef(onError);
  const onCallToolRef = useRef(onCallTool);
  const onListResourcesRef = useRef(onListResources);
  const onListResourceTemplatesRef = useRef(onListResourceTemplates);
  const onReadResourceRef = useRef(onReadResource);
  const onListPromptsRef = useRef(onListPrompts);
  const onFallbackRequestRef = useRef(onFallbackRequest);

  useEffect(() => {
    onMessageRef.current = onMessage;
    onOpenLinkRef.current = onOpenLink;
    onLoggingMessageRef.current = onLoggingMessage;
    onSizeChangedRef.current = onSizeChanged;
    onErrorRef.current = onError;
    onCallToolRef.current = onCallTool;
    onListResourcesRef.current = onListResources;
    onListResourceTemplatesRef.current = onListResourceTemplates;
    onReadResourceRef.current = onReadResource;
    onListPromptsRef.current = onListPrompts;
    onFallbackRequestRef.current = onFallbackRequest;
  });

  // Expose send methods via ref for Host → Guest notifications
  useImperativeHandle(
    ref,
    () => ({
      sendToolListChanged: () => appBridge?.sendToolListChanged(),
      sendResourceListChanged: () => appBridge?.sendResourceListChanged(),
      sendPromptListChanged: () => appBridge?.sendPromptListChanged(),
      teardownResource: () => appBridge?.teardownResource({}),
    }),
    [appBridge],
  );

  // Effect 1: Create and configure AppBridge
  useEffect(() => {
    let mounted = true;

    const createBridge = () => {
      try {
        const serverCapabilities = client?.getServerCapabilities();
        const bridge = new AppBridge(
          client ?? null,
          {
            name: 'MCP-UI Host',
            version: '1.0.0',
          },
          {
            openLinks: {},
            serverTools: serverCapabilities?.tools,
            serverResources: serverCapabilities?.resources,
          },
        );

        // Register message handler
        bridge.onmessage = async (params, extra) => {
          if (onMessageRef.current) {
            return onMessageRef.current(params, extra);
          } else {
            throw new McpError(ErrorCode.MethodNotFound, 'Method not found');
          }
        };

        // Register open-link handler
        bridge.onopenlink = async (params, extra) => {
          if (onOpenLinkRef.current) {
            return onOpenLinkRef.current(params, extra);
          } else {
            throw new McpError(ErrorCode.MethodNotFound, 'Method not found');
          }
        };

        // Register logging handler
        bridge.onloggingmessage = (params) => {
          if (onLoggingMessageRef.current) {
            onLoggingMessageRef.current(params);
          }
        };

        // Register custom MCP request handlers (these override automatic forwarding)
        if (onCallToolRef.current) {
          bridge.oncalltool = (params, extra) => onCallToolRef.current!(params, extra);
        }
        if (onListResourcesRef.current) {
          bridge.onlistresources = (params, extra) => onListResourcesRef.current!(params, extra);
        }
        if (onListResourceTemplatesRef.current) {
          bridge.onlistresourcetemplates = (params, extra) =>
            onListResourceTemplatesRef.current!(params, extra);
        }
        if (onReadResourceRef.current) {
          bridge.onreadresource = (params, extra) => onReadResourceRef.current!(params, extra);
        }
        if (onListPromptsRef.current) {
          bridge.onlistprompts = (params, extra) => onListPromptsRef.current!(params, extra);
        }

        // Register fallback handler for unregistered JSON-RPC methods
        // (e.g., experimental events like "x/clipboard/write" or MCP methods
        // not yet in the Apps spec like "sampling/createMessage")
        bridge.fallbackRequestHandler = async (request, extra) => {
          if (onFallbackRequestRef.current) {
            return onFallbackRequestRef.current(request, extra);
          }
          throw new McpError(
            ErrorCode.MethodNotFound,
            `No handler for method: ${request.method}`,
          );
        };

        if (!mounted) return;
        setAppBridge(bridge);
      } catch (err) {
        console.error('[AppRenderer] Error creating bridge:', err);
        if (!mounted) return;
        const error = err instanceof Error ? err : new Error(String(err));
        setError(error);
        onErrorRef.current?.(error);
      }
    };

    createBridge();

    return () => {
      mounted = false;
    };
  }, [client]);

  // Effect 2: Fetch HTML if not provided
  useEffect(() => {
    if (htmlProp) {
      setHtml(htmlProp);
      return;
    }

    // Determine if we can fetch HTML
    const canFetchWithClient = !!client;
    const canFetchWithCallback = !!toolResourceUri && !!onReadResourceRef.current;

    if (!canFetchWithClient && !canFetchWithCallback) {
      setError(
        new Error(
          "Either 'html' prop, 'client', or ('toolResourceUri' + 'onReadResource') must be provided to fetch UI resource",
        ),
      );
      return;
    }

    let mounted = true;

    const fetchHtml = async () => {
      try {
        // Get resource URI
        let uri: string;
        if (toolResourceUri) {
          uri = toolResourceUri;
          console.log(`[AppRenderer] Using provided resource URI: ${uri}`);
        } else if (client) {
          console.log(`[AppRenderer] Fetching resource URI for tool: ${toolName}`);
          const info = await getToolUiResourceUri(client, toolName);
          if (!info) {
            throw new Error(
              `Tool ${toolName} has no UI resource (no ui/resourceUri in tool._meta)`,
            );
          }
          uri = info.uri;
          console.log(`[AppRenderer] Got resource URI: ${uri}`);
        } else {
          throw new Error('Cannot determine resource URI without client or toolResourceUri');
        }

        if (!mounted) return;

        // Read HTML content - use client if available, otherwise use onReadResource callback
        console.log(`[AppRenderer] Reading resource HTML from: ${uri}`);
        let htmlContent: string;

        if (client) {
          htmlContent = await readToolUiResourceHtml(client, { uri });
        } else if (onReadResourceRef.current) {
          // Use the onReadResource callback to fetch the HTML
          const result = await onReadResourceRef.current({ uri }, {} as RequestHandlerExtra);
          if (!result.contents || result.contents.length !== 1) {
            throw new Error('Unsupported UI resource content length: ' + result.contents?.length);
          }
          const content = result.contents[0];
          const isHtml = (t?: string) => t === RESOURCE_MIME_TYPE;

          if ('text' in content && typeof content.text === 'string' && isHtml(content.mimeType)) {
            htmlContent = content.text;
          } else if (
            'blob' in content &&
            typeof content.blob === 'string' &&
            isHtml(content.mimeType)
          ) {
            htmlContent = atob(content.blob);
          } else {
            throw new Error('Unsupported UI resource content format: ' + JSON.stringify(content));
          }
        } else {
          throw new Error('No way to read resource HTML');
        }

        if (!mounted) return;

        setHtml(htmlContent);
      } catch (err) {
        if (!mounted) return;
        const error = err instanceof Error ? err : new Error(String(err));
        setError(error);
        onErrorRef.current?.(error);
      }
    };

    fetchHtml();

    return () => {
      mounted = false;
    };
  }, [client, toolName, toolResourceUri, htmlProp]);

  // Effect 3: Sync host context when it changes
  useEffect(() => {
    if (appBridge && hostContext) {
      appBridge.setHostContext(hostContext);
    }
  }, [appBridge, hostContext]);

  // Effect 4: Send partial tool input when it changes
  useEffect(() => {
    if (appBridge && toolInputPartial) {
      appBridge.sendToolInputPartial(toolInputPartial);
    }
  }, [appBridge, toolInputPartial]);

  // Effect 5: Send tool cancelled notification when flag is set
  useEffect(() => {
    if (appBridge && toolCancelled) {
      appBridge.sendToolCancelled({});
    }
  }, [appBridge, toolCancelled]);

  // Handle size change callback
  const handleSizeChanged = onSizeChangedRef.current;

  // Render error state
  if (error) {
    return <div style={{ color: 'red', padding: '1rem' }}>Error: {error.message}</div>;
  }

  // Render loading state
  if (!appBridge || !html) {
    return null;
  }

  // Render AppFrame with the fetched HTML and configured bridge
  return (
    <AppFrame
      html={html}
      sandbox={sandbox}
      appBridge={appBridge}
      toolInput={toolInput}
      toolResult={toolResult}
      onSizeChanged={handleSizeChanged}
      onError={onError}
    />
  );
});

AppRenderer.displayName = 'AppRenderer';


================================================
FILE: sdks/typescript/client/src/components/__tests__/AppFrame.test.tsx
================================================
import { render, screen, waitFor, act } from '@testing-library/react';
import { vi, describe, it, expect, beforeEach, afterEach } from 'vitest';
import '@testing-library/jest-dom';

import { AppFrame, type AppFrameProps } from '../AppFrame';
import * as appHostUtils from '../../utils/app-host-utils';
import type { AppBridge } from '@modelcontextprotocol/ext-apps/app-bridge';

// Mock the ext-apps module
vi.mock('@modelcontextprotocol/ext-apps/app-bridge', () => {
  // Create a mock constructor for PostMessageTransport
  const MockPostMessageTransport = vi.fn().mockImplementation(function (this: unknown) {
    return this;
  });

  return {
    AppBridge: vi.fn(),
    PostMessageTransport: MockPostMessageTransport,
  };
});

// Track registered handlers
let registeredOninitialized: (() => void) | null = null;
let registeredOnsizechange: ((params: { width?: number; height?: number }) => void) | null = null;

// Mock AppBridge factory
const createMockAppBridge = () => {
  const bridge = {
    connect: vi.fn().mockResolvedValue(undefined),
    sendSandboxResourceReady: vi.fn().mockResolvedValue(undefined),
    sendToolInput: vi.fn(),
    sendToolResult: vi.fn(),
    getAppVersion: vi.fn().mockReturnValue({ name: 'TestApp', version: '1.0.0' }),
    getAppCapabilities: vi.fn().mockReturnValue({ tools: {} }),
    _oninitialized: null as (() => void) | null,
    _onsizechange: null as ((params: { width?: number; height?: number }) => void) | null,
  };

  Object.defineProperty(bridge, 'oninitialized', {
    set: (fn) => {
      bridge._oninitialized = fn;
      registeredOninitialized = fn;
    },
    get: () => bridge._oninitialized,
  });
  Object.defineProperty(bridge, 'onsizechange', {
    set: (fn) => {
      bridge._onsizechange = fn;
      registeredOnsizechange = fn;
    },
    get: () => bridge._onsizechange,
  });

  return bridge;
};

// Mock the app-host-utils module
vi.mock('../../utils/app-host-utils', () => ({
  setupSandboxProxyIframe: vi.fn(),
}));

describe('<AppFrame />', () => {
  let mockIframe: Partial<HTMLIFrameElement>;
  let mockContentWindow: { postMessage: ReturnType<typeof vi.fn> };
  let onReadyResolve: () => void;
  let mockAppBridge: ReturnType<typeof createMockAppBridge>;

  beforeEach(() => {
    vi.clearAllMocks();
    registeredOninitialized = null;
    registeredOnsizechange = null;
    mockAppBridge = createMockAppBridge();

    // Create mock contentWindow
    mockContentWindow = {
      postMessage: vi.fn(),
    };

    // Create a real iframe element and mock contentWindow via defineProperty
    const realIframe = document.createElement('iframe');
    Object.defineProperty(realIframe, 'contentWindow', {
      get: () => mockContentWindow as unknown as Window,
      configurable: true,
    });
    mockIframe = realIframe;

    // Setup mock for setupSandboxProxyIframe
    const onReadyPromise = new Promise<void>((resolve) => {
      onReadyResolve = resolve;
    });

    vi.mocked(appHostUtils.setupSandboxProxyIframe).mockResolvedValue({
      iframe: mockIframe as HTMLIFrameElement,
      onReady: onReadyPromise,
    });
  });

  afterEach(() => {
    vi.clearAllMocks();
  });

  const defaultProps: Omit<AppFrameProps, 'appBridge'> = {
    html: '<html><body>Test</body></html>',
    sandbox: { url: new URL('http://localhost:8081/sandbox.html') },
  };

  const getPropsWithBridge = (overrides: Partial<AppFrameProps> = {}): AppFrameProps => ({
    ...defaultProps,
    appBridge: mockAppBridge as unknown as AppBridge,
    ...overrides,
  });

  it('should render without crashing', () => {
    render(<AppFrame {...getPropsWithBridge()} />);
    expect(document.querySelector('div')).toBeInTheDocument();
  });

  it('should call setupSandboxProxyIframe with sandbox URL', async () => {
    render(<AppFrame {...getPropsWithBridge()} />);

    await waitFor(() => {
      expect(appHostUtils.setupSandboxProxyIframe).toHaveBeenCalledWith(defaultProps.sandbox.url);
    });
  });

  it('should connect AppBridge when provided', async () => {
    render(<AppFrame {...getPropsWithBridge()} />);

    await act(() => {
      onReadyResolve();
    });

    await waitFor(() => {
      expect(mockAppBridge.connect).toHaveBeenCalled();
    });
  });

  it('should send HTML via AppBridge.sendSandboxResourceReady', async () => {
    render(<AppFrame {...getPropsWithBridge()} />);

    await act(() => {
      onReadyResolve();
    });

    // Trigger initialization
    await act(() => {
      registeredOninitialized?.();
    });

    await waitFor(() => {
      expect(mockAppBridge.sendSandboxResourceReady).toHaveBeenCalledWith({
        html: defaultProps.html,
        csp: undefined,
      });
    });
  });

  it('should call onInitialized with app info when app initializes', async () => {
    const onInitialized = vi.fn();

    render(<AppFrame {...getPropsWithBridge({ onInitialized })} />);

    await act(() => {
      onReadyResolve();
    });

    await act(() => {
      registeredOninitialized?.();
    });

    await waitFor(() => {
      expect(onInitialized).toHaveBeenCalledWith({
        appVersion: { name: 'TestApp', version: '1.0.0' },
        appCapabilities: { tools: {} },
      });
    });
  });

  it('should send tool input after initialization', async () => {
    const toolInput = { foo: 'bar' };

    render(<AppFrame {...getPropsWithBridge({ toolInput })} />);

    await act(() => {
      onReadyResolve();
    });

    await act(() => {
      registeredOninitialized?.();
    });

    await waitFor(() => {
      expect(mockAppBridge.sendToolInput).toHaveBeenCalledWith({
        arguments: toolInput,
      });
    });
  });

  it('should send tool result after initialization', async () => {
    const toolResult = { content: [{ type: 'text' as const, text: 'result' }] };

    render(<AppFrame {...getPropsWithBridge({ toolResult })} />);

    await act(() => {
      onReadyResolve();
    });

    await act(() => {
      registeredOninitialized?.();
    });

    await waitFor(() => {
      expect(mockAppBridge.sendToolResult).toHaveBeenCalledWith(toolResult);
    });
  });

  it('should call onSizeChanged when size changes', async () => {
    const onSizeChanged = vi.fn();

    render(<AppFrame {...getPropsWithBridge({ onSizeChanged })} />);

    await act(() => {
      onReadyResolve();
    });

    await act(() => {
      registeredOnsizechange?.({ width: 800, height: 600 });
    });

    expect(onSizeChanged).toHaveBeenCalledWith({ width: 800, height: 600 });
  });

  it('should forward CSP to sandbox', async () => {
    const csp = {
      connectDomains: ['api.example.com'],
      resourceDomains: ['cdn.example.com'],
    };

    render(<AppFrame {...getPropsWithBridge({ sandbox: { ...defaultProps.sandbox, csp } })} />);

    await act(() => {
      onReadyResolve();
    });

    await act(() => {
      registeredOninitialized?.();
    });

    await waitFor(() => {
      expect(mockAppBridge.sendSandboxResourceReady).toHaveBeenCalledWith({
        html: defaultProps.html,
        csp,
      });
    });
  });

  it('should call onError when setup fails', async () => {
    const onError = vi.fn();
    const error = new Error('Setup failed');

    vi.mocked(appHostUtils.setupSandboxProxyIframe).mockRejectedValue(error);

    render(<AppFrame {...getPropsWithBridge({ onError })} />);

    await waitFor(() => {
      expect(onError).toHaveBeenCalledWith(error);
    });
  });

  it('should display error message when error occurs', async () => {
    const error = new Error('Test error');
    vi.mocked(appHostUtils.setupSandboxProxyIframe).mockRejectedValue(error);

    render(<AppFrame {...getPropsWithBridge()} />);

    await waitFor(() => {
      expect(screen.getByText(/Error: Test error/)).toBeInTheDocument();
    });
  });

  describe('lifecycle', () => {
    it('should preserve iframe across re-renders', async () => {
      const { rerender } = render(<AppFrame {...getPropsWithBridge()} />);

      await act(() => {
        onReadyResolve();
      });

      await act(() => {
        registeredOninitialized?.();
      });

      // setupSandboxProxyIframe should be called once on initial mount
      expect(appHostUtils.setupSandboxProxyIframe).toHaveBeenCalledTimes(1);

      // Re-render with same props (simulating React StrictMode remount or parent re-render)
      rerender(<AppFrame {...getPropsWithBridge()} />);

      // Should NOT call setupSandboxProxyIframe again - iframe is preserved
      expect(appHostUtils.setupSandboxProxyIframe).toHaveBeenCalledTimes(1);
    });

    it('should recreate iframe when sandbox URL changes', async () => {
      const { rerender } = render(<AppFrame {...getPropsWithBridge()} />);

      await act(() => {
        onReadyResolve();
      });

      await act(() => {
        registeredOninitialized?.();
      });

      expect(appHostUtils.setupSandboxProxyIframe).toHaveBeenCalledTimes(1);

      // Create new mock for second iframe
      const secondOnReadyPromise = new Promise<void>((resolve) => {
        onReadyResolve = resolve;
      });
      vi.mocked(appHostUtils.setupSandboxProxyIframe).mockResolvedValue({
        iframe: mockIframe as HTMLIFrameElement,
        onReady: secondOnReadyPromise,
      });

      // Re-render with DIFFERENT sandbox URL
      const newSandboxUrl = new URL('http://localhost:9999/different-sandbox.html');
      rerender(<AppFrame {...getPropsWithBridge({ sandbox: { url: newSandboxUrl } })} />);

      // Should call setupSandboxProxyIframe again with new URL
      await waitFor(() => {
        expect(appHostUtils.setupSandboxProxyIframe).toHaveBeenCalledTimes(2);
        expect(appHostUtils.setupSandboxProxyIframe).toHaveBeenLastCalledWith(newSandboxUrl);
      });
    });

    it('should update HTML content without recreating iframe', async () => {
      const { rerender } = render(<AppFrame {...getPropsWithBridge()} />);

      await act(() => {
        onReadyResolve();
      });

      await act(() => {
        registeredOninitialized?.();
      });

      // Initial HTML sent
      await waitFor(() => {
        expect(mockAppBridge.sendSandboxResourceReady).toHaveBeenCalledTimes(1);
        expect(mockAppBridge.sendSandboxResourceReady).toHaveBeenCalledWith({
          html: defaultProps.html,
          csp: undefined,
        });
      });

      // Re-render with new HTML
      const newHtml = '<html><body>Updated Content</body></html>';
      rerender(<AppFrame {...getPropsWithBridge({ html: newHtml })} />);

      // Should send new HTML without recreating iframe
      await waitFor(() => {
        expect(mockAppBridge.sendSandboxResourceReady).toHaveBeenCalledTimes(2);
        expect(mockAppBridge.sendSandboxResourceReady).toHaveBeenLastCalledWith({
          html: newHtml,
          csp: undefined,
        });
      });

      // Iframe should NOT be recreated
      expect(appHostUtils.setupSandboxProxyIframe).toHaveBeenCalledTimes(1);
    });

    it('should update toolInput without recreating iframe', async () => {
      const { rerender } = render(
        <AppFrame {...getPropsWithBridge({ toolInput: { initial: true } })} />,
      );

      await act(() => {
        onReadyResolve();
      });

      await act(() => {
        registeredOninitialized?.();
      });

      await waitFor(() => {
        expect(mockAppBridge.sendToolInput).toHaveBeenCalledWith({ arguments: { initial: true } });
      });

      // Re-render with new toolInput
      rerender(<AppFrame {...getPropsWithBridge({ toolInput: { updated: true } })} />);

      await waitFor(() => {
        expect(mockAppBridge.sendToolInput).toHaveBeenCalledWith({ arguments: { updated: true } });
      });

      // Iframe should NOT be recreated
      expect(appHostUtils.setupSandboxProxyIframe).toHaveBeenCalledTimes(1);
    });
  });
});


================================================
FILE: sdks/typescript/client/src/components/__tests__/AppRenderer.test.tsx
================================================
import React from 'react';
import { render, screen, waitFor, act } from '@testing-library/react';
import { vi, describe, it, expect, beforeEach, afterEach } from 'vitest';
import '@testing-library/jest-dom';
import type { Client } from '@modelcontextprotocol/sdk/client/index.js';

import { AppRenderer, type AppRendererProps, type AppRendererHandle } from '../AppRenderer';
import type { AppFrameProps } from '../AppFrame';
import type { AppBridge } from '@modelcontextprotocol/ext-apps/app-bridge';
import * as appHostUtils from '../../utils/app-host-utils';

// Mock AppFrame to capture props
const mockAppFrame = vi.fn();
vi.mock('../AppFrame', () => ({
  AppFrame: (props: AppFrameProps) => {
    mockAppFrame(props);
    return (
      <div
        data-testid="app-frame"
        data-html={props.html}
        data-sandbox-url={props.sandbox?.url?.href}
      >
        {props.toolInput && <span data-testid="tool-input">{JSON.stringify(props.toolInput)}</span>}
        {props.toolResult && (
          <span data-testid="tool-result">{JSON.stringify(props.toolResult)}</span>
        )}
      </div>
    );
  },
}));

// Mock app-host-utils
vi.mock('../../utils/app-host-utils', () => ({
  getToolUiResourceUri: vi.fn(),
  readToolUiResourceHtml: vi.fn(),
}));

// Store mock bridge instance for test access
let mockBridgeInstance: Partial<AppBridge> | null = null;

// Mock AppBridge constructor
vi.mock('@modelcontextprotocol/ext-apps/app-bridge', () => {
  return {
    AppBridge: vi.fn().mockImplementation(function () {
      mockBridgeInstance = {
        onmessage: undefined,
        onopenlink: undefined,
        onloggingmessage: undefined,
        oncalltool: undefined,
        onlistresources: undefined,
        onlistresourcetemplates: undefined,
        onreadresource: undefined,
        onlistprompts: undefined,
        fallbackRequestHandler: undefined,
        setHostContext: vi.fn(),
        sendToolInputPartial: vi.fn(),
        sendToolCancelled: vi.fn(),
        sendToolListChanged: vi.fn(),
        sendResourceListChanged: vi.fn(),
        sendPromptListChanged: vi.fn(),
        teardownResource: vi.fn(),
      };
      return mockBridgeInstance;
    }),
    RESOURCE_MIME_TYPE: 'text/html',
  };
});

// Mock MCP Client
const mockClient = {
  getServerCapabilities: vi.fn().mockReturnValue({
    tools: {},
    resources: {},
  }),
};

function createMockExtra() {
  return {
    signal: new AbortController().signal,
    requestId: 1,
    sendNotification: vi.fn(),
    sendRequest: vi.fn(),
  };
}

describe('<AppRenderer />', () => {
  const defaultProps: AppRendererProps = {
    client: mockClient as unknown as Client,
    toolName: 'test-tool',
    sandbox: { url: new URL('http://localhost:8081/sandbox.html') },
  };

  beforeEach(() => {
    vi.clearAllMocks();
    mockBridgeInstance = null;
    mockAppFrame.mockClear();

    // Default mock implementations
    vi.mocked(appHostUtils.getToolUiResourceUri).mockResolvedValue({
      uri: 'ui://test-tool',
    });
    vi.mocked(appHostUtils.readToolUiResourceHtml).mockResolvedValue(
      '<html><body>Test Tool UI</body></html>',
    );
  });

  afterEach(() => {
    vi.clearAllMocks();
  });

  describe('basic rendering', () => {
    it('should render AppFrame after fetching HTML', async () => {
      render(<AppRenderer {...defaultProps} />);

      await waitFor(() => {
        expect(screen.getByTestId('app-frame')).toBeInTheDocument();
      });
    });

    it('should fetch resource URI for the tool', async () => {
      render(<AppRenderer {...defaultProps} />);

      await waitFor(() => {
        expect(appHostUtils.getToolUiResourceUri).toHaveBeenCalledWith(mockClient, 'test-tool');
      });
    });

    it('should read HTML from resource URI', async () => {
      render(<AppRenderer {...defaultProps} />);

      await waitFor(() => {
        expect(appHostUtils.readToolUiResourceHtml).toHaveBeenCalledWith(mockClient, {
          uri: 'ui://test-tool',
        });
      });
    });

    it('should pass fetched HTML to AppFrame', async () => {
      render(<AppRenderer {...defaultProps} />);

      await waitFor(() => {
        const appFrame = screen.getByTestId('app-frame');
        expect(appFrame).toHaveAttribute('data-html', '<html><body>Test Tool UI</body></html>');
      });
    });

    it('should use provided toolResourceUri instead of fetching', async () => {
      const props: AppRendererProps = {
        ...defaultProps,
        toolResourceUri: 'ui://custom-uri',
      };

      render(<AppRenderer {...props} />);

      await waitFor(() => {
        expect(appHostUtils.getToolUiResourceUri).not.toHaveBeenCalled();
        expect(appHostUtils.readToolUiResourceHtml).toHaveBeenCalledWith(mockClient, {
          uri: 'ui://custom-uri',
        });
      });
    });

    it('should use provided HTML directly without fetching', async () => {
      const props: AppRendererProps = {
        ...defaultProps,
        html: '<html><body>Pre-fetched HTML</body></html>',
      };

      render(<AppRenderer {...props} />);

      await waitFor(() => {
        expect(appHostUtils.getToolUiResourceUri).not.toHaveBeenCalled();
        expect(appHostUtils.readToolUiResourceHtml).not.toHaveBeenCalled();
        expect(screen.getByTestId('app-frame')).toHaveAttribute(
          'data-html',
          '<html><body>Pre-fetched HTML</body></html>',
        );
      });
    });

    it('should pass sandbox config to AppFrame', async () => {
      render(<AppRenderer {...defaultProps} />);

      await waitFor(() => {
        const appFrame = screen.getByTestId('app-frame');
        expect(appFrame).toHaveAttribute('data-sandbox-url', 'http://localhost:8081/sandbox.html');
      });
    });

    it('should pass toolInput to AppFrame', async () => {
      const toolInput = { query: 'test query' };
      const props: AppRendererProps = {
        ...defaultProps,
        toolInput,
      };

      render(<AppRenderer {...props} />);

      await waitFor(() => {
        const toolInputEl = screen.getByTestId('tool-input');
        expect(toolInputEl).toHaveTextContent(JSON.stringify(toolInput));
      });
    });

    it('should pass toolResult to AppFrame', async () => {
      const toolResult = { content: [{ type: 'text' as const, text: 'result' }] };
      const props: AppRendererProps = {
        ...defaultProps,
        toolResult,
      };

      render(<AppRenderer {...props} />);

      await waitFor(() => {
        const toolResultEl = screen.getByTestId('tool-result');
        expect(toolResultEl).toHaveTextContent(JSON.stringify(toolResult));
      });
    });

    it('should display error when tool has no UI resource', async () => {
      vi.mocked(appHostUtils.getToolUiResourceUri).mockResolvedValue(null);

      render(<AppRenderer {...defaultProps} />);

      await waitFor(() => {
        expect(screen.getByText(/Error:/)).toBeInTheDocument();
        expect(screen.getByText(/has no UI resource/)).toBeInTheDocument();
      });
    });

    it('should call onError when resource fetch fails', async () => {
      const onError = vi.fn();
      const error = new Error('Fetch failed');
      vi.mocked(appHostUtils.readToolUiResourceHtml).mockRejectedValue(error);

      render(<AppRenderer {...defaultProps} onError={onError} />);

      await waitFor(() => {
        expect(onError).toHaveBeenCalledWith(error);
      });
    });

    it('should return null while loading', () => {
      // Make the promise never resolve
      vi.mocked(appHostUtils.getToolUiResourceUri).mockReturnValue(new Promise(() => {}));

      const { container } = render(<AppRenderer {...defaultProps} />);

      // Should render nothing while loading
      expect(container.firstChild).toBeNull();
    });
  });

  describe('hostContext prop', () => {
    it('should call setHostContext when hostContext is provided', async () => {
      const hostContext = { theme: 'dark' as const };

      render(<AppRenderer {...defaultProps} hostContext={hostContext} />);

      await waitFor(() => {
        expect(mockBridgeInstance?.setHostContext).toHaveBeenCalledWith(hostContext);
      });
    });

    it('should update hostContext when prop changes', async () => {
      const { rerender } = render(
        <AppRenderer {...defaultProps} hostContext={{ theme: 'light' as const }} />,
      );

      await waitFor(() => {
        expect(mockBridgeInstance?.setHostContext).toHaveBeenCalledWith({ theme: 'light' });
      });

      rerender(<AppRenderer {...defaultProps} hostContext={{ theme: 'dark' as const }} />);

      await waitFor(() => {
        expect(mockBridgeInstance?.setHostContext).toHaveBeenCalledWith({ theme: 'dark' });
      });
    });
  });

  describe('toolInputPartial prop', () => {
    it('should call sendToolInputPartial when toolInputPartial is provided', async () => {
      const toolInputPartial = { arguments: { delta: 'partial data' } };

      render(<AppRenderer {...defaultProps} toolInputPartial={toolInputPartial} />);

      await waitFor(() => {
        expect(mockBridgeInstance?.sendToolInputPartial).toHaveBeenCalledWith(toolInputPartial);
      });
    });
  });

  describe('toolCancelled prop', () => {
    it('should call sendToolCancelled when toolCancelled is true', async () => {
      render(<AppRenderer {...defaultProps} toolCancelled={true} />);

      await waitFor(() => {
        expect(mockBridgeInstance?.sendToolCancelled).toHaveBeenCalledWith({});
      });
    });

    it('should not call sendToolCancelled when toolCancelled is false', async () => {
      render(<AppRenderer {...defaultProps} toolCancelled={false} />);

      await waitFor(() => {
        expect(screen.getByTestId('app-frame')).toBeInTheDocument();
      });

      expect(mockBridgeInstance?.sendToolCancelled).not.toHaveBeenCalled();
    });
  });

  describe('ref methods', () => {
    it('should expose sendToolListChanged via ref', async () => {
      const ref = React.createRef<AppRendererHandle>();

      render(<AppRenderer ref={ref} {...defaultProps} />);

      await waitFor(() => {
        expect(screen.getByTestId('app-frame')).toBeInTheDocument();
      });

      await waitFor(() => {
        expect(ref.current).not.toBeNull();
      });

      act(() => {
        ref.current?.sendToolListChanged();
      });

      expect(mockBridgeInstance?.sendToolListChanged).toHaveBeenCalled();
    });

    it('should expose sendResourceListChanged via ref', async () => {
      const ref = React.createRef<AppRendererHandle>();

      render(<AppRenderer ref={ref} {...defaultProps} />);

      await waitFor(() => {
        expect(screen.getByTestId('app-frame')).toBeInTheDocument();
      });

      await waitFor(() => {
        expect(ref.current).not.toBeNull();
      });

      act(() => {
        ref.current?.sendResourceListChanged();
      });

      expect(mockBridgeInstance?.sendResourceListChanged).toHaveBeenCalled();
    });

    it('should expose sendPromptListChanged via ref', async () => {
      const ref = React.createRef<AppRendererHandle>();

      render(<AppRenderer ref={ref} {...defaultProps} />);

      await waitFor(() => {
        expect(screen.getByTestId('app-frame')).toBeInTheDocument();
      });

      await waitFor(() => {
        expect(ref.current).not.toBeNull();
      });

      act(() => {
        ref.current?.sendPromptListChanged();
      });

      expect(mockBridgeInstance?.sendPromptListChanged).toHaveBeenCalled();
    });

    it('should expose teardownResource via ref', async () => {
      const ref = React.createRef<AppRendererHandle>();

      render(<AppRenderer ref={ref} {...defaultProps} />);

      await waitFor(() => {
        expect(screen.getByTestId('app-frame')).toBeInTheDocument();
      });

      await waitFor(() => {
        expect(ref.current).not.toBeNull();
      });

      act(() => {
        ref.current?.teardownResource();
      });

      expect(mockBridgeInstance?.teardownResource).toHaveBeenCalledWith({});
    });
  });

  describe('MCP request handler props', () => {
    it('should register onCallTool handler on AppBridge', async () => {
      const onCallTool = vi.fn().mockResolvedValue({ content: [] });

      render(<AppRenderer {...defaultProps} onCallTool={onCallTool} />);

      await waitFor(() => {
        expect(screen.getByTestId('app-frame')).toBeInTheDocument();
      });

      // The handler should be registered
      expect(mockBridgeInstance?.oncalltool).toBeDefined();
    });

    it('should register onListResources handler on AppBridge', async () => {
      const onListResources = vi.fn().mockResolvedValue({ resources: [] });

      render(<AppRenderer {...defaultProps} onListResources={onListResources} />);

      await waitFor(() => {
        expect(screen.getByTestId('app-frame')).toBeInTheDocument();
      });

      expect(mockBridgeInstance?.onlistresources).toBeDefined();
    });

    it('should register onListResourceTemplates handler on AppBridge', async () => {
      const onListResourceTemplates = vi.fn().mockResolvedValue({ resourceTemplates: [] });

      render(<AppRenderer {...defaultProps} onListResourceTemplates={onListResourceTemplates} />);

      await waitFor(() => {
        expect(screen.getByTestId('app-frame')).toBeInTheDocument();
      });

      expect(mockBridgeInstance?.onlistresourcetemplates).toBeDefined();
    });

    it('should register onReadResource handler on AppBridge', async () => {
      const onReadResource = vi.fn().mockResolvedValue({ contents: [] });

      render(<AppRenderer {...defaultProps} onReadResource={onReadResource} />);

      await waitFor(() => {
        expect(screen.getByTestId('app-frame')).toBeInTheDocument();
      });

      expect(mockBridgeInstance?.onreadresource).toBeDefined();
    });

    it('should register onListPrompts handler on AppBridge', async () => {
      const onListPrompts = vi.fn().mockResolvedValue({ prompts: [] });

      render(<AppRenderer {...defaultProps} onListPrompts={onListPrompts} />);

      await waitFor(() => {
        expect(screen.getByTestId('app-frame')).toBeInTheDocument();
      });

      expect(mockBridgeInstance?.onlistprompts).toBeDefined();
    });
  });

  describe('callback props', () => {
    it('should pass onSizeChanged to AppFrame', async () => {
      const onSizeChanged = vi.fn();

      render(<AppRenderer {...defaultProps} onSizeChanged={onSizeChanged} />);

      await waitFor(() => {
        expect(screen.getByTestId('app-frame')).toBeInTheDocument();
      });

      expect(mockAppFrame).toHaveBeenCalledWith(
        expect.objectContaining({
          onSizeChanged: expect.any(Function),
        }),
      );
    });

    it('should pass onError to AppFrame', async () => {
      const onError = vi.fn();

      render(<AppRenderer {...defaultProps} onError={onError} />);

      await waitFor(() => {
        expect(screen.getByTestId('app-frame')).toBeInTheDocument();
      });

      expect(mockAppFrame).toHaveBeenCalledWith(
        expect.objectContaining({
          onError,
        }),
      );
    });
  });

  describe('onFallbackRequest prop', () => {
    it('should register fallbackRequestHandler on AppBridge', async () => {
      const onFallbackRequest = vi.fn().mockResolvedValue({ success: true });

      render(<AppRenderer {...defaultProps} onFallbackRequest={onFallbackRequest} />);

      await waitFor(() => {
        expect(screen.getByTestId('app-frame')).toBeInTheDocument();
      });

      // fallbackRequestHandler should always be set (even without the prop, it throws MethodNotFound)
      expect(mockBridgeInstance?.fallbackRequestHandler).toBeDefined();
    });

    it('should invoke onFallbackRequest when fallbackRequestHandler is called', async () => {
      const onFallbackRequest = vi.fn().mockResolvedValue({ clipboard: 'written' });

      render(<AppRenderer {...defaultProps} onFallbackRequest={onFallbackRequest} />);

      await waitFor(() => {
        expect(screen.getByTestId('app-frame')).toBeInTheDocument();
      });

      // Simulate AppBridge calling the fallback handler with a custom method
      const mockRequest = {
        jsonrpc: '2.0' as const,
        id: 1,
        method: 'x/clipboard/write',
        params: { text: 'hello' },
      };
      const mockExtra = createMockExtra();

      const result = await mockBridgeInstance?.fallbackRequestHandler?.(mockRequest, mockExtra as never);

      expect(onFallbackRequest).toHaveBeenCalledWith(mockRequest, mockExtra);
      expect(result).toEqual({ clipboard: 'written' });
    });

    it('should throw MethodNotFound when onFallbackRequest is not provided', async () => {
      render(<AppRenderer {...defaultProps} />);

      await waitFor(() => {
        expect(screen.getByTestId('app-frame')).toBeInTheDocument();
      });

      const mockRequest = {
        jsonrpc: '2.0' as const,
        id: 1,
        method: 'x/unknown/method',
        params: {},
      };
      const mockExtra = createMockExtra();

      await expect(
        mockBridgeInstance?.fallbackRequestHandler?.(mockRequest, mockExtra as never),
      ).rejects.toThrow('No handler for method: x/unknown/method');
    });

    it('should use the latest onFallbackRequest callback (ref stability)', async () => {
      const firstHandler = vi.fn().mockResolvedValue({ version: 1 });
      const secondHandler = vi.fn().mockResolvedValue({ version: 2 });

      const { rerender } = render(
        <AppRenderer {...defaultProps} onFallbackRequest={firstHandler} />,
      );

      await waitFor(() => {
        expect(screen.getByTestId('app-frame')).toBeInTheDocument();
      });

      // Update the handler
      rerender(<AppRenderer {...defaultProps} onFallbackRequest={secondHandler} />);

      const mockRequest = {
        jsonrpc: '2.0' as const,
        id: 1,
        method: 'x/test/method',
        params: {},
      };
      const mockExtra = createMockExtra();

      const result = await mockBridgeInstance?.fallbackRequestHandler?.(mockRequest, mockExtra as never);

      // Should use the second (latest) handler
      expect(firstHandler).not.toHaveBeenCalled();
      expect(secondHandler).toHaveBeenCalledWith(mockRequest, mockExtra);
      expect(result).toEqual({ version: 2 });
    });

    it('should propagate errors from onFallbackRequest', async () => {
      const onFallbackRequest = vi.fn().mockRejectedValue(new Error('Permission denied'));

      render(<AppRenderer {...defaultProps} onFallbackRequest={onFallbackRequest} />);

      await waitFor(() => {
        expect(screen.getByTestId('app-frame')).toBeInTheDocument();
      });

      const mockRequest = {
        jsonrpc: '2.0' as const,
        id: 1,
        method: 'x/restricted/action',
        params: {},
      };
      const mockExtra = createMockExtra();

      await expect(
        mockBridgeInstance?.fallbackRequestHandler?.(mockRequest, mockExtra as never),
      ).rejects.toThrow('Permission denied');
    });
  });

  describe('no client', () => {
    it('should work without client when html is provided', async () => {
      const props: AppRendererProps = {
        // client omitted - using html prop instead
        toolName: 'test-tool',
        sandbox: { url: new URL('http://localhost:8081/sandbox.html') },
        html: '<html><body>Static HTML</body></html>',
      };

      render(<AppRenderer {...props} />);

      await waitFor(() => {
        expect(screen.getByTestId('app-frame')).toBeInTheDocument();
        expect(screen.getByTestId('app-frame')).toHaveAttribute(
          'data-html',
          '<html><body>Static HTML</body></html>',
        );
      });
    });

    it('should show error without client and no html', async () => {
      const props: AppRendererProps = {
        // client omitted, no html provided
        toolName: 'test-tool',
        sandbox: { url: new URL('http://localhost:8081/sandbox.html') },
      };

      render(<AppRenderer {...props} />);

      await waitFor(() => {
        expect(screen.getByText(/Error:/)).toBeInTheDocument();
      });
    });

    it('should work with onReadResource and toolResourceUri instead of client', async () => {
      const mockReadResource = vi.fn().mockResolvedValue({
        contents: [
          {
            uri: 'ui://test/tool',
            mimeType: 'text/html',
            text: '<html><body>Custom fetched HTML</body></html>',
          },
        ],
      });

      const props: AppRendererProps = {
        // client omitted - using onReadResource + toolResourceUri instead
        toolName: 'test-tool',
        sandbox: { url: new URL('http://localhost:8081/sandbox.html') },
        toolResourceUri: 'ui://test/tool',
        onReadResource: mockReadResource,
      };

      render(<AppRenderer {...props} />);

      await waitFor(() => {
        expect(mockReadResource).toHaveBeenCalledWith({ uri: 'ui://test/tool' }, expect.anything());
        expect(screen.getByTestId('app-frame')).toBeInTheDocument();
        expect(screen.getByTestId('app-frame')).toHaveAttribute(
          'data-html',
          '<html><body>Custom fetched HTML</body></html>',
        );
      });
    });
  });
});


================================================
FILE: sdks/typescript/client/src/components/__tests__/ProxyScript.test.ts
================================================
import { describe, it, expect } from 'vitest';
import { readFileSync } from 'node:fs';
import path from 'node:path';
import { JSDOM } from 'jsdom';
import '@testing-library/jest-dom';

function nextTick(): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, 0));
}

describe('Proxy script', () => {
  it('should use document.write to inject HTML via postMessage', async () => {
    const proxyPath = path.resolve(__dirname, '../../../scripts/proxy/index.html');
    const proxyHtml = readFileSync(proxyPath, 'utf8');

    // Create jsdom with proxy URL using contentType=rawhtml
    const dom = new JSDOM(proxyHtml, {
      url: 'http://proxy.local/?contentType=rawhtml',
      runScripts: 'dangerously',
      resources: 'usable',
      pretendToBeVisual: true,
    });

    const { window } = dom;

    // Capture the ready signal emitted by the proxy
    let proxyReady = false;
    window.addEventListener('message', (event: MessageEvent) => {
      const data = event.data as { type?: string };
      if (data?.type === 'ui-proxy-iframe-ready') {
        proxyReady = true;
      }
    });

    // Allow the inline script to run and emit readiness
    await nextTick();
    expect(proxyReady).toBe(true);

    // Find the iframe created by the script
    const outerDoc = window.document;
    const innerIframe = outerDoc.querySelector('iframe');
    expect(innerIframe).toBeTruthy();

    // Verify the iframe has id="root" and src="about:blank" as per the new implementation
    expect(innerIframe?.getAttribute('id')).toBe('root');
    expect(innerIframe?.getAttribute('src')).toBe('about:blank');

    // Send the html payload
    const html = '<!doctype html><html><body><form><input></form></body></html>';
    // Simulate parent -> proxy message ensuring source === window.parent
    const MsgEvent: typeof MessageEvent = window.MessageEvent;
    window.dispatchEvent(
      new MsgEvent('message', {
        data: { type: 'ui-html-content', payload: { html } },
        source: window.parent,
      }),
    );

    // Let the proxy handle the message
    await nextTick();
    await nextTick();

    // Note: JSDOM has limitations with document.write on dynamically created iframes
    // The new implementation uses document.write() instead of srcdoc, which avoids
    // CSP base-uri issues. In a real browser, the contentDocument would contain the HTML.
    // Here we just verify the iframe structure is correct.
    expect(innerIframe).toBeTruthy();

    // The new implementation doesn't use sandbox attributes from payload since
    // allow-same-origin is required for document.write to work. The sandbox
    // attribute is not set on the inner iframe anymore.
    expect(innerIframe?.hasAttribute('srcdoc')).toBe(false);
  });
});


================================================
FILE: sdks/typescript/client/src/index.ts
================================================
export { getUIResourceMetadata, getResourceMetadata } from './utils/metadataUtils';
export { isUIResource } from './utils/isUIResource';

// Client capabilities for UI extension support
export {
  type ClientCapabilitiesWithExtensions,
  UI_EXTENSION_NAME,
  UI_EXTENSION_CONFIG,
  UI_EXTENSION_CAPABILITIES,
} from './capabilities';

// MCP Apps renderers
export {
  AppRenderer,
  type AppRendererProps,
  type AppRendererHandle,
  type RequestHandlerExtra,
} from './components/AppRenderer';
export {
  AppFrame,
  type AppFrameProps,
  type SandboxConfig,
  type AppInfo,
} from './components/AppFrame';

// Re-export AppBridge, transport, and common types for advanced use cases
export {
  AppBridge,
  PostMessageTransport,
  type McpUiHostContext,
} from '@modelcontextprotocol/ext-apps/app-bridge';

// Re-export JSONRPCRequest for typing onFallbackRequest handlers
export type { JSONRPCRequest } from '@modelcontextprotocol/sdk/types.js';

export type { UIResourceMetadata } from './types';


================================================
FILE: sdks/typescript/client/src/test-setup.ts
================================================
import '@testing-library/jest-dom';

// Polyfill for requestAnimationFrame
if (typeof window !== 'undefined' && typeof window.requestAnimationFrame === 'undefined') {
  window.requestAnimationFrame = (callback) => {
    return setTimeout(callback, 0);
  };
}

if (typeof window !== 'undefined' && typeof window.cancelAnimationFrame === 'undefined') {
  window.cancelAnimationFrame = (id) => {
    clearTimeout(id);
  };
}


================================================
FILE: sdks/typescript/client/src/types.ts
================================================
export const UIMetadataKey = {
  PREFERRED_FRAME_SIZE: 'preferred-frame-size',
  INITIAL_RENDER_DATA: 'initial-render-data',
} as const;

export const UI_METADATA_PREFIX = 'mcpui.dev/ui-';

export type UIResourceMetadata = {
  [UIMetadataKey.PREFERRED_FRAME_SIZE]?: [string, string];
  [UIMetadataKey.INITIAL_RENDER_DATA]?: Record<string, unknown>;
};


================================================
FILE: sdks/typescript/client/src/utils/__tests__/isUIResource.test.ts
================================================
import { describe, it, expect } from 'vitest';
import { isUIResource } from '../isUIResource';

describe('isUIResource', () => {
  const uiResources = [
    { type: 'resource', resource: { uri: 'ui://test' } },
    {
      type: 'resource',
      resource: { uri: 'ui://test', mimeType: 'text/html', text: 'Hello, world!' },
      arbitraryProp: 'arbitrary',
    },
    {
      type: 'resource',
      resource: {
        uri: 'ui://test',
        mimeType: 'text/html;profile=mcp-app',
        text: 'https://example.com',
      },
    },
    {
      type: 'resource',
      resource: {
        uri: 'ui://test',
        mimeType: 'text/html;profile=mcp-app',
        text: 'Hello, world!',
      },
    },
  ];

  const nonUiResources = [
    { type: 'resource', resource: { uri: 'https://example.com' } },
    { type: 'text', text: 'Hello, world!' },
    { type: 'text', resource: { uri: 'ui://test' } },
  ];

  it(`should return true if the content is a UI resource: ${JSON.stringify(uiResources)}`, () => {
    uiResources.forEach((content) => {
      expect(isUIResource(content)).toBe(true);
    });
  });

  nonUiResources.forEach((content) => {
    it(`should return false if the content is not a UI resource: ${JSON.stringify(content)}`, () => {
      expect(isUIResource(content)).toBe(false);
    });
  });

  it('should return false if the content is not a UI resource', () => {
    const content = { type: 'resource', resource: { uri: 'https://example.com' } };
    expect(isUIResource(content)).toBe(false);
  });
});


================================================
FILE: sdks/typescript/client/src/utils/__tests__/metadataUtils.test.ts
================================================
import { describe, it, expect } from 'vitest';
import { getResourceMetadata, getUIResourceMetadata } from '../metadataUtils';
import { UI_METADATA_PREFIX } from '../../types';

describe('metadataUtils', () => {
  it('should get resource metadata', () => {
    const resource = { _meta: { foo: 'bar' } };
    expect(getResourceMetadata(resource)).toEqual({ foo: 'bar' });
  });

  it('should get ui resource metadata', () => {
    const resource = { _meta: { [`${UI_METADATA_PREFIX}foo`]: 'bar' } };
    expect(getUIResourceMetadata(resource)).toEqual({ foo: 'bar' });
  });

  it('should get ui resource metadata with prefix and user defined metadata', () => {
    const resource = { _meta: { [`${UI_METADATA_PREFIX}foo`]: 'bar', foo: 'baz' } };
    expect(getUIResourceMetadata(resource)).toEqual({ foo: 'bar' });
  });
});


================================================
FILE: sdks/typescript/client/src/utils/app-host-utils.ts
================================================
import {
  SANDBOX_PROXY_READY_METHOD,
  getToolUiResourceUri as _getToolUiResourceUri,
  RESOURCE_MIME_TYPE,
} from '@modelcontextprotocol/ext-apps/app-bridge';
import { type Client } from '@modelcontextprotocol/sdk/client/index.js';
import { type Tool } from '@modelcontextprotocol/sdk/types.js';
const DEFAULT_SANDBOX_TIMEOUT_MS = 10000;

export async function setupSandboxProxyIframe(sandboxProxyUrl: URL): Promise<{
  iframe: HTMLIFrameElement;
  onReady: Promise<void>;
}> {
  const iframe = document.createElement('iframe');
  iframe.style.width = '100%';
  iframe.style.height = '600px';
  iframe.style.border = 'none';
  iframe.style.backgroundColor = 'transparent';
  iframe.setAttribute('sandbox', 'allow-scripts allow-same-origin allow-forms');

  const onReady = new Promise<void>((resolve, reject) => {
    let settled = false;

    const cleanup = () => {
      window.removeEventListener('message', messageListener);
      iframe.removeEventListener('error', errorListener);
    };

    const timeoutId = setTimeout(() => {
      if (!settled) {
        settled = true;
        cleanup();
        reject(new Error('Timed out waiting for sandbox proxy iframe to be ready'));
      }
    }, DEFAULT_SANDBOX_TIMEOUT_MS);

    const messageListener = (event: MessageEvent) => {
      if (event.source === iframe.contentWindow) {
        if (event.data && event.data.method === SANDBOX_PROXY_READY_METHOD) {
          if (!settled) {
            settled = true;
            clearTimeout(timeoutId);
            cleanup();
            resolve();
          }
        }
      }
    };

    const errorListener = () => {
      if (!settled) {
        settled = true;
        clearTimeout(timeoutId);
        cleanup();
        reject(new Error('Failed to load sandbox proxy iframe'));
      }
    };

    window.addEventListener('message', messageListener);
    iframe.addEventListener('error', errorListener);
  });

  iframe.src = sandboxProxyUrl.href;

  return { iframe, onReady };
}

export type ToolUiResourceInfo = {
  uri: string;
};

export async function getToolUiResourceUri(
  client: Client,
  toolName: string,
): Promise<ToolUiResourceInfo | null> {
  let tool: Tool | undefined;
  let cursor: string | undefined = undefined;
  do {
    const toolsResult = await client.listTools({ cursor });
    tool = toolsResult.tools.find((t) => t.name === toolName);
    cursor = toolsResult.nextCursor;
  } while (!tool && cursor);
  if (!tool) {
    throw new Error(`tool ${toolName} not found`);
  }
  if (!tool._meta) {
    return null;
  }

  const uri = _getToolUiResourceUri(tool);
  if (!uri) {
    return null;
  }
  if (!uri.startsWith('ui://')) {
    throw new Error(`tool ${toolName} has unsupported output template URI: ${uri}`);
  }
  return { uri };
}

export async function readToolUiResourceHtml(
  client: Client,
  opts: {
    uri: string;
  },
): Promise<string> {
  const resource = await client.readResource({ uri: opts.uri });

  if (!resource) {
    throw new Error('UI resource not found: ' + opts.uri);
  }
  if (resource.contents.length !== 1) {
    throw new Error('Unsupported UI resource content length: ' + resource.contents.length);
  }
  const content = resource.contents[0];
  let html: string;
  const isHtml = (t?: string) => t === RESOURCE_MIME_TYPE;

  if ('text' in content && typeof content.text === 'string' && isHtml(content.mimeType)) {
    html = content.text;
  } else if ('blob' in content && typeof content.blob === 'string' && isHtml(content.mimeType)) {
    html = atob(content.blob);
  } else {
    throw new Error('Unsupported UI resource content format: ' + JSON.stringify(content));
  }

  return html;
}


================================================
FILE: sdks/typescript/client/src/utils/isUIResource.ts
================================================
import type { EmbeddedResource } from '@modelcontextprotocol/sdk/types.js';

export function isUIResource<
  T extends { type: string; resource?: Partial<EmbeddedResource['resource']> },
>(
  content: T,
): content is T & { type: 'resource'; resource: Partial<EmbeddedResource['resource']> } {
  return (content.type === 'resource' && content.resource?.uri?.startsWith('ui://')) ?? false;
}


================================================
FILE: sdks/typescript/client/src/utils/metadataUtils.ts
================================================
import type { Resource } from '@modelcontextprotocol/sdk/types.js';
import { UI_METADATA_PREFIX, type UIResourceMetadata } from '../types';

export function getResourceMetadata(resource: Partial<Resource>): Record<string, unknown> {
  return resource._meta ?? {};
}

export function getUIResourceMetadata(
  resource: Partial<Resource>,
): UIResourceMetadata & Record<string, unknown> {
  const metadata = getResourceMetadata(resource);
  const uiMetadata: UIResourceMetadata & Record<string, unknown> = {};
  Object.entries(metadata).forEach(([key, value]) => {
    if (key.startsWith(UI_METADATA_PREFIX)) {
      uiMetadata[key.slice(UI_METADATA_PREFIX.length)] = value;
    }
  });
  return uiMetadata;
}


================================================
FILE: sdks/typescript/client/tsconfig.json
================================================
{
  "extends": "../../../tsconfig.base.json",
  "compilerOptions": {
    "jsx": "react-jsx",
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist", "src/__tests__"]
}


================================================
FILE: sdks/typescript/client/tsconfig.test.json
================================================
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "composite": true,
    "jsx": "react-jsx"
  },
  "include": ["src/**/*.ts", "src/**/*.tsx"]
}


================================================
FILE: sdks/typescript/client/vite.config.ts
================================================
import { defineConfig } from 'vite';
import dts from 'vite-plugin-dts';
import path from 'path';
import react from '@vitejs/plugin-react-swc';

export default defineConfig({
  plugins: [
    react(),
    dts({
      insertTypesEntry: false,
      exclude: ['**/__tests__/**', '**/*.test.ts', '**/*.spec.ts'],
      // eslint-disable-next-line @typescript-eslint/no-explicit-any
    }) as any,
  ],
  build: {
    emptyOutDir: false,
    lib: {
      entry: path.resolve(__dirname, 'src/index.ts'),
      name: 'McpUiClient',
      formats: ['es', 'umd'],
      fileName: (format) =>
        `index.${format === 'es' ? 'mjs' : format === 'umd' ? 'js' : format + '.js'}`,
    },
    rollupOptions: {
      external: [
        'react',
        'react/jsx-runtime',
        '@mcp-ui/shared',
        /@modelcontextprotocol\/sdk(\/.*)?/,
      ],
      output: {
        globals: {
          react: 'React',
          'react/jsx-runtime': 'jsxRuntime',
          '@mcp-ui/shared': 'McpUiShared',
          '@modelcontextprotocol/sdk': 'ModelContextProtocolSDK',
        },
      },
    },
    sourcemap: false,
  },
  // Vitest specific config can go here if not using a separate vitest.config.ts for the package
  // test: { ... }
});


================================================
FILE: sdks/typescript/client/vitest.config.ts
================================================
import { defineConfig } from 'vitest/config';
import react from '@vitejs/plugin-react-swc';
import tsconfigPaths from 'vite-tsconfig-paths';

export default defineConfig({
  plugins: [react(), tsconfigPaths({ projects: ['./tsconfig.test.json'] })],
  test: {
    globals: true,
    environment: 'jsdom',
    setupFiles: ['./src/test-setup.ts'],
  },
});


================================================
FILE: sdks/typescript/server/CHANGELOG.md
================================================
# [6.1.0](https://github.com/MCP-UI-Org/mcp-ui/compare/server/v6.0.1...server/v6.1.0) (2026-02-13)


### Features

* support experimental messages ([#176](https://github.com/MCP-UI-Org/mcp-ui/issues/176)) ([327e4d9](https://github.com/MCP-UI-Org/mcp-ui/commit/327e4d9e6771eceb42f8823ae864e6758f371970))

## [6.0.1](https://github.com/MCP-UI-Org/mcp-ui/compare/server/v6.0.0...server/v6.0.1) (2026-02-06)


### Bug Fixes

* trigger MCP Apps client release ([#173](https://github.com/MCP-UI-Org/mcp-ui/issues/173)) ([b0c0659](https://github.com/MCP-UI-Org/mcp-ui/commit/b0c0659700b493a0083d0de12958f276e4c37715))

# [6.0.0](https://github.com/MCP-UI-Org/mcp-ui/compare/server/v5.17.0...server/v6.0.0) (2026-01-26)


### Features

* mcp-ui -> mcp apps! ([#172](https://github.com/MCP-UI-Org/mcp-ui/issues/172)) ([93a6e22](https://github.com/MCP-UI-Org/mcp-ui/commit/93a6e225808894cac3206504cf15c481f88ed540))


### BREAKING CHANGES

* removed discarded content types, changed mimetype, updated docs, etc.

# [5.17.0](https://github.com/MCP-UI-Org/mcp-ui/compare/server/v5.16.3...server/v5.17.0) (2026-01-25)


### Bug Fixes

* add connectedMoveCallback to the WC implementation ([#170](https://github.com/MCP-UI-Org/mcp-ui/issues/170)) ([5ac4734](https://github.com/MCP-UI-Org/mcp-ui/commit/5ac4734078ff56e213e7a57029fd612638abb0b4))


### Features

* React renderer for MCP Apps ([#147](https://github.com/MCP-UI-Org/mcp-ui/issues/147)) ([fbc918d](https://github.com/MCP-UI-Org/mcp-ui/commit/fbc918d713861396703ede124c5676cf3d1164dd))

## [5.16.3](https://github.com/MCP-UI-Org/mcp-ui/compare/server/v5.16.2...server/v5.16.3) (2025-12-18)


### Bug Fixes

* **client:** use type-only imports for @modelcontextprotocol/sdk types ([#157](https://github.com/MCP-UI-Org/mcp-ui/issues/157)) ([d84cb3e](https://github.com/MCP-UI-Org/mcp-ui/commit/d84cb3e217dfa90f038a8fbe64b4ffd0e0a1bc3f))
* trigger TS release ([e28d1f6](https://github.com/MCP-UI-Org/mcp-ui/commit/e28d1f65cd5f26e46801480995e178ee50c31e51))
* update adapter to latest MCP Apps spec ([#163](https://github.com/MCP-UI-Org/mcp-ui/issues/163)) ([e342034](https://github.com/MCP-UI-Org/mcp-ui/commit/e3420348098fe716f45b2182bc8c8d3358714035))
* update MCP Apps adapter mimetype ([#162](https://github.com/MCP-UI-Org/mcp-ui/issues/162)) ([c91e533](https://github.com/MCP-UI-Org/mcp-ui/commit/c91e5331b68c65de2347b16766a5711e05985e68))
* update ui/message to pass an array ([#167](https://github.com/MCP-UI-Org/mcp-ui/issues/167)) ([80cf222](https://github.com/MCP-UI-Org/mcp-ui/commit/80cf22290ff5e2f981be839f74705454483c21b5))

## [5.16.2](https://github.com/MCP-UI-Org/mcp-ui/compare/server/v5.16.1...server/v5.16.2) (2025-12-08)


### Bug Fixes

* revert externalUrl adapter for compatibility ([#159](https://github.com/MCP-UI-Org/mcp-ui/issues/159)) ([3c5289a](https://github.com/MCP-UI-Org/mcp-ui/commit/3c5289a5e59812f556bc2bb9e67c3ce2e3ce764e))

## [5.16.1](https://github.com/MCP-UI-Org/mcp-ui/compare/server/v5.16.0...server/v5.16.1) (2025-12-01)


### Bug Fixes

* use document.write in proxy sandbox ([#156](https://github.com/MCP-UI-Org/mcp-ui/issues/156)) ([447f582](https://github.com/MCP-UI-Org/mcp-ui/commit/447f582105a0889ee47d912925d7f02034fc39a9))

# [5.16.0](https://github.com/MCP-UI-Org/mcp-ui/compare/server/v5.15.0...server/v5.16.0) (2025-11-30)


### Features

* externalUrl adapter ([5a1e4de](https://github.com/MCP-UI-Org/mcp-ui/commit/5a1e4deeeda9ae0120d17b5abdf9096edf52054f))

# [5.15.0](https://github.com/MCP-UI-Org/mcp-ui/compare/server/v5.14.0...server/v5.15.0) (2025-11-29)


### Features

* add MCP Apps adapter ([#154](https://github.com/MCP-UI-Org/mcp-ui/issues/154)) ([986fd63](https://github.com/MCP-UI-Org/mcp-ui/commit/986fd634448637aa6488a18ad80ee9cd6b8de318))

# [5.14.0](https://github.com/MCP-UI-Org/mcp-ui/compare/server/v5.13.1...server/v5.14.0) (2025-11-29)


### Features

* support metadata in Python SDK ([#134](https://github.com/MCP-UI-Org/mcp-ui/issues/134)) ([9bc3c64](https://github.com/MCP-UI-Org/mcp-ui/commit/9bc3c646c2638e16ac62edf9faca2dbee2b8cb7e))

## [5.13.1](https://github.com/idosal/mcp-ui/compare/server/v5.13.0...server/v5.13.1) (2025-10-25)


### Bug Fixes

* Enable bidirectional message relay in rawhtml proxy mode ([#138](https://github.com/idosal/mcp-ui/issues/138)) ([f0bdefb](https://github.com/idosal/mcp-ui/commit/f0bdefb818aca5a3bfbdfe28fc4fe057b1818cb5))
* ensure Apps SDK adapter is bundled properly and initialized wth config ([#137](https://github.com/idosal/mcp-ui/issues/137)) ([4f7c25c](https://github.com/idosal/mcp-ui/commit/4f7c25ce7e6f25e36cfc188016b012d31d722204))

# [5.13.0](https://github.com/idosal/mcp-ui/compare/server/v5.12.0...server/v5.13.0) (2025-10-22)


### Bug Fixes

* fix file extension reference in package.json ([927989c](https://github.com/idosal/mcp-ui/commit/927989c4f81742106b6f5e2f68343fb7ea7d016a))


### Features

* support proxy for rawHtml ([#132](https://github.com/idosal/mcp-ui/issues/132)) ([1bbeb09](https://github.com/idosal/mcp-ui/commit/1bbeb093bc9c389f4ccfd9e8df06dc7f1eaadde0))

# [5.12.0](https://github.com/idosal/mcp-ui/compare/server/v5.11.0...server/v5.12.0) (2025-10-13)


### Bug Fixes

* update isUIResource to use EmbeddedResource type ([#122](https://github.com/idosal/mcp-ui/issues/122)) ([5a65a0b](https://github.com/idosal/mcp-ui/commit/5a65a0b1ba63e6cfda26b8da41239a532f00d60a)), closes [#117](https://github.com/idosal/mcp-ui/issues/117)


### Features

* add ui-request-render-data message type ([#111](https://github.com/idosal/mcp-ui/issues/111)) ([26135ce](https://github.com/idosal/mcp-ui/commit/26135ce2c7f7d586b0b81a03623cd77dc1bc7f90))
* support adapters ([#127](https://github.com/idosal/mcp-ui/issues/127)) ([d4bd152](https://github.com/idosal/mcp-ui/commit/d4bd152db0a1bd27081502098f3cd9aa54ca359e))

# [5.12.0-alpha.6](https://github.com/idosal/mcp-ui/compare/server/v5.12.0-alpha.5...server/v5.12.0-alpha.6) (2025-10-13)


### Bug Fixes

* separate adapter wrappers for flexibility ([#128](https://github.com/idosal/mcp-ui/issues/128)) ([a636844](https://github.com/idosal/mcp-ui/commit/a6368448c44b15da87c883cb3a65ebfe6119e85d))

# [5.12.0-alpha.5](https://github.com/idosal/mcp-ui/compare/server/v5.12.0-alpha.4...server/v5.12.0-alpha.5) (2025-10-12)


### Bug Fixes

* exports vite ([4de2b0c](https://github.com/idosal/mcp-ui/commit/4de2b0cfae91813ad68fb1ce68b1cf7c2a161baf))

# [5.12.0-alpha.4](https://github.com/idosal/mcp-ui/compare/server/v5.12.0-alpha.3...server/v5.12.0-alpha.4) (2025-10-11)


### Bug Fixes

* exports ([0018c17](https://github.com/idosal/mcp-ui/commit/0018c17dd8b184ee549327f1742d9da71edfd576))

# [5.12.0-alpha.3](https://github.com/idosal/mcp-ui/compare/server/v5.12.0-alpha.2...server/v5.12.0-alpha.3) (2025-10-11)


### Bug Fixes

* version ([767a245](https://github.com/idosal/mcp-ui/commit/767a245d2374f05e27ece090dc5af8613a9a6b96))

# [5.12.0-alpha.2](https://github.com/idosal/mcp-ui/compare/server/v5.12.0-alpha.1...server/v5.12.0-alpha.2) (2025-10-10)


### Bug Fixes

* set the mime type as text/html+skybridge for apps SDK ([bc47423](https://github.com/idosal/mcp-ui/commit/bc474232a249e5cc40f348e3a26f93c806fcc602))

# [5.12.0-alpha.1](https://github.com/idosal/mcp-ui/compare/server/v5.11.0...server/v5.12.0-alpha.1) (2025-10-10)


### Bug Fixes

* adapter version ([259c842](https://github.com/idosal/mcp-ui/commit/259c84247a00933575e1fff08674cce52be59973))
* release ([420efc0](https://github.com/idosal/mcp-ui/commit/420efc0a82bf8de2731514648268cad1209320e2))
* server alpha versioning ([7f35d3b](https://github.com/idosal/mcp-ui/commit/7f35d3be2cfa6a535d3fbd5f86fbec1b20432dca))
* server versioning ([2324371](https://github.com/idosal/mcp-ui/commit/2324371ed636381bb44a1feae1b59a87c84c6666))
* update isUIResource to use EmbeddedResource type ([#122](https://github.com/idosal/mcp-ui/issues/122)) ([5a65a0b](https://github.com/idosal/mcp-ui/commit/5a65a0b1ba63e6cfda26b8da41239a532f00d60a)), closes [#117](https://github.com/idosal/mcp-ui/issues/117)


### Features

* add adapters infra (appssdk) ([#125](https://github.com/idosal/mcp-ui/issues/125)) ([2e016cd](https://github.com/idosal/mcp-ui/commit/2e016cdc05d08c2f7c2e4a40efbec2b0704e7ef6))
* add ui-request-render-data message type ([#111](https://github.com/idosal/mcp-ui/issues/111)) ([26135ce](https://github.com/idosal/mcp-ui/commit/26135ce2c7f7d586b0b81a03623cd77dc1bc7f90))

# 1.0.0-alpha.1 (2025-10-10)


### Bug Fixes

* adapter version ([259c842](https://github.com/idosal/mcp-ui/commit/259c84247a00933575e1fff08674cce52be59973))
* add a bridge to pass messages in and out of the proxy ([#38](https://github.com/idosal/mcp-ui/issues/38)) ([30ccac0](https://github.com/idosal/mcp-ui/commit/30ccac0706ad8e02ebcd8960924ed1d58ddedf85))
* bump client version ([75c9236](https://github.com/idosal/mcp-ui/commit/75c923689654b4443ad1093fafc0bad16902e4cc))
* **client:** specify iframe ([fd0b70a](https://github.com/idosal/mcp-ui/commit/fd0b70a84948d3aa5d7a79269ff7c3bcd0946689))
* **client:** styling ([6ff9b68](https://github.com/idosal/mcp-ui/commit/6ff9b685fd1be770fd103943e45275e9ec86905c))
* dependencies ([887f61f](https://github.com/idosal/mcp-ui/commit/887f61f827b4585c17493d4fa2dfb251ea598587))
* export RemoteDomResource ([2b86f2d](https://github.com/idosal/mcp-ui/commit/2b86f2dd4506de49c69908e23d84a2a323170446))
* export ResourceRenderer and HtmlResource ([2b841a5](https://github.com/idosal/mcp-ui/commit/2b841a556c1111ed70ccb3d3987afd21fe7df897))
* exports ([3a93a16](https://github.com/idosal/mcp-ui/commit/3a93a16e1b7438ba7b2ef49ca854479f755abcc6))
* iframe handle ([#15](https://github.com/idosal/mcp-ui/issues/15)) ([66bd4fd](https://github.com/idosal/mcp-ui/commit/66bd4fd3d04f82e3e4557f064e701b68e1d8af11))
* lint ([4487820](https://github.com/idosal/mcp-ui/commit/44878203a71c3c9173d463b809be36769e996ba9))
* lint ([d0a91f9](https://github.com/idosal/mcp-ui/commit/d0a91f9a07ec0042690240c3d8d0bad620f8c765))
* minor typo ([a0bee9c](https://github.com/idosal/mcp-ui/commit/a0bee9c85e5ee02e021ba687940ced38220445fe))
* move react dependencies to be peer dependencies ([#91](https://github.com/idosal/mcp-ui/issues/91)) ([f672f3e](https://github.com/idosal/mcp-ui/commit/f672f3efc1c2ba2fbae16f9dcdc2142c2b4bd920)), closes [#90](https://github.com/idosal/mcp-ui/issues/90)
* package config ([8dc1e53](https://github.com/idosal/mcp-ui/commit/8dc1e5358c3c8e641206a5e6851427d360cc1955))
* packaging ([9e6babd](https://github.com/idosal/mcp-ui/commit/9e6babd3a587213452ea7aec4cc9ae3a50fa1965))
* pass ref explicitly using iframeProps ([#33](https://github.com/idosal/mcp-ui/issues/33)) ([d01b5d1](https://github.com/idosal/mcp-ui/commit/d01b5d1e4cdaedc436ba2fa8984d866d93d59087))
* publish ([0943e7a](https://github.com/idosal/mcp-ui/commit/0943e7acaf17f32aae085c2313bfbec47bc59f1f))
* ref passing to UIResourceRenderer ([#32](https://github.com/idosal/mcp-ui/issues/32)) ([d28c23f](https://github.com/idosal/mcp-ui/commit/d28c23f9b8ee320f4e361200ae02a23f0d2a1c0c))
* release ([420efc0](https://github.com/idosal/mcp-ui/commit/420efc0a82bf8de2731514648268cad1209320e2))
* remove shared dependency ([e66e8f4](https://github.com/idosal/mcp-ui/commit/e66e8f49b1ba46090db6e4682060488566f4fe41))
* rename components and methods to fit new scope ([#22](https://github.com/idosal/mcp-ui/issues/22)) ([6bab1fe](https://github.com/idosal/mcp-ui/commit/6bab1fe3a168a18e7ba4762e23478abf4e0cc84c))
* rename delivery -> encoding and flavor -> framework ([#36](https://github.com/idosal/mcp-ui/issues/36)) ([9a509ed](https://github.com/idosal/mcp-ui/commit/9a509ed80d051b0a8042b36958b401a0a7c1e138))
* Ruby comment ([b22dc2e](https://github.com/idosal/mcp-ui/commit/b22dc2e0a0db20d98ada884649ad408ebaf72d22))
* server versioning ([2324371](https://github.com/idosal/mcp-ui/commit/2324371ed636381bb44a1feae1b59a87c84c6666))
* support react-router ([21ffb95](https://github.com/idosal/mcp-ui/commit/21ffb95fe6d77a348b95b38dbf3741ba6442894e))
* text and blob support in RemoteDOM resources ([ec68eb9](https://github.com/idosal/mcp-ui/commit/ec68eb90df984da8b492cc25eafdafdeda79f299))
* trigger release ([aaca831](https://github.com/idosal/mcp-ui/commit/aaca83125c3f7825ccdebf0f04f8553e953c5249))
* typescript ci publish ([e7c0ebf](https://github.com/idosal/mcp-ui/commit/e7c0ebfa7f7b552f9763743fda659d1441f21692))
* typescript types to be compatible with MCP SDK ([#10](https://github.com/idosal/mcp-ui/issues/10)) ([74365d7](https://github.com/idosal/mcp-ui/commit/74365d7ed6422beef6cd9ee0f5a97c847bd9827b))
* update deps ([4091ef4](https://github.com/idosal/mcp-ui/commit/4091ef47da048fab3c4feb002f5287b2ff295744))
* update isUIResource to use EmbeddedResource type ([#122](https://github.com/idosal/mcp-ui/issues/122)) ([5a65a0b](https://github.com/idosal/mcp-ui/commit/5a65a0b1ba63e6cfda26b8da41239a532f00d60a)), closes [#117](https://github.com/idosal/mcp-ui/issues/117)
* use targetOrigin in the proxy message relay ([#40](https://github.com/idosal/mcp-ui/issues/40)) ([b3fb54e](https://github.com/idosal/mcp-ui/commit/b3fb54e28ca7b8eeda896b5bcf478b6343dbba47))
* validate URL ([b7c994d](https://github.com/idosal/mcp-ui/commit/b7c994dfdd947b3dfbb903fc8cb896d61004c8d8))
* wc dist overwrite ([#63](https://github.com/idosal/mcp-ui/issues/63)) ([9e46c56](https://github.com/idosal/mcp-ui/commit/9e46c56c7a8908410fad6d08a5d845139e93f80f))


### Documentation

* bump ([#4](https://github.com/idosal/mcp-ui/issues/4)) ([ad4d163](https://github.com/idosal/mcp-ui/commit/ad4d1632cc1f9c99072349a8f0cdaac343236132))


### Features

* add adapters infra (appssdk) ([#125](https://github.com/idosal/mcp-ui/issues/125)) ([2e016cd](https://github.com/idosal/mcp-ui/commit/2e016cdc05d08c2f7c2e4a40efbec2b0704e7ef6))
* add convenience function isUIResource to client SDK ([#86](https://github.com/idosal/mcp-ui/issues/86)) ([607c6ad](https://github.com/idosal/mcp-ui/commit/607c6add3567bb60c45accf3e1b25a38ed284a6f))
* add embeddedResourceProps for annotations ([#99](https://github.com/idosal/mcp-ui/issues/99)) ([b96ec44](https://github.com/idosal/mcp-ui/commit/b96ec442ec319a1944393ada0bdcccb93b7ffc62))
* add proxy option to externalUrl ([#37](https://github.com/idosal/mcp-ui/issues/37)) ([7b95cd0](https://github.com/idosal/mcp-ui/commit/7b95cd0b3873fc1cde28748ec463e81c6ff1c494))
* add remote-dom content type ([#18](https://github.com/idosal/mcp-ui/issues/18)) ([5dacf37](https://github.com/idosal/mcp-ui/commit/5dacf37c22b5ee6ae795049a8d573fc073b8a1f5))
* add Ruby server SDK ([#31](https://github.com/idosal/mcp-ui/issues/31)) ([5ffcde4](https://github.com/idosal/mcp-ui/commit/5ffcde4a373accdd063fa6c3b1b3d4df13c91b53))
* add sandbox permissions instead of an override ([#83](https://github.com/idosal/mcp-ui/issues/83)) ([b1068e9](https://github.com/idosal/mcp-ui/commit/b1068e9e87caa2b4302bf145a33efdfd1af05c1d))
* add ui-request-render-data message type ([#111](https://github.com/idosal/mcp-ui/issues/111)) ([26135ce](https://github.com/idosal/mcp-ui/commit/26135ce2c7f7d586b0b81a03623cd77dc1bc7f90))
* add UIResourceRenderer Web Component ([#58](https://github.com/idosal/mcp-ui/issues/58)) ([ec8f299](https://github.com/idosal/mcp-ui/commit/ec8f2994ecf36774e6ad5191654ba22946d0ee49))
* auto resize with the autoResizeIframe prop ([#56](https://github.com/idosal/mcp-ui/issues/56)) ([76c867a](https://github.com/idosal/mcp-ui/commit/76c867a569b72aed892290aa84e1194ab8eb79ce))
* change onGenericMcpAction to optional onUiAction ([1913b59](https://github.com/idosal/mcp-ui/commit/1913b5977c30811f9e67659949e2d961f2eda983))
* **client:** allow setting supportedContentTypes for HtmlResource ([#17](https://github.com/idosal/mcp-ui/issues/17)) ([e009ef1](https://github.com/idosal/mcp-ui/commit/e009ef10010134ba3d9893314cc4d8e1274f1f07))
* consolidate ui:// and ui-app:// ([#8](https://github.com/idosal/mcp-ui/issues/8)) ([2e08035](https://github.com/idosal/mcp-ui/commit/2e08035676bb6a46ef3c94dba916bc895f1fa3cc))
* pass iframe props down ([#14](https://github.com/idosal/mcp-ui/issues/14)) ([112539d](https://github.com/idosal/mcp-ui/commit/112539d28640a96e8375a6b416f2ba559370b312))
* refactor UTFtoB64 (bump server version) ([#95](https://github.com/idosal/mcp-ui/issues/95)) ([2d5e16b](https://github.com/idosal/mcp-ui/commit/2d5e16bf39073ee890586f458412f0c3b474c2b8))
* send render data to the iframe ([#51](https://github.com/idosal/mcp-ui/issues/51)) ([d38cfc7](https://github.com/idosal/mcp-ui/commit/d38cfc7925061c1ae1911bdee408033c8e9f283d))
* separate html and remote-dom props ([#24](https://github.com/idosal/mcp-ui/issues/24)) ([a7f0529](https://github.com/idosal/mcp-ui/commit/a7f05299dc9cc40184f9ab25c5b648ee7077be64))
* support generic messages response ([#35](https://github.com/idosal/mcp-ui/issues/35)) ([10b407b](https://github.com/idosal/mcp-ui/commit/10b407b279b3ee9608ef077445f4d714f88343c5))
* support passing resource metadata ([#87](https://github.com/idosal/mcp-ui/issues/87)) ([f1c1c9b](https://github.com/idosal/mcp-ui/commit/f1c1c9b62dd74c63045b295eb388181843ac772a))
* support ui action result types ([#6](https://github.com/idosal/mcp-ui/issues/6)) ([899d152](https://github.com/idosal/mcp-ui/commit/899d1527286a281a23fbb8f3a207d435dfc3fe96))
* switch to ResourceRenderer ([#21](https://github.com/idosal/mcp-ui/issues/21)) ([6fe3166](https://github.com/idosal/mcp-ui/commit/6fe316682675e27db914d60696754677e3783448))


### BREAKING CHANGES

* The existing naming is ambiguous. Renaming delivery to encoding and flavor to framework should clarify the intent.
* exported names have changed
* removed deprecated client API
* (previous one didn't take due to semantic-release misalignment)

# [5.11.0](https://github.com/idosal/mcp-ui/compare/v5.10.0...v5.11.0) (2025-09-16)


### Features

* add embeddedResourceProps for annotations ([#99](https://github.com/idosal/mcp-ui/issues/99)) ([b96ec44](https://github.com/idosal/mcp-ui/commit/b96ec442ec319a1944393ada0bdcccb93b7ffc62))

# [5.10.0](https://github.com/idosal/mcp-ui/compare/v5.9.0...v5.10.0) (2025-08-22)


### Features

* refactor UTFtoB64 (bump server version) ([#95](https://github.com/idosal/mcp-ui/issues/95)) ([2d5e16b](https://github.com/idosal/mcp-ui/commit/2d5e16bf39073ee890586f458412f0c3b474c2b8))


================================================
FILE: sdks/typescript/server/README.md
================================================
## 📦 Model Context Protocol UI SDK

<p align="center">
  <img width="250" alt="image" src="https://github.com/user-attachments/assets/65b9698f-990f-4846-9b2d-88de91d53d4d" />
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@mcp-ui/server"><img src="https://img.shields.io/npm/v/@mcp-ui/server?label=server&color=green" alt="Server Version"></a>
  <a href="https://www.npmjs.com/package/@mcp-ui/client"><img src="https://img.shields.io/npm/v/@mcp-ui/client?label=client&color=blue" alt="Client Version"></a>
  <a href="https://rubygems.org/gems/mcp_ui_server"><img src="https://img.shields.io/gem/v/mcp_ui_server" alt="Ruby Server SDK Version"></a>
  <a href="https://pypi.org/project/mcp-ui-server/"><img src="https://img.shields.io/pypi/v/mcp-ui-server?label=python&color=yellow" alt="Python Server SDK Version"></a>
  <a href="https://discord.gg/CEAG4KW7ZH"><img src="https://img.shields.io/discord/1401195140436983879?logo=discord&label=discord" alt="Discord"></a>
  <a href="https://gitmcp.io/idosal/mcp-ui"><img src="https://img.shields.io/endpoint?url=https://gitmcp.io/badge/idosal/mcp-ui" alt="MCP Documentation"></a>
</p>

<p align="center">
  <a href="#-whats-mcp-ui">What's mcp-ui?</a> •
  <a href="#-core-concepts">Core Concepts</a> •
  <a href="#-installation">Installation</a> •
  <a href="#-getting-started">Getting Started</a> •
  <a href="#-walkthrough">Walkthrough</a> •
  <a href="#-examples">Examples</a> •
  <a href="#-supported-hosts">Supported Hosts</a> •
  <a href="#-security">Security</a> •
  <a href="#-roadmap">Roadmap</a> •
  <a href="#-contributing">Contributing</a> •
  <a href="#-license">License</a>
</p>

----

**`mcp-ui`** brings interactive web components to the [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP). Deliver rich, dynamic UI resources directly from your MCP server to be rendered by the client. Take AI interaction to the next level!

> *This project is an experimental community playground for MCP UI ideas. Expect rapid iteration and enhancements!*

<p align="center">
  <video src="https://github.com/user-attachments/assets/7180c822-2dd9-4f38-9d3e-b67679509483"></video>
</p>

## 💡 What's `mcp-ui`?

`mcp-ui` is a playground for the open spec of UI over MCP. It offers a collection of community SDKs comprising:

* **`@mcp-ui/server` (TypeScript)**: Utilities to generate UI resources (`UIResource`) on your MCP server.
* **`@mcp-ui/client` (TypeScript)**: UI components (e.g., `<AppRenderer />`) to render the UI resources and handle their events.
* **`mcp_ui_server` (Ruby)**: Utilities to generate UI resources on your MCP server in a Ruby environment.
* **`mcp-ui-server` (Python)**: Utilities to generate UI resources on your MCP server in a Python environment.

Together, they let you define reusable UI snippets on the server side, seamlessly and securely render them in the client, and react to their actions in the MCP host environment.

## ✨ Core Concepts

In essence, by using `mcp-ui` SDKs, servers and hosts can agree on contracts that enable them to create and render interactive UI snippets (as a path to a standardized UI approach in MCP).

### UI Resource
The primary payload returned from the server to the client is the `UIResource`:

```ts
interface UIResource {
  type: 'resource';
  resource: {
    uri: string;       // e.g., ui://component/id
    mimeType: 'text/html;profile=mcp-app';
    text?: string;      // HTML content
    blob?: string;      // Base64-encoded HTML content
  };
}
```

* **`uri`**: Unique identifier for caching and routing
  * `ui://…` — UI resources
* **`mimeType`**: `text/html;profile=mcp-app` — the MCP Apps standard MIME type
* **`text` vs. `blob`**: Choose `text` for simple strings; use `blob` for larger or encoded content.

## 🏗️ Installation

### TypeScript

```bash
# using npm
npm install @mcp-ui/server @mcp-ui/client

# or pnpm
pnpm add @mcp-ui/server @mcp-ui/client

# or yarn
yarn add @mcp-ui/server @mcp-ui/client
```

### Ruby

```bash
gem install mcp_ui_server
```

### Python

```bash
# using pip
pip install mcp-ui-server

# or uv
uv add mcp-ui-server
```

## 🚀 Getting Started

You can use [GitMCP](https://gitmcp.io/idosal/mcp-ui) to give your IDE access to `mcp-ui`'s latest documentation! 

### TypeScript

1. **Server-side**: Build your UI resources

   ```ts
   import { createUIResource } from '@mcp-ui/server';

   // Inline HTML
   const htmlResource = await createUIResource({
     uri: 'ui://greeting/1',
     content: { type: 'rawHtml', htmlString: '<p>Hello, MCP UI!</p>' },
     encoding: 'text',
   });

   // External URL (fetches the page HTML and injects a <base> tag)
   const externalUrlResource = await createUIResource({
     uri: 'ui://greeting/1',
     content: { type: 'externalUrl', iframeUrl: 'https://example.com' },
     encoding: 'text',
   });
   ```

2. **Client-side**: Render in your MCP host

   ```tsx
   import React from 'react';
   import { AppRenderer } from '@mcp-ui/client';

   function ToolUI({ client, toolName, toolInput, toolResult }) {
     return (
       <AppRenderer
         client={client}
         toolName={toolName}
         sandbox={{ url: sandboxUrl }}
         toolInput={toolInput}
         toolResult={toolResult}
       />
     );
   }
   ```

### Python

**Server-side**: Build your UI resources

   ```python
   from mcp_ui_server import create_ui_resource

   # Inline HTML
   html_resource = create_ui_resource({
     "uri": "ui://greeting/1",
     "content": { "type": "rawHtml", "htmlString": "<p>Hello, from Python!</p>" },
     "encoding": "text",
   })

   # External URL
   external_url_resource = create_ui_resource({
     "uri": "ui://greeting/2",
     "content": { "type": "externalUrl", "iframeUrl": "https://example.com" },
     "encoding": "text",
   })
   ```

### Ruby

**Server-side**: Build your UI resources

   ```ruby
   require 'mcp_ui_server'

   # Inline HTML
   html_resource = McpUiServer.create_ui_resource(
     uri: 'ui://greeting/1',
     content: { type: :raw_html, htmlString: '<p>Hello, from Ruby!</p>' },
     encoding: :text
   )

   # External URL
   external_url_resource = McpUiServer.create_ui_resource(
     uri: 'ui://greeting/2',
     content: { type: :external_url, iframeUrl: 'https://example.com' },
     encoding: :text
   )

   ```

## 🚶 Walkthrough

For a detailed, simple, step-by-step guide on how to integrate `mcp-ui` into your own server, check out the full server walkthroughs on the [mcp-ui documentation site](https://mcpui.dev):

- **[TypeScript Server Walkthrough](https://mcpui.dev/guide/server/typescript/walkthrough)**
- **[Ruby Server Walkthrough](https://mcpui.dev/guide/server/ruby/walkthrough)**
- **[Python Server Walkthrough](https://mcpui.dev/guide/server/python/walkthrough)**

These guides will show you how to add a `mcp-ui` endpoint to an existing server, create tools that return UI resources, and test your setup with the `ui-inspector`!

## 🌍 Examples

**Client Examples**
* [Goose](https://github.com/block/goose) - open source AI agent that supports `mcp-ui`.
* [LibreChat](https://github.com/danny-avila/LibreChat) - enhanced ChatGPT clone that supports `mcp-ui`.
* [ui-inspector](https://github.com/idosal/ui-inspector) - inspect local `mcp-ui`-enabled servers.
* [MCP-UI Chat](https://github.com/idosal/scira-mcp-ui-chat) - interactive chat built with the `mcp-ui` client. Check out the [hosted version](https://scira-mcp-chat-git-main-idosals-projects.vercel.app/)!
**Server Examples**
* **TypeScript**: A [full-featured server](examples/server) that is deployed to a hosted environment for easy testing.
  * **[`typescript-server-demo`](./examples/typescript-server-demo)**: A simple Typescript server that demonstrates how to generate UI resources.
  * **server**: A [full-featured Typescript server](examples/server) that is deployed to a hosted Cloudflare environment for easy testing.
    * **HTTP Streaming**: `https://remote-mcp-server-authless.idosalomon.workers.dev/mcp`
    * **SSE**: `https://remote-mcp-server-authless.idosalomon.workers.dev/sse`
* **Ruby**: A barebones [demo server](/examples/ruby-server-demo) that shows how to use `mcp_ui_server` and `mcp` gems together.
* **Python**: A simple [demo server](/examples/python-server-demo) that shows how to use the `mcp-ui-server` Python package.
* [XMCP](https://github.com/basementstudio/xmcp/tree/main/examples/mcp-ui) - Typescript MCP framework with `mcp-ui` starter example.

Drop those URLs into any MCP-compatible host to see `mcp-ui` in action. For a supported local inspector, see the [ui-inspector](https://github.com/idosal/ui-inspector).

## 💻 Supported Hosts

`mcp-ui` is supported by a growing number of MCP-compatible clients. Feature support varies by host:

| Host      | Rendering | UI Actions | Notes
| :-------- | :-------: | :--------: | :--------: |
| [Nanobot](https://www.nanobot.ai/)    |     ✅    |     ✅     |
| [ChatGPT](https://chatgpt.com/)    |     ✅    |     ⚠️     | [Guide](https://mcpui.dev/guide/apps-sdk)
| [Postman](https://www.postman.com/)   |     ✅    |     ⚠️      |
| [Goose](https://block.github.io/goose/)     |     ✅    |     ⚠️      |
| [LibreChat](https://www.librechat.ai/)    |     ✅    |     ⚠️     |
| [Smithery](https://smithery.ai/playground)  |     ✅    |     ❌     |
| [MCPJam](https://www.mcpjam.com/)    |     ✅    |     ❌     |
| [fast-agent](https://fast-agent.ai/mcp/mcp-ui/) | ✅ | ❌ |
| [VSCode](https://github.com/microsoft/vscode/issues/260218) (TBA)    |    ?    |    ?     |

**Legend:**
- ✅: Supported
- ⚠️: Partial Support
- ❌: Not Supported (yet)

## 🔒 Security
Host and user security is one of `mcp-ui`'s primary concerns. In all content types, the remote code is executed in a sandboxed iframe.

## 🛣️ Roadmap

- [X] Add online playground
- [X] Expand UI Action API (beyond tool calls)
- [ ] Add component libraries (in progress)
- [ ] Add SDKs for additional programming languages (in progress; Ruby, Python available)
- [ ] Support additional frontend frameworks
- [ ] Add declarative UI content type
- [ ] Support generative UI?
      
## Core Team
`mcp-ui` is a project by [Ido Salomon](https://x.com/idosal1), in collaboration with [Liad Yosef](https://x.com/liadyosef).

## 🤝 Contributing

Contributions, ideas, and bug reports are welcome! See the [contribution guidelines](https://github.com/idosal/mcp-ui/blob/main/.github/CONTRIBUTING.md) to get started.

## 📄 License

Apache License 2.0 © [The MCP-UI Authors](LICENSE)

## Disclaimer

This project is provided "as is", without warranty of any kind. The `mcp-ui` authors and contributors shall not be held liable for any damages, losses, or issues arising from the use of this software. Use at your own risk.


================================================
FILE: sdks/typescript/server/package.json
================================================
{
  "name": "@mcp-ui/server",
  "version": "6.1.0",
  "private": false,
  "description": "mcp-ui Server SDK",
  "type": "module",
  "main": "./dist/index.cjs",
  "module": "./dist/index.mjs",
  "types": "./dist/src/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/src/index.d.ts",
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    }
  },
  "files": [
    "dist"
  ],
  "devDependencies": {
    "@types/node": "^18.19.100",
    "@vitest/coverage-v8": "^1.0.0",
    "typescript": "^5.0.0",
    "vite": "^5.0.0",
    "vite-plugin-dts": "^3.6.0",
    "vitest": "^1.0.0"
  },
  "scripts": {
    "prepublishOnly": "pnpm run build",
    "dev": "vite",
    "build": "vite build",
    "test": "vitest run",
    "test:watch": "vitest watch",
    "lint": "eslint ."
  },
  "publishConfig": {
    "access": "public"
  },
  "release": {
    "branches": [
      "main",
      {
        "name": "alpha",
        "prerelease": true
      }
    ],
    "tagFormat": "server/v${version}",
    "plugins": [
      "@semantic-release/commit-analyzer",
      "@semantic-release/release-notes-generator",
      [
        "@semantic-release/changelog",
        {
          "changelogFile": "CHANGELOG.md"
        }
      ],
      "@semantic-release/npm",
      "@semantic-release/github",
      [
        "@semantic-release/git",
        {
          "assets": [
            "CHANGELOG.md",
            "package.json"
          ],
          "message": "chore(release): ${nextRelease.version} [skip ci]\\n\\n${nextRelease.notes}"
        }
      ]
    ]
  },
  "license": "Apache-2.0",
  "dependencies": {
    "@modelcontextprotocol/ext-apps": "^0.3.1",
    "@modelcontextprotocol/sdk": "^1.25.1"
  }
}


================================================
FILE: sdks/typescript/server/src/__tests__/index.test.ts
================================================
import {
  createUIResource,
  sendExperimentalRequest,
} from '../index';
import { UI_METADATA_PREFIX } from '../types.js';
import { mockFetchWithBody } from './test-utils';

describe('@mcp-ui/server', () => {
  describe('createUIResource', () => {
    it('should create a text-based direct HTML resource', async () => {
      const options = {
        uri: 'ui://test-html' as const,
        content: { type: 'rawHtml' as const, htmlString: '<p>Test</p>' },
        encoding: 'text' as const,
      };
      const resource = await createUIResource(options);
      expect(resource.type).toBe('resource');
      expect(resource.resource.uri).toBe('ui://test-html');
      expect(resource.resource.mimeType).toBe('text/html;profile=mcp-app');
      expect(resource.resource.text).toBe('<p>Test</p>');
      expect(resource.resource.blob).toBeUndefined();
    });

    it('should create a blob-based direct HTML resource', async () => {
      const options = {
        uri: 'ui://test-html-blob' as const,
        content: { type: 'rawHtml' as const, htmlString: '<h1>Blob</h1>' },
        encoding: 'blob' as const,
      };
      const resource = await createUIResource(options);
      expect(resource.resource.blob).toBe(Buffer.from('<h1>Blob</h1>').toString('base64'));
      expect(resource.resource.text).toBeUndefined();
    });

    describe('externalUrl (fetches and injects <base>)', () => {
      const MOCK_HTML = '<html><head><title>Test</title></head><body>Hello</body></html>';

      beforeEach(() => {
        mockFetchWithBody(MOCK_HTML);
      });

      afterEach(() => {
        vi.unstubAllGlobals();
      });

      it('should fetch external URL, inject <base> tag, and set CSP resourceDomains', async () => {
        const resource = await createUIResource({
          uri: 'ui://test-url' as const,
          content: { type: 'externalUrl' as const, iframeUrl: 'https://example.com/page' },
          encoding: 'text' as const,
        });

        expect(fetch).toHaveBeenCalledWith('https://example.com/page', expect.objectContaining({
          signal: expect.any(AbortSignal),
        }));
        expect(resource.resource.uri).toBe('ui://test-url');
        expect(resource.resource.mimeType).toBe('text/html;profile=mcp-app');
        expect(resource.resource.text).toBe(
          '<html><head><base href="https://example.com/page"><title>Test</title></head><body>Hello</body></html>',
        );
        expect(resource.resource.blob).toBeUndefined();
        // CSP resourceDomains should contain the external origin
        expect(resource.resource._meta).toEqual({
          csp: { baseUriDomains: ['https://example.com'] },
        });
      });

      it('should fetch and encode as blob', async () => {
        const resource = await createUIResource({
          uri: 'ui://test-url-blob' as const,
          content: { type: 'externalUrl' as const, iframeUrl: 'https://example.com/blob' },
          encoding: 'blob' as const,
        });

        expect(fetch).toHaveBeenCalledWith('https://example.com/blob', expect.objectContaining({
          signal: expect.any(AbortSignal),
        }));
        const expectedHtml =
          '<html><head><base href="https://example.com/blob"><title>Test</title></head><body>Hello</body></html>';
        expect(resource.resource.blob).toBe(Buffer.from(expectedHtml).toString('base64'));
        expect(resource.resource.text).toBeUndefined();
      });

      it('should include metadata on fetched external URL resource', async () => {
        const resource = await createUIResource({
          uri: 'ui://test-url' as const,
          content: { type: 'externalUrl' as const, iframeUrl: 'https://example.com' },
          encoding: 'text' as const,
          uiMetadata: { 'preferred-frame-size': ['100px', '100px'] as [string, string] },
          resourceProps: { _meta: { 'arbitrary-prop': 'arbitrary' } },
        });

        expect(resource.resource._meta).toEqual({
          [`${UI_METADATA_PREFIX}preferred-frame-size`]: ['100px', '100px'],
          'arbitrary-prop': 'arbitrary',
          csp: { baseUriDomains: ['https://example.com'] },
        });
      });

      it('should include metadata respecting order of overriding metadata', async () => {
        const resource = await createUIResource({
          uri: 'ui://test-url' as const,
          content: { type: 'externalUrl' as const, iframeUrl: 'https://example.com' },
          encoding: 'text' as const,
          metadata: { 'arbitrary-prop': 'arbitrary', foo: 'bar' },
          resourceProps: { _meta: { 'arbitrary-prop': 'arbitrary2' } },
        });

        expect(resource.resource._meta).toEqual({
          foo: 'bar',
          'arbitrary-prop': 'arbitrary2',
          csp: { baseUriDomains: ['https://example.com'] },
        });
      });

      it('should include embedded resource props', async () => {
        const resource = await createUIResource({
          uri: 'ui://test-url' as const,
          content: { type: 'externalUrl' as const, iframeUrl: 'https://example.com' },
          encoding: 'text' as const,
          uiMetadata: { 'preferred-frame-size': ['100px', '100px'] as [string, string] },
          resourceProps: { _meta: { 'arbitrary-metadata': 'resource-level-metadata' } },
          embeddedResourceProps: {
            annotations: { audience: ['user'] },
            _meta: { 'arbitrary-metadata': 'embedded-resource-metadata' },
          },
        });

        expect(resource.annotations).toEqual({ audience: ['user'] });
        expect(resource._meta).toEqual({ 'arbitrary-metadata': 'embedded-resource-metadata' });
        expect(resource.resource._meta).toEqual({
          'arbitrary-metadata': 'resource-level-metadata',
          [`${UI_METADATA_PREFIX}preferred-frame-size`]: ['100px', '100px'],
          csp: { baseUriDomains: ['https://example.com'] },
        });
      });

      it('should merge with existing CSP baseUriDomains without duplicating', async () => {
        const resource = await createUIResource({
          uri: 'ui://test-url' as const,
          content: { type: 'externalUrl' as const, iframeUrl: 'https://example.com/page' },
          encoding: 'text' as const,
          resourceProps: {
            _meta: { csp: { baseUriDomains: ['https://cdn.other.com'] } },
          },
        });

        expect(resource.resource._meta).toEqual({
          csp: { baseUriDomains: ['https://cdn.other.com', 'https://example.com'] },
        });
      });

      it('should not duplicate origin if already present in CSP baseUriDomains', async () => {
        const resource = await createUIResource({
          uri: 'ui://test-url' as const,
          content: { type: 'externalUrl' as const, iframeUrl: 'https://example.com/page' },
          encoding: 'text' as const,
          resourceProps: {
            _meta: { csp: { baseUriDomains: ['https://example.com'] } },
          },
        });

        expect(resource.resource._meta).toEqual({
          csp: { baseUriDomains: ['https://example.com'] },
        });
      });

      it('should throw when fetch fails', async () => {
        vi.stubGlobal(
          'fetch',
          vi.fn().mockResolvedValue({
            ok: false,
            status: 404,
            statusText: 'Not Found',
            headers: new Headers(),
          }),
        );

        await expect(
          createUIResource({
            uri: 'ui://test-url' as const,
            content: { type: 'externalUrl' as const, iframeUrl: 'https://example.com/missing' },
            encoding: 'text' as const,
          }),
        ).rejects.toThrow('Failed to fetch external URL');
      });
    });

    it('should create a blob-based direct HTML resource with correct mimetype', async () => {
      const options = {
        uri: 'ui://test-html-blob' as const,
        content: { type: 'rawHtml' as const, htmlString: '<h1>Blob</h1>' },
        encoding: 'blob' as const,
      };
      const resource = await createUIResource(options);
      expect(resource.resource.mimeType).toBe('text/html;profile=mcp-app');
      expect(resource.resource.blob).toBe(Buffer.from('<h1>Blob</h1>').toString('base64'));
      expect(resource.resource.text).toBeUndefined();
    });

    it('should throw error for invalid URI prefix with rawHtml', async () => {
      const options = {
        uri: 'invalid://test-html' as const,
        content: { type: 'rawHtml' as const, htmlString: '<p>Test</p>' },
        encoding: 'text' as const,
      };
      // @ts-expect-error We are intentionally passing an invalid URI to test the error.
      await expect(createUIResource(options)).rejects.toThrow(
        "MCP-UI SDK: URI must start with 'ui://'.",
      );
    });

    it('should throw error for invalid URI prefix with externalUrl', async () => {
      const options = {
        uri: 'invalid://test-url' as const,
        content: {
          type: 'externalUrl' as const,
          iframeUrl: 'https://example.com',
        },
        encoding: 'text' as const,
      };
      // @ts-expect-error We are intentionally passing an invalid URI to test the error.
      await expect(createUIResource(options)).rejects.toThrow(
        "MCP-UI SDK: URI must start with 'ui://'.",
      );
    });

    it('should throw an error if htmlString is not a string for rawHtml', async () => {
      const options = {
        uri: 'ui://test' as const,
        content: { type: 'rawHtml' as const, htmlString: null },
      };
      // @ts-expect-error intentionally passing invalid type
      await expect(createUIResource(options)).rejects.toThrow(
        "MCP-UI SDK: content.htmlString must be provided as a string when content.type is 'rawHtml'.",
      );
    });

    it('should throw an error if iframeUrl is not a string for externalUrl', async () => {
      const options = {
        uri: 'ui://test' as const,
        content: { type: 'externalUrl' as const, iframeUrl: 123 },
      };
      // @ts-expect-error intentionally passing invalid type
      await expect(createUIResource(options)).rejects.toThrow(
        "MCP-UI SDK: content.iframeUrl must be provided as a string when content.type is 'externalUrl'.",
      );
    });

    it('should use MCP Apps mime type', async () => {
      const options = {
        uri: 'ui://test-html-no-config' as const,
        content: { type: 'rawHtml' as const, htmlString: '<p>Test no config</p>' },
        encoding: 'text' as const,
      };
      const resource = await createUIResource(options);
      expect(resource.resource.mimeType).toBe('text/html;profile=mcp-app');
      expect(resource.resource.text).toBe('<p>Test no config</p>');
    });
  });
});

describe('sendExperimentalRequest', () => {
  let originalParent: typeof window.parent;
  const mockParent = {
    postMessage: vi.fn(),
  };

  beforeEach(() => {
    vi.useFakeTimers();
    originalParent = window.parent;
    // Simulate being inside an iframe by making parent !== window
    Object.defineProperty(window, 'parent', {
      value: mockParent,
      writable: true,
      configurable: true,
    });
    mockParent.postMessage.mockClear();
  });

  afterEach(() => {
    vi.useRealTimers();
    Object.defineProperty(window, 'parent', {
      value: originalParent,
      writable: true,
      configurable: true,
    });
  });

  /** Simulate the host responding to a JSON-RPC request via postMessage */
  function simulateResponse(data: Record<string, unknown>, source: unknown = mockParent) {
    const event = new MessageEvent('message', { data, source: source as Window });
    window.dispatchEvent(event);
  }

  it('should reject when not inside an iframe', async () => {
    // Restore parent === window (top-level context)
    Object.defineProperty(window, 'parent', {
      value: window,
      writable: true,
      configurable: true,
    });

    await expect(sendExperimentalRequest('x/test')).rejects.toThrow(
      'sendExperimentalRequest must be called from within an iframe',
    );
  });

  it('should post a JSON-RPC request to the parent window', () => {
    sendExperimentalRequest('x/clipboard/write', { text: 'hello' });

    expect(mockParent.postMessage).toHaveBeenCalledWith(
      expect.objectContaining({
        jsonrpc: '2.0',
        method: 'x/clipboard/write',
        params: { text: 'hello' },
      }),
      '*',
    );
  });

  it('should omit params when not provided', () => {
    sendExperimentalRequest('x/ping');

    const posted = mockParent.postMessage.mock.calls[0][0];
    expect(posted).not.toHaveProperty('params');
  });

  it('should resolve with the result on a successful response', async () => {
    const promise = sendExperimentalRequest('x/test', { key: 'val' });
    const sentId = mockParent.postMessage.mock.calls[0][0].id;

    simulateResponse({ jsonrpc: '2.0', id: sentId, result: { success: true } });

    await expect(promise).resolves.toEqual({ success: true });
  });

  it('should reject with the error on an error response', async () => {
    const promise = sendExperimentalRequest('x/test');
    const sentId = mockParent.postMessage.mock.calls[0][0].id;

    const error = { code: -32601, message: 'Method not found' };
    simulateResponse({ jsonrpc: '2.0', id: sentId, error });

    await expect(promise).rejects.toEqual(error);
  });

  it('should ignore messages from non-parent sources', async () => {
    const promise = sendExperimentalRequest('x/test', undefined, { timeoutMs: 100 });
    const sentId = mockParent.postMessage.mock.calls[0][0].id;

    // Message from a different source — should be ignored
    simulateResponse({ jsonrpc: '2.0', id: sentId, result: { spoofed: true } }, {} as Window);

    // The promise should still be pending; advance timers to trigger timeout
    vi.advanceTimersByTime(100);

    await expect(promise).rejects.toThrow('timed out');
  });

  it('should ignore messages with non-matching ids', async () => {
    const promise = sendExperimentalRequest('x/test', undefined, { timeoutMs: 100 });
    const sentId = mockParent.postMessage.mock.calls[0][0].id;

    // Response with a different id
    simulateResponse({ jsonrpc: '2.0', id: sentId + 999, result: { wrong: true } });

    vi.advanceTimersByTime(100);

    await expect(promise).rejects.toThrow('timed out');
  });

  it('should reject after default timeout', async () => {
    const promise = sendExperimentalRequest('x/slow');

    vi.advanceTimersByTime(30_000);

    await expect(promise).rejects.toThrow('timed out after 30000ms');
  });

  it('should reject after custom timeout', async () => {
    const promise = sendExperimentalRequest('x/slow', undefined, { timeoutMs: 500 });

    vi.advanceTimersByTime(500);

    await expect(promise).rejects.toThrow('timed out after 500ms');
  });

  it('should not timeout when timeoutMs is 0', async () => {
    const promise = sendExperimentalRequest('x/test', undefined, { timeoutMs: 0 });
    const sentId = mockParent.postMessage.mock.calls[0][0].id;

    // Advance far into the future — should not reject
    vi.advanceTimersByTime(999_999);

    // Now respond — should still resolve
    simulateResponse({ jsonrpc: '2.0', id: sentId, result: { late: true } });

    await expect(promise).resolves.toEqual({ late: true });
  });

  it('should reject immediately when signal is already aborted', async () => {
    const controller = new AbortController();
    controller.abort();

    await expect(
      sendExperimentalRequest('x/test', undefined, { signal: controller.signal }),
    ).rejects.toThrow('was aborted');
  });

  it('should reject when signal is aborted mid-request', async () => {
    const controller = new AbortController();
    const promise = sendExperimentalRequest('x/test', undefined, {
      signal: controller.signal,
      timeoutMs: 0,
    });

    controller.abort();

    await expect(promise).rejects.toThrow('was aborted');
  });

  it('should clean up the message listener after resolving', async () => {
    const removeSpy = vi.spyOn(window, 'removeEventListener');

    const promise = sendExperimentalRequest('x/test');
    const sentId = mockParent.postMessage.mock.calls[0][0].id;

    simulateResponse({ jsonrpc: '2.0', id: sentId, result: {} });
    await promise;

    expect(removeSpy).toHaveBeenCalledWith('message', expect.any(Function));
    removeSpy.mockRestore();
  });

  it('should clean up the message listener after timeout', async () => {
    const removeSpy = vi.spyOn(window, 'removeEventListener');

    const promise = sendExperimentalRequest('x/test', undefined, { timeoutMs: 100 });

    vi.advanceTimersByTime(100);

    await expect(promise).rejects.toThrow('timed out');
    expect(removeSpy).toHaveBeenCalledWith('message', expect.any(Function));
    removeSpy.mockRestore();
  });
});


================================================
FILE: sdks/typescript/server/src/__tests__/test-utils.ts
================================================
import { vi } from 'vitest';

/**
 * Stubs the global `fetch` to return a successful response with a streaming body
 * containing the given text. Useful for testing code that reads via `response.body.getReader()`.
 */
export function mockFetchWithBody(body: string, headers?: Record<string, string>) {
  const encoder = new TextEncoder();
  const encoded = encoder.encode(body);
  let readCalled = false;
  vi.stubGlobal(
    'fetch',
    vi.fn().mockResolvedValue({
      ok: true,
      headers: new Headers(headers ?? {}),
      body: {
        getReader: () => ({
          read: () => {
            if (!readCalled) {
              readCalled = true;
              return Promise.resolve({ done: false, value: encoded });
            }
            return Promise.resolve({ done: true, value: undefined });
          },
          cancel: vi.fn(),
        }),
      },
    }),
  );
}


================================================
FILE: sdks/typescript/server/src/__tests__/utils.test.ts
================================================
import { describe, it, expect, vi } from 'vitest';
import {
  extractOrigin,
  fetchExternalUrl,
  getAdditionalResourceProps,
  injectBaseTag,
  utf8ToBase64,
  validateExternalUrl,
} from '../utils.js';
import { UI_METADATA_PREFIX, RESOURCE_MIME_TYPE } from '../types.js';
import { mockFetchWithBody } from './test-utils';
import { RESOURCE_MIME_TYPE as EXT_APPS_RESOURCE_MIME_TYPE } from '@modelcontextprotocol/ext-apps';

describe('getAdditionalResourceProps', () => {
  it('should return the additional resource props', () => {
    const uiMetadata = {
      'preferred-frame-size': ['100px', '100px'] as [string, string],
      'initial-render-data': { test: 'test' },
    };
    const additionalResourceProps = getAdditionalResourceProps({ uiMetadata });
    expect(additionalResourceProps).toEqual({
      _meta: {
        [`${UI_METADATA_PREFIX}preferred-frame-size`]: ['100px', '100px'],
        [`${UI_METADATA_PREFIX}initial-render-data`]: { test: 'test' },
      },
    });
  });

  it('should return the additional resource props with user defined _meta', () => {
    const uiMetadata = {
      'preferred-frame-size': ['100px', '100px'] as [string, string],
      'initial-render-data': { test: 'test' },
    };
    const additionalResourceProps = getAdditionalResourceProps({
      uiMetadata,
      resourceProps: {
        annotations: { audience: 'user' },
        _meta: { foo: 'bar', [`${UI_METADATA_PREFIX}preferred-frame-size`]: ['200px', '200px'] },
      },
    });
    expect(additionalResourceProps).toEqual({
      _meta: {
        [`${UI_METADATA_PREFIX}initial-render-data`]: { test: 'test' },
        foo: 'bar',
        [`${UI_METADATA_PREFIX}preferred-frame-size`]: ['200px', '200px'],
      },
      annotations: { audience: 'user' },
    });
  });

  it('should return an empty object if no uiMetadata or metadata is provided', () => {
    const additionalResourceProps = getAdditionalResourceProps({});
    expect(additionalResourceProps).toEqual({});
  });

  it('should respect order of overriding metadata', () => {
    const additionalResourceProps = getAdditionalResourceProps({
      uiMetadata: { 'preferred-frame-size': ['100px', '100px'] as [string, string] },
      metadata: { [`${UI_METADATA_PREFIX}preferred-frame-size`]: ['200px', '200px'], foo: 'bar' },
      resourceProps: { annotations: { audience: 'user' }, _meta: { foo: 'baz' } },
    });
    expect(additionalResourceProps).toEqual({
      _meta: {
        [`${UI_METADATA_PREFIX}preferred-frame-size`]: ['200px', '200px'],
        foo: 'baz',
      },
      annotations: { audience: 'user' },
    });
  });
});

describe('utf8ToBase64', () => {
  it('should correctly encode a simple ASCII string', () => {
    const str = 'hello world';
    const expected = 'aGVsbG8gd29ybGQ=';
    expect(utf8ToBase64(str)).toBe(expected);
  });

  it('should correctly encode a string with UTF-8 characters', () => {
    const str = '你好,世界';
    const expected = '5L2g5aW9LOS4lueVjA==';
    expect(utf8ToBase64(str)).toBe(expected);
  });

  it('should correctly encode an empty string', () => {
    const str = '';
    const expected = '';
    expect(utf8ToBase64(str)).toBe(expected);
  });

  it('should correctly encode a string with various special characters', () => {
    const str = '`~!@#$%^&*()_+-=[]{}\\|;\':",./<>?';
    const expected = 'YH4hQCMkJV4mKigpXystPVtde31cfDsnOiIsLi88Pj8=';
    expect(utf8ToBase64(str)).toBe(expected);
  });

  it('should use TextEncoder and btoa when Buffer is not available', () => {
    const str = 'hello world';
    const expected = 'aGVsbG8gd29ybGQ=';

    const bufferBackup = global.Buffer;
    // @ts-expect-error - simulating Buffer not being available
    delete global.Buffer;

    expect(utf8ToBase64(str)).toBe(expected);

    global.Buffer = bufferBackup;
  });

  it('should use fallback btoa when Buffer and TextEncoder are not available', () => {
    const str = 'hello world';
    const expected = 'aGVsbG8gd29ybGQ=';

    const bufferBackup = global.Buffer;
    const textEncoderBackup = global.TextEncoder;

    // @ts-expect-error - simulating Buffer not being available
    delete global.Buffer;
    // @ts-expect-error - simulating TextEncoder not being available
    delete global.TextEncoder;

    const consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
    expect(utf8ToBase64(str)).toBe(expected);
    expect(consoleWarnSpy).toHaveBeenCalledWith(
      'MCP-UI SDK: Buffer API and TextEncoder/btoa not available. Base64 encoding might not be UTF-8 safe.',
    );

    consoleWarnSpy.mockRestore();
    global.Buffer = bufferBackup;
    global.TextEncoder = textEncoderBackup;
  });

  it('should throw an error if all encoding methods fail', () => {
    const str = 'hello world';

    const bufferBackup = global.Buffer;
    const textEncoderBackup = global.TextEncoder;
    const btoaBackup = global.btoa;

    // @ts-expect-error - simulating Buffer not being available
    delete global.Buffer;
    // @ts-expect-error - simulating TextEncoder not being available
    delete global.TextEncoder;
    // @ts-expect-error - simulating btoa not being available
    delete global.btoa;

    expect(() => utf8ToBase64(str)).toThrow(
      'MCP-UI SDK: Suitable UTF-8 to Base64 encoding method not found, and fallback btoa failed.',
    );

    global.Buffer = bufferBackup;
    global.TextEncoder = textEncoderBackup;
    global.btoa = btoaBackup;
  });
});

describe('injectBaseTag', () => {
  it('should inject after <head>', () => {
    const html = '<html><head><title>Test</title></head><body></body></html>';
    expect(injectBaseTag(html, 'https://example.com/page')).toBe(
      '<html><head><base href="https://example.com/page"><title>Test</title></head><body></body></html>',
    );
  });

  it('should inject after <head> with attributes', () => {
    const html = '<html><head lang="en"><title>Test</title></head></html>';
    expect(injectBaseTag(html, 'https://example.com')).toBe(
      '<html><head lang="en"><base href="https://example.com"><title>Test</title></head></html>',
    );
  });

  it('should prepend if no <head> tag', () => {
    const html = '<p>Hello</p>';
    expect(injectBaseTag(html, 'https://example.com')).toBe(
      '<base href="https://example.com"><p>Hello</p>',
    );
  });

  it('should not add if <base> already exists', () => {
    const html = '<html><head><base href="https://other.com"><title>T</title></head></html>';
    expect(injectBaseTag(html, 'https://example.com')).toBe(html);
  });

  it('should escape ampersands and quotes in URL', () => {
    const html = '<head></head>';
    expect(injectBaseTag(html, 'https://example.com/a?b=1&c="2"')).toBe(
      '<head><base href="https://example.com/a?b=1&amp;c=&quot;2&quot;"></head>',
    );
  });
});

describe('extractOrigin', () => {
  it('should extract origin from a valid URL', () => {
    expect(extractOrigin('https://example.com/page?q=1')).toBe('https://example.com');
  });

  it('should include port if non-default', () => {
    expect(extractOrigin('https://example.com:8080/path')).toBe('https://example.com:8080');
  });

  it('should return undefined for invalid URLs', () => {
    expect(extractOrigin('not a url')).toBeUndefined();
  });
});

describe('validateExternalUrl', () => {
  it('should accept valid http URLs', () => {
    expect(() => validateExternalUrl('http://example.com')).not.toThrow();
  });

  it('should accept valid https URLs', () => {
    expect(() => validateExternalUrl('https://example.com/page?q=1')).not.toThrow();
  });

  it('should reject non-http protocols', () => {
    expect(() => validateExternalUrl('ftp://example.com')).toThrow('must use http or https');
    expect(() => validateExternalUrl('file:///etc/passwd')).toThrow('must use http or https');
  });

  it('should reject invalid URLs', () => {
    expect(() => validateExternalUrl('not a url')).toThrow('Invalid external URL');
  });

  it('should reject localhost', () => {
    expect(() => validateExternalUrl('http://localhost:3000')).toThrow('localhost or loopback');
    expect(() => validateExternalUrl('http://127.0.0.1:8080')).toThrow('localhost or loopback');
    expect(() => validateExternalUrl('http://[::1]/page')).toThrow('localhost or loopback');
    expect(() => validateExternalUrl('http://0.0.0.0')).toThrow('localhost or loopback');
  });

  it('should reject private IPv4 ranges', () => {
    expect(() => validateExternalUrl('http://10.0.0.1')).toThrow('private network');
    expect(() => validateExternalUrl('http://172.16.0.1')).toThrow('private network');
    expect(() => validateExternalUrl('http://172.31.255.255')).toThrow('private network');
    expect(() => validateExternalUrl('http://192.168.1.1')).toThrow('private network');
    expect(() => validateExternalUrl('http://169.254.169.254')).toThrow('private network');
  });

  it('should allow public IPs and non-private ranges', () => {
    expect(() => validateExternalUrl('http://8.8.8.8')).not.toThrow();
    expect(() => validateExternalUrl('http://172.32.0.1')).not.toThrow();
    expect(() => validateExternalUrl('https://203.0.113.1')).not.toThrow();
  });
});

describe('fetchExternalUrl', () => {
  afterEach(() => {
    vi.unstubAllGlobals();
  });

  it('should fetch and inject <base> tag', async () => {
    mockFetchWithBody('<html><head></head><body>Hi</body></html>');

    const result = await fetchExternalUrl('https://example.com/page');
    expect(fetch).toHaveBeenCalledWith('https://example.com/page', expect.objectContaining({
      signal: expect.any(AbortSignal),
      redirect: 'follow',
    }));
    expect(result).toBe(
      '<html><head><base href="https://example.com/page"></head><body>Hi</body></html>',
    );
  });

  it('should throw on non-OK response', async () => {
    vi.stubGlobal(
      'fetch',
      vi.fn().mockResolvedValue({
        ok: false,
        status: 500,
        statusText: 'Internal Server Error',
        headers: new Headers(),
      }),
    );

    await expect(fetchExternalUrl('https://example.com/error')).rejects.toThrow(
      'Failed to fetch external URL "https://example.com/error": 500 Internal Server Error',
    );
  });

  it('should reject URLs with non-http protocols', async () => {
    await expect(fetchExternalUrl('ftp://example.com')).rejects.toThrow('must use http or https');
  });

  it('should reject localhost URLs', async () => {
    await expect(fetchExternalUrl('http://localhost:3000')).rejects.toThrow('localhost or loopback');
  });

  it('should reject private IP URLs', async () => {
    await expect(fetchExternalUrl('http://10.0.0.1/admin')).rejects.toThrow('private network');
  });

  it('should reject responses exceeding content-length limit', async () => {
    vi.stubGlobal(
      'fetch',
      vi.fn().mockResolvedValue({
        ok: true,
        headers: new Headers({ 'content-length': '999999999' }),
        body: { getReader: () => ({ read: () => Promise.resolve({ done: true, value: undefined }), cancel: vi.fn() }) },
      }),
    );

    await expect(fetchExternalUrl('https://example.com/huge')).rejects.toThrow(
      'response too large',
    );
  });

  it('should reject responses exceeding streaming size limit', async () => {
    // Create a mock that returns chunks totalling over 10MB
    const bigChunk = new Uint8Array(6 * 1024 * 1024); // 6MB
    let callCount = 0;
    vi.stubGlobal(
      'fetch',
      vi.fn().mockResolvedValue({
        ok: true,
        headers: new Headers(),
        body: {
          getReader: () => ({
            read: () => {
              callCount++;
              if (callCount <= 2) {
                return Promise.resolve({ done: false, value: bigChunk });
              }
              return Promise.resolve({ done: true, value: undefined });
            },
            cancel: vi.fn(),
          }),
        },
      }),
    );

    await expect(fetchExternalUrl('https://example.com/stream-huge')).rejects.toThrow(
      'response too large',
    );
  });
});

describe('RESOURCE_MIME_TYPE constant from @modelcontextprotocol/ext-apps', () => {
  it('should match the expected MCP Apps MIME type', () => {
    // This test ensures that if @modelcontextprotocol/ext-apps changes RESOURCE_MIME_TYPE,
    // we'll be alerted to the breaking change
    expect(EXT_APPS_RESOURCE_MIME_TYPE).toBe('text/html;profile=mcp-app');
  });

  it('should be re-exported correctly from types.ts', () => {
    // Verify that our re-export matches the original
    expect(RESOURCE_MIME_TYPE).toBe(EXT_APPS_RESOURCE_MIME_TYPE);
  });
});


================================================
FILE: sdks/typescript/server/src/index.ts
================================================
import {
  type Base64BlobContent,
  type CreateUIResourceOptions,
  type HTMLTextContent,
  type MimeType,
  RESOURCE_MIME_TYPE,
} from './types.js';
import {
  extractOrigin,
  fetchExternalUrl,
  getAdditionalResourceProps,
  utf8ToBase64,
} from './utils.js';

export type UIResource = {
  type: 'resource';
  resource: HTMLTextContent | Base64BlobContent;
  annotations?: Record<string, unknown>;
  _meta?: Record<string, unknown>;
};

/**
 * Creates a UIResource.
 * This is the object that should be included in the 'content' array of a toolResult.
 *
 * For `externalUrl` content, fetches the URL's HTML and injects a `<base>` tag
 * so that relative paths resolve against the original URL.
 *
 * @param options Configuration for the interactive resource.
 * @returns a UIResource (async for externalUrl content which requires fetching)
 */
export async function createUIResource(options: CreateUIResourceOptions): Promise<UIResource> {
  let actualContentString: string;
  const mimeType: MimeType = RESOURCE_MIME_TYPE;

  if (!options.uri.startsWith('ui://')) {
    throw new Error("MCP-UI SDK: URI must start with 'ui://'.");
  }

  let externalOrigin: string | undefined;

  if (options.content.type === 'rawHtml') {
    actualContentString = options.content.htmlString;
    if (typeof actualContentString !== 'string') {
      throw new Error(
        "MCP-UI SDK: content.htmlString must be provided as a string when content.type is 'rawHtml'.",
      );
    }
  } else if (options.content.type === 'externalUrl') {
    const iframeUrl = options.content.iframeUrl;
    if (typeof iframeUrl !== 'string') {
      throw new Error(
        "MCP-UI SDK: content.iframeUrl must be provided as a string when content.type is 'externalUrl'.",
      );
    }
    actualContentString = await fetchExternalUrl(iframeUrl);
    externalOrigin = extractOrigin(iframeUrl);
  } else {
    // This case should ideally be prevented by TypeScript's discriminated union checks
    const exhaustiveCheckContent: never = options.content;
    throw new Error(`MCP-UI SDK: Invalid content.type specified: ${exhaustiveCheckContent}`);
  }

  const additionalProps = getAdditionalResourceProps(options);

  // For externalUrl, auto-populate _meta.csp.baseUriDomains with the origin
  // so the sandbox iframe's CSP base-uri directive allows the injected <base> tag.
  if (externalOrigin) {
    const meta = (additionalProps._meta ?? {}) as Record<string, unknown>;
    const existingCsp = (meta.csp ?? {}) as Record<string, unknown>;
    const existingDomains = (existingCsp.baseUriDomains ?? []) as string[];
    if (!existingDomains.includes(externalOrigin)) {
      meta.csp = { ...existingCsp, baseUriDomains: [...existingDomains, externalOrigin] };
    }
    additionalProps._meta = meta;
  }

  let resource: UIResource['resource'];

  switch (options.encoding) {
    case 'text':
      resource = {
        uri: options.uri,
        mimeType,
        text: actualContentString,
        ...additionalProps,
      };
      break;
    case 'blob':
      resource = {
        uri: options.uri,
        mimeType,
        blob: utf8ToBase64(actualContentString),
        ...additionalProps,
      };
      break;
    default: {
      const exhaustiveCheck: never = options.encoding;
      throw new Error(`MCP-UI SDK: Invalid encoding type: ${exhaustiveCheck}`);
    }
  }

  return {
    type: 'resource',
    resource: resource,
    ...(options.embeddedResourceProps ?? {}),
  };
}

export type {
  CreateUIResourceOptions,
  ResourceContentPayload,
} from './types.js';

// Re-export constants from @modelcontextprotocol/ext-apps via types.js
// This allows users to import everything they need from @mcp-ui/server
export { RESOURCE_URI_META_KEY, RESOURCE_MIME_TYPE } from './types.js';

// --- Experimental JSON-RPC helpers ---
// These enable guest UIs to send custom JSON-RPC requests to the host's
// onFallbackRequest handler on AppRenderer, using the existing PostMessageTransport.

let _experimentalRequestId = 0;

const DEFAULT_EXPERIMENTAL_REQUEST_TIMEOUT_MS = 30_000;

/**
 * Send an experimental JSON-RPC request to the host from inside a guest UI iframe.
 *
 * The host must have an `onFallbackRequest` handler registered on AppRenderer.
 * The request flows through PostMessageTransport and AppBridge's fallbackRequestHandler.
 *
 * @param method - JSON-RPC method name. Convention: use "x/<namespace>/<action>" for
 *   experimental methods (e.g., "x/clipboard/write"). Standard MCP methods not yet
 *   in the Apps spec (e.g., "sampling/createMessage") can use their canonical names.
 * @param params - Request parameters
 * @param options - Optional configuration
 * @param options.signal - AbortSignal to cancel the request
 * @param options.timeoutMs - Timeout in milliseconds (default: 30000). Set to 0 to disable.
 * @returns Promise that resolves with the host's JSON-RPC response result, or rejects
 *   with the JSON-RPC error
 *
 * @example
 * ```ts
 * const result = await sendExperimentalRequest('x/clipboard/write', { text: 'hello' });
 * ```
 */
export function sendExperimentalRequest(
  method: string,
  params?: Record<string, unknown>,
  options?: { signal?: AbortSignal; timeoutMs?: number },
): Promise<unknown> {
  if (window.parent === window) {
    return Promise.reject(
      new Error('sendExperimentalRequest must be called from within an iframe'),
    );
  }

  const id = ++_experimentalRequestId;
  const timeoutMs = options?.timeoutMs ?? DEFAULT_EXPERIMENTAL_REQUEST_TIMEOUT_MS;

  return new Promise((resolve, reject) => {
    let timeoutId: ReturnType<typeof setTimeout> | undefined;

    const cleanup = () => {
      window.removeEventListener('message', handler);
      if (timeoutId !== undefined) {
        clearTimeout(timeoutId);
      }
      options?.signal?.removeEventListener('abort', onAbort);
    };

    const handler = (event: MessageEvent) => {
      // Only accept responses from the parent window
      if (event.source !== window.parent) return;

      const data = event.data;
      if (data?.jsonrpc === '2.0' && data?.id === id) {
        cleanup();
        if (data.error) {
          reject(data.error);
        } else {
          resolve(data.result);
        }
      }
    };

    const onAbort = () => {
      cleanup();
      reject(new Error(`Experimental request "${method}" was aborted`));
    };

    if (options?.signal?.aborted) {
      reject(new Error(`Experimental request "${method}" was aborted`));
      return;
    }

    options?.signal?.addEventListener('abort', onAbort);
    window.addEventListener('message', handler);

    if (timeoutMs > 0) {
      timeoutId = setTimeout(() => {
        cleanup();
        reject(new Error(`Experimental request "${method}" timed out after ${timeoutMs}ms`));
      }, timeoutMs);
    }

    window.parent.postMessage(
      {
        jsonrpc: '2.0',
        id,
        method,
        ...(params !== undefined && { params }),
      },
      '*',
    );
  });
}


================================================
FILE: sdks/typescript/server/src/types.ts
================================================
import type { EmbeddedResource, Resource } from '@modelcontextprotocol/sdk/types.js';

// Re-export constants from the official ext-apps SDK for convenience
// This ensures we stay in sync with the MCP Apps specification
export { RESOURCE_URI_META_KEY, RESOURCE_MIME_TYPE } from '@modelcontextprotocol/ext-apps';

// Primary identifier for the resource. Starts with ui://`
export type URI = `ui://${string}`;

// text/html;profile=mcp-app is the MCP Apps standard MIME type
export type MimeType = 'text/html;profile=mcp-app';

export type HTMLTextContent = {
  uri: URI;
  mimeType: MimeType;
  text: string; // HTML content or iframe URL
  blob?: never;
  _meta?: Record<string, unknown>;
};

export type Base64BlobContent = {
  uri: URI;
  mimeType: MimeType;
  blob: string; // Base64 encoded HTML content or iframe URL
  text?: never;
  _meta?: Record<string, unknown>;
};

export type ResourceContentPayload =
  | { type: 'rawHtml'; htmlString: string }
  | { type: 'externalUrl'; iframeUrl: string };

export interface CreateUIResourceOptions {
  uri: URI;
  content: ResourceContentPayload;
  encoding: 'text' | 'blob';
  // specific mcp-ui metadata
  uiMetadata?: UIResourceMetadata;
  // additional metadata to be passed on _meta
  metadata?: Record<string, unknown>;
  // additional resource props to be passed on the resource itself
  resourceProps?: UIResourceProps;
  // additional resource props to be passed on the top-level embedded resource (i.e. annotations)
  embeddedResourceProps?: EmbeddedUIResourceProps;
}

export type UIResourceProps = Omit<Partial<Resource>, 'uri' | 'mimeType'>;
export type EmbeddedUIResourceProps = Omit<Partial<EmbeddedResource>, 'resource' | 'type'>;

export const UIMetadataKey = {
  PREFERRED_FRAME_SIZE: 'preferred-frame-size',
  INITIAL_RENDER_DATA: 'initial-render-data',
} as const;

export const UI_METADATA_PREFIX = 'mcpui.dev/ui-';

export type UIResourceMetadata = {
  [UIMetadataKey.PREFERRED_FRAME_SIZE]?: [string, string];
  [UIMetadataKey.INITIAL_RENDER_DATA]?: Record<string, unknown>;
};


================================================
FILE: sdks/typescript/server/src/utils.ts
================================================
import type { CreateUIResourceOptions, UIResourceProps } from './types.js';
import { UI_METADATA_PREFIX } from './types.js';

/** Maximum response body size in bytes (10 MB). */
const MAX_RESPONSE_BYTES = 10 * 1024 * 1024;

/** Default fetch timeout in milliseconds (30 seconds). */
const FETCH_TIMEOUT_MS = 30_000;

/** Hostnames that are always blocked to prevent SSRF. */
const BLOCKED_HOSTNAMES = new Set([
  'localhost',
  '127.0.0.1',
  '0.0.0.0',
  '[::1]',
  '[::]',
]);

/**
 * Returns true if the hostname belongs to a private/reserved IPv4 range.
 * Checks 10.x.x.x, 172.16-31.x.x, 192.168.x.x, and 169.254.x.x (link-local).
 */
function isPrivateIPv4(hostname: string): boolean {
  const parts = hostname.split('.');
  if (parts.length !== 4) return false;
  const nums = parts.map(Number);
  if (nums.some((n) => isNaN(n) || n < 0 || n > 255)) return false;

  const [a, b] = nums;
  // 10.0.0.0/8
  if (a === 10) return true;
  // 172.16.0.0/12
  if (a === 172 && b >= 16 && b <= 31) return true;
  // 192.168.0.0/16
  if (a === 192 && b === 168) return true;
  // 169.254.0.0/16 (link-local)
  if (a === 169 && b === 254) return true;

  return false;
}

/**
 * Validates that a URL is safe for server-side fetching.
 * Restricts to http/https and blocks private/reserved network addresses.
 *
 * @throws Error if the URL is invalid or targets a restricted address.
 */
export function validateExternalUrl(url: string): URL {
  let parsed: URL;
  try {
    parsed = new URL(url);
  } catch {
    throw new Error(`MCP-UI SDK: Invalid external URL: "${url}"`);
  }

  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
    throw new Error(
      `MCP-UI SDK: External URL must use http or https protocol, got "${parsed.protocol}" in "${url}"`,
    );
  }

  const hostname = parsed.hostname.toLowerCase();

  if (BLOCKED_HOSTNAMES.has(hostname)) {
    throw new Error(
      `MCP-UI SDK: External URL must not target localhost or loopback addresses: "${url}"`,
    );
  }

  if (isPrivateIPv4(hostname)) {
    throw new Error(
      `MCP-UI SDK: External URL must not target private network addresses: "${url}"`,
    );
  }

  return parsed;
}

/**
 * Fetches the HTML content from an external URL and injects a `<base>` tag
 * so that relative paths (CSS, JS, images, etc.) resolve against the original URL.
 *
 * Includes SSRF protections (protocol/host validation), a timeout, and a
 * response size limit.
 *
 * @param url The external URL to fetch.
 * @returns The fetched HTML with a `<base>` tag injected.
 */
export async function fetchExternalUrl(url: string): Promise<string> {
  const parsed = validateExternalUrl(url);

  const controller = new AbortController();
  const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);

  try {
    const response = await fetch(parsed.href, {
      signal: controller.signal,
      redirect: 'follow',
    });

    if (!response.ok) {
      throw new Error(
        `MCP-UI SDK: Failed to fetch external URL "${url}": ${response.status} ${response.statusText}`,
      );
    }

    const contentLength = response.headers.get('content-length');
    if (contentLength && parseInt(contentLength, 10) > MAX_RESPONSE_BYTES) {
      throw new Error(
        `MCP-UI SDK: External URL response too large (${contentLength} bytes, max ${MAX_RESPONSE_BYTES}): "${url}"`,
      );
    }

    // Read body in chunks to enforce size limit even without content-length
    const reader = response.body?.getReader();
    if (!reader) {
      throw new Error(`MCP-UI SDK: Unable to read response body from "${url}"`);
    }

    const decoder = new TextDecoder();
    let html = '';
    let totalBytes = 0;

    for (;;) {
      const { done, value } = await reader.read();
      if (done) break;
      totalBytes += value.byteLength;
      if (totalBytes > MAX_RESPONSE_BYTES) {
        reader.cancel();
        throw new Error(
          `MCP-UI SDK: External URL response too large (exceeded ${MAX_RESPONSE_BYTES} bytes): "${url}"`,
        );
      }
      html += decoder.decode(value, { stream: true });
    }
    html += decoder.decode(); // flush remaining

    return injectBaseTag(html, url);
  } finally {
    clearTimeout(timeoutId);
  }
}

/**
 * Injects a `<base href="...">` tag into HTML so relative paths resolve against
 * the given URL. If the HTML already contains a `<base` tag, it is left as-is.
 */
export function injectBaseTag(html: string, url: string): string {
  // Don't add <base> if one already exists
  if (/<base\s/i.test(html)) {
    return html;
  }

  const baseTag = `<base href="${escapeHtmlAttr(url)}">`;

  // Inject after <head> or <head ...> if present
  const headMatch = html.match(/<head(\s[^>]*)?>/i);
  if (headMatch) {
    const insertPos = headMatch.index! + headMatch[0].length;
    return html.slice(0, insertPos) + baseTag + html.slice(insertPos);
  }

  // No <head> tag — prepend
  return baseTag + html;
}

function escapeHtmlAttr(str: string): string {
  return str.replace(/&/g, '&amp;').replace(/"/g, '&quot;');
}

/**
 * Extracts the origin (scheme + host) from a URL string.
 * Returns undefined if the URL is invalid.
 */
export function extractOrigin(url: string): string | undefined {
  try {
    return new URL(url).origin;
  } catch {
    return undefined;
  }
}

export function getAdditionalResourceProps(
  resourceOptions: Partial<CreateUIResourceOptions>,
): UIResourceProps {
  const additionalResourceProps = { ...(resourceOptions.resourceProps ?? {}) } as UIResourceProps;

  // prefix ui specific metadata with the prefix to be recognized by the client
  if (resourceOptions.uiMetadata || resourceOptions.metadata) {
    const uiPrefixedMetadata = Object.fromEntries(
      Object.entries(resourceOptions.uiMetadata ?? {}).map(([key, value]) => [
        `${UI_METADATA_PREFIX}${key}`,
        value,
      ]),
    );
    // allow user defined _meta to override ui metadata
    additionalResourceProps._meta = {
      ...uiPrefixedMetadata,
      ...(resourceOptions.metadata ?? {}),
      ...(additionalResourceProps._meta ?? {}),
    };
  }

  return additionalResourceProps;
}

/**
 * Robustly encodes a UTF-8 string to Base64.
 * Uses Node.js Buffer if available, otherwise TextEncoder and btoa.
 * @param str The string to encode.
 * @returns Base64 encoded string.
 */
export function utf8ToBase64(str: string): string {
  if (typeof Buffer !== 'undefined') {
    return Buffer.from(str, 'utf-8').toString('base64');
  } else if (typeof TextEncoder !== 'undefined' && typeof btoa !== 'undefined') {
    const encoder = new TextEncoder();
    const uint8Array = encoder.encode(str);
    // Efficiently convert Uint8Array to binary string, handling large arrays in chunks
    let binaryString = '';
    // 8192 is a common chunk size used in JavaScript for performance reasons.
    // It tends to align well with internal buffer sizes and memory page sizes,
    // and it's small enough to avoid stack overflow errors with String.fromCharCode.
    const CHUNK_SIZE = 8192;
    for (let i = 0; i < uint8Array.length; i += CHUNK_SIZE) {
      binaryString += String.fromCharCode(...uint8Array.slice(i, i + CHUNK_SIZE));
    }
    return btoa(binaryString);
  } else {
    console.warn(
      'MCP-UI SDK: Buffer API and TextEncoder/btoa not available. Base64 encoding might not be UTF-8 safe.',
    );
    try {
      return btoa(str);
    } catch (_e) {
      throw new Error(
        'MCP-UI SDK: Suitable UTF-8 to Base64 encoding method not found, and fallback btoa failed.',
      );
    }
  }
}


================================================
FILE: sdks/typescript/server/tsconfig.json
================================================
{
  "extends": "../../../tsconfig.base.json",
  "compilerOptions": {
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist", "src/__tests__"]
}


================================================
FILE: sdks/typescript/server/vite.config.ts
================================================
import { defineConfig } from 'vite';
import dts from 'vite-plugin-dts';
import path from 'path';
import react from '@vitejs/plugin-react-swc';

export default defineConfig({
  plugins: [
    react(),
    dts({
      insertTypesEntry: false,
      tsconfigPath: path.resolve(__dirname, 'tsconfig.json'),
      exclude: ['**/__tests__/**', '**/*.test.ts', '**/*.spec.ts'],
    }),
  ],
  build: {
    lib: {
      entry: path.resolve(__dirname, 'src/index.ts'),
      name: 'McpUiServer',
      formats: ['es', 'cjs'], // cjs for Node compatibility
      fileName: (format) => `index.${format === 'es' ? 'mjs' : 'cjs'}`,
    },
    target: 'node18',
    sourcemap: true,
  },
});


================================================
FILE: sdks/typescript/server/vitest.config.ts
================================================
import { defineConfig } from 'vitest/config';
import { fileURLToPath } from 'url';
import { dirname, join } from 'path';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

export default defineConfig({
  test: {
    globals: true,
    environment: 'node',
    globalSetup: join(__dirname, '../../../vitest.global-setup.ts'),
  },
});


================================================
FILE: sdks/typescript/shared/package.json
================================================
{
  "name": "@mcp-ui/shared",
  "version": "0.1.0",
  "type": "module",
  "main": "./dist/index.js",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "files": [
    "dist"
  ],
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "test": "vitest run",
    "test:watch": "vitest watch",
    "lint": "eslint ."
  },
  "devDependencies": {
    "typescript": "^5.0.0",
    "vite": "^5.0.0",
    "vite-plugin-dts": "^3.6.0",
    "vitest": "^1.0.0"
  },
  "publishConfig": {
    "access": "public"
  }
}


================================================
FILE: sdks/typescript/shared/src/index.ts
================================================


================================================
FILE: sdks/typescript/shared/tsconfig.json
================================================
{
  "extends": "../../../tsconfig.base.json",
  "compilerOptions": {
    "baseUrl": "src",
    "paths": {
      "@/*": ["./src/"]
    }
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist", "src/__tests__"]
}


================================================
FILE: sdks/typescript/shared/vite.config.ts
================================================
import { defineConfig } from 'vite';
import dts from 'vite-plugin-dts';
import react from '@vitejs/plugin-react-swc';
import path from 'path';

export default defineConfig({
  plugins: [
    react(),
    dts({
      insertTypesEntry: true,
      tsconfigPath: path.resolve(__dirname, 'tsconfig.json'),
    }),
  ],
  build: {
    lib: {
      entry: path.resolve(__dirname, 'src/index.ts'),
      name: 'McpUiShared',
      formats: ['es', 'umd'], // UMD for broader compatibility if needed, es for modern
      fileName: (format) =>
        `index.${format === 'es' ? 'mjs' : format === 'umd' ? 'js' : format + '.js'}`,
    },
    sourcemap: true,
    // Minify options if needed, default is esbuild which is fast
    // minify: 'terser',
    // terserOptions: { ... }
  },
});


================================================
FILE: tsconfig.base.json
================================================
{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "declarationMap": true,
    "module": "ESNext",
    "moduleResolution": "bundler",
    "target": "ES2022",
    "sourceMap": true,
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "allowSyntheticDefaultImports": true,
    "resolveJsonModule": true,
    "noEmit": true,
    "isolatedModules": true,
    "types": ["vitest/globals"]
  }
}


================================================
FILE: vitest.config.ts
================================================
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    globals: true, // Use global APIs (describe, it, expect)
    environment: 'jsdom', // Default environment, can be overridden per package/file
    setupFiles: './vitest.setup.ts',
    // include: ['sdks/typescript/*/src/**/__tests__/**/*.test.ts'],
    exclude: ['**/node_modules/**', '**/dist/**', '**/.pnpm-store/**'],
    coverage: {
      provider: 'v8',
      reporter: ['text', 'json', 'html'],
      reportsDirectory: './coverage',
      include: ['sdks/typescript/*/src/**/*.{ts,tsx}'],
      exclude: [
        'sdks/typescript/*/src/index.{ts,tsx}',
        'sdks/typescript/*/**/*.d.ts',
        'sdks/typescript/*/**/__tests__/**',
        'sdks/typescript/*/**/dist/**',
        'docs/src/**',
      ],
    },
  },
});


================================================
FILE: vitest.setup.ts
================================================
import '@testing-library/jest-dom';