MCP-UI 开源项目最佳实践教程

1. 项目介绍

MCP-UI 是一个基于 Model Context Protocol (MCP) 的开源项目，它为 MCP 服务器带来了交互式 Web 组件。通过该项目，可以直接从 MCP 服务器向客户端传递丰富的、动态的 UI 资源，并将其渲染在客户端上。MCP-UI 由两个包组成：@mcp-ui/server 和 @mcp-ui/client，分别用于在服务器端创建资源块和在客户端渲染这些资源块。

2. 项目快速启动

以下是一个简单的示例，展示如何在服务器端创建资源块，并在客户端渲染它们。

服务器端

首先，你需要安装 @mcp-ui/server 包。

npm install @mcp-ui/server
# 或者
pnpm add @mcp-ui/server
# 或者
yarn add @mcp-ui/server

然后，你可以使用以下代码来创建一个 HTML 资源块：

import { createHtmlResource } from '@mcp-ui/server';

// 创建一个内联 HTML 资源
const direct = createHtmlResource({
  uri: 'ui://greeting/1',
  content: {
    type: 'directHtml',
    htmlString: '<p>你好，MCP UI！</p>'
  },
  delivery: 'text'
});

// 创建一个外部 URL 资源
const external = createHtmlResource({
  uri: 'ui-app://widget/session-42',
  content: {
    type: 'externalUrl',
    iframeUrl: 'https://example.com/widget'
  },
  delivery: 'text'
});

客户端

在客户端，你需要安装 @mcp-ui/client 包。

npm install @mcp-ui/client
# 或者
pnpm add @mcp-ui/client
# 或者
yarn add @mcp-ui/client

接着，你可以使用以下代码来渲染 MCP 资源：

import React from 'react';
import { HtmlResource } from '@mcp-ui/client';

function App({ mcpResource }) {
  if (mcpResource.type === 'resource' && mcpResource.resource.mimeType === 'text/html') {
    return (
      <HtmlResource resource={mcpResource.resource} onUiAction={(tool, params) => {
        console.log('动作：', tool, params);
        return { status: 'ok' };
      }} />
    );
  }
  return <p>不支持的资源</p>;
}

3. 应用案例和最佳实践

在开发过程中，以下是一些最佳实践：

• 确保你的资源 URI 是唯一的，以便正确地缓存和路由。
• 对于简单的 HTML 内容，使用 directHtml 类型，对于大型或编码后的内容，使用 blob 类型。
• 使用 onUiAction 回调来处理 UI 组件发出的事件，从而与代理进行交互。

4. 典型生态项目

目前，MCP-UI 生态中包括以下项目：

• ui-inspector：一个用于检查本地已启用 MCP-UI 的服务器的工具。
• MCP-UI Chat：一个使用 MCP-UI 客户端构建的交互式聊天应用。
• HTTP Streaming 和 SSE：部署在 workers.dev 上的服务器端示例，用于演示 MCP-UI 的实时特性。

通过遵循这些最佳实践和案例，开发者可以更好地利用 MCP-UI 项目来创建丰富的交互式 UI。