FinLedger

Локальная финансовая книга с тремя поверхностями чтения, плюс MCP-сервер, чтобы агент мог запрашивать их:

• expenses: расходные счета, сверяемые с возмещениями от коллег

• investments: брокерские остатки, позиции и активность

• income: зарплата (гросс, удержания, на руки)

Расходы и инвестиции используют общее хранилище и больше ничего. Счёт имеет явный domain, и каждый запрос расходов проходит через него, поэтому покупка акций не может попасть в матчер возмещений.

Матчер основан на правилах. Он воздерживается, когда не уверен. Человек или агент подтверждает, прежде чем совпадение уменьшит чистые расходы.

Реальные транзакции, расчётные листы и API-ключи остаются на вашей машине (~/.finledger/ledger.db, .env). Этот репозиторий содержит только код и синтетический набор для оценки.

Установка

Python 3.10+. Книга, матчер, MCP-цикл и среда оценки используют стандартную библиотеку. pypdf необязателен и нужен только для импорта PDF-расчётных листов.

pip install -e .

Related MCP server: MCP Agent - AI Expense Tracker

MCP-сервер

python3 -m finledger.mcp_server --db ~/.finledger/ledger.db

18 инструментов с пространствами имён expenses_*, investments_* и income_*, плюс savings_rate, accounts, sync и reconcile.

Пример для Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "finledger": {
      "command": "python3",
      "args": ["-m", "finledger.mcp_server"]
    }
  }
}

Путь к книге по умолчанию: ~/.finledger/ledger.db.

CLI

finledger sync
finledger reconcile
finledger review
finledger serve

finledger serve открывает локальный стол на :8770. На macOS вы также можете дважды щёлкнуть scripts/Expense Desk.command.

Дополнительные живые источники (поместите учётные данные в .env, никогда не коммитьте его):

Скопируйте .env.example в .env.

Публичная оценка

Опубликованный эталонный набор является синтетическим. Он генерируется scripts/make_sample_data.py и находится в data-sample/. Каждая строка транзакции помечена synthetic: true. Это набор покрытия для поведения матчера (чистое совпадение, фан-ин, объединение, родительская исходящая от коллеги, мерчант-кредиты, слабые заметки, кросс-источниковые двойники). Это не анонимизированные реальные данные.

python3 scripts/eval_public.py
# equivalent:
python3 -m reconcile.eval --matcher rules_v0

Числа, которые можно воспроизвести из этого репозитория

Измерено на data-sample/ с rules_v0 (окно ±90 дней, порог автоподбора 0.75):

Перезапустите python3 scripts/eval_public.py, чтобы обновить эти числа. Два оставшихся ложных срабатывания на выборке — реальные слабости матчера, включая чрезмерное срабатывание правила повышения полноты для эмодзи.

Чего нет в этом репозитории

В ходе разработки использовался частный эталонный набор из примерно 92 размеченных примеров. В нём указаны реальные люди и реальные покупки, и он не публикуется. Не рассматривайте числа на выборке как воспроизведение того набора. Другой корпус, другой размер, другие оценки.

Этот репозиторий не претендует на 100% точность автоподбора.

Матчер

См. reconcile/README.md. Краткая версия:

Разметьте корпус выборки с помощью python3 labeling/app.py (по умолчанию data-sample/).

Лицензия

MIT