fintablo-mcp

Только для чтения MCP-сервер поверх API Fintablo. Задайте финансовый вопрос на естественном языке — сервер вычисляет ответ в коде на основе актуальных данных API: без ручных выгрузок и устаревших срезов.

Главный инструмент: get_nzp — незавершённое производство (НЗП) по сделке, восстановленное из примитивов API и сверенное с собственной цифрой Fintablo.

Только чтение по умолчанию. В клиенте нет ни одного метода записи. Fintablo не получает от этого сервера никаких изменений — независимо от того, о чём попросили модель.

Формула НЗП

Расходы привязываются к этапам сделки, а не к сделке целиком. Открытые этапы (без даты акта) → НЗП; этапы, закрытые актом, → списаны. Для каждого открытого этапа — четыре слоя:

НЗП = Σ по открытым этапам [ операции + обязательства + зарплата + зарплатные налоги ]

Слой	Источник	Нюанс
операции	прямые списания по этапу (/v1/transaction)	сумма берётся из поля value, за вычетом НДС по строке (nds — это процент)
обязательства	все обязательства по этапу (/v1/obligation)	считаются целиком, даже если ещё не подписаны актом; поле amount уже без НДС
зарплата	сдельная зарплата по этапу (/v1/deal-salary)	сумма из поля value
зарплатные налоги	НДФЛ + взносы	оценка — пропорционально зарплате (см. ниже)

Выручка и «списано» сходятся к 100 %, итог НЗП — к ~98–99 %, остаток приходится целиком на слой зарплатных налогов.

Как расходы привязаны к этапам

В API сделка содержит массив stages[], у каждого этапа свой id, actDate и amount (выручка без НДС). У самих расходов нет отдельного поля stageId — они привязываются через поле dealId.

• Операции (/v1/transaction): документация прямо говорит, что при прикреплении операции к этапу в dealId передаётся идентификатор этапа. Поэтому операции запрашиваются по id этапа (?dealId=<stageId>).
• Обязательства и сдельная зарплата (/v1/obligation, /v1/deal-salary): здесь документация описывает dealId только как «идентификатор сделки», без оговорки про этап. Значит, Fintablo может хранить там либо id сделки, либо id этапа. Чтобы результат был верным в любом случае, сервер запрашивает эти слои по всем кандидатам сразу — id сделки + id всех этапов — и убирает дубликаты по id записи. Каждая запись затем относится к этапу по своему собственному dealId: если он совпадает с этапом — к этому этапу; если это id сделки целиком («на уровне сделки») — к первому открытому этапу, чтобы попасть в НЗП ровно один раз.

Сделка без этапов считается как единый расчётный объект (по собственным id/actDate/amount).

Известная неопределённость — как распознать неверный результат

⚠️ Документация Fintablo гарантирует привязку к этапу через dealId только для операций ДДС. Для обязательств и сдельной зарплаты поведение в спецификации не зафиксировано, и проверить его можно только на живой сделке с этапами. Сервер написан так, чтобы быть корректным при любом из вариантов (см. выше), но если цифра НЗП выглядит не так, как ожидается, в первую очередь проверьте именно эти два слоя.

На что смотреть:

• Обязательства или зарплата «потерялись». Если по многоэтапной сделке вы видите в Fintablo обязательства/сдельную зарплату, а в НЗП соответствующий слой нулевой или заметно меньше — сообщите об этом: вероятно, привязка dealId устроена иначе, чем предполагалось.
• Обязательство «уровня сделки» попало не на тот этап. Обязательство, привязанное к сделке целиком (а не к конкретному этапу), относится к первому открытому этапу. В разбивке по этапам (perStage) оно окажется на этом этапе — это намеренное упрощение. На итоговую сумму НЗП это не влияет (запись считается один раз), но распределение по этапам может выглядеть неожиданно.
• Зарплата считается только сдельная. Слой зарплаты берётся из /v1/deal-salary (сдельная зарплата, привязанная к сделке). Зарплата, начисленная через Ведомость месяца (/v1/salary), в расчёт НЗП не попадает. Если в производстве есть труд, который проводится не как сдельный, этот слой будет занижен.
• Зарплатные налоги — всегда оценка. См. раздел «О слое зарплатных налогов»: это коэффициент, а не фактические суммы.

Все перечисленное — вопросы бизнес-логики, а не ошибки в коде. Окончательно закрыть их можно, сверив результат с эталонной цифрой Fintablo на реальной сделке с этапами (см. Golden-тесты).

Инструменты

Инструмент	Назначение
get_nzp	НЗП по одной сделке по её коду (основной)
list_partners	справочник контрагентов
list_partner_groups	группы контрагентов
list_categories	статьи ОПиУ, с фильтром по pnlType
fintablo_get	ограниченный сырой GET для исследования (allowlist путей, лимит размера)

Установка

npm install
cp .env.example .env        # добавьте ваш FINTABLO_TOKEN
npm run dev                 # запуск на stdio (tsx)
npm run inspect             # открыть MCP Inspector
npm test                    # запустить тесты математики

Сборка и подключение в Claude Desktop:

npm run build

Затем добавьте запись из claude_desktop_config.example.json в ваш claude_desktop_config.json (используйте абсолютный путь к dist/index.js).

Контракт API (проверено)

Эндпоинты и имена полей в src/fintablo/client.ts сверены с OpenAPI-спецификацией FinTablo (https://my.fintablo.ru/api/FinTablo-v1-swagger.yaml, она же отрисованная документация на https://my.fintablo.ru/api/docs):

• Базовый URL: https://api.fintablo.ru, все ресурсы под /v1.
• Авторизация: заголовок Authorization: Bearer <token>. Лимит — 300 запросов в минуту (клиент делает retry/backoff на 429 и 5xx).
• Операции живут на /v1/transaction: сумма — value, тип — group (income/outcome/transfer), НДС — nds (процент). Разбитые операции приходят отдельными строками (через parentId), а не вложенным массивом.
• Пагинация различается: /transaction — page + pageSize (до 1000), /deal — page (по 500), справочники (/partner, /partner-group, /category) не пагинируются.
• Сделка ищется по name (поля code в API нет; человекочитаемый код вроде 02-26/Б — это имя сделки).
• Обязательства (/v1/obligation): amount уже без НДС, отдельное поле nds — это сумма НДС. Привязка dealId к этапу спецификацией не гарантирована — см. «Известная неопределённость».
• Сдельная зарплата (/v1/deal-salary): сумма — value. Не путать с /v1/salary (ведомость месяца — другой формат). Привязка dealId к этапу так же не гарантирована (см. там же).

О слое зарплатных налогов

Слой payrollTax — это оценка: общий коэффициент PAYROLL_TAX_RATE (НДФЛ + взносы), применённый к сумме зарплаты этапа. Реальные эффективные ставки различаются по сотрудникам, и привязать их к конкретному этапу из сырых данных нельзя.

При этом ведомость месяца /v1/salary возвращает фактические tax (НДФЛ) и fee (взносы) по сотруднику за месяц. Это месячные итоги, поэтому для разнесения по сделкам/этапам всё равно нужна пропорция — но их можно использовать, чтобы откалибровать PAYROLL_TAX_RATE по эталонным сделкам.

Golden-тесты

test/nzp.test.ts содержит синтетические проверки плюс TODO на самую ценную работу: записать реальные фикстуры DealData для 11-24/Г и 02-26/Б, затем проверять, что computeNzp(...) совпадает с эталонными цифрами в пределах допуска. Эти две сделки — ваша регрессионная сеть: любое будущее изменение API, ломающее математику, будет поймано.

Открытые вопросы, которые закроют именно эти фикстуры:

• наследуют ли строки-части разбитой операции group/nds родителя (сейчас по умолчанию outcome);
• значение PAYROLL_TAX_RATE, при котором итог сходится к ~98–99 %.

Структура

src/
  index.ts              # MCP-сервер: stdio + регистрация инструментов
  fintablo/
    client.ts           # клиент API: авторизация, пагинация, retry/backoff, raw→domain
    types.ts            # доменные типы, от которых зависит математика
  domain/
    nzp.ts              # формула — ЧИСТАЯ, без I/O, покрыта тестами
    vat.ts              # вычет НДС по строке (по проценту)
test/
  nzp.test.ts           # тесты математики + каркас golden-тестов

Лицензия

MIT