美食旅游MCP服务器
A. 模型上下文协议（MCP）服务器 为AI客户提供餐厅搜索和食物推荐工具。该服务器与Google Places API集成，向人工智能应用程序提供实时餐厅数据。
🎯 什么是MCP？
模型上下文协议（MCP） 使AI应用程序能够通过标准化的界面访问外部工具和数据源。
- MCP服务器 （本项目）：向人工智能客户展示与食品相关的工具
- MCP客户端 （Claude Desktop，自定义AI代理）：根据用户提示调用我们的工具
原理
User: "Find Italian restaurants near me"
↓
AI Client (Claude/Custom Agent)
↓ (analyzes prompt, decides to call search_restaurants tool)
Our MCP Server
↓ (calls Google Places API)
Real Restaurant Data
↓ (returns structured JSON to AI client)
AI Client formats response for user🚀 特性
- 实时餐厅搜索 使用Google Places API
- 基于位置的过滤 可定制半径
- 菜肴类型过滤 （意大利语、中文等）
- 灵活的参数 （最高结果，价格水平）
- 数据库缓存 为了提高性能
- 全面的测试套件
- 生产就绪架构
📋 先决条件
- Python 3.8或更高版本
- Google Places API密钥(在这里买一个)
- Git
🛠️ 安装
步骤1：克隆存储库
git clone
cd Food-Travel-MCP第二步：创建虚拟环境
# Create virtual environment
python -m venv venv
# Activate it
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate步骤3：安装依赖项
pip install -r requirements.txt步骤4：环境配置
# Copy environment template
cp .env.example .env
# Edit .env file and add your Google Places API key
# Replace "your_google_places_api_key_here" with your actual API key中所需的环境变量 .env:
GOOGLE_PLACES_API_KEY=your_actual_api_key_here
DATABASE_URL=sqlite:///./food_travel.db
DEBUG=false步骤5：初始化数据库
python scripts/init_db.py您应该看到：
Creating database tables...
Database tables created successfully!🧪 测试
快速测试（推荐）
# Run all tests in sequence
python tests/run_all_tests.py单个测试组件
# Test Google Places API integration
python tests/test_components.py
# Test MCP tools functionality
python tests/test_mcp_tools.py使用Pytest（高级）
# Install pytest if not already included
pip install pytest pytest-asyncio
# Run all tests
pytest tests/ -v
# Run with output
pytest tests/ -v -s预期测试输出
✅ 组件测试：验证Google Places API连接和数据格式\ ✅ MCP工具测试：验证工具是否接受参数并返回正确的JSON响应\ ✅ 集成测试：端到端功能验证
🎮 运行服务器
启动MCP服务器
python -m src.food_mcp.server预期产量：
INFO Food Travel MCP Server initialized
INFO Restaurant tools registered
INFO Starting Food Travel MCP Server
[Server running and waiting for MCP client connections...]服务器端点
服务器公开了以下MCP工具：
search_restaurants
根据位置和偏好搜索餐厅。
参数：
location（必填）：“纽约州纽约市”或“40.7128，-74.0060”cuisine_type（可选）：“意大利”、“中国”、“披萨”等。radius_km（可选）：搜索半径，单位为公里（默认值：10）max_results（可选）：返回的最大结果数（默认值：10）
示例响应：
{
"success": true,
"location": "New York, NY",
"total_results": 5,
"restaurants": [
{
"google_place_id": "ChIJ...",
"name": "Tony's Italian Restaurant",
"address": "123 Main St, New York, NY",
"latitude": 40.7128,
"longitude": -74.0060,
"rating": 4.5,
"user_ratings_total": 127,
"price_level": 2,
"types": ["restaurant", "food"]
}
]
}📁 项目结构
Food-Travel-MCP/
├── 📄 README.md # This file
├── 📄 requirements.txt # Python dependencies
├── 📄 .env.example # Environment template
├── 📄 .gitignore # Git ignore rules
│
├── 📁 config/ # Configuration
│ ├── __init__.py
│ └── settings.py # Application settings
│
├── 📁 src/food_mcp/ # Main MCP server package
│ ├── __init__.py
│ ├── server.py # MCP server entry point
│ │
│ ├── 📁 models/ # Database models
│ │ ├── __init__.py
│ │ ├── base.py # Database base & session
│ │ └── restaurant.py # Restaurant cache model
│ │
│ ├── 📁 clients/ # External API clients
│ │ ├── __init__.py
│ │ └── google_places.py # Google Places API client
│ │
│ ├── 📁 services/ # Business logic layer
│ │ ├── __init__.py
│ │ └── restaurant_service.py
│ │
│ └── 📁 tools/ # MCP tool definitions
│ ├── __init__.py
│ └── restaurant_tools.py # Restaurant search tools
│
├── 📁 tests/ # Test suite
│ ├── __init__.py
│ ├── conftest.py # Pytest configuration
│ ├── test_components.py # Component tests
│ ├── test_mcp_tools.py # MCP tools tests
│ └── run_all_tests.py # Test runner
│
└── 📁 scripts/ # Utility scripts
└── init_db.py # Database initialization🔧 开发工作流程
1.开发设置
# Make sure virtual environment is activated
source venv/bin/activate # or venv\Scripts\activate on Windows
# Install development dependencies
pip install -r requirements.txt
# Set up pre-commit hooks (optional)
pip install pre-commit
pre-commit install2.进行更改
# Run tests before making changes
python tests/run_all_tests.py
# Make your changes...
# Run tests again to ensure nothing broke
python tests/run_all_tests.py
# Test server startup
python -m src.food_mcp.server3.添加新工具
- 在中创建工具功能
src/food_mcp/tools/ - 在中注册工具
__init__.py - 在中添加相应的服务逻辑
src/food_mcp/services/ - 在中编写测试
tests/ - 更新文档
🌟 使用示例
使用克劳德桌面
- 安装克劳德桌面
- 在Claude的设置中配置MCP服务器
- 问：“寻找时代广场附近的意大利餐厅”
使用自定义MCP客户端
# Example client code
import asyncio
from mcp_client import MCPClient
async def find_restaurants():
client = MCPClient("food-travel-mcp")
result = await client.call_tool(
"search_restaurants",
location="San Francisco, CA",
cuisine_type="Italian",
max_results=5
)
print(result)🚧 当前阶段：第一阶段-基本餐厅搜索
✅ 完成
- \[x\] 生产就绪项目结构
- \[x\] Google Places API集成
- \[x\] 基本餐厅搜索工具
- \[x\] 数据库模型和缓存结构
- \[x\] 全面的测试套件
- \[x\] 错误处理和验证
🔄 进行中
- \[\]数据库缓存实现
- \[\]性能优化
- \[\]其他餐厅工具（菜单、评论）
📅 未来阶段
- 第2阶段：用户个性化与现有后端集成
- 第三期：菜单数据和订购功能
- 阶段4：增强的AI功能和趋势分析
- 阶段5：生产部署和监控
🐛 故障排除
常见问题
导入错误： ModuleNotFoundError: No module named 'src'
# Make sure you're running from project root
cd Food-Travel-MCP
python scripts/init_db.pyGoogle Places API错误
# Check your API key in .env file
cat .env | grep GOOGLE_PLACES_API_KEY
# Verify API key has Places API enabled in Google Console数据库问题
# Reinitialize database
rm food_travel.db # if using SQLite
python scripts/init_db.py测试失败
# Check API key configuration
python -c "from dotenv import load_dotenv; import os; load_dotenv(); print('API Key configured:', bool(os.getenv('GOOGLE_PLACES_API_KEY')))"
# Run individual test components
python tests/test_components.py📞 支持
对于问题和疑问：
- 检查上面的故障排除部分
- 检查测试输出是否存在特定错误
- 确保满足所有先决条件
- 验证Google Places API密钥是否有效并具有适当的权限
🎉 快速入门摘要
# 1. Setup
git clone && cd Food-Travel-MCP
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
# 2. Configure
cp .env.example .env
# Edit .env with your Google Places API key
# 3. Initialize
python scripts/init_db.py
# 4. Test
python tests/run_all_tests.py
# 5. Run
python -m src.food_mcp.server🎯 您已准备好与AI客户端集成，并开始寻找餐厅！