krx-cli 1.3.1 → 1.6.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
 
@@ -224,16 +291,19 @@ mkdir -p ~/.claude/skills && cp SKILL.md ~/.claude/skills/krx-cli.md
 mkdir -p ~/.cursor/skills && cp SKILL.md ~/.cursor/skills/krx-cli.md
 ```
 
-## MCP 서버 (Claude Desktop / ChatGPT Desktop)
+## MCP 서버
 
-CLI 외에 MCP(Model Context Protocol) 서버도 제공합니다. Claude Desktop, ChatGPT Desktop 등 MCP를 지원하는 클라이언트에서 사용할 수 있습니다.
+CLI 외에 MCP(Model Context Protocol) 서버도 제공합니다. 두 가지 전송 방식을 지원합니다:
 
-### 설정 (Claude Desktop)
+| 전송 방식       | 바이너리    | 지원 클라이언트 |
+| --------------- | ----------- | --------------- |
+| stdio           | `krx-mcp`   | Claude Desktop  |
+| Streamable HTTP | `krx serve` | ChatGPT 웹      |
 
 API 키는 `krx auth set <key>`로 등록한 것이 자동으로 사용됩니다.
 `krx-mcp`는 `npm install -g krx-cli`로 설치하면 함께 설치됩니다.
 
-### Claude Desktop
+### Claude Desktop (stdio)
 
 설정 파일 위치:
 
@@ -250,38 +320,52 @@ API 키는 `krx auth set <key>`로 등록한 것이 자동으로 사용됩니다
 }
 ```
 
-### ChatGPT Desktop
+설정 후 앱을 재시작하면 MCP 도구가 활성화됩니다.
 
-설정 파일 위치:
+### ChatGPT 웹 (Streamable HTTP)
 
-- **macOS**: `~/Library/Application Support/com.openai.chat/mcp.json`
-- **Windows**: `%LOCALAPPDATA%\OpenAI\ChatGPT\mcp.json`
+ChatGPT 웹은 원격 MCP 서버만 지원하므로, HTTP 서버를 실행한 뒤 ngrok으로 외부에 노출해야 합니다.
 
-```json
-{
-  "mcpServers": {
-    "krx": {
-      "command": "krx-mcp"
-    }
-  }
-}
+```bash
+# 터미널 1: MCP 서버 실행
+krx serve --port 3000 --host 0.0.0.0
+
+# 터미널 2: ngrok으로 외부 노출
+ngrok http 3000
 ```
 
-설정 후 앱을 재시작하면 MCP 도구가 활성화됩니다.
+1. ngrok 출력에서 `https://xxxx.ngrok.io` URL 복사
+2. ChatGPT 웹 → Settings → Developer → MCP Server 추가
+3. URL: `https://xxxx.ngrok.io/mcp`
+
+Health check: `http://localhost:3000/health`
 
 ### 제공 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 +388,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.6.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,55 @@ 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)
+```
+
+### MCP HTTP Server
+
+```bash
+krx serve                        # Start on http://127.0.0.1:3000/mcp
+krx serve --port 8080            # Custom port
+krx serve --host 0.0.0.0        # Bind to all interfaces (for ngrok)
+```
+
 ### Schema (introspection)
 
 ```bash
@@ -128,9 +177,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 +213,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 stock list --date 20260310 --market kospi --fields ISU_NM,TDD_CLSPRC,FLUC_RT | jq '.[] | select(.ISU_NM == "삼성전자")'
+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 watchlist add 삼성전자           # Add to watchlist
+krx watchlist show --date 20260310  # View prices for all watchlist stocks
 ```
 
 ### Check API availability before querying
@@ -294,3 +379,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) |