Status Invest MCP Server

Instructions

Implementation Reference

• src/interface/controllers/StatusInvestToolsController.ts:75-117 (registration)

  Registers the MCP tool 'get-acoes-datas-pagamento' including input validation schema (Zod) and thin handler delegating to service
  private registerGetStockPaymentDatesToolHandler(): void { this.server.tool( 'get-acoes-datas-pagamento', 'Buscar datas de pagamento de ações', { initialDate: z .string() .refine((date) => dayjs(date, 'YYYY-MM-DD', true).isValid(), { message: 'Data inicial inválida. Formato esperado: YYYY-MM-DD', }) .describe('Data inicial'), finalDate: z .string() .refine((date) => dayjs(date, 'YYYY-MM-DD', true).isValid(), { message: 'Data final inválida. Formato esperado: YYYY-MM-DD', }) .describe('Data final'), stocks: z .array( z.string().regex(/^[A-Z]{4}(3|4|11)$/, { message: 'Código de ação inválido. Deve seguir o padrão: 4 letras + 3, 4 ou 11.', }), ) .optional() .describe('Ação'), }, async (args) => { const paymentDatesInput = args as GetPaymentDatesInput; const infos = await this.service.getStockPaymentDates(paymentDatesInput); return { content: [ { type: 'text', text: JSON.stringify(infos, null, 2), }, ], }; }, ); }
• src/domain/models/StatusInvestServiceModel.ts:1-16 (schema)

  TypeScript interfaces for input and output of getStockPaymentDates
  export interface GetPaymentDatesInput { initialDate: string; finalDate: string; stocks?: string[]; } export interface GetPaymentDatesOutput { code: string; companyName: string; price: number; dateCom: string; paymentDate: string; type: string; dy: string; url: string; }
• src/application/services/StatusInvestService.ts:91-112 (handler)

  Main handler logic in application service: supports multiple stocks, delegates per stock to private getDatesPayment
  async getStockPaymentDates(paymentDatesInput: GetPaymentDatesInput) { const { initialDate, finalDate, stocks } = paymentDatesInput; if (!stocks || stocks.length === 0) { const response = await this.getDatesPayment(initialDate, finalDate); return response; } const data = []; for (const stock of stocks) { const response = await this.getDatesPayment( initialDate, finalDate, stock.toUpperCase(), ); if (response && response.length > 0) { data.push(...response); } } return data; }
• src/application/services/StatusInvestService.ts:256-292 (helper)

  Private helper that fetches raw data from API service and formats into output structure (date parsing, price parsing, URL construction)
  private async getDatesPayment( initialDate: string, finalDate: string, stock?: string, ): Promise<GetPaymentDatesOutput[]> { const baseUrl = this.apiService.getUrlBase(); const paymentDatesInput = { initialDate, finalDate, stock, }; const paymentDate = await this.apiService.getStockPaymentDates(paymentDatesInput); const datePayments = paymentDate?.datePayment; if (!datePayments || datePayments.length === 0) { return []; } const data = datePayments.map((item) => { return { code: item.code, companyName: item.companyName, price: parseFloat(item.resultAbsoluteValue.replace(',', '.')), dateCom: dayjs(item.dateCom, 'DD/MM/YYYY').format('YYYY-MM-DD'), paymentDate: dayjs(item.paymentDividend, 'DD/MM/YYYY').format( 'YYYY-MM-DD', ), type: item.earningType, dy: item.dy, url: `${baseUrl}${item.uRLClear}`, }; }); return data; }
• src/infrastructure/services/StatusInvestApiService.ts:69-81 (handler)

  Core API handler: constructs StatusInvest earnings endpoint URL and fetches JSON data
  async getStockPaymentDates( paymentDatesInput: GetPaymentDatesInput, ): Promise<GetEarnings | null> { const { initialDate, finalDate, stock } = paymentDatesInput; let url = `/acao/getearnings?IndiceCode=Ibovespa&Start=${initialDate}&End=${finalDate}`; if (stock) { url += `&Filter=${stock}`; } const data = await this.makeJsonRequest<GetEarnings>(url); if (!data) return null; return data; } }