Real Estate 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功能

• 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 個）

• 經紀人績效：績效儀表盤和分析。
• 經紀人營銷策略：業務發展和營銷。
• 經紀人培訓發展：技能提升和培訓計劃。

🏗️ 架構

服務器採用模塊化、組件化架構，以確保可維護性和可擴展性：

real - estate - mcp/
├── main.py                    # 主服務器入口點
├── utils.py                   # 核心數據管理工具
├── tools/                     # MCP 工具（按類別組織）
│   ├── property_tools.py      # 房產搜索、篩選、洞察
│   ├── agent_tools.py         # 經紀人資料、績效、儀表盤
│   ├── market_tools.py        # 市場分析和趨勢
│   ├── client_tools.py        # 客戶管理和匹配
│   ├── area_tools.py          # 區域情報和設施
│   └── system_tools.py        # 數據管理和系統工具
├── resources/                 # MCP 資源（按領域組織）
│   ├── property_resources.py  # 與房產相關的資源
│   ├── agent_resources.py     # 與經紀人相關的資源
│   ├── market_resources.py    # 市場分析資源
│   ├── client_resources.py    # 客戶管理資源
│   └── location_resources.py  # 區域和設施資源
├── prompts/                   # MCP 提示模板（用戶可控制的模板）
│   ├── __init__.py            # 中央提示模板註冊
│   ├── property_prompts.py    # 房產分析和比較提示模板
│   ├── client_prompts.py      # 客戶匹配和諮詢提示模板
│   ├── market_prompts.py      # 市場分析和投資提示模板
│   └── agent_prompts.py       # 經紀人績效和發展提示模板
└── data/                      # 房地產數據文件
    ├── properties/
    ├── agents/
    ├── clients/
    ├── market/
    ├── transactions/
    ├── areas/
    └── amenities/

📦 安裝指南

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 檢查器

要檢查和調試 MCP 服務器，可使用 MCP 檢查器工具：

npx @modelcontextprotocol/inspector

這將啟動 MCP 檢查器界面，允許你：

• 實時監控 MCP 消息。
• 調試工具和資源調用。
• 檢查服務器響應。
• 測試服務器功能。

🌐 服務器傳輸

服務器使用 服務器發送事件（SSE） 傳輸，使其與以下環境兼容：

• 網頁瀏覽器和 HTTP 客戶端。
• 傳統 MCP 客戶端。
• 自定義集成。

連接詳情

• SSE 端點：http://127.0.0.1:8000/sse（用於建立 SSE 連接）
• 消息端點：http://127.0.0.1:8000/messages/（用於發送 MCP 消息）
• 傳輸方式：SSE（服務器發送事件）
• 協議：MCP（模型上下文協議）

網頁客戶端示例

// 建立 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();
}

🔧 技術細節

核心組件

utils.py - 數據管理

• RealEstateDataManager：中央數據訪問類。
• PropertyFilter：搜索和篩選工具。
• JSON 數據加載和緩存。
• 交叉引用和關係映射。

main.py - 服務器入口點

• FastMCP 服務器初始化。
• 組件註冊編排。
• SSE 傳輸配置。
• 啟動日誌記錄和診斷。

工具模塊

每個工具模塊遵循一致的模式：

def register_[category]_tools(mcp: FastMCP):
    """向 MCP 服務器註冊所有 [類別] 工具"""
    
    @mcp.tool()
    def tool_function(parameters) -> str:
        """工具描述"""
        # 實現代碼
        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):
    """向 MCP 服務器註冊所有 [領域] 資源"""
    
    @mcp.resource("realestate://resource - name")
    def resource_function() -> str:
        """資源描述"""
        return json.dumps(data, indent = 2)

提示模板

提示模板指導 AI 分析：

@mcp.prompt()
def analysis_prompt(param: str = "default") -> str:
    """分析提示模板描述"""
    return f"""
    針對 {param} 的詳細分析說明...
    """

📊 數據結構

服務器處理全面的房地產數據：

• 5 種房產類型：維多利亞式住宅、現代住宅、豪華住宅、聯排別墅。
• 3 名經紀人：專業房地產經紀人。
• 6 名客戶：有不同偏好的買家、賣家和投資者。
• 多筆銷售記錄：近期交易歷史。
• 5 個區域：河濱市中心、伍德克里斯特、峽谷頂、阿靈頓高地、拉塞拉。
• 各類設施：學校、公園、購物中心、醫療保健設施。

💻 使用示例

基礎用法

# 建立 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"}}}'

🧪 測試

測試結構

tests/
├── conftest.py              # Pytest 配置和共享測試夾具
├── unit/                    # 核心組件的單元測試
│   ├── test_utils.py        # RealEstateDataManager 和 PropertyFilter 測試
│   └── test_*.py            # 其他單元測試
├── integration/             # MCP 組件的集成測試
│   ├── test_property_tools.py    # 房產工具集成測試
│   ├── test_all_tools.py         # 所有其他工具類別的測試
│   ├── test_resources.py         # 靜態和模板資源測試
│   └── test_prompts.py            # 提示模板測試
└── __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_* 方法。

🔄 SSE 傳輸的優勢

• 與 Web 兼容：可直接集成到瀏覽器。
• 實時性：服務器發送事件實現實時更新。
• 符合 HTTP 標準：可與標準 HTTP 工具配合使用。
• 對防火牆友好：使用標準 HTTP 端口。
• 可擴展：支持多個併發連接。

📄 許可證

本項目採用 MIT 許可證。

🤝 貢獻指南

1. 分叉倉庫。
2. 創建功能分支。
3. 按照既定模式添加組件。
4. 進行全面測試。
5. 提交拉取請求。

📖 擴展閱讀

要深入瞭解此 MCP 服務器的架構、設計原則和實際應用，請閱讀詳細的博客文章：

[🔌 MCP 服務器 - 模型上下文協議實現](https://edwin.genego.io/ai/mcp - servers)

博客文章涵蓋：

• 理解 MCP 服務器及其商業影響。
• 深入剖析架構並提供代碼示例。
• 解釋 MCP 工具、提示模板和資源。
• 實際使用場景和實現模式。
• 安全考慮和最佳實踐。
• MCP 技術的未來影響。

基於模型上下文協議（MCP）構建，實現無縫 AI 集成