Villa Ops AI

VillaOps AI

巴厘岛别墅和酒店物业经理的人工智能运营助理。与人工智能代理聊天，该代理可以查询预订、管理酒店、联系客人并提供分析——所有这些都是通过LangGraph和MCP支持的自然语言完成的。

现场演示： villaops.esakrissa.com | API文件： villaops.esakrissa.com/docs

______________________________________________________________________

主要特点

• AI聊天工具调用 --LangGraph代理通过Streamable HTTP连接到8个MCP工具，具有实时SSE流响应
• 完整SaaS计费 --Stripe Checkout、客户门户、webhook驱动的订阅生命周期（免费/专业/业务层）
• 计划门控使用限制 --中间件强制执行属性限制、AI查询配额和每个计划的功能访问
• 多提供商OAuth --Google+GitHub OAuth以及使用JWT令牌的电子邮件/密码注册
• 实时分析仪表板 --使用Recharts构建的入住率、收入趋势和预订图表
• 多提供商LLM网关 --LiteLLM路由到Gemini（默认），Anthropic和OpenAI作为回退，加上响应缓存
• 262次测试，覆盖率82% -跨身份验证、计费、代理、MCP工具和API端点的全面测试套件
• 具有目标部署的CI/CD --GitHub Actions管道，仅通过代码更改重建和部署服务
• 部署在AWS ECS Fargate上 --使用RDS PostgreSQL、ElastiCache Redis和Cloudflare SSL的生产基础设施

______________________________________________________________________

截图

______________________________________________________________________

它的作用

物业经理可以简单地问：

• *“显示明天的所有签到”*
• *“为约翰预订日落别墅，2月10日至15日”*
• *“我们这个月的入住率是多少？”*
• *“向明天抵达的旅客发送入住说明”*
• *“取消预订#1234”*
• *“巴厘岛这个周末的天气预报是什么？”*

AI代理理解意图，选择正确的MCP工具，执行它，并通过聊天界面实时流式传输结果。

______________________________________________________________________

建筑

应用架构

┌────────────────────────────────────────────────────────────┐
│                    Next.js Frontend                        │
│                                                            │
│  ┌────────┐  ┌────────┐  ┌───────────┐  ┌───────────────┐  │
│  │  Auth  │  │Pricing │  │  Chat UI  │  │   Dashboard   │  │
│  │  Pages │  │  Page  │  │  (SSE)    │  │  (Bookings/   │  │
│  │        │  │        │  │           │  │   Analytics)  │  │
│  └────────┘  └────────┘  └───────────┘  └───────────────┘  │
└────────┬───────────────────────────────────────────────────┘
         │ REST + SSE
         ▼
┌────────────────────────────────────────────────────┐
│              FastAPI Backend                       │
│                                                    │
│  ┌──────────────────────────────────────────────┐  │
│  │  Auth: JWT + Google OAuth + GitHub OAuth     │  │
│  └──────────────────────────────────────────────┘  │
│                                                    │
│  ┌──────────────────────────────────────────────┐  │
│  │  Billing: Stripe Checkout + Webhooks         │  │
│  │  Plan gating middleware (usage limits)       │  │
│  └──────────────────────────────────────────────┘  │
│                                                    │
│  ┌──────────┐  ┌────────────────────────────────┐  │
│  │ REST API │  │  Chat API (SSE streaming)      │  │
│  │ /api/v1  │  │  /api/v1/chat                  │  │
│  └────┬─────┘  └──────────┬─────────────────────┘  │
│       │                   │                        │
│       │        ┌──────────▼─────────────────────┐  │
│       │        │   LangGraph Agent              │  │
│       │        │ + MCP Client (Streamable HTTP) │  │
│       │        └──────────┬─────────────────────┘  │
│       │                   │ Streamable HTTP        │
│       │                   ▼                        │
│  ┌────────────────────────────────────────────┐    │
│  │  MCP Server (Streamable HTTP on /mcp)      │    │
│  │  booking_search | booking_create           │    │
│  │  booking_update | booking_analytics        │    │
│  │  guest_lookup   | property_manage          │    │
│  │  send_notification | web_search            │    │
│  └────────────────────────────────────────────┘    │
│                                                    │
│  ┌────────────────────────────────────────────┐    │
│  │  LiteLLM Gateway                           │    │
│  │  Gemini (default) → Claude → GPT           │    │
│  │  + caching + cost tracking + fallback      │    │
│  └────────────────────────────────────────────┘    │
└────────────────────────────────────────────────────┘

┌──────────────────┐  ┌────────────────┐  ┌─────────────┐
│  PostgreSQL      │  │     Redis      │  │   Stripe    │
│  (8 tables)      │  │    (cache)     │  │   Payments  │
└──────────────────┘  └────────────────┘  └─────────────┘

部署架构

                  Cloudflare (SSL + DNS)
                         │
                         ▼
              ┌───────────────────────┐
              │   Nginx (ECS Fargate) │
              │   Reverse Proxy       │
              └──────────┬────────────┘
                         │
           ┌─────────────┼─────────────┐
           ▼             ▼             ▼
    ┌─────────────┐ ┌─────────────┐ ┌──────────────┐
    │   Backend   │ │   Frontend  │ │  MCP Server  │
    │  (FastAPI)  │ │  (Next.js)  │ │  (FastMCP)   │
    │   :8000     │ │   :3000     │ │   :8001      │
    └──────┬──────┘ └─────────────┘ └──────┬───────┘
           │                               │
    ┌──────┴──────┐                 ┌──────┴──────┐
    │     RDS     │                 │ ElastiCache │
    │ PostgreSQL  │                 │    Redis    │
    └─────────────┘                 └─────────────┘

    Service Discovery: AWS Cloud Map (villaops.local)
    CI/CD: GitHub Actions → ECR → ECS (targeted deploy)

______________________________________________________________________

技术栈

______________________________________________________________________

定价

______________________________________________________________________

入门指南

先决条件

• Docker&Docker编写
• Python 3.13+
• Node.js 22+
• 至少一个LLM提供程序（Gemini、Anthropic或OpenAI）的API密钥
• 条纹账户（测试模式）——本地开发人员可选，无需计费

快速入门（Docker）

1. 克隆存储库

   git clone https://github.com/esakrissa/villa-ops-ai.git
   cd villa-ops-ai

1. 配置环境变量

   cp .env.example .env
   # Edit .env with your API keys, OAuth credentials, and Stripe keys

1. 启动所有服务

   docker-compose up --build

这将启动5个服务：FastAPI后端（：8000）、MCP服务器（：8001）、Next.js前端（：3000）、PostgreSQL和Redis。

1. 运行数据库迁移和种子数据

   docker-compose exec backend alembic upgrade head
   docker-compose exec backend python scripts/seed_data.py

1. 启动Stripe webhook侦听器 （可选，用于计费功能）

   stripe listen --forward-to localhost:8000/api/v1/webhooks/stripe

1. 打开应用程序

不使用Docker运行

Backend

cd backend
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Ensure PostgreSQL and Redis are running locally
alembic upgrade head
python scripts/seed_data.py
uvicorn app.main:app --reload

MCP Server

cd backend
source .venv/bin/activate
python -m app.mcp.server

Frontend

cd frontend
npm install
npm run dev

______________________________________________________________________

API概述

身份验证端点

计费端点

REST端点

聊天端点

POST /api/v1/chat
Content-Type: application/json
Accept: text/event-stream
Authorization: Bearer 

{
  "message": "Show me all check-ins for tomorrow",
  "conversation_id": "optional-uuid"
}

将SSE事件与代理响应和工具调用结果流式传输。人工智能查询的使用将计入计划限制。

______________________________________________________________________

MCP工具

LangGraph代理通过Streamable HTTP连接到MCP服务器，可以访问8个工具：

______________________________________________________________________

测试

cd backend

# Run all tests
pytest

# With coverage report
pytest --cov=app --cov-report=term-missing

# Specific test suites
pytest tests/test_api/         # API endpoints
pytest tests/test_auth/        # Authentication (JWT + OAuth)
pytest tests/test_billing/     # Stripe billing lifecycle
pytest tests/test_agent/       # Agent reasoning + tool selection
pytest tests/test_mcp/         # MCP tool edge cases
pytest tests/test_services/    # Business logic

当前统计数据： 262个测试通过，代码覆盖率82%。

______________________________________________________________________

部署

应用程序部署在 AWS云服务器Fargate 通过GitHub Actions实现自动化CI/CD。

基础设施

CI/CD管道

Push to main → CI (lint + test + build) → Deploy (targeted)

• 有针对性的部署 --仅部署具有实际代码更改的服务
• 后端更改→ 重建后端+MCP映像（约8分钟）
• 前端更改→ 仅重建前端图像（约5分钟）
• 无服务更改→ 跳过部署（约1分钟）
• Cloudflare DNS自动更新 --如果nginx公共IP发生变化，部署工作流会更新A记录

______________________________________________________________________

项目结构

villa-ops-ai/
├── backend/
│   ├── app/
│   │   ├── main.py              # FastAPI entry point
│   │   ├── config.py            # Settings (pydantic-settings)
│   │   ├── database.py          # Async SQLAlchemy engine + sessions
│   │   ├── models/              # 8 SQLAlchemy models
│   │   ├── schemas/             # Pydantic request/response schemas
│   │   ├── api/v1/              # REST + Chat + Auth + Billing + Webhook routers
│   │   ├── auth/                # JWT + OAuth (Google, GitHub)
│   │   ├── billing/             # Stripe (checkout, webhooks, plan gating)
│   │   ├── agent/               # LangGraph agent + MCP client
│   │   ├── mcp/                 # MCP server (Streamable HTTP)
│   │   │   ├── server.py
│   │   │   └── tools/           # 8 tool modules
│   │   └── services/            # Business logic layer
│   ├── tests/                   # 262 tests (82% coverage)
│   │   ├── conftest.py
│   │   ├── test_api/
│   │   ├── test_auth/
│   │   ├── test_billing/
│   │   ├── test_agent/
│   │   ├── test_mcp/
│   │   └── test_services/
│   ├── scripts/
│   │   └── seed_data.py         # Idempotent demo data seeder
│   ├── alembic/                 # Database migrations
│   ├── Dockerfile
│   ├── pyproject.toml
│   └── alembic.ini
├── frontend/
│   ├── src/
│   │   ├── app/
│   │   │   ├── (auth)/          # Login, register, OAuth callbacks
│   │   │   ├── pricing/         # Public pricing page
│   │   │   ├── chat/            # Chat interface (SSE streaming)
│   │   │   └── dashboard/       # Bookings, analytics, properties, billing
│   │   ├── components/
│   │   │   ├── auth/            # OAuthButtons, LoginForm, RegisterForm
│   │   │   ├── chat/            # ChatWindow, MessageBubble, ToolCallCard
│   │   │   ├── dashboard/       # BookingTable, OccupancyChart, PropertyCard
│   │   │   ├── billing/         # PricingCard, UsageMeter, PlanBadge
│   │   │   └── ui/              # Header, Sidebar, LoadingSkeleton
│   │   └── lib/                 # API client, auth helpers, hooks
│   ├── Dockerfile
│   └── package.json
├── .aws/                        # AWS ECS infrastructure
│   ├── backend-task-def.json
│   ├── frontend-task-def.json
│   ├── mcp-task-def.json
│   ├── nginx-task-def.json
│   ├── setup-infra.sh
│   └── nginx/                   # Nginx config + Dockerfile
├── .github/workflows/
│   ├── ci.yml                   # CI: lint (ruff+mypy) + test + build
│   └── deploy.yml               # Deploy: targeted ECR + ECS + Cloudflare DNS
├── docker-compose.yml           # Dev: 5 services (frontend + backend + MCP + postgres + redis)
├── .env.example                 # Environment variable template
└── README.md

______________________________________________________________________

环境变量

所有变量均通过配置 .env （参见 .env.example 模板）。

______________________________________________________________________

许可证

麻省理工学院