@hubex/mcp 0.2.0

package/dist/guides/field-notes.json

@@ -0,0 +1,27 @@
+{
+  "taskTypeID": {
+    "description": "Тип заявки.",
+    "required": true,
+    "lookup": "WORK:GET:/TaskTypes"
+  },
+  "requestMethodID": {
+    "description": "Способ подачи заявки. Для интеграций используется значение 4.",
+    "required": true,
+    "lookup": "WORK:GET:/RequestMethods"
+  },
+  "workTypeID": { "description": "Вид работ.", "lookup": "WORK:GET:/WorkTypes" },
+  "taskStatusID": {
+    "description": "Статус заявки. Переход должен быть разрешён жизненным циклом.",
+    "lookup": "WORK:GET:/TaskStatuses"
+  },
+  "companyID": { "description": "Компания-заказчик.", "lookup": "ES:GET:/Companies" },
+  "assetID": { "description": "Объект обслуживания.", "lookup": "ES:GET:/Assets" },
+  "assetTypeID": { "description": "Тип объекта.", "lookup": "ES:GET:/AssetTypes" },
+  "assetClassID": { "description": "Класс объекта.", "lookup": "ES:GET:/AssetClasses" },
+  "locationID": { "description": "Адрес/локация.", "lookup": "ES:GET:/Locations" },
+  "userID": { "description": "Пользователь HubEx.", "lookup": "ADM:GET:/Users/short" },
+  "roleID": { "description": "Роль пользователя.", "lookup": "ADM:GET:/Roles" },
+  "notes": { "description": "Описание без HTML — показывается в списке заявок." },
+  "notesHtml": { "description": "Описание с HTML — показывается в карточке заявки." },
+  "deadline": { "description": "Крайний срок закрытия, ISO 8601." }
+}

package/dist/guides/loader.js

@@ -0,0 +1,32 @@
+/**
+ * Чтение markdown-гайдов и оверлея аннотаций полей.
+ * Гайды лежат в docs/guides и грузятся только по явному запросу.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { GUIDES_DIR } from "../paths.js";
+const NOTES_FILE = join(dirname(fileURLToPath(import.meta.url)), "field-notes.json");
+let notesCache;
+export function loadFieldNotes() {
+    if (!notesCache) {
+        notesCache = JSON.parse(readFileSync(NOTES_FILE, "utf8"));
+    }
+    return notesCache;
+}
+const guideCache = new Map();
+export function loadGuide(topic, dir = GUIDES_DIR) {
+    const cached = guideCache.get(topic);
+    if (cached)
+        return cached;
+    if (!/^[a-z]+$/.test(topic)) {
+        throw new Error(`Некорректный топик гайда: ${topic}`);
+    }
+    const file = join(dir, `${topic}.md`);
+    if (!existsSync(file)) {
+        throw new Error(`Гайд "${topic}" не найден.`);
+    }
+    const text = readFileSync(file, "utf8");
+    guideCache.set(topic, text);
+    return text;
+}

package/dist/guides/service-map.js

@@ -0,0 +1,6 @@
+/** Сервис → топик гайда, который стоит прочитать перед работой с ним. */
+export const SERVICE_GUIDES = {
+    WORK: "taskcreate",
+    ES: "assets",
+    ADM: "users",
+};

package/dist/http.js

@@ -0,0 +1,93 @@
+/**
+ * Thin HTTP client for HubEx services. Builds `{base}/fsm/{SERVICE}{path}`,
+ * injects auth + `X-Application-ID`, and normalizes responses and errors.
+ */
+import { maskPii } from "./pii/mask.js";
+export class HubexApiError extends Error {
+    status;
+    service;
+    path;
+    payload;
+    constructor(status, service, path, payload) {
+        super(HubexApiError.format(status, service, path, payload));
+        this.status = status;
+        this.service = service;
+        this.path = path;
+        this.payload = payload;
+        this.name = "HubexApiError";
+    }
+    static format(status, service, path, payload) {
+        let detail = "";
+        if (typeof payload === "string") {
+            detail = payload;
+        }
+        else if (Array.isArray(payload) && payload.length > 0) {
+            // HubEx error shape: [{ traceIdentifier, code, message }]
+            const first = payload[0];
+            detail = [first.code, first.message, first.traceIdentifier].filter(Boolean).join(" | ");
+        }
+        else if (payload && typeof payload === "object") {
+            detail = JSON.stringify(payload).slice(0, 800);
+        }
+        return `HubEx ${service} ${path} -> HTTP ${status}${detail ? `: ${detail}` : ""}`;
+    }
+}
+function buildQueryString(query) {
+    if (!query)
+        return "";
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value === undefined || value === null)
+            continue;
+        if (Array.isArray(value)) {
+            for (const v of value)
+                params.append(key, String(v));
+        }
+        else {
+            params.append(key, String(value));
+        }
+    }
+    const s = params.toString();
+    return s ? `?${s}` : "";
+}
+export class HubexClient {
+    config;
+    auth;
+    constructor(config, auth) {
+        this.config = config;
+        this.auth = auth;
+    }
+    async request(req) {
+        const token = await this.auth.getAccessToken();
+        const url = `${this.config.apiBaseUrl}/${req.service}${req.path}` + buildQueryString(req.query);
+        const headers = {
+            Authorization: `Bearer ${token}`,
+            "X-Application-ID": this.config.applicationId,
+            Accept: "application/json",
+        };
+        const init = { method: req.method, headers };
+        if (req.body !== undefined && req.method !== "GET" && req.method !== "HEAD") {
+            headers["Content-Type"] = "application/json";
+            init.body = JSON.stringify(req.body);
+        }
+        const res = await fetch(url, init);
+        const text = await res.text();
+        let data = undefined;
+        if (text) {
+            try {
+                data = JSON.parse(text);
+            }
+            catch {
+                data = text;
+            }
+        }
+        // Маскирование стоит здесь, а не в инструментах: так покрыты сразу все
+        // потребители клиента, включая текст ошибок. Авторизация ходит мимо
+        // HubexClient (src/auth.ts), поэтому токены сессии не задеваются.
+        const visible = this.config.maskPii ? maskPii(data) : data;
+        if (!res.ok) {
+            throw new HubexApiError(res.status, req.service, req.path, visible ?? text);
+        }
+        return { status: res.status, data: visible };
+    }
+}

package/dist/index/store.js

@@ -0,0 +1,134 @@
+/**
+ * Индекс эндпоинтов в памяти: фильтрация по разрешённым методам и сервисам,
+ * перечисление скоупов и поиск. Полные схемы здесь не хранятся.
+ */
+import { readFileSync } from "node:fs";
+export const DEFAULT_SEARCH_LIMIT = 30;
+export const MAX_SEARCH_LIMIT = 100;
+export function loadIndexFile(file) {
+    return JSON.parse(readFileSync(file, "utf8"));
+}
+export class EndpointIndex {
+    data;
+    byId = new Map();
+    allowedMethods;
+    allowedServices;
+    constructor(data, opts) {
+        this.data = data;
+        this.allowedMethods = new Set(opts.methods);
+        if (opts.services) {
+            const known = new Set(data.services.map((s) => s.code));
+            const unknown = opts.services.filter((s) => !known.has(s));
+            if (unknown.length > 0) {
+                throw new Error(`HUBEX_SERVICES содержит неизвестный сервис(ы): ${unknown.join(", ")}. ` +
+                    `Известные сервисы: ${[...known].sort().join(", ")}. Проверь переменную окружения HUBEX_SERVICES.`);
+            }
+            this.allowedServices = new Set(opts.services);
+        }
+        for (const e of data.endpoints)
+            this.byId.set(e.id, e);
+    }
+    isAllowed(entry) {
+        if (!this.allowedMethods.has(entry.method))
+            return false;
+        if (this.allowedServices && !this.allowedServices.has(entry.service))
+            return false;
+        return true;
+    }
+    isServiceAllowed(code) {
+        return !this.allowedServices || this.allowedServices.has(code);
+    }
+    get(id) {
+        return this.byId.get(id);
+    }
+    listServices() {
+        const out = [];
+        for (const svc of this.data.services) {
+            if (!this.isServiceAllowed(svc.code))
+                continue;
+            const counts = this.countMethods(this.data.endpoints.filter((e) => e.service === svc.code && this.isAllowed(e)));
+            if (Object.keys(counts).length === 0)
+                continue;
+            out.push({ code: svc.code, title: svc.title, description: svc.description, counts });
+        }
+        return out;
+    }
+    listTags(service) {
+        const code = service.toUpperCase();
+        if (!this.data.services.some((s) => s.code === code)) {
+            throw new Error(`Неизвестный сервис: ${service}. Вызови hubex_list_scopes без аргументов, чтобы увидеть список.`);
+        }
+        if (!this.isServiceAllowed(code)) {
+            throw new Error(`Сервис ${code} отключён настройкой HUBEX_SERVICES. Вызови hubex_list_scopes без аргументов, чтобы увидеть список доступных сервисов.`);
+        }
+        const groups = new Map();
+        for (const e of this.data.endpoints) {
+            if (e.service !== code || !this.isAllowed(e))
+                continue;
+            for (const tag of e.tags.length > 0 ? e.tags : ["(без тега)"]) {
+                const list = groups.get(tag) ?? [];
+                list.push(e);
+                groups.set(tag, list);
+            }
+        }
+        return [...groups.entries()]
+            .sort((a, b) => a[0].localeCompare(b[0]))
+            .map(([tag, entries]) => ({ tag, counts: this.countMethods(entries) }));
+    }
+    search(opts) {
+        const groupMethods = new Set(opts.methods.filter((m) => this.allowedMethods.has(m)));
+        const scope = opts.scope?.toUpperCase();
+        const tag = opts.tag?.toLowerCase();
+        const tokens = (opts.query ?? "")
+            .toLowerCase()
+            .split(/\s+/)
+            .filter((t) => t !== "");
+        const limit = Math.min(Math.max(opts.limit ?? DEFAULT_SEARCH_LIMIT, 1), MAX_SEARCH_LIMIT);
+        const scored = [];
+        for (const entry of this.data.endpoints) {
+            if (!groupMethods.has(entry.method))
+                continue;
+            if (!this.isAllowed(entry))
+                continue;
+            if (scope && entry.service !== scope)
+                continue;
+            if (tag && !entry.tags.some((t) => t.toLowerCase() === tag))
+                continue;
+            const score = scoreEntry(entry, tokens);
+            if (score === null)
+                continue;
+            scored.push({ entry, score });
+        }
+        scored.sort((a, b) => b.score - a.score || a.entry.id.localeCompare(b.entry.id));
+        return { results: scored.slice(0, limit).map((s) => s.entry), total: scored.length };
+    }
+    countMethods(entries) {
+        const counts = {};
+        for (const e of entries)
+            counts[e.method] = (counts[e.method] ?? 0) + 1;
+        return counts;
+    }
+}
+/**
+ * Все токены запроса должны найтись хотя бы в одном из полей.
+ * Вес совпадения: путь > тег > summary — путь на английском и обычно точнее.
+ */
+function scoreEntry(entry, tokens) {
+    if (tokens.length === 0)
+        return 0;
+    const path = entry.path.toLowerCase();
+    const tags = entry.tags.join(" ").toLowerCase();
+    const summary = entry.summary.toLowerCase();
+    let total = 0;
+    for (const token of tokens) {
+        if (path.includes(token))
+            total += 3;
+        else if (tags.includes(token))
+            total += 2;
+        else if (summary.includes(token))
+            total += 1;
+        else
+            return null;
+    }
+    return total;
+}

package/dist/index/types.js

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

package/dist/index.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * Entry point: load config and serve HubEx tools over stdio.
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config.js";
+import { createServer } from "./server.js";
+async function main() {
+    const config = loadConfig();
+    const server = createServer(config);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Log to stderr only — stdout is the MCP protocol channel.
+    console.error(`[hubex-mcp] connected. env=${config.env} tenant=${config.tenantId ?? "(from token)"} ` +
+        `authMode=${config.authMode} readonly=${config.readonly}`);
+}
+main().catch((err) => {
+    console.error("[hubex-mcp] fatal:", err instanceof Error ? err.message : err);
+    process.exit(1);
+});

package/dist/paths.js

@@ -0,0 +1,20 @@
+/**
+ * Расположение файлов данных относительно корня пакета.
+ * Работает и из `src/` (tsx), и из `dist/` (сборка): оба лежат на один уровень
+ * ниже корня, поэтому `..` от каталога этого модуля указывает на корень.
+ */
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+export const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+export const GENERATED_DIR = join(PACKAGE_ROOT, "generated");
+/** Корень кэша swagger; сами схемы лежат в подкаталоге каталога (dev/prod). */
+export const SWAGGER_ROOT = join(PACKAGE_ROOT, "swagger");
+export const GUIDES_DIR = join(PACKAGE_ROOT, "docs", "guides");
+/** Каталог swagger-схем одного контура: swagger/dev или swagger/prod. */
+export function swaggerDirFor(catalog) {
+    return join(SWAGGER_ROOT, catalog);
+}
+/** Индекс эндпоинтов одного контура: generated/index.dev.json или index.prod.json. */
+export function indexFileFor(catalog) {
+    return join(GENERATED_DIR, `index.${catalog}.json`);
+}

package/dist/pii/fields.js

@@ -0,0 +1,100 @@
+/**
+ * Реестр имён полей, которые считаются персональными данными, и тип маски
+ * для каждого. Поиск идёт по имени ключа JSON, а не по значению: это
+ * работает на любых формах ответов HubEx и не зависит от swagger-схем.
+ */
+/**
+ * Ключи хранятся в нижнем регистре: имена полей в разных сервисах HubEx
+ * отличаются регистром (`email` / `eMail`, `coordinate` / `Coordinate`).
+ */
+const FIELDS = {
+    // Части ФИО
+    firstname: "name",
+    middlename: "name",
+    lastname: "name",
+    leadfirstname: "name",
+    leadmiddlename: "name",
+    leadlastname: "name",
+    ownerfirstname: "name",
+    ownermiddlename: "name",
+    ownerlastname: "name",
+    membername: "name",
+    // ФИО целиком (несколько слов в одной строке)
+    fullname: "fullName",
+    managerfullname: "fullName",
+    userfullname: "fullName",
+    tenantfullname: "fullName",
+    signatory: "fullName",
+    // По swagger эти поля содержат ФИО целиком («Иванов Иван Иванович»),
+    // в ссылочной форме {id, name} — там же, под ключом name.
+    contactperson: "fullName",
+    responsibleperson: "fullName",
+    acceptedperson: "fullName",
+    customassetresponsibleperson: "fullName",
+    // Почта
+    email: "email",
+    // Защитная запись: в swagger-схемах HubEx поле не встречается.
+    emails: "email",
+    contactemail: "email",
+    manageremail: "email",
+    supportemail: "email",
+    customemaillist: "email",
+    recipient: "email",
+    lastrecipient: "email",
+    // Телефоны
+    phone: "phone",
+    phone1: "phone",
+    phone2: "phone",
+    phone01: "phone",
+    phone02: "phone",
+    phone03: "phone",
+    mobilephone: "phone",
+    workphone: "phone",
+    otherphone: "phone",
+    contactphone: "phone",
+    managerphone: "phone",
+    supportphone: "phone",
+    customphonelist: "phone",
+    // Адреса
+    address: "address",
+    lawaddress: "address",
+    postaddress: "address",
+    registeredoffice: "address",
+    // Секреты: маскируются целиком, длина не сохраняется
+    password: "secret",
+    currentpassword: "secret",
+    // Защитная запись: в swagger-схемах HubEx поле не встречается.
+    newpassword: "secret",
+    token: "secret",
+    tokens: "secret",
+    access_token: "secret",
+    refresh_token: "secret",
+    refreshtoken: "secret",
+    servicetoken: "secret",
+    onetimelogintoken: "secret",
+    pushtoken: "secret",
+    verificationcodehash: "secret",
+    codehash: "secret",
+    // Ссылка на фото
+    avatarurl: "url",
+    // Логины и прочие идентификаторы физлица
+    login: "misc",
+    domainlogin: "misc",
+    accountdomainlogin: "misc",
+    personnelnumber: "misc",
+    inn: "misc",
+    tin: "misc",
+    credentials: "misc",
+    checkingaccount: "misc",
+    correspondingaccount: "misc",
+    // Координаты: числа, огрубляются вместо замены звёздочками
+    latitude: "geo",
+    longitude: "geo",
+    // Строковые координаты вида «55.7558, 37.6173» и «LAT:LNG».
+    coordinate: "geo",
+    center: "geo",
+};
+/** Тип маски для имени поля, либо undefined, если поле не является ПДн. */
+export function lookupPiiField(key) {
+    return FIELDS[key.toLowerCase()];
+}

package/dist/pii/mask.js

@@ -0,0 +1,50 @@
+/**
+ * Рекурсивный обход разобранного JSON-ответа HubEx: каждое поле, чьё имя
+ * числится в реестре ПДн, заменяется маской. Решение принимается по имени
+ * ключа, поэтому обход одинаково работает на словарях `{"1": {...}}`,
+ * массивах и произвольной вложенности.
+ */
+import { lookupPiiField } from "./fields.js";
+import { maskValue } from "./strategies.js";
+/** Предохранитель от аномально глубоких ответов. */
+const MAX_DEPTH = 32;
+/**
+ * Ключи-обёртки ссылочной формы `{id, name}` (`IdNameResult`): под ними лежит
+ * значение родительского поля. Сами по себе они не ПДн — `name` подписывает и
+ * типы задач, и страны, — поэтому маска переносится только от PII-родителя.
+ */
+const WRAPPER_KEYS = new Set(["name", "value"]);
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Присвоение через defineProperty: обычное `out[key]` на `__proto__` теряет данные. */
+function setOwn(out, key, value) {
+    Object.defineProperty(out, key, { value, enumerable: true, writable: true, configurable: true });
+}
+/**
+ * `kind` — маска, унаследованная от PII-поля-родителя. Она передаётся сквозь
+ * массивы и ровно на один уровень вглубь объекта.
+ */
+function walk(data, depth, kind) {
+    // Предохранитель обязан срабатывать в безопасную сторону: ниже предела
+    // данные не проверены на ПДн, поэтому наружу уходит маска, а не оригинал.
+    if (depth > MAX_DEPTH)
+        return "***";
+    if (Array.isArray(data)) {
+        return data.map((item) => walk(item, depth + 1, kind));
+    }
+    if (!isPlainObject(data)) {
+        return kind === undefined ? data : maskValue(data, kind);
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(data)) {
+        const own = lookupPiiField(key);
+        const inherited = kind !== undefined && WRAPPER_KEYS.has(key.toLowerCase()) ? kind : undefined;
+        setOwn(out, key, walk(value, depth + 1, own ?? inherited));
+    }
+    return out;
+}
+/** Вернуть копию `data`, в которой все известные поля с ПДн замаскированы. */
+export function maskPii(data) {
+    return walk(data, 0, undefined);
+}

package/dist/pii/strategies.js

@@ -0,0 +1,88 @@
+/**
+ * Стратегии маскирования одиночных значений. Каждая сохраняет ровно столько
+ * контекста, сколько нужно, чтобы человек узнал запись, но не смог по ней
+ * идентифицировать субъекта.
+ */
+/** Первая буква + звёздочки по длине остатка. Односимвольное значение — одна звёздочка. */
+function keepFirst(value) {
+    if (value.length <= 1)
+        return "*";
+    return value[0] + "*".repeat(value.length - 1);
+}
+/** Каждое слово маскируется отдельно; лишние пробелы схлопываются. */
+function maskFullName(value) {
+    return value.trim().split(/\s+/).map(keepFirst).join(" ");
+}
+/** Логин → первая буква; домен → все метки, кроме TLD. */
+function maskEmail(value) {
+    const at = value.lastIndexOf("@");
+    if (at <= 0 || at === value.length - 1)
+        return keepFirst(value);
+    const local = value.slice(0, at);
+    const labels = value.slice(at + 1).split(".");
+    const domain = labels.length === 1
+        ? keepFirst(labels[0])
+        : labels
+            .map((label, i) => (i === labels.length - 1 ? label : keepFirst(label)))
+            .join(".");
+    return `${keepFirst(local)}@${domain}`;
+}
+/** Ведущий «+» и две последние цифры остаются, всё между ними — звёздочки. */
+function maskPhone(value) {
+    const plus = value.startsWith("+");
+    const rest = plus ? value.slice(1) : value;
+    if (rest.length <= 2)
+        return (plus ? "+" : "") + "*".repeat(rest.length || 1);
+    const tail = rest.slice(-2);
+    return (plus ? "+" : "") + "*".repeat(rest.length - 2) + tail;
+}
+/** Остаётся только населённый пункт — часть до первой запятой. */
+function maskAddress(value) {
+    const comma = value.indexOf(",");
+    if (comma <= 0)
+        return "***";
+    return `${value.slice(0, comma).trim()}, ***`;
+}
+/** Огрубление координаты до ~1 км. */
+function maskGeo(value) {
+    return Math.round(value * 100) / 100;
+}
+/**
+ * Координата в виде строки («55.7558, 37.6173», «55.7558:37.6173»): каждое
+ * число огрубляется, разделители сохраняются. Строка без чисел координатой
+ * не является, поэтому маскируется целиком — так безопаснее.
+ */
+function maskGeoString(value) {
+    if (!/\d/.test(value))
+        return "***";
+    return value.replace(/-?\d+(?:\.\d+)?/g, (num) => String(maskGeo(Number(num))));
+}
+/**
+ * Замаскировать скалярное значение по типу маски. Значения, к которым маска
+ * неприменима (не строка и не число для geo), возвращаются без изменений:
+ * решение принимается по имени поля, а тип значения может оказаться любым.
+ */
+export function maskValue(value, kind) {
+    if (kind === "geo" && typeof value === "number")
+        return maskGeo(value);
+    if (typeof value !== "string" || value === "")
+        return value;
+    switch (kind) {
+        case "secret":
+        case "url":
+            return "***";
+        case "fullName":
+            return maskFullName(value);
+        case "email":
+            return maskEmail(value);
+        case "phone":
+            return maskPhone(value);
+        case "address":
+            return maskAddress(value);
+        case "geo":
+            return maskGeoString(value);
+        case "name":
+        case "misc":
+            return keepFirst(value);
+    }
+}

package/dist/schema/build-index.js

@@ -0,0 +1,67 @@
+/**
+ * Build-time сборка тонкого индекса всех эндпоинтов из кэша swagger.
+ * В индекс попадают только сигнатуры — развёрнутые схемы тела достаёт
+ * SchemaProvider по требованию.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ALL_METHODS } from "../config.js";
+import { resolvePointer } from "./deref.js";
+export function buildIndex(swaggerDir) {
+    const services = [];
+    const endpoints = [];
+    const files = readdirSync(swaggerDir)
+        .filter((f) => f.endsWith(".json"))
+        .sort();
+    for (const file of files) {
+        const code = file.replace(/\.json$/, "").toUpperCase();
+        const doc = JSON.parse(readFileSync(join(swaggerDir, file), "utf8"));
+        services.push({
+            code,
+            title: doc.info?.title ?? code,
+            description: doc.info?.description ?? "",
+        });
+        for (const [path, pathItem] of Object.entries(doc.paths ?? {})) {
+            for (const [rawMethod, op] of Object.entries(pathItem)) {
+                const method = rawMethod.toUpperCase();
+                if (!ALL_METHODS.includes(method))
+                    continue; // parameters, options, trace
+                endpoints.push(buildEntry(code, method, path, op, doc));
+            }
+        }
+    }
+    services.sort((a, b) => (a.code < b.code ? -1 : a.code > b.code ? 1 : 0));
+    endpoints.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    return { services, endpoints };
+}
+function buildEntry(service, method, path, op, doc) {
+    const pathParams = [];
+    const queryParams = [];
+    const seen = new Set();
+    for (const raw of (op.parameters ?? [])) {
+        const param = raw.$ref ? (resolvePointer(doc, raw.$ref) ?? {}) : raw;
+        if (param.in !== "path" && param.in !== "query")
+            continue; // header/cookie ставит клиент
+        if (seen.has(param.name))
+            continue; // swagger иногда дублирует параметр
+        seen.add(param.name);
+        (param.in === "path" ? pathParams : queryParams).push(param.name);
+    }
+    const bodySchema = op.requestBody?.content?.["application/json"]?.schema;
+    return {
+        id: `${service}:${method}:${path}`,
+        service,
+        method,
+        path,
+        summary: op.summary || op.description || `${method} ${path}`,
+        tags: Array.isArray(op.tags) ? [...op.tags] : [],
+        pathParams,
+        queryParams,
+        hasBody: Boolean(bodySchema),
+        bodyRequired: Boolean(bodySchema) && op.requestBody?.required === true,
+    };
+}
+/** Стабильная сериализация: два прогона дают побайтово одинаковый результат. */
+export function serializeIndex(index) {
+    return JSON.stringify(index, null, 2) + "\n";
+}