🇰🇷 Korean Land MCP (MCP пространственных данных о земле) — v2.0

MCP-сервер пространственных данных о земле и городском планировании на базе V-World API Используя V-World Open API Министерства земли, инфраструктуры и транспорта в качестве бэкенда, это Model Context Protocol сервер, который позволяет ИИ запрашивать на естественном языке информацию о зонах использования, районах использования, зонах планирования, планах детальной планировки, объектах городского планирования и других нормативных актах, которую раньше приходилось проверять вручную на сайте 토지이음 (eum.go.kr).

Пространственный слой MCP, работающий в паре с korean-law-mcp (тексты законов). При совместном использовании этих двух MCP можно одной фразой на естественном языке связать вопрос: «К какой зоне относится этот участок?» с ответом: «Какие действия разрешены/ограничены соответствующими законами и постановлениями?».

✨ Принципы архитектуры v2.0

1. Только V-World API. Никаких других коммерческих API, парсинга или фиктивных (mock) данных.

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 → интерактивная настройка. На этапе настройки запрашиваются ключ V-World API и домен, после чего автоматически создается файл .env.

Получение ключа V-World API: https://www.vworld.kr/dev/v4api.do (вход → Open API → получение ключа, бесплатно). Для локальной разработки в качестве домена можно указать localhost.

2. Повторная настройка

Если вы хотите изменить ключ API или домен:

npm run configure

3. Регистрация в Claude Desktop / Claude Code

После завершения настройки в терминал будет выведен 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

• «Есть ли объекты городского планирования в радиусе 50 м?» → 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

Фикстуры: городская жилая зона (Ённам-дон), сельскохозяйственная зона + приоритетное делегирование (Сечхуль-ри), смешанная зона + городское развитие (Кальме-ри).

⚠️ Известные ограничения

• Определение на основе точки: Базовый запрос отправляет в V-World 1 центральную точку участка. Поскольку это не пересечение полигонов участка, случаи на границах могут быть пропущены. Параметр radius_m в get_urban_facility смягчает это ограничение с помощью BOX-фильтра, но для окончательного решения о «затрагивании» или «прилегании» требуется перепроверка пересечения полигонов пользователем или ответственным чиновником.

• Сбои слоев V-World: Некоторые слои периодически возвращают HTTP 500. После 1 повторной попытки в случае сбоя 5xx, ошибка отображается в layer_errors, а результаты по остальным слоям возвращаются нормально.

• Отсутствие муниципальных постановлений: Этот MCP работает только с пространственными слоями. Тексты муниципальных постановлений о городском планировании следует запрашивать отдельно через korean-law-mcp или API Министерства законодательства.

📜 Лицензия

MIT License.

🤝 Вклад

Ишью и PR приветствуются. При добавлении нового слоя V-World достаточно добавить { id, label } в массив LAYERS в src/tools/*.ts, и он автоматически попадет в конвейер queryOverlays.