MCP De Agente De Viajes

🌍 旅行计划代理

使用Model Context Protocol（MCP）和Google Gemini帮助计划假期的智能助手。

______________________________________________________________________

📖 项目描述

该项目实施 智能对话代理 帮助用户计划假期。系统使用 模型上下文协议（MCP） 要展示允许：

• 🔍 搜索城市之间的可用航班
• 🏨 按星级搜索酒店
• 🌤️ 查询旅游目的地的气候
• 💾 保存和修改自定义旅行计划

该代理旨在 自动执行 当您收到所有必要的信息时进行搜索，而不会向用户要求不必要的权限。

______________________________________________________________________

🎯 使用案例

问题： 用户在计划旅行之前，会浪费时间访问多个网站来比较航班、酒店和天气。

解决方案 ： 一个对话代理，集中所有信息，并指导用户逐步规划假期。

目标用户： 寻求简化体验以组织旅行的旅行者。

______________________________________________________________________

🎬 演示

Demo del Agente de Viajes

_当用户提供目的地、始发地、日期和停留天数时，代理会自动搜索航班、酒店和天气。_

______________________________________________________________________

🛠️ 堆栈技术

后端

• 快速API：创建代理服务器的Web框架
• FastMCP：实现MCP服务器的书店
• LangChain：使用LLMS构建应用程序的框架
• langchain_google_genai：谷歌双子座与LangChain的整合
• langchain_mcp_适配器：连接MCP和LangChain的适配器

LLM

• 谷歌双子座2.0 Flash Exp：最先进的语言模型

数据与验证

• 派丹蒂克：验证结构化数据和模型
• Uvicorn：高性能ASGI服务器

运输

• 服务器发送事件（SSE）：MCP通信协议

______________________________________________________________________

📦 安装

先决条件

• Python 3.11以上
• Python包管理器
• 谷歌API密钥（使用双子座）

安装步骤

1. 克隆存储库：

git clone https://github.com/tu-usuario/agente-viajes-mcp.git
cd agente-viajes-mcp

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

python -m venv venv

# En Windows:
venv\Scripts\activate

# En Linux/Mac:
source venv/bin/activate

1. 安装依赖项：

pip install -r requirements.txt

1. 配置器Google API密钥：

打开 agent_server.py 并替换API密钥：

GOOGLE_API_KEY = "TU_API_KEY_AQUI"

⚠️ 重要提示： 永远不要将您的密钥API上传到GitHub。考虑在生产中使用环境变量。

______________________________________________________________________

🚀 使用

第一步：启动MCP服务器

在终端上，它执行：

python mcp_server.py

你应该看看：

--- Iniciando Servidor de Herramientas (Mauricio) en http://localhost:8000 ---

步骤2：启动代理服务器

恩 其他终端，执行：

python agent_server.py

你应该看看：

🚀 Iniciando carga del agente de viajes...
✅ ¡Conexión con Google Gemini exitosa!
✅ Herramientas MCP cargadas: ['buscar_vuelos', 'buscar_hoteles', ...]
🌐 Iniciando Servidor de Agente en http://localhost:8001

步骤3：与代理交互

你可以使用 迅雷客户端, 邮递员，o Python请求:

import requests

response = requests.post(
    "http://localhost:8001/chat",
    json={
        "message": "Quiero viajar de Buenos Aires a Madrid el 20 de diciembre por 7 días",
        "history": []
    }
)

print(response.json()["response"])

______________________________________________________________________

🔌 可用端点

1.健康检查

端点： GET /health

描述： 验证代理是否准备好并运行。

回答：

{
  "status": "ok",
  "message": "Agente listo",
  "model": "gemini-2.0-flash-exp",
  "tools": 5
}

______________________________________________________________________

2.聊天

端点： POST /chat

描述： 向代理发送消息并接收响应。

主体：

{
  "message": "Hola, quiero planificar unas vacaciones",
  "history": []
}

参数：

• message （字符串）：用户消息
• history （数组）：格式化对话历史：

  [
    { "role": "user", "content": "mensaje del usuario" },
    { "role": "ai", "content": "respuesta del agente" }
  ]

回答：

{
  "response": "¡Hola! Para planificar tus vacaciones necesito saber: ¿Cuál es tu destino?..."
}

______________________________________________________________________

🛠️ MCP服务器工具

1. buscar_vuelos

描述： 搜索两个城市之间在特定日期的可用航班。

参数：

• origen （字符串）：航班的始发城市
• destino （字符串）：航班目的地城市
• fecha （字符串）：YYY-MM-DD格式的航班日期

返回 ： 对象列表 Vuelo:

{
  "id": "VUELO-001",
  "origen": "Buenos Aires",
  "destino": "Madrid",
  "fecha": "2025-12-20",
  "precio": 850,
  "duracion_hs": 13
}

______________________________________________________________________

2. buscar_hoteles

描述： 在一个评级最低的城市寻找可用的酒店。

参数：

• ciudad （字符串）：寻找酒店的城市
• estrellas （INT）：酒店的最低星级（1-5）。默认3

返回 ： 对象列表 Hotel:

{
  "id": "HOTEL-001",
  "ciudad": "Madrid",
  "estrellas": 5,
  "nombre": "Hotel Dandi Royal",
  "precio_noche_usd": 220
}

______________________________________________________________________

3. obtener_clima

描述： 获取特定城市的当前天气预报。

参数：

• ciudad （字符串）：查询天气的城市名称

返回 ： 物体 Clima:

{
  "ciudad": "Madrid",
  "condicion": "Soleado",
  "temperatura_c": 27,
  "descripcion": "Día soleado, ideal para turismo"
}

可能的条件： 晴天，多云，部分多云，多雨，暴风雨

______________________________________________________________________

4. guardar_plan_viaje

描述： 保存或更新用户的旅行计划。

参数：

• usuario （字符串）：用户的名称或ID
• destino （字符串）：目的地城市
• fecha_salida （字符串）：YYY-MM-DD格式的输出日期
• dias_estadia （int）：停留天数
• vuelo_ida （字符串，可选）：选定航班的ID
• hotel （字符串，可选）：所选酒店的ID
• notas （字符串，可选）：关于计划的附加说明

返回 ：

{
  "status": "success",
  "mensaje": "Plan de viaje guardado exitosamente para usuario_react",
  "plan": {
    "destino": "Madrid",
    "fecha_salida": "2025-12-20",
    "dias_estadia": 7,
    "vuelo_ida": "VUELO-001",
    "hotel": "HOTEL-002",
    "notas": null
  }
}

______________________________________________________________________

5. obtener_plan_viaje

描述： 检索为用户保存的旅行计划。

参数：

• usuario （字符串）：用户的名称或ID

返回 ：

{
  "status": "success",
  "plan": {
    "destino": "Madrid",
    "fecha_salida": "2025-12-20",
    "dias_estadia": 7,
    "vuelo_ida": "VUELO-001",
    "hotel": "HOTEL-002"
  }
}

如果没有计划：

{
  "status": "not_found",
  "mensaje": "No se encontró un plan de viaje para usuario_react"
}

______________________________________________________________________

💬 对话的例子

例1：全面规划

用户：

Quiero ir de Buenos Aires a Madrid el 20 de diciembre de 2025 por 7 días

代理人：

Aquí tienes las opciones que encontré:

**Vuelos:**
- VUELO-001: Buenos Aires a Madrid - 2025-12-20 - $850 USD
- VUELO-002: Buenos Aires a Madrid - 2025-12-20 - $780 USD

**Hoteles:**
- HOTEL-001: Hotel Dandi Royal (5★) - $220 USD/noche
- HOTEL-002: Hotel Gorditos Plaza (4★) - $150 USD/noche

**Clima:**
El clima en Madrid para esas fechas suele ser frío, con temperaturas
promedio entre 5°C y 12°C. Es recomendable llevar abrigo.

¿Cuál vuelo y hotel te gustaría elegir?

用户：

Quiero el vuelo VUELO-001 y el hotel HOTEL-002

代理人：

¡Perfecto! He guardado tu plan de viaje con el vuelo VUELO-001
y el hotel HOTEL-002 para tu viaje a Madrid del 20 de diciembre de 2025.

______________________________________________________________________

例2：计划修改

用户：

Cambio de opinión, prefiero el hotel HOTEL-001

代理人：

¡Listo! He actualizado tu plan de viaje con el hotel HOTEL-001.

______________________________________________________________________

例3：拒绝查询

用户：

¿Cuál es la capital de Francia?

代理人：

Lo siento, solo puedo ayudarte con la planificación de viajes.
¿Deseas organizar unas vacaciones?

______________________________________________________________________

📁 项目结构

├── 📁 client
│   ├── 📁 src
│   │   ├── 📄 App.tsx
│   │   ├── 🎨 index.css
│   │   └── 📄 main.tsx
│   ├── ⚙️ .gitignore
│   ├── 📝 README.md
│   ├── 🌐 index.html
│   ├── ⚙️ package.json
│   ├── ⚙️ pnpm-lock.yaml
│   ├── ⚙️ tsconfig.app.json
│   ├── ⚙️ tsconfig.json
│   ├── ⚙️ tsconfig.node.json
│   └── 📄 vite.config.ts
├── 📁 server
│   └── 🐍 agent_server.py
├── 📁 server-mcp
│   ├── 🐍 mcp_server.py
│   └── 📄 requirements.txt
├── 📝 Prueba_bot.md
└── 📝 README.md

______________________________________________________________________

🧪 可用的模拟数据

航班

• 布宜诺斯艾利斯→ 马德里（20/12/2025）-850美元
• 布宜诺斯艾利斯→ 巴塞罗那（20/12/2025）-780美元
• 布宜诺斯艾利斯→巴黎（2025年12月20日）-920美元
• 布宜诺斯艾利斯→ 罗马（25/12/2025）-890美元
• 福尔摩沙→ 布宜诺斯艾利斯（20/12/2025）-150美元

酒店

马德里：

• 丹迪皇家酒店（5★）-220美元/晚
• 戈迪托斯广场酒店（4★）-150美元/晚
• 马德里中央酒店（3★）-95美元/晚

巴塞罗那：

• 戈迪托斯广场酒店（4★）-150美元/晚

巴黎：

• 巴黎Le Grand Hotel（5★）-280美元/晚

罗马：

• 罗马诺酒店（4★）-180美元/晚

气候

• 马德里：索莱亚多，27°C
• 巴塞罗那：部分多云，25°C
• 巴黎：多云，18°C
• 罗马：索莱亚多，29°C
• 布宜诺斯艾利斯：索莱多，30°C

______________________________________________________________________

🎯 主要特征

✅ 自然对话： 代理维护会话上下文\ ✅ 自动执行： 未经许可搜索信息\ ✅ 数据验证： 使用pydantic验证所有条目\ ✅ 错误处理： 友好地捕获和报告错误\ ✅ 智能拒绝： 仅回答有关旅行规划的查询\ ✅ 计划修改： 允许更新现有计划\ ✅ 结构化数据： JSON格式的答案和类型化的对象