MCP Authendication example

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

安装

1. 克隆或下载此项目

1. 创建虚拟环境（推荐）

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate

1. 安装必要的依赖项

   pip install -r requirements.txt

关键依赖关系包括：

- fastmcp -快速MCP服务器框架 - python-dotenv -环境变量管理 - openai -OpenAI API集成 - pyjwt -JWT令牌处理 - langgraph -代理编排 - langchain-openai -OpenAI语言链集成 - aiohttp -异步HTTP服务器 - httpx -HTTP客户端

1. 配置环境变量

创建一个 .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客户端应用程序** 模板

   ![MCP Client App Selection](images/mcp-client-app-selection.png)

1. 配置您的应用程序：

   - **应用程序名称**：爪子宠物护理MCP
   - **授权重定向URL**：添加客户端应用程序的回调URL
     - 对于MCP检查员： `http://localhost:6274/oauth/callback`
     - 对于代理人： `http://localhost:8080/callback`

   ![MCP Client Creation](images/mcp-client-creation.png)

### 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

   ![MCP Auth Configs](images/mcp-auth-configs.png)

1. **测试身份验证**:

   - 点击 **连接**
   - 您将被重定向到Asgardeo进行登录
   - 成功验证后，您可以测试这些工具

   ![MCP Server Connect](images/mcp-server-connect.png)

## 对话流程示例

### 示例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提供技术支持** -现代应用程序的企业级身份和访问管理。