publicdata-kr

FieldCure MCP PublicData.Kr

韩国公共数据 API 网关。这是一个 Model Context Protocol (MCP) 服务，允许任何 MCP 客户端发现、检查并调用 data.go.kr 上的 80,000 多个 API，涵盖天气、房地产、企业注册、空气质量、公共交通等领域。使用 C# 和官方 MCP C# SDK 构建。

功能

• 3 个工具 — 按关键词搜索 API、检查参数和响应字段、调用任意 data.go.kr API
• 自动注入 serviceKey — API 密钥会添加到每个请求中，绝不会泄露给大模型
• 惰性密钥解析 — 环境变量 → MCP Elicitation → 软失败链（启动时不会硬失败）。支持 MCP Elicitation 的宿主可以在首次使用时提示用户输入密钥；遇到上游 401/403 或 SERVICE_KEY_IS_NOT_REGISTERED 时，会使缓存密钥失效并尝试重新询问（每个会话最多重新询问 2 次）
• XML → JSON 规范化 — 移除 response/header/body/items 包装，返回整洁的 JSON
• 错误代码映射 — 将 data.go.kr 错误代码转换为韩文指导消息，供大模型直接转述
• SSRF 防护 — 域名白名单将调用限制在获批的政府主机范围内
• EUC-KR 支持 — 自动检测并转换旧版政府 API 使用的传统编码
• 无状态 — 无缓存、无数据库、无本地文件；每次调用均独立执行
• Stdio 传输 — 通过 stdin/stdout 使用 JSON-RPC 的标准 MCP 子进程模型

安装

dotnet tool（推荐）

dotnet tool install -g FieldCure.Mcp.PublicData.Kr

安装后，fieldcure-mcp-publicdata-kr 命令即可全局使用。

从源代码安装

git clone https://github.com/fieldcure/fieldcure-mcp-publicdata.git
cd fieldcure-mcp-publicdata
dotnet build

前置条件

1. 在 data.go.kr 注册并获取 API 密钥 （在 data.go.kr 注册会员后申请认证密钥）
2. 订阅 목록조회서비스（必需） — discover_api 和 describe_api 依赖此 API （discover_api、describe_api 工具会使用此 API）
3. 订阅要查询的每个单独 API （查询所需的各个 API 也需分别申请使用）

系统要求

• .NET 8.0 Runtime 或更高版本

身份验证

此服务需要 data.go.kr API 密钥（公共数据门户认证密钥）。密钥采用 惰性解析（首次调用工具时），并遵循 FieldCure MCP Credential ADR：

1. 环境变量 — DATA_GO_KR_API_KEY（规范名称）或 PUBLICDATA_API_KEY（旧版别名）
2. MCP Elicitation — 如果未找到环境变量，服务会在首次调用工具时交互式请求密钥 （需要客户端支持 MCP Elicitation，例如 Claude Code ≥ 2.1.76、AssistStudio）。解析出的密钥会缓存在进程内存中，供整个会话使用；服务绝不会将其写入磁盘。
3. 软失败 — 如果这两种方式都失败，tools/list 仍可正常工作，工具调用会返回 结构化错误消息，提示用户设置环境变量。

也接受 --api-key <value> 作为 CLI 参数，但该参数仅供手动测试， 并非受支持的配置方式。

按宿主设置

Claude Code / Claude Desktop — 将密钥添加到 MCP 配置中：

{
  "mcpServers": {
    "publicdata-kr": {
      "command": "fieldcure-mcp-publicdata-kr",
      "env": {
        "DATA_GO_KR_API_KEY": "<your-key>"
      }
    }
  }
}

在 Claude Code（≥ 2.1.76）中，如果省略环境变量，服务会在首次使用时通过 Elicitation 提示输入密钥。

AssistStudio — 首次使用时会通过 Elicitation 请求密钥，并将其存储在 Windows PasswordVault 中以供后续启动使用；随后，宿主会在启动服务时将密钥注入为环境变量。

Docker / CI — 将密钥作为标准环境变量传入：

docker run -e DATA_GO_KR_API_KEY=<your-key> ...

密钥验证与重新请求

如果服务收到 HTTP 401/403，或收到来自 data.go.kr 的 resultCode=22 / SERVICE_KEY_IS_NOT_REGISTERED_ERROR 响应正文，则会使缓存的密钥失效，并通过 Elicitation 重新请求密钥（每个 ApiKeyResolver 生命周期最多重新请求 2 次）。重试次数用尽后，工具会返回软失败错误消息。

注意： 在 data.go.kr 上，HTTP 401 既可能表示密钥无效，也可能表示你尚未申请使用该 API（활용신청）。如果你调用尚未订阅的 API 后立即出现重新请求密钥的提示，输入相同的密钥会返回包含详细信息的最终错误响应；此时请访问该 API 的 data.go.kr 页面并申请访问权限。

配置

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "publicdata-kr": {
      "command": "fieldcure-mcp-publicdata-kr",
      "env": {
        "DATA_GO_KR_API_KEY": "YOUR_DATA_GO_KR_API_KEY"
      }
    }
  }
}

Claude Code（v2.1.76+）

claude mcp add publicdata-kr -- fieldcure-mcp-publicdata-kr

Claude Code 支持 MCP Elicitation，因此可以省略 DATA_GO_KR_API_KEY — 服务会在首次使用工具时提示输入密钥。

VS Code（Copilot）

添加到 .vscode/mcp.json：

{
  "servers": {
    "publicdata-kr": {
      "command": "fieldcure-mcp-publicdata-kr",
      "env": {
        "DATA_GO_KR_API_KEY": "YOUR_DATA_GO_KR_API_KEY"
      }
    }
  }
}

从源代码运行（不使用 dotnet tool）

{
  "mcpServers": {
    "publicdata-kr": {
      "command": "dotnet",
      "args": [
        "run",
        "--project", "C:\\path\\to\\fieldcure-mcp-publicdata\\src\\FieldCure.Mcp.PublicData.Kr"
      ],
      "env": {
        "DATA_GO_KR_API_KEY": "YOUR_DATA_GO_KR_API_KEY"
      }
    }
  }
}

AssistStudio

请先安装 dotnet tool。 AssistStudio 不会自动安装外部 MCP 服务（仅内置服务通过 AssistStudio 自动更新流程进行管理）。 添加服务前，必须确保 fieldcure-mcp-publicdata-kr 命令已加入 PATH， 否则连接会失败，并显示通用错误消息“server shut down unexpectedly”。

dotnet tool install -g FieldCure.Mcp.PublicData.Kr
# later, to upgrade:
dotnet tool update -g FieldCure.Mcp.PublicData.Kr

然后依次选择：Settings > MCP Servers > Add Server：

字段	值
名称	PublicData.Kr
命令	fieldcure-mcp-publicdata-kr
参数	(空)
环境变量	DATA_GO_KR_API_KEY = 你的 data.go.kr API 密钥 (可选 — 如果未设置，AssistStudio 可通过 Elicitation 提示输入)
说明	(首次连接时自动填充)

工具

工具	说明
discover_api	按关键词搜索 data.go.kr API — 返回名称、提供方和端点 URL
describe_api	获取特定 API 的操作、请求参数和响应字段
call_api	调用任意 data.go.kr API，自动注入 serviceKey 并规范化响应

工作流

1. discover_api("미세먼지")
   → { serviceId: "15073861", serviceName: "한국환경공단_에어코리아_대기오염정보", ... }

2. describe_api("15073861")
   → { operations: [{ name: "getMsrstnAcctoRltmMesureDnsty", url: "...", requestParameters: [...] }] }

3. call_api(url: "http://apis.data.go.kr/B552584/ArpltnInforInqireSvc/getMsrstnAcctoRltmMesureDnsty",
            params: '{"stationName": "종로구", "dataTerm": "DAILY", "returnType": "json"}')
   → { totalCount: 24, items: [{ stationName: "종로구", pm10Value: "45", ... }] }

discover_api

按关键词搜索 data.go.kr 上的韩国公共数据 API。结果按服务去重 — 即使某个 API 包含多个操作，也只会显示一次。

参数	类型	必填	说明
query	string	是	搜索关键词（例如：미세먼지、부동산、사업자）
page	int	—	页码（默认：1）
pageSize	int	—	每页结果数（默认：10，最大：50）

describe_api

获取特定 API 的请求参数和响应字段。使用 discover_api 结果中的 serviceId。

参数	类型	必填	说明
serviceId	string	是	来自 discover_api 的服务 ID（list_id）

call_api

调用韩国公共数据 API。系统会自动注入 serviceKey，切勿自行传入。如果调用因 ACCESS_DENIED 失败，用户需要在 data.go.kr 申请访问该特定 API。

参数	类型	必填	说明
url	string	是	describe_api 结果中的完整端点 URL
params	string	—	JSON 字符串形式的查询参数（不是原始对象），例如 '{"stationName":"종로구","dataTerm":"DAILY"}'。参数名称必须来自 describe_api 的 request_parameters，不要猜测。
maxResults	int	—	要返回的最大项目数（默认：20，可防止上下文溢出）

错误代码映射

当 data.go.kr API 返回错误时，服务会将其转换为韩语指导消息，供大模型直接转达：

代码	含义	大模型收到的消息
12	NO_OPENAPI_SERVICE	이 API가 존재하지 않습니다. discover_api로 다시 검색해보세요.
20	ACCESS_DENIED	이 API에 대한 활용신청이 필요합니다. (포털 링크 포함)
22	KEY_NOT_REGISTERED	API 키가 등록되지 않았습니다.
30	TRAFFIC_EXCEEDED	일일 호출 한도를 초과했습니다.
31	UNREGISTERED_IP	이 IP가 등록되지 않았습니다.

环境变量

变量	必填	默认值	说明
DATA_GO_KR_API_KEY	—	—	data.go.kr API 密钥（인증키）。如果未设置，服务会在首次调用工具时通过 MCP Elicitation 请求该密钥。
PUBLICDATA_API_KEY	—	—	DATA_GO_KR_API_KEY 的旧别名。仍可使用；新配置请优先使用规范名称。
PUBLICDATA_TIMEOUT_SECONDS	—	30	每次请求的超时时间
PUBLICDATA_MAX_RESPONSE_LENGTH	—	50000	响应正文的最大字符数

CLI 参数（--api-key、--timeout、--max-response-length）会覆盖环境变量， 仅供手动测试使用——受支持的配置方式是 DATA_GO_KR_API_KEY 和 Elicitation。

命名说明： API 密钥遵循外部服务的命名约定 （DATA_GO_KR_API_KEY），而服务本地配置使用 PUBLICDATA_ 前缀。 这样，密钥名称便与 data.go.kr 自身的文档保持一致，用户无需重复配置， 同时本地可调参数也归在同一套包命名空间下。

安全性

• API 密钥屏蔽 — 在大模型可见的任何错误输出中，serviceKey 都会替换为 ***
• 域名白名单 — call_api 仅允许向获准的主机发起请求：api.odcloud.kr、apis.data.go.kr、api.data.go.kr、openapi.data.go.kr、www.law.go.kr、open.neis.go.kr
• 响应大小限制 — 可通过 PUBLICDATA_MAX_RESPONSE_LENGTH 配置（默认：50,000 个字符）
• 不泄露日志 — API 密钥绝不会输出到 stdout 或 stderr

项目结构

src/FieldCure.Mcp.PublicData.Kr/
├── Program.cs                       # MCP server entry point (stdio); no startup hard-fail
├── Services/
│   ├── ApiKeyResolver.cs            # env var → MCP Elicitation → soft-fail chain + cache + retry cap
│   ├── InvalidApiKeyException.cs    # Signals upstream auth rejection (HTTP 401/403 or body error)
│   ├── KeyedCall.cs                 # Tool-side resolve → run → invalidate → retry helper
│   ├── PublicDataHttpClient.cs      # HTTP proxy with serviceKey injection + auth-error detection
│   ├── DomainWhitelist.cs           # SSRF prevention via host whitelist
│   ├── ResponseNormalizer.cs        # XML→JSON conversion, wrapper removal
│   └── ErrorCodeMapper.cs           # Error code → Korean guidance messages
└── Tools/
    ├── DiscoverApiTool.cs           # discover_api
    ├── DescribeApiTool.cs           # describe_api
    └── CallApiTool.cs               # call_api

开发

# Build
dotnet build

# Test
dotnet test

# Pack as dotnet tool
dotnet pack src/FieldCure.Mcp.PublicData.Kr -c Release

另请参阅

属于 AssistStudio 生态系统 的一部分。

许可证

MIT