search_stocks_in_screeners

Instructions

Implementation Reference

• src/tools/screeners.ts:12-24 (schema)

  Input schema (SearchStocksInScreenersInputSchema) defining parameters: screener_slugs (1-24 strings), mode (intersection/union), and limit.

  export const SearchStocksInScreenersInputSchema = z.object({
    screener_slugs: z
      .array(z.string())
      .min(1)
      .max(24)
      .describe("List of screener slugs to query (1-24)"),
    mode: z
      .enum(["intersection", "union"])
      .default("intersection")
      .optional()
      .describe("intersection = stocks in ALL screeners; union = stocks in ANY screener"),
    limit: z.number().int().min(1).max(500).default(50).optional(),
  });

• src/tools/screeners.ts:41-47 (registration)

  Tool definition object with name 'search_stocks_in_screeners', description, and inputSchema.

  {
    name: "search_stocks_in_screeners",
    description:
      "Find stocks that appear in multiple screeners simultaneously. Powerful for high-confidence picks where the user wants confluence across strategies. Use when the user asks 'which stocks are in both X and Y' or 'find stocks in 3+ bullish screeners'. Returns { screeners_queried, mode, count, symbols: [{symbol, screeners, match_count}] }. Intersection mode returns only stocks in ALL listed screeners; union returns stocks in ANY.",
    inputSchema: z.toJSONSchema(SearchStocksInScreenersInputSchema) as Tool["inputSchema"],
    annotations: READ_ONLY_ANNOTATIONS,
  },

• src/tools/screeners.ts:67-125 (handler)

  The handler function handleSearchStocksInScreeners: parses args, fetches each screener in parallel (cached, up to 500 rows), builds a symbol->screeners map, filters by intersection/union mode, sorts by match_count, and returns { screeners_queried, mode, count, symbols }.

  export async function handleSearchStocksInScreeners(
    ctx: McpContext,
    rawArgs: unknown
  ): Promise<unknown> {
    const args = SearchStocksInScreenersInputSchema.parse(rawArgs);
    const mode = args.mode ?? "intersection";
    const limit = args.limit ?? 50;
  
    // Fetch each screener in parallel with cached reads
    const results = await Promise.all(
      args.screener_slugs.map(async (slug) => {
        try {
          const res = await ctx.cache.wrap(
            `screeners:${slug}:1:500`,
            300_000,
            () =>
              ctx.apiClient.get<{ data?: { symbol?: string }[] }>(`/screeners/${slug}`, { limit: 500 })
          );
          const symbols = new Set(
            (res.data || [])
              .map((r) => (r.symbol || "").toUpperCase())
              .filter(Boolean)
          );
          return { slug, symbols };
        } catch {
          return { slug, symbols: new Set<string>() };
        }
      })
    );
  
    // Build symbol → screeners map
    const symbolMap = new Map<string, string[]>();
    for (const { slug, symbols } of results) {
      for (const sym of symbols) {
        if (!symbolMap.has(sym)) symbolMap.set(sym, []);
        symbolMap.get(sym)!.push(slug);
      }
    }
  
    const combined = Array.from(symbolMap.entries())
      .map(([symbol, screeners]) => ({
        symbol,
        screeners,
        match_count: screeners.length,
      }))
      .filter((row) => {
        if (mode === "intersection") return row.match_count === args.screener_slugs.length;
        return row.match_count >= 1;
      })
      .sort((a, b) => b.match_count - a.match_count || a.symbol.localeCompare(b.symbol))
      .slice(0, limit);
  
    return {
      screeners_queried: args.screener_slugs,
      mode,
      count: combined.length,
      symbols: combined,
    };
  }

• src/tools/index.ts:17-18 (registration)

  Import of handleSearchStocksInScreeners from ./screeners.

    handleSearchStocksInScreeners,
  } from "./screeners";

• src/tools/index.ts:74-74 (registration)

  Handler mapping in the HANDLERS record, routing 'search_stocks_in_screeners' to handleSearchStocksInScreeners.

  search_stocks_in_screeners: (ctx, args) => handleSearchStocksInScreeners(ctx, args),