@insightsentry/mcp 1.4.40 → 1.4.42

package/README.md

@@ -55,6 +55,16 @@ Use `npx` in your MCP config:
 The MCP server also falls back to the key saved by `insight login` when `INSIGHTSENTRY_API_KEY` is not set.
 Set `INSIGHTSENTRY_CONFIG_DIR` to force the CLI and MCP server to read the same saved-login directory when they run with different home directories.
 
+### Bounded live collection for AI agents
+
+The MCP server exposes `collect_live` and `collect_newsfeed`. Both return structured JSON and stop
+after 20 data messages or 10 seconds by default. Calls can request up to 100 messages or 60 seconds;
+whichever limit is reached first ends the collection. A fixed response-size limit may stop a call
+earlier; check `stop_reason`. The structured result includes `activated`, while the text response is
+a short summary so message data is not duplicated. If the subscription does not activate before the
+duration limit, the call returns `activation_timeout`. Use the CLI commands below for continuous
+terminal streaming.
+
 ## CLI Usage
 
 ```bash
@@ -70,10 +80,11 @@ insight whoami
 insight search_symbols --query "tesla"
 insight get_quotes --codes "NASDAQ:AAPL,NASDAQ:MSFT"
 insight get_symbol_series --symbol "NASDAQ:AAPL" --bar_type day --dp 30
+insight get_options_snapshot --code "CBOE:VIX_W" --range 10
 insight screen_stocks --fields "close,volume,market_cap" --exchanges "NYSE,NASDAQ" --sortBy market_cap --sortOrder desc
 insight download_history --symbol "NASDAQ:AAPL" --bar_type day --from 2024-01-01 --to 2024-06-30 --output_dir ./history
-insight stream_live --symbols "NASDAQ:AAPL,NASDAQ:MSFT" --type both --bar_type minute --bar_interval 1
-insight stream_newsfeed --output_file ./news.ndjson --append
+insight stream_live --symbols "NASDAQ:AAPL,NASDAQ:MSFT" --type both --bar_type minute --bar_interval 1 --max_messages 100 --duration_seconds 30
+insight stream_newsfeed --output_file ./news.ndjson --append --duration_seconds 30
 ```
 
 Symbol codes must use `EXCHANGE:SYMBOL` format. Use `search_symbols` before calling symbol tools.
@@ -98,21 +109,23 @@ The long-running WebSocket commands are available through the terminal CLI:
 
 ```bash
 # Use the same settings for every symbol
-insight stream_live --symbols "NASDAQ:AAPL,NASDAQ:MSFT" --type quote
+insight stream_live --symbols "NASDAQ:AAPL,NASDAQ:MSFT" --type quote \
+  --max_messages 100 --duration_seconds 30
 
 # Use different settings per symbol
 insight stream_live \
-  --subscriptions '[{"code":"NASDAQ:AAPL","type":"series","bar_type":"minute","bar_interval":5},{"code":"NASDAQ:MSFT","type":"quote"}]'
+  --subscriptions '[{"code":"NASDAQ:AAPL","type":"series","bar_type":"minute","bar_interval":5},{"code":"NASDAQ:MSFT","type":"quote"}]' \
+  --duration_seconds 60
 
 # Collect 100 data messages, then disconnect successfully
 insight stream_live --symbols "NASDAQ:AAPL" --type quote --max_messages 100
 
 # Stream all news to stdout
-insight stream_newsfeed
+insight stream_newsfeed --max_messages 20 --duration_seconds 30
 
 # Append filtered news to a file and also emit it to stdout
 insight stream_newsfeed --content "earnings" --related_symbols "NASDAQ:AAPL" \
-  --output_file ./news.ndjson --append --tee
+  --output_file ./news.ndjson --append --tee --duration_seconds 60
 ```
 
 In an interactive terminal, run `insight stream_live` or choose it from the no-argument command
@@ -124,7 +137,8 @@ unless `--append` is set; `--tee` also writes the same lines to stdout. Connecti
 and local errors are written to stderr, so stdout remains valid NDJSON and can be piped safely:
 
 ```bash
-insight stream_live --symbols "NASDAQ:AAPL" --type quote | jq -c .
+insight stream_live --symbols "NASDAQ:AAPL" --type quote \
+  --max_messages 20 --duration_seconds 30 --quiet | jq -c .
 ```
 
 The CLI answers WebSocket control pings, reconnects with bounded exponential backoff, and resends
@@ -138,6 +152,9 @@ and exits successfully. The message limit counts quote, series, or news data—n
 market-data timestamp frames—and continues across reconnects. `--max_reconnect_attempts 0` disables
 automatic reconnects.
 
+Use `--quiet` to suppress WebSocket connection and status diagnostics. Preflight errors still use
+stderr, received server error frames remain in NDJSON, and failures retain a non-zero exit code.
+
 Newsfeed connections replay up to 10 recent matching items before streaming new items. Reconnecting
 can therefore repeat items already written; consumers should deduplicate by `link`, or by
 `published_at`, `source`, and `title` when no link is present. Content terms are matched with OR,
@@ -145,10 +162,10 @@ while populated `source`, `related_symbols`, and `content` filters are combined
 
 Quote updates can be sparse. Merge updates by `code` when maintaining a current quote snapshot.
 
-Run `insight stream_live --help` or `insight stream_newsfeed --help` for every flag. WebSocket
-streaming is CLI-only and is not registered as a long-running MCP tool.
+Run `insight stream_live --help` or `insight stream_newsfeed --help` for every flag. Continuous
+WebSocket streaming is CLI-only; use the bounded MCP collection tools from an AI client.
 
-## Tools
+## MCP Tools
 
 Auth and files:
 
@@ -158,8 +175,6 @@ Auth and files:
 | `download_history` | Download date ranges to JSON/CSV files |
 | `get_symbol_history` | Same as `download_history`; downloads history to files |
 | `render_chart` | Render Chart.js configs as PNG images |
-| `stream_live` | Stream real-time market data as NDJSON |
-| `stream_newsfeed` | Stream financial news as NDJSON |
 
 Market data:
 
@@ -172,6 +187,8 @@ Market data:
 | `get_sip_quotes` | Latest SIP quotes |
 | `get_sip_series` | Recent SIP market-data series |
 | `get_sip_history` | SIP intraday history for a specific period |
+| `collect_live` | Collect a bounded sample of live quotes or series |
+| `collect_newsfeed` | Collect a bounded sample of live financial news |
 | `get_symbol_info` | Symbol metadata |
 | `get_symbol_session` | Trading hours and session details |
 | `get_symbol_contracts` | Futures contract list |
@@ -184,6 +201,7 @@ Fundamentals, options, screeners, calendars, documents:
 | `get_fundamentals_series` | Historical fundamental indicators |
 | `get_fundamentals_meta` | Available fundamental/technical IDs |
 | `get_options_contracts` | Option contract metadata and codes |
+| `get_options_snapshot` | Latest option bars, quotes, trades, Greeks, and implied volatility |
 | `get_options_quotes` | Option quote rows with bid/ask and Greeks |
 | `screen_stocks`, `screen_etfs`, `screen_bonds`, `screen_crypto` | Screen assets |
 | `get_stock_screener_params`, `get_etf_screener_params`, `get_bond_screener_params`, `get_crypto_screener_params` | Screener fields |

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/cli.js

@@ -22,6 +22,7 @@ import { toolDefinitions } from "./tool-definitions.js";
 import { runApiTool, validateFilterExpression } from "./tool-runner.js";
 import { fetchLatestPackageVersion, formatUpgradeNotice, formatVersionStatus, getVersionStatus, } from "./version-status.js";
 import { buildLiveStreamRequest, buildNewsfeedStreamRequest, } from "./websocket-contract.js";
+import { LIVE_STREAM_SCHEMA, NEWSFEED_STREAM_SCHEMA, STREAM_OUTPUT_SCHEMA, } from "./websocket-schemas.js";
 import { runWebSocketStream, } from "./websocket-stream.js";
 export { coerceArgs } from "./arg-coercion.js";
 const DOWNLOAD_HISTORY_COMMAND = "download_history";
@@ -75,83 +76,6 @@ const RENDER_CHART_SCHEMA = {
         .optional()
         .describe("Chart height in pixels. Default: 400."),
 };
-const LIVE_STREAM_SCHEMA = {
-    symbols: z
-        .string()
-        .optional()
-        .describe("Comma-separated EXCHANGE:SYMBOL codes for simple subscriptions."),
-    type: z
-        .enum(["quote", "quotes", "series", "both"])
-        .optional()
-        .describe("Data to receive for every symbol. quotes is accepted as an alias for quote."),
-    subscriptions: z
-        .string()
-        .optional()
-        .describe("JSON array of subscription objects for different per-symbol settings."),
-    bar_type: z
-        .enum(["tick", "second", "minute", "hour", "day", "week", "month"])
-        .optional()
-        .describe("Series bar type."),
-    bar_interval: z
-        .number()
-        .int()
-        .positive()
-        .optional()
-        .describe("Series interval. Tick requires 1; second accepts 1, 5, 10, 15, 30, or 45."),
-    dp: z
-        .number()
-        .int()
-        .min(1)
-        .max(30_000)
-        .optional()
-        .describe("Initial series data points, 1-30000."),
-    currency: z.string().optional().describe("Requested currency code."),
-    unit: z.string().optional().describe("Requested unit code."),
-    extended: z.boolean().optional().describe("Include extended-hours data."),
-    "24h": z.boolean().optional().describe("Include 24-hour market data."),
-    split: z.boolean().optional().describe("Apply split adjustment."),
-    dadj: z.boolean().optional().describe("Apply dividend adjustment."),
-    badj: z.boolean().optional().describe("Back-adjust continuous futures."),
-    settlement: z.boolean().optional().describe("Use settlement as daily close."),
-    slow_consumer_policy: z
-        .enum(["disconnect", "adaptive"])
-        .optional()
-        .describe("Use adaptive for fresh lower-frequency delivery instead of backlog disconnects."),
-};
-const NEWSFEED_STREAM_SCHEMA = {
-    source: z.string().optional().describe("Case-insensitive exact source name."),
-    related_symbols: z.string().optional().describe("Comma- or space-separated related symbols."),
-    content: z
-        .string()
-        .optional()
-        .describe("Comma- or space-separated terms; matches when content contains at least one term."),
-};
-const STREAM_OUTPUT_SCHEMA = {
-    output_file: z.string().optional().describe("Write NDJSON messages to this file."),
-    append: z
-        .boolean()
-        .optional()
-        .describe("Append instead of replacing the output file. Requires output_file."),
-    tee: z.boolean().optional().describe("Also write NDJSON to stdout when output_file is set."),
-    max_reconnect_attempts: z
-        .number()
-        .int()
-        .min(0)
-        .max(100)
-        .optional()
-        .describe("Maximum consecutive reconnect or request-retry attempts. Use 0 to disable automatic reconnects. Default: 10."),
-    duration_seconds: z
-        .number()
-        .positive()
-        .optional()
-        .describe("Stop successfully after this total duration, including reconnects."),
-    max_messages: z
-        .number()
-        .int()
-        .positive()
-        .optional()
-        .describe("Stop successfully after this many data messages; status and time frames do not count."),
-};
 export function parseArgs(argv) {
     const args = {};
     const valuelessArgs = new Set();
@@ -227,8 +151,8 @@ export function buildHelp() {
     lines.push('  insight screen_stocks --fields "close,volume,market_cap" --exchanges "NYSE,NASDAQ" --sortBy market_cap --sortOrder desc');
     lines.push("  insight get_earnings --c US");
     lines.push('  insight get_options_contracts --code "NASDAQ:AAPL" --type call --range 10');
-    lines.push('  insight stream_live --symbols "NASDAQ:AAPL" --type both --bar_type minute');
-    lines.push("  insight stream_newsfeed --output_file ./news.ndjson --append");
+    lines.push('  insight stream_live --symbols "NASDAQ:AAPL" --type both --bar_type minute --max_messages 100 --duration_seconds 30');
+    lines.push("  insight stream_newsfeed --output_file ./news.ndjson --append --duration_seconds 30");
     lines.push("");
     lines.push("API tools support --filter <jsonata> to transform the response.");
     lines.push("Use: insight <tool> --help for tool-specific parameters.");
@@ -317,7 +241,7 @@ export function buildStreamHelp(commandName) {
                     : "[optional]";
         lines.push(`  --${key.padEnd(24)} ${formatTypeName(zodType)} ${requirement}  ${formatHelpDescription(zodType)}`);
     }
-    lines.push("", "Boolean options accept a bare flag or an explicit true/false value.", "Received WebSocket frames use stdout as NDJSON; CLI status and local errors use stderr.");
+    lines.push("", "Boolean options accept a bare flag or an explicit true/false value.", "Received WebSocket frames use stdout as NDJSON; CLI status and local errors use stderr.", "Use --quiet to suppress WebSocket status diagnostics for machine-readable terminal output.");
     if (isLive) {
         lines.push("Quote updates can be sparse; merge updates by code when maintaining a current snapshot.");
     }
@@ -327,12 +251,12 @@ export function buildStreamHelp(commandName) {
     lines.push("");
     lines.push("Examples:");
     if (isLive) {
-        lines.push('  insight stream_live --symbols "NASDAQ:AAPL,NASDAQ:MSFT" --type both --bar_type minute --bar_interval 1');
-        lines.push(`  insight stream_live --subscriptions '[{"code":"NASDAQ:AAPL","type":"series","bar_type":"day"},{"code":"NASDAQ:MSFT","type":"quote"}]' --output_file ./market.ndjson --append`);
+        lines.push('  insight stream_live --symbols "NASDAQ:AAPL,NASDAQ:MSFT" --type both --bar_type minute --bar_interval 1 --max_messages 100 --duration_seconds 30');
+        lines.push(`  insight stream_live --subscriptions '[{"code":"NASDAQ:AAPL","type":"series","bar_type":"day"},{"code":"NASDAQ:MSFT","type":"quote"}]' --output_file ./market.ndjson --append --duration_seconds 60`);
     }
     else {
-        lines.push("  insight stream_newsfeed");
-        lines.push('  insight stream_newsfeed --content "earnings" --related_symbols "NASDAQ:AAPL" --output_file ./news.ndjson --append');
+        lines.push("  insight stream_newsfeed --max_messages 20 --duration_seconds 30");
+        lines.push('  insight stream_newsfeed --content "earnings" --related_symbols "NASDAQ:AAPL" --output_file ./news.ndjson --append --duration_seconds 60');
     }
     lines.push("");
     lines.push("Press Ctrl+C to close the socket after queued output is written.");
@@ -393,6 +317,7 @@ const toolExamples = {
     get_options_snapshot: [
         'insight get_options_snapshot --code "NASDAQ:AAPL"',
         'insight get_options_snapshot --code "NASDAQ:AAPL" --expiration "2026-06-19" --type call',
+        'insight get_options_snapshot --code "CBOE:VIX_W" --range 10',
     ],
     get_options_quotes: [
         'insight get_options_quotes --code "NASDAQ:AAPL"',
@@ -897,8 +822,10 @@ async function runStreamCliCommand(commandName, args, valuelessArgs, sessionApiK
         const request = commandName === STREAM_LIVE_COMMAND
             ? buildLiveStreamRequest(pickStreamInput(coerced, LIVE_STREAM_SCHEMA), apiKey)
             : buildNewsfeedStreamRequest(pickStreamInput(coerced, NEWSFEED_STREAM_SCHEMA), apiKey);
-        reportArgUsage(io, knownArgs, Object.keys(fullSchema), inputArgs);
-        if (request.ignoredArgs.length > 0) {
+        if (coerced.quiet !== true) {
+            reportArgUsage(io, knownArgs, Object.keys(fullSchema), inputArgs);
+        }
+        if (coerced.quiet !== true && request.ignoredArgs.length > 0) {
             io.progress?.(`Ignoring inapplicable subscription args: ${request.ignoredArgs.join(", ")}`);
         }
         const outputFactory = io.createStreamOutput ?? createStreamOutput;
@@ -912,7 +839,7 @@ async function runStreamCliCommand(commandName, args, valuelessArgs, sessionApiK
             const result = await runner({
                 request,
                 output: streamOutput,
-                diagnostics: io.progress,
+                diagnostics: coerced.quiet === true ? () => { } : io.progress,
                 signal: io.streamSignal,
                 maxReconnectAttempts: typeof coerced.max_reconnect_attempts === "number"
                     ? coerced.max_reconnect_attempts