@hubex/mcp 0.2.0

package/dist/tools/guides.js

@@ -0,0 +1,126 @@
+/**
+ * Знание о бизнес-процессах HubEx в двух формах: markdown-гайды под явный
+ * запрос и аннотации полей, подмешиваемые в вывод describe_endpoint.
+ */
+import { loadFieldNotes, loadGuide } from "../guides/loader.js";
+import { okResult, failResult } from "./registry.js";
+/** Топики сгруппированы по областям: группировка попадает в описание инструмента,
+ * чтобы выбор топика не требовал отдельного «хаб»-гайда и лишнего вызова. */
+const TOPIC_GROUPS = [
+    {
+        title: "База",
+        topics: {
+            start: "URL, заголовки, авторизация, формат ответов, порядок работы с этим сервером",
+            dictionaries: "справочники: где брать идентификаторы для полей",
+        },
+    },
+    {
+        title: "Заявки",
+        topics: {
+            taskcreate: "создание заявки: метаданные формы, обязательные поля, справочники, порядок вызовов",
+            taskedit: "редактирование заявки: правка полей, стадии и статусы, работы и материалы, удаление",
+            taskchecklists: "чек-листы в заявке: заполнение пунктов, вложения, сохранение и переход стадии",
+        },
+    },
+    {
+        title: "Объекты, контрагенты, склад",
+        topics: {
+            assets: "объекты обслуживания: справочники, создание с локацией и связями, редактирование",
+            companies: "компании-заказчики",
+            users: "пользователи, роли и навыки исполнителей",
+            materials: "материалы склада: создание и изменение, валюта цены, единицы измерения",
+        },
+    },
+    {
+        title: "Настройка тенанта",
+        topics: {
+            lifecycle: "жизненный цикл заявки: стадии, маршрут типа заявки, переходы, переопределения для ролей, статусы",
+            tasktypes: "типы заявок: маска номера, срок закрытия, виды работ, участки, критичности, актуальности, форма заявки",
+            roles: "роли и полномочия: API/UI/расширенные, приложения, плагины, доступ к полям заявки",
+            notifications: "оповещения: шаблоны уведомлений, правила выбора получателей, триггеры, webhooks, приём заявок с почты",
+            sla: "правила расчёта крайнего срока закрытия и графики работ",
+            attributes: "дополнительные поля: типы, списки значений, привязка к сущностям",
+            checklisttemplates: "шаблоны чек-листов: пункты, атрибуты и привязки к объектам и видам работ",
+        },
+    },
+];
+export const GUIDE_TOPICS = TOPIC_GROUPS.flatMap((g) => Object.keys(g.topics));
+function guideTool() {
+    const topicList = TOPIC_GROUPS.map((g) => `${g.title}: ` +
+        Object.entries(g.topics)
+            .map(([topic, summary]) => `${topic} — ${summary}`)
+            .join("; ")).join(". ");
+    return {
+        definition: {
+            name: "hubex_get_guide",
+            description: "Короткий гайд по бизнес-процессу HubEx: порядок вызовов, обязательные поля, подводные камни. " +
+                `Читай перед первой работой с областью. Топики по областям. ${topicList}.`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    topic: {
+                        type: "string",
+                        enum: GUIDE_TOPICS,
+                        description: "Какой процесс описать.",
+                    },
+                },
+                required: ["topic"],
+            },
+        },
+        async execute(args) {
+            try {
+                const topic = String(args.topic ?? "");
+                if (!GUIDE_TOPICS.includes(topic)) {
+                    throw new Error(`Неизвестный топик "${topic}". Доступны: ${GUIDE_TOPICS.join(", ")}.`);
+                }
+                return okResult(loadGuide(topic));
+            }
+            catch (err) {
+                return failResult(err);
+            }
+        },
+    };
+}
+export function buildGuideTools() {
+    return [guideTool()];
+}
+function noteText(note) {
+    const parts = [note.description];
+    if (note.required)
+        parts.push("Обязателен.");
+    if (note.lookup)
+        parts.push(`Справочник: ${note.lookup}`);
+    return parts.join(" ");
+}
+function annotateProperties(properties, notes) {
+    if (!properties)
+        return;
+    for (const [name, schema] of Object.entries(properties)) {
+        if (!schema || typeof schema !== "object")
+            continue;
+        const note = notes[name];
+        if (note) {
+            const existing = typeof schema.description === "string" ? schema.description.trim() : "";
+            schema.description = existing ? `${existing} ${noteText(note)}` : noteText(note);
+        }
+        if (schema.properties)
+            annotateProperties(schema.properties, notes);
+        if (schema.items?.properties)
+            annotateProperties(schema.items.properties, notes);
+    }
+}
+/** Подмешать ручные аннотации в схему, не затирая описания из swagger. */
+export function annotateDescription(description) {
+    const notes = loadFieldNotes();
+    const out = {
+        ...description,
+        pathParams: structuredClone(description.pathParams),
+        queryParams: structuredClone(description.queryParams),
+        body: description.body ? structuredClone(description.body) : undefined,
+    };
+    annotateProperties(out.pathParams, notes);
+    annotateProperties(out.queryParams, notes);
+    if (out.body?.properties)
+        annotateProperties(out.body.properties, notes);
+    return out;
+}

package/dist/tools/registry.js

@@ -0,0 +1,37 @@
+/**
+ * Собирает реестр из 13 фиксированных инструментов: курируемых, гайдов, discovery и исполнения.
+ */
+import { HubexApiError } from "../http.js";
+import { buildDiscoveryTools } from "./discovery.js";
+import { buildRequestTools } from "./request.js";
+import { buildCuratedTools } from "./curated.js";
+import { buildGuideTools, annotateDescription } from "./guides.js";
+function ok(data) {
+    if (typeof data === "string")
+        return { text: data };
+    // JSON.stringify(undefined) === undefined, а MCP требует строку в content[0].text.
+    return { text: JSON.stringify(data ?? null, null, 2) };
+}
+function fail(err) {
+    const message = err instanceof HubexApiError ? err.message : err instanceof Error ? err.message : String(err);
+    return { text: message, isError: true };
+}
+/** Собрать все 13 инструментов: курируемые, гайды, discovery и исполнение. */
+export function buildRegistry(deps) {
+    const tools = [
+        ...buildCuratedTools(deps.client, deps.config, deps.auth),
+        ...buildGuideTools(),
+        ...buildDiscoveryTools({
+            index: deps.index,
+            schemas: deps.schemas,
+            methods: deps.config.methods,
+            annotate: annotateDescription,
+        }),
+        ...buildRequestTools({ client: deps.client, index: deps.index, config: deps.config }),
+    ];
+    const registry = new Map();
+    for (const tool of tools)
+        registry.set(tool.definition.name, tool);
+    return registry;
+}
+export { ok as okResult, fail as failResult };

package/dist/tools/request.js

@@ -0,0 +1,170 @@
+/**
+ * Исполнение произвольного эндпоинта HubEx. Инструменты разделены по группам
+ * HTTP-методов и принимают только endpointId: метод выводится из него, поэтому
+ * инструмент не может выполнить операцию чужой группы.
+ */
+import { METHOD_GROUPS, enabledGroups } from "./discovery.js";
+import { okResult, failResult } from "./registry.js";
+const GROUP_DESCRIPTIONS = {
+    read: "Выполнить GET-запрос к HubEx по идентификатору эндпоинта.",
+    write: "Выполнить POST/PUT/PATCH-запрос к HubEx по идентификатору эндпоинта. ИЗМЕНЯЕТ ДАННЫЕ. " +
+        "Схему тела бери из hubex_describe_endpoint.",
+    delete: "Выполнить DELETE-запрос к HubEx по идентификатору эндпоинта. УДАЛЯЕТ ДАННЫЕ. " +
+        "Часть эндпоинтов удаляет пачкой и требует список в body — схему бери из hubex_describe_endpoint.",
+    head: "Выполнить HEAD-запрос к HubEx: проверить существование ресурса без загрузки тела ответа.",
+};
+/** Группа, к которой относится метод — для подсказки «зови другой инструмент». */
+function groupOf(method) {
+    for (const [group, methods] of Object.entries(METHOD_GROUPS)) {
+        if (methods.includes(method))
+            return group;
+    }
+    throw new Error(`Метод ${method} не принадлежит ни одной группе`);
+}
+export function applyDefaults(body, defaults) {
+    if (body === null || typeof body !== "object" || Array.isArray(body)) {
+        return { body, applied: [] };
+    }
+    const out = { ...body };
+    const applied = [];
+    for (const [key, value] of Object.entries(defaults)) {
+        if (value === undefined)
+            continue;
+        if (out[key] === undefined) {
+            out[key] = value;
+            applied.push(key);
+        }
+    }
+    return { body: out, applied };
+}
+function resolvePath(entry, pathParams) {
+    const missing = entry.pathParams.filter((name) => {
+        const v = pathParams[name];
+        return v === undefined || v === null || v === "";
+    });
+    if (missing.length > 0) {
+        throw new Error(`Не хватает обязательных path-параметров для ${entry.id}: ${missing.join(", ")}. ` +
+            `Передай их в объекте pathParams.`);
+    }
+    let path = entry.path;
+    for (const name of entry.pathParams) {
+        path = path.replace(`{${name}}`, encodeURIComponent(String(pathParams[name])));
+    }
+    const unresolved = path.match(/\{[^}]+\}/g);
+    if (unresolved) {
+        throw new Error(`Не удалось подставить параметры пути для ${entry.id}: остались незаменённые ${unresolved.join(", ")}. ` +
+            `Объявленные параметры: ${entry.pathParams.join(", ")}. Проверь точное написание имён (регистр может отличаться от текста в пути) через hubex_describe_endpoint.`);
+    }
+    return path;
+}
+function requestTool(group, deps) {
+    const isWrite = group === "write";
+    // DELETE в HubEx нередко удаляет пачкой и принимает список в теле запроса.
+    const acceptsBody = group === "write" || group === "delete";
+    const properties = {
+        endpointId: {
+            type: "string",
+            description: "Идентификатор вида SERVICE:METHOD:/path из hubex_search_*_endpoints или гайда.",
+        },
+        pathParams: {
+            type: "object",
+            description: "Значения параметров пути, например { \"taskID\": 42 }.",
+        },
+        query: { type: "object", description: "Query-параметры запроса." },
+    };
+    if (acceptsBody) {
+        properties.body = {
+            type: ["object", "array"],
+            description: "Тело запроса по схеме из hubex_describe_endpoint. Если в схеме body.type = array, " +
+                "передавай именно массив: обёртка вида { \"data\": [...] } уйдёт на сервер как объект, " +
+                "и HubEx ответит «Параметр [data] не может быть пустым».",
+        };
+    }
+    const defaultKeys = Object.keys(deps.config.defaults);
+    const defaultsNote = isWrite && defaultKeys.length > 0
+        ? ` Если поля ${defaultKeys.join(", ")} не заданы в body, подставляются значения из настроек сервера.`
+        : "";
+    // HEAD не возвращает тела, предупреждать там не о чем.
+    const maskNote = deps.config.maskPii && group !== "head"
+        ? " Персональные данные в ответах (ФИО, телефоны, email, адреса, логины, токены) " +
+            "маскируются звёздочками: звёздочки не являются частью реальных данных, " +
+            "и замаскированное значение нельзя использовать как аргумент следующего запроса."
+        : "";
+    return {
+        definition: {
+            name: `hubex_request_${group}`,
+            description: GROUP_DESCRIPTIONS[group] + defaultsNote + maskNote,
+            inputSchema: { type: "object", properties, required: ["endpointId"] },
+        },
+        async execute(args) {
+            try {
+                const id = String(args.endpointId ?? "").trim();
+                const entry = deps.index.get(id);
+                if (!entry) {
+                    throw new Error(`Эндпоинт ${id || "(пусто)"} не найден. Вызови hubex_search_${group}_endpoints ` +
+                        `со scope, чтобы получить корректный идентификатор.`);
+                }
+                // Рубеж 1: метод принадлежит группе этого инструмента.
+                if (!METHOD_GROUPS[group].includes(entry.method)) {
+                    throw new Error(`${entry.id} использует метод ${entry.method}, а этот инструмент выполняет только ` +
+                        `${METHOD_GROUPS[group].join("/")}. Нужный инструмент: hubex_request_${groupOf(entry.method)}.`);
+                }
+                // Рубеж 2: метод и сервис разрешены настройками сервера.
+                if (!deps.config.methods.includes(entry.method)) {
+                    throw new Error(`Метод ${entry.method} отключён настройкой HUBEX_METHODS=${deps.config.methods.join(",")} ` +
+                        `сервера (разрешены только: ${deps.config.methods.join(", ")}). Вызови hubex_search_${group}_endpoints ` +
+                        `или hubex_list_scopes, чтобы найти доступный эндпоинт с разрешённым методом.`);
+                }
+                if (!deps.index.isAllowed(entry)) {
+                    throw new Error(`Сервис ${entry.service} отключён настройкой HUBEX_SERVICES=` +
+                        `${(deps.config.services ?? []).join(",")}. Вызови hubex_list_scopes, чтобы увидеть разрешённые сервисы.`);
+                }
+                const pathParams = (args.pathParams ?? {});
+                const path = resolvePath(entry, pathParams);
+                const query = (args.query ?? undefined);
+                let body = acceptsBody ? args.body : undefined;
+                let applied = [];
+                if (acceptsBody && body === undefined && entry.bodyRequired) {
+                    throw new Error(`${entry.id} требует тело запроса. Вызови hubex_describe_endpoint с этим ` +
+                        `идентификатором, чтобы получить схему body.`);
+                }
+                // Значения по умолчанию — про создание сущностей: в теле DELETE они
+                // только исказили бы список удаляемых записей.
+                if (isWrite && body !== undefined) {
+                    const r = applyDefaults(body, deps.config.defaults);
+                    body = r.body;
+                    applied = r.applied;
+                }
+                const res = await deps.client.request({
+                    service: entry.service,
+                    method: entry.method,
+                    path,
+                    query,
+                    body,
+                });
+                if (group === "head") {
+                    return okResult({ status: res.status, endpointId: entry.id });
+                }
+                if (applied.length > 0) {
+                    return okResult({
+                        appliedDefaults: applied,
+                        status: res.status,
+                        data: res.data ?? null,
+                    });
+                }
+                // Пустое тело ответа (204/200 без содержимого) — валидный успех:
+                // отдаём статус, иначе результат инструмента оказался бы пустым.
+                if (res.data === undefined) {
+                    return okResult({ status: res.status, endpointId: entry.id, data: null });
+                }
+                return okResult(res.data);
+            }
+            catch (err) {
+                return failResult(err);
+            }
+        },
+    };
+}
+export function buildRequestTools(deps) {
+    return enabledGroups(deps.config.methods).map((group) => requestTool(group, deps));
+}

package/dist/tools/types.js

@@ -0,0 +1 @@
+export {};