# FieldCure MCP PublicData.Kr

[![NuGet](https://img.shields.io/nuget/v/FieldCure.Mcp.PublicData.Kr)](https://www.nuget.org/packages/FieldCure.Mcp.PublicData.Kr)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/fieldcure/fieldcure-mcp-publicdata/blob/main/LICENSE)

Korean public data API gateway. A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that lets any MCP client discover, inspect, and call 80,000+ APIs on [data.go.kr](https://www.data.go.kr) — weather, real estate, business registration, air quality, transit, and more. Built with C# and the official [MCP C# SDK](https://github.com/modelcontextprotocol/csharp-sdk).

## Features

- **3 tools** — search APIs by keyword, inspect parameters/response fields, call any data.go.kr API
- **Automatic serviceKey injection** — the API key is added to every request; never leaked to the LLM
- **Lazy key resolution** — env var → MCP Elicitation → soft-fail chain (no hard-fail on startup). Hosts that support [MCP Elicitation](https://modelcontextprotocol.io/specification/2025-06-18/server/elicitation) can prompt the user for the key on first use; on upstream `401/403` or `SERVICE_KEY_IS_NOT_REGISTERED` the cached key is invalidated and a re-elicit is attempted (session cap: 2 re-elicits)
- **XML → JSON normalization** — strips the `response/header/body/items` wrapper, returns clean JSON
- **Error code mapping** — translates data.go.kr error codes into Korean guidance messages the LLM can relay directly
- **SSRF protection** — domain whitelist limits calls to approved government hosts
- **EUC-KR support** — legacy encoding from older government APIs is auto-detected and converted
- **Stateless** — no cache, no database, no local files; every call is independent
- **Stdio transport** — standard MCP subprocess model via JSON-RPC over stdin/stdout

## Installation

### dotnet tool (recommended)

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

After installation, the `fieldcure-mcp-publicdata-kr` command is available globally.

### From source

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

## Prerequisites

1. Sign up at [data.go.kr](https://www.data.go.kr) and get your API key
   (data.go.kr 회원가입 후 인증키 발급)
2. **Subscribe to [목록조회서비스](https://www.data.go.kr/data/15077093/openapi.do)** (Required)
   — `discover_api` and `describe_api` depend on this API
   (discover_api, describe_api 도구가 이 API를 사용합니다)
3. Subscribe to each individual API you want to query
   (조회하려는 개별 API도 각각 활용신청 필요)

## Requirements

- [.NET 8.0 Runtime](https://dotnet.microsoft.com/download/dotnet/8.0) or later

## Authentication

This server requires a **data.go.kr API key** (공공데이터포털 인증키). Key resolution is
lazy (on first tool call) and follows the [FieldCure MCP Credential ADR](https://github.com/fieldcure/fieldcure-assiststudio/blob/main/docs/ADR-001-MCP-Credential-Management.md):

1. **Environment variable** — `DATA_GO_KR_API_KEY` (canonical) or `PUBLICDATA_API_KEY` (legacy alias)
2. **MCP Elicitation** — if no env var is found, the server requests the key interactively
   on the first tool call (requires a client that supports MCP Elicitation — e.g. Claude
   Code ≥ 2.1.76, AssistStudio). The resolved key is cached in process memory for the
   session lifetime and is never written to disk by the server.
3. **Soft-fail** — if both paths fail, `tools/list` still works and tool calls return a
   structured error message asking the user to set the env var.

`--api-key <value>` is also accepted as a CLI arg but is intended for manual testing only,
not as a supported configuration path.

### Setup by host

**Claude Code / Claude Desktop** — add the key to your MCP config:

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

On Claude Code (≥ 2.1.76), if the env var is omitted the server prompts for the key via
Elicitation on first use.

**AssistStudio** — the key is requested via Elicitation on first use and stored in Windows
PasswordVault for subsequent launches; the host then injects it as an env var when
starting the server.

**Docker / CI** — pass the key as a standard environment variable:

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

### Key validation and re-elicitation

If the server receives an HTTP 401/403 or a `resultCode=22` / `SERVICE_KEY_IS_NOT_REGISTERED_ERROR`
body from data.go.kr, it invalidates the cached key and re-requests via Elicitation
(session cap: 2 re-elicits per `ApiKeyResolver` lifetime). After exhausting retries, the
tool returns a soft-fail error message.

> **Note:** On data.go.kr an HTTP 401 can mean either an invalid key *or* an API that you
> have not applied for (활용신청). If a re-elicitation prompt appears right after calling
> an API you haven't subscribed to, entering the same key will produce the final error
> envelope with details — at that point visit the API's data.go.kr page and apply for access.

## Configuration

### Claude Desktop

Add to `claude_desktop_config.json`:

```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+)

```bash
claude mcp add publicdata-kr -- fieldcure-mcp-publicdata-kr
```

Claude Code supports MCP Elicitation, so `DATA_GO_KR_API_KEY` may be omitted — the
server will prompt for the key on first tool use.

### VS Code (Copilot)

Add to `.vscode/mcp.json`:

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

### From source (without dotnet tool)

```json
{
  "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

> **Install the dotnet tool first.** AssistStudio does not auto-install external MCP
> servers (only built-in ones are managed via the AssistStudio auto-update path).
> The `fieldcure-mcp-publicdata-kr` command must be on PATH before you add the server,
> otherwise the connection fails with a generic "server shut down unexpectedly" message.
>
> ```bash
> dotnet tool install -g FieldCure.Mcp.PublicData.Kr
> # later, to upgrade:
> dotnet tool update -g FieldCure.Mcp.PublicData.Kr
> ```

Then: Settings > MCP Servers > **Add Server**:

| Field | Value |
|-------|-------|
| **Name** | `PublicData.Kr` |
| **Command** | `fieldcure-mcp-publicdata-kr` |
| **Arguments** | *(empty)* |
| **Environment** | `DATA_GO_KR_API_KEY` = your data.go.kr API key *(optional — AssistStudio can prompt via Elicitation if unset)* |
| **Description** | *(auto-filled on first connection)* |

## Tools

| Tool | Description |
|------|-------------|
| `discover_api` | Search data.go.kr APIs by keyword — returns names, providers, endpoint URLs |
| `describe_api` | Get operations, request parameters, and response fields for a specific API |
| `call_api` | Call any data.go.kr API with automatic serviceKey injection and response normalization |

### Workflow

```
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`

Search Korean public data APIs on data.go.kr by keyword. Results are deduplicated by service — each API appears once even if it has multiple operations.

| Parameter | Type | Required | Description |
|-----------|------|:--------:|-------------|
| `query` | string | Yes | Search keyword (e.g., `미세먼지`, `부동산`, `사업자`) |
| `page` | int | — | Page number (default: 1) |
| `pageSize` | int | — | Results per page (default: 10, max: 50) |

### `describe_api`

Get the request parameters and response fields of a specific API. Use the `serviceId` from `discover_api` results.

| Parameter | Type | Required | Description |
|-----------|------|:--------:|-------------|
| `serviceId` | string | Yes | Service ID (`list_id`) from `discover_api` |

### `call_api`

Call a Korean public data API. The serviceKey is automatically injected — never pass it yourself. If the call fails with ACCESS_DENIED, the user needs to apply for access to that specific API at data.go.kr.

| Parameter | Type | Required | Description |
|-----------|------|:--------:|-------------|
| `url` | string | Yes | Full endpoint URL from `describe_api` results |
| `params` | string | — | Query parameters as a JSON **string** (not a raw object), e.g. `'{"stationName":"종로구","dataTerm":"DAILY"}'`. Parameter names must come from `describe_api`'s `request_parameters` — do not guess. |
| `maxResults` | int | — | Max items to return (default: 20, prevents context overflow) |

## Error Code Mapping

When a data.go.kr API returns an error, the server translates it into a Korean guidance message the LLM can relay directly:

| Code | Meaning | LLM receives |
|------|---------|--------------|
| 12 | NO_OPENAPI_SERVICE | 이 API가 존재하지 않습니다. discover_api로 다시 검색해보세요. |
| 20 | ACCESS_DENIED | 이 API에 대한 활용신청이 필요합니다. (포털 링크 포함) |
| 22 | KEY_NOT_REGISTERED | API 키가 등록되지 않았습니다. |
| 30 | TRAFFIC_EXCEEDED | 일일 호출 한도를 초과했습니다. |
| 31 | UNREGISTERED_IP | 이 IP가 등록되지 않았습니다. |

## Environment Variables

| Variable | Required | Default | Description |
|----------|:--------:|---------|-------------|
| `DATA_GO_KR_API_KEY` | — | — | data.go.kr API key (인증키). If unset, the server requests it via MCP Elicitation on first tool call. |
| `PUBLICDATA_API_KEY` | — | — | Legacy alias for `DATA_GO_KR_API_KEY`. Still accepted; prefer the canonical name for new setups. |
| `PUBLICDATA_TIMEOUT_SECONDS` | — | 30 | Per-request timeout |
| `PUBLICDATA_MAX_RESPONSE_LENGTH` | — | 50000 | Maximum response body length in characters |

CLI args (`--api-key`, `--timeout`, `--max-response-length`) override environment variables
and are intended for manual testing only — `DATA_GO_KR_API_KEY` and Elicitation are the
supported paths.

> **Naming note:** the API key follows the external service naming convention
> (`DATA_GO_KR_API_KEY`), while server-local configuration uses the `PUBLICDATA_` prefix.
> This keeps the key aligned with data.go.kr's own documentation so users don't have to
> configure it twice, while local tunables stay grouped under a single package namespace.

## Security

- **API key masking** — the serviceKey is replaced with `***` in any error output visible to the LLM
- **Domain whitelist** — `call_api` only allows requests to approved hosts: `api.odcloud.kr`, `apis.data.go.kr`, `api.data.go.kr`, `openapi.data.go.kr`, `www.law.go.kr`, `open.neis.go.kr`
- **Response size limit** — configurable via `PUBLICDATA_MAX_RESPONSE_LENGTH` (default: 50,000 chars)
- **No log leaks** — the API key is never printed to stdout or stderr

## Project Structure

```
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
```

## Development

```bash
# Build
dotnet build

# Test
dotnet test

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

## See Also

Part of the [AssistStudio ecosystem](https://github.com/fieldcure/fieldcure-assiststudio#packages).

## License

[MIT](LICENSE)