Status Invest MCP Server

Instructions

Implementation Reference

• src/interface/controllers/StatusInvestToolsController.ts:49-73 (registration)

  Registers the 'get-indicadores' MCP tool, including input schema (stocks array) and thin handler that delegates to StatusInvestService.getStockIndicators and returns JSON.
  private registerGetIndicatorsToolHandler(): void { this.server.tool( 'get-indicadores', 'Buscar informações de indicadores de ações', { stocks: z.array(z.string()).describe('Array of stock symbols'), }, async (args) => { const stocks: string[] = Array.isArray(args.stocks) ? args.stocks : [args.stocks]; const infos = await this.service.getStockIndicators(stocks); return { content: [ { type: 'text', text: JSON.stringify(infos, null, 2), }, ], }; }, ); }
• src/application/services/StatusInvestService.ts:45-89 (handler)

  Core handler implementation: loops over stocks, fetches HTML via API service, parses key resume metrics and all indicators, structures the output.
  async getStockIndicators(stocks: string[]) { const baseUrl = this.apiService.getUrlBase(); const stockData = []; for (const stock of stocks) { const response = await this.apiService.getIndicators(stock); if (!response) continue; const resume = this.getResume(response); const indicators = this.getAllIndicators(response); const data = { stock: stock, url: `${baseUrl}/acoes/${stock.toLowerCase()}`, resume: { price: { value: resume.price.value, variation: resume.price.variation, }, min52weeks: { value: resume.min52Weeks.value, }, max52weeks: { value: resume.max52Weeks.value, }, minMonth: { value: resume.minMonth.value, }, maxMonth: { value: resume.maxMonth.value, }, valuation12Months: { value: resume.valuation12Months.value, }, valuationCurrentMonth: { value: resume.valuationCurrentMonth.value, }, }, indicators, }; stockData.push(data); } return stockData; }
• src/application/services/StatusInvestService.ts:114-216 (helper)

  Helper to parse resume metrics (price, variations, 52-week min/max, monthly min/max, 12-month and current month valuations) from HTML using Cheerio.
  private getResume(html: string) { const $ = cheerio.load(html); const priceText = $('div[title="Valor atual do ativo"] strong.value') .text() .trim(); const price = parseFloat( priceText.replace('R$', '').replace('.', '').replace(',', '.'), ); const variationText = $( 'span[title="Variação do valor do ativo com base no dia anterior"] b', ) .text() .trim(); const variation = parseFloat( variationText.replace('%', '').replace(',', '.'), ); const min52weeksText = $( 'div[title="Valor mínimo das últimas 52 semanas"] strong.value', ) .text() .trim(); const min52weeks = parseFloat( min52weeksText.replace('R$', '').replace('.', '').replace(',', '.'), ); const max52weeksText = $( 'div[title="Valor máximo das últimas 52 semanas"] strong.value', ) .text() .trim(); const max52weeks = parseFloat( max52weeksText.replace('R$', '').replace('.', '').replace(',', '.'), ); const minMonthText = $( 'div[title="Valor mínimo do mês atual"] span.sub-value', ) .text() .trim(); const minMonth = parseFloat( minMonthText.replace('R$', '').replace('.', '').replace(',', '.'), ); const maxMonthText = $( 'div[title="Valor máximo do mês atual"] span.sub-value', ) .text() .trim(); const maxMonth = parseFloat( maxMonthText.replace('R$', '').replace('.', '').replace(',', '.'), ); const valuation12MonthsText = $( 'div[title="Valorização no preço do ativo com base nos últimos 12 meses"] strong.value', ) .text() .trim(); const valuation12Months = parseFloat( valuation12MonthsText .replace('R$', '') .replace('.', '') .replace(',', '.'), ); const valuationCurrentMonthText = $( 'div[title="Valorização no preço do ativo com base no mês atual"] span.sub-value b', ) .text() .trim(); const valuationCurrentMonth = parseFloat( valuationCurrentMonthText.replace('%', '').replace(',', '.'), ); return { price: { value: price, variation, }, min52Weeks: { value: min52weeks, }, max52Weeks: { value: max52weeks, }, minMonth: { value: minMonth, }, maxMonth: { value: maxMonth, }, valuation12Months: { value: valuation12Months, }, valuationCurrentMonth: { value: valuationCurrentMonth, }, }; }
• src/application/services/StatusInvestService.ts:218-254 (helper)

  Helper to extract all dynamic indicator sections from the stock page HTML using Cheerio, parsing titles and numeric values.
  private getAllIndicators(html: string) { const $ = cheerio.load(html); const indicatorContainer = $( 'div.indicator-today-container > div > div.indicators', ); if (indicatorContainer.length === 0) { return []; } if (indicatorContainer.length > 0) { const valuationIndicators = indicatorContainer.map((_, element) => { const title = $(element).find('strong.uppercase').text().trim(); const indicatorsSection = $(element).find('.item'); const values = indicatorsSection .map((_, item) => { const title = $(item).find('.title').text().trim(); const value = $(item).find('.value').text().trim(); return { title, value: parseFloat(value.replace(',', '.')), }; }) .get(); return { title: voca.camelCase(title), values, }; }); return valuationIndicators.toArray(); } }
• src/infrastructure/services/StatusInvestApiService.ts:61-67 (helper)

  Fetches the raw HTML content of the stock indicators page from statusinvest.com.br.
  async getIndicators(stock: string): Promise<string | null> { const data = await this.makeTextRequest<string>( `/acoes/${stock.toLowerCase()}`, ); if (!data) return null; return data; }