Avie Money Lover MCP / Local Bridge

Неофициальная интеграция Money Lover для двух сценариев работы:

1. MCP-сервер — предоставляет инструменты чтения/записи Money Lover MCP-совместимому клиенту.

2. GPT + локальный мост — ChatGPT подготавливает/проверяет JSON выписки, а ваш собственный компьютер хранит токен/куку Money Lover и выполняет финальный импорт.

Неофициальный проект. Этот репозиторий не связан с Money Lover и не поддерживается им. Здесь используются веб-эндпоинты, наблюдаемые в веб-приложении Money Lover. Эти эндпоинты, механизмы аутентификации, поведение категорий и требования к защите от ботов могут изменяться без предупреждения.

Что умеет

• Читает информацию об аутентифицированном пользователе

• Выводит список кошельков и категорий кошельков

• Читает транзакции по диапазонам дат

• Преобразует исходные идентификаторы Money Lover user_category_v2 в runtime-идентификаторы на основе истории транзакций

• Предпросматривает одну транзакцию без записи

• Добавляет транзакцию с защитой от дубликатов

• Предпросматривает пакет банковской/карточной выписки

• Сверяет расходы − доход с итогом выписки

• Помечает точные дубликаты, вероятные дубликаты, нераспознанные категории и проблемные строки

• Импортирует последовательно только после явного подтверждения

• Проверяет созданные транзакции обратным чтением

• Безопасно повторно выполняет после частичного импорта: точные дубликаты пропускаются

Related MCP server: monarch-mcp

Требования

• Windows 10/11, macOS или Linux

• Node.js 22+

• Контролируемый вами аккаунт Money Lover

• Для стабильной записи: свежая сессия владельца кошелька, актуальная браузерная cookie/cf_clearance, если требуется, и совпадающий браузерный User-Agent

Быстрый старт

git clone https://github.com/haonguyen97ftu/avie-moneylover-mcp.git
cd avie-moneylover-mcp
npm install
npm test

Настройка помощника Windows

scripts\setup-windows.cmd

Задайте учётные данные только в текущей оболочке:

set "MONEYLOVER_ACCESS_TOKEN=YOUR_FRESH_OWNER_TOKEN"
set "MONEYLOVER_CF_CLEARANCE=YOUR_CURRENT_CF_CLEARANCE_VALUE"
set "MONEYLOVER_USER_AGENT=YOUR_EXACT_BROWSER_USER_AGENT"

Затем выполните:

scripts\doctor.cmd

Рекомендуемый рабочий процесс GPT + локальный мост

Bank/card statement
        ↓
ChatGPT extracts + categorizes
        ↓
statement JSON
        ↓
local preview
        ↓
review / duplicate / reconciliation checks
        ↓
explicit IMPORT confirmation
        ↓
Money Lover
        ↓
local verification report

Do не вставляйте токены Money Lover, refresh-токены, пароль, браузерные куки или Cookie Cookie. Кредит, cf_clearance в ChatGPT, issues в issues, логи или скриншоты. ChatGPT достаточно только выписки и сгенерированного JSON предпросмотра/результата.

Предпросмотр выписки

scripts\preview.cmd data\your-statement.json

Импорт после проверки

scripts\import.cmd data\your-statement.json

Импорттер требует ввести точно:

IMPORT

перед началом записи.

Полное руководство на вьетнамском см. в docs/HUONG_DAN_SU_DUNG.md.

Наблюдаемое поведение API

Для аутентифицированных запросов в настоящее время используется:

Authorization: AuthJWT <access_token>

Наблюдаемые эндпоинта:

Запись может требовать браузерные заголовки и активную сессию Cloudflare. Поддерживаемые переменн окружения включают:

• MONEYLOVER_ACCESS_TOKEN

• MONEYLOVER_CF_CLEARANCE

• MONEYLOVER_COOKIE

• MONEYLOVER_USER_AGENT

• MONEYLOVER_TIMEOUT_MS

• MONEYLOVER_CATEGORY_LOOKBACK_DAYS

• MONEYLOVER_WRITE_DELAY_MS

Формат пакетной выписки

Начните с data/example-statement.json. Полная документация по полям приведена в docs/STATEMENT_FORMAT.md.

Предпросмотр:

npm run preview -- data\your-statement.json

Импорт:

npm run import -- data\your-statement.json

Необязательные флаги:

• --allow-review — оставить для проверки строки, намеренно без изменений после их анализа

• --allow-mismatch — обойти защиту сверки; используйте только если понимаете расхождение

• --allow-shared-wallet — обойти проверку владельца; запись для общего кошелька может не сработать

• --confirm IMPORT — неинтерактивное подтверждение импорта; не рекомендуется для обычного ручного использования

Безопасность по умолчанию

Импорттер отказывается от импорта, когда:

• любая строка находится в статусе blocked

• существует строка review, если не передан --allow-review

• расхождение при сверке с выписки не равно нулю, если не передан --allow-mismatch

• авторизованный пользователь не является владельцем кошелька, если не передан --allow-shared-wallet

• подтверждение не совпадает точно с IMPORT

Суммы должны быть положительными.

Категория v2

В некоторых аккаунт появляется исходный/шаблонный идентификатор категории из /category/list, в то время как /transaction/add ожидает другой runtime-идентификатор. Мост получает это сопоставление из существующих транзакций.

Если категория ни разу не встречалась в истории, скопируйте:

config/runtime-category-overrides.example.json

в:

config/runtime-category-overrides.json

и добавьте runtime-идентификатор, выбранный из реального браузерного запроса. Локальный файл переопределения игнорируется Git.

Безопасность публичного репозитория

Репозиторий настроен на то, чтобы случайно не коммитить локальные финансовые данные:

• data/*.json игнорируется, кроме безопасного примера

• out/ игнорируется

• .env* игнорируется

• локальные переопределения в runtime-категории игнорируются

• локальные вспомогательные файлы сессии игнорируются

Перед пушем выполните:

npm run repo:check
npm test

Затем вручную проверьте git status.

Безопасность

Если токен, пароль, refresh-токен, браузерная cookie или значение cf_clearance были скомпрометированы, считайте их скомпруют и запротектите. См. SECURITY.md.

Вклад в проект

Баг-репорты и pull request приветствуются. Перед изменениями прочитайте CONTRIBUTING.md. Не выкладывайте реальные финансовые выписки, идентификация аккаунтов, токены или куки в issues и тестовых сценариях.

Документация

• Вьетнамское руководство

• Формат выписки

• Архитектура

• Публикация на GitHub

• Политика безопасности

• Журнал изменений

• Промпт нормализации выписки для GPT

• Промпт проверка предпросмотра для GPT

Лицense

MIT — см. LICENSE.