krx-cli 1.5.0 → 1.7.0

package/README.md

@@ -180,6 +180,7 @@ krx schema stock.stk_bydd_trd
 | `--code <isuCd>`        | 종목코드 필터 (ISU_CD)              | -                              |
 | `--sort <field>`        | 결과 정렬 기준 필드                 | -                              |
 | `--asc`                 | 오름차순 정렬 (기본: 내림차순)      | -                              |
+| `--offset <n>`          | 처음 N개 건너뛰기 (페이지네이션)    | -                              |
 | `--limit <n>`           | 결과 개수 제한                      | -                              |
 | `--from <date>`         | 기간 조회 시작일 (YYYYMMDD)         | -                              |
 | `--to <date>`           | 기간 조회 종료일 (YYYYMMDD)         | -                              |
@@ -291,16 +292,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)
 
 설정 파일 위치:
 
@@ -317,24 +321,25 @@ 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
 

package/SKILL.md

@@ -7,7 +7,7 @@ install: npm install -g krx-cli
 binary: krx
 metadata:
   author: kyo504
-  version: "1.5.0"
+  version: "1.7.0"
 invariants:
   - Always use YYYYMMDD format for --date (e.g., 20260310)
   - Data is T-1 (previous trading day), available from 2010 onwards
@@ -159,6 +159,14 @@ 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
@@ -174,6 +182,7 @@ krx schema index.kospi_dd_trd # Specific endpoint schema
 --code <isuCd>           Filter by stock code (ISU_CD)
 --sort <field>           Sort results by field name
 --asc                    Sort ascending (default: descending)
+--offset <n>             Skip first N results (for pagination)
 --limit <n>              Limit number of results
 --from <date>            Start date for range query (YYYYMMDD)
 --to <date>              End date for range query (YYYYMMDD)
@@ -197,6 +206,39 @@ krx schema index.kospi_dd_trd # Specific endpoint schema
 6 = Service not approved (category not activated)
 ```
 
+## Handling Large Results
+
+Full market listings (e.g., all KOSPI stocks) output 900+ rows with 15+ fields each. This can exceed context limits. Always narrow results using these strategies:
+
+### Strategy 1: Select only needed fields (preferred)
+
+```bash
+# Instead of all fields, select only what's needed
+krx stock list --date 20260310 --market kospi --fields ISU_NM,TDD_CLSPRC,FLUC_RT
+```
+
+### Strategy 2: Paginate with offset + limit
+
+```bash
+# Page 1: first 100 rows
+krx stock list --date 20260310 --market kospi --limit 100
+
+# Page 2: next 100 rows
+krx stock list --date 20260310 --market kospi --offset 100 --limit 100
+
+# Page 3: next 100 rows
+krx stock list --date 20260310 --market kospi --offset 200 --limit 100
+```
+
+### Strategy 3: Filter to relevant subset
+
+```bash
+# Only stocks with >5% change
+krx stock list --date 20260310 --market kospi --filter "FLUC_RT > 5"
+```
+
+IMPORTANT: When the user asks for "all" data, prefer Strategy 1 (fields) first. If still too large, combine with Strategy 2 (pagination). Always tell the user the total count.
+
 ## Common Patterns
 
 ### Get KOSPI closing price for a specific date