Property Price Search MCP Server

物件価格検索 MCP サーバー

HM Land Registry の SPARQL エンドポイントを使用して、郵便番号から物件価格を検索できる Model Context Protocol（MCP）サーバーです。

特長

• 郵便番号、または通り名と市区町村名の組み合わせから物件価格を検索
• 価格帯、物件タイプ、期間で結果を絞り込み
• HM Land Registry の公開 SPARQL エンドポイントに接続
• IDE 連携用の MCP stdio トランスポートを実装
• 完全な型安全性を備えた TypeScript 実装
• 包括的なテストスイート
• Ordnance Survey Code-Point Open（別途ダウンロード）を使用した、ローカルの郵便番号検索と近隣郵便番号検索ツール
• 直接利用できる CLI インターフェース

前提条件

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

インストール

グローバルインストール

npm install -g property-prices-mcp

ローカルインストール

npm install property-prices-mcp

使用方法

MCP サーバーとして

このサーバーは、MCP クライアント（Claude Desktop、MCP に対応した IDE など）から使用することを想定しています。stdio トランスポートを介してこのサーバーを利用するよう、MCP クライアントを設定してください。

{
  "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

使用上の注意

大文字と小文字の区別

UK Land Registry のデータでは、通り名と市区町村名の大文字と小文字が区別されます。ただし、この MCP は Land Registry API に送信する前にこれらのパラメーターを自動的に大文字に変換するため、検索時の大文字と小文字は問いません。

例：

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

検索パラメーター

サーバーでは、次の検索パラメーターを指定できます。

パラメーター	型	説明	デフォルト
postcode	string	検索する UK の郵便番号	-
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
   

   注：E2E テストでは HM Land Registry SPARQL エンドポイントに実際に API 呼び出しを行うため、デフォルトではスキップされます。インターネット接続が必要で、サンドボックス環境では失敗することがあります。

5. 開発モードで起動します。

   npm run dev
   

テスト

このプロジェクトでは、3 段階のテスト方式を採用しています。

テスト構成

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 テスト：HM Land Registry への実際の API 呼び出し

  npm run test:e2e
  

  注：E2E テストはデフォルトでスキップされ、実行には以下が必要です。

  • インターネット接続
  • https://landregistry.data.gov.uk へのアクセス
  • 環境変数 RUN_E2E_TESTS=true の設定

• すべてのテスト：ユニットテストと E2E テストの両方を実行します

  npm run test:all
  

手動テスト

実際のデータを使ったアドホックなテストを行う場合：

npm run test-mcp

トラブルシューティング

よくある問題

1. SPARQL エンドポイントへの接続の問題

   • インターネット接続を確認してください
   • HM Land Registry のエンドポイントが利用可能か確認してください
   • IP アドレスがレート制限されていないことを確認してください

2. 無効な郵便番号の形式

   • 郵便番号が英国の正しい形式になっていることを確認してください
   • 余分なスペースを削除してください
   • 大文字を使用してください

3. 結果が見つからない

   • 検索条件を広げてみてください
   • 日付範囲が狭すぎないか確認してください
   • 郵便番号が存在することを確認してください

貢献

行動規範とプルリクエストの提出手順については、CONTRIBUTING.md をお読みください。

変更履歴

変更内容とバージョン履歴については、CHANGELOG.md をご覧ください。

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細については LICENSE ファイルをご覧ください。