krx-cli 1.6.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)         | -                              |

package/SKILL.md

@@ -7,7 +7,7 @@ install: npm install -g krx-cli
 binary: krx
 metadata:
   author: kyo504
-  version: "1.6.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
@@ -182,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)
@@ -205,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

package/dist/cli.js

@@ -48869,6 +48869,9 @@ function applyPipeline(data, options) {
   if (options.sort) {
     result = sortData(result, options.sort, options.direction ?? "desc");
   }
+  if (options.offset && options.offset > 0) {
+    result = result.slice(options.offset);
+  }
   if (options.limit && options.limit > 0) {
     result = limitData(result, options.limit);
   }
@@ -48971,6 +48974,7 @@ async function executeCommand(options) {
     filter: parentOpts.filter,
     sort: parentOpts.sort,
     direction: parentOpts.asc ? "asc" : "desc",
+    offset: parentOpts.offset,
     limit: parentOpts.limit
   });
   if (data.length === 0) {
@@ -60522,6 +60526,42 @@ var EMPTY_COMPLETION_RESULT = {
   }
 };
 
+// src/mcp/tools/result.ts
+var MAX_RESULT_BYTES = 9e5;
+function successResult(data) {
+  const text = JSON.stringify(data, null, 2);
+  if (Buffer.byteLength(text, "utf-8") <= MAX_RESULT_BYTES) {
+    return { content: [{ type: "text", text }] };
+  }
+  let lo = 0;
+  let hi = data.length;
+  while (lo < hi) {
+    const mid = Math.ceil((lo + hi) / 2);
+    const candidate = JSON.stringify(data.slice(0, mid), null, 2);
+    if (Buffer.byteLength(candidate, "utf-8") <= MAX_RESULT_BYTES - 200) {
+      lo = mid;
+    } else {
+      hi = mid - 1;
+    }
+  }
+  const truncated = data.slice(0, lo);
+  const result = {
+    data: truncated,
+    _truncated: {
+      total: data.length,
+      returned: lo,
+      message: `Result truncated: ${lo} of ${data.length} rows returned. To get remaining rows, use offset=${lo} with limit=${lo}. Or use 'fields' to reduce row size.`
+    }
+  };
+  return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+}
+function errorResult(message) {
+  return {
+    content: [{ type: "text", text: JSON.stringify({ error: message }) }],
+    isError: true
+  };
+}
+
 // src/mcp/tools/index.ts
 function getEndpointShortName(path6) {
   return path6.split("/").pop() ?? path6;
@@ -60541,7 +60581,8 @@ Notes:
 - Date format: YYYYMMDD (e.g., 20260310)
 - Data is T-1 (previous trading day)
 - All response values are strings
-- Rate limit: 10,000 calls/day`;
+- Rate limit: 10,000 calls/day
+- IMPORTANT: Full market listings can exceed the 1MB result limit. Use 'fields' to select only needed columns, or 'limit'+'offset' for pagination. If the response contains '_truncated', follow its instructions to retrieve remaining data.`;
 }
 function buildInputSchema(endpoints) {
   const shortNames = endpoints.map((e) => getEndpointShortName(e.path));
@@ -60559,6 +60600,7 @@ function buildInputSchema(endpoints) {
     isuCd: external_exports.string().optional().describe("Stock/item code (ISU_CD) to filter a specific item"),
     sort: external_exports.string().optional().describe("Sort results by this field name"),
     sort_direction: external_exports.enum(["asc", "desc"]).optional().describe("Sort direction (default: desc)"),
+    offset: external_exports.number().optional().describe("Skip first N results (use with limit for pagination)"),
     limit: external_exports.number().optional().describe("Limit number of results returned"),
     filter: external_exports.string().optional().describe(
       'Filter expression (e.g. "FLUC_RT > 5", "MKT_NM == KOSPI"). Operators: >, <, >=, <=, ==, !='
@@ -60581,14 +60623,6 @@ function filterFields2(data, fields) {
     return filtered;
   });
 }
-function errorResult(message) {
-  return {
-    content: [
-      { type: "text", text: JSON.stringify({ error: message }) }
-    ],
-    isError: true
-  };
-}
 function createCategoryTool(categoryId) {
   const endpoints = ENDPOINTS.filter((e) => e.category === categoryId);
   return {
@@ -60645,22 +60679,20 @@ function createCategoryTool(categoryId) {
         const filterExpr = args.filter;
         const sortField2 = args.sort;
         const sortDirection2 = args.sort_direction ?? "desc";
+        const offsetN2 = args.offset;
         const limitN2 = args.limit;
         data2 = applyPipeline(data2, {
           filter: filterExpr,
           sort: sortField2,
           direction: sortDirection2,
+          offset: offsetN2,
           limit: limitN2
         });
         const fields2 = args.fields;
         if (fields2) {
           data2 = filterFields2(data2, fields2);
         }
-        return {
-          content: [
-            { type: "text", text: JSON.stringify(data2, null, 2) }
-          ]
-        };
+        return successResult(data2);
       }
       const dateStr = args.date ?? getRecentTradingDate();
       try {
@@ -60685,23 +60717,21 @@ function createCategoryTool(categoryId) {
       const filterExpr2 = args.filter;
       const sortField = args.sort;
       const sortDirection = args.sort_direction ?? "desc";
+      const offsetN = args.offset;
       const limitN = args.limit;
       let data = result.data;
       data = applyPipeline(data, {
         filter: filterExpr2,
         sort: sortField,
         direction: sortDirection,
+        offset: offsetN,
         limit: limitN
       });
       const fields = args.fields;
       if (fields) {
         data = filterFields2(data, fields);
       }
-      return {
-        content: [
-          { type: "text", text: JSON.stringify(data, null, 2) }
-        ]
-      };
+      return successResult(data);
     }
   };
 }
@@ -61212,7 +61242,11 @@ function startHttpServer(options) {
       sessionTimers.delete(sessionId);
     }
   }
+  const originalWarn = console.warn;
+  console.warn = () => {
+  };
   const app = createMcpExpressApp({ host });
+  console.warn = originalWarn;
   app.get("/health", (_req, res) => {
     res.json({
       status: "ok",
@@ -61359,7 +61393,11 @@ function registerServeCommand(program3) {
 
 // src/cli/index.ts
 var program2 = new Command();
-program2.name("krx").description("Agent-native CLI for KRX (Korea Exchange) Open API").version(getVersion()).option("-o, --output <format>", "output format: json, table, ndjson, csv").option("-f, --fields <fields>", "comma-separated fields to include").option("--dry-run", "show request without calling API").option("-v, --verbose", "verbose output to stderr").option("--code <isuCd>", "filter by stock code (ISU_CD)").option("--sort <field>", "sort results by field name").option("--asc", "sort ascending (default: descending)").option("--limit <n>", "limit number of results", parseInt).option("--no-cache", "bypass cache and fetch fresh data").option("--from <date>", "start date for range query (YYYYMMDD)").option("--to <date>", "end date for range query (YYYYMMDD)").option("--filter <expression>", 'filter results (e.g. "FLUC_RT > 5")').option("--save <path>", "save output to file instead of stdout").option(
+program2.name("krx").description("Agent-native CLI for KRX (Korea Exchange) Open API").version(getVersion()).option("-o, --output <format>", "output format: json, table, ndjson, csv").option("-f, --fields <fields>", "comma-separated fields to include").option("--dry-run", "show request without calling API").option("-v, --verbose", "verbose output to stderr").option("--code <isuCd>", "filter by stock code (ISU_CD)").option("--sort <field>", "sort results by field name").option("--asc", "sort ascending (default: descending)").option(
+  "--offset <n>",
+  "skip first N results (for pagination)",
+  (v) => Number(v)
+).option("--limit <n>", "limit number of results", parseInt).option("--no-cache", "bypass cache and fetch fresh data").option("--from <date>", "start date for range query (YYYYMMDD)").option("--to <date>", "end date for range query (YYYYMMDD)").option("--filter <expression>", 'filter results (e.g. "FLUC_RT > 5")').option("--save <path>", "save output to file instead of stdout").option(
   "--retries <n>",
   "max retries on network error (default: 3)",
   parseInt