MCP应用程序工作人员模板
一个生产就绪的模板，用于在Cloudflare Workers上使用交互式UI小部件构建模型上下文协议（MCP）服务器。此模板演示如何创建MCP工具，使用React、Tailwind CSS和MCP扩展应用程序API返回丰富的交互式HTML小部件。
概述
此模板为构建MCP服务器提供了完整的基础，这些服务器公开了：
- MCP工具：MCP客户端可以调用的服务器端函数
- UI控件：可在MCP兼容主机中呈现的交互式HTML小部件
- 资源处理程序：使用适当的CSP配置为小部件HTML提供服务的动态资源端点
示例实现包括一个动画搜索工具，该工具查询Jikan API（MyAnimeList）并在一个漂亮的交互式小部件中显示结果。
特性
- ✅ MCP服务器实现：使用完整的MCP服务器
@modelcontextprotocol/sdk - ✅ 交互式小部件：具有Tailwind CSS样式的基于React的UI小部件
- ✅ Cloudflare员工：部署到Cloudflare的边缘网络以获得全球性能
- ✅ 资产管理：为小部件HTML文件提供服务的内置资产
- ✅ 类型安全：Cloudflare Workers类型生成完全支持TypeScript
- ✅ 现代建筑流水线：基于Vite的单文件输出构建系统
- ✅ CSP配置：小部件安全的内容安全策略支持
- ✅ MCP扩展应用程序：与集成
@modelcontextprotocol/ext-apps用于小部件通信
先决条件
- Node.js 18+和npm
- Cloudflare帐户 （用于部署）
- 牧马人CLI （通过npm安装）
安装
- 克隆仓库:
git clone https://github.com/MCPJam/mcp-app-workers-template.git
cd mcp-app-workers-template- 安装依赖项:
npm install- 生成Cloudflare Workers类型:
npm run cf-typegen这将为Cloudflare Workers绑定生成TypeScript类型。这些类型用于 server/index.ts 当使用实例化Hono时 CloudflareBindings.
发展
地方发展
- 构建小部件 （运行开发服务器之前需要）：
npm run build- 启动开发服务器:
npm run dev这将启动Wrangler的开发服务器。MCP端点将在 http://localhost:8787/mcp.
构建小部件
小部件使用Vite构建，并作为单个文件HTML包输出：
npm run build构建过程：
- 编译React/TypeScript组件
- 将所有依赖项捆绑到一个文件中
- 应用顺风CSS
- 输出到
web/dist/widgets/
要构建特定的小部件，请设置 INPUT 环境变量：
INPUT=widgets/anime-detail-widget.html npm run build部署
部署到Cloudflare Workers
- 与Wrangler进行身份验证 （仅限第一次）：
npx wrangler login- 构建小部件:
npm run build- 部署:
npm run deploy这将：
- 构建小部件 - 将Worker部署到Cloudflare - 将小部件资产上传到Worker的assets绑定
- 获取您的部署URL:
部署后，Wrangler将输出您的Worker URL。您的MCP端点将位于：
https://..workers.dev/mcp环境配置
该项目使用 wrangler.jsonc 用于配置。关键设置：
- 名字：工人名称（将其更改为您的项目名称）
- 主要的：入口点(
server/index.ts) - 资产：包含内置小部件的目录(
./web/dist/widgets) - 兼容性_日期：Cloudflare Workers兼容性日期
项目结构
mcp-app-workers-template/
├── server/ # Server-side code
│ ├── index.ts # Hono router and MCP endpoint handler
│ └── mcp.ts # MCP server implementation
├── web/ # Frontend/widget code
│ ├── components/ # React components
│ │ ├── anime-card.tsx # Anime display component
│ │ └── ui/ # UI component library
│ ├── widgets/ # Widget entry points
│ │ ├── anime-detail-widget.html
│ │ └── anime-widget.tsx
│ ├── lib/ # Utilities
│ └── index.css # Global styles
├── wrangler.jsonc # Cloudflare Workers configuration
├── vite.config.ts # Vite build configuration
├── tsconfig.json # TypeScript configuration
└── package.json # Dependencies and scripts运作原理
MCP服务器设置
MCP服务器(server/mcp.ts)寄存器：
- 工具：MCP客户端可以调用的服务器端函数
- 例子： get-anime-detail -搜索动漫并返回结构化数据
- 资源：为小部件HTML提供服务的动态端点
- 例子： ui://widget/anime-detail-widget.html -提供动漫小部件HTML
小部件通信
小工具使用MCP扩展应用程序API(@modelcontextprotocol/ext-apps)致：
- 接收工具输入：倾听工具何时被调用
- 接收工具结果：从工具执行中获取结构化数据
- 发送命令：请求主机执行操作（例如，打开链接）
小部件注册
小部件已在中注册 server/mcp.ts 使用 registerWidget():
registerWidget(server, assets, {
name: "anime-detail-widget",
htmlPath: "/anime-detail-widget.html",
resourceUri: "ui://widget/anime-detail-widget.html",
descripition: "Interactive anime detail widget UI",
resourceDomains: ["https://cdn.myanimelist.net/"], // CSP allowed domains
});工具到小部件链接
工具可以使用指定要显示的小部件 _meta:
server.registerTool(
"get-anime-detail",
{
// ... tool config
_meta: {
"ui/resourceUri": "ui://widget/anime-detail-widget.html",
},
},
// ... handler
);添加新小部件
- 创建小部件HTML入口点 在
web/widgets/:
My Widget
- 创建小部件React组件 在
web/widgets/:
import { useApp } from "@modelcontextprotocol/ext-apps/react";
// ... implement widget logic- 构建小部件:
INPUT=widgets/my-widget.html npm run build- 注册小部件 在
server/mcp.ts:
registerWidget(server, assets, {
name: "my-widget",
htmlPath: "/my-widget.html",
resourceUri: "ui://widget/my-widget.html",
descripition: "My widget description",
resourceDomains: ["https://example.com"], // Optional: CSP domains
});- 将工具链接到小部件 （可选）：
server.registerTool(
"my-tool",
{
// ... config
_meta: {
"ui/resourceUri": "ui://widget/my-widget.html",
},
},
handler,
);配置
小部件配置选项
注册小部件时，您可以配置：
- 名字：唯一小部件标识符
- htmlPath：ASSETS绑定中HTML文件的路径
- resourceUri：MCP资源URI（必须以开头
ui://widget/) - 描述：小部件描述
- connectDomains：CSP允许域用于fetch/XHR/Webocket
- resourceDomains：CSP允许图像、脚本等域。
- 领域：小部件的自定义域
- 偏好订购：小部件是否喜欢边框
CSP（内容安全策略）
小部件支持CSP配置以确保安全：
registerWidget(server, assets, {
// ...
connectDomains: ["https://api.example.com"], // For API calls
resourceDomains: ["https://cdn.example.com"], // For images/assets
});使用的技术
- 荣誉：Cloudflare Workers的快速web框架
- 模型上下文协议SDK：MCP服务器实现
- MCP扩展应用程序：小工具通信API
- 反应：小部件的UI框架
- 顺风CSS：实用程序优先的CSS框架
- 维特：构建工具和开发服务器
- TypeScript：类型安全的JavaScript
- Cloudflare员工：边缘计算平台
- 牧马人：Cloudflare Workers CLI
脚本
npm run dev-启动开发服务器npm run build-构建小部件（需要INPUT任何人）npm run deploy-部署到Cloudflare Workersnpm run cf-typegen-生成Cloudflare Workers TypeScript类型npm run format-使用Prettier格式化代码
故障排除
小部件未加载
- 确保构建了小部件：
npm run build - 检查HTML文件是否存在于
web/dist/widgets/ - 验证
htmlPath小部件注册与实际文件路径匹配
MCP连接问题
- 验证终结点URL是否正确：
https://your-worker.workers.dev/mcp - 检查Cloudflare Workers日志：
npx wrangler tail - 确保MCP客户端支持HTTP/SSE传输
类型错误
- 跑
npm run cf-typegen重新生成类型 - 确保
CloudflareBindings从生成的类型导入