korbus-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BearMett
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,251 @@
+# korbus-mcp
+
+서울/경기 실시간 버스 도착 정보를 제공하는 [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 서버입니다.
+
+AI 어시스턴트가 버스 정류장 검색, 노선 조회, 실시간 도착 정보 확인, 알림 설정 등을 수행할 수 있습니다.
+
+## Features
+
+| Tool | Description |
+|------|-------------|
+| `search_stations` | 정류장 이름으로 검색 (서울 + 경기) |
+| `search_routes` | 버스 노선 번호/이름으로 검색 (서울 + 경기) |
+| `get_arrivals` | 정류장의 실시간 버스 도착 정보 조회 |
+| `create_alarm` | 버스 도착 알림 생성 |
+| `list_alarms` | 등록된 알림 목록 조회 |
+| `update_alarm` | 기존 알림 수정 |
+| `delete_alarm` | 알림 삭제 |
+| `poll_now` | 활성 알림에 대해 즉시 도착 정보 확인 및 알림 발송 |
+
+## API 키 발급
+
+이 서버를 사용하려면 [공공데이터포털](https://www.data.go.kr/index.do)에서 API 키를 발급받고, 필요한 서비스를 신청해야 합니다.
+
+### 1단계: 회원가입
+
+[data.go.kr](https://www.data.go.kr/index.do)에 접속하여 회원가입 후 로그인합니다.
+
+### 2단계: API 활용 신청
+
+아래 **6개 서비스**에 각각 활용 신청을 해야 합니다. 링크를 클릭한 뒤 **"활용신청"** 버튼을 누르세요.
+
+**서울 버스** (3개):
+
+| 서비스 | 용도 |
+|--------|------|
+| [서울특별시_정류소정보조회 서비스](https://www.data.go.kr/data/15000303/openapi.do) | 정류장 검색 |
+| [서울특별시_노선정보조회 서비스](https://www.data.go.kr/data/15000193/openapi.do) | 버스 노선 검색 |
+| [서울특별시_버스도착정보조회 서비스](https://www.data.go.kr/data/15000314/openapi.do) | 실시간 도착 정보 |
+
+**경기 버스** (3개):
+
+| 서비스 | 용도 |
+|--------|------|
+| [경기도_정류소 조회](https://www.data.go.kr/data/15080666/openapi.do) | 정류장 검색 |
+| [경기도_버스노선 조회](https://www.data.go.kr/data/15080662/openapi.do) | 버스 노선 검색 |
+| [경기도_버스도착정보 조회](https://www.data.go.kr/data/15080346/openapi.do) | 실시간 도착 정보 |
+
+> **참고**: 서울 또는 경기 중 한 지역만 사용한다면 해당 지역의 3개만 신청해도 됩니다.
+
+### 3단계: 인증키 확인
+
+1. 활용 신청 승인 후 (즉시 ~ 최대 1~2시간), [마이페이지 > 오픈API > 인증키 발급현황](https://www.data.go.kr/iim/api/selectAPIAc498View.do)에서 **일반 인증키 (Decoding)** 을 복사합니다.
+2. 동일 계정으로 신청한 서비스들은 같은 인증키를 공유합니다.
+
+### 4단계: 환경변수 설정
+
+발급받은 키를 `KORBUS_DATA_API_KEY`에 설정합니다:
+
+```bash
+KORBUS_DATA_API_KEY=your_decoding_key npx korbus-mcp
+```
+
+## Quick Start
+
+두 가지 방식으로 사용할 수 있습니다:
+
+### A. OpenClaw 플러그인 (권장)
+
+[OpenClaw](https://openclaw.ai) 게이트웨이에 플러그인으로 설치합니다. 텔레그램, 디스코드, 슬랙 등 OpenClaw이 지원하는 모든 채널로 알림을 받을 수 있습니다.
+
+```bash
+openclaw plugins install korbus-mcp
+```
+
+플러그인 설정에 API 키를 추가합니다. `~/.openclaw/openclaw.json`을 직접 편집하거나:
+
+```json5
+{
+  "plugins": {
+    "entries": {
+      "korbus-mcp": {
+        "enabled": true,
+        "config": {
+          "apiKey": "your_decoding_key"
+        }
+      }
+    }
+  }
+}
+```
+
+또는 환경변수로 설정합니다:
+
+```bash
+export KORBUS_DATA_API_KEY=your_decoding_key
+```
+
+설정 후 게이트웨이를 재시작합니다:
+
+```bash
+openclaw gateway restart
+```
+
+설치 확인:
+
+```bash
+openclaw plugins list        # korbus-mcp 표시 확인
+openclaw doctor              # 전체 상태 점검
+```
+
+### B. Standalone MCP 서버
+
+MCP 클라이언트(Claude Desktop, Cursor 등)에서 직접 실행합니다:
+
+```bash
+KORBUS_DATA_API_KEY=your_key npx korbus-mcp
+```
+
+## 환경변수
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `KORBUS_DATA_API_KEY` | Yes | 공공데이터포털 버스 API 인증키 (서울/경기 공용) |
+| `TELEGRAM_BOT_TOKEN` | Standalone만 | 텔레그램 알림 봇 토큰 (OpenClaw 모드에서는 불필요) |
+| `DATABASE_URL` | No | SQLite DB 경로 (기본: `~/.korbus-mcp/korbus.db`) |
+
+> **참고**: API 키는 인코딩된 값과 디코딩된 값 모두 사용 가능합니다.
+>
+> OpenClaw 플러그인 모드에서는 `plugins.entries.korbus-mcp.config.apiKey`로도 설정할 수 있습니다.
+
+## MCP 클라이언트 설정 (Standalone)
+
+Standalone MCP 서버로 사용할 때의 클라이언트별 설정입니다.
+
+### Claude Desktop
+
+`claude_desktop_config.json`에 추가:
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "korbus": {
+      "command": "npx",
+      "args": ["-y", "korbus-mcp"],
+      "env": {
+        "KORBUS_DATA_API_KEY": "your_api_key",
+        "TELEGRAM_BOT_TOKEN": "your_bot_token"
+      }
+    }
+  }
+}
+```
+
+### Claude Code (CLI)
+
+```bash
+claude mcp add \
+  -e KORBUS_DATA_API_KEY=your_api_key \
+  korbus -- npx -y korbus-mcp
+```
+
+### Cursor
+
+`.cursor/mcp.json`에 추가:
+
+```json
+{
+  "mcpServers": {
+    "korbus": {
+      "command": "npx",
+      "args": ["-y", "korbus-mcp"],
+      "env": {
+        "KORBUS_DATA_API_KEY": "your_api_key"
+      }
+    }
+  }
+}
+```
+
+### 기타 MCP 클라이언트
+
+stdio 전송 방식을 지원하는 모든 MCP 클라이언트에서 사용할 수 있습니다:
+
+```json
+{
+  "command": "npx",
+  "args": ["-y", "korbus-mcp"],
+  "env": {
+    "KORBUS_DATA_API_KEY": "your_api_key"
+  }
+}
+```
+
+## 알림 채널
+
+### OpenClaw 플러그인 모드
+
+OpenClaw이 지원하는 모든 채널(Telegram, Discord, Slack, Signal 등)로 알림을 전송합니다. 알람 생성 시 `channel`과 `to` 파라미터로 수신 대상을 지정합니다. 대화 중 알람을 만들면 현재 대화 채널로 자동 설정됩니다.
+
+### Standalone MCP 모드
+
+| 채널 | 설명 | 가이드 |
+|------|------|--------|
+| Telegram | 텔레그램 메시지로 알림 수신 | [설정 가이드](docs/telegram-setup.md) |
+| Webhook | HTTP POST로 외부 서비스에 알림 전송 | [설정 가이드](docs/webhook-setup.md) |
+| Console | 서버 로그에 출력 (디버깅용) | — |
+
+## 사용 예시
+
+AI 어시스턴트에게 자연어로 요청하세요:
+
+- "강남역 정류장 검색해줘"
+- "341번 버스 노선 찾아줘"
+- "강남역 정류장에 341번 버스 언제 오는지 알려줘"
+- "매일 아침 8시에 강남역 341번 버스 도착 알림 만들어줘"
+- "등록된 알림 목록 보여줘"
+
+## 데이터 영속성
+
+검색된 정류장, 노선, 알림 데이터는 `~/.korbus-mcp/korbus.db` SQLite 파일에 자동 저장됩니다. `npx`로 재실행해도 데이터가 유지됩니다.
+
+`DATABASE_URL` 환경변수로 다른 경로를 지정할 수 있습니다:
+
+```bash
+DATABASE_URL="file:/path/to/custom.db" npx korbus-mcp
+```
+
+## Development
+
+```bash
+git clone https://github.com/BearMett/korbus-mcp.git
+cd korbus-mcp
+npm install
+cp .env.example .env  # API 키 설정
+npm run dev
+```
+
+```bash
+# 빌드
+npm run build
+
+# 마이그레이션
+npm run db:migrate
+```
+
+## License
+
+[MIT](LICENSE)

package/dist/bus/gateway.d.ts

@@ -0,0 +1,11 @@
+import type { Arrival, Route, Station, StationRef } from '../types.js';
+export interface BusGateway {
+    searchStations(query: string): Promise<Station[]>;
+    searchRoutes(query: string): Promise<Route[]>;
+    getArrivals(stationRef: StationRef, routeId?: string): Promise<Arrival[]>;
+}
+export declare function createBusGateway(config: {
+    seoulApiKey: string;
+    gyeonggiApiKey: string;
+}): BusGateway;
+//# sourceMappingURL=gateway.d.ts.map

package/dist/bus/gateway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway.d.ts","sourceRoot":"","sources":["../../src/bus/gateway.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAU,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAM/E,MAAM,WAAW,UAAU;IACzB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAClD,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;IAC9C,WAAW,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;CAC3E;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,GAAG,UAAU,CAgCpG"}

package/dist/bus/gateway.js

@@ -0,0 +1,36 @@
+import { createSeoulAdapter } from './seoul.js';
+import { createGyeonggiAdapter } from './gyeonggi.js';
+export function createBusGateway(config) {
+    const adapters = [
+        createSeoulAdapter(config.seoulApiKey),
+        createGyeonggiAdapter(config.gyeonggiApiKey),
+    ];
+    function getAdapter(region) {
+        const adapter = adapters.find((a) => a.region === region);
+        if (!adapter)
+            throw new Error(`No adapter for region: ${region}`);
+        return adapter;
+    }
+    return {
+        async searchStations(query) {
+            const results = await Promise.allSettled(adapters.map((a) => a.searchStations(query)));
+            return results
+                .filter((r) => r.status === 'fulfilled')
+                .flatMap((r) => r.value);
+        },
+        async searchRoutes(query) {
+            const results = await Promise.allSettled(adapters.map((a) => a.searchRoutes(query)));
+            return results
+                .filter((r) => r.status === 'fulfilled')
+                .flatMap((r) => r.value);
+        },
+        async getArrivals(stationRef, routeId) {
+            const adapter = getAdapter(stationRef.region);
+            const arrivals = await adapter.getArrivalsByStation(stationRef);
+            if (routeId)
+                return arrivals.filter((a) => a.routeId === routeId);
+            return arrivals;
+        },
+    };
+}
+//# sourceMappingURL=gateway.js.map

package/dist/bus/gateway.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway.js","sourceRoot":"","sources":["../../src/bus/gateway.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAqB,MAAM,YAAY,CAAC;AACnE,OAAO,EAAE,qBAAqB,EAAwB,MAAM,eAAe,CAAC;AAU5E,MAAM,UAAU,gBAAgB,CAAC,MAAuD;IACtF,MAAM,QAAQ,GAAc;QAC1B,kBAAkB,CAAC,MAAM,CAAC,WAAW,CAAC;QACtC,qBAAqB,CAAC,MAAM,CAAC,cAAc,CAAC;KAC7C,CAAC;IAEF,SAAS,UAAU,CAAC,MAAc;QAChC,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC;QAC1D,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,KAAK,CAAC,0BAA0B,MAAM,EAAE,CAAC,CAAC;QAClE,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,OAAO;QACL,KAAK,CAAC,cAAc,CAAC,KAAK;YACxB,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACvF,OAAO,OAAO;iBACX,MAAM,CAAC,CAAC,CAAC,EAA0C,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,WAAW,CAAC;iBAC/E,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QAC7B,CAAC;QACD,KAAK,CAAC,YAAY,CAAC,KAAK;YACtB,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACrF,OAAO,OAAO;iBACX,MAAM,CAAC,CAAC,CAAC,EAAwC,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,WAAW,CAAC;iBAC7E,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QAC7B,CAAC;QACD,KAAK,CAAC,WAAW,CAAC,UAAU,EAAE,OAAQ;YACpC,MAAM,OAAO,GAAG,UAAU,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;YAC9C,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,oBAAoB,CAAC,UAAU,CAAC,CAAC;YAChE,IAAI,OAAO;gBAAE,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,OAAO,CAAC,CAAC;YAClE,OAAO,QAAQ,CAAC;QAClB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/bus/gyeonggi.d.ts

@@ -0,0 +1,9 @@
+import type { Arrival, Route, Station, StationRef } from '../types.js';
+export declare function createGyeonggiAdapter(apiKey: string): {
+    region: "GYEONGGI";
+    searchStations(name: string): Promise<Station[]>;
+    searchRoutes(name: string): Promise<Route[]>;
+    getArrivalsByStation(stationRef: StationRef): Promise<Arrival[]>;
+};
+export type GyeonggiAdapter = ReturnType<typeof createGyeonggiAdapter>;
+//# sourceMappingURL=gyeonggi.d.ts.map

package/dist/bus/gyeonggi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gyeonggi.d.ts","sourceRoot":"","sources":["../../src/bus/gyeonggi.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAKvE,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM;;yBAuBrB,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;uBAa7B,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;qCAWX,UAAU,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;EAiBzE;AAED,MAAM,MAAM,eAAe,GAAG,UAAU,CAAC,OAAO,qBAAqB,CAAC,CAAC"}

package/dist/bus/gyeonggi.js

@@ -0,0 +1,69 @@
+import axios from 'axios';
+import { apiKeyError, apiKeyExpiredError, rateLimitError } from '../errors.js';
+const BASE_URL = 'https://apis.data.go.kr/6410000';
+export function createGyeonggiAdapter(apiKey) {
+    const client = axios.create({ timeout: 10000 });
+    const key = decodeURIComponent(apiKey);
+    function extractBody(data, bodyKey) {
+        const header = data?.response?.msgHeader;
+        if (header) {
+            const code = String(header.resultCode ?? '');
+            const msg = String(header.resultMessage ?? '');
+            if (code === '20' || code === '30')
+                throw apiKeyError('경기', msg);
+            if (code === '21' || code === '31')
+                throw apiKeyExpiredError('경기');
+            if (code === '22')
+                throw rateLimitError('경기');
+        }
+        const body = data?.response?.msgBody;
+        if (!body)
+            return [];
+        const items = body[bodyKey];
+        if (!items)
+            return [];
+        return Array.isArray(items) ? items : [items];
+    }
+    return {
+        region: 'GYEONGGI',
+        async searchStations(name) {
+            const res = await client.get(`${BASE_URL}/busstationservice/v2/getBusStationListv2`, {
+                params: { keyword: name, serviceKey: key, format: 'json' },
+            });
+            return extractBody(res.data, 'busStationList').map((item) => ({
+                id: String(item.stationId),
+                name: String(item.stationName),
+                region: 'GYEONGGI',
+                posX: item.x != null ? Number(item.x) : undefined,
+                posY: item.y != null ? Number(item.y) : undefined,
+            }));
+        },
+        async searchRoutes(name) {
+            const res = await client.get(`${BASE_URL}/busrouteservice/v2/getBusRouteListv2`, {
+                params: { keyword: name, serviceKey: key, format: 'json' },
+            });
+            return extractBody(res.data, 'busRouteList').map((item) => ({
+                id: String(item.routeId),
+                name: String(item.routeName),
+                region: 'GYEONGGI',
+            }));
+        },
+        async getArrivalsByStation(stationRef) {
+            const res = await client.get(`${BASE_URL}/busarrivalservice/v2/getBusArrivalListv2`, {
+                params: { stationId: stationRef.id, serviceKey: key, format: 'json' },
+            });
+            return extractBody(res.data, 'busArrivalList').map((item) => {
+                const predictMinutes = Number(item.predictTime1);
+                return {
+                    routeId: String(item.routeId),
+                    routeName: String(item.routeName),
+                    stationId: String(item.stationId),
+                    vehicleId: item.plateNo1 ? String(item.plateNo1) : undefined,
+                    arrivalSec: predictMinutes * 60,
+                    arrivalMsg: `${predictMinutes}분 후 도착`,
+                };
+            });
+        },
+    };
+}
+//# sourceMappingURL=gyeonggi.js.map

package/dist/bus/gyeonggi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gyeonggi.js","sourceRoot":"","sources":["../../src/bus/gyeonggi.ts"],"names":[],"mappings":"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"}

package/dist/bus/seoul.d.ts

@@ -0,0 +1,9 @@
+import type { Arrival, Route, Station, StationRef } from '../types.js';
+export declare function createSeoulAdapter(apiKey: string): {
+    region: "SEOUL";
+    searchStations(name: string): Promise<Station[]>;
+    searchRoutes(name: string): Promise<Route[]>;
+    getArrivalsByStation(stationRef: StationRef): Promise<Arrival[]>;
+};
+export type SeoulAdapter = ReturnType<typeof createSeoulAdapter>;
+//# sourceMappingURL=seoul.d.ts.map

package/dist/bus/seoul.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seoul.d.ts","sourceRoot":"","sources":["../../src/bus/seoul.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAKvE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM;;yBAuBlB,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;uBAc7B,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;qCAWX,UAAU,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;EAmBzE;AAED,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC"}

package/dist/bus/seoul.js

@@ -0,0 +1,72 @@
+import axios from 'axios';
+import { XMLParser } from 'fast-xml-parser';
+import { apiKeyError, apiKeyExpiredError, rateLimitError } from '../errors.js';
+const BASE_URL = 'http://ws.bus.go.kr/api/rest';
+export function createSeoulAdapter(apiKey) {
+    const client = axios.create({ timeout: 10000 });
+    const parser = new XMLParser({ parseTagValue: false });
+    const key = decodeURIComponent(apiKey);
+    function parseItemList(xml) {
+        const parsed = parser.parse(xml);
+        const header = parsed?.ServiceResult?.msgHeader;
+        if (header) {
+            const code = String(header.headerCd);
+            const msg = String(header.headerMsg ?? '');
+            if (code === '4' || code === '3')
+                throw apiKeyError('서울', msg);
+            if (code === '5')
+                throw apiKeyExpiredError('서울');
+            if (code === '8')
+                throw rateLimitError('서울');
+        }
+        const itemList = parsed?.ServiceResult?.msgBody?.itemList;
+        if (!itemList)
+            return [];
+        return Array.isArray(itemList) ? itemList : [itemList];
+    }
+    return {
+        region: 'SEOUL',
+        async searchStations(name) {
+            const res = await client.get(`${BASE_URL}/stationinfo/getStationByName`, {
+                params: { stSrch: name, serviceKey: key },
+            });
+            return parseItemList(res.data).map((item) => ({
+                id: String(item.stId),
+                arsId: item.arsId ? String(item.arsId) : undefined,
+                name: String(item.stNm),
+                region: 'SEOUL',
+                posX: item.tmX ? Number(item.tmX) : undefined,
+                posY: item.tmY ? Number(item.tmY) : undefined,
+            }));
+        },
+        async searchRoutes(name) {
+            const res = await client.get(`${BASE_URL}/busRouteInfo/getBusRouteList`, {
+                params: { strSrch: name, serviceKey: key },
+            });
+            return parseItemList(res.data).map((item) => ({
+                id: String(item.busRouteId),
+                name: String(item.busRouteNm),
+                region: 'SEOUL',
+            }));
+        },
+        async getArrivalsByStation(stationRef) {
+            const res = await client.get(`${BASE_URL}/arrive/getLowArrInfoByStId`, {
+                params: { stId: stationRef.id, serviceKey: key },
+            });
+            return parseItemList(res.data)
+                .filter((item) => {
+                const msg = String(item.arrmsg1 || '');
+                return msg !== '운행종료' && msg !== '출발대기';
+            })
+                .map((item) => ({
+                routeId: String(item.busRouteId),
+                routeName: String(item.rtNm || item.busRouteAbrv),
+                stationId: String(item.stId),
+                vehicleId: item.vehId1 ? String(item.vehId1) : undefined,
+                arrivalSec: Number(item.exps1 || 0),
+                arrivalMsg: String(item.arrmsg1),
+            }));
+        },
+    };
+}
+//# sourceMappingURL=seoul.js.map

package/dist/bus/seoul.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seoul.js","sourceRoot":"","sources":["../../src/bus/seoul.ts"],"names":[],"mappings":"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"}

package/dist/db.d.ts

@@ -0,0 +1,55 @@
+import { PrismaClient } from '@prisma/client';
+import type { Station, Route, StationRef, AlarmWithRelations, CreateAlarmInput, CreateOnceAlarmInput, UpdateAlarmInput } from './types.js';
+/**
+ * Initialise PrismaClient singleton.
+ * Automatically runs `prisma migrate deploy` so the DB schema is up-to-date.
+ */
+export declare function initDb(): Promise<PrismaClient>;
+/** Return the initialised PrismaClient. Throws if `initDb()` has not been called. */
+export declare function getDb(): PrismaClient;
+/** Disconnect PrismaClient and reset the singleton. */
+export declare function closeDb(): Promise<void>;
+/** Upsert an array of stations, returning the mapped results. */
+export declare function upsertStations(stations: Station[]): Promise<Station[]>;
+/** Upsert an array of routes, returning the mapped results. */
+export declare function upsertRoutes(routes: Route[]): Promise<Route[]>;
+/** Find a station by id and return a lightweight StationRef. */
+export declare function findStationById(stationId: string): Promise<StationRef | null>;
+/** Create an alarm with nested schedules and channels. */
+export declare function createAlarm(input: CreateAlarmInput): Promise<AlarmWithRelations>;
+/** List all alarms with their station, route, schedules, and channels. */
+export declare function listAlarms(): Promise<AlarmWithRelations[]>;
+/** Find a single alarm by id, or return null. */
+export declare function findAlarm(alarmId: string): Promise<AlarmWithRelations | null>;
+/**
+ * Update an alarm. If `schedules` or `channels` are provided in the input
+ * the existing child rows are deleted and recreated.
+ */
+export declare function updateAlarm(alarmId: string, input: UpdateAlarmInput): Promise<AlarmWithRelations>;
+/** Delete an alarm by id. Cascading deletes handle children. */
+export declare function deleteAlarm(alarmId: string): Promise<void>;
+/** Create a one-time alarm (no schedules). */
+export declare function createOnceAlarm(input: CreateOnceAlarmInput): Promise<AlarmWithRelations>;
+/** Mark a one-time alarm as fired. */
+export declare function markAlarmFired(alarmId: string): Promise<void>;
+/**
+ * List all *active* alarms whose schedule matches the given `now` timestamp.
+ *
+ * "Active" means:
+ *   - RECURRING: `enabled` is true and at least one schedule row matches now.
+ *   - ONCE: `enabled` is true, `firedAt` is null, and `activeUntil` is null or >= now.
+ */
+export declare function listActiveAlarms(now: Date): Promise<AlarmWithRelations[]>;
+/**
+ * Check whether a notification log exists for the given alarm + vehicle
+ * combination since the provided timestamp.
+ */
+export declare function hasRecentNotification(alarmId: string, vehicleId: string, since: Date): Promise<boolean>;
+/** Create a notification log entry. */
+export declare function createNotificationLog(input: {
+    alarmId: string;
+    vehicleId: string;
+    message: string;
+    channel: string;
+}): Promise<void>;
+//# sourceMappingURL=db.d.ts.map

package/dist/db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../src/db.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,KAAK,EACV,OAAO,EACP,KAAK,EACL,UAAU,EAIV,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAGjB,MAAM,YAAY,CAAC;AAQpB;;;GAGG;AACH,wBAAsB,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC,CA+BpD;AAED,qFAAqF;AACrF,wBAAgB,KAAK,IAAI,YAAY,CAKpC;AAED,uDAAuD;AACvD,wBAAsB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAM7C;AAgID,iEAAiE;AACjE,wBAAsB,cAAc,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CA2B5E;AAED,+DAA+D;AAC/D,wBAAsB,YAAY,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAqBpE;AAED,gEAAgE;AAChE,wBAAsB,eAAe,CACnC,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAS5B;AAMD,0DAA0D;AAC1D,wBAAsB,WAAW,CAC/B,KAAK,EAAE,gBAAgB,GACtB,OAAO,CAAC,kBAAkB,CAAC,CA2B7B;AAED,0EAA0E;AAC1E,wBAAsB,UAAU,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAIhE;AAED,iDAAiD;AACjD,wBAAsB,SAAS,CAC7B,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAQpC;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,gBAAgB,GACtB,OAAO,CAAC,kBAAkB,CAAC,CAiD7B;AAED,gEAAgE;AAChE,wBAAsB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGhE;AAED,8CAA8C;AAC9C,wBAAsB,eAAe,CACnC,KAAK,EAAE,oBAAoB,GAC1B,OAAO,CAAC,kBAAkB,CAAC,CAkC7B;AAED,sCAAsC;AACtC,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMnE;AAMD;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,IAAI,GACR,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAiD/B;AAMD;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,IAAI,GACV,OAAO,CAAC,OAAO,CAAC,CAUlB;AAED,uCAAuC;AACvC,wBAAsB,qBAAqB,CAAC,KAAK,EAAE;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC,IAAI,CAAC,CAGhB"}