stock-scanner-mcp 1.16.4 → 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
 
@@ -228,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 |
@@ -238,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)
 
@@ -323,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)
 
@@ -416,7 +417,7 @@ curl http://localhost:3200/openapi.json
 
 See [Sidecar HTTP API](https://github.com/yyordanov-tradu/stock-scanner-mcp/wiki/Sidecar-HTTP-API) for endpoint details.
 
-**64 tools** exposed as REST routes, including `/tradingview/quote`, `/options/chain`, `/workspace/profile`, and more.
+**65 tools** exposed as REST routes, including `/tradingview/quote`, `/options/chain`, `/workspace/profile`, and more.
 
 ## Rate Limits
 
@@ -469,7 +470,7 @@ 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)
 │   ├── routes.ts         # Declarative URL routing table

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" },

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.4",
+    "version": "1.17.0",
     "contact": {
       "name": "Yordan Yordanov",
       "url": "https://github.com/yyordanov-tradu/stock-scanner-mcp"
@@ -3979,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",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "stock-scanner-mcp",
   "mcpName": "io.github.yyordanov-tradu/stock-scanner-mcp",
-  "version": "1.16.4",
+  "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": {
@@ -86,7 +86,7 @@
   "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",