🇰🇷 Korean Land MCP (Landraum-Informations-MCP) — v2.0

V-World API-basierter MCP-Server für Land- und Stadtplanungs-Rauminformationen Dies ist ein Model Context Protocol-Server, der die V-World Open API des Ministeriums für Land, Infrastruktur und Verkehr als Backend nutzt. Er ermöglicht es einer KI, Informationen zu Nutzungszonen, Nutzungsgebieten, Nutzungsbereichen, Bebauungsplänen, städtebaulichen Einrichtungen und Festlegungen nach anderen Gesetzen – die man früher manuell auf 토지이음 (eum.go.kr) prüfen musste – mittels natürlicher Sprache abzufragen.

Ein Raum-Layer-MCP, das als Gegenstück zu korean-law-mcp (Gesetzestexte) fungiert. Wenn beide MCPs zusammen verwendet werden, lässt sich eine Kette von „Zu welchem Grundstück gehört dies?“ bis hin zu „Was erlaubt/verbietet das entsprechende Gesetz/die Verordnung?“ in einer einzigen natürlichsprachlichen Abfrage verknüpfen.

✨ v2.0 Architekturprinzipien

1. Exklusiv für V-World API. Keine anderen kommerziellen APIs, Scraping oder Mock-Daten.

2. Ehrliches Scheitern. Wenn V-World für einen bestimmten Layer einen 500er-Fehler zurückgibt, wird dieser unverändert in layer_errors angezeigt. Es werden niemals gefälschte Daten eingefügt.

3. Rollentrennung von korean-law-mcp. Dieses MCP beantwortet nur die Frage: „Wo im Raum befindet sich das Objekt?“. Die Auslegung der Paragraphen erfolgt durch korean-law-mcp.

4. Automatische Erkennung der vorrangigen Delegation gemäß Art. 76 Abs. 5 des Raumplanungsgesetzes. Wenn landwirtschaftliche Fördergebiete, Schutzwälder, Wasserschutzgebiete, nationale Industriekomplexe usw. das Grundstück betreffen, wird über priority_delegation_hint angezeigt, „welches Gesetz vor der Tabelle der Durchführungsverordnung zum Raumplanungsgesetz zu prüfen ist“.

Related MCP server: Korea Building Register MCP

🛠️ Verfügbare Werkzeuge (7)

discover_tools ist ebenfalls enthalten, um den Werkzeugkatalog natürlichsprachlich zu durchsuchen.

📡 V-World Layer-Abdeckung

• Nutzungszone: LT_C_UQ111/112/113/114 (Stadt, Verwaltung, Land-Forst, Naturschutz komplett)

• Nutzungsgebiet/-bereich: LT_C_UQ121~130, LT_C_UD801, LT_C_UQ162

• Bebauungsplan/Genehmigungsbeschränkung: LT_C_UPISUQ161, LT_C_UPISUQ171

• Städtebauliche Einrichtungen: LT_C_UPISUQ151~159

• Festlegungen nach anderen Gesetzen: Landwirtschaft (AGRIXUE) · Forst (UF) · Industrie (WGISIE*, DAM*) · Wasser (UM, WGISARWET) · Viehzucht (UM000) · Kulturerbe (UO) · Naturpark (WGISNP*) · Sondergebiete (UO/UJ/UH/UB) · Wohnungsbau (UD) · Katastrophen (UP) · Meer (TFISMPA, WGISRE*) · Luftfahrt (AIS*)

• Grundstück/Gebäude: LP_PA_CBND_BUBUN, LT_C_BLDGINFO, A2SM_LNDPRCPS

🚀 Schnelleinstieg

1. Alles in einem Setup

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

npm run setup führt nacheinander npm install → npm run build → interaktive Konfiguration aus. Während der Konfiguration werden der V-World API-Schlüssel und die Domain abgefragt und die .env-Datei automatisch erstellt.

V-World API-Schlüssel beantragen: https://www.vworld.kr/dev/v4api.do (Login → Open API → Zertifizierungsschlüssel beantragen, kostenlos). Für die lokale Entwicklung kann als Domain localhost registriert werden.

2. Nur Konfiguration erneut ausführen

Wenn Sie den API-Schlüssel oder die Domain ändern möchten:

npm run configure

3. Registrierung in Claude Desktop / Claude Code

Nach Abschluss der Konfiguration wird ein JSON-Block für das Terminal ausgegeben. Alternativ manuell:

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

💬 Anwendungsbeispiele

• „Zeige mir die Nutzungszone für 680 Naegi-ri, Poseung-eup, Pyeongtaek-si, Gyeonggi-do“ → get_zoning

• „Prüfe, ob für dieses Grundstück die vorrangige Delegation gemäß Art. 76 Abs. 5 gilt“ → get_other_law_designations

• „Gibt es im Umkreis von 50m städtebauliche Einrichtungen, die betroffen oder angrenzend sind?“ → `get_urban_facility({ radius_m: 50 })

• „Analysiere diese Flurstücksnummer komplett und nenne mir den nächsten Schritt für korean-law“ → analyze_parcel

🧭 Workflow mit korean-law-mcp

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

🗂️ Projektstruktur

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

🧪 Tests

Unit-Tests (reine Funktionen, kein API-Schlüssel erforderlich):

npm test

Live Smoke Test (tatsächlicher V-World-Aufruf, VWORLD_API_KEY erforderlich):

# 단일 지번 디버그
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: Städtisches Wohngebiet (Yeonnam-dong), Land-Forst-Gebiet + vorrangige Delegation (Sechul-ri), gemischte Nutzungszone + Stadtentwicklung (Galmae-ri).

⚠️ Bekannte Einschränkungen

• Punktbasierte Beurteilung: Die Standardabfrage sendet einen einzelnen Mittelpunkt des Grundstücks an V-World. Da es sich nicht um eine Schnittmengenprüfung von Grundstückspolygonen handelt, können Fälle an den Grenzen übersehen werden. Der radius_m-Parameter in get_urban_facility mildert dies durch einen BOX-Filter ab, aber die endgültige Entscheidung über „betroffen“ vs. „angrenzend“ erfordert eine erneute Überprüfung der Polygon-Schnittmenge durch den Benutzer oder den zuständigen Beamten.

• V-World Layer-Störungen: Einige Layer geben sporadisch HTTP 500 zurück. Nach einem einmaligen Wiederholungsversuch bei 5xx-Fehlern wird der Fehler in layer_errors angezeigt, während die Ergebnisse der restlichen Layer normal zurückgegeben werden.

• Keine kommunalen Verordnungen enthalten: Dieses MCP deckt nur die Raum-Layer ab. Die Texte der städtebaulichen Verordnungen der Kommunen müssen separat über korean-law-mcp oder die API des Ministeriums für Gesetzgebung (자치법규 API) abgefragt werden.

📜 Lizenz

MIT License.

🤝 Beitrag

Issues und PRs sind willkommen. Beim Hinzufügen eines neuen V-World-Layers müssen Sie lediglich { id, label } zum LAYERS-Array in src/tools/*.ts hinzufügen, um es automatisch in die queryOverlays-Pipeline aufzunehmen.