AI导哈

待办事项管理工具

一个基于MCP协议的待办事项管理工具，提供创建、列表、更新和删除待办事项的功能，支持自然语言交互和实时UI更新。

  • by Phonganbundau
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 Phonganbundau/mcp

使用说明

MCP所有演示

最小模型上下文协议栈由以下部分组成：

  • mcp服务器 --Spring Boot WebSocket服务器公开了4个必需的MCP todo工具
  • mcp用户界面 --Next.js UI通过MCP通道调用工具
  • 带Gemini的MCP测试客户端 -此测试客户端模拟 精确经验 在真实的LLM客户端（如Claude Desktop、Cursor等）中使用MCP-UI。它使用谷歌的Gemini AI和原生函数调用，与您的MCP服务器自然交互。

1.要求

组件 要求
服务器 Java 17+，Maven 3.9+
客户端 Node.js 18+（用20.19.0测试），npm 9+

2.目录布局

server/  # Java Spring Boot MCP server
client/  # Next.js UI client

3.运行MCP服务器

cd server
mvn spring-boot:run

这将在以下位置启动与MCP兼容的WebSocket端点 ws://localhost:8080/mcp 它公开了以下工具：

工具名称 描述 输入模式（摘要） 输出
todo_create 创建待办事项 { title: string, completed?: boolean } { todo }
todo_list 列出所有 {} { todos: Todo[] }
todo_update 更新待办事项 { id: string, title?: string, completed?: boolean } { todo }
todo_delete 删除待办事项 { id: string } { id, deleted: true }

所有数据都保存在内存中(TodoService)，因此重新启动服务器会重置列表。

4.运行MCP UI客户端

cd client
npm install
npm run dev

带Gemini的MCP测试客户端

此测试客户端模拟 精确经验 在真实的LLM客户端（如Claude Desktop、Cursor等）中使用MCP-UI。它使用谷歌的Gemini AI和原生函数调用，与您的MCP服务器自然交互。

🎯 这表明了什么

  1. 自然语言交互：用户用简单的英语与Gemini聊天
  2. 自动工具调用：Gemini分析消息并调用相应的MCP工具
  3. 交互式UI渲染：服务器返回MCP-UI资源→ 在聊天中内联呈现
  4. 无缝更新：用户与UI交互→ 动作回流→ 工具再次调用→ UI实时更新

这是 精确地 Claude Desktop或Cursor将如何处理MCP-UI资源！

🚀 快速开始

1.安装依赖项

cd test-client
npm install

2.配置环境

创建一个 .env 文件在 test-client 目录：

GEMINI_API_KEY=your-gemini-api-key-here
MCP_WS_URL=ws://localhost:8080/mcp

获取Gemini API密钥：

  1. 首选https://aistudio.google.com/app/apikey
  2. 单击“创建API密钥”
  3. 复制密钥并将其粘贴到您的 .env 文件

3.启动MCP服务器

在单独的终端中：

cd server
mvn spring-boot:run

等到你看到： Started McpServerApplication

4.启动测试客户端

cd test-client
npm run dev

您应该看到：

🚀 Starting MCP Chat Client with Gemini...
📡 Connecting to MCP server at ws://localhost:8080/mcp...
✅ Connected! Found 4 tools:
   • todo_create: Create a todo item
   • todo_list: List all todo items
   • todo_update: Update a todo item
   • todo_delete: Delete a todo item

🌐 Chat UI is ready!

   👉 Open: http://localhost:3003

5.打开聊天界面

打开http://localhost:3003在浏览器中开始聊天！

💬 对话示例

尝试以下自然语言提示：

  • “显示我的待办事项” → 双子座来电 todo_list → 交互式仪表板显示为内联
  • “添加购买杂货的新待办事项” → 双子座来电 todo_create → 仪表板更新新待办事项
  • “将第一个待办事项标记为已完成” → 双子座来电 todo_update → UI立即刷新
  • “删除id为abc-123的待办事项” → 双子座来电 todo_delete → Todo消失了

🔄 运作原理

  1. 用户键入消息 自然语言
  2. Gemini分析 使用其本机函数调用的消息
  3. 双子座决定 根据工具的描述调用哪个MCP工具
  4. 工具已执行 通过WebSocket连接到您的Spring Boot MCP服务器
  5. 服务器响应 与：
    • JSON数据（待办事项列表、创建的待办事项等）
    • MCP-UI资源 （交互式HTML仪表板）
  6. UI内联渲染 在聊天对话中使用iframe
  7. 用户交互 在渲染的UI中使用表单/按钮
  8. 行动回流 通过聊天→ Gemini再次调用工具→ UI更新

🎨 你会看到什么

  • 聊天界面 类似于Claude/ChatGPT
  • 消息 从你和助理
  • 交互式UI卡 当工具返回MCP-UI资源时显示为内联
  • 实时更新 当您与仪表板交互时

🛠️ 建筑

  • 前端：基于React的聊天UI（作为静态HTML）
  • 后端：Node.js服务器：
    • 通过WebSocket连接到MCP服务器
    • 将Gemini AI与函数调用集成
    • 处理聊天消息和工具执行
    • 返回用于内联渲染的MCP-UI资源

🐛 故障排除

“无法连接到MCP服务器”

  • 确保Spring Boot服务器在端口8080上运行
  • 检查一下 MCP_WS_URL 在 .env 匹配您的服务器URL

“需要GEMINI_API_KEY环境变量”

  • 确保您创建了 .env 文件
  • 验证API密钥是否正确（无额外空格）

UI不呈现

  • 检查浏览器控制台是否有错误
  • 验证MCP服务器是否正在返回UI资源（检查服务器日志）

📚 后续步骤

在本地测试后，您可以：

  • 将MCP服务器部署到云提供商
  • 将其用于真正的LLM客户端，如Claude Desktop或Cursor
  • 添加更复杂的UI交互
  • 使用其他工具进行扩展

5.快速测试集成

  1. 启动Spring Boot服务器。
  2. 在第二个终端中启动Next.js开发服务器。
  3. 负载 http://localhost:3000，等待连接指示器显示“已连接”。
  4. 从iframe内的MCP-UI仪表板或通过回退刷新按钮创建/更新/删除待办事项——主机只需将操作中继回MCP服务器。

6.故障排除

  • Cannot find module '.next/server/middleware-manifest.json' –删除 .next 文件夹并重新运行 npm run dev 强制进行清洁建设。
  • WebSocket未连接 –确保服务器正在运行，客户端也在运行 NEXT_PUBLIC_MCP_WS_URL 与服务器URL匹配。
  • MCP-UI iframe保持空白 –确认Spring服务器正在返回 ui 字段（参见 McpWebSocketHandler)并且您的浏览器控制台没有显示CSP错误。手册 todo_list 工具调用应始终刷新UI资源。

相关 MCP