T-Invest MCP Server

Instructions

Implementation Reference

• src/tools/get-dividends.ts:20-74 (handler)

  The handler function that executes the logic for fetching dividends, processing tickers, and formatting the response.

  async ({ tickers, from, to }) => {
    try {
      const instrumentMap = await resolveTickersToInstruments(client, tickers);
      const notFound = tickers.filter((t) => !instrumentMap.has(t.toUpperCase()));
      const results: string[] = [];
  
      await Promise.allSettled(
        tickers
          .filter((t) => instrumentMap.has(t.toUpperCase()))
          .map(async (ticker) => {
            const instrument = instrumentMap.get(ticker.toUpperCase())!;
            const body: Record<string, unknown> = { figi: instrument.figi };
            if (from) body.from = from;
            if (to) body.to = to;
  
            try {
              const resp = await client.post<GetDividendsResponse>(
                API_PATHS.INSTRUMENTS.GET_DIVIDENDS,
                body,
              );
  
              if (!resp.dividends || resp.dividends.length === 0) {
                results.push(`${ticker}: дивиденды не найдены`);
                return;
              }
  
              const divLines = resp.dividends.map((d) => {
                const parts = [`  Дата отсечки: ${formatDate(d.lastBuyDate)}`];
                if (d.paymentDate) parts.push(`  Дата выплаты: ${formatDate(d.paymentDate)}`);
                if (d.dividendNet) parts.push(`  Размер: ${formatMoney(d.dividendNet)}`);
                if (d.yieldValue) parts.push(`  Доходность: ${quotationToNumber(d.yieldValue).toFixed(2)}%`);
                if (d.dividendType) parts.push(`  Тип: ${d.dividendType}`);
                return parts.join('\n');
              });
  
              results.push(`${ticker}:\n${divLines.join('\n\n')}`);
            } catch {
              results.push(`${ticker}: ошибка запроса`);
            }
          }),
      );
  
      if (notFound.length > 0) {
        results.push(`\nНе найдены: ${notFound.join(', ')}`);
      }
  
      const text = results.length > 0 ? results.join(SEPARATOR) : 'Данные не найдены.';
      return { content: [{ type: 'text' as const, text }] };
    } catch (error) {
      return {
        content: [{ type: 'text' as const, text: `Ошибка: ${error instanceof Error ? error.message : String(error)}` }],
        isError: true,
      };
    }
  },

• src/tools/get-dividends.ts:10-76 (registration)

  Registration of the 'get_dividends' tool using the MCP server instance.

  export function registerGetDividends(server: McpServer, client: TInvestClient): void {
    server.tool(
      'get_dividends',
      'Получить дивидендные выплаты по тикерам из Т-Инвестиций',
      {
        tickers: z.array(z.string()).min(1).max(50).describe('Массив тикеров (до 50)'),
        from: z.string().optional().describe('Начало периода (ISO 8601, например 2024-01-01T00:00:00Z)'),
        to: z.string().optional().describe('Конец периода (ISO 8601)'),
      },
      READ_ONLY,
      async ({ tickers, from, to }) => {
        try {
          const instrumentMap = await resolveTickersToInstruments(client, tickers);
          const notFound = tickers.filter((t) => !instrumentMap.has(t.toUpperCase()));
          const results: string[] = [];
  
          await Promise.allSettled(
            tickers
              .filter((t) => instrumentMap.has(t.toUpperCase()))
              .map(async (ticker) => {
                const instrument = instrumentMap.get(ticker.toUpperCase())!;
                const body: Record<string, unknown> = { figi: instrument.figi };
                if (from) body.from = from;
                if (to) body.to = to;
  
                try {
                  const resp = await client.post<GetDividendsResponse>(
                    API_PATHS.INSTRUMENTS.GET_DIVIDENDS,
                    body,
                  );
  
                  if (!resp.dividends || resp.dividends.length === 0) {
                    results.push(`${ticker}: дивиденды не найдены`);
                    return;
                  }
  
                  const divLines = resp.dividends.map((d) => {
                    const parts = [`  Дата отсечки: ${formatDate(d.lastBuyDate)}`];
                    if (d.paymentDate) parts.push(`  Дата выплаты: ${formatDate(d.paymentDate)}`);
                    if (d.dividendNet) parts.push(`  Размер: ${formatMoney(d.dividendNet)}`);
                    if (d.yieldValue) parts.push(`  Доходность: ${quotationToNumber(d.yieldValue).toFixed(2)}%`);
                    if (d.dividendType) parts.push(`  Тип: ${d.dividendType}`);
                    return parts.join('\n');
                  });
  
                  results.push(`${ticker}:\n${divLines.join('\n\n')}`);
                } catch {
                  results.push(`${ticker}: ошибка запроса`);
                }
              }),
          );
  
          if (notFound.length > 0) {
            results.push(`\nНе найдены: ${notFound.join(', ')}`);
          }
  
          const text = results.length > 0 ? results.join(SEPARATOR) : 'Данные не найдены.';
          return { content: [{ type: 'text' as const, text }] };
        } catch (error) {
          return {
            content: [{ type: 'text' as const, text: `Ошибка: ${error instanceof Error ? error.message : String(error)}` }],
            isError: true,
          };
        }
      },
    );
  }

• src/tools/get-dividends.ts:14-18 (schema)

  Input validation schema using Zod for the 'get_dividends' tool.

  {
    tickers: z.array(z.string()).min(1).max(50).describe('Массив тикеров (до 50)'),
    from: z.string().optional().describe('Начало периода (ISO 8601, например 2024-01-01T00:00:00Z)'),
    to: z.string().optional().describe('Конец периода (ISO 8601)'),
  },