Status Invest MCP Server

Instructions

Implementation Reference

• src/interface/controllers/StatusInvestToolsController.ts:119-208 (handler)

  Primary MCP tool implementation for 'analise-carteira': registers the tool with Zod input schema, handles arguments, fetches stock resume and indicators using parallel Promise.all, constructs and returns formatted portfolio data as JSON text content, with error handling.
  private registerPortfolioAnalysisToolHandler(): void { this.server.tool( 'analise-carteira', 'Análise completa de carteira com rebalanceamento multifatorial', { stocks: z .array(z.string()) .describe('Array of stock symbols (e.g., ["BBAS3", "ITUB3"])'), totalAmount: z .number() .describe('Total amount available to invest in BRL'), orderCost: z.number().describe('Cost per order in BRL'), strategy: z .string() .optional() .describe( 'Investment strategy (buy-and-hold, dividend-focused, etc.)', ), }, async (args) => { try { const { stocks, totalAmount, orderCost, strategy = 'buy-and-hold', } = args; const stocksArray: string[] = Array.isArray(stocks) ? stocks : typeof stocks === 'string' ? [stocks] : []; const [basicInfo, indicators] = await Promise.all([ this.service.getStockResume(stocksArray), this.service.getStockIndicators(stocksArray), ]); const portfolioData = { strategy, totalAmount, orderCost, stocks: stocks.map((_ticker: string, index: number) => { const stock = indicators[index]; const basic = basicInfo[index]; return { ticker: stock.stock, name: basic.name, price: basic.price, data: stock, }; }), basicInfo, indicators, timestamp: new Date().toISOString(), }; return { content: [ { type: 'text', text: JSON.stringify(portfolioData, null, 2), }, ], }; } catch (error) { console.error('Portfolio analysis error:', error); return { content: [ { type: 'text', text: JSON.stringify( { error: error instanceof Error ? error.message : 'Unknown error occurred during portfolio analysis', timestamp: new Date().toISOString(), }, null, 2, ), }, ], }; } }, ); }
• src/application/services/StatusInvestService.ts:17-43 (helper)

  Supporting helper: Retrieves basic resume information (price, variation, etc.) for a list of stocks by calling the API service and formatting the response.
  async getStockResume(stocks: string[]) { const data = []; for (const stock of stocks) { const stockData = await this.apiService.getStockResume(stock); if (stockData && stockData?.length > 0) { for (const item of stockData) { let type = TypeEnum[item.type]; if (!type) { type = `${item.type} unknown`; } const jsonData = { id: item.id, type, code: item.code, name: item.name, price: item.price, variation: item.variation, variationUp: item.variationUp, url: item.url, image: `https://statusinvest.com.br/img/company/avatar/${item.parentId}.jpg?v=214`, }; data.push(jsonData); } } } return data; }
• src/application/services/StatusInvestService.ts:45-89 (helper)

  Supporting helper: Fetches detailed indicators and resume data for stocks by scraping HTML response with Cheerio, extracting key metrics like price, 52-week highs/lows, valuations, and all indicator sections.
  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; }