YNAB MCP Starter

Шаблон репозитория на TypeScript в стиле продакшена для MCP-сервера YNAB с доступом только для чтения.

Этот шаблон намеренно сделан компактным и понятным:

• Node.js 18+

• TypeScript со строгими настройками компилятора

• Валидация входных и выходных данных инструментов с помощью Zod

• Клиент YNAB API с доступом только для чтения, поддержкой повторных попыток и обработкой тайм-аутов

• Модульные тесты с имитацией ответов YNAB

• Четкие маркеры TODO там, где должно быть подключено транспортное соединение MCP

Что включено в этот репозиторий

src/
  clients/   YNAB API client, environment config, and error types
  schemas/   strict Zod schemas for tool contracts
  server/    MCP server composition and transport TODO placeholders
  tools/     read-only business logic for each YNAB capability
  types/     shared API and service types
tests/       unit tests with mocked API responses

Реализованы возможности только для чтения:

• список бюджетов

• список счетов

• список категорий

• список недавних транзакций

• поиск транзакций без категории

• ежемесячные расходы по категориям

Запись данных намеренно не реализована.

Related MCP server: MCP Server Starter

Настройка

1. Установите зависимости:

npm install

2. Скопируйте пример файла окружения:

cp .env.example .env

3. Укажите свой токен YNAB в .env:

YNAB_TOKEN=your-token-here

4. Запустите режим локальной разработки:

npm run dev

Скрипты

• npm run build компилирует TypeScript в dist/

• npm run dev запускает точку входа шаблона с отслеживанием изменений файлов

• npm run lint запускает ESLint

• npm run test запускает модульные тесты с помощью Vitest

• npm run typecheck запускает TypeScript в режиме без генерации файлов

Подключение MCP

Репозиторий включает уровень композиции сервера, но пока не привязывает вас к конкретному транспорту.

Ищите комментарии TODO в:

• src/server/index.ts

• src/server/registerTools.ts

Именно там вам следует:

1. Инициализировать MCP-сервер

2. Зарегистрировать определения инструментов и схемы

3. Подключить stdio, SSE или другой транспорт

4. Добавить структурированное логирование и операционные хуки

Заметки по безопасности

• Этот шаблон ожидает наличие персонального токена доступа YNAB_TOKEN в переменных окружения.

• Никогда не записывайте токен в исходный код, тесты, промпты или логи.

• Ограничьте использование токена только операциями чтения и обновляйте его в случае компрометации.

• Избегайте логирования необработанных ответов YNAB API в продакшене, так как они могут содержать примечания к транзакциям или другие конфиденциальные финансовые метаданные.

• Этот шаблон выполняет только GET-запросы к YNAB API. Конечные точки для записи не реализованы.

Заметки по проектированию

• Клиент YNAB централизует повторные попытки, обработку тайм-аутов и нормализацию ошибок.

• Модули инструментов изолированы от деталей HTTP и работают через небольшой сервисный интерфейс.

• Схемы Zod проверяют как входные, так и выходные данные инструментов, чтобы своевременно обнаруживать расхождения.

• Денежные суммы представлены как в миллиединицах YNAB, так и в удобных для чтения десятичных числах.

• Ежемесячные расходы по категориям учитывают только оттоки за запрошенный месяц.

Примеры промптов

• "List my YNAB budgets."

• "Show the accounts in budget budget-id-123."

• "List categories for budget budget-id-123."

• "Show the most recent 20 transactions in budget budget-id-123."

• "Find uncategorized transactions in budget budget-id-123 since 2026-04-01."

• "Summarize monthly spend by category for budget budget-id-123 in 2026-04."

Тестирование

Тесты имитируют ответы YNAB API, поэтому вы можете проверить поведение без реального токена:

npm run test

Идеи по доработке для продакшена

• Добавьте идентификаторы корреляции запросов и структурированные логи

• Добавьте метрики для повторных попыток, ограничения частоты запросов и задержек

• Добавьте интеграционные тесты для имитируемого уровня HTTP

• Добавьте элементы управления пагинацией результатов, если ваш MCP-клиент ожидает большие наборы данных

• Добавьте интеграцию с менеджером секретов вместо использования локальных файлов .env для развертывания