busan-essentials

# Busan Essentials — MCP Server

Find the nearest restroom, pharmacy, free WiFi, AED, or tourist information center in Busan, South Korea. 8,680 places from Korean government open data, every record in both Korean and English.

<a href="https://glama.ai/mcp/servers/@do-droid/busan-essentials">
  <img width="380" height="200" src="https://glama.ai/mcp/servers/@do-droid/busan-essentials/badge" alt="busan-essentials MCP server" />
</a>

## What is this?

Busan Essentials is an MCP (Model Context Protocol) server that answers "where is the nearest X in Busan?" for AI agents helping travellers and residents. Every record carries a Korean **and** English name and address, so an agent can hand the Korean text to a taxi driver and the English to the traveller.

## Available Data

| Type | Description | Count |
|------|-------------|-------|
| `aed` | AED (defibrillator) locations | 2,799 |
| `toilet` | Public restrooms across all 16 districts | 2,487 |
| `wifi` | Free public WiFi hotspots | 1,702 |
| `pharmacy` | Pharmacies in Busan | 1,667 |
| `tourist_info` | Tourist information centers | 25 |

> **8,680 places live** across all 16 Busan districts, sourced from data.go.kr. Each record has GPS coordinates, opening hours, accessibility flags, and a `trust_score`.
>
> **Not covered:** subway and bus timetables, taxis, restaurants, hotels, attractions, and anywhere outside Busan. `get_subway_timetable` is registered but has no data loaded — see **Known Data Limitations**.

## MCP Tools

### `find_places`
Search by type, district, and attributes. Use `find_nearby` instead when the user has a location or asks for the *nearest* one.

**Parameters:**
- `type` (required): `"toilet"` | `"pharmacy"` | `"wifi"` | `"aed"` | `"tourist_info"`
- `district` (optional): Busan district name in English or Korean (e.g., `"haeundae"`, `"해운대구"`)
- `filters` (optional): Attribute filters, all of which must match. Only these exist:

  | Type | Filter | Matching records |
  |------|--------|------------------|
  | `toilet` | `{"wheelchair": true}` | 1,050 of 2,487 |
  | `toilet` | `{"is_24h": true}` | 839 of 2,487 |
  | `toilet` | `{"diaper_table": true}` | 433 of 2,487 |
  | `tourist_info` | `{"english": true}` | 14 of 25 |
  | `tourist_info` | `{"chinese": true}` | 13 of 25 |
  | `tourist_info` | `{"japanese": true}` | 9 of 25 |

  `pharmacy`, `wifi`, and `aed` carry no usable filter — the upstream sources record no per-facility variation. An unknown filter key returns zero results rather than being ignored.
- `limit` (optional): Max results, 1-50 (default: 10)

### `get_place_detail`
Get the full record for one facility by its ID. IDs come from `find_places` or `find_nearby` — don't guess them.

**Parameters:**
- `id` (required): Place ID (e.g., `"toilet_00001"`, `"pharmacy_0538"`, `"aed_00001"`, `"tourist_info_08"`)

### `find_nearby`
Find the nearest facilities to a GPS point, sorted by distance. The right default for "nearest", "closest", or "around here" — and for urgent needs.

**Parameters:**
- `lat` (required): Latitude (Busan spans ~35.04 to ~35.40)
- `lng` (required): Longitude (Busan spans ~128.78 to ~129.30)
- `radius_m` (optional): Search radius in meters, 100-5000 (default: 500). Widen it if the first call comes back empty — 500m is dense downtown but sparse in outer districts.
- `type` (optional): Restrict to one facility type. Omit to get whatever is closest.
- `limit` (optional): Max results, 1-20 (default: 5)

Each result includes `distance_m`, the straight-line distance from the search point.

### `get_subway_timetable`
**Not available yet.** No timetable data is loaded, so every call returns nothing for every station. The tool stays registered so it starts working the moment the data lands — see **Known Data Limitations**.

### `submit_feedback`
Report missing, wrong, or stale data. Reports are read and acted on: earlier reports about empty English fields led to all 8,680 records being filled.

**Parameters:**
- `category` (required): `new_data` | `data_quality` | `coverage` | `format` | `frequency` | `other`
- `message` (required): What's wrong. Include the place ID when you have one.
- `priority` (optional): `low` | `medium` | `high` (default: `medium`)

## Quick Start

### Option A: Smithery (Recommended)

Visit [Busan Essentials on Smithery](https://smithery.ai/servers/do-droid/busan-essentials) and follow the setup instructions for your MCP client.

### Option B: Direct Connection

Add to your MCP client config (e.g., Claude Desktop `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "busan-essentials": {
      "url": "https://busan-essentials-mcp-85013349489.asia-northeast3.run.app/mcp"
    }
  }
}
```

### Option C: Run Locally

```bash
git clone https://github.com/do-droid/busan-essentials.git
cd busan-essentials
API_BASE_URL="https://asia-northeast3-busan-essentials.cloudfunctions.net/api" \
uv run python -m src.server
```

## Example Queries

An AI agent can use these tools to answer questions like:

**English**
- "Find a pharmacy near Seomyeon Station"
- "Where is the nearest public restroom to Haeundae Beach?"
- "I need a wheelchair-accessible restroom in Haeundae that's open 24 hours"
- "Find free WiFi hotspots in Gwangalli area"
- "Where is the closest AED to Nampo-dong?"
- "Which tourist information center near me has English-speaking staff?"

**日本語**
- 「西面（ソミョン）で薬局を探して」
- 「広安里（クァンアルリ）の近くで無料Wi-Fiが使える場所は？」
- 「海雲台（ヘウンデ）駅周辺の公衆トイレを教えて」

**中文**
- "在西面附近找药店"
- "广安里附近哪里有免费WiFi？"
- "南浦洞附近最近的AED在哪里？"

## Feedback

We actively review and incorporate feedback to improve data quality and coverage.

**For AI agents:** Use the `submit_feedback` tool during a conversation to report issues or suggest improvements.

**For developers:** [Open a feedback issue](https://github.com/do-droid/busan-essentials/issues/new?template=feedback.yml) on GitHub.

**Categories:** `new_data` | `data_quality` | `coverage` | `format` | `frequency` | `other`

## Known Data Limitations

- **`subway`**: Not loaded. The Humetro timetable API (data.go.kr 15000522) requires a separate usage application that is still pending, so `get_subway_timetable` returns nothing for every station. The parser and config are in place; the data flows the moment the key is approved. Donghae Line and Busan–Gimhae Light Rail follow later.
- **`pharmacy`**: No 24-hour or foreign-language flags. The nationwide E-Gen source does not carry them, so `is_24h` reads `false` on all 1,667 records — that is a source gap, not a statement that no 24-hour pharmacy exists in Busan.
- **`toilet` coordinates** fall back to the district centroid; the upstream standard dataset dropped its WGS84 columns. `wifi`, `pharmacy`, `aed`, and `tourist_info` have precise coordinates.
- **English names and addresses** are generated by Revised Romanization plus a facility-type glossary (미래약국 → "Mirae Pharmacy"). Loanword names romanize phonetically rather than recovering the original spelling (오션약국 → "Osyeon Pharmacy", not "Ocean"). Korean fields are always the authoritative ones.
- **`tourist_info`** is 25 records, not 26: the source dataset contains a test entry ("테스트 관광안내소") which is excluded.

## Data Sources

All data sourced from official Korean government open data, used under **KOGL Type 1 (출처표시 / Attribution)**:

- [Korea Open Data Portal (data.go.kr)](https://www.data.go.kr)
- [Busan Open Data Portal (data.busan.go.kr)](https://data.busan.go.kr)

## License

MIT (code) / KOGL Type 1 — Attribution (data)