@besales/mcp 0.31.0 → 0.32.0

package/dist/schemas/mcp-tools.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "besales-mcp Tool Definitions",
   "version": "1.2.0-draft",
-  "lastUpdated": "2026-06-25",
+  "lastUpdated": "2026-07-26",
   "description": "MCP tool schemas для besales-mcp npm package. Active v1.5 set содержит PromptHub/ICP/Sandbox/Knowledge external-execution operations и stateless Platform Setup Bridge direct tools. Setup Pipeline session tools сохранены как Phase 4+ future design, но не входят в active toolset.",
   "executionModes": {
     "summary": "Каждая active LLM-операция имеет 2 MCP tools: get_instructions + submit. Claude локально между tools выполняет LLM-вызовы своими моделями. Auto-detection через JWT scope mcp:* → external default.",
@@ -1490,6 +1490,310 @@
         }
       }
     },
+    {
+      "name": "besales_getcourse_wave_run_start",
+      "description": "Start a durable GetCourse status-mode wave run for up to 5000 contacts. The run chunks the cohort, waits for the import lock, processes chunks sequentially and survives service restarts; poll one run via besales_getcourse_wave_run_status instead of building waves manually. WITHOUT confirm=true this is a DRY-RUN and no run is created. A real run requires BOTH confirm=true and explicit_confirmation=true. Only launch_type=status is supported; use besales_getcourse_wave_import for board/group. HTTP 409 returns the already active runId for the platform. Scope: mcp:platform-setup.",
+      "inputSchema": {
+        "type": "object",
+        "required": [
+          "platform_id",
+          "crm_id",
+          "channels",
+          "contacts"
+        ],
+        "properties": {
+          "workspace_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Optional override. Normally omit — resolved from the connected session."
+          },
+          "platform_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "GetCourse PLATFORM uuid."
+          },
+          "crm_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "GetCourse CRM uuid."
+          },
+          "launch_type": {
+            "type": "string",
+            "enum": [
+              "status"
+            ],
+            "description": "Only status mode is supported. For board/group use besales_getcourse_wave_import."
+          },
+          "channels": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "minItems": 1,
+            "description": "Wave channels (GetCourseTransport: VK|Telegram|MAX|SMS|Email|Site) for analytics."
+          },
+          "funnel": {
+            "type": "string",
+            "maxLength": 200,
+            "description": "Canonical business-funnel key/name for analytics."
+          },
+          "segment": {
+            "type": "string",
+            "maxLength": 200,
+            "description": "Wave segment label for analytics."
+          },
+          "cohort_label": {
+            "type": "string",
+            "maxLength": 200,
+            "description": "Human-readable name of this concrete run."
+          },
+          "message_variant": {
+            "type": "string",
+            "maxLength": 120,
+            "description": "Welcome-message variant for run analytics."
+          },
+          "found_count": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 10000000,
+            "description": "Contacts found in the source before deduplication and filters."
+          },
+          "product_code": {
+            "type": "string",
+            "maxLength": 100,
+            "pattern": "^[^\\s/]+$",
+            "description": "Product code for the funnel→product analytics dictionary."
+          },
+          "product_name": {
+            "type": "string",
+            "maxLength": 200,
+            "description": "Display name of the analytics product."
+          },
+          "deal_fields": {
+            "type": "object",
+            "additionalProperties": {
+              "type": [
+                "string",
+                "number",
+                "boolean",
+                "null"
+              ]
+            },
+            "description": "status mode: { \"<numeric fieldId>\": value } applied to every contact's deal."
+          },
+          "contacts": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 5000,
+            "description": "Durable-run cohort.",
+            "items": {
+              "type": "object",
+              "required": [
+                "contact_id"
+              ],
+              "properties": {
+                "contact_id": {
+                  "type": "string",
+                  "description": "GetCourse user id."
+                },
+                "deal_id": {
+                  "type": "string",
+                  "description": "Optional order id to pin."
+                },
+                "transport": {
+                  "type": "string",
+                  "description": "Optional known transport of the contact."
+                },
+                "dialog_id": {
+                  "type": "string",
+                  "description": "Optional GetCourse dialog id (resp_id)."
+                },
+                "lead_last_active_at": {
+                  "type": "string",
+                  "format": "date-time",
+                  "description": "Legacy ISO timestamp of the lead's last activity."
+                },
+                "segment_entered_at": {
+                  "type": "string",
+                  "format": "date-time",
+                  "description": "Exact ISO timestamp when the contact entered the segment."
+                }
+              },
+              "additionalProperties": false
+            }
+          },
+          "confirm": {
+            "type": "boolean",
+            "description": "Without true the call is a DRY-RUN: no run is created and nothing is sent."
+          },
+          "check_messenger_presence": {
+            "type": "boolean",
+            "description": "Whether to skip contacts without Telegram/Max/VK messenger presence."
+          },
+          "dedup_window_days": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 365,
+            "description": "Deduplication window in days; 0 disables deduplication."
+          },
+          "dedup_scope": {
+            "type": "string",
+            "enum": [
+              "any",
+              "same_funnel"
+            ],
+            "description": "Deduplicate against any wave or only the same canonical funnel."
+          },
+          "preflight": {
+            "type": "object",
+            "description": "Per-contact pre-send gate.",
+            "properties": {
+              "enabled": {
+                "type": "boolean",
+                "description": "false disables the row-level preflight gate."
+              },
+              "product_title": {
+                "type": "string",
+                "maxLength": 500,
+                "description": "Human product title used to build the match key."
+              },
+              "product_match_key": {
+                "type": "string",
+                "maxLength": 500,
+                "description": "Pre-normalized product match key."
+              },
+              "offer_id": {
+                "type": "integer",
+                "minimum": 1,
+                "description": "Optional GetCourse offer id."
+              },
+              "other_product_active_deal_mode": {
+                "type": "string",
+                "enum": [
+                  "warn",
+                  "block",
+                  "ignore"
+                ],
+                "description": "How to handle an active deal for another product."
+              }
+            },
+            "additionalProperties": false
+          },
+          "chunk_size": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 500,
+            "default": 100,
+            "description": "Contacts per sequential chunk."
+          },
+          "explicit_confirmation": {
+            "type": "boolean",
+            "enum": [
+              true
+            ],
+            "description": "Required together with confirm=true for a real run. MCP-only safety gate; not sent to the backend."
+          },
+          "confirmation_reason": {
+            "type": "string",
+            "description": "Optional human-readable reason accompanying explicit confirmation; not sent to the backend."
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "besales_getcourse_wave_run_status",
+      "description": "Get the aggregate status of one durable GetCourse wave run. The run owns chunking, sequential processing, import-lock waiting and restart recovery. This endpoint returns aggregates only; use besales_getcourse_wave_run_contacts for cursor-paginated per-contact outcomes. UNKNOWN and FAILED contacts are never retried automatically. Scope: mcp:platform-setup.",
+      "inputSchema": {
+        "type": "object",
+        "required": [
+          "run_id"
+        ],
+        "properties": {
+          "workspace_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Optional override. Normally omit — resolved from the connected session."
+          },
+          "run_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Durable run uuid returned by besales_getcourse_wave_run_start or an HTTP 409 response."
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "besales_getcourse_wave_run_contacts",
+      "description": "List cursor-paginated per-contact outcomes of a durable GetCourse wave run, optionally filtered by PENDING|CLAIMED|SENT|SKIPPED|FAILED|UNKNOWN. SKIPPED covers deduplication, missing messenger and preflight blocks. UNKNOWN means the outcome is unknown after an interrupted chunk and sending may have happened. UNKNOWN and FAILED are never retried automatically; repeat only as a deliberate operator decision in a separate wave. Scope: mcp:platform-setup.",
+      "inputSchema": {
+        "type": "object",
+        "required": [
+          "run_id"
+        ],
+        "properties": {
+          "workspace_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Optional override. Normally omit — resolved from the connected session."
+          },
+          "run_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Durable GetCourse wave run uuid."
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "PENDING",
+              "CLAIMED",
+              "SENT",
+              "SKIPPED",
+              "FAILED",
+              "UNKNOWN"
+            ],
+            "description": "Optional per-contact status filter."
+          },
+          "cursor": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Opaque cursor returned by the previous page."
+          },
+          "limit": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 500,
+            "default": 100,
+            "description": "Contacts per page."
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    {
+      "name": "besales_getcourse_wave_run_cancel",
+      "description": "Cancel a durable GetCourse wave run so no new chunks are claimed. A currently claimed chunk may still finish; poll besales_getcourse_wave_run_status and inspect rows with besales_getcourse_wave_run_contacts. UNKNOWN and FAILED rows are never retried automatically. Scope: mcp:platform-setup.",
+      "inputSchema": {
+        "type": "object",
+        "required": [
+          "run_id"
+        ],
+        "properties": {
+          "workspace_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Optional override. Normally omit — resolved from the connected session."
+          },
+          "run_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Durable GetCourse wave run uuid."
+          }
+        },
+        "additionalProperties": false
+      }
+    },
     {
       "name": "besales_wazzup_templates_list",
       "description": "List approved WABA templates of a Wazzup platform with usability flags. Returns templateGuid, title, Meta moderation status, bodyText, variableCount (values required) and usable + unsupportedReasons. Only usable=true templates can be sent in a wave; the rest are unapproved or carry a media header / variable URL button, where values would land in the wrong slots. Scope: mcp:platform-setup.",
@@ -2700,7 +3004,169 @@
             ]
           },
           "config": {
-            "type": "object"
+            "type": "object",
+            "description": "Конфигурация цепочки. Ключи — camelCase (передаётся в бэкенд без преобразования). Поля ниже описывают INACTIVE_USER_REACTIVATION; для MEETING_REMINDER/LOST_CLIENTS структура своя и произвольные поля разрешены.",
+            "properties": {
+              "enabled": {
+                "type": "boolean"
+              },
+              "filterMode": {
+                "type": "string",
+                "enum": [
+                  "status",
+                  "eventType",
+                  "variable"
+                ],
+                "description": "Режим отбора контактов. Неизвестное значение НЕ включает ни один фильтр — цепочка ушла бы всем контактам канала, поэтому бэкенд его отвергает."
+              },
+              "sequenceConditions": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "required": [
+                    "variable",
+                    "op",
+                    "value"
+                  ],
+                  "properties": {
+                    "variable": {
+                      "type": "string",
+                      "description": "Имя per-contact переменной канала."
+                    },
+                    "op": {
+                      "type": "string",
+                      "enum": [
+                        "eq",
+                        "neq",
+                        "in"
+                      ]
+                    },
+                    "value": {
+                      "description": "Строка для eq/neq; непустой массив непустых строк для in.",
+                      "oneOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "array",
+                          "items": {
+                            "type": "string"
+                          }
+                        }
+                      ]
+                    }
+                  }
+                },
+                "description": "Обязателен и непуст при filterMode=variable."
+              },
+              "steps": {
+                "type": "array",
+                "minItems": 1,
+                "description": "Шаги цепочки. Пустой массив отвергается: цепочка без шагов ничего не отправит.",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "stepType": {
+                      "type": "string",
+                      "enum": [
+                        "message",
+                        "webhook"
+                      ]
+                    },
+                    "scheduleMode": {
+                      "type": "string",
+                      "enum": [
+                        "offset",
+                        "clock"
+                      ],
+                      "description": "clock — время суток + сдвиг дней вместо задержки от последней активности."
+                    },
+                    "anchorMode": {
+                      "type": "string",
+                      "enum": [
+                        "last_inbound",
+                        "variable"
+                      ],
+                      "description": "variable — расписание считается от даты из переменной контакта (календарная цепочка)."
+                    },
+                    "anchorVariable": {
+                      "type": "string",
+                      "description": "Имя переменной с якорной датой. Обязательно при anchorMode=variable; переменная должна существовать у канала и НЕ быть константой."
+                    },
+                    "atTime": {
+                      "type": "string",
+                      "description": "Время суток HH:MM для scheduleMode=clock."
+                    },
+                    "dayOffset": {
+                      "type": "integer",
+                      "minimum": 0,
+                      "maximum": 30,
+                      "description": "Сдвиг в днях от якоря."
+                    },
+                    "validityMinutes": {
+                      "type": "integer",
+                      "minimum": 1,
+                      "description": "Окно валидности слота. Меньше 10 минут крон почти всегда промахнётся."
+                    },
+                    "slotGroup": {
+                      "type": "string",
+                      "description": "Метка взаимоисключающих вариантов одного момента (first-match-wins). Варианты ОБЯЗАНЫ идти в steps подряд."
+                    },
+                    "conditions": {
+                      "type": "array",
+                      "maxItems": 3,
+                      "items": {
+                        "type": "object",
+                        "required": [
+                          "variable",
+                          "op",
+                          "value"
+                        ],
+                        "properties": {
+                          "variable": {
+                            "type": "string",
+                            "description": "Имя per-contact переменной канала."
+                          },
+                          "op": {
+                            "type": "string",
+                            "enum": [
+                              "eq",
+                              "neq",
+                              "in"
+                            ]
+                          },
+                          "value": {
+                            "description": "Строка для eq/neq; непустой массив непустых строк для in.",
+                            "oneOf": [
+                              {
+                                "type": "string"
+                              },
+                              {
+                                "type": "array",
+                                "items": {
+                                  "type": "string"
+                                }
+                              }
+                            ]
+                          }
+                        }
+                      },
+                      "description": "Условия на переменные контакта; не прошли — шаг пропускается."
+                    },
+                    "delayHours": {
+                      "type": "number"
+                    },
+                    "delayMinutes": {
+                      "type": "number"
+                    },
+                    "messageConfig": {
+                      "type": "object",
+                      "description": "Текст/шаблон касания. Плейсхолдеры {name} календарного шага обязаны резолвиться, иначе шаг пропускается в рантайме."
+                    }
+                  }
+                }
+              }
+            }
           },
           "explicit_confirmation": {
             "type": "boolean"
@@ -3233,6 +3699,31 @@
                     "MAX"
                   ]
                 }
+              },
+              "create_missing_deal_enabled": {
+                "type": "boolean",
+                "description": "Create an order when the contact has no deal at all, so a status wave can still reach them (fields need a deal to be stamped on). The order is created from create_missing_deal_offer_id; funnel/stage are optional placement hints. Creates REAL orders in the school — dangerous, requires explicit_confirmation."
+              },
+              "create_missing_deal_offer_id": {
+                "type": [
+                  "integer",
+                  "null"
+                ],
+                "description": "GetCourse offer id used to create the order. REQUIRED when create_missing_deal_enabled is true: the legacy /pl/api/deals endpoint can only create an order from an offer. Use a free offer so the order amount is zero."
+              },
+              "create_missing_deal_funnel_id": {
+                "type": [
+                  "integer",
+                  "null"
+                ],
+                "description": "OPTIONAL GetCourse funnel id for placing the created order (defaults to the offer funnel). Must be set together with create_missing_deal_stage_id and belong to the GetCourse CRM of the wave."
+              },
+              "create_missing_deal_stage_id": {
+                "type": [
+                  "integer",
+                  "null"
+                ],
+                "description": "OPTIONAL GetCourse stage id inside the funnel above. Must be set together with create_missing_deal_funnel_id."
               }
             }
           },
@@ -6963,6 +7454,243 @@
           }
         }
       }
+    },
+    {
+      "name": "besales_followup_sequence_list",
+      "description": "Read-only список follow-up-цепочек канала: id, имя, тип, триггер, enabled, число шагов. Полный config — только по sequence_id или include_config=true (иначе ответ раздувает контекст). Upsert заменяет config ЦЕЛИКОМ, поэтому перед правкой одного шага прочитай конфиг здесь. Scope: read:analytics.",
+      "inputSchema": {
+        "type": "object",
+        "required": [
+          "platform_id"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "platform_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "sequence_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Вернуть одну цепочку вместе с полным конфигом."
+          },
+          "include_config": {
+            "type": "boolean",
+            "description": "Отдать конфиги всех цепочек. По умолчанию не отдаются — они объёмные."
+          }
+        }
+      }
+    },
+    {
+      "name": "besales_followup_step_stats",
+      "description": "Read-only витрина по шагам follow-up-цепочки: сколько ушло, сколько пропущено и почему (условие, плейсхолдер, окно валидности, закрытый слот). Окно по умолчанию 30 дней. Scope: read:analytics.",
+      "inputSchema": {
+        "type": "object",
+        "required": [
+          "platform_id",
+          "sequence_id"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "platform_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "sequence_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "from": {
+            "type": "string",
+            "format": "date",
+            "description": "Начало окна (YYYY-MM-DD). По умолчанию 30 дней назад."
+          },
+          "to": {
+            "type": "string",
+            "format": "date",
+            "description": "Конец окна (YYYY-MM-DD). По умолчанию сейчас."
+          }
+        }
+      }
+    },
+    {
+      "name": "besales_scheduled_task_list",
+      "description": "Read-only список плановых задач канала (модуль «Задачи»). Единственный тип — DIALOGUE_ANALYSIS (суфлёр: саммари дня + почасовой «Статус коммуникации»). Scope: mcp:platform-setup.",
+      "inputSchema": {
+        "type": "object",
+        "required": [
+          "platform_id"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "platform_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Канал (только Bitrix24Bot)."
+          }
+        }
+      }
+    },
+    {
+      "name": "besales_scheduled_task_update",
+      "description": "Создать/обновить плановую задачу канала. Конфиг мержится на сервере — присылай только изменяемые поля. Требует explicit_confirmation: задача пишет в CRM клиента по расписанию. Scope: mcp:platform-setup.",
+      "inputSchema": {
+        "type": "object",
+        "required": [
+          "platform_id",
+          "is_enabled"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "platform_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Канал (только Bitrix24Bot)."
+          },
+          "type": {
+            "type": "string",
+            "enum": [
+              "DIALOGUE_ANALYSIS"
+            ],
+            "default": "DIALOGUE_ANALYSIS"
+          },
+          "is_enabled": {
+            "type": "boolean",
+            "description": "Выключено — не выполняется вовсе, независимо от режимов."
+          },
+          "daily": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "enabled"
+            ],
+            "properties": {
+              "enabled": {
+                "type": "boolean"
+              },
+              "summary_time": {
+                "type": "string",
+                "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
+                "description": "Локальное время канала, HH:mm"
+              },
+              "output": {
+                "type": "string",
+                "enum": [
+                  "note",
+                  "hidden"
+                ],
+                "description": "note — заметка в таймлайн CRM (безопасно). hidden — скрытое сообщение в открытой линии (клиент не видит; на живом портале НЕ проверено)."
+              }
+            },
+            "description": "Саммари дня. Пишется ПОСЛЕ summary_time по локальному времени канала.",
+            "if": {
+              "properties": {
+                "enabled": {
+                  "const": true
+                }
+              },
+              "required": [
+                "enabled"
+              ]
+            },
+            "then": {
+              "required": [
+                "enabled",
+                "summary_time"
+              ]
+            }
+          },
+          "hourly": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "enabled"
+            ],
+            "properties": {
+              "enabled": {
+                "type": "boolean"
+              },
+              "window_start": {
+                "type": "string",
+                "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
+                "description": "Локальное время канала, HH:mm"
+              },
+              "window_end": {
+                "type": "string",
+                "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$",
+                "description": "Локальное время канала, HH:mm"
+              },
+              "min_new_events": {
+                "type": "integer",
+                "minimum": 1,
+                "description": "Порог новых событий: не набрано — разбор не запускается и заметка не пишется."
+              },
+              "output": {
+                "type": "string",
+                "enum": [
+                  "note",
+                  "hidden"
+                ],
+                "description": "note — заметка в таймлайн CRM (безопасно). hidden — скрытое сообщение в открытой линии (клиент не видит; на живом портале НЕ проверено)."
+              }
+            },
+            "description": "«Статус коммуникации» — раз в час внутри рабочего окна и только при новых сообщениях.",
+            "if": {
+              "properties": {
+                "enabled": {
+                  "const": true
+                }
+              },
+              "required": [
+                "enabled"
+              ]
+            },
+            "then": {
+              "required": [
+                "enabled",
+                "window_start",
+                "window_end"
+              ]
+            }
+          },
+          "funnels": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            },
+            "description": "ID воронок CRM. Пусто = без фильтра."
+          },
+          "managers": {
+            "type": "array",
+            "items": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "description": "ASSIGNED_BY_ID ответственных Bitrix (не наши id — бери из besales_crm_operator_list). Пусто = без фильтра."
+          },
+          "daily_prompt": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "minLength": 1,
+            "description": "Переопределение системного промпта саммари дня. Пусто = встроенный (написан под «ткани/производство»). null — СНЯТЬ переопределение (вернуть встроенный промпт)."
+          },
+          "hourly_prompt": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "minLength": 1,
+            "description": "Переопределение системного промпта почасового статуса. null — СНЯТЬ переопределение (вернуть встроенный промпт)."
+          },
+          "explicit_confirmation": {
+            "type": "boolean",
+            "description": "Обязательно true после подтверждения оператором."
+          }
+        }
+      }
     }
   ],
   "resources": [
@@ -7154,9 +7882,9 @@
     }
   ],
   "summary": {
-    "total_tools": 145,
+    "total_tools": 156,
     "tools_by_category": {
-      "getcourse_wave": 2,
+      "getcourse_wave": 6,
       "files_upload": 3,
       "platform_provisioning": 3,
       "crm_provisioning": 6,
@@ -7190,7 +7918,9 @@
       "session_workspace": 2,
       "model_comparison": 4,
       "dialog_script": 2,
-      "broadcast_analytics": 2
+      "broadcast_analytics": 2,
+      "scheduled_tasks": 2,
+      "follow_up_read": 2
     },
     "external_execution_pairs": [
       "besales_icp_analysis_get_instructions / submit",