mirror of
https://github.com/NomaDamas/k-skill.git
synced 2026-06-24 02:04:11 +00:00
docs(household-waste-info): align skill contract with proxy reality
vkehfdl1's review on PR #82: skill/docs claimed support for cond[DAT_CRTR_YMD::*] / cond[DAT_UPDT_PNT::*] filters and an optional returnType, but the proxy only forwards pageNo, numOfRows, and cond[SGG_NM::LIKE], and forces returnType=json. Typical user queries ("강남구 쓰레기 배출 요일") only need 시군구 검색, so shrink the documented contract to match the proxy instead of widening pass-through. - household-waste-info/SKILL.md: list only proxy-supported params, note returnType is server-forced, fix failure modes. - docs/features/household-waste-info.md: switch base example to the proxy route, drop the bare upstream curl, call out unsupported filters explicitly. - docs/install.md, docs/security-and-secrets.md, k-skill-setup/SKILL.md: describe the skill as calling the proxy /v1/household-waste/info route rather than the raw upstream endpoint.
This commit is contained in:
Jeffrey (Dongkyu) Kim
parent
baea3f2c24
commit
df70ce7a09
5 changed files with 24 additions and 23 deletions
|
|
@ -5,12 +5,12 @@
|
|||
- 시군구 기준 생활쓰레기 배출요일/시간 조회
|
||||
- 음식물쓰레기/재활용품 배출방법 조회
|
||||
- 배출장소, 미수거일, 관리부서 연락처 확인
|
||||
- 공공데이터 원본 endpoint 스펙 기준 조회 + API 키는 프록시 주입
|
||||
- 공공데이터 원본 API를 k-skill-proxy `/v1/household-waste/info` 라우트로 감싸서 조회 + API 키는 프록시 주입
|
||||
|
||||
## 가장 중요한 규칙
|
||||
|
||||
Base URL은 `https://apis.data.go.kr/1741000/household_waste_info` 이다.
|
||||
사용자는 `DATA_GO_KR_API_KEY`를 직접 들고 있지 않고, `serviceKey`는 proxy 서버에서만 주입한다.
|
||||
스킬은 항상 `k-skill-proxy`의 `/v1/household-waste/info` 라우트를 호출한다.
|
||||
사용자는 `DATA_GO_KR_API_KEY`를 직접 들고 있지 않고, `serviceKey`는 proxy 서버에서만 원본 API(`https://apis.data.go.kr/1741000/household_waste_info/info`)로 주입한다.
|
||||
|
||||
## 먼저 필요한 것
|
||||
|
||||
|
|
@ -21,21 +21,21 @@ Base URL은 `https://apis.data.go.kr/1741000/household_waste_info` 이다.
|
|||
## 기본 조회 예시
|
||||
|
||||
```bash
|
||||
curl -fsS --get 'https://apis.data.go.kr/1741000/household_waste_info/info' \
|
||||
--data-urlencode 'serviceKey=${INJECTED_BY_PROXY}' \
|
||||
--data-urlencode 'returnType=json' \
|
||||
curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/household-waste/info' \
|
||||
--data-urlencode 'pageNo=1' \
|
||||
--data-urlencode 'numOfRows=20' \
|
||||
--data-urlencode 'cond[SGG_NM::LIKE]=강남구'
|
||||
```
|
||||
|
||||
현재 proxy가 패스스루하는 파라미터는 `pageNo`, `numOfRows`, `cond[SGG_NM::LIKE]` 뿐이며, `returnType`은 항상 `json`으로 강제된다. 원본 API의 `cond[DAT_CRTR_YMD::*]`, `cond[DAT_UPDT_PNT::*]` 같은 부가 필터는 현재 지원하지 않는다 — 일반 사용자 질의("강남구 쓰레기 배출 요일")는 시군구 검색만으로 충분하기 때문이다.
|
||||
|
||||
## 조회 흐름 권장 순서
|
||||
|
||||
1. 사용자에게 시/군/구를 먼저 확인한다.
|
||||
2. 입력이 모호하면 상위 행정구역을 포함해 재질문한다.
|
||||
3. `/info` endpoint 스펙으로 조회하고 `serviceKey`는 proxy 주입을 사용한다.
|
||||
3. proxy `/v1/household-waste/info` 라우트로 조회한다 (`serviceKey`는 proxy가 주입).
|
||||
4. 배출장소/요일/시간/미수거일/문의처를 3~6개 포인트로 요약한다.
|
||||
5. 결과가 여러 건이면 최신 `DAT_UPDT_PNT` 기준으로 우선 정렬해 보여준다.
|
||||
5. 결과가 여러 건이면 응답 항목을 `DAT_UPDT_PNT` 기준으로 클라이언트에서 정렬해 최신 항목을 우선 보여준다.
|
||||
|
||||
## 자주 보는 필드
|
||||
|
||||
|
|
|
|||
|
|
@ -100,7 +100,7 @@ korean-law list
|
|||
|
||||
`real-estate-search` 는 별도 설치 없이 기본 hosted proxy(`k-skill-proxy.nomadamas.org`)를 통해 바로 사용할 수 있다. 사용자 쪽 `DATA_GO_KR_API_KEY` 가 불필요하다. 원본 참고: `https://github.com/tae0y/real-estate-mcp/tree/main`. 자세한 사용법은 [한국 부동산 실거래가 조회 가이드](features/real-estate-search.md)를 본다.
|
||||
|
||||
`household-waste-info` 는 원본 API(`apis.data.go.kr/1741000/household_waste_info`) endpoint 스펙으로 호출하고, `serviceKey`(`DATA_GO_KR_API_KEY`)만 proxy 서버에서 주입해 사용한다. 사용자 쪽 `DATA_GO_KR_API_KEY` 가 불필요하다. 자세한 사용법은 [생활쓰레기 배출정보 조회 가이드](features/household-waste-info.md)를 본다.
|
||||
`household-waste-info` 는 별도 설치 없이 `k-skill-proxy`의 `/v1/household-waste/info` 라우트를 호출하고, `serviceKey`(`DATA_GO_KR_API_KEY`)는 proxy 서버에서만 원본 API(`apis.data.go.kr/1741000/household_waste_info/info`)로 주입한다. 사용자 쪽 `DATA_GO_KR_API_KEY` 가 불필요하다. 자세한 사용법은 [생활쓰레기 배출정보 조회 가이드](features/household-waste-info.md)를 본다.
|
||||
|
||||
### `olive-young-search` upstream CLI quickstart
|
||||
|
||||
|
|
|
|||
|
|
@ -29,7 +29,7 @@ AIR_KOREA_OPEN_API_KEY=replace-me
|
|||
KSKILL_PROXY_BASE_URL=https://your-proxy.example.com
|
||||
```
|
||||
|
||||
서울 지하철 도착정보는 hosted public route rollout 이 끝나기 전까지 self-host 또는 배포 확인이 끝난 proxy URL 만 넣는다. 미세먼지, 한강 수위, 주유소 가격은 기본 hosted proxy(`k-skill-proxy.nomadamas.org`)를 쓰므로 사용자 쪽 키가 불필요하다. 생활쓰레기 배출정보는 원본 API endpoint를 쓰되 `serviceKey`만 proxy 서버에서 주입하므로 사용자 쪽 키가 불필요하다.
|
||||
서울 지하철 도착정보는 hosted public route rollout 이 끝나기 전까지 self-host 또는 배포 확인이 끝난 proxy URL 만 넣는다. 미세먼지, 한강 수위, 주유소 가격은 기본 hosted proxy(`k-skill-proxy.nomadamas.org`)를 쓰므로 사용자 쪽 키가 불필요하다. 생활쓰레기 배출정보는 `k-skill-proxy`의 `/v1/household-waste/info` 라우트를 거쳐 `serviceKey`만 proxy 서버에서 주입하므로 사용자 쪽 키가 불필요하다.
|
||||
|
||||
## Missing secret handling policy
|
||||
|
||||
|
|
@ -64,6 +64,6 @@ KSKILL_PROXY_BASE_URL=https://your-proxy.example.com
|
|||
- `AIR_KOREA_OPEN_API_KEY`
|
||||
- `KSKILL_PROXY_BASE_URL`
|
||||
|
||||
`LAW_OC` 는 `korean-law-mcp` 가 법제처 Open API 를 호출할 때 쓰는 표준 변수명이다. 이 값은 로컬 CLI/로컬 MCP server 경로에서만 사용자 쪽에 필요하고, upstream remote MCP endpoint 예시는 사용자 `LAW_OC` 없이 `url`만 등록한다. `DATA_GO_KR_API_KEY` 는 프록시 운영자 문맥에서만 서버에 넣는다. 부동산 실거래가 조회는 기본 hosted proxy(`k-skill-proxy.nomadamas.org`)를 경유하고, 생활쓰레기 배출정보 조회는 원본 API endpoint를 쓰되 `serviceKey`를 proxy 서버에서 주입하므로 사용자 쪽 키가 불필요하다. 근처 가장 싼 주유소 찾기는 기본 hosted proxy를 경유하므로 사용자 쪽 `OPINET_API_KEY` 가 불필요하다. `OPINET_API_KEY` 는 프록시 운영자 문맥에서만 서버에 넣는다. public 공유용 Cloudflare Tunnel/Auth0/operator secret은 사용자 기본 secrets 파일에 넣지 않는다. 프록시 운영자 문맥에서는 upstream 환경변수 `SEOUL_OPEN_API_KEY`, `AIR_KOREA_OPEN_API_KEY`, `HRFCO_OPEN_API_KEY`, `OPINET_API_KEY`, `DATA_GO_KR_API_KEY` 를 사용할 수 있다. 다만 일반 사용자/client 쪽 기본 secrets 파일에는 넣지 않는다. `KSKILL_PROXY_BASE_URL` 은 서울 지하철 route가 실제 배포된 proxy URL 로만 넣는다. 미세먼지, 한강 수위, 주유소 가격은 이 값이 없으면 기본 hosted path(`k-skill-proxy.nomadamas.org`)를 사용한다.
|
||||
`LAW_OC` 는 `korean-law-mcp` 가 법제처 Open API 를 호출할 때 쓰는 표준 변수명이다. 이 값은 로컬 CLI/로컬 MCP server 경로에서만 사용자 쪽에 필요하고, upstream remote MCP endpoint 예시는 사용자 `LAW_OC` 없이 `url`만 등록한다. `DATA_GO_KR_API_KEY` 는 프록시 운영자 문맥에서만 서버에 넣는다. 부동산 실거래가 조회는 기본 hosted proxy(`k-skill-proxy.nomadamas.org`)를 경유하고, 생활쓰레기 배출정보 조회는 `k-skill-proxy`의 `/v1/household-waste/info` 라우트를 거쳐 `serviceKey`를 proxy 서버에서 주입하므로 사용자 쪽 키가 불필요하다. 근처 가장 싼 주유소 찾기는 기본 hosted proxy를 경유하므로 사용자 쪽 `OPINET_API_KEY` 가 불필요하다. `OPINET_API_KEY` 는 프록시 운영자 문맥에서만 서버에 넣는다. public 공유용 Cloudflare Tunnel/Auth0/operator secret은 사용자 기본 secrets 파일에 넣지 않는다. 프록시 운영자 문맥에서는 upstream 환경변수 `SEOUL_OPEN_API_KEY`, `AIR_KOREA_OPEN_API_KEY`, `HRFCO_OPEN_API_KEY`, `OPINET_API_KEY`, `DATA_GO_KR_API_KEY` 를 사용할 수 있다. 다만 일반 사용자/client 쪽 기본 secrets 파일에는 넣지 않는다. `KSKILL_PROXY_BASE_URL` 은 서울 지하철 route가 실제 배포된 proxy URL 로만 넣는다. 미세먼지, 한강 수위, 주유소 가격은 이 값이 없으면 기본 hosted path(`k-skill-proxy.nomadamas.org`)를 사용한다.
|
||||
|
||||
이 레포의 credential-bearing skill은 전부 이 정책을 전제로 작성한다. 자세한 공통 설치 절차는 [공통 설정 가이드](setup.md)를 본다.
|
||||
|
|
|
|||
|
|
@ -58,15 +58,15 @@ metadata:
|
|||
|
||||
추가 client API 레이어는 불필요하다. Base URL은 원본 API를 기준으로 유지한다.
|
||||
|
||||
핵심 쿼리 파라미터:
|
||||
현재 proxy가 지원하는 쿼리 파라미터(이외 값은 무시된다):
|
||||
|
||||
- `serviceKey`: proxy가 서버 측에서 주입하는 인증키 (`DATA_GO_KR_API_KEY`)
|
||||
- `pageNo`: 페이지 번호
|
||||
- `numOfRows`: 페이지 크기(최대 100)
|
||||
- `returnType`: `json` 권장
|
||||
- `cond[SGG_NM::LIKE]`: 시군구명 포함 검색
|
||||
- `cond[DAT_CRTR_YMD::GTE]`, `cond[DAT_CRTR_YMD::LT]`: 데이터 기준일 필터
|
||||
- `cond[DAT_UPDT_PNT::GTE]`, `cond[DAT_UPDT_PNT::LT]`: 갱신시점 필터
|
||||
- `serviceKey`: proxy가 서버 측에서 주입하는 인증키 (`DATA_GO_KR_API_KEY`) — 클라이언트에서 전달 금지
|
||||
- `pageNo`: 페이지 번호 (기본값 `1`)
|
||||
- `numOfRows`: 페이지 크기 (기본값 `20`, 최대 100)
|
||||
- `returnType`: proxy가 항상 `json`으로 강제 — 클라이언트가 값을 보내도 무시된다
|
||||
- `cond[SGG_NM::LIKE]`: 시군구명 포함 검색 (필수)
|
||||
|
||||
> 원본 API의 `cond[DAT_CRTR_YMD::*]`, `cond[DAT_UPDT_PNT::*]` 같은 부가 필터는 현재 proxy 라우트에서 패스스루되지 않는다. 사용자가 보내는 일반적인 질의("강남구 쓰레기 배출 요일")는 시군구 기준 검색만으로 충분하므로, 필요하다면 응답에서 `DAT_UPDT_PNT` 기준으로 클라이언트에서 정렬한다.
|
||||
|
||||
## Workflow
|
||||
|
||||
|
|
@ -87,12 +87,13 @@ proxy가 `serviceKey`를 서버 측에서 주입한 뒤 원본 API로 전달한
|
|||
|
||||
```bash
|
||||
curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/household-waste/info' \
|
||||
--data-urlencode "returnType=json" \
|
||||
--data-urlencode "pageNo=1" \
|
||||
--data-urlencode "numOfRows=20" \
|
||||
--data-urlencode "cond[SGG_NM::LIKE]=강남구"
|
||||
```
|
||||
|
||||
`returnType`은 proxy가 항상 `json`으로 강제하므로 클라이언트에서 별도로 보낼 필요가 없다.
|
||||
|
||||
`KSKILL_PROXY_BASE_URL`이 있으면 그 값을 사용하고, 없으면 기본 hosted proxy(`k-skill-proxy.nomadamas.org`)를 사용한다.
|
||||
|
||||
### 4) Summarize for user
|
||||
|
|
@ -108,7 +109,7 @@ curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/household-waste/info' \
|
|||
## Done when
|
||||
|
||||
- 사용자 지역(시군구)을 확인했다.
|
||||
- 원본 endpoint 호출 스펙으로 조회에 성공했다.
|
||||
- proxy `/v1/household-waste/info` 호출에 성공했다.
|
||||
- 배출 요일/시간/장소를 3~6개 핵심 포인트로 요약해 안내했다.
|
||||
|
||||
## Failure modes
|
||||
|
|
@ -116,7 +117,7 @@ curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/household-waste/info' \
|
|||
- 프록시 서버에 `DATA_GO_KR_API_KEY`가 없거나 만료된 경우 (`serviceKey` 주입 실패)
|
||||
- 검색 지역명이 API 데이터와 불일치하여 결과가 비는 경우
|
||||
- 공공데이터 API 일시 장애/트래픽 제한
|
||||
- 필수 파라미터 누락(`pageNo`, `numOfRows`)
|
||||
- 필수 파라미터 누락(`cond[SGG_NM::LIKE]`)
|
||||
|
||||
## Notes
|
||||
|
||||
|
|
|
|||
|
|
@ -82,7 +82,7 @@ chmod 0600 ~/.config/k-skill/secrets.env
|
|||
|
||||
한국 부동산 실거래가 조회는 기본 hosted proxy(`k-skill-proxy.nomadamas.org`)를 경유하므로 사용자 쪽 `DATA_GO_KR_API_KEY` 가 불필요하다.
|
||||
|
||||
생활쓰레기 배출정보 조회는 원본 API endpoint 스펙을 사용하되, `serviceKey`(`DATA_GO_KR_API_KEY`)는 proxy 서버에서 주입/관리하므로 사용자 쪽 `DATA_GO_KR_API_KEY` 가 불필요하다.
|
||||
생활쓰레기 배출정보 조회는 `k-skill-proxy`의 `/v1/household-waste/info` 라우트를 호출하고, `serviceKey`(`DATA_GO_KR_API_KEY`)는 proxy 서버에서 주입/관리하므로 사용자 쪽 `DATA_GO_KR_API_KEY` 가 불필요하다.
|
||||
|
||||
근처 가장 싼 주유소 찾기는 기본 hosted proxy를 경유하므로 사용자 쪽 `OPINET_API_KEY` 가 불필요하다.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue