search_setups

Instructions

Implementation Reference

• src/tools/composite.ts:302-374 (handler)

  The main handler function for the search_setups tool. It parses input (side, limit), fetches options flow signals, filters by side and latest date, scores each signal based on strength, streak bonus, and premium size, sorts descending, and returns the top N ranked setups.

  export async function handleSearchSetups(
    ctx: McpContext,
    rawArgs: unknown
  ): Promise<unknown> {
    const args = SearchSetupsInputSchema.parse(rawArgs);
    const side = args.side ?? "bullish";
    const limit = args.limit ?? 20;
  
    // Pull today's signals (all sides)
    const signalsRes = await safeCall(() =>
      ctx.cache.wrap("options-flow:signals:default", 300_000, () =>
        ctx.apiClient.get<{ signals?: SignalRow[] }>("/options-flow/signals")
      )
    );
  
    if ("error" in signalsRes) {
      throw new McpError(
        `Could not load signals: ${signalsRes.error}`,
        (signalsRes as { code?: string }).code === "TIER_UPGRADE_REQUIRED"
          ? "TIER_UPGRADE_REQUIRED"
          : "UPSTREAM_ERROR",
        "search_setups"
      );
    }
  
    const allSignals = (signalsRes as { signals?: SignalRow[] }).signals || [];
    if (allSignals.length === 0) {
      return { side, date: null, count: 0, setups: [], note: "No signals available yet." };
    }
  
    // Get the most recent signal date
    const latestDate = allSignals
      .map((s) => (s.signal_date || "").slice(0, 10))
      .sort()
      .pop() || "";
    const todaysSignals = allSignals.filter(
      (s) => (s.signal_date || "").slice(0, 10) === latestDate && s.side === side
    );
  
    if (todaysSignals.length === 0) {
      return { side, date: latestDate, count: 0, setups: [] };
    }
  
    // Score each signal
    const setups = todaysSignals.map((s) => {
      const strength = s.strength_score || 0;
      const streakBonus = (s.consecutive_days || 0) >= 5 ? 1 : 0;
      const premiumBonus = toNum(s.total_premium) >= 10_000_000 ? 0.5 : 0;
      const score = strength + streakBonus + premiumBonus;
      return {
        symbol: s.symbol,
        score: Number(score.toFixed(1)),
        signal: {
          type: s.signal_type,
          strength: strength,
          consecutive_days: s.consecutive_days,
          call_put_ratio: s.call_put_ratio,
          total_premium: toNum(s.total_premium),
        },
      };
    });
  
    setups.sort((a, b) => b.score - a.score);
  
    return {
      side,
      date: latestDate,
      count: setups.length,
      setups: setups.slice(0, limit),
      note:
        "Scores combine signal strength, streak length, and premium size. This is a ranking hint, not financial advice.",
    };
  }

• src/tools/composite.ts:63-77 (schema)

  Zod schema defining input validation for search_setups: side ('bullish'|'bearish', default bullish) and limit (1-100, default 20).

  export const SearchSetupsInputSchema = z.object({
    side: z
      .enum(["bullish", "bearish"])
      .default("bullish")
      .optional()
      .describe("Side of setups to return"),
    limit: z
      .number()
      .int()
      .min(1)
      .max(100)
      .default(20)
      .optional()
      .describe("Max setups to return"),
  });

• src/tools/composite.ts:89-96 (registration)

  Tool metadata registration in the compositeTools array. Defines name 'search_setups', description, inputSchema (converted from Zod), and read-only annotations.

    {
      name: "search_setups",
      description:
        "Find the strongest trading setups today by combining options flow signals and screener confluence into a ranked list. Use when the user asks 'what should I trade today', 'best setups', 'top bullish plays'. Returns a ranked list with a composite score (signal strength + screener confluence + streak length). Present the top 3-5 to the user with narrative context, don't dump the raw JSON. Use get_stock_report if the user wants to dig deeper into any specific result. Returns { side, date, count, setups: [{symbol, score, signal, screeners_hit, ...}] }.",
      inputSchema: z.toJSONSchema(SearchSetupsInputSchema) as Tool["inputSchema"],
      annotations: READ_ONLY_ANNOTATIONS,
    },
  ];

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

  Handler mapping in the HANDLERS record: maps string 'search_setups' to handleSearchSetups function. This is where the tool name is bound to its implementation at runtime.

    search_setups: (ctx, args) => handleSearchSetups(ctx, args),
    get_market_momentum: (ctx, args) => handleGetMarketMomentum(ctx, args),
    get_trends: (ctx, args) => handleGetTrends(ctx, args),
    get_trend_connections: (ctx, args) => handleGetTrendConnections(ctx, args),
    explain_concept: (ctx, args) => handleExplainConcept(ctx, args),
  };

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

  Aggregation of ALL_TOOLS array which includes compositeTools (containing search_setups) along with all other tool definitions, registered with the MCP server.

  const ALL_TOOLS: Tool[] = [
    PING_TOOL,
    ...screenersTools,
    ...patternsTools,
    ...optionsFlowTools,
    ...stockTools,
    ...compositeTools,
    ...marketMomentumTools,
    ...trendsTools,
    ...educationTools,
  ];