Property Price Search MCP Server

房产价格搜索 MCP 服务

一个模型上下文协议（MCP）服务，允许用户通过邮编，使用 HM Land Registry 的 SPARQL 端点搜索房产价格。

功能

• 按邮编或街道与城市组合搜索房产价格
• 按价格范围、房产类型和日期范围筛选结果
• 连接到 HM Land Registry 的公共 SPARQL 端点
• 实现 MCP stdio 传输，支持 IDE 集成
• 使用 TypeScript 实现，并提供完整的类型安全保障
• 全面的测试套件
• 使用 Ordnance Survey Code-Point Open（需单独下载）的本地邮编查询和最近邻工具
• 用于直接使用的命令行界面

先决条件

• 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
}

你也可以使用基于 Ordnance Survey Code-Point Open 构建的 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 包含 Ordnance Survey 数据，© Crown copyright and database right；Royal Mail 数据，© Royal Mail copyright and database right；以及 National Statistics 数据，© Crown copyright and database right。

命令行界面

用于测试或直接使用：

property-prices-mcp

使用说明

区分大小写

英国土地登记局数据中的街道名称和城市名称区分大小写。不过，此 MCP 服务会在将这些参数发送给土地登记局 API 之前自动将其转换为大写，因此搜索时可以使用任意大小写。

示例：

"Cherry Drive" and "CHERRY DRIVE" will both work correctly.

搜索参数

服务接受以下搜索参数：

参数	类型	描述	默认值
postcode	string	要搜索的英国邮编	-
street	string	街道名称	-
city	string	城市名称	-
minPrice	number	房产最低价格	-
maxPrice	number	房产最高价格	-
propertyType	string	类型之一：detached、semi-detached、terraced、flat、other	-
fromDate	string	开始日期（YYYY-MM-DD）	-
toDate	string	结束日期（YYYY-MM-DD）	-
limit	number	最大结果数	10
offset	number	要跳过的结果数	0
sortBy	string	按 'date' 或 'price' 排序	'date'
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"
}

开发

1. 克隆仓库：

   git clone https://github.com/joemclo/property-prices-mcp.git
   cd property-prices-mcp
   

2. 安装依赖：

   npm install
   

3. 构建项目：

   npm run build
   

4. 运行测试：

   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
   

   注意：端到端测试会向 HM Land Registry SPARQL 端点发起真实 API 调用，默认情况下会跳过。这些测试需要互联网连接，在沙盒环境中可能会失败。

5. 在开发模式下启动：

   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
  

• 端到端测试：向 HM Land Registry 发起真实 API 调用

  npm run test:e2e
  

  注意：端到端测试默认会跳过，并且需要：

  • 互联网连接
  • 访问 https://landregistry.data.gov.uk
  • 设置 RUN_E2E_TESTS=true 环境变量

• 所有测试：同时运行单元测试和端到端测试

  npm run test:all
  

手动测试

使用真实数据进行临时测试：

npm run test-mcp

故障排除

常见问题

1. SPARQL 端点连接问题

   • 检查互联网连接
   • 确认 HM Land Registry 端点可用
   • 确保 IP 未被限制访问频率

2. 邮政编码格式无效

   • 确保邮政编码符合正确的英国格式
   • 删除多余的空格
   • 使用大写字母

3. 未找到结果

   • 尝试扩大搜索条件
   • 检查日期范围是否过窄
   • 确认邮政编码存在

贡献

请阅读 CONTRIBUTING.md，了解我们的行为准则以及提交拉取请求的流程。

更新日志

请参阅 CHANGELOG.md，查看更改列表和版本历史记录。

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。