AI导哈

MCP代理可视化工具

一个教育项目，通过集成电子邮件和交互式序列图可视化的真实世界提醒系统，展示模型上下文协议（MCP）概念。

  • by akhileshnr1998
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 akhileshnr1998/reminder-system-mcp

使用说明

MCP代理可视化工具

一个全面的教育项目，展示 模型上下文协议（MCP） 通过一个具有电子邮件集成和交互式序列图可视化的现实世界提醒系统。

🧠 什么是MCP？

模型上下文协议（MCP） 是一个标准，使人工智能模型能够安全地与外部工具和数据源进行交互。本项目展示了MCP的核心概念：

  • 工具声明：AI代理如何发现和理解可用功能
  • 安全通信：人工智能和外部服务之间的标准化协议
  • 错误处理：优雅的故障管理和恢复
  • 可观测性：实时监控人工智能决策过程
  • 多服务架构：人工智能协调多个独立服务

🎓 学习资源

🎯 为什么这个项目很重要

这不仅仅是一个提醒应用程序——它是一个 完整的MCP学习环境 这展示了AI代理如何：

  • 对工具的使用做出明智的决策
  • 与外部API和服务安全交互
  • 处理复杂的多步骤工作流程
  • 提供透明、可调试的执行流程

特性

  • 交互式查询输入：输入自然语言查询以与提醒代理交互
  • 电子邮件提醒：通过Nodemailer集成发送提醒电子邮件
  • 📅 日历集成：自动生成ICS文件，并将日历邀请附加到电子邮件中
  • 🧠 智能时间解析：自然语言时间理解（“明天下午2点”，“下周”）
  • ⏰ 智能持续时间：根据任务类型（电话、会议、约会）自动建议事件持续时间
  • 实时序列图：使用Mermaid图直观表示代理执行流程
  • 执行步骤跟踪：代理人决策过程中每个步骤的详细细分
  • 工具调用可视化：查看代理何时以及如何调用不同的工具
  • 多服务架构：MCP服务器与单独的电子邮件服务通信

设置

先决条件

  • Node.js（v18或更高版本）
  • npm
  • 环境变量中的有效GEMINI_API_KEY

安装

  1. 安装后端依赖项：

    npm install

  2. 安装前端依赖项：

    npm run install:frontend

  3. 设置环境变量： 创建一个 .env 根目录中的文件（请参见 env.example 供参考）：

    # AI Model Configuration
GEMINI_API_KEY=your_gemini_api_key_here

# Email Configuration
EMAIL_SERVICE=gmail
EMAIL_USER=your_email@gmail.com
EMAIL_PASS=your_app_password_here

# Optional: Default email for reminders
DEFAULT_REMINDER_EMAIL=your_email@gmail.com

    Gmail用户注意事项： 您需要：

    • 启用双因素身份验证
    • 为生成“应用程序密码” EMAIL_PASS
    • 使用应用程序密码，而不是常规的Gmail密码

运行应用程序

选项1：同时运行后端和前端（推荐）

npm run start:full

这将开始：

  • MCP服务器已打开http://localhost:3000
  • 电子邮件服务器上http://localhost:3002
  • 前端开发服务器位于http://localhost:3001

选项2：单独运行

仅限MCP服务器：

npm run start:dev

仅限电子邮件服务器：

npm run start:email

仅限前端：

npm run start:frontend

CLI客户端（原始）：

npm run start:client

用法

  1. 打开浏览器http://localhost:3001
  2. 在输入字段中输入查询，例如：
    • “添加提醒，在上午10点打电话给医生”
    • “下午5点给我发一封电子邮件提醒我购买杂货john@example.com"
    • “我目前的提醒是什么？”
    • 电子邮件提醒：团队会议将于明天下午2点在A会议室召开team@company.com60分钟”
    • “将下周下午3点牙医预约的日历邀请发送至myself@email.com"
  3. 点击“执行”运行查询
  4. 观察序列图填充代理的执行步骤
  5. 查看图表下方的详细步骤信息

🏗️ MCP架构演示

该项目实现了 规范MCP架构 明确区分关注点：

核心组件

  • 🤖 AI 代理 (src/agent-executor.ts)：制定工具决策的LangChain代理
  • 🔧 MCP服务器 (src/mcp_server.ts)：工具注册表和执行协调器
  • 📧 电子邮件服务 (src/email-server.ts)：独立的电子邮件操作服务
  • 📊 可视化 (frontend/src/)：使用序列图进行实时执行监控

MCP通信流程

👤 User Query 
    ↓
📱 Frontend (React UI)
    ↓ HTTP Request
🔧 MCP Server (Tool Registry)
    ↓ Agent Invocation  
🤖 AI Agent (Decision Making)
    ↓ Tool Selection & Execution
🛠️ Tools (Local Storage + Email Service)
    ↓ Results
📊 Sequence Diagram Visualization

演示关键MCP模式

  1. 工具发现：代理在运行时学习可用功能
  2. 参数验证：Zod模式确保类型安全
  3. 错误传播：通过有意义的消息优雅地处理故障
  4. 执行跟踪：完成人工智能决策和行动的审计跟踪
  5. 服务隔离：每个工具都独立运行，边界清晰

查询示例

本地提醒

  • “添加提醒，明天下午2点给Ranjith打电话”
  • “设置提醒，今晚8点买杂货”
  • “列出我的所有提醒”

带有日历邀请的电子邮件提醒

  • “给我发一封电子邮件提醒我上午10点打电话给医生john@example.com"
  • 电子邮件提醒：团队会议将于明天下午2点在A会议室召开team@company.com60分钟”
  • “将下周下午3点牙医预约的日历邀请发送至myself@email.com"
  • “电子邮件提醒今晚8点给妈妈打电话mom@email.com15分钟”

📅 日历功能

  • ICS自动生成：所有电子邮件提醒都包括日历邀请附件
  • 智能时间解析：自然语言理解（“明天下午2点”，“下周二”）
  • 持续时间智能：根据任务类型自动建议持续时间：
    • 电话：15分钟
    • 会议：60分钟
    • 医疗预约：45分钟
    • 默认值：30分钟
  • 位置支持：提取并包含位置信息
  • 提醒提醒：包括15分钟和5分钟的活动前通知

序列图图例

  • 蓝色箭头：代理人→ 工具调用
  • 绿色箭头：工具响应
  • 橙色箭头：LLM处理和响应
  • 红箭：错误条件

发展

生产大楼

npm run build
npm run build:frontend

项目结构

├── src/
│   ├── mcp_server.ts          # 🔧 MCP Tool Server (core protocol implementation)
│   ├── email-server.ts        # 📧 Independent Email Service  
│   ├── agent-executor.ts      # 🤖 AI Agent with Tool Orchestration
│   └── mcp_client.ts          # 💻 CLI Interface (alternative to web UI)
├── frontend/
│   ├── src/
│   │   ├── components/        # 📊 React UI Components
│   │   ├── types/            # 📝 TypeScript Interfaces
│   │   └── App.tsx           # 🎨 Main Application
│   └── package.json          # Frontend Dependencies
├── docs/
│   ├── MCP_CONCEPTS.md        # 📚 MCP Theory & Benefits
│   ├── TUTORIAL.md            # 🛠️ Step-by-Step Learning Guide  
│   └── EXAMPLES.md            # 💡 Advanced Patterns & Use Cases
├── env.example                # ⚙️ Configuration Template
└── package.json              # Backend Dependencies

🚀 MCP学习快速入门

  1. 理解概念：阅读 MCP_CONCEPTS.md
  2. 在行动中看到它：运行 npm run start:full 并尝试UI
  3. 构建自己的工具：关注 TUTORIAL.md
  4. 探索高级模式：研究 示例.md
  5. 实验：修改现有工具或添加新工具

🎯 教育价值

该项目展示了 生产就绪的MCP概念:

  • ✅ 安全：输入验证、错误边界、服务隔离
  • ✅ 可扩展性：模块化架构，独立服务部署
  • ✅ 可观测性：完整的执行跟踪和调试功能
  • ✅ 可靠性：优雅的错误处理和恢复机制
  • ✅ 开发者体验：清晰的界面，全面的文档

非常适合学习构建的开发人员 代理人工智能系统 可以安全有效地与现实世界的服务进行交互。

相关 MCP