talonicdev/talonic-mcp

Захватывает доступную задачу стадии Agent или повторно захватывает её после истечения срока аренды. ИСПОЛЬЗУЙТЕ, КОГДА: готовы обработать задачу. Сохраните возвращённые execution_epoch и lease_expires_at. НЕ ДЛЯ: простой проверки работы (используйте talonic_get_agent_task) или продления активной аренды (используйте talonic_heartbeat_agent_task). Конфликтующая активная попытка захвата возвращает HTTP 409. Успешный захват возвращает полезную нагрузку задачи.

Превращает ЛЮБОЙ документ в структурированный JSON, прошедший проверку схемы. Инструмент по умолчанию, когда нужно извлечь данные ИЗ неструктурированного файла: PDF, скан, изображение, DOCX, письмо или фото. Возвращает запрошенные поля с оценками уверенности для каждого поля. ИСПОЛЬЗОВАТЬ КОГДА: 'извлечь данные из этого документа', 'превратить этот PDF в JSON', 'вытащить поля из этого файла', 'распарсить этот скан / форму / выписку / чек / отчёт' - для ЛЮБОГО типа документов, обычных (счёт, договор) или необычных. Если задача - неструктурированный документ -> структурированные данные, это ответ. НЕ ДЛЯ: полный обычный текст (используйте talonic_to_markdown) · поиск документов (используйте talonic_search / talonic_filter). ПО ИМЕНИ: если пользователь называет файл, сначала вызовите talonic_search, чтобы получить его document_id, затем вызовите этот инструмент. АРГУМЕНТЫ: определите нужные поля с помощью встроенной schema (JSON Schema, например {type:'object',properties:{vendor_name:{type:'string'}}}) ИЛИ сохранённого schema_id, но не одновременно. Ещё не знаете поля? Установите auto_schema:true, чтобы Talonic обнаружил их (открытый захват) и вернул предлагаемую схему, которую можно доработать. Укажите РОВНО ОДИН источник документа: document_id (самый дешёвый, документ рабочей области), file_url (публичный URL) или file_data+filename (только небольшие локальные файлы). СТОИМОСТЬ: дёшево за вызов, есть бесплатный тариф - можно свободно использовать; проверяйте бюджет через talonic_get_balance. ВОЗВРАЩАЕТ: данные (JSON), confidence.overall и confidence.fields (значения ниже 0.7 считайте требующими проверки), метаданные документа, extraction_id.

Находит документы по значениям извлечённых полей с помощью составляемых условий (например, «счета, где total > 1000»). ИСПОЛЬЗУЙ, КОГДА: нужны условия на основе значений извлечённых полей — сравнения чисел/дат/текста или проверки наличия. НЕ ДЛЯ: полнотекстового / смыслового поиска (используй talonic_search) · поиска одного документа по id (используй talonic_get_document). АРГУМЕНТЫ: conditions[] (AND-логика). Каждый = РОВНО ОДИН из field (каноническое имя) или field_id (UUID), operator и обычно value. Операторы: eq, neq, gt, gte, lt, lte, between (требует value И value_to), contains, is_empty / is_not_empty (без value). value/value_to — string|number|boolean в соответствии с типом поля (для дат — ISO YYYY-MM-DD). ТЕКСТОВЫЕ ФИЛЬТРЫ: для eq/contains/is_not_empty по текстовому полю просто ПОПРОБУЙ естественное имя поля ('currency', 'vendor_name') — имена разрешаются на сервере, и неразрешённое поле попадает в warnings[], а не в ошибку. НЕ блокируйся на предварительном определении поля; search-first требуется только для числовых операторов. ЧИСЛОВАЯ ЗАЩИТА: gt/gte/lt/lte/between работают только если dataType поля равен 'number'. Сначала вызови talonic_search и проверь dataType; числовая операция над строковым полем возвращает ноль совпадений. Если в ответе есть warnings[], покажи их пользователю — не делай повторных попыток молча. ВОЗВРАЩАЕТ: data[] (подходящие документы со значениями полей), total, warnings[].

Получает неизменяемый снимок входных данных, инструкции и объявленный контракт вывода для одной задачи этапа агента. Это раскрытие проверяется. ИСПОЛЬЗУЙТЕ, КОГДА: осматриваете задачу из списка перед принятием решения, обрабатывать ли её. НЕ ДЛЯ: получения задачи (используйте talonic_claim_agent_task) или возврата результатов (используйте talonic_submit_agent_task). АРГУМЕНТЫ: task_id. ВОЗВРАЩАЕТ: metadata, input_snapshot, output_contract, instructions и timeout_fallthrough.

Читает баланс кредитов Talonic рабочего пространства, его стоимость в евро, тариф, расход за 30 дней и прогнозируемый остаток работы. ИСПОЛЬЗУЙТЕ КОГДА: пользователь спрашивает о кредитах/бюджете, или перед большой пакетной обработкой, когда нужно подтвердить наличие запаса. НЕ ДЛЯ: стоимости одного вызова извлечения (она возвращается в ответе talonic_extract). АРГУМЕНТЫ: нет. ВОЗВРАЩАЕТ: balance_credits, balance_eur, tier, burn_rate_30d_credits, projected_runway_days (-1 = недавнего использования нет), tier_resets_at.

Извлекает метаданные и статус обработки одного документа из рабочего пространства. ИСПОЛЬЗУЙТЕ, КОГДА: «расскажи о документе X» или для опроса статуса после talonic_request_upload, пока файл не будет готов. НЕ ДЛЯ: полного текста (используйте talonic_to_markdown) · извлечённых полей (используйте talonic_extract). ПО ИМЕНИ: если пользователь называет файл, сначала вызовите talonic_search, чтобы получить его document_id, затем вызовите этот инструмент. АРГУМЕНТЫ: document_id. ВОЗВРАЩАЕТ: filename, pages, type_detected, language и status. Жизненный цикл статуса: pending_upload -> uploading -> queued -> extracting -> completed. Дождитесь completed перед вызовом talonic_extract для только что загруженного документа. Конечные статусы ошибок: ocr_failed, extraction_failed, error — прекратите опрос и сообщите об ошибке пользователю, если появится любой из них. Чтобы прочитать текст документа, вызовите talonic_to_markdown с этим id.

Читает машиночитаемый каталог цен на кредиты Talonic: фиксированные ставки за единицу, чтобы вы могли предсказать расходы ДО запуска чего-либо. ИСПОЛЬЗУЙТЕ КОГДА: оцениваете стоимость запланированной задачи по извлечению/структурированию/сопоставлению или отвечаете на вопрос о цене. Публичный - работает без траты кредитов. НЕ ДЛЯ: текущего баланса рабочего пространства (используйте talonic_get_balance) или того, что оно уже потратило (используйте talonic_get_usage). АРГУМЕНТЫ: нет. ВОЗВРАЩАЕТ: currency, credits_per_eur, multipliers (например, batch 0.5x) и units[] - каждый { unit, label, credits, eur, free }.

Читает потребление кредитов по функциям рабочего пространства за скользящее окно: куда на самом деле ушли кредиты. ИСПОЛЬЗОВАТЬ КОГДА: пользователь спрашивает, на что он потратил кредиты, или вы хотите увидеть, какая функция (извлечение, структурирование, интеллектуальные операции) доминирует в затратах. НЕ ДЛЯ: остатка на балансе (используйте talonic_get_balance) или тарифов за единицу (используйте talonic_get_pricing). ПАРАМЕТРЫ: days (необязательный, по умолчанию 30, ограничение 1-365). ВОЗВРАЩАЕТ: period_days, total_credits и by_function[] - каждый { operation_type, operations, credits }, сначала наибольшие затраты.

Продлевает аренду на закреплённую задачу этапа агента. КОГДА ИСПОЛЬЗОВАТЬ: обработка может продолжаться после lease_expires_at; отправьте сердцебиение до истечения срока, используя значение epoch из закрепления. НЕ ДЛЯ: получения задачи (используйте talonic_claim_agent_task) или отправки завершённых результатов (используйте talonic_submit_agent_task). АРГУМЕНТЫ: task_id и execution_epoch. Устаревшие или чужие закрепления возвращают HTTP 409.

Перечисляет задачи стадии Agent, видимые для этого учётного доступа рабочей области Talonic. ИСПОЛЬЗУЙТЕ КОГДА: ищете внешнюю работу агента для обработки; начните со статуса 'available'. НЕ ДЛЯ: чтения неизменяемой полезной нагрузки задачи (используйте talonic_get_agent_task) или взятия аренды (используйте talonic_claim_agent_task). АРГУМЕНТЫ: необязательные status, limit и cursor. ВОЗВРАЩАЕТ: только метаданные и pagination.next_cursor.

Перечисляет сохранённые схемы в рабочем пространстве в виде компактных сводок (id, short_id, name, description, version, field_count). ИСПОЛЬЗУЕТСЯ КОГДА: «what schemas do I have» или для поиска переиспользуемой схемы перед извлечением. НЕ ДЛЯ: одноразового извлечения со встроенной схемой (вызывайте talonic_extract напрямую). АРГУМЕНТЫ: нет. ВОЗВРАЩАЕТ: data[] со сводками схем. Полные определения полей здесь опущены — для их получения прочитайте ресурс talonic://schemas. Передавайте id/short_id схемы в talonic_extract как schema_id.

Получает ссылку для загрузки в браузере, которую пользователь открывает, чтобы добавить файл в своё рабочее пространство. Возвращает ссылку и предварительно выделенный document_id. ИСПОЛЬЗУЙ, КОГДА: пользователь хочет загрузить документ, и вы не можете передать его напрямую - размещённые/песочные клиенты (ChatGPT, Claude.ai) или файлы слишком велики для аргументов вызова инструмента. НЕ ДЛЯ: документа, уже находящегося в рабочем пространстве (используйте его document_id) · файла, уже доступного по публичному URL (используйте file_url в talonic_extract). АРГУМЕНТЫ: имя файла (с расширением). ВОЗВРАЩАЕТ: upload_url, document_id, expires_at. После загрузки пользователя опрашивайте talonic_get_document с этим document_id, пока статус не станет 'completed', затем вызывайте talonic_extract. Если статус становится ocr_failed, extraction_failed или error, прекратите опрос и сообщите об ошибке пользователю.

Сохраняет повторно используемую схему в рабочую область для применения в будущих извлечениях. ИСПОЛЬЗУЙТЕ, КОГДА: пользователь подтверждает схему/шаблон, который хочет повторно использовать в разных документах. НЕ ДЛЯ: однократного извлечения (передайте схему напрямую в talonic_extract). АРГУМЕНТЫ: name; definition — JSON-схема ({type:'object',properties:{...}}) или плоская map {field:'type'}. ВОЗВРАЩАЕТ: сохранённую схему с id и short_id. Передайте любой из них в talonic_extract как schema_id.

Находит документы, поля, схемы или источники в рабочем пространстве. Один вызов возвращает ранжированные результаты по всем типам. ПОИСК ИДЁТ ПО ТОЧНОМУ КЛЮЧЕВОМУ СЛОВУ, а не по смыслу. Запрашивайте ОДНИМ коротким термином в единственном числе или точным именем файла: 'invoice', 'bank statement', 'sample-invoice.pdf'. Предложения ('documents related to invoices') и множественное число ('invoices') возвращают пустой результат. Если поиск ничего не дал, повторите с более коротким ключевым словом в единственном числе, прежде чем делать вывод, что в рабочем пространстве ничего нет. ИСПОЛЬЗУЙТЕ, КОГДА: пользователь называет или описывает документ без идентификатора, или вам нужен document_id или имя фильтруемого поля перед вызовом extract / to_markdown / get_document / filter. НЕ ДЛЯ: структурированных фильтров вида «поле-значение» (например, 'amount > 1000' — для них используйте talonic_filter). АРГУМЕНТЫ: query (короткое точное ключевое слово); опционально limit. ВОЗВРАЩАЕТ: documents[], fields[]/fieldMatches[] (только записи с filterable: true работают в talonic_filter), schemas[], sources[]. Используйте id из documents[], чтобы работать с именованным файлом.

Отправляет заявленные поля вывода для захваченной задачи на этапе Agent и возобновляет приостановленный документ. ИСПОЛЬЗУЙТЕ, КОГДА: обработка завершена и все требуемые выходные данные в output_contract готовы. НЕ ДЛЯ: незаявленные поля или частичное обслуживание аренды (используйте talonic_heartbeat_agent_task). АРГУМЕНТЫ: task_id, execution_epoch, outputs, привязанные точно по ключу заявленного поля, и опциональное summary. Платформа проверяет все поля и типы транзакционно перед записью чего-либо.

Получает текст документа в Markdown, преобразованный с помощью OCR. ИСПОЛЬЗУЙТЕ, КОГДА: пользователь хочет получить полный текст - 'что здесь написано', краткое содержание или перевод документа. НЕ ДЛЯ: конкретных структурированных полей (используйте talonic_extract со схемой). ПО ИМЕНИ: если пользователь указывает имя файла, сначала вызовите talonic_search, чтобы получить его document_id, затем вызовите этот. АРГУМЕНТЫ: предпочтительнее document_id (документ из рабочего пространства - один дешёвый вызов). В противном случае file_url, или file_data+filename для небольших локальных файлов - укажите ровно один. Ввод файла сначала загружает документ и расходует кредиты; document_id не расходует. ВОЗВРАЩАЕТ: document_id и markdown (полный текст).