🇰🇷 Korean Land MCP (土地空間情報MCP) — v2.0

V-World APIベースの土地・都市計画空間情報MCPサーバー 国土交通部のV-World Open APIをバックエンドに使用し、土地利用計画確認書（eum.go.kr）で人が手動で確認していた用途地域・用途地区・用途区域・地区単位計画・都市計画施設・他法令指定事項を、AIが自然言語で照会できるようにしたModel Context Protocolサーバーです。

korean-law-mcp（法令テキスト）と対になる空間レイヤーMCP。2つのMCPを併用することで、「この地番はどこに属するか → その法令・条例は何を許可/制限するか」までを自然言語の一文でつなげることができます。

✨ v2.0 アーキテクチャ原則

1. V-World API専用。他の商用API・スクレイピング・モックデータはなし。

2. 正直な失敗。特定のレイヤーでV-Worldが500を返した場合、layer_errorsにそのまま露出。偽のデータで埋めることは一切しない。

3. korean-law-mcpとの役割分担。このMCPは「空間的にどこに属するか」のみを回答。条文解釈はkorean-law-mcpに委ねる。

4. 国土計画法第76条⑤の優先委任を自動検知。農業振興区域・保全山地・水源保護区域・国家産業団地などが地番にかかっている場合、priority_delegation_hintで「国土計画法施行令の別表の代わりにどの法令を優先すべきか」を通知。

Related MCP server: Korea Building Register MCP

🛠️ 提供ツール (7個)

discover_toolsも含まれており、ツールカタログを自然言語で探索可能。

📡 V-Worldレイヤーカバレッジ

• 用途地域: LT_C_UQ111/112/113/114 (都市・管理・農林・自然環境保全 全体)

• 用途地区・区域: LT_C_UQ121~130, LT_C_UD801, LT_C_UQ162

• 地区単位計画・許可制限: LT_C_UPISUQ161, LT_C_UPISUQ171

• 都市計画施設: LT_C_UPISUQ151~159

• 他法令指定: 農地(AGRIXUE) · 山林(UF) · 産業団地(WGISIE*, DAM*) · 水質環境(UM, WGISARWET) · 畜産(UM000) · 文化財(UO) · 自然公園(WGISNP*) · 特殊地区(UO/UJ/UH/UB) · 住居整備(UD) · 災害(UP) · 海洋(TFISMPA, WGISRE*) · 航空(AIS*)

• 地番・建物: LP_PA_CBND_BUBUN, LT_C_BLDGINFO, A2SM_LNDPRCPS

🚀 クイックスタート

1. 一括セットアップ

git clone https://github.com/UrbanWatcherKr/korean-land-mcp.git
cd korean-land-mcp
npm run setup

npm run setupはnpm install → npm run build → インタラクティブなconfigureの順で実行されます。configure段階でV-World APIキー・ドメインを尋ね、.envファイルを自動生成します。

V-World APIキー発行: https://www.vworld.kr/dev/v4api.do (ログイン → オープンAPI → 認証キー発行、無料)。ローカル開発用であればドメインはlocalhostで登録。

2. 設定のみ再実行

APIキーを変更したりドメインを修正したい場合はいつでも：

npm run configure

3. Claude Desktop / Claude Code に登録

configureが完了すると、貼り付けるJSONブロックをターミナルに出力します。または手動で：

{
  "mcpServers": {
    "korean-land": {
      "command": "node",
      "args": ["/absolute/path/to/korean-land-mcp/dist/server.js"],
      "env": {
        "VWORLD_API_KEY": "your_real_key_here",
        "VWORLD_DOMAIN": "localhost"
      }
    }
  }
}

💬 使用例

• 「京畿道平沢市浦升邑内基里680の用途地域を教えて」 → get_zoning

• 「この地番に第76条⑤の優先委任が適用されるかチェックして」 → get_other_law_designations

• 「半径50m以内に都市計画施設の抵触・接合はある？」 → get_urban_facility({ radius_m: 50 })

• 「この地番を全体的に分析して、korean-lawの次のステップを教えて」 → analyze_parcel

🧭 korean-law-mcp とのワークフロー

사용자: "이 지번에 공장 지을 수 있어?"
  ↓
korean-land-mcp · analyze_parcel
  ↓ (용도지역=일반공업, 산업단지=아산포승, 우선위임=산업입지법)
korean-law-mcp · search_law("산업입지법")
  ↓
korean-law-mcp · get_law_text(산업입지법 제33조)
  ↓
결론 + 원문 근거

🗂️ プロジェクト構造

src/
├── server.ts                          # MCP stdio 엔트리, 7개 도구 등록
├── lib/
│   ├── vworld.ts                      # V-World HTTP 클라이언트 (5xx 재시도 1회)
│   ├── overlays.ts                    # 병렬 레이어 쿼리 + POINT/BOX 필터
│   ├── resolve.ts                     # 주소/지번/PNU 해석
│   └── jimok.ts                       # 지목 코드 28종 매핑
└── tools/
    ├── resolve_parcel.ts
    ├── get_zoning.ts
    ├── get_district_plan.ts
    ├── get_urban_facility.ts
    ├── get_other_law_designations.ts
    ├── get_land_attributes.ts
    └── analyze_parcel.ts

🧪 テスト

ユニットテスト（純粋関数、APIキー不要）：

npm test

Live smoke test（実際のV-World呼び出し、VWORLD_API_KEYが必要）：

# 단일 지번 디버그
npx tsx tests/live/smoke-polygon.ts "서울특별시 마포구 연남동 229-1"

# 3개 픽스처 회귀 테스트 (스냅샷 비교)
npx tsx tests/live/smoke-fixtures.ts

# 스냅샷 갱신 (V-World 데이터 변경 시)
npx tsx tests/live/smoke-fixtures.ts --update

Fixtures: 都市住宅地（延南洞）、農林地域+優先委任（世出里）、複合用途地域+都市開発（葛梅里）。

⚠️ 既知の制限

• 点ベースの判定: 基本クエリは地番の中心点1つをV-Worldに送信します。地番ポリゴンの交差ではないため、境界にかかっているケースは見逃す可能性があります。get_urban_facilityのradius_mはBOXフィルターでこの制限を緩和しますが、「抵触」vs「接合」の最終判定は、ユーザーまたは担当公務員によるポリゴン交差の再検証が必要です。

• V-Worldレイヤーの障害: 一部のレイヤーが断続的にHTTP 500を返します。5xxエラーが1回再試行しても失敗した場合はlayer_errorsに露出され、残りのレイヤー結果は正常に返されます。

• 自治体条例は未含: このMCPは空間レイヤーのみです。自治体の都市計画条例の条文は、korean-law-mcpまたは法制処の自治法規APIで別途照会してください。

📜 ライセンス

MIT License.

🤝 貢献

Issue・PR歓迎。新しいV-Worldレイヤーを追加する際は、src/tools/*.tsのLAYERS配列に{ id, label }を追加するだけで、自動的にqueryOverlaysパイプラインに組み込まれます。