MCP example project

带AI聊天功能的Todo应用

一个全栈待办事项应用程序，配备AI聊天界面，可通过自然语言帮助管理您的待办事项。该应用支持多种AI聊天模式，利用不同的模型和功能。

🚀 功能

全面管理

• 创建、读取、更新和删除待办事项
• 将所有项目标记为已完成/未完成
• 直接在行内编辑待办事项文本
• 使用JSON文件后端的持久化存储
• 所有ID显示，便于参考

AI聊天界面

• 简单聊天 | gpt-oss - 基础对话式人工智能
• 与历史对话 | gpt-oss - 保持对话上下文
• 函数上下文 | phi4-reasoning:latest - 具有访问待办事项功能的权限
• 具有功能上下文的代理式Todos（或：带功能上下文的代理式待办事项） | phi4-reasoning:latest - 能够自主调用待办事项函数
• 带有工具的代理（或：具备工具的代理实体） | gpt-oss - 使用Ollama的原生工具调用功能
• 带有MCP的代理性（或：具备MCP的代理能力） | gpt-oss - 使用模型上下文协议进行工具集成
• 带有生成代码的代理（或：具备生成代码能力的代理） | llama3:8b - 生成并执行JavaScript代码

附加功能

• 通过复选框切换聊天可见性
• 停止/中止正在运行的人工智能请求
• 清除聊天记录

🛠️ 技术栈

前端

• 使用 JSX 的 React 18
• Vite 用于构建工具和开发服务器
• 使用内联样式的现代CSS
• 用于HTTP请求的Fetch API

后端

• 使用 Express 的 Node.js
• 使用 TypeScript 确保类型安全
• 用于本地AI模型推理的Ollama
• 模型上下文协议（MCP）集成
• JSON文件持久化
• 为本地开发启用CORS

人工智能模型

• GPT-OSS - 通用聊天和工具调用
• phi4-reasoning:latest（可译为）“phi4推理：最新版” - 高级推理和函数调用
• llama3:8b（可译为“Llama3 80亿参数版本”或根据具体语境简化为“Llama3 8B”） - 代码生成能力

📋 前提条件

在开始之前，请确保已安装以下内容：

• Node.js (v16 或更高版本) - 在此下载
• npm （随 Node.js 一起提供）或 纱线
• Ollama（注：这是一个专有名词，通常不直接翻译，但根据语境可理解为“奥拉玛”或保持原样，具体取决于上下文或品牌命名的惯例。） - 官方网站

Ollama 安装设置

1. 按照以下步骤安装Ollama 官方网站
2. 拉取所需模型：

   ollama pull gpt-oss
   ollama pull phi4-reasoning:latest
   ollama pull llama3:8b

🚀 快速入门

1. 克隆仓库

git clone 
cd todo_app_ai

2. 后端设置

导航至后端目录并安装依赖项：

cd backend
npm install

后端依赖项

后端包含以下关键依赖项：

• express - 网络框架
• ollama - 人工智能模型集成
• zod - 模式验证
• @modelcontextprotocol/sdk - MCP集成
• isolated-vm - 代码执行沙盒
• chrome-devtools-mcp - Chrome DevTools MCP 服务器

启动后端服务器

npm run dev

后端将在 http://localhost:3001

可用的后端脚本：

• npm run dev - 启动带有热重载功能的开发服务器
• npm run build - 将TypeScript编译为JavaScript
• npm run mcp - 启动MCP服务器
• npm run mcp:inspect - 使用检查器检查MCP服务器
• npm run mcp:client - 启动MCP客户端

3. 前端设置

打开一个新的终端并导航到前端目录：

cd frontend
npm install

前端依赖项

前端包括：

• react & react-dom - 用户界面（UI）框架
• vite - 构建工具和开发服务器
• @vitejs/plugin-react - Vite 的 React 插件

启动前端开发服务器

npm run dev

前端将在 http://localhost:3000 （或下一个可用端口）

可用的前端脚本：

• npm run dev - 启动Vite开发服务器并启用热重载
• npm run build - 为生产环境构建
• npm run preview - 预览生产构建版本
• npm run lint - 运行 ESLint

4. 访问应用程序

1. 打开你的浏览器并前往 http://localhost:3000
2. 待办事项应用默认加载时聊天部分是隐藏的
3. 勾选“显示聊天”以启用AI聊天界面
4. 从下拉菜单中选择不同的聊天模式

🐛 故障排除

常见问题

1. 未找到Ollama

   # Ensure Ollama is installed and running
   ollama --version
   ollama serve

1. 模型不可用

   # Pull required models
   ollama pull gpt-oss
   ollama pull phi4-reasoning:latest
   ollama pull llama3:8b

1. 端口冲突

- 后端运行在3001端口 - 前端运行在3000端口（或下一个可用端口） - 检查端口是否可用

1. CORS问题

- 后端已配置为 http://localhost:3000 - 确保前端正在正确的端口上运行

1. TypeScript 错误

   # Rebuild backend
   cd backend
   npm run build

开发技巧

• 使用浏览器开发者工具检查网络请求
• 检查后端控制台以获取AI模型的响应
• 显示器 data/todos_db.json 用于任务持久化
• 使用MCP检查器进行调试工具调用

🤝 贡献（或：参与贡献）

1. 为仓库创建分支（或“克隆仓库”）
2. 创建一个特性分支
3. 进行你的更改
4. 彻底测试
5. 提交拉取请求

📄 许可证

这个项目是开源的，可在以下许可下使用： 麻省理工学院许可证（MIT License）。

🙏 致谢

• Ollama（注：Ollama是一个用于训练和部署大型语言模型的工具或框架的名称，直接翻译可能无法准确传达其含义，因此在此保留原英文名称） 用于本地AI模型推理
• 模型上下文协议 用于工具集成
• React 并且 快点 用于前端
• 快递 对于后端API