Real Estate MCP

🚀 不動産MCPサーバー

不動産データ管理用の包括的なモデルコンテキストプロトコル（MCP）サーバーです。このサーバーは、物件リスト、エージェント管理、市場分析、クライアント関係管理、および地域情報に関するツール、リソース、およびプロンプトを提供します。

🚀 クイックスタート

この不動産MCPサーバーを使用するには、以下の手順に従ってください。

インストール

1. リポジトリのクローン

   git clone https://github.com/agentic-ops/real-estate-mcp.git
   cd real-estate-mcp
   

2. 依存関係のインストール

   pip install -r requirements.txt
   

3. サーバーの起動

   python main.py
   

サーバーの使用

サーバーが起動したら、MCPプロトコルを使用してエンドポイントと通信できます。以下は、いくつかの使用例です。

# SSE接続の確立（サーバーメッセージを待機）
curl -N http://127.0.0.1:8000/sse

# MCPメッセージの送信（別のターミナルで）
# 物件を検索
curl -X POST http://127.0.0.1:8000/messages/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "search_properties", "arguments": {"query": "Victorian"}}}'

# 条件でフィルタリング
curl -X POST http://127.0.0.1:8000/messages/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "filter_properties", "arguments": {"min_price": 500000, "max_price": 1000000}}}'

# 市場の概要を取得
curl -X POST http://127.0.0.1:8000/messages/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 3, "method": "resources/read", "params": {"uri": "realestate://market-overview"}}'

# クライアントの嗜好にマッチさせる
curl -X POST http://127.0.0.1:8000/messages/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": {"name": "match_client_preferences", "arguments": {"client_id": "CLI001"}}}'

✨ 主な機能

MCP機能

• 30以上のツール：包括的な不動産業務をサポート
• 10のリソース：5つの静的リソースと5つの動的リソーステンプレート
• 11のプロンプト：4つのカテゴリにわたるユーザー制御の分析テンプレート
• SSEトランスポート：Web互換のServer-Sent Eventsエンドポイント

ツールカテゴリ

🏠 物件管理（7つのツール）

• 複数の条件で物件を検索およびフィルタリング
• 物件の詳細と包括的な洞察を取得
• 地域とエージェントに基づく物件リスト
• 市場コンテキストと比較分析

👥 エージェント業務（6つのツール）

• エージェントのプロフィールと専門分野
• パフォーマンスダッシュボードとメトリクス
• クライアントと物件ポートフォリオの管理
• 販売トラッキングと分析

📊 市場分析（7つのツール）

• 市場の概要と価格分析
• 地域固有の市場パフォーマンス
• 投資機会分析
• 比較地域分析
• 取引トラッキング

🤝 クライアント管理（3つのツール）

• クライアントのプロフィールと嗜好
• 物件マッチングアルゴリズム
• 予算と条件に基づく推薦

🏘️ 地域情報（9つのツール）

• 包括的な地域レポート
• アメニティと人口統計情報
• 学校、公園、ショッピング、医療データ
• 都市の概要と地域比較

⚙️ システム管理（2つのツール）

• データの更新とキャッシュ管理
• システムの統計と要約

リソース

静的リソース

• realestate://all-properties：完全な物件リスト
• realestate://all-agents：エージェントディレクトリ
• realestate://market-overview：現在の市場トレンド
• realestate://all-areas：地域情報
• realestate://amenities：完全なアメニティデータベース

動的リソーステンプレート

• realestate://properties/area/{area}：地域固有の物件
• realestate://agent/{agent_id}/dashboard：エージェントのパフォーマンスダッシュボード
• realestate://market/area/{area}：地域の市場分析
• realestate://property/{property_id}/insights：物件の洞察
• realestate://client/{client_id}/matches：クライアントの物件マッチ

プロンプト（合計11個）

物件プロンプト（2つのプロンプト）

• 物件分析：包括的な物件評価と洞察
• 物件比較：並列の物件比較分析

クライアントプロンプト（3つのプロンプト）

• クライアントマッチング：パーソナライズされた物件推薦
• クライアント相談：構造化された相談フレームワーク
• クライアントフィードバック分析：検索戦略の改善

市場プロンプト（3つのプロンプト）

• 市場レポート：包括的な地域市場分析
• 投資分析：投資収益率と機会評価
• 比較市場分析：複数地域の比較

エージェントプロンプト（3つのプロンプト）

• エージェントパフォーマンス：パフォーマンスダッシュボードと分析
• エージェントマーケティング戦略：ビジネス開発とマーケティング
• エージェントトレーニング開発：スキル向上とトレーニング計画

📦 インストール

1. リポジトリのクローン

   git clone https://github.com/agentic-ops/real-estate-mcp.git
   cd real-estate-mcp
   

2. 依存関係のインストール

   pip install -r requirements.txt
   

3. サーバーの起動

   python main.py
   

💻 使用例

基本的な使用法

# SSE接続の確立（サーバーメッセージを待機）
curl -N http://127.0.0.1:8000/sse

# MCPメッセージの送信（別のターミナルで）
# 物件を検索
curl -X POST http://127.0.0.1:8000/messages/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "search_properties", "arguments": {"query": "Victorian"}}}'

高度な使用法

# 条件でフィルタリング
curl -X POST http://127.0.0.1:8000/messages/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "filter_properties", "arguments": {"min_price": 500000, "max_price": 1000000}}}'

📚 ドキュメント

サーバートランスポート

サーバーはServer-Sent Events (SSE) トランスポートを使用しており、以下と互換性があります。

• WebブラウザとHTTPクライアント
• 従来のMCPクライアント
• カスタム統合

接続詳細

• SSEエンドポイント：http://127.0.0.1:8000/sse（SSE接続の確立用）
• メッセージエンドポイント：http://127.0.0.1:8000/messages/（MCPメッセージの投稿用）
• トランスポート：SSE (Server-Sent Events)
• プロトコル：MCP (Model Context Protocol)

Webクライアントの例

// SSE接続の確立
const eventSource = new EventSource('http://127.0.0.1:8000/sse');
eventSource.onmessage = function(event) {
    const mcpMessage = JSON.parse(event.data);
    // MCPプロトコルメッセージを処理
};

// MCPメッセージの送信
async function sendMCPMessage(message) {
    const response = await fetch('http://127.0.0.1:8000/messages/', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
        },
        body: JSON.stringify(message)
    });
    return response.json();
}

MCPインスペクター

MCPサーバーを検査およびデバッグするには、MCPインスペクターツールを使用できます。

npx @modelcontextprotocol/inspector

これにより、MCPインスペクターインターフェイスが起動し、以下のことができます。

• MCPメッセージをリアルタイムで監視
• ツールとリソースの呼び出しをデバッグ
• サーバーの応答を検査
• サーバーの機能をテスト

🔧 技術詳細

コアコンポーネント

utils.py - データ管理

• RealEstateDataManager：中央データアクセスクラス
• PropertyFilter：検索とフィルタリングユーティリティ
• JSONデータの読み込みとキャッシュ
• 相互参照と関係マッピング

main.py - サーバーエントリポイント

• FastMCPサーバーの初期化
• コンポーネント登録のオーケストレーション
• SSEトランスポートの設定
• 起動ログと診断

ツールモジュール

各ツールモジュールは一貫したパターンに従っています。

def register_[category]_tools(mcp: FastMCP):
    """Register all [category] tools with the MCP server"""
    
    @mcp.tool()
    def tool_function(parameters) -> str:
        """Tool description"""
        # Implementation
        return json.dumps(result, indent=2)

リソースモジュール

リソースは保守性を高めるためにドメイン別に整理されています。

物件リソース (property_resources.py)

• 物件リストと検索結果
• 物件の洞察と市場コンテキスト
• 地域に基づく物件フィルタリング

エージェントリソース (agent_resources.py)

• エージェントのプロフィールとディレクトリ
• パフォーマンスダッシュボードとメトリクス

市場リソース (market_resources.py)

• 市場の概要とトレンド
• 地域固有の市場分析

クライアントリソース (client_resources.py)

• クライアントの嗜好マッチング
• 物件推薦

場所リソース (location_resources.py)

• 地域情報と人口統計
• アメニティと地域サービス

各モジュールは一貫したパターンに従っています。

def register_[domain]_resources(mcp: FastMCP):
    """Register all [domain] resources with the MCP server"""
    
    @mcp.resource("realestate://resource-name")
    def resource_function() -> str:
        """Resource description"""
        return json.dumps(data, indent=2)

プロンプトテンプレート

プロンプトはAI分析をガイドします。

@mcp.prompt()
def analysis_prompt(param: str = "default") -> str:
    """Analysis prompt description"""
    return f"""
    Detailed analysis instructions for {param}...
    """

📊 データ構造

サーバーは包括的な不動産データを扱います。

• 5つの物件タイプ：ビクトリアン風住宅、現代住宅、高級住宅、タウンハウス
• 3人のエージェント：専門的な不動産プロフェッショナル
• 6人のクライアント：嗜好を持つ買い手、売り手、投資家
• 複数の売買取引：最近の取引履歴
• 5つの地域：ダウンタウンリバーサイド、ウッドクレスト、キャニオンクレスト、アーリントンハイツ、ラシエラ
• アメニティ：学校、公園、ショッピング、医療施設

🧪 テスト

このプロジェクトには、すべてのコンポーネントと機能をカバーする包括的なテストスイートが含まれています。

テスト構造

tests/
├── conftest.py              # Pytest configuration and shared fixtures
├── unit/                    # Unit tests for core components
│   ├── test_utils.py        # RealEstateDataManager and PropertyFilter tests
│   └── test_*.py            # Additional unit tests
├── integration/             # Integration tests for MCP components
│   ├── test_property_tools.py    # Property tools integration tests
│   ├── test_all_tools.py         # All other tool categories
│   ├── test_resources.py         # Static and template resources tests
│   └── test_prompts.py            # Prompt template tests
└── __init__.py

テストカテゴリ

単体テスト (tests/unit/)

• データマネージャーテスト：RealEstateDataManagerのコア機能
• フィルターテスト：物件フィルタリングのロジックとエッジケース
• ユーティリティ関数：ヘルパー関数とデータ検証

統合テスト (tests/integration/)

• 物件ツール：検索、フィルタリング、洞察、および地域ベースのクエリ
• エージェントツール：プロフィール管理、パフォーマンスダッシュボード
• 市場ツール：市場分析とトレンド計算
• クライアントツール：クライアントマッチングと嗜好アルゴリズム
• 地域ツール：地域情報とアメニティデータ
• システムツール：データ更新とシステム統計
• リソース：静的リソースと動的テンプレート
• プロンプト：テンプレート生成とパラメーター処理（4つのカテゴリにわたる11のプロンプト）

テストの実行

前提条件

# テスト用の依存関係をインストール
pip install -r requirements.txt

クイックテストコマンド

# すべてのテストを実行
pytest

# カバレッジレポート付きで実行
pytest --cov=. --cov-report=html

# 特定のテストカテゴリを実行
pytest tests/unit/                    # 単体テストのみ
pytest tests/integration/             # 統合テストのみ
pytest tests/integration/test_property_tools.py  # 物件ツールのみ

テストランナースクリプトの使用

# すべてのテストを実行
python run_tests.py

# 特定のテストタイプを実行
python run_tests.py unit              # 単体テストのみ
python run_tests.py integration       # 統合テストのみ
python run_tests.py property          # 物件ツールのみ
python run_tests.py resources         # リソーステストのみ

# 詳細出力とカバレッジ付きで実行
python run_tests.py all -v -c

テストの機能

フィクスチャとテストデータ

• 分離されたテスト環境：各テストは一時的なデータディレクトリを使用
• モックデータ：すべてのテストケースで一貫したテストデータ
• 共有フィクスチャ：conftest.py の再利用可能なテストコンポーネント
• データマネージャーのモッキング：ファイルシステムに依存しない分離されたテスト

カバレッジとレポート

• コードカバレッジ：pytest-covによる包括的なカバレッジレポート
• HTMLレポート：htmlcov/index.html の視覚的なカバレッジレポート
• 未カバーの行：カバーされていないコードパスの特定
• ブランチカバレッジ：ロジックブランチのテスト

テスト設定

• pytest.ini：集中的なテスト設定
• 自動検索：命名規則によるテストの自動検出
• 並列実行：並列テスト実行のサポート
• フィルタリング：クリーンなテスト出力のための警告フィルター

テストデータの検証

テストスイートは以下を検証します。

• ✅ 30以上のすべてのツールがモックデータと実データで正しく機能する
• ✅ 物件フィルタリングのロジックがエッジケースを処理する
• ✅ 検索機能が大文字小文字を区別せず、包括的である
• ✅ エージェントのパフォーマンス計算が正確である
• ✅ 市場分析ツールがデータを正しく処理する
• ✅ クライアントマッチングアルゴリズムが期待どおりに機能する
• ✅ 地域情報がデータを適切に集約する
• ✅ リソースエンドポイントが有効なJSONを返す
• ✅ プロンプトテンプレートが適切な指示を生成する
• ✅ 欠落または無効なデータに対するエラー処理
• ✅ データ更新とキャッシュメカニズム
• ✅ システム統計と要約

継続的インテグレーション

CI/CDパイプラインでは、以下を使用します。

# 基本的なテスト実行
pytest tests/ --tb=short

# CIレポート用のカバレッジ付き
pytest tests/ --cov=. --cov-report=xml --cov-report=term-missing

# 段階的なテストのための特定のテストカテゴリ
pytest tests/unit/ --tb=short          # 最初に高速な単体テスト
pytest tests/integration/ --tb=short   # 次に統合テスト

新しいテストの作成

新しい機能を追加する場合は、以下の手順に従ってください。

1. 単体テスト：コアロジックの場合は tests/unit/ に追加
2. 統合テスト：適切な tests/integration/test_*.py に追加
3. フィクスチャの使用：conftest.py の既存のフィクスチャを活用
4. 外部依存関係のモック：分離のために unittest.mock を使用
5. エッジケースのテスト：境界条件とエラーシナリオを含める
6. 命名規則に従う：test_*.py ファイル、Test* クラス、test_* メソッド

🛠️ 開発

新しいツールの追加

1. tools/ の適切なカテゴリを選択
2. @mcp.tool() デコレータでツール関数を追加
3. カテゴリの register_*_tools() 関数で登録
4. main.py で登録をインポートして呼び出す
5. テストの追加：tests/integration/ に対応するテストを作成

新しいリソースの追加

1. resources/ の適切なドメインモジュールを選択（物件、エージェント、市場、クライアント、場所）
2. @mcp.resource() デコレータとURIパターンでリソース関数を追加
3. ドメインの register_*_resources() 関数で登録
4. main.py で登録をインポートして呼び出す
5. テストの追加：tests/integration/test_resources.py にリソーステストを含める

新しいプロンプトの追加

1. prompts/ の適切なカテゴリを選択（物件、クライアント、市場、またはエージェント）
2. @mcp.prompt() デコレータでプロンプト関数を追加
3. パラメーターのデフォルト値と包括的な指示を含める
4. カテゴリの register_*_prompts() 関数で登録
5. テストの追加：tests/integration/test_prompts.py にプロンプトテストを含める

新しいプロンプトカテゴリの追加

1. prompts/ ディレクトリに新しいファイルを作成（例：prompts/new_category_prompts.py）
2. register_new_category_prompts(mcp) 関数で既存のパターンに従う
3. prompts/__init__.py でインポートして登録
4. テストの追加：対応するテストフィクスチャとテストメソッドを作成

🔄 SSEトランスポートの利点

• Web互換：直接ブラウザに統合可能
• リアルタイム：サーバー送信イベントによるライブ更新
• HTTP標準：標準のHTTPツールで動作
• ファイアウォールに優しい：標準のHTTPポートを使用
• スケーラブル：複数の同時接続をサポート

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。

🤝 コントリビューション

1. リポジトリをフォークする
2. 機能ブランチを作成する
3. 確立されたパターンに従ってコンポーネントを追加する
4. 十分にテストする
5. プルリクエストを送信する

📖 詳細情報

このMCPサーバーのアーキテクチャ、設計原則、および実世界のアプリケーションについて詳しく調べるには、詳細なブログ記事を読んでください。

🔌 MCP Servers - Model Context Protocol Implementation

ブログ記事では以下がカバーされています。

• MCPサーバーとそのビジネスへの影響の理解
• コード例を用いたアーキテクチャの詳細分析
• MCPツール、プロンプト、およびリソースの説明
• 実世界の使用シナリオと実装パターン
• セキュリティ上の考慮事項とベストプラクティス
• MCP技術の将来的な影響

Built with the Model Context Protocol (MCP) for seamless AI integration