🇰🇷 MCP de Suelo Coreano (Información Espacial de Terrenos) — v2.0

Servidor MCP de información espacial sobre terrenos y planificación urbana basado en la API de V-World Utilizando la API abierta V-World del Ministerio de Tierra, Infraestructura y Transporte como backend, este es un servidor de Model Context Protocol que permite a la IA consultar en lenguaje natural los usos del suelo, distritos, zonas, planes de unidades de distrito, instalaciones de planificación urbana y otras designaciones legales que antes debían verificarse manualmente en Land-eum (eum.go.kr).

Una capa espacial MCP que se complementa con korean-law-mcp (texto legal). Al usar ambos MCP juntos, se puede conectar en una sola línea de lenguaje natural: "¿A qué pertenece esta parcela? → ¿Qué permite/restringe la normativa u ordenanza correspondiente?".

✨ Principios de arquitectura v2.0

1. Exclusivo para la API de V-World. Sin otras APIs comerciales, scraping o datos simulados (mock).

2. Fallo honesto. Si V-World devuelve un error 500 en una capa específica, se expone tal cual en layer_errors. Nunca se rellena con datos falsos.

3. Separación de roles con korean-law-mcp. Este MCP solo responde a "¿dónde se encuentra espacialmente?". La interpretación de los artículos legales queda para korean-law-mcp.

4. Detección automática de delegación prioritaria según el Art. 76⑤ de la Ley de Planificación Territorial. Si zonas como áreas de promoción agrícola, bosques de conservación, zonas de protección de fuentes de agua o complejos industriales nacionales afectan a la parcela, se informa mediante priority_delegation_hint sobre "qué ley debe consultarse primero en lugar de la tabla del Decreto de Ejecución de la Ley de Planificación Territorial".

Related MCP server: Korea Building Register MCP

🛠️ Herramientas proporcionadas (7)

También incluye discover_tools para explorar el catálogo de herramientas mediante lenguaje natural.

📡 Cobertura de capas de V-World

• Uso del suelo: LT_C_UQ111/112/113/114 (urbano, gestión, agrícola, conservación del entorno natural)

• Distritos/Zonas: LT_C_UQ121~130, LT_C_UD801, LT_C_UQ162

• Planes de distrito/Restricciones: LT_C_UPISUQ161, LT_C_UPISUQ171

• Instalaciones urbanas: LT_C_UPISUQ151~159

• Otras designaciones legales: Tierras agrícolas (AGRIXUE) · Bosques (UF) · Complejos industriales (WGISIE*, DAM*) · Calidad del agua (UM, WGISARWET) · Ganadería (UM000) · Patrimonio cultural (UO) · Parques naturales (WGISNP*) · Distritos especiales (UO/UJ/UH/UB) · Reurbanización (UD) · Desastres (UP) · Marina (TFISMPA, WGISRE*) · Aviación (AIS*)

• Parcelas/Edificios: LP_PA_CBND_BUBUN, LT_C_BLDGINFO, A2SM_LNDPRCPS

🚀 Inicio rápido

1. Configuración completa

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

npm run setup ejecuta npm install → npm run build → configuración interactiva. En la fase de configuración, solicita la clave API y el dominio de V-World y genera automáticamente el archivo .env.

Obtención de clave API de V-World: https://www.vworld.kr/dev/v4api.do (Iniciar sesión → API abierta → Emitir clave de autenticación, gratuito). Para desarrollo local, registre el dominio como localhost.

2. Reconfiguración

Si desea cambiar la clave API o modificar el dominio:

npm run configure

3. Registro en Claude Desktop / Claude Code

Al finalizar la configuración, se imprime en la terminal el bloque JSON necesario. O manualmente:

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

💬 Ejemplos de uso

• "Dime el uso del suelo de 680 Naegi-ri, Poseung-eup, Pyeongtaek-si, Gyeonggi-do" → get_zoning

• "Comprueba si se aplica la delegación prioritaria del Art. 76⑤ a esta parcela" → get_other_law_designations

• "¿Hay instalaciones de planificación urbana afectadas o adyacentes en un radio de 50m?" → get_urban_facility({ radius_m: 50 })

• "Analiza este número de lote completo y dime el siguiente paso para korean-law" → analyze_parcel

🧭 Flujo de trabajo con korean-law-mcp

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

🗂️ Estructura del proyecto

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

🧪 Pruebas

Pruebas unitarias (funciones puras, no requiere clave API):

npm test

Prueba de humo en vivo (llamada real a V-World, requiere 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: Zona residencial urbana (Yeonnam-dong), zona agrícola/forestal + delegación prioritaria (Sechul-ri), zona de uso mixto + desarrollo urbano (Galmae-ri).

⚠️ Limitaciones conocidas

• Determinación basada en puntos: La consulta básica envía 1 punto central de la parcela a V-World. Dado que no es una intersección de polígonos de parcela, los casos que tocan el límite pueden pasarse por alto. El radius_m de get_urban_facility mitiga esta limitación con un filtro BOX, pero la determinación final de "afectado" vs "adyacente" requiere una re-verificación de intersección de polígonos por parte del usuario o del funcionario a cargo.

• Fallo en capas de V-World: Algunas capas devuelven HTTP 500 de forma intermitente. Si falla después de 1 reintento de 5xx, se expone en layer_errors, y los resultados de las capas restantes se devuelven normalmente.

• Exclusión de ordenanzas locales: Este MCP solo cubre capas espaciales. Los artículos de las ordenanzas de planificación urbana locales deben consultarse por separado mediante korean-law-mcp o la API de leyes locales del Ministerio de Legislación Gubernamental.

📜 Licencia

Licencia MIT.

🤝 Contribución

Se aceptan issues y PRs. Al añadir una nueva capa de V-World, solo es necesario agregar { id, label } al array LAYERS en src/tools/*.ts para que se incorpore automáticamente a la tubería queryOverlays.