get_market_summary

Instructions

Implementation Reference

• src/brvm_mcp/server.py:83-100 (handler)

  Tool registration and execution handler for get_market_summary. Decorated with @mcp.tool(), it checks cache first, then delegates to scraper.get_market_summary(), serializes the MarketSummary model to JSON, and caches the result.

  @mcp.tool()
  async def get_market_summary() -> str:
      """
      Get today's BRVM market summary including total volume, value traded,
      number of gainers/losers, and all index values.
  
      Returns a JSON object with the full trading session overview.
      """
      assert scraper and cache
  
      cached = cache.get("market_summary")
      if cached:
          return json.dumps(cached, ensure_ascii=False, indent=2)
  
      summary = await scraper.get_market_summary()
      data = summary.model_dump()
      cache.set("market_summary", data)
      return json.dumps(data, ensure_ascii=False, indent=2)

• src/brvm_mcp/models/__init__.py:58-68 (schema)

  Pydantic model MarketSummary defining the schema: date, total_volume, total_value, market_cap, gainers, losers, unchanged, and a list of IndexValue objects.

  class MarketSummary(BaseModel):
      """Aggregate BRVM trading session summary."""
  
      date: str = Field(..., description="Trading date")
      total_volume: int = Field(0, description="Total shares traded")
      total_value: float = Field(0.0, description="Total value traded in XOF")
      market_cap: float = Field(0.0, description="Total market capitalization in XOF")
      gainers: int = Field(0, description="Number of stocks that gained")
      losers: int = Field(0, description="Number of stocks that declined")
      unchanged: int = Field(0, description="Number of unchanged stocks")
      indices: list[IndexValue] = Field(default_factory=list)

• src/brvm_mcp/server.py:83-84 (registration)

  Registration via @mcp.tool() decorator on line 83, registering the function as an MCP tool named 'get_market_summary'.

  @mcp.tool()
  async def get_market_summary() -> str:

• src/brvm_mcp/scrapers/__init__.py:248-290 (helper)

  Scraper method get_market_summary() that scrapes the BRVM page, calls get_all_quotes() and get_indices(), computes gainers/losers/unchanged counts, parses market cap and total value, and returns a MarketSummary Pydantic model.

  async def get_market_summary(self) -> MarketSummary:
      """Build a full market summary from scraped data."""
      resp = await self._get_with_retry(f"{AFX_BASE}/")
      soup = BeautifulSoup(resp.text, "lxml")
  
      quotes = await self.get_all_quotes()
      indices = await self.get_indices()
  
      gainers = [q for q in quotes if q.change_pct > 0]
      losers = [q for q in quotes if q.change_pct < 0]
      unchanged = [q for q in quotes if q.change_pct == 0]
  
      # Parse market cap from the summary table ("XOF 15.51Tr")
      market_cap = 0.0
      for table in soup.find_all("table"):
          th = table.find("th")
          if th and "BRVM-CI" in th.get_text():
              cells = table.find_all("td")
              if len(cells) >= 3:
                  cap_text = cells[2].get_text(strip=True)
                  cap_m = re.search(r"([\d.,]+)\s*Tr", cap_text)
                  if cap_m:
                      market_cap = self._parse_number(cap_m.group(1)) * 1e12
              break
  
      # Parse total volume/value from trading summary paragraph
      full_text = soup.get_text()
      total_volume = sum(q.volume for q in quotes)
      total_value = 0.0
      val_m = re.search(r"XOF\s*([\d,. ]+)", full_text)
      if val_m:
          total_value = self._parse_number(val_m.group(1))
  
      return MarketSummary(
          date=datetime.now().strftime("%Y-%m-%d"),
          total_volume=total_volume,
          total_value=total_value,
          market_cap=market_cap,
          gainers=len(gainers),
          losers=len(losers),
          unchanged=len(unchanged),
          indices=indices,
      )