房产价格搜索MCP服务器
一种模型上下文协议（MCP）服务器，允许用户使用HM土地注册处的SPARQL端点按邮政编码搜索房价。
特性
- 按邮政编码或街道/城市组合搜索房价
- 按价格范围、房产类型和日期范围筛选结果
- 连接到HM土地注册处的公共SPARQL端点
- 实现MCP stdio传输以实现IDE集成
- 具有完全类型安全的TypeScript实现
- 全面的测试套件
- 使用英国地形测量局代码点Open（单独下载）的本地邮政编码查找和最近邻工具
- CLI界面可直接使用
先决条件
- Node.js>=20
- npm>=7
安装
全球安装
npm install -g property-prices-mcp本地安装
npm install property-prices-mcp用法
作为MCP服务器
此服务器设计用于MCP客户端（如Claude Desktop、支持MCP的IDE等）。配置您的MCP客户端以通过stdio传输使用此服务器：
{
"mcpServers": {
"property-prices": {
"command": "property-prices-mcp"
}
}
}连接后，您可以使用 search-property-prices 工具具有以下参数：
{
"postcode": "SW1A 1AA",
"minPrice": 1000000,
"propertyType": "flat",
"limit": 5
}您还可以使用 lookup-postcodes 该工具（基于英国地形测量局代码点开放）用于解析邮政编码并查找附近的邮政编码：
{
"postcode": "SW1A 1AA",
"radiusMeters": 2000,
"limit": 5
}注意：Code Point Open CSV没有捆绑在一起。下载一次，然后构建本地邮政编码数据库： -npm run setup:postcodes（下载+构建），或 -npm run fetch:codepo然后npm run build:postcodes手动下载：https://api.os.uk/downloads/v1/products/CodePointOpen/downloads?area=GB&format=CSV&redirect 包含英国地形测量局数据©皇家版权和数据库权，皇家邮政数据©英国皇家邮政版权和数据库权利，以及国家统计数据©王室版权和数据库版权。
命令行界面
用于测试或直接使用：
property-prices-mcp使用说明
区分大小写
英国土地注册处的数据对街道名称和城市名称区分大小写。但是，此MCP在发送到土地注册处API之前会自动将这些参数转换为大写，因此您可以在搜索中使用任何情况。
例子：
"Cherry Drive" and "CHERRY DRIVE" will both work correctly.搜索参数
服务器接受以下搜索参数：
| 参数 | 类型 | 描述 | 默认值 |
|---|---|---|---|
| 邮编 | 字符串 | 要搜索的英国邮政编码 | - |
| street | string | 街道名称 | - |
| city | string | 城市名称 | - |
| minPrice | number | 最低房价 | - |
| maxPrice | number | 最高房价 | - |
| propertyType | string | 其中之一：独立式、半独立式、联排式、平面式、其他 | - |
| fromDate | string | 开始日期（YYYY-MM-DD） | - |
| toDate | string | 结束日期（YYYY-MM-DD） | - |
| limit | number | 最大结果数 | 10 |
| offset | number | 要跳过的结果数 | 0 |
| sortBy | string | 按“日期”或“价格”排序 | “日期” |
| sortOrder | string | 排序顺序“asc”或“desc” | “desc |
响应格式
API以以下格式返回结果：
interface PropertyPrice {
price: number;
date: string;
postcode: string;
propertyType: 'detached' | 'semi-detached' | 'terraced' | 'flat' | 'other';
street: string;
city: string;
paon?: string;
saon?: string;
}
interface SearchResponse {
properties: PropertyPrice[];
total: number;
offset: number;
limit: number;
}错误处理
服务器返回标准HTTP状态代码：
- 200：请求成功
- 400：无效参数
- 404：未找到结果
- 500：服务器错误
错误响应包括一条解释错误的消息：
{
"error": "Invalid postcode format"
}发展
- 克隆存储库：
git clone https://github.com/joemclo/property-prices-mcp.git
cd property-prices-mcp- 安装依赖项：
npm install- 构建项目：
npm run build- 运行测试：
npm test # Run unit tests (fast, mocked)
npm run test:unit # Run unit tests only
npm run test:e2e # Run e2e tests (requires internet, hits real API)
npm run test:all # Run all tests including e2e备注：E2E测试对HM Land Registry SPARQL端点进行真正的API调用，默认情况下跳过。它们需要互联网连接，在沙盒环境中可能会失败。
- 以开发模式启动：
npm run dev测试
本项目使用三层测试方法：
测试结构
src/__tests__/
├── unit/ # Unit tests (fast, all mocked)
│ ├── queries.test.ts
│ ├── sparqlService.test.ts
│ └── mcpTool.test.ts
└── e2e/ # End-to-end tests (slow, real API calls)
└── propertySearch.e2e.test.ts运行测试
- 单元测试 （默认）：具有模拟依赖关系的快速测试
npm test # or npm run test:unit- E2E测试：对英国皇家土地注册处的真实API调用
npm run test:e2e注：默认情况下跳过E2E测试，并要求：
- 互联网连接 - 访问https://landregistry.data.gov.uk - 设置 RUN_E2E_TESTS=true 环境变量
- 所有测试：运行unit和e2e测试
npm run test:all手动测试
对于使用真实数据的临时测试：
npm run test-mcp故障排除
常见问题
- SPARQL端点连接问题
- 检查您的互联网连接 - 验证HM土地注册处端点是否可用 - 确保您的IP不受速率限制
- 邮政编码格式无效
- 确保邮政编码采用正确的英国格式 - 删除所有多余的空格 - 使用大写字母
- 未找到结果
- 尝试扩大搜索范围 - 检查日期范围是否太窄 - 验证邮政编码是否存在
贡献
请阅读 贡献.md 有关我们的行为准则和提交pull请求流程的详细信息。
更新日志
看 更改日志.md 查看更改和版本历史记录列表。
许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。