@hubex/mcp 0.9.20261015 → 0.10.20261016

package/.env.example

@@ -10,6 +10,7 @@ HUBEX_ENV=dev
 HUBEX_APPLICATION_ID=5
 
 # Optional: pin the tenant explicitly. If omitted, it is read from the JWT (TenantID claim).
+# In "login" mode it picks the tenant to authorize in.
 # HUBEX_TENANT_ID=5
 
 # Auth mode: token | login | service
@@ -23,6 +24,11 @@ HUBEX_AUTH_MODE=token
 # HUBEX_AUTH_MODE=login
 # HUBEX_USERNAME=poweruser@hubex.ru
 # HUBEX_PASSWORD=your-password
+# Если учётная запись может войти от имени нескольких пользователей (в разных
+# тенантах или в одном), выбери нужного через HUBEX_TENANT_ID и HUBEX_USER_ID
+# (userID пользователя в тенанте). Если они не сужают выбор до одного, сервер
+# спросит при первом обращении (список в клиенте, либо инструмент hubex_select_tenant).
+# HUBEX_USER_ID=868
 
 # --- mode "service" ---
 # Долгоживущий интеграционный токен. HUBEX_TENANT_ID в этом режиме не нужен:

package/CONNECTING.md

@@ -79,7 +79,8 @@ npm run build
 | `HUBEX_AUTH_MODE` | да | `token`, `login` или `service` |
 | `HUBEX_USERNAME` / `HUBEX_PASSWORD` | для `login` | логин/пароль (токен обновляется сам) |
 | `HUBEX_SERVICE_TOKEN` | для `service` | долгоживущий интеграционный токен (обновляется сам) |
-| `HUBEX_TENANT_ID` | нет | tenant явно; иначе берётся из JWT |
+| `HUBEX_TENANT_ID` | нет | tenant явно; иначе берётся из JWT. В `login` — в каком тенанте авторизоваться |
+| `HUBEX_USER_ID` | нет | в `login` — от имени какого пользователя (userID) войти, если в тенанте их несколько |
 | `HUBEX_METHODS` | нет | список доступных HTTP-методов через запятую (по умолчанию — все шесть) |
 | `HUBEX_READONLY` | нет | `true` — эквивалент `HUBEX_METHODS=GET,HEAD` |
 | `HUBEX_SERVICES` | нет | ограничить поиск и исполнение списком сервисов (по умолчанию — все 22) |
@@ -95,6 +96,13 @@ npm run build
 > Если HubEx отверг токен (ошибка 401), следующий запрос получит новый — по
 > refresh, а если не выйдет, сервер снова попросит токен.
 
+> В режиме `login` учётная запись может входить от имени нескольких
+> пользователей — в разных тенантах или в одном. Если `HUBEX_TENANT_ID` и
+> `HUBEX_USER_ID` не сужают выбор до одного, при первом обращении сервер
+> покажет список (клиенты с elicitation) или попросит вызвать инструмент
+> `hubex_select_tenant` с выбранными `tenantID` и `userID`. Выбор действует до
+> перезапуска сервера.
+
 > Сервисный токен выпускается один раз администратором:
 > `POST /fsm/AUTHZ/ServiceTokens` с Bearer и полномочием `ServiceTokenAdd`, тело — массив id
 > членов тенанта. Отзыв — `DELETE /fsm/AUTHZ/ServiceTokens` с полномочием `ServiceTokenRemove`.

package/README.md

@@ -151,7 +151,8 @@ claude mcp add hubex --scope user \
 |---|---|---|
 | `HUBEX_ENV` | `dev` | Окружение: `dev` \| `stg` \| `prod`. От него зависят базовый URL и то, какой кэш swagger-схем берётся (`prod` или `dev`) |
 | `HUBEX_APPLICATION_ID` | — (**обязательный**) | Значение заголовка `X-Application-ID` (`5` — Api/интеграции, `3` — MainWeb) |
-| `HUBEX_TENANT_ID` | из JWT (`TenantID`) | Задаёт тенант явно. В режиме `service` не нужен |
+| `HUBEX_TENANT_ID` | из JWT (`TenantID`) | Задаёт тенант явно. В режиме `login` — в каком тенанте авторизоваться; если не задан и тенантов несколько, сервер спросит. В режиме `service` не нужен |
+| `HUBEX_USER_ID` | — | Только для `login`: userID, от имени которого войти, если пользователей несколько. Если не задан, сервер спросит |
 | `HUBEX_AUTH_MODE` | `token` | Режим авторизации: `token` \| `login` \| `service` |
 | `HUBEX_USERNAME` | — | Логин. Обязателен при `login` |
 | `HUBEX_PASSWORD` | — | Пароль. Обязателен при `login` |
@@ -177,7 +178,7 @@ claude mcp add hubex --scope user \
 | Настройка | Что делает | По умолчанию |
 |---|---|---|
 | `HUBEX_ENV` | Контур: `dev` — тестовый, `stg` — предбоевой, `prod` — боевой | `dev` |
-| `HUBEX_TENANT_ID` | Номер тенанта. Обычно не нужен: сервер сам берёт его из вашего токена. Пригодится, только если у вас доступ сразу к нескольким тенантам | берётся из токена |
+| `HUBEX_TENANT_ID` | Номер тенанта. Обычно не нужен: сервер сам берёт его из вашего токена. Если вы входите по логину и паролю и у вас несколько тенантов, сервер спросит, в какой войти, — переменная избавляет от вопроса | берётся из токена |
 
 ### Как входить
 
@@ -186,6 +187,7 @@ claude mcp add hubex --scope user \
 | `HUBEX_AUTH_MODE` | Способ входа: `token` — сервер спросит токен при первом обращении, `login` — вход по логину и паролю, `service` — по долгоживущему служебному токену | `token` |
 | `HUBEX_USERNAME` | Логин. Нужен только при `HUBEX_AUTH_MODE=login` | — |
 | `HUBEX_PASSWORD` | Пароль. Нужен только при `HUBEX_AUTH_MODE=login` | — |
+| `HUBEX_USER_ID` | Номер пользователя, от имени которого входить по логину и паролю, если в тенанте их у вас несколько. Если не задан, сервер спросит | — |
 | `HUBEX_SERVICE_TOKEN` | Служебный токен, который выдаёт администратор HubEx. Нужен только при `HUBEX_AUTH_MODE=service`. Удобен, когда сервер работает сам по себе и спросить токен не у кого | — |
 
 ### Что помощнику разрешено делать
@@ -206,7 +208,7 @@ claude mcp add hubex --scope user \
 | Настройка | Что делает |
 |---|---|
 | `HUBEX_DEFAULT_COMPANY_ID` | Компания по умолчанию |
-| `HUBEX_DEFAULT_TASK_TYPE_ID` | Тип заявки по умолчанию |
+| `HUBEX_DEFAULT_TASK_TYPE_ID` | Тип заявки по умолчанию. Если не задан, перед созданием заявки ассистент спросит тип у вас |
 | `HUBEX_DEFAULT_REQUEST_METHOD_ID` | Способ обращения по умолчанию (например, «звонок» или «почта») |
 
 ### Пример: строгая настройка для боевого контура

package/dist/auth.js

@@ -1,10 +1,12 @@
 /**
  * Authentication. One lifecycle, three ways to obtain the first access token:
  *  - "token": the user is asked for a ready Bearer JWT.
- *  - "login": Basic (username:password) -> JWT via the AUTHN service.
+ *  - "login": Basic (username:password) via AUTHN, then a tenant user JWT via
+ *    AUTHZ/Accounts/authorize.
  *  - "service": a long-lived service token -> JWT via AUTHZ/AccessTokens.
  * Afterwards all three refresh the same way.
  */
+export const SELECT_TENANT_TOOL = "hubex_select_tenant";
 /** Decode a JWT payload without verifying the signature (we only read claims). */
 export function decodeJwt(token) {
     const parts = token.split(".");
@@ -41,6 +43,16 @@ export function assertUsableJwt(token) {
         throw new Error("Срок действия токена уже истёк. Нужен свежий access-токен HubEx.");
     }
 }
+/**
+ * Lists tenant users for the model to relay. Person names stay out: this text
+ * reaches the LLM context, which only gets PII through the masking layer.
+ */
+function describeMembers(members) {
+    return members
+        .map((m) => `тенант ${m.tenantID}${m.name ? ` «${m.name}»` : ""}, пользователь ${m.userID}` +
+        (m.tenantMemberDescription ? ` (${m.tenantMemberDescription})` : ""))
+        .join("; ");
+}
 /**
  * Obtains a JWT and keeps it fresh. Three ways in — Basic credentials
  * ("login"), a long-lived service token ("service") or a token typed in by the
@@ -49,6 +61,9 @@ export function assertUsableJwt(token) {
 class RefreshingAuth {
     config;
     prompter;
+    chooser;
+    /** Tenant user picked by the user; survives re-logins so they are asked once. */
+    chosen;
     accessToken;
     accessExp; // seconds since epoch
     /**
@@ -70,6 +85,28 @@ class RefreshingAuth {
     setPrompter(prompt) {
         this.prompter = prompt;
     }
+    setTenantChooser(choose) {
+        this.chooser = choose;
+    }
+    async selectTenantMember(tenantID, userID) {
+        if (this.inflight)
+            await this.inflight.catch(() => undefined);
+        const previous = this.chosen;
+        this.chosen = { tenantID, userID };
+        // Tokens of the previous user must not be reused or refreshed.
+        this.accessToken = undefined;
+        this.accessExp = undefined;
+        this.refreshToken = undefined;
+        this.refreshExp = undefined;
+        try {
+            await this.getAccessToken();
+        }
+        catch (err) {
+            // A wrong pick must not lock out the next login.
+            this.chosen = previous;
+            throw err;
+        }
+    }
     /** Stores a token supplied out of band and immediately buys a refresh token. */
     async acceptToken(token) {
         const trimmed = token.trim();
@@ -167,13 +204,65 @@ class RefreshingAuth {
         assertUsableJwt(token);
         return token;
     }
-    loginByPassword() {
+    /**
+     * Two steps, as in the HubEx web and mobile apps. AUTHN only proves the
+     * credentials: its token carries no tenant, so every service answers 401 and
+     * AUTHZ/RefreshTokens 403. AUTHZ/Accounts/authorize trades it for a token of
+     * one tenant member, picked from the tenants the login reported.
+     */
+    async loginByPassword() {
         const basic = Buffer.from(`${encodeURIComponent(this.config.username)}:${encodeURIComponent(this.config.password)}`).toString("base64");
-        return this.fetchJwt(`${this.config.apiBaseUrl}/AUTHN/Accounts/login`, {
+        const account = (await this.fetchJwt(`${this.config.apiBaseUrl}/AUTHN/Accounts/login`, { method: "POST", headers: this.authHeaders({ Authorization: `Basic ${basic}` }) }, `Проверь HUBEX_USERNAME и HUBEX_PASSWORD: учётная запись должна существовать в окружении ` +
+            `HUBEX_ENV=${this.config.env}.`));
+        const member = await this.pickTenantMember(account.tenantEntities ?? []);
+        // The chosen tenant, even when switching users: absorb() keeps a known tenant.
+        this.tenantId = String(member.tenantID);
+        return this.fetchJwt(`${this.config.apiBaseUrl}/AUTHZ/Accounts/authorize`, {
             method: "POST",
-            headers: this.authHeaders({ Authorization: `Basic ${basic}` }),
+            headers: this.authHeaders({
+                Authorization: `Bearer ${account.access_token}`,
+                "Content-Type": "application/json",
+            }),
+            body: JSON.stringify({ tenantID: member.tenantID, tenantMemberID: member.tenantMemberID }),
         });
     }
+    /**
+     * Narrows the account's tenant users by HUBEX_TENANT_ID / HUBEX_USER_ID. One
+     * left — sign in as it; several — the user decides, once.
+     */
+    async pickTenantMember(members) {
+        if (members.length === 0) {
+            throw new Error("Учётная запись не состоит ни в одном тенанте — авторизоваться не в чем.");
+        }
+        const { tenantId, userId } = this.config;
+        const candidates = members.filter((m) => (!tenantId || String(m.tenantID) === tenantId) && (!userId || String(m.userID) === userId));
+        if (candidates.length === 0) {
+            const filter = [tenantId && `HUBEX_TENANT_ID=${tenantId}`, userId && `HUBEX_USER_ID=${userId}`]
+                .filter(Boolean)
+                .join(", ");
+            throw new Error(`Нет пользователя с ${filter}. Учётной записи доступны: ${describeMembers(members)}.`);
+        }
+        const chosen = this.chosen;
+        if (chosen) {
+            const match = candidates.find((m) => m.tenantID === chosen.tenantID && m.userID === chosen.userID);
+            if (!match) {
+                throw new Error(`Нет пользователя ${chosen.userID} в тенанте ${chosen.tenantID}. ` +
+                    `Доступны: ${describeMembers(candidates)}.`);
+            }
+            return match;
+        }
+        if (candidates.length === 1)
+            return candidates[0];
+        const picked = this.chooser ? await this.chooser(candidates) : undefined;
+        if (!picked) {
+            throw new Error(`Учётная запись может войти от имени нескольких пользователей HubEx. Спроси пользователя, ` +
+                `под кем работать, и вызови ${SELECT_TENANT_TOOL} с его tenantID и userID ` +
+                `(или задай HUBEX_TENANT_ID и HUBEX_USER_ID в настройках сервера). ` +
+                `Варианты: ${describeMembers(candidates)}.`);
+        }
+        this.chosen = { tenantID: picked.tenantID, userID: picked.userID };
+        return picked;
+    }
     /** AUTHZ/AccessTokens is anonymous — the service token itself identifies the member. */
     loginByServiceToken() {
         return this.fetchJwt(`${this.config.apiBaseUrl}/AUTHZ/AccessTokens`, {
@@ -213,12 +302,16 @@ class RefreshingAuth {
             ...extra,
         };
     }
-    async fetchJwt(url, init) {
+    /** `rejectHint` replaces the default wrong-environment hint on 401/403/409. */
+    async fetchJwt(url, init, rejectHint) {
         const res = await fetch(url, init);
         if (!res.ok) {
             const body = await res.text().catch(() => "");
             let message = `${init.method ?? "GET"} ${url} failed (HTTP ${res.status}): ${body.slice(0, 500)}`;
-            if (res.status === 401 || res.status === 403) {
+            if (rejectHint && [401, 403, 409].includes(res.status)) {
+                message += ` ${rejectHint}`;
+            }
+            else if (res.status === 401 || res.status === 403) {
                 message +=
                     ` Сейчас выбрано окружение HUBEX_ENV=${this.config.env}. Если токен получен в другом ` +
                         `окружении (dev/stg/prod), авторизация не пройдёт — проверь, что токен именно из ${this.config.env}.`;

package/dist/config.js

@@ -93,6 +93,7 @@ export function loadConfig(env = process.env) {
         swaggerCatalog: swaggerCatalogFor(hubexEnv),
         applicationId: required("HUBEX_APPLICATION_ID", env.HUBEX_APPLICATION_ID),
         tenantId: env.HUBEX_TENANT_ID?.trim() || undefined,
+        userId: env.HUBEX_USER_ID?.trim() || undefined,
         authMode: authMode,
         readonly: parseBool(env.HUBEX_READONLY),
         maskPii: parseBoolDefaultTrue(env.HUBEX_MASK_PII),

package/dist/server.js

@@ -7,6 +7,7 @@ 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 { createElicitTenantChooser } from "./tenant-prompt.js";
 import { HubexClient } from "./http.js";
 import { EndpointIndex, loadIndexFile } from "./index/store.js";
 import { SchemaProvider } from "./schema/describe.js";
@@ -51,6 +52,8 @@ export function createServer(config) {
     // Провайдер создаётся раньше сервера, поэтому способ ввода вносится сюда, а не в конструктор.
     if (config.authMode === "token")
         auth.setPrompter(createElicitPrompter(server));
+    if (config.authMode === "login")
+        auth.setTenantChooser(createElicitTenantChooser(server));
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: [...registry.values()].map((t) => ({
             name: t.definition.name,

package/dist/tenant-prompt.js

@@ -0,0 +1,51 @@
+/**
+ * Asking the user which tenant user to sign in as in `HUBEX_AUTH_MODE=login`,
+ * when the account has several and HUBEX_TENANT_ID / HUBEX_USER_ID do not
+ * narrow them to one.
+ *
+ * The primary channel is MCP elicitation: the client shows a pick list and the
+ * people's names in it never pass through the model's context. Clients without
+ * that capability fall back to the `hubex_select_tenant` tool.
+ */
+import { SELECT_TENANT_TOOL } from "./auth.js";
+const PROMPT_MESSAGE = "Учётная запись HubEx может войти от имени нескольких пользователей. Выбери, под кем работать — " +
+    "выбор сохранится до перезапуска сервера.";
+function optionValue(m) {
+    return `${m.tenantID}:${m.userID}`;
+}
+function optionLabel(m) {
+    const person = [m.lastName, m.firstName].filter(Boolean).join(" ");
+    const details = [person, m.tenantMemberDescription].filter(Boolean).join(", ");
+    return `${m.name ?? `Тенант ${m.tenantID}`}${details ? ` — ${details}` : ""} ` +
+        `(тенант ${m.tenantID}, пользователь ${m.userID})`;
+}
+export function createElicitTenantChooser(server) {
+    return async (options) => {
+        if (!server.getClientCapabilities()?.elicitation)
+            return undefined;
+        const result = await server.elicitInput({
+            message: PROMPT_MESSAGE,
+            requestedSchema: {
+                type: "object",
+                properties: {
+                    member: {
+                        type: "string",
+                        title: "Пользователь HubEx",
+                        enum: options.map(optionValue),
+                        enumNames: options.map(optionLabel),
+                    },
+                },
+                required: ["member"],
+            },
+        });
+        if (result.action !== "accept") {
+            throw new Error("Выбор пользователя HubEx отменён — авторизоваться не удалось. Если клиент заявляет " +
+                "поддержку elicitation, но не показывает форму, спроси пользователя, под кем работать, " +
+                `и вызови ${SELECT_TENANT_TOOL} с его tenantID и userID.`);
+        }
+        const picked = options.find((m) => optionValue(m) === result.content?.member);
+        if (!picked)
+            throw new Error("Пользователь HubEx не выбран.");
+        return picked;
+    };
+}

package/dist/tools/curated.js

@@ -1,7 +1,7 @@
 /**
  * Hand-written convenience tools layered on top of the generated ones.
  */
-import { decodeJwt } from "../auth.js";
+import { SELECT_TENANT_TOOL, 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. */
@@ -75,7 +75,49 @@ function setToken(auth) {
         },
     };
 }
+/**
+ * Fallback for clients without elicitation support: the model asks the user
+ * which tenant user to sign in as and passes the answer here.
+ */
+function selectTenant(auth) {
+    return {
+        definition: {
+            name: SELECT_TENANT_TOOL,
+            description: "Выбрать, от имени какого пользователя HubEx работать, если учётная запись может войти от " +
+                "нескольких (в разных тенантах или в одном). Нужен, если клиент не умеет показывать выбор " +
+                "сам: варианты придут в ошибке авторизации — спроси пользователя и передай его выбор сюда. " +
+                "Выбор действует до перезапуска сервера.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    tenantID: { type: "integer", description: "ID тенанта." },
+                    userID: { type: "integer", description: "ID пользователя в этом тенанте." },
+                },
+                required: ["tenantID", "userID"],
+            },
+        },
+        async execute(args) {
+            try {
+                await auth.selectTenantMember(Number(args.tenantID), Number(args.userID));
+                const claims = decodeJwt(await auth.getAccessToken());
+                return okResult({
+                    ok: true,
+                    tenantId: auth.getTenantId(),
+                    tenantMemberId: claims?.TenantMemberID,
+                    account: claims?.sub,
+                });
+            }
+            catch (err) {
+                return failResult(err);
+            }
+        },
+    };
+}
+// Типы заявок у каждого тенанта свои: без серверного дефолта модель не должна выбирать тип сама.
+const ASK_TASK_TYPE = "Спроси пользователя, какой тип заявки использовать: покажи ему список из " +
+    "hubex_request_read с endpointId WORK:GET:/TaskTypes и не выбирай тип сам.";
 function createTestTask(client, config) {
+    const defaultTaskTypeID = config.defaults.taskTypeID;
     return {
         definition: {
             name: "hubex_create_test_task",
@@ -87,7 +129,10 @@ function createTestTask(client, config) {
                     notes: { type: "string", description: "Текст/описание заявки." },
                     taskTypeID: {
                         type: "integer",
-                        description: "ID типа заявки (список: hubex_request_read с endpointId WORK:GET:/TaskTypes).",
+                        description: defaultTaskTypeID !== undefined
+                            ? "ID типа заявки (список: hubex_request_read с endpointId WORK:GET:/TaskTypes). " +
+                                `По умолчанию ${defaultTaskTypeID} (HUBEX_DEFAULT_TASK_TYPE_ID).`
+                            : `ID типа заявки. Обязателен: дефолт HUBEX_DEFAULT_TASK_TYPE_ID не задан. ${ASK_TASK_TYPE}`,
                     },
                     workTypeID: {
                         type: "integer",
@@ -104,20 +149,22 @@ function createTestTask(client, config) {
                             "По умолчанию 1 (WEB), если не настроен HUBEX_DEFAULT_REQUEST_METHOD_ID.",
                     },
                 },
-                required: ["notes"],
+                required: defaultTaskTypeID !== undefined ? ["notes"] : ["notes", "taskTypeID"],
             },
         },
         async execute(args) {
             try {
+                const taskTypeID = args.taskTypeID ?? defaultTaskTypeID;
+                if (taskTypeID === undefined) {
+                    return failResult(new Error(`Не указан taskTypeID, а HUBEX_DEFAULT_TASK_TYPE_ID не задан. ${ASK_TASK_TYPE}`));
+                }
                 const notes = String(args.notes ?? "").trim();
                 const body = {
                     notes: `${TEST_MARKER} ${notes}`.trim(),
                     // Приоритет: явный аргумент модели > серверный дефолт (HUBEX_DEFAULT_*) > встроенный дефолт.
                     requestMethodID: args.requestMethodID ?? config.defaults.requestMethodID ?? 1,
+                    taskTypeID,
                 };
-                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;
@@ -144,6 +191,8 @@ export function buildCuratedTools(client, config, auth) {
     const tools = [whoami(config, auth)];
     if (config.authMode === "token")
         tools.push(setToken(auth));
+    if (config.authMode === "login")
+        tools.push(selectTenant(auth));
     if (config.methods.includes("POST") && (!config.services || config.services.includes("WORK"))) {
         tools.push(createTestTask(client, config));
     }

package/docs/guides/taskcreate.md

@@ -65,8 +65,11 @@ sources:
 Набор полей заявки в каждом тенанте свой. Не собирай тело по этому гайду по памяти
 и не придумывай значения за пользователя — действуй так:
 
-1. Возьми `taskTypeID` (если тип не назван — покажи список из `WORK:GET:/TaskTypes`
-   и спроси, какой нужен; если тип в тенанте один, бери его молча).
+1. Возьми `taskTypeID`. Если пользователь тип не назвал и он не задан в настройках
+   сервера (тогда `taskTypeID` перечислен среди подставляемых полей в описании
+   `hubex_request_write`), покажи список из `WORK:GET:/TaskTypes` и спроси, какой
+   нужен. Не выбирай тип сам по похожему названию; молча брать можно, только если
+   тип в тенанте один.
 2. Запроси `WORK:GET:/Tasks/new/meta` с query `taskTypeID=<выбранный>` **до** сборки тела.
 3. Разбери ответ на три группы:
    - `capability` = `RWM` в `components` → **обязательное поле**, заявка без него