AI导哈

房产价格搜索服务

一个通过英国土地注册局SPARQL端点，允许用户按邮编搜索房产价格的模型上下文协议（MCP）服务器。

  • by joemclo
  • TypeScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 joemclo/property-prices-mcp

使用说明

房产价格搜索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"
}

发展

  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

    备注：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

  • 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

故障排除

常见问题

  1. SPARQL端点连接问题

    • 检查您的互联网连接
    • 验证HM土地注册处端点是否可用
    • 确保您的IP不受速率限制

  2. 邮政编码格式无效

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

  3. 未找到结果

    • 尝试扩大搜索范围
    • 检查日期范围是否太窄
    • 验证邮政编码是否存在

贡献

请阅读 贡献.md 有关我们的行为准则和提交pull请求流程的详细信息。

更新日志

看 更改日志.md 查看更改和版本历史记录列表。

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

相关 MCP