房产价格搜索 MCP 服务器

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

功能

• 按邮政编码或街道/城市组合搜索房产价格
• 按价格范围、房产类型和日期范围过滤结果
• 连接到英国土地注册局的公共 SPARQL 端点
• 实现用于 IDE 集成的 MCP stdio 传输
• 具有完全类型安全的 TypeScript 实现
• 完善的测试套件
• 用于直接使用的 CLI 界面

前提条件

• Node.js >= 18
• npm >= 7

安装

全局安装

npm install -g property-prices-mcp

本地安装

npm install property-prices-mcp

用法

命令行界面

property-prices-mcp

作为库

import { McpClient } from '@modelcontextprotocol/sdk/client';

const client = new McpClient();
const result = await client.resource('property-prices').query({
  postcode: 'SW1A 1AA',
  minPrice: 1000000,
  propertyType: 'flat',
  limit: 5,
});

console.log(result);

搜索参数

服务器接受以下搜索参数：

参数	类型	描述	默认值
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;
  propertyType: string;
  newBuild: boolean;
  tenure: string;
  paon: string;
  saon?: string;
  street: string;
  locality?: string;
  town: string;
  district: string;
  county: string;
  postcode: string;
}

interface SearchResponse {
  results: 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                  # 运行所有测试
   npm run test:unit        # 仅运行单元测试
   npm run test:integration # 仅运行集成测试
   

5. 以开发模式启动：

   npm run dev
   

故障排除

常见问题

1. SPARQL 端点连接问题

   • 检查您的互联网连接
   • 验证英国土地注册局端点是否可用
   • 确保您的 IP 没有受到速率限制

2. 邮政编码格式无效

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

3. 未找到结果

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

贡献

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

更新日志

请参阅 CHANGELOG.md 以获取更改和版本历史的列表。

许可证

该项目已获得 MIT 许可证的许可 - 有关详细信息，请参阅 LICENSE 文件。