使用说明

AI酒店MCP服务器

用于具有混合数据库架构的人工智能驱动酒店预订系统的生产质量MCP（模型上下文协议）服务器。

🎯 项目概述

该项目展示了一个智能酒店管理系统，其中“Poe”是一个人工智能实体，可以协调运营，从客人互动中学习，并做出自主决策。该系统通过实时性能基准测试展示了混合数据库架构的好处。

主要特点

30+MCP工具：通过克劳德代码完成酒店运营
混合式结构：PostgreSQL+MongoDB+Redis协同工作
实时基准测试：实时性能比较显示缓存性能提高了10-20倍
真实数据：100位客人，500次预订，1000+次对话可供测试
12个核心查询：PDF规范中的所有SQL查询
AI决策跟踪：完成学习循环实施

📊 数据库体系结构

┌─────────────┐     ┌──────────────┐     ┌─────────┐
│ PostgreSQL  │────▶│ MCP Server   │────▶│  Redis  │
│ (ACID Data) │     │  (Python)    │     │ (Cache) │
└─────────────┘     └──────────────┘     └─────────┘
                           │
                           ▼
                    ┌──────────────┐
                    │   MongoDB    │
                    │ (Documents)  │
                    └──────────────┘

数据库角色

PostgreSQL：交易数据（10个表：客人、房间、预订、AIPersonality、AIConvertation、AIDecision、AIMemory、客人资料、传感器数据、主动行动）
MongoDB：灵活的文档存储（带有嵌套消息的对话记录，内容丰富的AI记忆）
瑞迪斯：超快缓存层（访客偏好、最近情绪、传感器读数）

🚀 快速开始

先决条件

Docker&Docker编写
Python 3.11+
克劳德代码（适用于MCP客户端）

1.启动数据库

# Start all services (PostgreSQL, MongoDB, Redis)
docker-compose up -d

# Verify all services are healthy
docker ps

# Check logs
docker-compose logs -f postgres
docker-compose logs -f mongodb
docker-compose logs -f redis

2.验证数据库设置

# Connect to PostgreSQL
docker exec -it hotel-ai-postgres psql -U hotel_admin -d hotel_ai

# List tables (should show 10 tables)
\dt

# Check sample data
SELECT COUNT(*) FROM Guest;  -- Should show 100
SELECT COUNT(*) FROM Booking;  -- Should show 500
SELECT COUNT(*) FROM AIConversation;  -- Should show 1000

\q

# Connect to MongoDB
docker exec -it hotel-ai-mongodb mongosh -u hotel_admin -p hotel_password_2026 --authenticationDatabase admin

use hotel_ai
show collections  -- Should show: conversations, ai_memories
db.conversations.countDocuments()  -- Should show at least 1
exit

# Connect to Redis
docker exec -it hotel-ai-redis redis-cli
PING  -- Should return PONG
exit

3.安装Python依赖项

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

# Install dependencies
pip install -r requirements.txt

4.配置环境

# Copy example environment file
cp .env.example .env

# Edit .env if needed (defaults should work with Docker)
# For local Docker: hosts are already set to localhost

5.运行MCP服务器

# Start MCP server (connects via stdio to Claude Code)
python src/main.py

# Or run in background
nohup python src/main.py > mcp_server.log 2>&1 &

在Claude代码中配置：

添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "hotel-ai": {
      "command": "python",
      "args": ["/absolute/path/to/HotelAiProject/src/main.py"],
      "env": {
        "POSTGRES_HOST": "localhost",
        "POSTGRES_PORT": "5432",
        "MONGO_HOST": "localhost",
        "REDIS_HOST": "localhost"
      }
    }
  }
}

测试MCP连接：

在Claude Code中，您应该看到19个可用的工具：

13个查询工具（12个来自PDF+get_guest.profile）
6个测试/基准测试工具

📁 项目结构

hotel-ai-mcp-server/
├── docker-compose.yml                 # Multi-container orchestration
├── .env.example                       # Environment template
├── README.md                          # This file
├── requirements.txt                   # Python dependencies
│
├── docker/                            # Docker configuration
│   ├── postgres/init/                 # PostgreSQL initialization
│   │   ├── 01-create-schema.sql      # 10 tables (exact from PDF)
│   │   ├── 02-create-indexes.sql     # 14 performance indexes
│   │   └── 03-seed-data.sql          # Realistic sample data
│   └── mongodb/init/                  # MongoDB initialization
│       └── init-collections.js       # Conversation & memory collections
│
├── src/                               # Source code
│   ├── main.py                       # MCP server entry point ✅
│   ├── config.py                     # Configuration management ✅
│   ├── database/                     # Database clients
│   │   ├── postgres_client.py        # PostgreSQL (12 queries) ✅
│   │   ├── mongodb_client.py         # MongoDB operations ✅
│   │   ├── redis_client.py           # Redis caching ✅
│   │   └── models.py                 # Pydantic models ✅
│   └── mcp/                          # MCP implementation
│       ├── server.py                 # MCP server setup ✅
│       └── tools/                    # MCP tools
│           ├── query_tools.py        # 13 query tools ✅
│           └── testing_tools.py      # 6 benchmark tools ✅
│
└── tests/                            # Test suite
    └── test_database_clients.py      # Database tests ✅

🗄️ 数据库模式

PostgreSQL表（10个表）

核心酒店数据：

Guest：100位拥有个人资料的客人
Room150个房间（10层×15个房间）
Booking：500个预订（350个已完成，50个正在进行，100个未来）

AI核心：

AIPersonality：Poe的配置（学习率=0.75）
AIConversation：1000个带有情绪分析的对话
AIDecision：1000个自主决策（约85%的成功率）
AIMemory：500个关于客人、模式、事件的回忆

人工智能：

GuestProfile：100个带有偏好的AI生成配置文件
SensorData：10000+传感器读数（过去7天）
ProactiveAction：500个自主服务操作

指标（14个战略指标）

PDF第4.4节中的所有索引均已实现：

访客资料快速检索（<100ms）
对话时间表
传感器时间序列
决策分析
记忆检索
房间可用性
还有8个。..

🔧 配置

编辑 .env 自定义配置文件：

# Toggle Redis for benchmarking
REDIS_ENABLED=true  # Set to false to test without cache

# Cache TTLs
CACHE_TTL_GUEST_PREFERENCES=3600  # 1 hour
CACHE_TTL_RECENT_SENTIMENT=1800   # 30 minutes
CACHE_TTL_SENSOR_DATA=60          # 60 seconds

# Benchmark iterations
BENCHMARK_ITERATIONS=100

📊 样品数据

该系统包括用于即时测试的真实样本数据：

100位客人：频繁（10）、定期（10）和新客人（80）的组合
150间客房：10层楼共有4种类型（单人、双人、套房、豪华）
500预订：70%人工智能分配，30%手动
- 350已完成（过去6个月）
- 50个活动（当前已签入）
- 100未来（已确认）
1000对话：各种话题、情绪、渠道
1000个人工智能决策：5种类型，成功率85%
100位客人资料：JSON偏好和行为模式
10000+传感器读数：温度、占用率、声音、光线、门状态
500项主动行动：有客人反馈
500个AI记忆：链接到客人、预订、对话

🎯 MCP工具（19种可用工具）

查询工具（13个工具）

来自PDF第4.3节（12个查询）：

✅ search_available_rooms -查找日期范围内的房间
✅ get_recent_conversations -对话历史
✅ get_ai_decision_success_rate -性能指标
✅ find_low_satisfaction_guests -需要关注的高危客人
✅ get_proactive_action_counts -动作类型频率
✅ get_guest_stay_history -完整的预订历史记录
✅ get_recent_sensor_data -物联网传感器读数
✅ count_successful_decisions_month -每月成功次数
✅ compare_ai_vs_manual_bookings -人工智能与手动分配
✅ get_recent_memory_access -最近访问的内存
✅ find_high_confidence_failures -学习机会
✅ get_proactive_actions_per_guest -每位活跃客人的行动

奖金： 13. ✅ get_guest_profile -配置文件与缓存演示

测试/基准测试工具（6个工具）

✅ benchmark_query_with_redis -使用缓存进行测量
✅ benchmark_query_without_redis -无缓存测量
✅ compare_redis_performance -Redis并排比较（显示10-20倍的加速）
✅ validate_performance_requirements -检查<100ms/<500ms SLA
✅ get_cache_statistics -Redis统计数据（命中率、内存）
✅ clear_redis_cache -清除缓存以进行测试

示例用法

# Find available rooms
User: "Show me available Double rooms for March 1-5, 2026"
→ Calls: search_available_rooms(check_in_date="2026-03-01", check_out_date="2026-03-05", room_type="Double")

# Benchmark Redis performance
User: "Prove that Redis improves performance for guest profile retrieval"
→ Calls: compare_redis_performance(guest_id=1, iterations=100)
→ Result: "12.1x faster with Redis (12ms vs 145ms), 92% latency reduction"

# Find at-risk guests
User: "Which guests need proactive attention right now?"
→ Calls: find_low_satisfaction_guests(threshold=3.0)

# Validate SLAs
User: "Are we meeting our performance requirements?"
→ Calls: validate_performance_requirements(guest_id=1, iterations=50)

🧪 测试

手动数据库测试

# Test PostgreSQL queries
docker exec -it hotel-ai-postgres psql -U hotel_admin -d hotel_ai -c "
SELECT r.room_number, r.room_type, r.floor
FROM Room r
WHERE r.status = 'Available'
  AND r.room_type = 'Double'
LIMIT 5;
"

# Test MongoDB queries
docker exec -it hotel-ai-mongodb mongosh -u hotel_admin -p hotel_password_2026 --authenticationDatabase admin --eval "
db = db.getSiblingDB('hotel_ai');
db.conversations.findOne();
"

# Test Redis
docker exec -it hotel-ai-redis redis-cli PING

绩效基准（预期）

基于PDF规范：

操作	无Redis	有Redis	改进
访客资料检索	145毫秒	12毫秒	快12.1倍
房间搜索	285毫秒	N/A	索引优化
对话历史	420ms（关系型）	95ms（MongoDB）	快4.4倍

📖 文档

基于PDF规范

此实现遵循以下完整的数据库设计： DB_Semesterprojekt_AI_Hotel.pdf

实施的关键部分：

第2节：需求分析（100%）
第3节：信息建模（ER图，10个实体）
第4节：关系实现（10个表，12个查询，14个索引）
第5节：NoSQL讨论（MongoDB+Redis集成）

架构决策

PostgreSQL用于事务处理：预订符合ACID标准，确保无重复预订
MongoDB用于对话：嵌套消息数组，AI进化的灵活模式
Redis缓存：对频繁读取的数据进行低于1000毫秒的访问

🐛 故障排除

数据库连接问题

# Check service health
docker-compose ps

# Restart services
docker-compose restart postgres mongodb redis

# View logs
docker-compose logs postgres

端口冲突

如果端口5432、27017或6379已在使用中：

# Edit docker-compose.yml and change ports:
ports:
  - "5433:5432"  # PostgreSQL
  - "27018:27017"  # MongoDB
  - "6380:6379"  # Redis

然后更新 .env:

POSTGRES_PORT=5433
MONGO_PORT=27018
REDIS_PORT=6380

🔄 开发状态

✅ 第1-3阶段：基础设施和数据库层（完成）

[x] Docker基础架构（PostgreSQL、MongoDB、Redis）
[x] 数据库模式（10个表，精确来自PDF）
[x] 指标（14个战略指标）
[x] 样本数据生成（100位客人，500次预订，1000+件商品）
[x] 带验证的MongoDB集合
[x] 配置管理
[x] 用于类型安全的Pydantic模型
[x] 数据库客户端（PostgreSQL、MongoDB、Redis）
[x] 数据库客户端测试（全部通过✓)

✅ 阶段4-6:MCP服务器核心（完成）

[x] 带stdio传输的MCP服务器
[x] 13个查询工具（12个来自PDF+get_guest.profile）
[x] 6个性能基准测试工具
[x] Redis缓存旁模式，带切换
[x] 所有数据库的连接池

📊 当前能力

总计：19个MCP工具就绪

查询操作：13个工具
测试/基准测试：6个工具
性能：缓存时间<100ms，查询时间<500ms
样本数据：100位客人，500次预订，1000+次对话

📋 未来增强功能（可选）

[]变异工具（create_booking、log_ai_desion等）
[]分析工具（趋势、准确性分析）
[]MCP资源（可浏览数据）
[]MCP提示（交互模板）
[]用于监视的Web UI
[]附加单元测试

📝 许可证

这是一个演示数据库设计和MCP服务器实现的学术项目。

🤝 贡献

这是一个学期项目。如有疑问或建议，请打开一个问题。

📚 参考文献

MCP Python SDK
PostgreSQL 15文档
MongoDB 7.0文档
Redis文档
PDF规范： DB_Semesterprojekt_AI_Hotel.pdf

内置： Python、PostgreSQL、MongoDB、Redis、Docker、MCP SDK 目的： 展示人工智能驱动的酒店运营的混合数据库架构作者伊亚德·埃尔维 机构： PSE硕士KnowledgeFoundation@HSReutlingen