krx-cli 1.3.1 → 1.5.0

package/README.md

@@ -8,6 +8,12 @@ Claude Code, GPT, Cursor 등의 AI 에이전트가 Bash tool을 통해 한국
 
 - **Agent-Native**: JSON 출력 기본, 시맨틱 exit code, 스키마 인트로스펙션
 - **전체 시장 커버리지**: 지수, 주식, ETF/ETN/ELW, 채권, 파생상품, 일반상품, ESG (31개 엔드포인트)
+- **종목 검색**: 종목명으로 검색 후 코드 조회 (`krx stock search`)
+- **시장 요약**: 한 번의 호출로 지수/상승·하락/Top movers 확인 (`krx market summary`)
+- **워치리스트**: 관심 종목 저장 및 일괄 시세 조회 (`krx watchlist`)
+- **기간 조회**: `--from/--to`로 여러 날짜 데이터 병렬 조회
+- **데이터 파이프라인**: `--sort`, `--limit`, `--code` 로 서버 사이드 필터링
+- **파일 캐싱**: 과거 데이터 자동 캐싱으로 rate limit 절약
 - **안전한 사용**: 입력 검증, rate limit 추적, dry-run 지원
 - **서비스 승인 관리**: API별 승인 상태 자동 확인
 
@@ -70,6 +76,53 @@ krx index list --date 20260310 --market kosdaq
 krx stock list --date 20260310 --market kospi
 krx stock list --date 20260310 --market kosdaq
 krx stock info --market kospi
+krx stock search 삼성전자     # 종목 검색
+```
+
+### 시장 요약
+
+```bash
+krx market summary                    # 최근 거래일 시장 요약
+krx market summary --date 20260310    # 특정 날짜
+```
+
+### 기간 조회
+
+```bash
+krx index list --market kospi --from 20260301 --to 20260310
+krx stock list --market kospi --from 20260301 --to 20260305 --code KR7005930003
+```
+
+### 정렬 및 제한
+
+```bash
+krx stock list --date 20260310 --market kospi --sort FLUC_RT --limit 10
+krx stock list --date 20260310 --market kospi --sort ACC_TRDVAL --asc --limit 5
+```
+
+### 워치리스트
+
+```bash
+krx watchlist add 삼성전자          # 종목 검색 후 워치리스트 추가
+krx watchlist remove 삼성전자       # 정확한 이름으로 제거
+krx watchlist remove KR7005930003   # 종목코드로 제거
+krx watchlist list                   # 워치리스트 조회
+krx watchlist show                   # 워치리스트 종목 시세 조회
+krx watchlist show --date 20260310  # 특정 날짜 시세
+```
+
+### 캐시 관리
+
+```bash
+krx cache status    # 캐시 현황 조회
+krx cache clear     # 캐시 전체 삭제
+```
+
+### 버전 관리
+
+```bash
+krx version    # 현재 버전 확인 및 최신 버전 비교
+krx update     # 최신 버전으로 업데이트
 ```
 
 ### ETF/ETN/ELW 조회
@@ -91,6 +144,10 @@ krx bond list --date 20260310 --market general
 ```bash
 krx derivative list --date 20260310 --type futures
 krx derivative list --date 20260310 --type options
+krx derivative list --date 20260310 --type futures-kospi
+krx derivative list --date 20260310 --type futures-kosdaq
+krx derivative list --date 20260310 --type options-kospi
+krx derivative list --date 20260310 --type options-kosdaq
 ```
 
 ### 일반상품 조회
@@ -116,12 +173,22 @@ krx schema stock.stk_bydd_trd
 
 ## 글로벌 옵션
 
-| 옵션                    | 설명                           | 기본값                         |
-| ----------------------- | ------------------------------ | ------------------------------ |
-| `-o, --output <format>` | 출력 형식: json, table, ndjson | json (파이프) / table (터미널) |
-| `-f, --fields <fields>` | 출력 필드 필터 (쉼표 구분)     | 전체                           |
-| `--dry-run`             | API 호출 없이 요청 내용 출력   | -                              |
-| `-v, --verbose`         | 상세 로그 (stderr)             | -                              |
+| 옵션                    | 설명                                | 기본값                         |
+| ----------------------- | ----------------------------------- | ------------------------------ |
+| `-o, --output <format>` | 출력 형식: json, table, ndjson, csv | json (파이프) / table (터미널) |
+| `-f, --fields <fields>` | 출력 필드 필터 (쉼표 구분)          | 전체                           |
+| `--code <isuCd>`        | 종목코드 필터 (ISU_CD)              | -                              |
+| `--sort <field>`        | 결과 정렬 기준 필드                 | -                              |
+| `--asc`                 | 오름차순 정렬 (기본: 내림차순)      | -                              |
+| `--limit <n>`           | 결과 개수 제한                      | -                              |
+| `--from <date>`         | 기간 조회 시작일 (YYYYMMDD)         | -                              |
+| `--to <date>`           | 기간 조회 종료일 (YYYYMMDD)         | -                              |
+| `--no-cache`            | 캐시 무시하고 새로 조회             | -                              |
+| `--filter <expression>` | 필터 표현식 (예: "FLUC_RT > 5")     | -                              |
+| `--save <path>`         | 결과를 파일로 저장                  | -                              |
+| `--retries <n>`         | 네트워크 에러 시 재시도 (기본: 3)   | -                              |
+| `--dry-run`             | API 호출 없이 요청 내용 출력        | -                              |
+| `-v, --verbose`         | 상세 로그 (stderr)                  | -                              |
 
 ## Exit Codes
 
@@ -271,17 +338,30 @@ API 키는 `krx auth set <key>`로 등록한 것이 자동으로 사용됩니다
 
 ### 제공 Tool
 
-| Tool             | 설명                                       |
-| ---------------- | ------------------------------------------ |
-| `krx_index`      | 지수 일별시세 (KOSPI/KOSDAQ/KRX/채권/파생) |
-| `krx_stock`      | 주식 일별매매정보 + 종목 기본정보          |
-| `krx_etp`        | ETF/ETN/ELW 일별매매정보                   |
-| `krx_bond`       | 채권 일별매매정보 (국채/일반/소액)         |
-| `krx_derivative` | 선물/옵션 일별매매정보                     |
-| `krx_commodity`  | 금/석유/배출권 일별매매정보                |
-| `krx_esg`        | ESG 지수/채권/ETP 정보                     |
-| `krx_schema`     | 엔드포인트 응답 필드 스키마 조회           |
-| `krx_rate_limit` | 일일 API 호출 현황 조회                    |
+| Tool                 | 설명                                         |
+| -------------------- | -------------------------------------------- |
+| `krx_index`          | 지수 일별시세 (KOSPI/KOSDAQ/KRX/채권/파생)   |
+| `krx_stock`          | 주식 일별매매정보 + 종목 기본정보            |
+| `krx_etp`            | ETF/ETN/ELW 일별매매정보                     |
+| `krx_bond`           | 채권 일별매매정보 (국채/일반/소액)           |
+| `krx_derivative`     | 선물/옵션 일별매매정보                       |
+| `krx_commodity`      | 금/석유/배출권 일별매매정보                  |
+| `krx_esg`            | ESG 지수/채권/ETP 정보                       |
+| `krx_search`         | 종목명 검색 (KOSPI + KOSDAQ)                 |
+| `krx_market_summary` | 시장 요약 (지수/상승·하락/Top movers/거래량) |
+| `krx_watchlist`      | 관심종목 관리 (추가/제거/조회/시세)          |
+| `krx_schema`         | 엔드포인트 응답 필드 스키마 조회             |
+| `krx_rate_limit`     | 일일 API 호출 현황 조회                      |
+
+### 제공 Resource
+
+MCP Resource로 읽기 전용 상태 데이터를 노출합니다.
+
+| Resource               | 설명                               |
+| ---------------------- | ---------------------------------- |
+| `krx://watchlist`      | 워치리스트 종목 목록 (JSON)        |
+| `krx://rate-limit`     | 일일 API 호출 현황 (JSON)          |
+| `krx://service-status` | 카테고리별 서비스 승인 상태 (JSON) |
 
 ### 사용 예시
 
@@ -304,6 +384,7 @@ MCP 클라이언트에서 자연어로 요청하면 됩니다:
 pnpm install
 pnpm build
 pnpm test
+pnpm test:e2e
 pnpm typecheck
 pnpm lint
 ```

package/SKILL.md

@@ -7,7 +7,7 @@ install: npm install -g krx-cli
 binary: krx
 metadata:
   author: kyo504
-  version: "1.3.1"
+  version: "1.5.0"
 invariants:
   - Always use YYYYMMDD format for --date (e.g., 20260310)
   - Data is T-1 (previous trading day), available from 2010 onwards
@@ -118,6 +118,47 @@ krx esg list --date 20260310 --type etp          # ESG ETP
 krx esg list --date 20260310 --type sri-bond     # SRI bonds
 ```
 
+### Stock Search (종목 검색)
+
+```bash
+krx stock search 삼성전자     # Search by name (KOSPI + KOSDAQ)
+krx stock search SK           # Partial match
+```
+
+### Market Summary (시장 요약)
+
+```bash
+krx market summary                    # Today's market overview
+krx market summary --date 20260310    # Specific date
+```
+
+Returns: KOSPI/KOSDAQ indices, top 5 gainers/losers, advancing/declining/unchanged counts, total volume/value.
+
+### Watchlist (관심종목)
+
+```bash
+krx watchlist add 삼성전자          # Search and add to watchlist
+krx watchlist remove 삼성전자       # Remove by exact name
+krx watchlist remove KR7005930003   # Remove by ISU_CD
+krx watchlist list                   # List all watchlist entries
+krx watchlist show                   # Show prices for watchlist stocks
+krx watchlist show --date 20260310  # Specific date
+```
+
+### Cache Management
+
+```bash
+krx cache status    # Show cache size, files, dates
+krx cache clear     # Clear all cached data
+```
+
+### Version & Update
+
+```bash
+krx version    # Show current version and check for updates
+krx update     # Update to the latest version (npm install -g krx-cli)
+```
+
 ### Schema (introspection)
 
 ```bash
@@ -128,9 +169,19 @@ krx schema index.kospi_dd_trd # Specific endpoint schema
 ## Global Flags
 
 ```
---output, -o <format>    json (default) | table | ndjson
+--output, -o <format>    json (default) | table | ndjson | csv
 --fields, -f <fields>    Filter output fields: --fields ISU_NM,TDD_CLSPRC,FLUC_RT
+--code <isuCd>           Filter by stock code (ISU_CD)
+--sort <field>           Sort results by field name
+--asc                    Sort ascending (default: descending)
+--limit <n>              Limit number of results
+--from <date>            Start date for range query (YYYYMMDD)
+--to <date>              End date for range query (YYYYMMDD)
+--no-cache               Bypass cache and fetch fresh data
+--filter <expression>    Filter results (e.g. "FLUC_RT > 5", "MKT_NM == KOSPI")
 --dry-run                Show request details without calling API
+--save <path>            Save output to file instead of stdout
+--retries <n>            Max retries on network error (default: 3)
 --verbose, -v            Verbose logging to stderr
 ```
 
@@ -154,10 +205,36 @@ krx schema index.kospi_dd_trd # Specific endpoint schema
 krx index list --date 20260310 --market kospi --fields IDX_NM,CLSPRC_IDX,FLUC_RT
 ```
 
-### Get Samsung Electronics stock price
+### Get Samsung Electronics stock price (by search)
+
+```bash
+krx stock search 삼성전자     # Find ISU_CD first
+krx stock list --date 20260310 --market kospi --code KR7005930003
+```
+
+### Top 5 gainers
+
+```bash
+krx stock list --date 20260310 --market kospi --sort FLUC_RT --limit 5 --fields ISU_NM,TDD_CLSPRC,FLUC_RT
+```
+
+### Date range query (multi-day)
+
+```bash
+krx index list --market kospi --from 20260301 --to 20260310 --fields IDX_NM,BAS_DD,CLSPRC_IDX
+```
+
+### Quick market overview
+
+```bash
+krx market summary --date 20260310
+```
+
+### Track and monitor stocks
 
 ```bash
-krx stock list --date 20260310 --market kospi --fields ISU_NM,TDD_CLSPRC,FLUC_RT | jq '.[] | select(.ISU_NM == "삼성전자")'
+krx watchlist add 삼성전자           # Add to watchlist
+krx watchlist show --date 20260310  # View prices for all watchlist stocks
 ```
 
 ### Check API availability before querying
@@ -294,3 +371,13 @@ krx schema index.kospi_dd_trd    # Shows params + responseFields
 krx schema stock.stk_bydd_trd   # Stock endpoint fields
 krx schema --all                  # All 31 endpoints
 ```
+
+## MCP Resources
+
+Read-only state data exposed as MCP Resources (for MCP clients):
+
+| Resource               | Description                         |
+| ---------------------- | ----------------------------------- |
+| `krx://watchlist`      | Watchlist entries (JSON)            |
+| `krx://rate-limit`     | Daily API call status (JSON)        |
+| `krx://service-status` | Per-category approval status (JSON) |