stock-scanner-mcp 1.16.4 → 1.17.1

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
 
@@ -52,8 +52,19 @@ This gives you **46 tools** immediately with no API keys. API keys are optional
 
 Restart Claude Desktop after saving. Claude Code picks up the config automatically.
 
+> **Claude Code shortcut — install as a plugin instead of Steps 1 and 2.** If you use Claude Code, skip the manual config above and install everything with two commands:
+> ```
+> /plugin marketplace add yyordanov-tradu/stock-scanner-mcp
+> /plugin install stock-scanner@tradu-marketplace
+> ```
+> Run `/reload-plugins`, then `/mcp` — you should see the `stock-scanner` server listed as connected. The first launch runs `npx -y stock-scanner-mcp`, which downloads the package once (then it is cached). The plugin enables the workspace by default (data is stored in `~/.stock-scanner-mcp`) and passes the optional API keys (`FINNHUB_API_KEY`, `ALPHA_VANTAGE_API_KEY`, `FRED_API_KEY`) through from your environment; modules without a key are skipped automatically.
+>
+> **The plugin already bundles the skills — do NOT run Step 2.** All 19 skills ship with the plugin and load under the `stock-scanner:` namespace, e.g. `/stock-scanner:analyze-stock AAPL`, `/stock-scanner:morning-briefing`, `/stock-scanner:setup-market-workspace`. Running the Step 2 installer as well copies a second, unprefixed set into `~/.claude/skills/`, and the two collide — Step 2 is only for the manual (non-plugin) install. After installing, go straight to Step 3, using the namespaced command: `/stock-scanner:setup-market-workspace`.
+
 ### Step 2 — Install the trading skills
 
+> Skip this step if you installed via the plugin above — the plugin already bundles these skills (as `stock-scanner:<name>`). This step is only for the manual config in Step 1.
+
 Run this command in your terminal:
 
 ```bash
@@ -97,7 +108,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 +239,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 +249,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 +334,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 +428,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 +481,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.1",
     "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.1",
   "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",

package/skills/README.md

@@ -4,6 +4,8 @@ Ready-made trading workflows that orchestrate [stock-scanner-mcp](https://www.np
 
 ## Quick Start
 
+> **Installed the Claude Code plugin?** You already have these skills — the plugin bundles them and loads them under the `stock-scanner:` namespace (e.g. `/stock-scanner:morning-briefing`). Skip the installer below; it is only for the manual MCP-server setup.
+
 **Prerequisites:** stock-scanner-mcp configured as an MCP server in Claude Code.
 
 ```bash