stock-scanner-mcp 1.16.3 → 1.17.0

package/README.md

@@ -6,7 +6,7 @@
 
 A modular MCP server for Claude Code and Claude Desktop that provides real-time access to stock and crypto market data. Scan markets, check technicals, monitor insider trades, track earnings, analyze options flow, and optionally save your own watchlists and thesis notes from one server.
 
-**64 tools** across **13 modules** — 9 modules work with zero API keys, including an optional stateful Market Workspace.
+**65 tools** across **13 modules** — 9 modules work with zero API keys, including an optional stateful Market Workspace.
 
 ## Quick Start
 
@@ -97,7 +97,7 @@ Once answered, it saves your profile and creates a `core` watchlist:
 
 You can also skip the skill and ask Claude directly: *"Set up my workspace — I'm a swing trader, create a core watchlist with MARA, HOOD, BTC, daily reviews."*
 
-**That's it.** You now have 64 tools, 19 skills, and a personalized workspace. Try `/workspace-morning-brief` for your first tailored market scan.
+**That's it.** You now have 65 tools, 19 skills, and a personalized workspace. Try `/workspace-morning-brief` for your first tailored market scan.
 
 ## What You Can Do
 
@@ -208,6 +208,14 @@ Data is stored locally in `workspace.json` — no cloud sync, no external calls.
 
 For the full list of workspace tools, see the [tool reference](#workspace--personalized-context-optional-no-api-key) below.
 
+## Documentation
+
+- **[Installation & Setup](https://github.com/yyordanov-tradu/stock-scanner-mcp/wiki/Installation-&-Setup)** — Getting the MCP server running in Claude Code or Cursor
+- **[Trading Skills](https://github.com/yyordanov-tradu/stock-scanner-mcp/wiki/Trading-Skills)** — Ready-made workflows for professional analysis
+- **[Sidecar HTTP API](https://github.com/yyordanov-tradu/stock-scanner-mcp/wiki/Sidecar-HTTP-API)** — REST endpoints for non-MCP clients
+- **[Docker Deployment](docs/DOCKER.md)** — Running in containers with workspace persistence
+- **[FAQ & Troubleshooting](https://github.com/yyordanov-tradu/stock-scanner-mcp/wiki/FAQ-&-Troubleshooting)** — Common issues and solutions
+
 ## Modules
 
 | Module | Tools | API Key | Description |
@@ -220,7 +228,7 @@ For the full list of workspace tools, see the [tool reference](#workspace--perso
 | options-cboe | 1 | None | CBOE put/call ratio sentiment indicator |
 | sentiment | 2 | None | CNN Fear & Greed Index, Crypto Fear & Greed Index |
 | frankfurter | 5 | None | Forex exchange rates — 31 currencies from ECB (daily reference rates) |
-| reddit | 3 | None | Reddit trending tickers, mention tracking, and sentiment from r/wallstreetbets, r/stocks, r/investing, r/options |
+| reddit | 4 | None | Reddit trending tickers, mention tracking, sentiment, and batch watchlist scan from r/wallstreetbets, r/stocks, r/investing, r/options |
 | workspace | 7 | None | Optional stateful profile, watchlists, and thesis tracking for personalized workflows (`--enable-workspace`) |
 | finnhub | 9 | `FINNHUB_API_KEY` | Quotes, news, earnings, analyst ratings, short interest |
 | alpha-vantage | 5 | `ALPHA_VANTAGE_API_KEY` | Quotes, daily prices, fundamentals, earnings, dividends |
@@ -230,7 +238,7 @@ Modules auto-enable when their API key is set. No-key modules are always enabled
 
 For a complete list of every tool with descriptions, see the [Full Tool Reference](#full-tool-reference-64-tools) below.
 
-## Full Tool Reference (64 tools)
+## Full Tool Reference (65 tools)
 
 ### TradingView — Stock Scanning (no API key)
 
@@ -315,6 +323,7 @@ For a complete list of every tool with descriptions, see the [Full Tool Referenc
 | `reddit_trending` | Trending stock tickers from Reddit by mention frequency across r/wallstreetbets, r/stocks, r/investing, r/options |
 | `reddit_mentions` | Mention count and top posts for a specific ticker across Reddit investing subreddits |
 | `reddit_sentiment` | Keyword-based sentiment analysis (bullish/bearish/neutral) for a ticker from Reddit discussions |
+| `reddit_watchlist_scan` | Batch Reddit scan for a list of tickers in one pass (combined OR query, ceil(N/20)×4 requests) — per-ticker mentions, sentiment, top post, and a hot flag (≥5 mentions) |
 
 ### Workspace — Personalized Context (optional, no API key)
 
@@ -399,14 +408,16 @@ An optional HTTP server exposing all tools as REST endpoints for non-MCP integra
 npx stock-scanner-sidecar              # Start on port 3200
 npx stock-scanner-sidecar --port 8080  # Custom port
 
+# Optional: Enable the stateful Market Workspace via HTTP
+npx stock-scanner-sidecar --enable-workspace --data-dir ./my-data
+
 # Access the OpenAPI spec
 curl http://localhost:3200/openapi.json
 ```
 
-See [Sidecar HTTP API](wiki-repo/Sidecar-HTTP-API.md) for endpoint details.
-```
+See [Sidecar HTTP API](https://github.com/yyordanov-tradu/stock-scanner-mcp/wiki/Sidecar-HTTP-API) for endpoint details.
 
-55 endpoints including `/tradingview/quote`, `/options/chain`, `/frankfurter/convert`, and more. See [wiki](https://github.com/yyordanov-tradu/stock-scanner-mcp/wiki/Sidecar-HTTP-API) for the full route table.
+**65 tools** exposed as REST routes, including `/tradingview/quote`, `/options/chain`, `/workspace/profile`, and more.
 
 ## Rate Limits
 
@@ -459,10 +470,11 @@ src/
 │   ├── fred/             # 4 tools — economic calendar, indicators, historical data
 │   ├── sentiment/        # 2 tools — Fear & Greed indexes (market + crypto)
 │   ├── frankfurter/      # 5 tools — forex exchange rates (ECB, 31 currencies)
-│   └── reddit/           # 3 tools — trending tickers, mentions, sentiment from Reddit
+│   └── reddit/           # 4 tools — trending tickers, mentions, sentiment, watchlist scan from Reddit
 ├── sidecar/
 │   ├── index.ts          # HTTP sidecar entry point (port 3200)
-│   └── server.ts         # HTTP request handler (55 endpoints)
+│   ├── routes.ts         # Declarative URL routing table
+│   └── server.ts         # Dynamic HTTP request handler
 └── shared/
     ├── http.ts           # HTTP client with timeouts and key sanitization
     ├── cache.ts          # In-memory TTL cache

package/dist/{chunk-5IWY6HOQ.js → chunk-WRGE3BZV.js}

@@ -2978,6 +2978,7 @@ var DEFAULT_SUBREDDITS = [
 ];
 var trendingCache = new TtlCache(5 * 60 * 1e3);
 var mentionCache = new TtlCache(2 * 60 * 1e3);
+var watchlistCache = new TtlCache(5 * 60 * 1e3);
 var STOP_WORDS = /* @__PURE__ */ new Set([
   // 1-2 letter
   "I",
@@ -3466,6 +3467,75 @@ async function getTickerMentions(symbol, period = "week") {
   mentionCache.set(cacheKey, result);
   return result;
 }
+var WATCHLIST_BATCH_SIZE = 20;
+var HOT_THRESHOLD = 5;
+async function scanWatchlist(symbols, period = "day") {
+  const upperSymbols = symbols.map((s) => s.toUpperCase());
+  const cacheKey = `watchlist:${[...upperSymbols].sort().join(",")}:${period}`;
+  const cached = watchlistCache.get(cacheKey);
+  if (cached) return cached;
+  const tickerData = /* @__PURE__ */ new Map();
+  for (const sym of upperSymbols) {
+    tickerData.set(sym, { mentions: 0, bullish: 0, bearish: 0, neutral: 0, scoreSum: 0, topPost: null });
+  }
+  const batches = [];
+  for (let i = 0; i < upperSymbols.length; i += WATCHLIST_BATCH_SIZE) {
+    batches.push(upperSymbols.slice(i, i + WATCHLIST_BATCH_SIZE));
+  }
+  let requestsMade = 0;
+  for (const batch of batches) {
+    const orQuery = batch.join(" OR ");
+    const settled = await Promise.allSettled(
+      DEFAULT_SUBREDDITS.map((sub) => fetchSubredditPosts(sub, orQuery, period, 100))
+    );
+    for (const outcome of settled) {
+      if (outcome.status !== "fulfilled") continue;
+      requestsMade += 1;
+      const posts = outcome.value;
+      for (const post of posts) {
+        const text = `${post.title} ${post.selftext}`;
+        const matched = extractTickers(text).filter((t) => tickerData.has(t));
+        if (matched.length === 0) continue;
+        const sentScore = scoreSentiment(text);
+        for (const sym of matched) {
+          const acc = tickerData.get(sym);
+          acc.mentions += 1;
+          if (sentScore > 0) acc.bullish += 1;
+          else if (sentScore < 0) acc.bearish += 1;
+          else acc.neutral += 1;
+          acc.scoreSum += sentScore;
+          if (!acc.topPost || post.score > acc.topPost.score) {
+            acc.topPost = { title: post.title, score: post.score, subreddit: post.subreddit };
+          }
+        }
+      }
+    }
+  }
+  const tickers = upperSymbols.map((sym) => {
+    const acc = tickerData.get(sym);
+    const total = acc.bullish + acc.bearish + acc.neutral;
+    return {
+      symbol: sym,
+      mentions: acc.mentions,
+      sentiment: {
+        bullish: acc.bullish,
+        bearish: acc.bearish,
+        neutral: acc.neutral,
+        score: total > 0 ? Math.round(acc.scoreSum / total * 100) / 100 : 0
+      },
+      topPost: acc.topPost,
+      hot: acc.mentions >= HOT_THRESHOLD
+    };
+  }).sort((a, b) => b.mentions - a.mentions);
+  const result = {
+    scanned: upperSymbols.length,
+    subredditsChecked: [...DEFAULT_SUBREDDITS],
+    requestsMade,
+    tickers
+  };
+  watchlistCache.set(cacheKey, result);
+  return result;
+}
 async function getTickerSentiment(symbol, limit = 50) {
   const cacheKey = `sentiment:${symbol}:${limit}`;
   const cached = mentionCache.get(cacheKey);
@@ -3546,12 +3616,25 @@ var sentimentTool = {
     return successResult(JSON.stringify(result, null, 2));
   }, { source: "reddit", dataDelay: "real-time" })
 };
+var watchlistScanTool = {
+  name: "reddit_watchlist_scan",
+  description: "Batch Reddit sentiment scan for a list of stock tickers in a single pass. Combines the tickers into one OR query per subreddit (r/wallstreetbets, r/stocks, r/investing, r/options), costing ceil(symbols/20)\xD74 requests instead of one call per ticker \u2014 prefer this over calling reddit_mentions or reddit_sentiment for each symbol in a watchlist. Returns, per ticker: mention count, bullish/bearish/neutral sentiment breakdown with an average score, the top post by upvotes, and a 'hot' flag (true when a ticker has 5 or more mentions in the period). Limitations: keyword-based scoring, not NLP (sarcasm/context may be missed); sentiment is scored per-post, not per-ticker, so a multi-ticker post applies the same score to each matched symbol; symbols that collide with common English words/finance acronyms (e.g. REAL, OPEN, HOLD, SELL) or fall outside 2\u20135 uppercase characters may report zero mentions even when discussed; and because each subreddit's combined query shares one 100-post cap, heavily-discussed tickers in a large batch can crowd out quieter ones, so counts may run lower than a single-ticker reddit_mentions query. Results cached for 5 minutes.",
+  inputSchema: z12.object({
+    symbols: z12.array(z12.string().max(10)).min(1).max(50).describe("Watchlist stock tickers to scan, e.g. ['AAPL', 'NVDA', 'TSLA'] (1\u201350 symbols)"),
+    period: z12.enum(["hour", "day", "week"]).default("day").describe("Time window to search Reddit posts (default: day)")
+  }),
+  readOnly: true,
+  handler: withMetadata(async (args) => {
+    const result = await scanWatchlist(args.symbols, args.period ?? "day");
+    return successResult(JSON.stringify(result, null, 2));
+  }, { source: "reddit", dataDelay: "real-time" })
+};
 function createRedditModule() {
   return {
     name: "reddit",
     description: "Reddit sentiment \u2014 trending tickers, mention tracking, and sentiment analysis from popular investing subreddits",
     requiredEnvVars: [],
-    tools: [trendingTool2, mentionsTool, sentimentTool]
+    tools: [trendingTool2, mentionsTool, sentimentTool, watchlistScanTool]
   };
 }
 
@@ -3975,7 +4058,7 @@ var MODULE_CATALOG = [
   { name: "fred", envVar: "FRED_API_KEY", toolCount: 4, factory: (config) => config.env.FRED_API_KEY ? createFredModule(config.env.FRED_API_KEY) : null },
   { name: "sentiment", envVar: null, toolCount: 2, factory: () => createSentimentModule() },
   { name: "frankfurter", envVar: null, toolCount: 5, factory: () => createFrankfurterModule() },
-  { name: "reddit", envVar: null, toolCount: 3, factory: () => createRedditModule() },
+  { name: "reddit", envVar: null, toolCount: 4, factory: () => createRedditModule() },
   { name: "workspace", envVar: null, toolCount: 7, factory: (config) => config.enableWorkspace ? createWorkspaceModule(config.dataDir || path2.join(os.homedir(), ".stock-scanner-mcp"), config.defaultExchange) : null }
 ];
 function resolveEnabledModules(allModules, env, filter) {

package/dist/index.js

@@ -5,7 +5,7 @@ import {
 import {
   MODULE_CATALOG,
   resolveEnabledModules
-} from "./chunk-5IWY6HOQ.js";
+} from "./chunk-WRGE3BZV.js";
 
 // src/index.ts
 import { readFileSync } from "fs";
@@ -79,7 +79,7 @@ OPTIONS
   --enable-workspace      Enable stateful workspace (watchlists, theses, profile)
   --data-dir <path>       Directory for workspace storage (default: ~/.stock-scanner-mcp)
 
-MODULES (64 tools total)
+MODULES (65 tools total)
   tradingview        10 tools Stock scanning, quotes, technicals       (no key)
   tradingview-crypto 4 tools  Crypto pair scanning and technicals      (no key)
   sec-edgar          6 tools  SEC filings, insider trades, holdings    (no key)
@@ -88,7 +88,7 @@ MODULES (64 tools total)
   options-cboe       1 tool   CBOE put/call ratio sentiment            (no key)
   sentiment          2 tools  Market & crypto Fear & Greed sentiment   (no key)
   frankfurter        5 tools  Forex exchange rates and conversion       (no key)
-  reddit             3 tools  Reddit trending tickers and sentiment     (no key)
+  reddit             4 tools  Reddit trending, sentiment, watchlist scan (no key)
   workspace          7 tools  Stateful watchlists, theses, and profile  (no key)
   finnhub            9 tools  Quotes, profiles, peers, news, earnings  (FINNHUB_API_KEY)
   alpha-vantage      5 tools  Stock quotes, fundamentals, dividends    (ALPHA_VANTAGE_API_KEY)
@@ -132,6 +132,11 @@ async function main() {
     await runInstallSkills(args.slice(1));
     process.exit(0);
   }
+  if (args.includes("--version") || args.includes("-v")) {
+    process.stderr.write(`stock-scanner-mcp v${pkg.version}
+`);
+    process.exit(0);
+  }
   if (args.includes("--help") || args.includes("-h")) {
     printHelp();
     process.exit(0);

package/dist/sidecar/index.js

@@ -2,7 +2,7 @@
 import {
   MODULE_CATALOG,
   resolveEnabledModules
-} from "../chunk-5IWY6HOQ.js";
+} from "../chunk-WRGE3BZV.js";
 
 // src/sidecar/server.ts
 import * as http from "http";
@@ -144,6 +144,17 @@ var SIDECAR_ROUTES = [
   { method: "GET", path: "/reddit/trending", tool: "reddit_trending" },
   { method: "GET", path: "/reddit/mentions", tool: "reddit_mentions" },
   { method: "GET", path: "/reddit/sentiment", tool: "reddit_sentiment" },
+  {
+    method: "GET",
+    path: "/reddit/watchlist-scan",
+    tool: "reddit_watchlist_scan",
+    transformParams: (p) => ({
+      // Default to [] (not undefined) so a missing param fails Zod's .min(1)
+      // with a clear "at least 1" message rather than a generic type error.
+      symbols: p.get("symbols")?.split(",").map((s) => s.trim()).filter(Boolean) ?? [],
+      period: p.get("period") || void 0
+    })
+  },
   // Workspace
   { method: "GET", path: "/workspace/profile", tool: "workspace_get_profile" },
   { method: "POST", path: "/workspace/profile", tool: "workspace_update_profile" },
@@ -210,9 +221,7 @@ function convertZodToOpenApi(zod) {
     const inner = convertZodToOpenApi(def.innerType || def.schema);
     return { ...inner, optional: true, description: description || inner.description };
   }
-  if (typeName === "ZodNumber" || defType === "number") {
-    return { type: zod.isInt ? "integer" : "number", description };
-  }
+  if (typeName === "ZodNumber" || defType === "number") return { type: zod.isInt ? "integer" : "number", description };
   if (typeName === "ZodBoolean" || defType === "boolean") return { type: "boolean", description };
   if (typeName === "ZodEnum" || defType === "enum") return { type: "string", enum: def.values, description };
   if (typeName === "ZodString" || defType === "string") return { type: "string", description };
@@ -245,6 +254,51 @@ function convertZodToOpenApi(zod) {
   }
   return { type: "string", description };
 }
+function getResponseSchema(toolName) {
+  if (toolName.startsWith("tradingview_") || toolName.startsWith("crypto_")) {
+    return {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          symbol: { type: "string" },
+          data: { type: "object", additionalProperties: true }
+        }
+      }
+    };
+  }
+  if (toolName.startsWith("edgar_")) {
+    return { type: "array", items: { type: "object", additionalProperties: true } };
+  }
+  if (toolName === "finnhub_quote") {
+    return {
+      type: "object",
+      properties: {
+        c: { type: "number", description: "Current price" },
+        d: { type: "number", description: "Change" },
+        dp: { type: "number", description: "Percent change" },
+        h: { type: "number", description: "High price of the day" },
+        l: { type: "number", description: "Low price of the day" },
+        o: { type: "number", description: "Open price of the day" },
+        pc: { type: "number", description: "Previous close price" },
+        t: { type: "integer", description: "Timestamp" }
+      }
+    };
+  }
+  if (toolName.startsWith("finnhub_")) {
+    return { type: "object", additionalProperties: true };
+  }
+  if (toolName.startsWith("options_")) {
+    return { type: "object", additionalProperties: true };
+  }
+  if (toolName.startsWith("fred_")) {
+    return { type: "array", items: { type: "object", additionalProperties: true } };
+  }
+  if (toolName.startsWith("workspace_")) {
+    return { type: "object", additionalProperties: true };
+  }
+  return { type: "object", description: "Varies by tool" };
+}
 function generateOpenApiSpec() {
   const mockConfig = {
     env: {
@@ -315,7 +369,11 @@ function generateOpenApiSpec() {
       responses: {
         "200": {
           description: "Successful response",
-          content: { "application/json": { schema: { type: "object", description: "Varies by tool" } } }
+          content: {
+            "application/json": {
+              schema: getResponseSchema(route.tool)
+            }
+          }
         },
         "400": {
           description: "Invalid parameters",
@@ -361,7 +419,9 @@ function generateOpenApiSpec() {
           description: prop.description || ""
         };
         if (prop.type === "array") {
-          param.schema = { type: "string", description: prop.description + " (comma-separated list)" };
+          const desc = prop.description + " (comma-separated list)";
+          param.description = desc;
+          param.schema = { type: "string", description: desc };
         } else {
           param.schema = prop;
         }
@@ -455,8 +515,9 @@ function buildTools(config) {
       FRED_API_KEY: config.fredApiKey,
       ALPHA_VANTAGE_API_KEY: config.alphaVantageApiKey
     },
-    enableWorkspace: false,
-    defaultExchange: "NASDAQ"
+    enableWorkspace: config.enableWorkspace ?? false,
+    dataDir: config.dataDir,
+    defaultExchange: config.defaultExchange ?? "NASDAQ"
   };
   const allModules = MODULE_CATALOG.map((entry) => entry.factory(mockConfig)).filter((m) => m !== null);
   const enabled = resolveEnabledModules(allModules, mockConfig.env);
@@ -609,13 +670,29 @@ function parsePort(args) {
   }
   return 3200;
 }
+function parseStringFlag(args, flag) {
+  const idx = args.indexOf(flag);
+  if (idx !== -1 && args[idx + 1]) return args[idx + 1];
+  return void 0;
+}
 function main() {
   const args = process.argv.slice(2);
   const port = parsePort(args);
+  const enableWorkspace = args.includes("--enable-workspace");
+  const dataDir = parseStringFlag(args, "--data-dir") ?? process.env.STOCK_SCANNER_DATA_DIR;
+  const defaultExchange = parseStringFlag(args, "--default-exchange") ?? "NASDAQ";
   const finnhubApiKey = process.env.FINNHUB_API_KEY;
   const fredApiKey = process.env.FRED_API_KEY;
   const alphaVantageApiKey = process.env.ALPHA_VANTAGE_API_KEY;
-  const server = createServer2({ port, finnhubApiKey, fredApiKey, alphaVantageApiKey });
+  const server = createServer2({
+    port,
+    finnhubApiKey,
+    fredApiKey,
+    alphaVantageApiKey,
+    enableWorkspace,
+    dataDir,
+    defaultExchange
+  });
   const enabled = [];
   const disabled = [];
   if (finnhubApiKey) enabled.push("finnhub");
@@ -624,8 +701,10 @@ function main() {
   else disabled.push("fred (FRED_API_KEY not set)");
   if (alphaVantageApiKey) enabled.push("alpha-vantage");
   else disabled.push("alpha-vantage (ALPHA_VANTAGE_API_KEY not set)");
+  if (enableWorkspace) enabled.push("workspace");
+  else disabled.push("workspace (--enable-workspace not set)");
   console.error(`[stock-scanner-sidecar] listening on port ${port}`);
-  console.error(`  Always-on: tradingview, tradingview-crypto, sec-edgar, options, options-cboe, sentiment, coingecko, frankfurter`);
+  console.error(`  Always-on: tradingview, tradingview-crypto, sec-edgar, options, options-cboe, sentiment, coingecko, frankfurter, reddit`);
   if (enabled.length) console.error(`  Enabled:   ${enabled.join(", ")}`);
   if (disabled.length) console.error(`  Disabled:  ${disabled.join(", ")}`);
   const shutdown = () => {

package/docs/sidecar-openapi.json

@@ -3,7 +3,7 @@
   "info": {
     "title": "Stock Scanner Sidecar API",
     "description": "REST API for stock and crypto market data, SEC filings, and technical analysis. This is the HTTP sidecar for the stock-scanner-mcp server.",
-    "version": "1.16.3",
+    "version": "1.17.0",
     "contact": {
       "name": "Yordan Yordanov",
       "url": "https://github.com/yyordanov-tradu/stock-scanner-mcp"
@@ -52,8 +52,19 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
-                  "description": "Varies by tool"
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "symbol": {
+                        "type": "string"
+                      },
+                      "data": {
+                        "type": "object",
+                        "additionalProperties": true
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -178,8 +189,19 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
-                  "description": "Varies by tool"
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "symbol": {
+                        "type": "string"
+                      },
+                      "data": {
+                        "type": "object",
+                        "additionalProperties": true
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -220,7 +242,7 @@
             "name": "tickers",
             "in": "query",
             "required": true,
-            "description": "Stock tickers, e.g. ['AAPL', 'MSFT']",
+            "description": "Stock tickers, e.g. ['AAPL', 'MSFT'] (comma-separated list)",
             "schema": {
               "type": "string",
               "description": "Stock tickers, e.g. ['AAPL', 'MSFT'] (comma-separated list)"
@@ -239,8 +261,19 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
-                  "description": "Varies by tool"
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "symbol": {
+                        "type": "string"
+                      },
+                      "data": {
+                        "type": "object",
+                        "additionalProperties": true
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -281,7 +314,7 @@
             "name": "tickers",
             "in": "query",
             "required": true,
-            "description": "Stock tickers, e.g. ['AAPL', 'IBM']",
+            "description": "Stock tickers, e.g. ['AAPL', 'IBM'] (comma-separated list)",
             "schema": {
               "type": "string",
               "description": "Stock tickers, e.g. ['AAPL', 'IBM'] (comma-separated list)"
@@ -310,8 +343,19 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
-                  "description": "Varies by tool"
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "symbol": {
+                        "type": "string"
+                      },
+                      "data": {
+                        "type": "object",
+                        "additionalProperties": true
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -352,7 +396,7 @@
             "name": "tickers",
             "in": "query",
             "required": true,
-            "description": "2-5 stock tickers to compare (e.g. AAPL, MSFT)",
+            "description": "2-5 stock tickers to compare (e.g. AAPL, MSFT) (comma-separated list)",
             "schema": {
               "type": "string",
               "description": "2-5 stock tickers to compare (e.g. AAPL, MSFT) (comma-separated list)"
@@ -371,8 +415,19 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
-                  "description": "Varies by tool"
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "symbol": {
+                        "type": "string"
+                      },
+                      "data": {
+                        "type": "object",
+                        "additionalProperties": true
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -452,8 +507,19 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
-                  "description": "Varies by tool"
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "symbol": {
+                        "type": "string"
+                      },
+                      "data": {
+                        "type": "object",
+                        "additionalProperties": true
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -533,8 +599,19 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
-                  "description": "Varies by tool"
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "symbol": {
+                        "type": "string"
+                      },
+                      "data": {
+                        "type": "object",
+                        "additionalProperties": true
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -614,8 +691,19 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
-                  "description": "Varies by tool"
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "symbol": {
+                        "type": "string"
+                      },
+                      "data": {
+                        "type": "object",
+                        "additionalProperties": true
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -664,8 +752,19 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
-                  "description": "Varies by tool"
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "symbol": {
+                        "type": "string"
+                      },
+                      "data": {
+                        "type": "object",
+                        "additionalProperties": true
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -714,8 +813,19 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
-                  "description": "Varies by tool"
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "symbol": {
+                        "type": "string"
+                      },
+                      "data": {
+                        "type": "object",
+                        "additionalProperties": true
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -785,8 +895,19 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
-                  "description": "Varies by tool"
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "symbol": {
+                        "type": "string"
+                      },
+                      "data": {
+                        "type": "object",
+                        "additionalProperties": true
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -919,8 +1040,19 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
-                  "description": "Varies by tool"
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "symbol": {
+                        "type": "string"
+                      },
+                      "data": {
+                        "type": "object",
+                        "additionalProperties": true
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -961,7 +1093,7 @@
             "name": "symbols",
             "in": "query",
             "required": true,
-            "description": "Crypto pair symbols (e.g. ['BTCUSDT', 'ETHUSDT'])",
+            "description": "Crypto pair symbols (e.g. ['BTCUSDT', 'ETHUSDT']) (comma-separated list)",
             "schema": {
               "type": "string",
               "description": "Crypto pair symbols (e.g. ['BTCUSDT', 'ETHUSDT']) (comma-separated list)"
@@ -980,8 +1112,19 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
-                  "description": "Varies by tool"
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "symbol": {
+                        "type": "string"
+                      },
+                      "data": {
+                        "type": "object",
+                        "additionalProperties": true
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -1022,7 +1165,7 @@
             "name": "symbols",
             "in": "query",
             "required": true,
-            "description": "Crypto symbols (e.g. ['BTCUSDT'])",
+            "description": "Crypto symbols (e.g. ['BTCUSDT']) (comma-separated list)",
             "schema": {
               "type": "string",
               "description": "Crypto symbols (e.g. ['BTCUSDT']) (comma-separated list)"
@@ -1051,8 +1194,19 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
-                  "description": "Varies by tool"
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "symbol": {
+                        "type": "string"
+                      },
+                      "data": {
+                        "type": "object",
+                        "additionalProperties": true
+                      }
+                    }
+                  }
                 }
               }
             }
@@ -1123,7 +1277,7 @@
               "application/json": {
                 "schema": {
                   "type": "object",
-                  "description": "Varies by tool"
+                  "additionalProperties": true
                 }
               }
             }
@@ -1214,7 +1368,7 @@
               "application/json": {
                 "schema": {
                   "type": "object",
-                  "description": "Varies by tool"
+                  "additionalProperties": true
                 }
               }
             }
@@ -1305,7 +1459,7 @@
               "application/json": {
                 "schema": {
                   "type": "object",
-                  "description": "Varies by tool"
+                  "additionalProperties": true
                 }
               }
             }
@@ -1366,7 +1520,7 @@
               "application/json": {
                 "schema": {
                   "type": "object",
-                  "description": "Varies by tool"
+                  "additionalProperties": true
                 }
               }
             }
@@ -1427,7 +1581,7 @@
               "application/json": {
                 "schema": {
                   "type": "object",
-                  "description": "Varies by tool"
+                  "additionalProperties": true
                 }
               }
             }
@@ -1498,7 +1652,7 @@
               "application/json": {
                 "schema": {
                   "type": "object",
-                  "description": "Varies by tool"
+                  "additionalProperties": true
                 }
               }
             }
@@ -1559,7 +1713,7 @@
               "application/json": {
                 "schema": {
                   "type": "object",
-                  "description": "Varies by tool"
+                  "additionalProperties": true
                 }
               }
             }
@@ -1620,7 +1774,7 @@
               "application/json": {
                 "schema": {
                   "type": "object",
-                  "description": "Varies by tool"
+                  "additionalProperties": true
                 }
               }
             }
@@ -1681,7 +1835,40 @@
               "application/json": {
                 "schema": {
                   "type": "object",
-                  "description": "Varies by tool"
+                  "properties": {
+                    "c": {
+                      "type": "number",
+                      "description": "Current price"
+                    },
+                    "d": {
+                      "type": "number",
+                      "description": "Change"
+                    },
+                    "dp": {
+                      "type": "number",
+                      "description": "Percent change"
+                    },
+                    "h": {
+                      "type": "number",
+                      "description": "High price of the day"
+                    },
+                    "l": {
+                      "type": "number",
+                      "description": "Low price of the day"
+                    },
+                    "o": {
+                      "type": "number",
+                      "description": "Open price of the day"
+                    },
+                    "pc": {
+                      "type": "number",
+                      "description": "Previous close price"
+                    },
+                    "t": {
+                      "type": "integer",
+                      "description": "Timestamp"
+                    }
+                  }
                 }
               }
             }
@@ -1741,8 +1928,11 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
-                  "description": "Varies by tool"
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "additionalProperties": true
+                  }
                 }
               }
             }
@@ -1803,7 +1993,7 @@
             "name": "forms",
             "in": "query",
             "required": false,
-            "description": "Form types to filter (e.g. ['10-K', '10-Q', '8-K'])",
+            "description": "Form types to filter (e.g. ['10-K', '10-Q', '8-K']) (comma-separated list)",
             "schema": {
               "type": "string",
               "description": "Form types to filter (e.g. ['10-K', '10-Q', '8-K']) (comma-separated list)"
@@ -1813,7 +2003,7 @@
             "name": "tickers",
             "in": "query",
             "required": false,
-            "description": "Company tickers to filter (e.g. ['AAPL', 'MSFT'])",
+            "description": "Company tickers to filter (e.g. ['AAPL', 'MSFT']) (comma-separated list)",
             "schema": {
               "type": "string",
               "description": "Company tickers to filter (e.g. ['AAPL', 'MSFT']) (comma-separated list)"
@@ -1842,8 +2032,11 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
-                  "description": "Varies by tool"
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "additionalProperties": true
+                  }
                 }
               }
             }
@@ -1904,7 +2097,7 @@
             "name": "forms",
             "in": "query",
             "required": false,
-            "description": "Form types to filter (e.g. ['10-K', '10-Q', '8-K'])",
+            "description": "Form types to filter (e.g. ['10-K', '10-Q', '8-K']) (comma-separated list)",
             "schema": {
               "type": "string",
               "description": "Form types to filter (e.g. ['10-K', '10-Q', '8-K']) (comma-separated list)"
@@ -1914,7 +2107,7 @@
             "name": "tickers",
             "in": "query",
             "required": false,
-            "description": "Company tickers to filter (e.g. ['AAPL', 'MSFT'])",
+            "description": "Company tickers to filter (e.g. ['AAPL', 'MSFT']) (comma-separated list)",
             "schema": {
               "type": "string",
               "description": "Company tickers to filter (e.g. ['AAPL', 'MSFT']) (comma-separated list)"
@@ -1943,8 +2136,11 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
-                  "description": "Varies by tool"
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "additionalProperties": true
+                  }
                 }
               }
             }
@@ -1995,7 +2191,7 @@
             "name": "forms",
             "in": "query",
             "required": false,
-            "description": "Form types (e.g. ['10-K', '10-Q']). Default: all.",
+            "description": "Form types (e.g. ['10-K', '10-Q']). Default: all. (comma-separated list)",
             "schema": {
               "type": "string",
               "description": "Form types (e.g. ['10-K', '10-Q']). Default: all. (comma-separated list)"
@@ -2024,8 +2220,11 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
-                  "description": "Varies by tool"
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "additionalProperties": true
+                  }
                 }
               }
             }
@@ -2085,8 +2284,11 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
-                  "description": "Varies by tool"
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "additionalProperties": true
+                  }
                 }
               }
             }
@@ -2156,8 +2358,11 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
-                  "description": "Varies by tool"
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "additionalProperties": true
+                  }
                 }
               }
             }
@@ -2227,8 +2432,11 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
-                  "description": "Varies by tool"
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "additionalProperties": true
+                  }
                 }
               }
             }
@@ -2299,7 +2507,7 @@
               "application/json": {
                 "schema": {
                   "type": "object",
-                  "description": "Varies by tool"
+                  "additionalProperties": true
                 }
               }
             }
@@ -2420,7 +2628,7 @@
               "application/json": {
                 "schema": {
                   "type": "object",
-                  "description": "Varies by tool"
+                  "additionalProperties": true
                 }
               }
             }
@@ -2481,7 +2689,7 @@
               "application/json": {
                 "schema": {
                   "type": "object",
-                  "description": "Varies by tool"
+                  "additionalProperties": true
                 }
               }
             }
@@ -2572,7 +2780,7 @@
               "application/json": {
                 "schema": {
                   "type": "object",
-                  "description": "Varies by tool"
+                  "additionalProperties": true
                 }
               }
             }
@@ -2643,7 +2851,7 @@
               "application/json": {
                 "schema": {
                   "type": "object",
-                  "description": "Varies by tool"
+                  "additionalProperties": true
                 }
               }
             }
@@ -2714,7 +2922,7 @@
               "application/json": {
                 "schema": {
                   "type": "object",
-                  "description": "Varies by tool"
+                  "additionalProperties": true
                 }
               }
             }
@@ -2884,8 +3092,11 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
-                  "description": "Varies by tool"
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "additionalProperties": true
+                  }
                 }
               }
             }
@@ -2955,8 +3166,11 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
-                  "description": "Varies by tool"
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "additionalProperties": true
+                  }
                 }
               }
             }
@@ -3016,8 +3230,11 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
-                  "description": "Varies by tool"
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "additionalProperties": true
+                  }
                 }
               }
             }
@@ -3137,8 +3354,11 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
-                  "description": "Varies by tool"
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "additionalProperties": true
+                  }
                 }
               }
             }
@@ -3759,6 +3979,77 @@
         ]
       }
     },
+    "/reddit/watchlist-scan": {
+      "get": {
+        "summary": "Batch Reddit sentiment scan for a list of stock tickers in a single pass",
+        "description": "Batch Reddit sentiment scan for a list of stock tickers in a single pass. Combines the tickers into one OR query per subreddit (r/wallstreetbets, r/stocks, r/investing, r/options), costing ceil(symbols/20)×4 requests instead of one call per ticker — prefer this over calling reddit_mentions or reddit_sentiment for each symbol in a watchlist. Returns, per ticker: mention count, bullish/bearish/neutral sentiment breakdown with an average score, the top post by upvotes, and a 'hot' flag (true when a ticker has 5 or more mentions in the period). Limitations: keyword-based scoring, not NLP (sarcasm/context may be missed); sentiment is scored per-post, not per-ticker, so a multi-ticker post applies the same score to each matched symbol; symbols that collide with common English words/finance acronyms (e.g. REAL, OPEN, HOLD, SELL) or fall outside 2–5 uppercase characters may report zero mentions even when discussed; and because each subreddit's combined query shares one 100-post cap, heavily-discussed tickers in a large batch can crowd out quieter ones, so counts may run lower than a single-ticker reddit_mentions query. Results cached for 5 minutes.",
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "description": "Varies by tool"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid parameters",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Tool not found or API key missing",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal server error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        },
+        "parameters": [
+          {
+            "name": "symbols",
+            "in": "query",
+            "required": true,
+            "description": "Watchlist stock tickers to scan, e.g. ['AAPL', 'NVDA', 'TSLA'] (1–50 symbols) (comma-separated list)",
+            "schema": {
+              "type": "string",
+              "description": "Watchlist stock tickers to scan, e.g. ['AAPL', 'NVDA', 'TSLA'] (1–50 symbols) (comma-separated list)"
+            }
+          },
+          {
+            "name": "period",
+            "in": "query",
+            "required": false,
+            "description": "Time window to search Reddit posts (default: day)",
+            "schema": {
+              "type": "string",
+              "description": "Time window to search Reddit posts (default: day)"
+            }
+          }
+        ]
+      }
+    },
     "/workspace/profile": {
       "get": {
         "summary": "Get the current user's trading profile and workspace settings",
@@ -3770,7 +4061,7 @@
               "application/json": {
                 "schema": {
                   "type": "object",
-                  "description": "Varies by tool"
+                  "additionalProperties": true
                 }
               }
             }
@@ -3818,7 +4109,7 @@
               "application/json": {
                 "schema": {
                   "type": "object",
-                  "description": "Varies by tool"
+                  "additionalProperties": true
                 }
               }
             }
@@ -3896,7 +4187,7 @@
               "application/json": {
                 "schema": {
                   "type": "object",
-                  "description": "Varies by tool"
+                  "additionalProperties": true
                 }
               }
             }
@@ -3944,7 +4235,7 @@
               "application/json": {
                 "schema": {
                   "type": "object",
-                  "description": "Varies by tool"
+                  "additionalProperties": true
                 }
               }
             }
@@ -4013,7 +4304,7 @@
               "application/json": {
                 "schema": {
                   "type": "object",
-                  "description": "Varies by tool"
+                  "additionalProperties": true
                 }
               }
             }
@@ -4091,7 +4382,7 @@
               "application/json": {
                 "schema": {
                   "type": "object",
-                  "description": "Varies by tool"
+                  "additionalProperties": true
                 }
               }
             }
@@ -4150,7 +4441,7 @@
               "application/json": {
                 "schema": {
                   "type": "object",
-                  "description": "Varies by tool"
+                  "additionalProperties": true
                 }
               }
             }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "stock-scanner-mcp",
   "mcpName": "io.github.yyordanov-tradu/stock-scanner-mcp",
-  "version": "1.16.3",
+  "version": "1.17.0",
   "description": "MCP server providing Claude Code with real-time stock and crypto market data, SEC filings, insider trades, and technical analysis",
   "type": "module",
   "bin": {
@@ -80,18 +80,18 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
     "proper-lockfile": "^4.1.2",
-    "zod": "^4.3.6"
+    "zod": "^4.3.6",
+    "zod-to-json-schema": "^3.25.2"
   },
   "devDependencies": {
     "@emnapi/core": "^1.9.2",
     "@emnapi/runtime": "^1.9.2",
-    "@emnapi/wasi-threads": "^1.2.1",
+    "@emnapi/wasi-threads": "^2.0.0",
     "@types/node": "^25.5.0",
     "@types/proper-lockfile": "^4.1.4",
     "tsup": "^8.0.0",
     "tsx": "^4.21.0",
     "typescript": "^6.0.2",
-    "vitest": "^4.1.1",
-    "zod-to-json-schema": "^3.25.2"
+    "vitest": "^4.1.1"
   }
 }