Atlas-MCP Powered Agentic AI Trip Planner

🗺️ 项目图集-人工智能旅行计划

使用LangChain、LangGraph和Google Gemini的人工智能旅行计划器。为航班（行李）、天气（OpenMeteo）、活动（Tavily）、住宿（OpenBnB）和愿望清单协调MCP服务器。

______________________________________________________________________

🎯 概述

阿特拉斯 是一款基于人工智能的旅行伴侣，它改变了用户规划旅行的方式。用户只需用自然语言描述他们的旅行需求，而不是在多个网站之间来回切换。阿特拉斯：

• 🌤️ 检查天气 在目的地（OpenMeteo API）
• ✈️ 搜索航班 实时（Duffel API v2）
• 🏨 寻找住宿 具有风格匹配功能（OpenBnB MCP-AirBnB的MCP服务器）
• 🎭 发现活动 和隐藏的宝石（Tavily AI搜索）
• 📋 管理愿望清单 用于行程规划
• 📊 提供成本估算 以及行程建议

______________________________________________________________________

🏗️ 建筑

高级图表

┌─────────────────────────────────────────────────────────┐
│                    User Interfaces                      │
│  ┌──────────────┐          ┌──────────────┐             │
│  │ CLI Client   │          │ Streamlit UI │             │
│  │ (async)      │          │ (web)        │             │
│  └──────────────┘          └──────────────┘             │
└───────────────┬──────────────────────────┬──────────────┘
                │                          │
                └──────────────┬───────────┘
                               │
        ┌──────────────────────▼─────────────────────────┐
        │         LangGraph Agent Executor               │
        │  (Orchestrates tools, manages chat state)      │
        │                                                │
        └──────────────────────┬─────────────────────────┘
                               │
        ┌──────────────────────▼─────────────────────────┐
        │       MultiServerMCPClient (langchain)         │
        │     (Routes requests to specialized servers)   │
        └──────┬───┬───┬───┬─────────────────────────────┘
               │   │   │   │
     ┌─────────┘   │   │   └─────────────────┐
     │             │   │                     │
┌────▼────┐  ┌────▼────┐  ┌────▼────┐  ┌────▼────┐  ┌────▼────┐
│ Flight  │  │ Weather │  │ Scout   │  │Wishlist │  │ Airbnb  │
│ Server  │  │ Server  │  │ Server  │  │ Server  │  │ Server  │
│Port 8002│  │Port 8000│  │Port 8003│  │Port 8001│  │ (npx)   │
└────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘
     │            │            │            │            │
┌────▼────────────▼────────────▼────────────▼────────────▼────┐
│             External APIs & Services                        │
│  Duffel (Flights) │ OpenMeteo │ Tavily  │ OpenBnB │         |
└─────────────────────────────────────────────────────────────┘

技术栈

______________________________________________________________________

🚀 快速开始

1.安装和设置

python -m venv venv
source venv/Scripts/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

2.配置环境

创建 .env 在项目根目录中：

# LLM (pick one)
GOOGLE_API_KEY=your_gemini_key
GROQ_API_KEY=your_groq_key

# APIs
DUFFEL_API_KEY=your_duffel_key
TAVILY_API_KEY=your_tavily_key

# Optional
LANGFUSE_SECRET_KEY=your_secret_key
LANGFUSE_PUBLIC_KEY=your_public_key

3.启动MCP服务器

打开 4个独立的终端:

python -m src.atlas.servers.flight_server      # Port 8002 - Flight search
python -m src.atlas.servers.wish_list_server   # Port 8001 - Wishlist management
python -m src.atlas.servers.wheather_server    # Port 8000 - Weather forecasts
python -m src.atlas.servers.scout_server       # Port 8003 - Activities discovery

或者，如果你有根包装脚本：

python flight_server.py
python wish_list_server.py
python wheather_server.py
python scout_server.py

4.运行应用程序

命令行接口命令模式 （推荐）：

python -m src.atlas.client.client

Web用户界面 （流光灯）：

streamlit run src/atlas/client/app.py
# Opens at http://localhost:8501

______________________________________________________________________

📁 项目结构

project atlas/
├── README.md                          # Documentation (this file)
├── requirements.txt                   # Python dependencies
├── .env                              # API keys & config (not tracked)
├── test.py                           # Test script
│
├── src/atlas/                        # Main application package
│   ├── __init__.py
│   │
│   ├── client/                       # User Interface Layer
│   │   ├── client.py                 # CLI agent (async, async main loop)
│   │   └── app.py                    # Streamlit web UI interface
│   │
│   ├── servers/                      # MCP Tool Servers (FastMCP)
│   │   ├── flight_server.py          # ✈️ Flight search (Duffel API, Port 8002)
│   │   ├── wheather_server.py        # 🌤️ Weather forecasts (OpenMeteo, Port 8000)
│   │   ├── scout_server.py           # 🎭 Activities discovery (Tavily, Port 8003)
│   │   └── wish_list_server.py       # 📋 Wishlist management (In-memory, Port 8001)
│   │
│   ├── prompt/                       # Prompt Templates
│   │   └── agent_prompt.py           # System instructions & planning rules
│   │
│   │
│   └── config/                       # Configuration (empty - for future use)
│       └── env loader
│
├── tests/                            # Test suite directory (if created)
│
├── logs/                             # Application logs (auto-created)
│   └── atlas.log                     # Rotating log file (5MB, 10-day retention)
│
└── __pycache__/                      # Python cache (ignored in git)

关键文件

______________________________________________________________________

⚙️ MCP服务器

______________________________________________________________________

� API设置

谷歌双子座

1. 访问 谷歌AI工作室
2. 创建API密钥→ 添加到 .env 作为 GOOGLE_API_KEY

备选方案： Groq Calma 3.1 （更快）→ GROQ_API_KEY

行李架（航班）

1. 注册地址： 达夫尔
2. 获取测试/生产API密钥→ DUFFEL_API_KEY

Tavily（活动）

1. 注册地址： 塔维利
2. 获取API密钥→ TAVILY_API_KEY

OpenMeteo（天气）

✅ 免费，不需要API密钥！

廊坊（可选）

1. 注册地址： 浪伏
2. 创建项目，添加密钥 .env 用于追踪

______________________________________________________________________

�️ 发展

添加新服务器

1. 创建 src/atlas/servers/my_server.py:

from fastmcp import FastMCP

mcp = FastMCP("My Server")

@mcp.tool()
def my_tool(param: str) -> str:
    return f"Result: {param}"

if __name__ == "__main__":
    mcp.run(transport="streamable-http", port=8004)

1. 创建根包装器 my_server.py:

import sys
sys.path.insert(0, "src")
from atlas.servers.my_server import mcp
if __name__ == "__main__":
    mcp.run(transport="streamable-http", port=8004)

1. 注册 MCP_SERVERS dict（客户端.py/app.py）：

MCP_SERVERS = {
    "my_server": {
        "transport": "streamable_http",
        "url": "http://127.0.0.1:8004/mcp",
    }
}

______________________________________________________________________

🐛 故障排除

______________________________________________________________________

📚 主要特点

✅ 多回合对话 具有状态持久性（LangGraph MemorySaver）\ ✅ 异步I/O 用于快速API调用\ ✅ 集中化的日志 （洛古鲁→ 控制台+旋转文件）\ ✅ 优雅的API漏洞 （例如，如果Tavily失败，则进行模拟搜索）\ ✅ 键入提示 贯穿始终（Pydantic模型）\ ✅ 可选可观察性 （Langfuse追踪）

______________________________________________________________________

� 资源

• LangChain文档
• LangGraph文档
• FastMCP文档
• Loguru文件

______________________________________________________________________

旅途愉快！ ✈️🗺️

最后更新日期：2025年12月|版本：1.0.0