360 Ghar - Real Estate MCP Server

360 Ghar バックエンド

360 Ghar の統合不動産プラットフォームを支える、高性能でモダンなバックエンドです。FastAPI と PostgreSQL で構築されており、次の 3 つの統合モジュールに API を提供します。

• 360 Ghar Core：スワイプによる物件検索、物件見学、エージェントとの調整機能を備えた、物件の購入・賃貸向け不動産マーケットプレイス
• 360 Stays：ホテル、バケーションレンタル、一時滞在先向けの短期滞在予約プラットフォーム
• Property Management：家主や物件管理者向けの総合的な物件管理システム（賃貸契約、家賃回収、メンテナンス、レポート）

目次

• プロジェクトについて
• 主な機能
• 技術スタック
• プロジェクト構成
• API エンドポイント
• はじめに
• Docker で実行する
• 環境設定
• API ドキュメント
• MCP HTTP サーバー
• 主な実装の詳細
• コントリビューション
• ライセンス

プロジェクトについて

360 Ghar は、物件のライフサイクル全体を支える統合不動産プラットフォームです。

• 360 Ghar Core は、使いやすいスワイプ式インターフェースに強力な地図ベースの検索機能と、物件の購入・賃貸を支援するプロのエージェントによるサポートを組み合わせ、物件探しを一新します。
• 360 Stays は、ホテルやバケーションレンタル向けに、空室確認、動的料金設定、ゲスト管理を備えた総合的な短期滞在予約システムを提供します。
• Property Management は、テナント管理、賃貸契約の追跡、家賃回収、メンテナンス対応、財務レポートのためのツールを家主や物件管理者に提供します。

3 つのモジュールはすべて、共通のバックエンドインフラストラクチャ、ユーザー認証、物件データベースを共有しています。

概要動画

プラットフォームの 6 つのモジュールとアーキテクチャを紹介する、2〜3 分の音声なしの解説動画です。Wiki 全編をご覧ください。

主な機能

360 Ghar Core（不動産マーケットプレイス）

• Tinder のような物件スワイプ：直感的なスワイプ操作で、物件への「いいね」またはスキップができます
• 高度な物件検索：地理空間検索、全文検索、フィルター検索に対応した統合エンドポイント
• 物件見学のスケジュール調整：エージェントが管理する見学調整と自動割り当て
• エージェント管理：負荷分散やパフォーマンス追跡を備えた包括的なエージェントシステム
• ユーザーに合わせたパーソナライズ：ユーザーの操作や検索履歴から好みを学習

360 Stays（短期滞在予約）

• 短期滞在予約：空室確認と料金設定を備えた総合的な予約システム
• 動的料金設定：日ごとの料金と最低宿泊日数を設定可能
• ゲスト管理：予約からチェックアウトまでの予約ライフサイクルを管理

Property Management

• テナント・賃貸契約管理：テナント、賃貸契約、賃貸申込を追跡
• 家賃回収：請求の生成と支払いの追跡に対応した、手動処理を優先する家賃台帳
• メンテナンス依頼：物件の維持管理に向けた作業指示を管理
• 書類保管庫：賃貸契約書、領収書、物件関連書類を安全に保管
• 財務レポート：賃料一覧、損益計算書、損益、稼働率レポート

技術的な特長

• モダンで高速：高いパフォーマンスと自動 API ドキュメント生成を実現する FastAPI を使用
• 完全な非同期処理：API からデータベース操作まで、非同期アーキテクチャを採用
• 地理空間機能：位置情報に基づく効率的なクエリに PostgreSQL + PostGIS を使用
• セキュアな認証：電話番号を主な認証方式とする Supabase Auth 連携
• パフォーマンス最適化：PgBouncer との互換性とスケーラブルな接続プーリングを考慮して設計
• 本番環境対応：Sentry 連携、包括的なログ記録、エラー処理
• コンテナ化：開発向けの Docker Compose を含む、完全な Docker サポート

技術スタック

カテゴリ	技術
バックエンドフレームワーク	FastAPI
データベース	PostgreSQL + PostGIS
ORM	SQLAlchemy 2.0+ (Async)
データ検証	Pydantic
認証	Supabase Auth
キャッシュ	Redis（オプション）
マイグレーション	Supabase Migrations
可観測性	Sentry
コンテナ化	Docker と Docker Compose
地理空間	GeoAlchemy2

プロジェクト構成

app/
├── api/                 # API endpoints and routing
│   └── api_v1/
│       └── endpoints/   # Individual endpoint modules
├── config/              # Compatibility config package; implementation remains in core/config.py
├── core/                # Core components (config, db, auth, logging)
├── infrastructure/      # App factory helpers, adapters, lifespan, middleware wiring
├── middleware/          # Custom middleware (rate limiting, security)
├── models/              # SQLAlchemy ORM models and enums  
├── modules/             # Reserved namespace for future physical domain packages
├── schemas/             # Pydantic schemas for data validation
├── services/            # Business logic and database operations (legacy implementation layer)
├── shared/              # Reserved namespace for future physical shared packages
└── utils/               # Utility functions

supabase/
└── migrations/          # Database schema migrations

populate_data/           # Legacy data files (preserved for reference)
seed_data/               # Data seeding system (hardcoded, seed, generated categories)
tests/                   # Test files

API エンドポイント

すべてのエンドポイントには /api/v1 がプレフィックスとして付きます。

🔑 認証モデル

• クライアントは Supabase Auth SDK を使って直接認証します（電話番号が優先、メールアドレスは任意）。
• 保護されたルートでは、バックエンドは Authorization: Bearer <supabase_access_token> を想定します。
• バックエンドは /api/v1/auth/* ユーザーセッションエンドポイントを公開しなくなりました。

👤 ユーザー（/users）

• GET /profile/：現在のユーザープロフィールを取得
• PUT /profile/：ユーザープロフィール情報を更新
• PUT /preferences/：物件検索の設定を更新
• PUT /location/：ユーザーの現在地を更新

🏠 物件（/properties）

• GET /：地理空間検索、テキスト検索、高度な絞り込みを統合した物件検索
• GET /recommendations/：ユーザーに合わせた物件のおすすめを取得
• GET /{property_id}/：物件の詳細情報を取得
• POST /：新しい物件を作成（認証済みユーザー）
• PUT /{property_id}/：物件を更新（物件の所有者）
• DELETE /{property_id}/：物件を削除（物件の所有者）

↔️ スワイプ（/swipes）

• POST /：物件のスワイプ（いいね／パス）を記録
• GET /：詳細な検索・絞り込み機能を備えたスワイプ履歴を取得
• DELETE /undo/：最後のスワイプ操作を取り消し
• PUT /{swipe_id}/toggle/：スワイプ済み物件の「いいね」状態を切り替え
• GET /stats/：ユーザーのスワイプ統計を取得

📅 内見（/visits）

• POST /：物件の内見を予約
• GET /：ユーザーの内見一覧を取得（すべて／今後／過去）
• GET /{visit_id}/：内見の詳細を取得
• POST /reschedule/：既存の内見を再予約
• POST /cancel/：予約済みの内見をキャンセル

🏨 予約（/bookings）

• POST /：短期滞在の予約を作成
• GET /：ユーザーの予約一覧を取得
• GET /{booking_id}/：予約の詳細を取得
• POST /check-availability/：物件の空き状況を確認
• POST /calculate-pricing/：予約料金の内訳を取得
• POST /cancel/：予約をキャンセル

🧑‍💼 エージェント（/agents）

• GET /assigned/：ユーザーに割り当てられたエージェントを取得
• POST /assign/：ユーザーにエージェントを割り当て（エージェントが指定されていない場合は自動割り当て）
• GET /available/：対応可能なエージェント一覧を取得
• GET /{agent_id}/：エージェントの詳細を取得
• GET /{agent_id}/stats/：エージェントの業績統計を取得

🏢 プロパティ管理 (/pm)

• /pm/dashboard：ポートフォリオの概要と指標
• /pm/properties：管理対象のプロパティの CRUD
• /pm/tenants：テナント一覧
• /pm/applications：賃貸申し込みとフォーム
• /pm/leases：リース管理
• /pm/rent：家賃の請求と支払い
• /pm/expenses：経費の追跡
• /pm/maintenance：メンテナンスの依頼
• /pm/documents：ドキュメント保管庫
• /pm/inspections：プロパティの検査
• /pm/reports：財務レポート

はじめに

前提条件

• Python 3.12+
• Docker と Docker Compose
• 認証用の Supabase プロジェクト

ローカル開発環境のセットアップ

1. リポジトリをクローンします：

   git clone https://github.com/your-username/360ghar-backend.git
   cd 360ghar-backend
   

2. 依存関係をインストールします：

   オプション A：uv を使用（推奨）

   # Install uv if not already installed
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # Install dependencies (reads pyproject.toml)
   uv sync
   

   オプション B：pip を使用

   # Create virtual environment
   python -m venv .venv
   
   # Activate it (Linux/Mac)
   source .venv/bin/activate
   # Or on Windows:
   # .venv\Scripts\activate
   
   # Install dependencies
   uv sync
   

   注： このプロジェクトでは、依存関係の管理に uv を使用します。依存関係は pyproject.toml で定義され、uv.lock に固定されています。

3. 環境変数を設定します：

   cp .env.example .env
   

   .env ファイルを編集し、データベース、Supabase、その他の認証情報を設定します。

4. データベースサービスを起動します：

   docker-compose up -d db redis
   

5. データベースのマイグレーションを適用します：

   supabase db push
   

6. サンプルデータを読み込みます（任意）：

   # Load all seed data (hardcoded + generated)
   uv run python seed_data/01_load_all.py
   
   # Quick mode — skip generated activity
   uv run python seed_data/01_load_all.py --only hardcoded,seed
   
   # Clear and reload
   uv run python seed_data/02_clear_data.py --confirm
   uv run python seed_data/01_load_all.py
   

7. アプリケーションを起動します：

   uv を使用する場合（推奨）：

   # Run with uv (no need to activate virtual environment)
   uv run python run.py
   
   # Or using FastAPI CLI with hot reload (recommended for development)
   uv run fastapi dev app/main.py --port 3600 --host 0.0.0.0
   

   pip を使用する場合（仮想環境を有効化した状態）：

   # Run directly
   python run.py
   
   # Or using FastAPI CLI with hot reload (recommended for development)
   fastapi dev app/main.py --port 3600 --host 0.0.0.0
   

API は http://localhost:3600 で利用できます。

💡 開発のヒント：FastAPI CLI を使うと、ホットリロードのパフォーマンスが向上し、開発向けの機能も追加で利用できます。日常的な開発には FastAPI CLI の使用をおすすめします。

MCP HTTP サーバー

バックエンドは、AI アシスタントと MCP 対応クライアント向けに Model Context Protocol（MCP）HTTP サーバーを公開します。

エンドポイント

エンドポイント	用途
/mcp	ユーザー向け MCP サーバー（所有者、テナント、一般ユーザー）
/mcp-admin	管理者向け MCP サーバー（エージェント、管理者）

認証

両サーバーは OAuth 2.1 認証（Supabase 経由の電話番号とパスワード）を使用します：

• 認可： GET /mcp/oauth/authorize（ブラウザベースのログインと同意ページ）
• トークン： POST /mcp/oauth/token
• 認可サーバーのメタデータ： GET /.well-known/oauth-authorization-server/mcp/oauth

クライアントの設定

エンドユーザー向けアプリケーションの場合：

{
  "mcpServers": {
    "ghar360": {
      "transport": "http",
      "url": "https://api.360ghar.com/mcp"
    }
  }
}

エージェント／管理者向けアプリケーションの場合：

{
  "mcpServers": {
    "ghar360-admin": {
      "transport": "http",
      "url": "https://api.360ghar.com/mcp-admin"
    }
  }
}

設定後、クライアントはブラウザーで OAuth フローを開始します。認可されると、MCP 経由でプロパティ検索、スワイプ、内見のスケジュール設定などのツールを呼び出せます。

Docker で実行する

スタック全体をコンテナ内で実行するには：

# Build and start all services
docker-compose up --build

# Or run in detached mode
docker-compose up -d --build

環境設定

.env.example を基に .env ファイルを作成します：

# Database Configuration
DATABASE_URL=postgresql://username:password@localhost:5432/ghar360

# Supabase Configuration
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_PUBLISHABLE_KEY=your_publishable_key
SUPABASE_SECRET_KEY=your_service_role_key
# Storage uses Cloudinary (configured via CLOUDINARY_* env vars)

# JWT Configuration
SECRET_KEY=your_jwt_secret_key
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

# Optional Services
REDIS_URL=redis://localhost:6379
SENTRY_DSN=your_sentry_dsn_here
ENABLE_SENTRY_TEST_ENDPOINT=false

# Environment
ENVIRONMENT=development
 
# Push Notifications (FCM + Supabase)
FIREBASE_PROJECT_ID=your_firebase_project_id
GOOGLE_APPLICATION_CREDENTIALS=/absolute/path/to/service-account.json
ENABLE_NOTIF_SCHEDULER=false
NOTIF_SCHED_TZ=Asia/Kolkata

# Vector Embeddings / Semantic Search
GOOGLE_API_KEY=
GEMINI_EMBED_MODEL=gemini-embedding-2
VECTOR_SYNC_ENABLED=true
# Either provide CRON schedule or interval seconds (defaults to CRON below)
VECTOR_SYNC_CRON=*/10 * * * *
VECTOR_SYNC_INTERVAL_SECONDS=300
VECTOR_SYNC_BATCH_SIZE=500
VECTOR_SYNC_MAX_RETRIES=3

### One-time backfill
Run a single incremental sync pass (first run will process all properties):

```bash
uv run python -m app.vector.backfill

このサービスは property_embeddings テーブル（pgvector）を作成し、vector_sync_state で増分処理の進行状況を追跡します。

## API Documentation

Once running, access the interactive API documentation:

- **Swagger UI**: [http://localhost:3600/api/v1/docs](http://localhost:3600/api/v1/docs)
- **ReDoc**: [http://localhost:3600/api/v1/redoc](http://localhost:3600/api/v1/redoc)
- **OpenAPI YAML**: [http://localhost:3600/api/v1/openapi.yaml](http://localhost:3600/api/v1/openapi.yaml)

Additional endpoints:
- **Health Check**: [http://localhost:3600/health](http://localhost:3600/health)
- **Config Info**: [http://localhost:3600/config](http://localhost:3600/config)

### Notifications API

- `POST /api/v1/notifications/devices/register` — Register or refresh device token (uses auth header when present)
- `POST /api/v1/notifications/send/token` — Send to a single token (admin only)
- `POST /api/v1/notifications/send/user` — Send to all tokens for a user (admin only)
- `POST /api/v1/notifications/send/topic` — Broadcast to an FCM topic (admin only)
- `POST /api/v1/notifications/send/bulk` — Bulk send to up to 500 tokens (admin only)
- `POST /api/v1/notifications/deliveries/{delivery_id}/opened` — Mark a delivery as opened

## Key Implementation Details

### Authentication System
- **Phone-First Authentication**: Uses phone numbers as primary identifiers with Supabase Auth
- **JWT Token Validation**: Local token verification for optimal performance
- **Flexible Verification**: Supports both email and phone verification
- **User Sync**: Automatic synchronization between Supabase and local database

### Database Architecture
- **Async SQLAlchemy 2.0+**: Modern async database operations
- **PostGIS Integration**: Efficient geospatial queries with proper indexing
- **PgBouncer Ready**: Configured for production connection pooling
- **Full-Text Search**: PostgreSQL native text search capabilities
- **Comprehensive Indexing**: Optimized indexes for common query patterns

### Property Search System
- **Unified Search Endpoint**: Single endpoint supporting multiple search types
- **Geospatial Optimization**: PostGIS `ST_DWithin` for radius-based searches
- **Full-Text Search**: PostgreSQL TSVECTOR for relevant text matching
- **Semantic Search**: Hybrid vector + text relevance scoring for richer discovery
- **Advanced Filtering**: Support for 25+ property filters
- **Pagination**: Efficient cursor-based pagination for large datasets
- **Endpoints**: `GET /api/v1/properties` (set `semantic_search=true&q=` for hybrid) and `GET /api/v1/properties/semantic-search` (pure semantic + filters)

### Agent Management
- **Auto-Assignment**: Round-robin agent assignment based on workload
- **Load Balancing**: Distributes users across available agents
- **Performance Tracking**: Comprehensive agent statistics and metrics
- **Availability Management**: Real-time agent availability tracking

### Performance Optimizations
- **Async Throughout**: Non-blocking operations from API to database
- **Efficient Queries**: Optimized database queries with proper joins and indexes
- **Caching Ready**: Redis integration for caching expensive operations
- **Error Handling**: Comprehensive error handling with Sentry integration

## Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

---

**360 Ghar Development Team** - [[email protected]](mailto:[email protected])

Project Link: [https://github.com/your-username/360ghar-backend](https://github.com/your-username/360ghar-backend)