使用说明

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:**
```bash
# 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客户端应用程序

登录到您的 阿斯加德奥 帐户在 https://console.asgardeo.io
导航到 应用程序 选项卡并选择 MCP客户端应用程序 模板
配置您的应用程序：
- 应用程序名称：爪子宠物护理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 文件：

替换 <your-tenant> 使用您的实际Asgardeo租户姓名
替换 <your-client-id> 使用Asgardeo提供的OAuth2客户端ID

安全说明：永远不要承诺你的 .env 文件到版本控制。添加 .env 你的 .gitignore 文件。

架构概述

MCP服务器(`main.py`)

MCP服务器为宠物管理提供了安全的工具：

JWT令牌验证
- 使用Asgardeo JWKS端点验证传入令牌
- 提取用户声明（主题、范围、受众）
- 实现RFC 9728受保护资源元数据
可用工具:
- 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`)

代理通过动态上下文管理编排智能对话：

身份验证流程
- 使用PKCE实现OAuth2授权码流
- 自动打开浏览器进行Asgardeo登录
- 从ID令牌和SCIM2/Me端点检索用户电子邮件
- 交换访问令牌的授权码
状态管理
- 维护每个会话的对话历史记录
- 缓存用户上下文（用户ID、宠物、活动宠物）
- 从用户消息中动态解析宠物上下文
图形节点:
- load_context -在对话开始时加载用户数据
- classify -确定用户意图
- mcp_agent -使用动态上下文执行MCP工具调用
- greeting, services, pricing, general -特定意图处理程序
多宠物逻辑:
- 单宠物：自动上下文选择
- 多只宠物：检测消息中的宠物名称或要求澄清
- 禁止宠物：适当通知用户

运行系统

1.启动MCP服务器

python main.py

服务器将于启动 http://localhost:8000 使用 streamable-http 运输。

2.启动代理服务器

python agent.py

代理人将：

打开浏览器进行Asgardeo身份验证
等待授权回调
检索您的用户电子邮件
启动聊天服务器 http://localhost:8080

3.访问Web界面

打开 http://localhost:8080 在浏览器中与聊天机器人交互。

MCP检验员测试

设置MCP检查器

安装并运行MCP检查器:
```
npx @modelcontextprotocol/inspector
```
备注：确保版本 0.16.3 或更高。
配置检查器回调:
- 添加 http://localhost:6274/oauth/callback 转到您的Asgardeo应用程序的授权重定向URL
连接到MCP服务器:
- 打开检查器URL（例如。， http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=<token>)
- 配置服务器连接：
  - 运输：HTTP SSE
  - 统一资源定位符: http://localhost:8000/mcp
  - 认证：具有Asgardeo设置的OAuth2
测试身份验证:
- 点击连接
- 您将被重定向到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

安全特性

JWT令牌验证
- 根据Asgardeo JWKS端点验证令牌
- 验证发行人、受众和到期时间
- 提取并验证作用域
授权流程
- 使用PKCE的OAuth2授权码流
- 安全令牌交换
- 无需客户端机密（PKCE保护公共客户端）
基于范围的访问控制
- 工具需要有效的访问令牌
- 未来增强：特定范围的工具访问
用户上下文隔离
- 每个用户只看到自己的宠物
- 基于会话的对话记忆
- 每个会话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工具：

在中定义工具 main.py:

@mcp.tool()
async def my_new_tool(param: str) -> dict:
    """Tool description"""
    # Implementation
    return {"result": "data"}

代理将自动发现并使用新工具。

贡献

欢迎投稿！请确保：

代码遵循PEP 8风格指南
所有新工具都包括适当的身份验证检查
文档已针对新功能进行了更新

许可证

本项目按原样提供，用于演示目的。

由Asgardeo提供技术支持 -现代应用程序的企业级身份和访问管理。