🇰🇷 韩国土地 MCP (Korean Land MCP) — v2.0

基于 V-World API 的土地与城市规划空间信息 MCP 服务器 该服务器使用韩国国土交通部 V-World Open API 作为后端，是一个 Model Context Protocol 服务器，旨在让 AI 能够通过自然语言查询原本需要人工在“土地连接 (eum.go.kr)”上手动确认的 用途区域、用途地区、用途区域、地球单位规划、城市规划设施及其他法律指定事项。

这是一个与 korean-law-mcp（法律文本）配套的 空间层 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 → 交互式 configure。在配置阶段，系统会询问 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

• “半径 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

实时冒烟测试 (实际调用 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

测试用例: 城市居住区（延南洞）、农林地区+优先委托（世出里）、复合用途区域+城市开发（葛梅里）。

⚠️ 已知限制

• 基于点的判定: 默认查询将地块中心点 1 个坐标发送给 V-World。由于不是地块多边形交叉，可能会漏掉跨越边界的情况。get_urban_facility 的 radius_m 通过 BOX 过滤器缓解了这一限制，但“抵触”与“接壤”的最终判定仍需用户或相关公务员进行多边形交叉复核。

• V-World 图层故障: 部分图层会间歇性返回 HTTP 500。在 5xx 错误重试一次后若仍失败，将暴露在 layer_errors 中，其余图层结果正常返回。

• 不包含地方自治团体条例: 此 MCP 仅包含空间图层。地方自治团体的城市规划条例条文需通过 korean-law-mcp 或法制处自治法规 API 另行查询。

📜 许可证

MIT License.

🤝 贡献

欢迎提交 Issue 和 PR。添加新的 V-World 图层时，只需在 src/tools/*.ts 的 LAYERS 数组中添加 { id, label }，即可自动纳入 queryOverlays 流水线。