AI导哈

生成式UI框架

一个基于CopilotKit和OpenRouter的即插即用框架，用于构建AI驱动的生成式用户界面。

  • by Roentek
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 Roentek/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

环境变量

变量 必填 描述
OPENAI_API_KEY 是 您的OpenRouter API密钥（由CopilotKit运行时使用）
OPENAI_BASE_URL 是 设置为 https://openrouter.ai/api/v1 适用于OpenRouter
OPENROUTER_MODEL 否 要使用的模型（默认为 openai/gpt-4o)-看 OpenRouter型号
MCP_SERVER_URL 无 MCP服务器URL（默认为 http://localhost:3001/mcp)
SUPABASE_API_PAT 否 取消MCP访问令牌
PINECONE_API_KEY 否 松果向量DB API键
APIFY_API_PAT 否 指定web抓取访问令牌
TAVILY_API_KEY 否 Tavilly搜索API密钥
VAPI_API_TOKEN 否 Vapi语音MCP服务器令牌
N8N_HOST_URL 无 n8n实例URL
N8N_API_KEY 没有 n8n API密钥
GOOGLE_USER_EMAIL 否 谷歌工作区电子邮件
GOOGLE_OAUTH_CLIENT_ID 否 谷歌OAuth客户端ID
GOOGLE_OAUTH_CLIENT_SECRET 否 谷歌OAuth客户端机密
OPENROUTER_API_KEY 否 MCP服务器集成的OpenRouter密钥

预配置的MCP服务器集成

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

服务器 用途 传输
n8n 工作流自动化 stdio
塔维利 网络搜索与研究
瓦皮 语音和呼叫API stdio
泽普 文档和内存 远程
松果 矢量数据库 stdio
Apify 网络抓取 stdio
Supabase 数据库操作 stdio
开放路由 LLM 路由
Google Workspace 谷歌服务

可用的NPM脚本

脚本 描述
npm run setup 安装所有依赖项（root+MCP服务器）
npm run dev:all 同时启动Next.js+MCP服务器
npm run dev 仅启动Next.js开发服务器
npm run mcp:dev 仅启动MCP服务器
npm run build 为生产环境构建Next.js
npm run start 启动Next.js生产服务器
npm run lint 运行ESLint

如何添加新的MCP应用程序

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

步骤1：创建HTML应用程序

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

<!-- mcp-server/src/apps/my-app.html -->
<!DOCTYPE html>
<html>
<head>
  <style>/* Your styles here */</style>
</head>
<body>
  <div id="app"></div>
  <script>
    window.addEventListener("message", (event) => {
      const data = typeof event.data === "string"
        ? JSON.parse(event.data)
        : event.data;
      // Render your UI with the data
    });
  </script>
</body>
</html>

步骤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服务器的环境变量。

资源

许可证

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

看 许可证 了解详情。

相关 MCP