Skip to main content
Glama
overture-maps

overture-maps

by koizumikento
README.md
# overture-maps-mcp

Overture Mapsの6テーマを検索・分析する、Pythonライブラリ・CLI・読み取り専用MCPサーバーです。公式Overture製品ではなく、独立した実装です。

Python 3.12以上、uv、DuckDBを使用し、MCP接続には任意依存の公式MCP Python SDKを使います。住所から座標を得る処理はgeo-jp-mcp等へ任せ、座標・検索範囲・地物IDを渡して組み合わせます。

## Pythonライブラリ・CLI

通常のインストールにはMCP SDKを含みません。MCPサーバーを使う場合だけ`[mcp]`を追加します。PyPIには未公開のため、取得したこのリポジトリからインストールしてください。

```powershell
uv add C:/workspace/overture-maps-mcp       # 他のPythonプロジェクトの依存へ追加
uv tool install C:/workspace/overture-maps-mcp  # CLIとしてインストール
overture-maps --help
overture-maps search --theme places --type place --bounds 139.760 35.680 139.762 35.682 --limit 2
```

```python
from overture_maps_mcp import Client, Bounds

client = Client()
result = client.search(
    "places",
    "place",
    bounds=Bounds(west=139.760, south=35.680, east=139.762, north=35.682),
    limit=2,
)
print(result.data)
print(client.storage_dir)
```

Python、CLI、MCPで同じ9種類の操作を使えます。引数の型と検証ルールは共通です。結果と出典の形式、JSONファイルや標準入力からの指定方法、エラー、保存先は[ライブラリ・CLIガイド](docs/library-cli.md)を参照してください。

依存関係を専用の保存先にまとめてCLIを使うには、リポジトリで次のコマンドを実行します。

Windows:

```powershell
./manage.ps1 cli search --theme places --type place --bounds 139.760 35.680 139.762 35.682 --limit 2
```

Windows以外:

```sh
uv run --isolated --no-project --no-cache --python 3.12 python -B manage.py cli search --theme places --type place --bounds 139.760 35.680 139.762 35.682 --limit 2
```

## インストール・起動

```powershell
git clone https://github.com/koizumikento/overture-maps-mcp.git
cd overture-maps-mcp
.\manage.ps1 run
```

初回は依存をインストールします。Windows以外では`uv run --isolated --no-project --no-cache --python 3.12 python -B manage.py run`。管理用Pythonは一時環境で動かし、MCP本体の実行環境を後から削除できるようにしています。

stdioが既定です。ローカルMCPクライアントからの設定例:

```json
{
  "mcpServers": {
    "overture-maps": {
      "command": "uv",
      "args": ["run", "--isolated", "--no-project", "--no-cache", "--python", "3.12", "python", "-B", "C:/workspace/overture-maps-mcp/manage.py", "run"]
    }
  }
}
```

Streamable HTTPは`.\manage.ps1 run -Transport streamable-http`、接続先は`http://127.0.0.1:8000/mcp`です。`-Port`でポートを変更できます。通常のHTTP起動はloopback専用・認証なしです。

Sites向けには[認証backend+Worker adapterの手順](docs/sites.md)を用意しています。DuckDBは別Pythonホストで実行し、`-SitesBackend`でサービス認証付きのstateless HTTPを起動します。Sites OAuthとユーザー認可はWorker側で扱います。Python API・CLI・stdioの9操作は共通で、Sites単体では実行しません。

Workerの `/mcp` は、`Origin` ヘッダーがないリクエストと、Sitesと同じオリジンからのリクエストを受け付けます。別のオリジンからのリクエストには、バックエンドに接続せずHTTP 403を返します。

## TLS証明書と実行環境の更新

カタログとSTACの取得に使うHTTPXは、`certifi>=2026.10.19` のCAバンドルで証明書を検証します。[certifiのセキュリティ勧告](https://github.com/certifi/python-certifi/security/advisories/GHSA-6q48-6c7w-9gw2)

実行環境の依存関係を更新するときは、MCPを停止し、次のコマンドを実行してから再起動してください。

- Windows: `./manage.ps1 setup`
- Windows以外: `uv run --isolated --no-project --no-cache --python 3.12 python -B manage.py setup`

開発環境ではそれぞれ `setup -Dev`、`setup --dev` を使います。wheelやローカルパスからインストールした場合は、インストール先の環境でパッケージを更新してください。

Python本体、pip、uv、OS、DuckDBの通信で使う証明書の更新は、利用環境ごとに別途確認してください。既存の仮想環境も確認の対象です。TLS検証を無効にしないでください。[Python公式の案内](https://blog.python.org/2026/10/python-3151-3149-31317/)

## PCの保存容量と削除

管理コマンド経由の起動では、Python依存・uvキャッシュ・DuckDB拡張・Python bytecodeをリポジトリ内の`.runtime`へ集約します。地理データの永続DBやディスクキャッシュは作りません。起動時に現在の保存容量をstderrへ表示します。

```powershell
.\manage.ps1 storage   # 保存先・内訳・旧保存先・対象外の共有拡張のサイズを表示
.\manage.ps1 clean     # MCPを止めてから、専用環境・キャッシュ・拡張を削除
```

`clean`はソース・docs・Gitを保持し、`.runtime`と旧版のリポジトリ内`.venv`・`.cache`・`dist`・既知のテストキャッシュ・bytecodeを削除します。稼働中のMCPがあれば拒否し、所有マーカーがない保存先や想定外のファイル、外部へのリンクも拒否します。再度`run`すれば依存・拡張を再取得できます。サイズはbytes / MiBとファイル数で表示し、物理占有量とは異なる場合があります。

ファイルを削除するには、MCP設定を外してサーバーを停止してから、`clean` を実行します。削除対象の環境に依存しないよう、Windowsでは上記のPowerShellコマンドを使ってください。Windows以外では次のコマンドを使います。

```sh
uv run --isolated --no-project --no-cache --python 3.12 python -B manage.py clean
```

uv本体、共有Python、ユーザーホームの `.duckdb/extensions` は削除対象外です。このMCPが取得するDuckDB拡張は `.runtime` 内に保存し、共有拡張の容量は別に表示します。管理用の `.runtime.lock`(1 byte)はリポジトリに残ります。保存量は依存関係や拡張のバージョンによって変わります。固定の容量上限はありません。

## Tools

| Tool | 用途 |
|---|---|
| `overture_catalog` | 最新・利用可能リリース、6テーマとタイプ、上限の確認 |
| `overture_schema` | 選択データの列・型の確認 |
| `overture_search` | 矩形・半径・ポリゴンと属性条件で検索、全属性/選択属性、ページング、GeoJSON |
| `overture_get_feature` | UUIDの詳細取得。範囲を省略すると現在のGERSで解決 |
| `overture_summarize` | 検索と同条件で全件数・複数属性別集計・数値統計・面積・道路長・距離 |
| `overture_nearest` | 最大半径内の近傍検索。距離とIDによる順序・ページング |
| `overture_spatial_join` | 2テーマ/タイプの交差・包含・接触・重複・距離条件。ペア/全件数/左地物別件数 |
| `overture_compare_releases` | 2リリースを同じ条件で比較、追加・削除・変更・不変の件数と詳細 |
| `overture_resolve_id` | 位置・テーマ不明のUUIDをGERSで解決。現存・削除・未収録を区別 |

6テーマ: `addresses`, `base`, `buildings`, `divisions`, `places`, `transportation`。タイプの組み合わせはcatalogが返します。地図描画・住所文字列のgeocoding・経路探索は担当しません。これらを必要とするクライアントは別のMCPと組み合わせてください。

使い方:

1. `overture_catalog`でreleaseとtheme/typeを取得する。
2. 必要なら`overture_schema`でフィルタ・集計列を確認する。
3. 同じreleaseを指定してsearch/get_feature/summarizeを呼ぶ。

```json
{
  "theme": "places", "feature_type": "place",
  "bounds": {"west": 139.74, "south": 35.67, "east": 139.78, "north": 35.70},
  "category": "cafe", "limit": 20,
  "release": "2026-09-23.1"
}
```

例にあるリリースは指定方法を示すものです。公開データの保持期間は最大60日なので、検索には `overture_catalog` が返すリリースを使ってください。施設の分類は `taxonomy.primary` で絞り込めます。名前は大文字・小文字を区別せず、部分一致で検索します。存在しない列を条件に指定するとエラーになります。

属性は既定で全列を返します。必要な列だけ取得するには `fields` を指定します。`filters` では型に応じた20種類の条件を使え、構造体や配列に含まれる属性も指定できます。範囲検索、集計、空間結合、リリース間の比較の例は[検索・分析ガイド](docs/analysis.md)を参照してください。

## 結果・上限

- 結果には対象の `release`、`theme`、`feature_type`、`scope` が含まれます。出典と利用条件は `source`、`license`、`attribution_url` で確認できます。取得したデータ、次ページの位置、警告はそれぞれ `data`、`next_cursor`、`warnings` で返ります。
- WGS84の矩形範囲は東西・南北1度以内、概算2500km²以内。日付変更線をまたぐ範囲は分割します。
- 1ページ最大50件。次ページではrelease・範囲・フィルタ・geometry設定を維持します。
- bboxで候補を絞り、geometryとの交差・距離条件で地物を選びます。件数はレコード数。面積・線の長さは別の指標で、WGS84楕円体のm² / mです。
- 集計の上位50グループを返し、`other_count`で省略分を示します。検索ページの件数を全件数として扱いません。
- geometryは検索では既定で省略。詳細取得で確認できます。dataは最大400KB、超過時は件数・範囲・geometry設定の変更を促すエラーになります。
- DuckDBの実行は1回30秒、メモリ512MB、同時2本に制限。巨大な全世界検索・任意SQL・任意URL/パスはtoolへ公開しません。
- 初回のDuckDB spatial / httpfs拡張取得と公開データ問い合わせにはネットワークが必要です。処理はローカルで実行し、AWSの認証情報は不要です。
- 半径は最大25000m、polygonは最大2000座標。空間結合・版比較は各データセット最大5000候補で、超過時は範囲や条件を絞るエラーを返します。
- 点以外の距離は局所投影による近似、円の面積・長さのクリップは128辺の近似です。GERSレジストリは現在版のみ、履歴版・非GERSのID取得にはboundsが必要です。
- 公式STACのファイル収録範囲で問い合わせ先を絞り、メタデータを10分キャッシュします。初回は各タイプのファイル一覧を確認する時間がかかります。STAC取得失敗・上限超過は成功や空結果として扱いません。

## 利用条件・データ品質

コードはMIT。データの権利は別で、[Overtureの出典・ライセンス一覧](https://docs.overturemaps.org/attribution/)が正本です。PlacesにはCDLA-Permissive-2.0、Apache-2.0、CC0などが混在し、Base・Buildings・Divisions・TransportationはODbL。住所は出典ごとに異なります。返却した`source`・`sources`と利用条件を保持してください。

件数は当該リリース・検索範囲のレコード数です。施設の現実の網羅率、現在営業中であること、座標の正確性を保証しません。AddressesはAlpha。Base・building_partのIDにはGERS安定性保証がありません。IDが同じであることとリリース間の完全追跡は別です。

## 開発・検証

```powershell
.\manage.ps1 setup -Dev
$env:UV_PROJECT_ENVIRONMENT = "$PWD/.runtime/venv"
$env:UV_CACHE_DIR = "$PWD/.runtime/uv-cache"
$env:PYTHONPYCACHEPREFIX = "$PWD/.runtime/pycache"
$env:OVERTURE_MAPS_MCP_STORAGE_DIR = "$PWD/.runtime"
uv run python -c "import duckdb; from overture_maps_mcp.storage import Storage; duckdb.connect(config={'extension_directory': str(Storage.default().extension_directory())}).execute('INSTALL spatial')"
uv run ruff check .
uv run ruff format --check .
uv run ty check .
uv run pytest
node --test sites/tests/worker.test.mjs
node sites/scripts/build.mjs
uv build
```

ローカルの合成Parquet fixtureによるSQL・geometry・ページング・集計検証とMCP接続試験を既定にします。公開データの問い合わせや実クライアント接続の結果は[validation](docs/validation.md)で別に記録します。

公開データに接続して確認する場合は、目的に応じて次のコマンドを実行します。これらの確認は通常のpytestには含まれません。

- `uv run python scripts/verify_managed.py` で、管理コマンド経由のstdio接続、施設検索、稼働中に削除を拒否する動作を確認します。
- `uv run python scripts/verify_live.py` で、stdio接続から6テーマを確認します。
- `uv run python scripts/verify_http.py` で、ループバックのHTTP接続とカタログ取得を確認します。

`uv run python scripts/verify_complete.py` は、全15タイプについて、公式の列定義と取得結果、条件付きの件数、地物の詳細を公開データで照合します。空間検索、計測、結合、ID解決、リリース間の比較も確認します。地理データはディスクに保存しません。この検証の対象はツールの動作です。

設計・受入条件: [requirements](docs/requirements.md)。参考: [PlaceRoot](https://github.com/chuofringer/placeroot)、[Overture Maps MCP Server](https://github.com/srivinod1/overture-mcp-server)、[Soapbox MCP](https://github.com/soapboxbuild/overture-mcp)。これらの機能分割を参考にし、コードは複製していません。

TDQS

A3.9/5.0

Scored across 9 tools

Disambiguation4/5

Most tools have clearly distinct purposes (catalog vs schema vs summarize vs spatial_join vs compare_releases). However, overture_get_feature and overture_resolve_id both retrieve a feature by UUID, and overture_search vs overture_nearest both find intersecting features, so a couple of boundaries rely on descriptions rather than being inherently separate.

Naming Consistency4/5

All tools share a consistent overture_ snake_case prefix with predictable verb/verb_noun forms (search, get_feature, summarize, spatial_join, compare_releases, resolve_id). Minor deviation: catalog and schema are noun-style rather than action verbs, but the overall pattern is readable and uniform.

Tool Count5/5

Nine tools is well-scoped for a rich geospatial dataset, with each tool covering a distinct capability (discovery, schema, search, nearest, retrieval, aggregation, joins, release diffing). No redundant or filler tools.

Completeness5/5

The surface covers the full read-only query lifecycle: theme/release discovery, schema inspection, spatial and attribute search, distance search, feature retrieval, aggregation, cross-theme joins, release comparison, and ID resolution. No obvious gaps remain for a read-only dataset domain.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues