397d0eea84
Add the first cheap-gas-nearby skill/package pair so nearby gas-price
queries can resolve a user-supplied location, translate it into Opinet's
KATEC search contract, and return the cheapest nearby stations with
address and facility detail. The docs and setup surfaces now advertise
the new skill and its Opinet API key requirement.
Constraint: Nearby fuel prices must come from the official KNOC Opinet API when available
Constraint: No new external dependencies were allowed for coordinate conversion or location resolution
Rejected: Map-only gas price scraping | official Opinet Open API exists and is the preferred source
Rejected: Require lat/lng input only | poorer UX than supporting landmark/station queries through anchor resolution
Confidence: medium
Scope-risk: moderate
Reversibility: clean
Directive: Keep `OPINET_API_KEY` as the only supported official-price credential unless the repo adopts an Opinet proxy later
Tested: npm run ci; node --test packages/cheap-gas-nearby/test/index.test.js; offline fixture smoke via searchCheapGasStationsByLocationQuery('서울역', ...)
Not-tested: Live Opinet API call with a real `OPINET_API_KEY` (no non-placeholder key was configured locally)
Related: #54
4.8 KiB
공통 설정 가이드
k-skill 전체 스킬을 설치한 뒤, 인증 정보가 필요한 기능(SRT 예매, KTX 예매, 한국 법령 검색의 로컬 CLI/MCP 경로용 LAW_OC, 한국 부동산 실거래가 조회의 로컬/self-host 경로용 DATA_GO_KR_API_KEY, 근처 가장 싼 주유소 찾기용 OPINET_API_KEY, self-host 프록시 운영용 서울 지하철/미세먼지 upstream key, 또는 배포 확인이 끝난 proxy URL 공유)이 있으면 이 절차를 진행하면 된다.
Credential resolution order
모든 credential-bearing 스킬은 아래 우선순위를 따른다.
- 이미 환경변수에 있으면 그대로 사용한다.
- 에이전트가 자체 secret vault(1Password CLI, Bitwarden CLI, macOS Keychain 등)를 사용 중이면 거기서 꺼내 환경변수로 주입해도 된다.
~/.config/k-skill/secrets.env(기본 fallback) — plain dotenv 파일, 퍼미션0600.- 아무것도 없으면 유저에게 물어서 2 또는 3에 저장한다.
에이전트가 자체 vault를 사용 중이라면 기본 경로 설정을 건너뛰어도 된다.
기본 경로로 설정하기
에이전트가 별도 vault를 쓰지 않는 경우, 기본 fallback 파일을 만든다.
mkdir -p ~/.config/k-skill
cat > ~/.config/k-skill/secrets.env <<'EOF'
KSKILL_SRT_ID=replace-me
KSKILL_SRT_PASSWORD=replace-me
KSKILL_KTX_ID=replace-me
KSKILL_KTX_PASSWORD=replace-me
LAW_OC=replace-me
DATA_GO_KR_API_KEY=replace-me
OPINET_API_KEY=replace-me
AIR_KOREA_OPEN_API_KEY=replace-me
KSKILL_PROXY_BASE_URL=https://your-proxy.example.com
EOF
chmod 0600 ~/.config/k-skill/secrets.env
실제 값을 채운다.
서울 지하철 도착정보는 hosted public route rollout 이 끝나기 전까지 KSKILL_PROXY_BASE_URL 을 self-host 또는 배포 확인이 끝난 proxy URL 로 채워야 한다. 미세먼지만 쓴다면 이 값을 비워 두고 skill 기본 hosted path를 그대로 써도 된다.
한국 법령 검색의 로컬 CLI/MCP 경로용 LAW_OC 는 korean-law-mcp 로컬 실행에 쓴다. 로컬 CLI/MCP 경로는 LAW_OC 를 채운 뒤 npm install -g korean-law-mcp 와 korean-law list 로 설치 상태를 확인한다.
remote MCP endpoint는 사용자 LAW_OC 없이 url만으로 연결한다. 다만 기존 korean-law-mcp 경로가 서비스 장애로 막히면 법망(https://api.beopmang.org) MCP/REST를 fallback으로 사용할 수 있다.
한국 부동산 실거래가 조회의 로컬/self-host 경로는 upstream real-estate-mcp 가 읽는 DATA_GO_KR_API_KEY 를 채운다. 2026-04-05 기준 upstream 문서에는 고정 public endpoint가 없어 self-host를 기본으로 보고, Cloudflare Tunnel/operator secret은 운영자별 값이라 기본 client secrets 파일에는 넣지 않는다.
근처 가장 싼 주유소 찾기는 한국석유공사 Opinet Open API 인증키인 OPINET_API_KEY 를 채운다. 이 값이 없으면 공식 nearby 가격 조회를 시작할 수 없으므로 비공식 가격 서비스로 자동 우회하지 않는다.
확인
bash scripts/check-setup.sh
시크릿이 없을 때의 기본 응답
인증이 필요한 스킬에서 값이 비어 있으면 credential resolution order에 따라 확보한다.
- 어떤 값이 필요한지 정확한 변수 이름으로 알려주기
- resolution order에 따라 유저에게 확보 방법 안내하기
기능별로 필요한 값
| 기능 | 필요한 값 |
|---|---|
| SRT 예매 | KSKILL_SRT_ID, KSKILL_SRT_PASSWORD |
| KTX 예매 | KSKILL_KTX_ID, KSKILL_KTX_PASSWORD |
| 한국 법령 검색 (로컬 CLI/MCP) | LAW_OC |
| 한국 법령 검색 (remote MCP endpoint) | 사용자 시크릿 불필요 (url만 등록, 장애 시 법망 fallback 가능) |
| 한국 부동산 실거래가 조회 (로컬/stdio/self-host) | DATA_GO_KR_API_KEY |
| 근처 가장 싼 주유소 찾기 | OPINET_API_KEY |
| 한국 부동산 실거래가 조회 (공유 URL) | 사용자 시크릿 불필요, 대신 운영자가 self-host + Cloudflare Tunnel + launchd/systemd 를 준비 |
| 서울 지하철 도착정보 조회 | self-host 또는 배포 확인이 끝난 KSKILL_PROXY_BASE_URL |
| 사용자 위치 미세먼지 조회 | KSKILL_PROXY_BASE_URL 또는 AIR_KOREA_OPEN_API_KEY |
다음에 볼 문서
- SRT 예매 가이드
- KTX 예매 가이드
- 서울 지하철 도착정보 가이드
- 사용자 위치 미세먼지 조회 가이드
- 한국 법령 검색 가이드
- 한국 부동산 실거래가 조회 가이드
- 근처 가장 싼 주유소 찾기 가이드
- 보안/시크릿 정책
설치 기본 흐름은 "전체 스킬 설치 → 개별 기능 사용" 이다.