解锁MLS RESO参考MCP服务器
一种模型上下文协议（MCP）服务器，通过Bridge Interactive的RESO Web API提供对UNLOCK MLS房地产数据的标准化访问。该服务器使Claude等人工智能应用程序能够查询、分析和交互房地产列表数据。
特性
🏠 房产搜索与分析
- 自然语言搜索：使用对话式查询，如“德克萨斯州奥斯汀市50万美元以下的三居室房子”
- 高级过滤：精确搜索价格范围、房产类型、位置和特征
- 详细房产信息：全面的物业详细信息，包括照片、描述和代理信息
- 市场分析：实时市场趋势、定价统计和库存分析
🏘️ 市场情报
- 价格趋势分析：了解市场方向和定价模式
- 库存分析：知情决策的供需指标
- 比较市场分析：比较不同的区域和物业类型
- 投资指标：房地产投资决策数据
👥 代理商和专业网络
- 代理搜索：按地点、专业或办公室查找合格的房地产专业人员
- 专业简介：访问代理证书、联系信息和专业领域
- 当地市场专家：与专门从事特定市场的代理商联系
📊 综合资源
- 引导式工作流程：常见房地产任务的分步指南
- 市场洞察：了解市场数据的教育资源
- API状态监控：实时系统健康和连接信息
MCP服务器文档
- /用户/davidgumbper/文档/项目/解锁reso-mcp/docs/README.md
贡献者资源
快速开始
先决条件
- Python 3.11或更高版本
- 紫外线 包管理器
- Bridge Interactive API证书
安装
- 克隆仓库:
git clone
cd unlock-reso-mcp- 安装依赖项:
uv sync --dev- 配置环境变量:
cp .env.example .env
# Edit .env with your Bridge Interactive credentials- 运行MCP服务器:
python -m main环境配置
创建一个 .env 项目根目录中的文件，包含以下变量：
# Bridge Interactive API Configuration (Required)
BRIDGE_SERVER_TOKEN=your_server_token_here
BRIDGE_CLIENT_ID=your_client_id_here
BRIDGE_CLIENT_SECRET=your_client_secret_here
BRIDGE_MLS_ID=your_mls_id_here
BRIDGE_API_BASE_URL=https://api.bridgedataoutput.com/api/v2
# Optional Configuration
LOG_LEVEL=INFO
API_RATE_LIMIT_PER_MINUTE=60
CACHE_ENABLED=false
CACHE_TTL_SECONDS=300Claude桌面集成
将以下配置添加到您的Claude Desktop MCP设置中：
{
"mcpServers": {
"unlock-mls-mcp": {
"command": "python",
"args": ["-m", "main"],
"cwd": "/path/to/unlock-reso-mcp"
}
}
}使用示例
房产搜索
自然语言查询:
Find me a 3 bedroom house under $500k in Austin TX
Show me condos with pool downtown Dallas under $400k
Search for single family homes over 2000 sqft in Houston结构检索:
{
"filters": {
"city": "Austin",
"state": "TX",
"min_bedrooms": 3,
"max_price": 500000,
"property_type": "single_family"
},
"limit": 25
}市场分析
全市分析:
{
"city": "Austin",
"state": "TX",
"property_type": "residential",
"days_back": 90
}邮政编码分析:
{
"zip_code": "78701",
"property_type": "single_family",
"days_back": 90
}代理搜索
查找本地代理商:
{
"city": "Austin",
"state": "TX",
"limit": 20
}按专业搜索:
{
"specialization": "luxury homes",
"city": "Dallas",
"state": "TX"
}api参考
工具
search_properties
使用自然语言或特定条件搜索房产。
参数:
query（字符串，可选）：自然语言搜索查询filters（对象，可选）：结构化搜索筛选器limit（整数，可选）：最大结果（默认值：25，最大值：100）
示例:
{
"query": "3 bedroom house under $500k in Austin TX",
"limit": 25
}get_property_details
获取特定房产的详细信息。
参数:
listing_id（字符串，必填）：属性列表ID
示例:
{
"listing_id": "LISTING123"
}analyze_market
分析一个地点的市场趋势和统计数据。
参数:
city（string）：城市名称state（string）：州缩写zip_code（字符串）：邮政编码（城市/州的替代）property_type（字符串，可选）：属性类型筛选器days_back（整数，可选）：分析周期（天）（默认值：90）
示例:
{
"city": "Austin",
"state": "TX",
"property_type": "residential",
"days_back": 90
}find_agent
寻找房地产经纪人或会员。
参数:
name（字符串，可选）：代理名称（部分或全部）office（字符串，可选）：办公室名称city（字符串，可选）：城市state（字符串，可选）：州缩写specialization（字符串，可选）：代理专业化limit（整数，可选）：最大结果（默认值：20，最大值：50）
示例:
{
"name": "John Smith",
"city": "Austin",
"state": "TX",
"limit": 20
}资源
服务器提供了几个信息资源：
- 房产搜索示例：常见的搜索查询示例和模式
- 属性类型参考：物业类型和状态值指南
- 市场分析指南：如何解读市场分析数据
- 代理搜索指南：寻找并与房地产经纪人合作
- 常见工作流：房地产工作流程模式和最佳做法
- 引导式房产搜索：分步属性搜索工作流
- 引导式市场分析：逐步的市场分析工作流程
- API状态和信息：当前系统状态和配置
发展
项目结构
unlock-reso-mcp/
├── src/
│ ├── auth/ # OAuth2 authentication
│ ├── config/ # Configuration and settings
│ ├── utils/ # Data mapping and validation utilities
│ ├── reso_client.py # RESO API client
│ └── server.py # Main MCP server implementation
├── tests/ # Test suite
├── context/ # API documentation and examples
├── main.py # Entry point
└── pyproject.toml # Project configuration开发命令
# Install development dependencies
uv sync --dev
# Run tests
pytest
# Run tests with coverage
pytest --cov=src --cov-report=html
# Run linting
ruff check src tests
# Run type checking
mypy src
# Run a specific test
pytest tests/test_oauth2.py -v
# Run tests matching pattern
pytest -k "test_search" -v测试
该项目包括企业级测试覆盖范围：
- 单元测试：所有模块都有专用的测试文件（141+核心测试）
- 集成测试：具有真正API验证的端到端工作流测试
- 性能测试：以17000多个操作/秒的容量进行基准测试
- 错误场景测试：全面的错误处理验证（24+测试）
- 负载测试：通过并发用户模拟进行生产准备验证
- 真正的API测试：使用实时Bridge Interactive RESO Web API进行验证
- 模仿测试：用于开发和CI/CD的综合夹具
- 覆盖：85%的代码覆盖率和质量验证
建筑
服务器由以下组件构建：
- MCP服务器框架：使用标准
mcp.serverMCP合规框架 - 承载令牌身份验证：服务器令牌身份验证使用
BRIDGE_SERVER_TOKEN - RESO API客户：具有OData查询构建功能的异步HTTP客户端
- 数据映射：将RESO字段转换为用户友好的格式
- 自然语言处理：将会话搜索查询解析为结构化筛选器
- 全面的错误处理：优雅的降级，带有用户友好的错误消息
桥梁互动API
此服务器与Bridge Interactive的RESO Web API集成，以提供对UNLOCK MLS数据的访问。API遵循RESO数据字典2.0标准，以实现一致的字段命名和数据结构。
使用的API端点
- 认证：使用承载令牌
BRIDGE_SERVER_TOKEN - 属性数据:
/OData/{MLS_ID}/Property-房产列表和详细信息 - 成员数据:
/OData/{MLS_ID}/Member-房地产经纪人信息 - 局数据:
/OData/{MLS_ID}/Office-经纪办公室详细信息 - 查找数据:
/OData/{MLS_ID}/Lookup-参考数据和元数据
数据标准
返回的所有数据均符合RESO数据字典2.0规范：
- 标准化的字段名称和格式
- 一致的物业状态值
- 统一的地址和联系信息结构
- 标准化的物业类型和特征
故障排除
常见问题
身份验证错误
- 在中验证Bridge Interactive API凭据
.env文件 - 检查一下
BRIDGE_SERVER_TOKEN正确有效 - 确保正确
BRIDGE_MLS_ID已配置为您的访问权限 - 确保网络连接到
api.bridgedataoutput.com
没有搜索结果
- 检查城市名称拼写和州缩写
- 尝试更广泛的搜索条件（增加价格范围，降低要求）
- 通过解锁验证该区域是否有MLS覆盖
服务器连接问题
- 确保已安装Python 3.11+
- 检查所有依赖项是否已安装
uv sync --dev - 验证服务器是否在正确的传输（stdio）上运行
调试模式
通过设置环境变量启用调试日志记录：
LOG_LEVEL=DEBUG这将提供有关API调用、身份验证和数据处理的详细信息。
支持
技术支持：
- 检查上面的故障排除部分
- 查看服务器日志以了解错误详细信息
- 验证环境配置
- 使用Bridge Interactive测试API连接
许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
贡献
欢迎投稿！请按照以下步骤操作：
- 复刻仓库
- 创建要素分支
- 通过测试进行更改
- 确保所有测试通过并保持覆盖率
- 提交拉取请求
开发指南
- 遵循PEP 8风格指南
- 添加新功能的测试
- 保持或提高代码覆盖率
- 更新API变更文档
- 遵循传统的提交消息格式
更新日志
版本1.0.0（当前）-生产就绪
- ✅ 完成MCP服务器的实施
- ✅ 4个主要工具：搜索属性、获取属性细节、分析市场、查找代理
- ✅ 8综合资源和指南
- ✅ 自然语言查询处理
- ✅ 真正的API集成：使用Bridge Interactive RESO Web API进行验证
- ✅ 承载令牌身份验证：服务器令牌身份验证正在工作
- ✅ 符合RESO数据字典2.0标准
- ✅ 企业测试：141+次测试，覆盖率85%
- ✅ 性能已验证：17000+次操作/秒容量
- ✅ 全面的文件
路线图
✅ 第7阶段：增强测试套件（已完成）
- ✅ 端到端工作流的集成测试
- ✅ 性能测试和基准测试
- ✅ 错误场景测试
- ✅ 生产准备就绪负载测试
- ✅ 测试数据夹具和实用程序
第8阶段：优化和增强
- 缓存层可提高性能
- 速率限制合规性
- 增强的错误处理
第9阶段：部署和CI/CD
- Docker容器化
- GitHub操作工作流
- 部署文档
第10阶段：生产准备
- 最终验证和测试
- 性能优化
- 生产部署指南