Каталог MCP-инструментов

Expecto предоставляет всю свою функциональность через MCP-сервер, так что ИИ-ассистент (Claude Desktop, Claude Code, Cursor или собственный клиент) может управлять платформой напрямую: онбордить поставщиков, собирать контракты и трансформеры, запускать сессии и проверять результаты. На этой странице перечислены все доступные инструменты, сгруппированные по доменам.

Подключение и аутентификацию описывает Quickstart для разработчиков (раздел «Тот же сценарий через MCP»). Коротко: направьте клиент на <EXPECTO_BASE_URL>/mcp/ и аутентифицируйтесь тем же заголовком X-API-Key, что и для REST API.

Как читать каталог

Описания ниже — однострочные. Ваш MCP-клиент раскрывает полную входную схему каждого инструмента (имена параметров, типы, обязательность) через интроспекцию — большинство клиентов показывают её при осмотре или вызове инструмента. Параметры в скобках — это входные значения, которые принимает инструмент; какие из них обязательны, зависит от инструмента. Эквивалентная REST-поверхность интерактивно задокументирована на <EXPECTO_BASE_URL>/api/docs.

Все инструменты ограничены организацией, стоящей за вашим API-ключом. Инструменты, изменяющие состояние (create_*, update_*, delete_*, run_*, approve_*, …), требуют соответствующего разрешения у ключа.

Идентичность и health

Инструмент	Назначение
get_identity	Возвращает принципала, организацию и эффективные разрешения за API-ключом.
health	Проверяет статус и версию MCP-сервера.

Проекты

Инструмент	Назначение
list_projects	Список проектов организации (опциональный поиск).
get_project	Полные данные проекта: entity, каталоги, контракты, получатели и context_schema (обязательные scalars/tables session-контекста, которые надо задать перед запуском пайплайна).
get_project_instructions	Прочитать операционные инструкции проекта (markdown).
create_project	Создать проект (delivery standard); опц. задать output_format экспорта.
update_project	Изменить настройки проекта (режим одобрения, режим создания сессий, порог блокировки, output_format экспорта).
set_project_context_schema	Заменить схему контекста сессии проекта (скаляры + таблицы, у каждого required / filled_by). Прочитать текущую через get_project, смёржить и передать целиком; поля, наполняемые интеграцией, помечать filled_by: "integration".
update_project_instructions	Заменить операционные инструкции проекта.
delete_project	Удалить проект и все его scoped-ресурсы.
attach_entity_to_project	Привязать существующую entity к проекту под семантической ролью.
detach_entity_from_project	Отвязать entity от проекта по имени роли.
attach_catalog_to_project	Привязать org-level каталог к проекту.
detach_catalog_from_project	Отвязать org-level каталог от проекта.

Entity

Целевые схемы плюс построчные правила валидации.

Инструмент	Назначение
list_entities	Список entity (целевых схем) организации.
get_entity	Данные entity, включая схему и правила валидации.
create_entity	Создать новую entity (org-level или project-scoped).
update_entity	Изменить имя или описание entity.
delete_entity	Удалить entity вместе со схемой/правилами.
set_entity_schema	Создать или заменить JSON Schema entity.
get_entity_schema	Получить определение JSON Schema entity.
create_entity_rule	Создать правило валидации на entity. message принимает строку или многоязычный объект ({"en": …, "de": …, "ru": …}, ключ "en" обязателен).
update_entity_rule	Изменить существующее правило валидации. message принимает строку или многоязычный объект.
delete_entity_rule	Удалить правило валидации с entity.

Контракты данных

Соглашения о формате поставщика и их неизменяемые ревизии.

Инструмент	Назначение
list_data_contracts	Список контрактов данных (соглашений о формате поставщика).
get_data_contract	Данные контракта, включая ревизии и источники.
create_data_contract	Создать новый контракт данных (опционально с собственным external_id, уникальным в организации).
add_source_to_contract	Добавить источник (роль + тип + конфигурация парсинга) в ревизию.
create_revision	Создать новую черновую ревизию на существующем контракте.
activate_revision	Активировать черновую ревизию (с периодом valid_from).
update_data_contract	Изменить имя, описание или external_id контракта (пустая строка очищает значение; используется при создании сессии v1 как data_contract: {"external_id": …}).
delete_data_contract	Удалить контракт со всеми ревизиями/источниками.

Трансформеры

Маппинги полей из источников контракта в целевую схему entity.

Инструмент	Назначение
list_transformers	Список трансформеров контракта данных.
get_transformer	Трансформер со всеми маппингами полей.
create_transformer	Создать трансформер (маппинги из контракта в entity; опциональные построчные фильтры по ролям).
update_transformer_mappings	Заменить маппинги полей трансформера, опционально — и построчные фильтры.
validate_transformer_expressions	Проверить все выражения маппинга (и построчные фильтры) трансформера.
preview_transformer_sql	Показать скомпилированный DuckDB SQL трансформера.
delete_transformer	Удалить трансформер из контракта данных.

Построчные фильтры (row_filters_json). create_transformer и update_transformer_mappings принимают опциональную карту {роль: предикат}. Каждый предикат — булево выражение DuckDB SQL; входные строки, для которых он ложен, отбрасываются до маппинга и не попадают ни в данные entity, ни в валидацию, сверку или экспортный пакет. Так можно исключить из выгрузки в SAP явно не-маппящиеся счета, например {"postings": "\"Konto\" NOT IN (SELECT \"code\" FROM cat_kontenplan__provider WHERE \"mapping_type\" = 'ignore')"}. При обновлении отсутствие row_filters_json оставляет фильтры без изменений; {} их очищает. Число отброшенных строк отражается в сводке трансформации сессии.

Каталоги

Наборы справочных данных (планы счетов, кодовые таблицы, списки исключений). Каталог ограничен организацией, проектом или — через data_provider_id — одним поставщиком.

Инструмент	Назначение
list_catalogs	Список каталогов. Фильтр по project_id или по data_provider_id для provider-scoped каталогов.
get_catalog_data	Прочитать столбцы и строки каталога (с пагинацией).
create_catalog	Создать каталог — org-level, project-scoped (project_id) или provider-scoped (data_provider_id).
update_catalog	Изменить имя или описание каталога.
delete_catalog	Удалить каталог вместе с данными.
import_catalog_data	Импортировать CSV/Excel в каталог (заменяет существующие данные).
add_catalog_column	Добавить колонку (со значением по умолчанию) без переимпорта — существующие строки сохраняются.
edit_catalog_cell	Задать одну ячейку по индексу строки, напр. пометить счёту mapping_type = 'ignore'.

Поставщики данных

Поставщики, которые сдают данные. Поставщику выдаётся доступ к проекту, у него могут быть учётные записи участников и собственные provider-scoped каталоги.

Инструмент	Назначение
list_data_providers	Список поставщиков (data providers). Возвращённый id используется как data_provider_id для provider-scoped каталогов.
get_data_provider	Детали одного поставщика по id.
create_data_provider	Создать поставщика (name, опционально external_id, language en/de/ru).
update_data_provider	Переименовать, сменить external_id, задать язык сообщений language (en/de/ru) или is_active.
deactivate_data_provider	Деактивировать поставщика (мягкое удаление — is_active = false).
list_provider_members	Список учётных записей, привязанных к поставщику.
add_provider_member	Привязать пользователя по user_id или email с ролью role (contributor / manager); неизвестный email автоматически заводится в организацию.
remove_provider_member	Отвязать участника (по id членства).
list_provider_access	Список грантов доступа поставщика к проектам.
grant_provider_access	Выдать доступ к project_id (опционально в рамках data_contract_id).
revoke_provider_access	Отозвать грант доступа (по id гранта).

Интеграции, источники контекста и исходящие привязки

Подключения к внешним системам и настройка проекта вокруг них. Адаптер подключения объявляет возможности: context (автоматическое наполнение контекста сессии — BuiltAPI, PostgreSQL) и/или outbound (запись событий сессии во внешнюю платформу — Salesforce). Источники контекста позволяют вызывающей стороне передавать только параметры запроса (например, период и номер фонда) — остальное Expecto запрашивает сам при создании сессии; исходящие привязки отправляют результаты проверки наружу по завершении прогона.

Инструмент	Назначение
list_connection_types	Каталог поддерживаемых типов подключений: каждая запись несёт capabilities типа (context / outbound) и метаданные формы для создания подключения этого типа — форму base_url, форму credentials (один токен или структурированные поля) и config-поля с признаком обязательности. Вызывайте перед create_integration_connection.
create_integration_connection	Создать подключение уровня организации (name, type = builtapi, postgres или salesforce, base_url — URL API, DSN postgresql:// или My Domain-URL инстанса Salesforce, config_json — workspace_id для BuiltAPI, api_version для Salesforce, credentials только на запись — строка-токен или {client_id, client_secret} для OAuth-типов).
list_integration_connections	Список подключений; в ответах есть capabilities (context / outbound) и has_credentials, но никогда — сам секрет.
update_integration_connection	Переименовать, изменить конфигурацию, ротировать (credentials) или удалить (clear_credentials) токен, переключить is_active.
test_integration_connection	Проверить сохранённое подключение (connection_id, хранимые креденшелы) или несохранённые параметры дешёвым аутентифицированным вызовом; возвращает {ok, error_kind, message}.
delete_integration_connection	Удалить подключение; отклоняется, пока на него ссылаются источники контекста или исходящие привязки какого-либо проекта.
set_project_context_sources	Объявить, что запрашивать: источники с запросом к BuiltAPI — records_search (filter + projection) или aggregation (Mongo-пайплайн с $lookup) — либо sql-запрос к PostgreSQL (одиночный read-only SELECT); подстановки {{ context.* }} / {{ session.* }} — и таблицей/скаляром контекста, который наполняет каждый источник. Запросы к BuiltAPI пагинируются автоматически и забирают все строки; необязательный take — общий лимит строк (1–100 000), а не размер страницы. Без take результат больше 100 000 строк завершается явной ошибкой вместо тихой обрезки.
get_project_context_sources	Прочитать настройку источников контекста проекта.
test_context_source	Пробный прогон запроса одного источника с примерными значениями плейсхолдеров; возвращает превью (число строк, колонки, первые строки) или семантическую ошибку, без создания сессии.
fetch_session_context	Повторно выполнить автоматический сбор контекста сессии (доступно до подтверждения); результат — в context_fetch_report.
set_project_outbound_bindings	Объявить, какие события сессии куда записываются: привязки с outbound-подключением, events (например, session.checked, session.failed) и адаптер-специфичный mapping — для Salesforce: sobject + fields с шаблонами {{ … }} по полям конверта (session_id, run_id, health, …) и {{ context.* }}.
get_project_outbound_bindings	Прочитать исходящие привязки проекта.

Поля, наполняемые интеграцией, помечайте в контекстной схеме проекта как filled_by: "integration" — тогда они не требуются от вызывающей стороны; незавершённый или неудавшийся сбор блокирует пайплайн до parse с понятными причинами по каждому источнику.

Руководства по платформам (настройка на стороне Salesforce, виды запросов, лимиты, семантика ошибок) — в разделе Интеграции.

Вебхуки

Исходящие вебхуки для событий жизненного цикла сессии (совместимы со Standard Webhooks). Эндпоинты уровня организации или проекта; секрет подписи показывается один раз и хранится зашифрованным Fernet.

Инструмент	Назначение
list_webhook_endpoints	Список webhook-эндпоинтов организации.
get_webhook_endpoint	Детали эндпоинта по id.
create_webhook_endpoint	Создать эндпоинт (url, event_types, опц. project_id, опц. auth-заголовок). Секрет возвращается только при reveal_secret=true.
update_webhook_endpoint	Изменить URL, типы событий, активность или auth-заголовок.
delete_webhook_endpoint	Удалить эндпоинт и его доставки.
rotate_webhook_secret	Ротировать секрет подписи (виден один раз при reveal_secret=true).
send_webhook_ping	Отправить синтетический webhook.ping для проверки связи.
list_webhook_deliveries	Список попыток доставки — одного эндпоинта, одного подключения (connection_id) или всей организации; доставки исходящих привязок несут connection_id / project_id / binding_name, успешная хранит ссылку на созданную запись.
get_webhook_delivery	Детали доставки, включая выдержку из последнего ответа.
replay_webhook_delivery	Повторить прошлую доставку — эндпоинтные с исходным подписанным телом, доставки привязок — через адаптер.

Бизнес-правила

Межсущностная сверка и проверки на уровне проекта (DuckDB SQL / выражение).

Инструмент	Назначение
list_business_rules	Список бизнес-правил проекта.
get_business_rule	Конкретное бизнес-правило со всеми деталями.
create_business_rule	Создать бизнес-правило (опционально с привязкой через applicable_when_sources). message принимает строку или многоязычный объект ({"en": …, "de": …, "ru": …}, ключ "en" обязателен).
update_business_rule	Изменить бизнес-правило. message принимает строку или многоязычный объект.
delete_business_rule	Удалить бизнес-правило из проекта.

Сессии

Один акт доставки: файлы → парсинг → трансформация → валидация → проверка → подтверждение → одобрение → экспорт.

Инструмент	Назначение
list_sessions	Список сессий (фильтр по проекту, статусу, health, поиску).
get_session	Данные сессии: файлы (с parse_validation_summary по каждому файлу), трансформеры, статус пайплайна, а также context_validation_errors и file_validation_errors.
create_session	Создать сессию доставки для контракта + периода (+ поставщика).
upload_session_file	Загрузить файл под роль источника.
run_session_pipeline	Запустить полный пайплайн (парсинг → трансформация → валидация → проверка); возвращает job_id (для опроса статуса) и run_id — стабильный ID созданного прогона (один на каждое выполнение, см. GET /sessions/{id}/runs). При провале pre-flight-проверки возвращает error + details с перечнем отсутствующих полей контекста или файлов. Сессию с health=blocked можно перезапустить (каждый вызов создаёт новый прогон; blocked держится, пока новый прогон не пройдёт чисто). Если автоматический сбор контекста ещё идёт, парсинг выполняется сразу (технический результат контекста не ждёт), а затем прогон ждёт перед трансформацией — get_job_status показывает run_status = waiting, waiting_for = context_fetch — и продолжается сам, когда сбор завершится (те же run_id / job_id); упавший сбор или ожидание дольше таймаута закрывают его как errors.
set_session_context	Задать значения контекста сессии (скаляры и таблицы).
get_session_parse_issues	Ошибки валидации парсинга по одному загруженному файлу: счётчики summary, groups по паре (проверка, колонка) с количеством, подсказками формата и примерами строк, плюс постраничный сырой список issues. Единственный способ получить полные ошибки парсинга — get_session отдаёт только сводку.
get_session_violations	Нарушения валидации по трансформеру сессии.
get_session_check_violations	Нарушения по конкретному бизнес-правилу.
confirm_session	Подтвердить проверенную сессию (проверено отправителем).
approve_session	Одобрить подтверждённую сессию (финальная подпись перед экспортом).
reject_session	Отклонить подтверждённую сессию и вернуть на исправление.
export_session	Экспорт выходного пакета сессии как трекаемого job; у проекта должен быть настроен output format.
add_session_comment	Добавить комментарий к сессии.
list_session_comments	Список комментариев сессии в хронологическом порядке.

Задания (jobs)

Асинхронная работа (запуски пайплайна, экспорты, импорты) отслеживается как задания.

Инструмент	Назначение
get_job_status	Статус асинхронного задания (запуск пайплайна, экспорт, импорт). Для задания пайплайна дополнительно run_id, run_status и waiting_for (context_fetch, пока прогон ждёт сбор контекста).
list_jobs	Недавние асинхронные задания организации.