get_top_movers

Instructions

Implementation Reference

• src/brvm_mcp/server.py:152-175 (handler)

  MCP tool handler for get_top_movers. Decorated with @mcp.tool(), it accepts an optional 'n' parameter (default 5, max 10), checks cache, delegates to scraper.get_top_movers(), and returns JSON with 'gainers' and 'losers' arrays.

  @mcp.tool()
  async def get_top_movers(n: int = 5) -> str:
      """
      Get today's top gaining and losing stocks on the BRVM.
  
      Args:
          n: Number of stocks to return per category (default 5, max 10).
  
      Returns a JSON object with 'gainers' and 'losers' arrays.
      """
      assert scraper and cache
      n = min(max(n, 1), 10)
  
      cached = cache.get(f"top_movers:{n}")
      if cached:
          return json.dumps(cached, ensure_ascii=False, indent=2)
  
      movers = await scraper.get_top_movers(n=n)
      data = {
          "gainers": [m.model_dump() for m in movers["gainers"]],
          "losers": [m.model_dump() for m in movers["losers"]],
      }
      cache.set(f"top_movers:{n}", data)
      return json.dumps(data, ensure_ascii=False, indent=2)

• src/brvm_mcp/scrapers/__init__.py:294-314 (helper)

  Core scraping logic: fetches all quotes via get_all_quotes(), filters active stocks (volume > 0), sorts by change_pct descending for gainers and ascending for losers, maps to TopMover objects, and returns a dict with 'gainers' and 'losers' lists.

  async def get_top_movers(self, n: int = 5) -> dict[str, list[TopMover]]:
      """Get top N gainers and losers."""
      quotes = await self.get_all_quotes()
      active = [q for q in quotes if q.volume > 0]
  
      sorted_up = sorted(active, key=lambda q: q.change_pct, reverse=True)
      sorted_down = sorted(active, key=lambda q: q.change_pct)
  
      def to_mover(q: StockQuote) -> TopMover:
          return TopMover(
              ticker=q.ticker,
              name=q.name,
              price=q.price,
              change_pct=q.change_pct,
              volume=q.volume,
          )
  
      return {
          "gainers": [to_mover(q) for q in sorted_up[:n]],
          "losers": [to_mover(q) for q in sorted_down[:n] if q.change_pct < 0],
      }

• src/brvm_mcp/models/__init__.py:71-78 (schema)

  Pydantic model TopMover with fields: ticker (str), name (str), price (float), change_pct (float), volume (int). Used for serialization of top gainer/loser stocks.

  class TopMover(BaseModel):
      """A stock appearing in top gainers or top losers."""
  
      ticker: str
      name: str
      price: float
      change_pct: float
      volume: int

• src/brvm_mcp/server.py:69-77 (registration)

  FastMCP server instance creation; the @mcp.tool() decorator on line 152 registers get_top_movers as an MCP tool.

  mcp = FastMCP(
      "BRVM Market Data",
      instructions=(
          "Live market data from the BRVM (Bourse Régionale des Valeurs Mobilières), "
          "the regional stock exchange of 8 West African UEMOA member states. "
          "Provides stock quotes, index values, top movers, company info, and market summaries."
      ),
      lifespan=lifespan,
  )