MCP Core Architecture Poc

MCP旅行助理-POC

用于旅行相关任务的模型上下文协议（MCP）架构的概念验证实现。该项目演示了LLM如何通过标准化的JSON-RPC通信与外部服务无缝集成。

______________________________________________________________________

🎯 概述

MCP Travel Assistant是一个POC，展示了模型上下文协议，这是LLM与外部系统交互的标准化接口。服务器通过JSON-RPC 2.0实现MCP规范，通过stdin/stdout进行通信。

为什么选择MCP？

• 标准化：LLM工具集成的通用协议
• 可扩展性：易于添加新工具、资源和提示
• LLM兼容性：适用于任何MCP兼容客户端（Claude、GPT等）
• 可扩展性：将客户端和服务器逻辑之间的关注点分开

______________________________________________________________________

🏗️ 建筑

┌─────────────────────────────────────────┐
│         LLM Client (Claude/GPT)         │
└────────────────┬────────────────────────┘
                 │
         ┌───────┴────────┐
         │  JSON-RPC 2.0  │
         │   (stdio)      │
         └───────┬────────┘
                 │
┌────────────────▼────────────────────────┐
│       MCP Server (mcp_server.py)        │
├─────────────────────────────────────────┤
│  ✅ Tools (search_flights, weather)     │
│  ✅ Resources (calendar, knowledge)     │
│  ✅ Prompts (vacation planning, email)  │
└────────────────┬────────────────────────┘
                 │
    ┌────────────┼────────────┐
    │            │            │
┌───▼──┐  ┌─────▼──┐  ┌──────▼───┐
│Flight│  │Weather │  │ Calendar │
│API   │  │API     │  │  (Google)│
└──────┘  └────────┘  └──────────┘

______________________________________________________________________

✨ 特性

🛠️ 工具

• search_flights：使用日期和偏好查找机场之间的航班
• get_weather：使用纬度/经度检索天气预报
• list_calendar_events：从谷歌日历中获取即将到来的日历事件
• create_calendar_event：安排新的日历事件

📚 资源

• calendar://events:实时日历数据访问
• knowledge://travel_tips:旅行计划指南
• knowledge://booking_policy:预订和取消政策
• knowledge://destinations:热门旅游目的地信息

💬 提示

• plan_vcation：生成详细的度假行程
• draft_email：撰写与旅行相关的专业电子邮件
• summarize_meets：汇总某个日期范围内的日历会议

______________________________________________________________________

📁 项目结构

MCP_POC/
├── server/
│   ├── __init__.py
│   ├── mcp_server.py          # Main MCP server (JSON-RPC 2.0)
│   ├── clients.py             # External API clients
│   ├── config.py              # Configuration & settings
│   └── _pycache_/
├── client/
│   ├── __init__.py
│   ├── mcp_client.py          # Async/Sync MCP client
│   └── _pycache_/
├── app_mcp.py                 # Streamlit UI
├── requirements.txt           # Python dependencies
├── .env                       # Environment variables (not included)
└── README.md                  # This file

______________________________________________________________________

🚀 安装

先决条件 Python 3.8+ pip或诗意的包装管理 用于外部服务的API密钥（可选）

步骤1：克隆和设置

克隆仓库

git clone 
cd MCP_POC

创建虚拟环境

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

安装依赖项

pip install -r requirements.txt

步骤2：配置环境 在项目根目录中创建.env文件：

必需

API_KEY=your_api_key

Ollama配置

OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=llama2

谷歌日历（可选）

GOOGLE_CALENDAR_CREDENTIALS_FILE=path/to/credentials.json
GOOGLE_CALENDAR_TOKEN_FILE=./token.json

Amadeus API（可选，用于真实飞行数据）

AMADEUS_API_KEY=your_amadeus_key
AMADEUS_API_SECRET=your_amadeus_secret

API终点

OPEN_METEO_BASE_URL=https://api.open-meteo.com/v1

______________________________________________________________________

⚙️ 配置

• 环境变量
• 变量所需描述
• API_密钥✅ 是API主密钥
• OLLAMA_模型❌ 无LLM模型（默认：llama2）
• AMADEUS_API_KEY❌ 没有Amadeus航班API密钥
• GOOGLE_CALENDAR_CREDENTIALS_FILE❌ 没有Google OAuth凭据
• 谷歌日历设置
• 在Google Cloud控制台创建凭据

下载OAuth 2.0证书JSON

放入项目并更新.env

首次运行将触发OAuth身份验证

💻 用法

启动MCP服务器

# Direct execution (Python)
python server/mcp_server.py

服务器监听stdin/stdout

已准备好接收JSON-RPC请求

使用Streamlit UI

# Start the Streamlit app
streamlit run app_mcp.py

开放时间：http://localhost:8501

以编程方式使用MCP客户端

python
from client.mcp_client import MCPClientSync

初始化客户端

client = MCPClientSync("server/mcp_server.py")
client.start()

列出可用工具

tools = client.list_tools()
print(f"Available tools: {len(tools)}")

调用工具

result = client.call_tool("search_flights", {
    "origin": "JFK",
    "destination": "LAX",
    "departure_date": "2024-12-01"
})

列出资源

resources = client.list_resources()

获取提示

prompts = client.list_prompts()
prompt_text = client.get_prompt("plan_vacation", {
    "destination": "Paris",
    "days": 5,
    "interests": "art and food"
})

client.stop（） 🔌 api参考 JSON-RPC请求格式 所有请求均遵循JSON-RPC 2.0规范：

json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}
Response Format
json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [...]
  }
}

可用方法

工具

• 工具/列表-列出所有可用工具
• tools/call-执行特定工具

资源

• resources/list-列出所有资源
• resources/read-通过URI读取特定资源

提示

• promises/list-列出所有提示模板
• promises/get-生成特定提示

______________________________________________________________________

📖 例子

示例1：搜索航班

python
client.call_tool("search_flights", {
    "origin": "JFK",
    "destination": "LAX",
    "departure_date": "2024-12-01",
    "max_results": 5
})

Response:
json
{
  "flights": [
    {
      "id": "MOCK001",
      "airline": "Mock Air",
      "departure": "2024-12-01T08:00:00",
      "arrival": "2024-12-01T11:30:00",
      "price": "$299.00"
    }
  ]
}

示例2：获取天气预报

python
client.call_tool("get_weather", {
    "latitude": 40.7128,
    "longitude": -74.0060,
    "days": 5
})

示例3：生成假期计划

python
prompt = client.get_prompt("plan_vacation", {
    "destination": "Tokyo",
    "days": 7,
    "interests": "technology, food, culture"
})

示例4：访问知识资源

python
 Read travel tips
tips = client.read_resource("knowledge://travel_tips")

 Read destination info
destinations = client.read_resource("knowledge://destinations")

 Read booking policy
policy = client.read_resource("knowledge://booking_policy")