@hubex/mcp 0.2.0

package/dist/schema/deref.js

@@ -0,0 +1,87 @@
+/**
+ * Разворачивание OpenAPI-схем в плоский JSON Schema с защитой от циклических
+ * `$ref` и от чрезмерной глубины. Используется генератором индекса и рантайм-
+ * инструментом describe_endpoint.
+ */
+const SCALAR_KEYS = [
+    "type", "format", "enum", "description", "nullable",
+    "minimum", "maximum", "minLength", "maxLength", "pattern", "default", "example",
+];
+export function resolvePointer(doc, ref) {
+    if (!ref.startsWith("#/"))
+        return undefined;
+    const parts = ref.slice(2).split("/");
+    let cur = doc;
+    for (const p of parts) {
+        cur = cur?.[decodeURIComponent(p.replace(/~1/g, "/").replace(/~0/g, "~"))];
+        if (cur === undefined)
+            return undefined;
+    }
+    return cur;
+}
+/**
+ * Dereference an OpenAPI schema node into a plain JSON Schema, guarding against
+ * recursive `$ref` cycles and runaway depth.
+ */
+export function deref(node, doc, stack = new Set(), depth = 0) {
+    if (!node || depth > 25)
+        return { type: "object" };
+    if (node.$ref) {
+        const ref = node.$ref;
+        if (stack.has(ref))
+            return { type: "object", description: "(recursive reference omitted)" };
+        const target = resolvePointer(doc, ref);
+        if (!target)
+            return { type: "object" };
+        const nextStack = new Set(stack);
+        nextStack.add(ref);
+        return deref(target, doc, nextStack, depth + 1);
+    }
+    // allOf → merge object subschemas.
+    if (Array.isArray(node.allOf)) {
+        const merged = { type: "object", properties: {}, required: [] };
+        for (const sub of node.allOf) {
+            const r = deref(sub, doc, stack, depth + 1);
+            if (r.properties)
+                Object.assign(merged.properties, r.properties);
+            if (Array.isArray(r.required))
+                merged.required.push(...r.required);
+            if (r.description && !merged.description)
+                merged.description = r.description;
+        }
+        if (merged.required.length === 0)
+            delete merged.required;
+        if (Object.keys(merged.properties).length === 0)
+            delete merged.properties;
+        return merged;
+    }
+    const out = {};
+    for (const k of SCALAR_KEYS) {
+        if (node[k] !== undefined)
+            out[k] = node[k];
+    }
+    if (node.oneOf || node.anyOf) {
+        // Keep it simple for LLM consumption: fall back to first alternative's shape.
+        const alt = (node.oneOf ?? node.anyOf)[0];
+        return { ...out, ...deref(alt, doc, stack, depth + 1) };
+    }
+    if (node.properties) {
+        out.type = out.type ?? "object";
+        out.properties = {};
+        for (const [key, child] of Object.entries(node.properties)) {
+            out.properties[key] = deref(child, doc, stack, depth + 1);
+        }
+        if (Array.isArray(node.required))
+            out.required = node.required;
+    }
+    if (node.items) {
+        out.type = out.type ?? "array";
+        out.items = deref(node.items, doc, stack, depth + 1);
+    }
+    if (node.additionalProperties && typeof node.additionalProperties === "object") {
+        out.additionalProperties = deref(node.additionalProperties, doc, stack, depth + 1);
+    }
+    if (!out.type && !out.properties && !out.items && !out.enum)
+        out.type = "object";
+    return out;
+}

package/dist/schema/describe.js

@@ -0,0 +1,65 @@
+/**
+ * Ленивая выдача полной JSON Schema одного эндпоинта. Swagger читается по
+ * требованию и кэшируется на процесс: индекс дёшев, схемы — нет.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { deref, resolvePointer } from "./deref.js";
+export class SchemaProvider {
+    swaggerDir;
+    cache = new Map();
+    constructor(swaggerDir) {
+        this.swaggerDir = swaggerDir;
+    }
+    /** Сервисы, чей swagger уже прочитан (для тестов и диагностики). */
+    loadedServices() {
+        return [...this.cache.keys()].sort();
+    }
+    describe(entry) {
+        const doc = this.load(entry.service);
+        const op = doc.paths?.[entry.path]?.[entry.method.toLowerCase()];
+        if (!op) {
+            throw new Error(`Эндпоинт ${entry.id} есть в индексе, но отсутствует в swagger. Перегенерируй индекс: npm run generate`);
+        }
+        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;
+            if (seen.has(param.name))
+                continue;
+            seen.add(param.name);
+            const schema = deref(param.schema ?? { type: "string" }, doc);
+            if (param.description)
+                schema.description = param.description;
+            (param.in === "path" ? pathParams : queryParams)[param.name] = schema;
+        }
+        const bodySchema = op.requestBody?.content?.["application/json"]?.schema;
+        return {
+            id: entry.id,
+            service: entry.service,
+            method: entry.method,
+            path: entry.path,
+            summary: entry.summary,
+            pathParams,
+            queryParams,
+            body: bodySchema ? deref(bodySchema, doc) : undefined,
+            bodyRequired: Boolean(bodySchema) && op.requestBody?.required === true,
+        };
+    }
+    load(service) {
+        const cached = this.cache.get(service);
+        if (cached)
+            return cached;
+        const file = join(this.swaggerDir, `${service}.json`);
+        if (!existsSync(file)) {
+            throw new Error(`Нет кэша swagger для сервиса ${service}: ожидался файл ${file}. ` +
+                `Либо добавь файл в каталог swagger/, либо исключи сервис ${service} из HUBEX_SERVICES.`);
+        }
+        const doc = JSON.parse(readFileSync(file, "utf8"));
+        this.cache.set(service, doc);
+        return doc;
+    }
+}

package/dist/server.js

@@ -0,0 +1,62 @@
+/**
+ * MCP server wiring: exposes the tool registry over the Model Context Protocol.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { createAuthProvider } from "./auth.js";
+import { createElicitPrompter } from "./token-prompt.js";
+import { HubexClient } from "./http.js";
+import { EndpointIndex, loadIndexFile } from "./index/store.js";
+import { SchemaProvider } from "./schema/describe.js";
+import { buildRegistry } from "./tools/registry.js";
+import { PACKAGE_ROOT, indexFileFor, swaggerDirFor } from "./paths.js";
+/** Версия сервера = версия пакета: одна точка правды при релизе. */
+function packageVersion() {
+    const pkg = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8"));
+    return pkg.version ?? "0.0.0";
+}
+export function createServer(config) {
+    const auth = createAuthProvider(config);
+    const client = new HubexClient(config, auth);
+    const index = new EndpointIndex(loadIndexFile(indexFileFor(config.swaggerCatalog)), {
+        methods: config.methods,
+        services: config.services,
+    });
+    const schemas = new SchemaProvider(swaggerDirFor(config.swaggerCatalog));
+    const registry = buildRegistry({
+        client,
+        config,
+        auth,
+        index,
+        schemas,
+    });
+    const server = new Server({ name: "hubex-mcp", version: packageVersion() }, { capabilities: { tools: {} } });
+    // Провайдер создаётся раньше сервера, поэтому способ ввода вносится сюда, а не в конструктор.
+    if (config.authMode === "token")
+        auth.setPrompter(createElicitPrompter(server));
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [...registry.values()].map((t) => ({
+            name: t.definition.name,
+            description: t.definition.description,
+            inputSchema: t.definition.inputSchema,
+        })),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const tool = registry.get(req.params.name);
+        if (!tool) {
+            return {
+                content: [{ type: "text", text: `Unknown tool: ${req.params.name}` }],
+                isError: true,
+            };
+        }
+        const args = (req.params.arguments ?? {});
+        const result = await tool.execute(args);
+        return {
+            content: [{ type: "text", text: result.text }],
+            isError: result.isError ?? false,
+        };
+    });
+    return server;
+}

package/dist/token-prompt.js

@@ -0,0 +1,41 @@
+/**
+ * Asking the user for an access token in `HUBEX_AUTH_MODE=token`.
+ *
+ * The primary channel is MCP elicitation: the client shows an input field and
+ * the token never passes through the model's context. Clients without that
+ * capability fall back to the `hubex_set_token` tool.
+ */
+export const SET_TOKEN_TOOL = "hubex_set_token";
+const PROMPT_MESSAGE = "Нужен доступ к HubEx. Вставь access-токен (JWT без префикса «Bearer ») — " +
+    "по нему будет получен refresh-токен, дальше сессия продлевается сама.";
+export function createElicitPrompter(server) {
+    return async () => {
+        if (!server.getClientCapabilities()?.elicitation) {
+            throw new Error("Клиент не поддерживает интерактивный ввод (elicitation). " +
+                `Вызови инструмент ${SET_TOKEN_TOOL} и передай access-токен HubEx.`);
+        }
+        const result = await server.elicitInput({
+            message: PROMPT_MESSAGE,
+            requestedSchema: {
+                type: "object",
+                properties: {
+                    token: {
+                        type: "string",
+                        title: "Access-токен HubEx",
+                        description: "JWT без префикса «Bearer ».",
+                        minLength: 1,
+                    },
+                },
+                required: ["token"],
+            },
+        });
+        if (result.action !== "accept") {
+            throw new Error("Ввод токена отменён — авторизоваться в HubEx не удалось.");
+        }
+        const token = result.content?.token;
+        if (typeof token !== "string" || token.trim() === "") {
+            throw new Error("Токен не введён.");
+        }
+        return token.trim();
+    };
+}

package/dist/tools/curated.js

@@ -0,0 +1,151 @@
+/**
+ * Hand-written convenience tools layered on top of the generated ones.
+ */
+import { decodeJwt } from "../auth.js";
+import { SET_TOKEN_TOOL } from "../token-prompt.js";
+import { okResult, failResult } from "./registry.js";
+/** Marker prepended to test data so it is easy to find and clean up later. */
+export const TEST_MARKER = "[MCP-TEST]";
+function whoami(config, auth) {
+    return {
+        definition: {
+            name: "hubex_whoami",
+            description: "Показать текущую конфигурацию подключения к HubEx: окружение, tenant, режим авторизации и срок действия токена. Полезно для диагностики перед работой с данными.",
+            inputSchema: { type: "object", properties: {} },
+        },
+        async execute() {
+            try {
+                const token = await auth.getAccessToken();
+                const claims = decodeJwt(token);
+                const exp = claims?.exp ? new Date(claims.exp * 1000).toISOString() : undefined;
+                return okResult({
+                    env: config.env,
+                    apiBaseUrl: config.apiBaseUrl,
+                    applicationId: config.applicationId,
+                    authMode: config.authMode,
+                    readonly: config.readonly,
+                    maskPii: config.maskPii,
+                    tenantId: auth.getTenantId(),
+                    account: claims?.sub,
+                    accountId: claims?.AccountID,
+                    tenantMemberId: claims?.TenantMemberID,
+                    tokenExpiresAt: exp,
+                    tokenExpired: exp ? Date.now() >= claims.exp * 1000 : undefined,
+                });
+            }
+            catch (err) {
+                return failResult(err);
+            }
+        },
+    };
+}
+/**
+ * Fallback for clients without elicitation support: the token arrives as a tool
+ * argument instead of through an input field.
+ */
+function setToken(auth) {
+    return {
+        definition: {
+            name: SET_TOKEN_TOOL,
+            description: "Передать access-токен HubEx (JWT без префикса «Bearer »). Нужен, если клиент не умеет " +
+                "запрашивать ввод сам: попроси токен у пользователя и передай его сюда. По токену будет " +
+                "получен refresh-токен, дальше сессия продлевается автоматически.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    token: { type: "string", description: "Access-токен HubEx (JWT), без префикса «Bearer »." },
+                },
+                required: ["token"],
+            },
+        },
+        async execute(args) {
+            try {
+                await auth.acceptToken(String(args.token ?? ""));
+                const claims = decodeJwt(await auth.getAccessToken());
+                return okResult({
+                    ok: true,
+                    tenantId: auth.getTenantId(),
+                    account: claims?.sub,
+                    tokenExpiresAt: claims?.exp ? new Date(claims.exp * 1000).toISOString() : undefined,
+                });
+            }
+            catch (err) {
+                return failResult(err);
+            }
+        },
+    };
+}
+function createTestTask(client, config) {
+    return {
+        definition: {
+            name: "hubex_create_test_task",
+            description: `Создать ТЕСТОВУЮ заявку в HubEx с разумными дефолтами. К тексту заявки автоматически ` +
+                `добавляется префикс "${TEST_MARKER}", чтобы её было легко найти и удалить. (изменяет данные)`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    notes: { type: "string", description: "Текст/описание заявки." },
+                    taskTypeID: {
+                        type: "integer",
+                        description: "ID типа заявки (список: hubex_request_read с endpointId WORK:GET:/TaskTypes).",
+                    },
+                    workTypeID: {
+                        type: "integer",
+                        description: "ID вида работ (список: hubex_request_read с endpointId WORK:GET:/WorkTypes).",
+                    },
+                    assetID: { type: "integer", description: "ID объекта, к которому относится заявка." },
+                    companyID: { type: "integer", description: "ID компании-заказчика." },
+                    criticalityID: { type: "integer", description: "ID критичности." },
+                    contactPerson: { type: "string", description: "Контактное лицо." },
+                    contactPhone: { type: "string", description: "Контактный телефон." },
+                    requestMethodID: {
+                        type: "integer",
+                        description: "ID способа подачи (список: hubex_request_read с endpointId WORK:GET:/RequestMethods). " +
+                            "По умолчанию 1 (WEB), если не настроен HUBEX_DEFAULT_REQUEST_METHOD_ID.",
+                    },
+                },
+                required: ["notes"],
+            },
+        },
+        async execute(args) {
+            try {
+                const notes = String(args.notes ?? "").trim();
+                const body = {
+                    notes: `${TEST_MARKER} ${notes}`.trim(),
+                    // Приоритет: явный аргумент модели > серверный дефолт (HUBEX_DEFAULT_*) > встроенный дефолт.
+                    requestMethodID: args.requestMethodID ?? config.defaults.requestMethodID ?? 1,
+                };
+                const taskTypeID = args.taskTypeID ?? config.defaults.taskTypeID;
+                if (taskTypeID !== undefined)
+                    body.taskTypeID = taskTypeID;
+                const companyID = args.companyID ?? config.defaults.companyID;
+                if (companyID !== undefined)
+                    body.companyID = companyID;
+                for (const key of [
+                    "workTypeID",
+                    "assetID",
+                    "criticalityID",
+                    "contactPerson",
+                    "contactPhone",
+                ]) {
+                    if (args[key] !== undefined)
+                        body[key] = args[key];
+                }
+                const res = await client.request({ service: "WORK", method: "POST", path: "/Tasks", body });
+                return okResult(res.data);
+            }
+            catch (err) {
+                return failResult(err);
+            }
+        },
+    };
+}
+export function buildCuratedTools(client, config, auth) {
+    const tools = [whoami(config, auth)];
+    if (config.authMode === "token")
+        tools.push(setToken(auth));
+    if (config.methods.includes("POST") && (!config.services || config.services.includes("WORK"))) {
+        tools.push(createTestTask(client, config));
+    }
+    return tools;
+}

package/dist/tools/discovery.js

@@ -0,0 +1,187 @@
+/**
+ * Ступени лестницы подгрузки: карта скоупов, поиск по методам, описание схемы.
+ * Поиск разделён по группам HTTP-методов, чтобы группу можно было выключить
+ * настройкой сервера или тумблером в MCP-клиенте.
+ */
+import { DEFAULT_SEARCH_LIMIT, MAX_SEARCH_LIMIT } from "../index/store.js";
+import { SERVICE_GUIDES } from "../guides/service-map.js";
+import { okResult, failResult } from "./registry.js";
+export const METHOD_GROUPS = {
+    read: ["GET"],
+    write: ["POST", "PUT", "PATCH"],
+    delete: ["DELETE"],
+    head: ["HEAD"],
+};
+const GROUP_LABELS = {
+    read: "чтения (GET)",
+    write: "создания и изменения (POST/PUT/PATCH) — изменяет данные",
+    delete: "удаления (DELETE) — удаляет данные",
+    head: "проверки существования (HEAD)",
+};
+export const MAX_DESCRIBE_IDS = 5;
+/** Группы, у которых хотя бы один метод разрешён конфигом. */
+export function enabledGroups(methods) {
+    const allowed = new Set(methods);
+    return Object.keys(METHOD_GROUPS).filter((g) => METHOD_GROUPS[g].some((m) => allowed.has(m)));
+}
+export function formatSearchResults(result) {
+    if (result.total === 0) {
+        return "Ничего не найдено. Попробуй другой query, убери tag или вызови hubex_list_scopes, чтобы увидеть доступные сервисы.";
+    }
+    const lines = result.results.map((e) => {
+        const parts = [];
+        if (e.pathParams.length > 0)
+            parts.push(`path: ${e.pathParams.join(", ")}`);
+        if (e.queryParams.length > 0)
+            parts.push(`query: ${e.queryParams.join(", ")}`);
+        if (e.hasBody)
+            parts.push(e.bodyRequired ? "body: обязателен" : "body: опционален");
+        const suffix = parts.length > 0 ? ` [${parts.join("; ")}]` : "";
+        return `${e.id} — ${e.summary}${suffix}`;
+    });
+    if (result.results.length < result.total) {
+        lines.push(`— показано ${result.results.length} из ${result.total}; уточни query или tag, либо увеличь limit (максимум ${MAX_SEARCH_LIMIT}).`);
+    }
+    return lines.join("\n");
+}
+function listScopes(deps) {
+    return {
+        definition: {
+            name: "hubex_list_scopes",
+            description: "Карта доступных областей HubEx. Без аргументов — список сервисов с числом эндпоинтов по методам. " +
+                "С аргументом service — ресурсы (теги) внутри сервиса. Первый шаг перед hubex_search_*_endpoints.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    service: {
+                        type: "string",
+                        description: "Код сервиса, например WORK. Опционально: без него вернётся список сервисов.",
+                    },
+                },
+            },
+        },
+        async execute(args) {
+            try {
+                const service = args.service === undefined ? undefined : String(args.service);
+                if (!service) {
+                    const lines = deps.index.listServices().map((s) => {
+                        const counts = Object.entries(s.counts)
+                            .map(([m, n]) => `${m} ${n}`)
+                            .join(", ");
+                        const guide = SERVICE_GUIDES[s.code];
+                        return (`${s.code} — ${s.title} [${counts}]` +
+                            (guide ? ` (гайд: hubex_get_guide topic="${guide}")` : ""));
+                    });
+                    lines.push("— дальше: hubex_list_scopes с service=<КОД> для списка ресурсов, либо hubex_search_*_endpoints.");
+                    return okResult(lines.join("\n"));
+                }
+                const lines = deps.index.listTags(service).map((t) => {
+                    const counts = Object.entries(t.counts)
+                        .map(([m, n]) => `${m} ${n}`)
+                        .join(", ");
+                    return `${t.tag} [${counts}]`;
+                });
+                lines.push(`— дальше: hubex_search_*_endpoints со scope="${service.toUpperCase()}" и tag=<ресурс>.`);
+                return okResult(lines.join("\n"));
+            }
+            catch (err) {
+                return failResult(err);
+            }
+        },
+    };
+}
+function searchTool(group, deps) {
+    return {
+        definition: {
+            name: `hubex_search_${group}_endpoints`,
+            description: `Найти эндпоинты HubEx для ${GROUP_LABELS[group]}. ` +
+                `Возвращает только сигнатуры (id, краткое описание, параметры) — схемы полей достаёт hubex_describe_endpoint. ` +
+                `Запрос можно писать по-русски (по описанию) или по-английски (по пути и ресурсу).`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: {
+                        type: "string",
+                        description: "Слова для поиска по пути, ресурсу и описанию. Все слова должны найтись.",
+                    },
+                    scope: { type: "string", description: "Код сервиса из hubex_list_scopes, например WORK." },
+                    tag: { type: "string", description: "Ресурс внутри сервиса, например Tasks." },
+                    limit: {
+                        type: "integer",
+                        description: `Сколько результатов вернуть. По умолчанию ${DEFAULT_SEARCH_LIMIT}, максимум ${MAX_SEARCH_LIMIT}.`,
+                    },
+                },
+            },
+        },
+        async execute(args) {
+            try {
+                const result = deps.index.search({
+                    methods: METHOD_GROUPS[group],
+                    query: args.query === undefined ? undefined : String(args.query),
+                    scope: args.scope === undefined ? undefined : String(args.scope),
+                    tag: args.tag === undefined ? undefined : String(args.tag),
+                    limit: args.limit === undefined ? undefined : Number(args.limit),
+                });
+                return okResult(formatSearchResults(result));
+            }
+            catch (err) {
+                return failResult(err);
+            }
+        },
+    };
+}
+function describeEndpoint(deps) {
+    return {
+        definition: {
+            name: "hubex_describe_endpoint",
+            description: "Полная схема параметров и тела для конкретных эндпоинтов. Идентификаторы берутся из hubex_search_*_endpoints " +
+                "или из гайда. Вызывай только для тех эндпоинтов, которые собираешься выполнить: схемы объёмные.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    endpointIds: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: `Идентификаторы вида SERVICE:METHOD:/path. Не более ${MAX_DESCRIBE_IDS} за вызов.`,
+                    },
+                },
+                required: ["endpointIds"],
+            },
+        },
+        async execute(args) {
+            try {
+                const ids = Array.isArray(args.endpointIds) ? args.endpointIds.map(String) : [];
+                if (ids.length === 0) {
+                    throw new Error("Передай хотя бы один endpointId (см. hubex_search_*_endpoints).");
+                }
+                if (ids.length > MAX_DESCRIBE_IDS) {
+                    throw new Error(`Слишком много идентификаторов: не более ${MAX_DESCRIBE_IDS} за вызов, получено ${ids.length}. Разбей на несколько вызовов.`);
+                }
+                const out = [];
+                for (const id of ids) {
+                    const entry = deps.index.get(id);
+                    if (!entry) {
+                        throw new Error(`Эндпоинт ${id} не найден. Вызови hubex_search_*_endpoints со scope, чтобы получить корректный идентификатор.`);
+                    }
+                    if (!deps.index.isAllowed(entry)) {
+                        throw new Error(`Эндпоинт ${id} недоступен: метод ${entry.method} или сервис ${entry.service} отключён ` +
+                            `настройками HUBEX_METHODS / HUBEX_SERVICES. Вызови hubex_search_*_endpoints, чтобы найти доступный эндпоинт.`);
+                    }
+                    const described = deps.schemas.describe(entry);
+                    out.push(deps.annotate ? deps.annotate(described) : described);
+                }
+                return okResult(out);
+            }
+            catch (err) {
+                return failResult(err);
+            }
+        },
+    };
+}
+export function buildDiscoveryTools(deps) {
+    const tools = [listScopes(deps), describeEndpoint(deps)];
+    for (const group of enabledGroups(deps.methods)) {
+        tools.push(searchTool(group, deps));
+    }
+    return tools;
+}