🏥 智能医生助理
一个用于医疗预约和管理的智能代理人工智能系统，由 模型上下文协议（MCP） 以及工具调用LLM。
🎯 项目概述
这是一个生产质量的全栈应用程序演示 真正的代理行为 使用MCP。该系统支持：
- 患者：使用自然语言对话预约
- 医生：接收人工智能生成的摘要报告和统计数据
- AI 代理：动态发现和调用MCP工具，无需硬编码工作流
🆓 100%免费设置！\ 该项目使用完全免费的API，无需信用卡： - LLM：Ollama（本地）、Groq、Together AI或抱抱脸 - 电子邮件：Gmail SMTP - 通知：Discord Webhooks或Telegram Bot 看 FREE_APIS_SETUP.md 获取完整的设置指南。
主要特点
✅ 真正的智能人工智能：LLM动态决定使用哪些工具\ ✅ MCP集成：通过模型上下文协议公开的工具、资源和提示\ ✅ 多回合对话：跨交互的上下文保护\ ✅ 无直接数据库访问：通过MCP工具执行的所有操作\ ✅ 外部API集成：谷歌日历、Gmail/SendGrid、Slack
🏗️ 建筑
┌─────────────────────────────────────────────────────────────┐
│ Frontend (React) │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Patient Chat │ │ Doctor Dashboard │ │
│ │ Interface │ │ │ │
│ └──────────────────┘ └──────────────────┘ │
└───────────────────────────┬─────────────────────────────────┘
│
HTTP/REST API
│
┌───────────────────────────▼─────────────────────────────────┐
│ FastAPI Backend │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Agent Orchestrator │ │
│ │ • Manages conversation context │ │
│ │ • Calls LLM with tool definitions │ │
│ │ • Executes tool calls through MCP │ │
│ │ • Synthesizes final responses │ │
│ └────────────────────┬─────────────────────────────────┘ │
│ │ │
│ ┌────────────────────▼─────────────────────────────────┐ │
│ │ MCP Server │ │
│ │ │ │
│ │ MCP TOOLS (Actions): │ │
│ │ • get_doctor_availability │ │
│ │ • book_appointment │ │
│ │ • send_patient_email │ │
│ │ • get_doctor_stats │ │
│ │ • send_doctor_notification │ │
│ │ • list_doctors │ │
│ │ │ │
│ │ MCP RESOURCES (Read-only): │ │
│ │ • doctors_list │ │
│ │ • appointments_data │ │
│ │ • doctor_schedules │ │
│ │ │ │
│ │ MCP PROMPTS (Reasoning): │ │
│ │ • appointment_booking │ │
│ │ • doctor_summary │ │
│ └────────────────────┬─────────────────────────────────┘ │
│ │ │
└───────────────────────┼──────────────────────────────────────┘
│
┌───────────────┼───────────────┐
│ │ │
▼ ▼ ▼
PostgreSQL Google Calendar Gmail/Slack
Database API API🧠 MCP如何实现真正的代理行为
传统方法（硬编码）
if "book appointment" in message:
check_availability()
create_appointment()
send_email()代理方法（MCP）
# Agent discovers tools dynamically
tools = mcp_server.list_tools()
# LLM decides which tools to use based on user intent
llm_response = call_llm(message, tools)
# Execute whatever tools the LLM chose
for tool_call in llm_response.tool_calls:
result = mcp_server.invoke_tool(tool_call.name, tool_call.args)LLM代理：
- 发现 运行时可用的MCP工具
- 原因 关于用户请求需要哪些工具
- 执行 工具按最佳顺序排列
- 使适应 无需重新编程即可进行多轮对话
📁 项目结构
smart-doctor-assistant/
├── backend/
│ ├── main.py # FastAPI application
│ ├── requirements.txt # Python dependencies
│ ├── .env.example # Environment variables template
│ │
│ ├── mcp/
│ │ └── server.py # MCP server with tools/resources/prompts
│ │
│ ├── agents/
│ │ └── orchestrator.py # Agent orchestration engine
│ │
│ ├── db/
│ │ ├── database.py # Database connection
│ │ ├── models.py # SQLAlchemy models
│ │ └── schema.sql # Database schema + seed data
│ │
│ └── tools/ # External API integrations (future)
│
├── frontend/
│ ├── src/
│ │ ├── App.jsx # Main application component
│ │ ├── App.css # Global styles
│ │ ├── main.jsx # React entry point
│ │ │
│ │ └── components/
│ │ ├── PatientChat.jsx # Patient chat interface
│ │ └── DoctorDashboard.jsx # Doctor dashboard
│ │
│ ├── index.html # HTML template
│ ├── package.json # Node dependencies
│ └── vite.config.js # Vite configuration
│
└── README.md # This file🚀 安装说明
先决条件
- Python 3.10+
- Node.js 18+
- PostgreSQL 14+
- 免费LLM （选择一个）：
- 奥拉玛 （本地，推荐）-从下载https://ollama.ai - 格罗克 （云，免费套餐）-在以下网址注册https://console.groq.com - 共同AI （云，免费套餐）-在以下网址注册https://api.together.xyz - 拥抱脸 （云，免费）-注册https://huggingface.co
💡 无需支付API密钥！ 看 FREE_APIS_SETUP.md 详细设置。
1.数据库设置
# Create PostgreSQL database
createdb smart_doctor_db
# Or using psql
psql -U postgres
CREATE DATABASE smart_doctor_db;
\q
# Initialize schema and seed data
psql -U postgres -d smart_doctor_db -f backend/db/schema.sql2.后端设置
cd backend
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Configure environment variables
cp .env.example .env
# Edit .env and add your API keys
# Run the FastAPI server
python main.py
# Server will start at http://localhost:80003.前端设置
cd frontend
# Install dependencies
npm install
# Start development server
npm run dev
# Frontend will start at http://localhost:30004.验证安装
打开http://localhost:3000在您的浏览器中。您应该看到Smart Doctor Assistant界面。
🎭 示例提示和场景
场景1：患者预约
用户提示1：
"I want to book an appointment with Dr. Ahuja tomorrow morning."代理流程：
- 解析意图（医生：Ahuja，日期：明天，时间：早上）
- 呼叫
get_doctor_availability工具 - 显示可用插槽
- 等待用户确认
用户提示2：
"Book the 10 AM slot."代理流程：
- 回忆之前对话的背景
- 呼叫
book_appointment工具 - 创建谷歌日历事件
- 呼叫
send_patient_email工具 - 返回确认
场景2：多回合对话
第1回合：
User: "Check Dr. Ahuja's availability for Friday afternoon."
Agent: [Calls get_doctor_availability]
"Dr. Ahuja has these slots available on Friday afternoon:
• 2:00 PM
• 2:30 PM
• 3:00 PM
• 3:30 PM"第二回合：
User: "Book the 3 PM slot."
Agent: [Remembers: Dr. Ahuja, Friday, 3 PM from context]
[Calls book_appointment]
"Great! I've booked your appointment with Dr. Ahuja
for Friday at 3:00 PM. Confirmation email sent."场景3：医生总结报告
用户提示：
Doctor: "How many patients visited yesterday?"代理流程：
- 根据上下文识别医生
- 呼叫
get_doctor_stats昨天的日期范围 - 分析预约数据
- 呼叫
send_doctor_notification附摘要 - 返回格式化报告
医生查询示例：
- “本周有多少发烧病例？”
- “显示今天和明天的约会。”
- “这个月最常见的症状是什么？”
- “给我一份已完成预约与计划预约的总结。”
🔧 MCP工具定义
工具（动作）
1.get_doctor_availability
{
"name": "get_doctor_availability",
"description": "Get available appointment slots for a doctor",
"parameters": {
"doctor_name": "string",
"date": "YYYY-MM-DD"
}
}2.图书预约
{
"name": "book_appointment",
"description": "Book an appointment for a patient",
"parameters": {
"patient_name": "string",
"patient_email": "string",
"doctor_name": "string",
"appointment_date": "YYYY-MM-DD",
"appointment_time": "HH:MM",
"symptoms": "string (optional)"
}
}3.send_patien_email
{
"name": "send_patient_email",
"description": "Send confirmation email to patient",
"parameters": {
"patient_email": "string",
"appointment_id": "integer",
"subject": "string",
"message": "string"
}
}4.get_doctor_stats
{
"name": "get_doctor_stats",
"description": "Get appointment statistics for a doctor",
"parameters": {
"doctor_name": "string",
"start_date": "YYYY-MM-DD",
"end_date": "YYYY-MM-DD"
}
}5.send_doctor_nomination
{
"name": "send_doctor_notification",
"description": "Send notification to doctor (Slack/in-app)",
"parameters": {
"doctor_email": "string",
"notification_type": "report|alert|reminder",
"title": "string",
"message": "string"
}
}资源（只读数据）
- 医生名单:
resource://doctors - 预约_数据:
resource://appointments - 医生时间表:
resource://schedules
提示（推理模板）
- 预约_预订：指导预约推理
- 医生_总结：指导报告生成推理
🔌 API终点
聊天API
POST /api/chat-主代理交互端点
MCP端点
GET /api/mcp/tools-列出所有可用工具POST /api/mcp/tools/{tool_name}-调用特定工具GET /api/mcp/resources-列出所有资源GET /api/mcp/resources/{resource_name}-获取资源数据
医生终点
GET /api/doctors-列出所有医生POST /api/doctor/stats-获取医生统计数据POST /api/doctor/generate-report-生成AI报告
约会终点
GET /api/appointments-列出约会POST /api/appointments-创建约会GET /api/availability/{doctor_id}-检查可用性
🧪 测试代理
测试1：动态工具发现
curl http://localhost:8000/api/mcp/tools测试2：直接刀具调用
curl -X POST http://localhost:8000/api/mcp/tools/get_doctor_availability \
-H "Content-Type: application/json" \
-d '{
"doctor_name": "Dr. Rajesh Ahuja",
"date": "2025-12-20"
}'测试3：代理聊天
curl -X POST http://localhost:8000/api/chat \
-H "Content-Type: application/json" \
-d '{
"message": "I want to book an appointment with Dr. Ahuja tomorrow at 10 AM",
"user_type": "patient"
}'📊 数据库模式
医生桌
id,name,specialization,emailavailable_days[],available_start_time,available_end_timeslot_duration_minutes
患者表
id,name,email,phone,date_of_birth
预约表
id,patient_id,doctor_idappointment_date,appointment_time,duration_minutesstatus,symptoms,diagnosis,notesgoogle_calendar_event_id
🎯 为什么这种架构适合面试
1. 真正的代理行为
- 没有硬编码的if-else逻辑
- LLM动态发现和使用工具
- 无需更改代码即可适应新工具
2. 生产质量MCP实施
- 清洁分离：工具、资源、提示
- 每个工具都有单一的责任
- 正确的错误处理和验证
3. 可扩展设计
- 添加新工具很简单（只需在MCP服务器中注册）
- 代理自动发现新功能
- 前端与后端变化无关
4. 上下文管理
- 基于会话的会话跟踪
- 多回合上下文保存
- 交互过程中没有信息丢失
5. 外部API集成
- 用于日程安排的谷歌日历
- 用于通知的Gmail/SendGrid
- 医生提醒功能松弛
- 贯穿MCP抽象
🚀 未来的增强功能
- \[\]基于JWT的角色认证（患者/医生）
- \[\]医生不在时自动重新安排
- \[\]提示历史和分析
- \[\]语音接口集成
- \[\]基于症状的医生推荐
- \[\]通过短信发送预约提醒
- \[\]保险验证集成
🔒 安全考虑
- 环境变量中的API键
- 数据库凭据已保护
- 所有工具的输入验证
- 端点速率限制
- CORS配置正确
📝 许可证
麻省理工学院许可证-可自由用于学习和面试。
🤝 贡献
这是一个面试示范项目。请随意分叉和增强！
📧 联系
有关此实现的问题，请参阅代码注释和架构图。
______________________________________________________________________
内置于❤️ 展示代理人工智能和模型上下文协议的强大功能