Pawsome宠物护理-具有Asgardeo身份验证的人工智能兽医助理
该项目展示了一个复杂的人工智能宠物护理聊天机器人系统，该系统将安全的MCP（模型上下文协议）服务器与智能LangGraph代理集成在一起，使用 阿斯加德奥 作为用于身份验证和授权的OAuth2/OIDC提供者。
🌟 主要特点
- 安全MCP服务器 使用Asgardeo OAuth2身份验证
- 智能LangGraph代理 具有动态上下文管理
- 多宠物上下文处理 具有自动宠物选择逻辑
- JWT令牌验证 与JWKS端点集成
- OpenAI集成 基于人工智能的宠物名字建议
- RESTful Web界面 支持CORS
- 实时聊天 有对话记忆
先决条件
- Python 3.12或更高版本
- Asgardeo帐户 和应用程序设置
- OpenAI API密钥（用于宠物名称建议）
- pip（Python包安装程序）
项目结构
├── main.py # FastMCP server with secured endpoints
├── agent.py # LangGraph agent with dynamic context logic
├── jwt_validator.py # JWT validation module for Asgardeo tokens
├── index.html # Web interface for chat
├── .env # Environment variables configuration
├── requirements.txt # Python dependencies
└── README.md # This file安装
- 克隆或下载此项目
- 创建虚拟环境（推荐）
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate- 安装必要的依赖项
pip install -r requirements.txt关键依赖关系包括：
- fastmcp -快速MCP服务器框架 - python-dotenv -环境变量管理 - openai -OpenAI API集成 - pyjwt -JWT令牌处理 - langgraph -代理编排 - langchain-openai -OpenAI语言链集成 - aiohttp -异步HTTP服务器 - httpx -HTTP客户端
- 配置环境变量
创建一个 .env 项目根目录中的文件：
# Asgardeo OAuth2 Configuration
## Asgardeo Configuration
## 1. Create an Asgardeo Application
1. Login to your [Asgardeo](https://asgardeo.io/) account.
2. Navigate to the **Applications** tab and select the **MCP Client Application**.
3. Add your application name and callback URL.
## 2. Get Your Application Credentials
创建应用程序后，获取 客户端ID 和 租户名称:
- 客户端ID：在应用程序的 协议 选项卡。
- 租户名称：您组织的租户名称（在URL中可见）。
授权发布者=https://api.asgardeo.io/t/ 客户端ID= Jwks网址=https://api.asgardeo.io/t//oauth2/jwks
# OpenAI配置
OPENAI_API密钥=
**Example with actual values:**# Asgardeo OAuth2 Configuration AUTH_ISSUER=https://api.asgardeo.io/t/pawsomepets CLIENT_ID=abc123xyz789_client_id_from_asgardeo JWKS_URL=https://api.asgardeo.io/t/pawsomepets/oauth2/jwks
# OpenAI Configuration OPENAI_API_KEY=sk-proj-abc123xyz789
## 🔐 Asgardeo配置
### 1.在Asgardeo中创建MCP客户端应用程序
1. 登录到您的 **阿斯加德奥** 帐户在 [https://console.asgardeo.io](https://console.asgardeo.io)
1. 导航到 **应用程序** 选项卡并选择 **MCP客户端应用程序** 模板
1. 配置您的应用程序：
- **应用程序名称**：爪子宠物护理MCP
- **授权重定向URL**：添加客户端应用程序的回调URL
- 对于MCP检查员： `http://localhost:6274/oauth/callback`
- 对于代理人： `http://localhost:8080/callback`
### 2.获取您的申请证书
创建应用程序后，检索以下内容：
- **客户端ID**：在应用程序的 **协议** 标签
- **租户名称**：您组织的租户名称（例如。， `pawsomepets`)
### 3.配置所需范围
确保您的Asgardeo应用程序启用了以下作用域：
- `openid` -标准OpenID连接范围
- `email` -用户电子邮件地址访问
- `profile` -用户资料信息
- `internal_login` -用户身份验证所需
### 4.更新环境变量
替换您的占位符 `.env` 文件：
- 替换 `` 使用您的实际Asgardeo租户姓名
- 替换 `` 使用Asgardeo提供的OAuth2客户端ID
**安全说明**：永远不要承诺你的 `.env` 文件到版本控制。添加 `.env` 你的 `.gitignore` 文件。
## 架构概述
### MCP服务器(`main.py`)
MCP服务器为宠物管理提供了安全的工具：
1. **JWT令牌验证**
- 使用Asgardeo JWKS端点验证传入令牌
- 提取用户声明（主题、范围、受众）
- 实现RFC 9728受保护资源元数据
1. **可用工具**:
- `get_user_id_by_email` -从电子邮件中检索用户ID
- `get_pets_by_user_id` -列出用户的所有宠物
- `get_pet_vaccination_info` -胎儿疫苗接种史
- `book_vet_appointment` -预约兽医
- `cancel_appointment` -取消现有约会
- `suggest_pet_names` -通过OpenAI提供人工智能宠物名字建议
### LangGraph代理(`agent.py`)
代理通过动态上下文管理编排智能对话：
1. **身份验证流程**
- 使用PKCE实现OAuth2授权码流
- 自动打开浏览器进行Asgardeo登录
- 从ID令牌和SCIM2/Me端点检索用户电子邮件
- 交换访问令牌的授权码
1. **状态管理**
- 维护每个会话的对话历史记录
- 缓存用户上下文（用户ID、宠物、活动宠物）
- 从用户消息中动态解析宠物上下文
1. **图形节点**:
- `load_context` -在对话开始时加载用户数据
- `classify` -确定用户意图
- `mcp_agent` -使用动态上下文执行MCP工具调用
- `greeting`, `services`, `pricing`, `general` -特定意图处理程序
1. **多宠物逻辑**:
- 单宠物：自动上下文选择
- 多只宠物：检测消息中的宠物名称或要求澄清
- 禁止宠物：适当通知用户
## 运行系统
### 1.启动MCP服务器
python main.py
服务器将于启动 `http://localhost:8000` 使用 `streamable-http` 运输。
### 2.启动代理服务器
python agent.py
代理人将：
1. 打开浏览器进行Asgardeo身份验证
1. 等待授权回调
1. 检索您的用户电子邮件
1. 启动聊天服务器 `http://localhost:8080`
### 3.访问Web界面
打开 `http://localhost:8080` 在浏览器中与聊天机器人交互。
## MCP检验员测试
### 设置MCP检查器
1. **安装并运行MCP检查器**:
npx @modelcontextprotocol/inspector
**备注**：确保版本 `0.16.3` 或更高。
1. **配置检查器回调**:
- 添加 `http://localhost:6274/oauth/callback` 转到您的Asgardeo应用程序的授权重定向URL
1. **连接到MCP服务器**:
- 打开检查器URL（例如。， `http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=`)
- 配置服务器连接：
- **运输**：HTTP SSE
- **统一资源定位符**: `http://localhost:8000/mcp`
- **认证**：具有Asgardeo设置的OAuth2
1. **测试身份验证**:
- 点击 **连接**
- 您将被重定向到Asgardeo进行登录
- 成功验证后，您可以测试这些工具
## 对话流程示例
### 示例1：单宠物用户
User: Hi! Agent: Welcome back! I've loaded your pet details. How can I help?
User: What are Buddy's vaccinations? Agent: [Automatically calls get_pet_vaccination_info with Buddy's ID] Buddy's vaccination records show: - Rabies (Jan 15, 2024) - Next due: Jan 15, 2025 - DHPP (Mar 20, 2024) - Next due: Mar 20, 2025 - Bordetella (Jun 10, 2024) - Upcoming: Dec 10, 2024
### 示例2：多个宠物用户
User: Show me vaccination info Agent: Which pet are you referring to? You have: - Buddy (Dog) - Spot (Dog)
User: Buddy Agent: [Calls get_pet_vaccination_info with Buddy's ID] [Returns vaccination details...]
### 示例3：预约
User: Book an appointment for Buddy next Monday at 2 PM for checkup Agent: [Calls book_vet_appointment] Appointment confirmed! - Pet: Buddy - Date: 2025-11-24 - Time: 2:00 PM - Reason: Checkup - Veterinarian: Dr. Smith
## 安全特性
1. **JWT令牌验证**
- 根据Asgardeo JWKS端点验证令牌
- 验证发行人、受众和到期时间
- 提取并验证作用域
1. **授权流程**
- 使用PKCE的OAuth2授权码流
- 安全令牌交换
- 无需客户端机密（PKCE保护公共客户端）
1. **基于范围的访问控制**
- 工具需要有效的访问令牌
- 未来增强：特定范围的工具访问
1. **用户上下文隔离**
- 每个用户只看到自己的宠物
- 基于会话的对话记忆
- 每个会话ID的上下文缓存
## 故障排除
### 未从ID令牌中检索到电子邮件
该代理包含回退逻辑，用于在ID令牌中不存在的情况下从SCIM2/Me端点检索电子邮件：
Fallback to SCIM2/Me endpoint
scim_url = f"{base_url}/scim2/Me" scim_resp = await client.get( scim_url, headers={"Authorization": f"Bearer {access_token}"} )
### 令牌验证失败
检查以下内容：
- JWKS URL正确且可访问
- 发卡机构URL完全匹配（包括租户）
- 客户端ID正确
- 令牌尚未过期
### 连接问题
- 确保MCP服务器正在上运行 `http://localhost:8000`
- 验证代理服务器是否正在上运行 `http://localhost:8080`
- 检查本地端口的防火墙设置
## 高级配置
### 自定义端口配置
修改相应文件中的端口设置：
**MCP服务器** (`main.py`):
mcp.run(transport="streamable-http", port=8000)
**代理服务器** (`agent.py`):
site = web.TCPSite(runner, 'localhost', 8080)
### 添加新工具
要添加新的MCP工具：
1. 在中定义工具 `main.py`:
@mcp.tool() async def my_new_tool(param: str) -> dict: """Tool description""" # Implementation return {"result": "data"}
2. 代理将自动发现并使用新工具。
## 贡献
欢迎投稿！请确保：
- 代码遵循PEP 8风格指南
- 所有新工具都包括适当的身份验证检查
- 文档已针对新功能进行了更新
## 许可证
本项目按原样提供，用于演示目的。
______________________________________________________________________
**由Asgardeo提供技术支持** -现代应用程序的企业级身份和访问管理。