swiss-housing-mcp

swiss-housing-mcp

スイス公共データ MCP ポートフォリオの一部です。AI エージェントをスイスの公共データにつなぐオープンソースの MCP サーバーです。個人プロジェクトであり、雇用主や所属機関とは無関係です。

スイス連邦建物・住宅登録簿（GWR/RegBL）向けの MCP サーバーです。建物、住宅、建設パイプラインを扱います。

🇩🇪 ドイツ語版

---

🎯 デモの中心となるクエリ

「2020年以降、チューリッヒ市では住宅が新たに何戸建設され、そのうち4部屋以上の住宅は何戸ですか？ また、現在建設中の住宅は何戸ですか？」

2026-07-24 のライブダンプで検証済み：2020年以降に新築された住宅は 16'164戸（うち27.4%が4部屋以上。ファミリー向け住宅の目安）で、現在建設中の住宅は7'287戸です。現在建設中の住宅は、1～3年後に世帯が入居する住宅であり、学校の教室計画に役立つ早期指標です。

デモ

---

概要

GWR/RegBL は、企業にとっての Zefix に相当する建物の登録簿です。多数あるデータソースの一つではなく、連邦登録簿であり、その識別子（建物の EGID、住宅の EWID）はスイスの行政データを横断する結合キーとして使われます。このサーバーは MCP ツールを通じて登録簿の公開データを提供し、建物検索、住所のジオコーディング、自治体ごとの建設統計、自治体内のバウンディングボックス分析、計画・建設パイプラインに対応します。

address_to_egid は、ほかのデータソースを EGID 対応にするための接続役です。住所を入力すると、連邦識別子と LV95 座標を返します。

アーキテクチャの決定

このサーバーは **アーキテクチャ B（ハイブリッド：ダンプ優先、API フォールバック）**を採用しています。

理由（2026-07-24 にライブで検証済み）：

• 公開されている州別ダンプ（public.madd.bfs.admin.ch/{canton}.zip）は毎日（約05:30 CET）更新され、テーブル building（ZH は399'830行）、entrance、dwelling（ZH は894'631行）、code を含む data.sqlite をそのまま提供します。CSV の解析も認証も不要です。
• api3.geo.admin.ch（find / identify / SearchServer）は、単一エンティティの検索とジオコーディングでは認証なしで安定して動作しますが、地域全体の集計には拡張できません（結果件数の上限があるためです）。
• /api/buildings/{egid} で調査した MADD REST エンドポイントは404を返しました。パスと認証要件が明確になるまで対象外としています。フェーズ1のすべてのツールはこのエンドポイントなしで動作するため、支障はありません。

その結果：

• 州別ダンプはディスク上に24時間の TTL でキャッシュされます（SWISS_HOUSING_DUMP_TTL_HOURS で設定可能）。
• 集計と空間クエリは、キャッシュされた SQLite に対する読み取り専用 SQL として実行されます。単一検索とジオコーディングはライブ API を利用します。
• すべてのレスポンスには source（出典情報）と provenance（daily_dump | live_api | cached）が含まれます。

ライブ調査の結果（2026-07-24）

エンドポイント	HTTP	ステータス	備考
api3.geo.admin.ch …/find（EGID 検索）	200	✅ 動作	属性一式を取得。認証不要
api3.geo.admin.ch …/identify（座標）	200	✅ 動作	EGID/EWID を含む77属性
…/SearchServer（住所 → EGID）	200	✅ 動作	featureId = {EGID}_{EDID}。軸の入れ替わり：y=東、x=北
public.madd.bfs.admin.ch/zh.zip	200	✅ 動作	121 MB、毎日更新、data.sqlite を含む
madd.bfs.admin.ch/api/buildings/{egid}	404	❌ 対象外	パスと認証要件が不明
find に無効な EGID を指定	200	⚠️ ソフトエラー	results 配列が空になります。HTTP エラーではありません

機能

• lookup_building(egid) — 連邦識別子による単一の建物検索（ライブ API）
• address_to_egid(address) — スイス国内の任意の住所をジオコーディングし、EGID／EDID と LV95 を取得
• lookup_dwellings(egid) — 建物内のすべての住戸の部屋数、面積、階を取得
• new_construction(municipality_bfs, since_year) — 年ごとの新築件数（4 部屋以上のファミリー向け住宅の割合を含む）
• construction_pipeline(municipality_bfs) — 計画中／承認済み／建設中の建物
• buildings_in_bbox(e_min, n_min, e_max, n_max) — 市町村より細かい単位での分析（例：学区）
• municipality_housing_stats(municipality_bfs) — 住宅ストックと部屋数の内訳
• explain_code(attribute, code) — 公式の DE／FR／IT コード表を使って GWR コードを解読
• dump_status() — キャッシュの鮮度確認とグレースフルデグラデーションのエントリーポイント

前提条件

• Python 3.10 以降
• キャッシュする州データのダンプごとに約 130 MB のディスク容量（ZH）
• API キー不要 — フェーズ 1 では認証不要です

インストール

uvx swiss-housing-mcp        # once published on PyPI

# or from source
pip install -e .

使い方／クイックスタート

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "swiss-housing": {
      "command": "uvx",
      "args": ["swiss-housing-mcp"]
    }
  }
}

クラウド（Render/Railway）：

SWISS_HOUSING_TRANSPORT=streamable-http PORT=8000 swiss-housing-mcp

設定

変数	デフォルト値	用途
SWISS_HOUSING_TRANSPORT	stdio	stdio | streamable-http | sse
SWISS_HOUSING_CACHE	~/.cache/swiss-housing-mcp	ダンプのキャッシュディレクトリ
SWISS_HOUSING_DUMP_TTL_HOURS	24	ダンプの鮮度を保つ時間

MCP プロトコルバージョン

このサーバーは、同じエンドポイントで2 つのプロトコル世代に対応します。接続後のクライアントによる最初のリクエストで適用する世代が決まり、後から別の世代を指定しても拒否されます。

世代	リビジョン	対応するクライアント
initialize ハンドシェイク	2024-11-05 ～ 2025-11-25	現在のクライアントが使用する方式です。サーバーは要求されたリビジョン、または要求がそれより新しい場合は上限の 2025-11-25 で応答します。
リクエストごとのエンベロープ	2026-07-28	2026-07-28 の _meta エンベロープを含むリクエストによって、最新世代の接続が開始されます。

どちらの世代も推測ではなく、実測しています。 tests/test_modern_era.py は、このサーバー独自の ASGI アプリ（SWISS_HOUSING_TRANSPORT=streamable-http のときに __main__.py が提供するもの）を通じて、各世代の実際のリクエストを送信し、レスポンス本文からネゴシエートされたリビジョンを読み取ります。さらに、tests/test_protocol_version.py では、両方のリビジョンをインストール済み SDK に対して固定しているため、Dependabot による mcp の更新で、実測を確認する前にビルドが失敗します。

SDK の LATEST_PROTOCOL_VERSION はハンドシェイク世代ではなく、最新世代のエイリアスです。これだけを基準にすると、現在のクライアントが実際にネゴシエートする世代が、変更されても検出されなくなります。

最新世代における識別情報。 2026-07-28 世代には initialize ハンドシェイクがありません。接続は _meta エンベロープを含む単一のリクエストです。そのため、最新世代のクライアントがこのサーバーに関する情報を取得できるチャネルは server/discover のみであり、SDK がすべての結果に付与する serverInfo ブロックだけが、その識別情報を示す場所です。そこでこのサーバーでは、version、title、description、websiteUrl、instructions を宣言しています。description と websiteUrl はリテラルとして重複記載するのではなく、パッケージのメタデータから読み込みます。SDK はこれらを補完せず、バージョンを指定していないサーバーは、すべての応答で空の version を通知するためです。

更新ポリシー。 チェックに失敗した場合は、定数をそのまま編集しないでください。2 つのリビジョン間の仕様変更履歴を確認し、サーバーが引き続き正常に動作することを検証したうえで、定数、このセクション、README.de.md、CHANGELOG.md をまとめて更新してください。

テスト

PYTHONPATH=src pytest tests/ -m "not live"   # CI-safe
PYTHONPATH=src pytest tests/ -m live         # against real upstream

プロジェクト構成

swiss-housing-mcp/
├── src/swiss_housing_mcp/
│   ├── server.py      # FastMCP tools (9)
│   ├── gwr.py         # Dump store + geo.admin.ch client + retry
│   ├── models.py      # Pydantic v2 envelopes (source + provenance)
│   └── __main__.py    # Dual-transport entry point
├── tests/             # respx-mocked + @pytest.mark.live
└── .github/workflows/ # CI + OIDC PyPI publish

既知の制限事項

• 公開データの抽出では、GWR 全体に含まれる人物関連の属性や一部の機微な属性は省かれています。行政機関への公式なデータ提供は、BFS/MADD チャネルを通じて行われます。
• 座標は建物の参照点（LV95）であり、建物のフットプリントポリゴンではありません。ポリゴンとの結合（例：正確な学区の境界）には外部のジオメトリが必要です。buildings_in_bbox では、矩形による近似範囲をカバーします。
• GBAUJ（建築年）は、古い建物の一部で欠落しています。代替として期間コード（GBAUP）がありますが、まだ公開されていません。
• 自治体から州への対応付けは一般的なケースを対象に設定されています。それ以外の場合は、canton を明示的に指定してください。
• 住宅市場の指標（IMPI、建設価格指数、空室率）は、意図的に swiss-statistics-mcp に含めています。このサーバーは統計レイヤーではなく、登録情報レイヤーです。

変更履歴

CHANGELOG.md を参照してください。

コントリビューション

コントリビューションを歓迎します。CONTRIBUTING.md（ドイツ語）を参照してください。

セキュリティ

読み取り専用で、個人を特定できる情報（PII）や認証はありません。固定されたエンドポイント群を通じてアクセスする、公開された連邦登録情報です。セキュリティ対策の詳細と脆弱性の報告方法については、SECURITY.md（ドイツ語）を参照してください。

ライセンス

MIT License — LICENSE を参照してください。データ：GWR/RegBL、スイス連邦統計局（BFS）。出典表記を条件とするオープンガバメントデータです。

作者

Hayal Oezkan · github.com/malkreide

クレジットと関連プロジェクト

• データ：連邦統計局 — GWR/RegBL、geo.admin.ch
• 関連ポートフォリオプロジェクト：swiss-statistics-mcp（指標、STAT-TAB）、zurich-opendata-mcp（市レベルのデータ）