CopilotKit Generative UI MCP Framework

CopilotKit生成UI MCP框架


一个即插即用的框架，用于构建基于人工智能的生成用户界面 副驾驶套件, MCP应用程序，以及 开放路由.MCP服务器工具返回直接在基于浏览器的聊天界面中呈现的交互式HTML组件。

该项目包括一个带有CopilotKit的Next.js前端、一个带有示例UI生成工具的HTTP MCP服务器，以及为Claude Code预配置的9个MCP服务器集成。

建筑

Browser (localhost:3000)
    |
    |  User sends message in CopilotSidebar
    v
Next.js API Route (/api/copilotkit)
    |
    |  BuiltInAgent routes to OpenRouter (LLM)
    v
MCPAppsMiddleware
    |
    |  HTTP request to MCP server (localhost:3001/mcp)
    |  Tool returns data + _meta.ui/resourceUri reference
    v
CopilotKit Frontend
    |
    |  Fetches HTML resource from MCP server
    |  Renders interactive UI in sandboxed iframe
    v
User sees interactive dashboard in the chat sidebar

快速开始

1.克隆存储库

git clone https://github.com/Roentek/CopilotKit_Generative_UI_MCP_Framework.git
cd CopilotKit_Generative_UI_MCP_Framework

2.配置环境变量

cp .env.example .env

编辑 .env 并添加您的API密钥。您至少需要：

OPENAI_API_KEY=your-openrouter-api-key
OPENAI_BASE_URL=https://openrouter.ai/api/v1

3.安装依赖项并运行

npm run setup       # Installs root + MCP server dependencies
npm run dev:all     # Starts Next.js (port 3000) + MCP server (port 3001)

打开 http://localhost:3000 并尝试询问助手： “显示工作流状态”

先决条件

• Node.js 18+ 和 npm
• OpenRouter API密钥 (在这里买一个)--或任何与OpenAI兼容的LLM提供者
• Claude 代码命令行工具 （可选，用于使用预配置的MCP服务器）

项目结构

CopilotKit_Generative_UI_MCP_Framework/
├── .claude/                           # Claude Code settings
│   ├── settings.json                  #   Enabled plugins
│   └── settings.local.json            #   Permissions + MCP server config
├── mcp-server/                        # HTTP MCP server for generative UI
│   ├── package.json                   #   Server dependencies
│   ├── tsconfig.json                  #   TypeScript config
│   └── src/
│       ├── server.ts                  #   Express + StreamableHTTPServerTransport
│       └── apps/
│           └── workflow-dashboard.html #   Sample interactive HTML app
├── src/
│   └── app/
│       ├── layout.tsx                 # CopilotKit provider wrapper
│       ├── page.tsx                   # Dashboard + CopilotSidebar
│       ├── globals.css                # Tailwind base styles
│       └── api/
│           └── copilotkit/
│               └── route.ts           # CopilotRuntime + MCPAppsMiddleware
├── .env.example                       # Environment variable template
├── .mcp.json                          # 9 pre-configured MCP servers
├── CLAUDE.md                          # AI agent instructions
├── LICENSE                            # MIT License
├── package.json                       # Next.js + CopilotKit dependencies
└── README.md                          # This file

环境变量

预配置的MCP服务器集成

这9台MCP服务器配置在 .mcp.json 与Claude Code CLI/IDE一起使用：

可用的NPM脚本

如何添加新的MCP应用程序

MCP Apps模式允许工具返回交互式UI。以下是如何添加一个新的：

步骤1：创建HTML应用程序

在中创建一个自包含的HTML文件 mcp-server/src/apps/。它必须包含所有CSS和JavaScript内联（没有外部依赖关系）。该应用程序通过以下方式接收数据 window.addEventListener("message", ...).

  /* Your styles here */

  

  
    window.addEventListener("message", (event) => {
      const data = typeof event.data === "string"
        ? JSON.parse(event.data)
        : event.data;
      // Render your UI with the data
    });
  

步骤2：在中注册工具 mcp-server/src/server.ts

server.tool(
  "my-tool-name",
  "Description of what the tool does",
  { param1: z.string().describe("Parameter description") },
  async ({ param1 }) => {
    const data = { /* your data */ };
    return {
      content: [{ type: "text" as const, text: JSON.stringify(data) }],
      _meta: { "ui/resourceUri": "ui://generative-ui/my-app" },
    };
  }
);

步骤3：注册资源

server.resource(
  "my-app",
  "ui://generative-ui/my-app",
  { description: "My interactive app", mimeType: "text/html+mcp" },
  async (uri) => ({
    contents: [{
      uri: uri.href,
      mimeType: "text/html+mcp",
      text: loadApp("my-app.html"),
    }],
  })
);

步骤4：重新启动MCP服务器

npm run mcp:dev

OpenRouter配置

该框架使用 开放路由 作为LLM提供商。CopilotKit的运行时在内部使用OpenAI SDK，因此通过设置 OPENAI_BASE_URL 到 https://openrouter.ai/api/v1 和 OPENAI_API_KEY 对于您的OpenRouter密钥，所有LLM调用都透明地通过OpenRouter路由。

选择模型

默认模型为 openai/gpt-4o。要使用其他型号，请设置 OPENROUTER_MODEL 您的环境变量 .env 文件：

OPENROUTER_MODEL=anthropic/claude-sonnet-4  # Any OpenRouter model

热门选项：

• openai/gpt-4o -OpenAI GPT-4 Omni（默认，平衡性能）
• anthropic/claude-sonnet-4 -克劳德·十四行诗4（出色的推理能力）
• anthropic/claude-opus-4 -克劳德作品4（最有能力）
• google/gemini-2.0-flash-thinking-exp:free -谷歌Gemini 2.0 Flash（免费版）
• meta-llama/llama-3.3-70b-instruct -Llama 3.3 70B
• deepseek/deepseek-chat -DeepSeek V3（经济高效）

查看完整列表 OpenRouter型号.

故障排除

MCP服务器没有响应： 检查MCP服务器是否在端口3001上运行。跑 npm run mcp:dev 单独查看其日志。访问 http://localhost:3001/health 以验证。

CopilotSidebar显示错误： 确保 OPENAI_API_KEY 和 OPENAI_BASE_URL 设置在您的 .env 文件。API路由位于 /api/copilotkit 需要这些与OpenRouter通信。

MCPAppsMiddle的TypeScript类型错误包括： 这是一个已知的重复问题 @ag-ui/client 包装。这 route.ts 文件用途 as any 键入断言来解决这个问题。跑 npm dedupe 如果您在安装新软件包后发现问题。

端口冲突： Next.js在端口3000上运行，MCP服务器在端口3001上运行。如果这些端口正在使用中，请设置 PORT Next.js通过 next dev -p 3002 和 MCP_PORT MCP服务器的环境变量。

资源

• CopilotKit文档
• CopilotKit MCP应用程序规范
• MCP应用程序演示库
• 生成UI指南
• OpenRouter文档
• MCP TypeScript SDK

许可证

麻省理工学院许可证-版权所有（c）2026 Roentek Designs

看 许可证 了解详情。