@oneentry/mcp-platform-server 0.1.1 → 0.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OneEntry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,7 +1,7 @@
 # @oneentry/mcp-platform-server
 
-MCP server that lets an AI agent **operate the OneEntry Admin API** — grounded in the project's own
-rules rather than in guesswork.
+MCP server that lets an AI agent **operate the OneEntry Admin API** — grounded in published
+operating rules rather than in guesswork.
 
 Nothing is frozen into the package. Both halves are fetched at runtime and cached:
 
@@ -9,14 +9,15 @@ Nothing is frozen into the package. Both halves are fetched at runtime and cache
   ([ONEENTRY-PLATFORM/oneentry-platform-rules](https://github.com/ONEENTRY-PLATFORM/oneentry-platform-rules)),
   chunked into searchable sections. Editing a doc there — through the GitHub UI, a PR, whatever — takes effect on the next
   restart of any server, with no npm release.
-- **Actuation.** Every Admin API operation, built from the stand's own
+- **Actuation.** Every Admin API operation, built from the instance's own API document at
   `GET /api/admin/workflows/nodes/admin-api/swagger.json`, with parameter and body schemas, the
   permission each one requires, and a risk classification — reachable through one generic invoke
   tool instead of one tool per endpoint. The catalog always describes the API that is actually
   running, not a snapshot of it.
 
-The one thing still committed here is `data/permissions.json`: `@GrantByPermission` is a decorator
-and never reaches any swagger, so that map has to be recovered from the CMS sources.
+The one thing still committed here is `data/permissions.json`: the permission an operation requires
+is declared in platform code and never reaches the API document, so that map has to be recovered
+separately.
 
 Only the Admin API is exposed.
 
@@ -26,7 +27,7 @@ Only the Admin API is exposed.
 npm i -g @oneentry/mcp-platform-server     # or use npx, below
 ```
 
-## Local mode (agent and CMS on the same machine)
+## Local mode (agent and instance on the same machine)
 
 Add to `.mcp.json` in the repo you work from:
 
@@ -46,21 +47,21 @@ Add to `.mcp.json` in the repo you work from:
 }
 ```
 
-No checkout of the CMS is needed. On first run the knowledge repository is downloaded once and
+Nothing has to be checked out locally. On first run the knowledge repository is downloaded once and
 cached; later runs re-use the cache and only ask GitHub whether the commit moved, at most once an
 hour.
 
-backend-app must be running with `API_TYPE=/api/admin` (default port 3003).
+The base URL must point at an instance that exposes the Admin API under `/api/admin`.
 
-## Remote mode (hosted, many agents, one stand)
+## Remote mode (hosted, many agents, one instance)
 
 ```bash
 oneentry-mcp-platform --http --port 8931 --audit /var/log/oneentry-mcp-platform-audit.jsonl \
-        --base-url https://stand.example/api/admin \
+        --base-url https://your-instance.example/api/admin \
         --allowed-origins https://agent.example
 ```
 
-Each MCP session carries its own CMS identity, passed as connection headers — never as tool
+Each MCP session carries its own identity, passed as connection headers — never as tool
 arguments, so a prompt-injected instruction cannot swap identities:
 
 | header | meaning |
@@ -78,7 +79,7 @@ Sessions never share tokens or confirm tokens. `GET /health` reports liveness an
 | `cms_docs_search` | search the knowledge base, returns sections with snippets |
 | `cms_docs_read` | read one section, with its sibling sections listed for paging |
 | `cms_api_search` | find operations by keyword / tag / method / mutating |
-| `cms_api_describe` | params, body schema, required permission, risk, linked docs |
+| `cms_api_describe` | params, body schema, required permission, risk, confirm gating |
 | `cms_api_call` | execute one operation; `dryRun` and confirm-gating for mutations |
 | `cms_whoami` | mode, base URL, admin + permissions, knowledge commit, catalog state and warnings |
 
@@ -100,8 +101,8 @@ Read-only by default. `--allow` (or `ONEENTRY_MCP_ALLOW`) raises it:
   `auth/logout/all-users`), require a **confirm token**: the first call returns the token *and the
   current state of the target*, fetched via the sibling GET, so a human can see what is about to
   change. The token is bound to `hash(opId + arguments)`, single-use, valid 5 minutes.
-- Permissions are checked locally first: if the admin lacks the `AdminPermissionsEnum` value the
-  operation declares, the call is refused without being sent.
+- Permissions are checked locally first: if the admin lacks the permission the operation declares,
+  the call is refused without being sent.
 - Every non-GET call is appended to a JSONL audit log (arguments are hashed, not stored). Required
   in remote mode.
 
@@ -111,10 +112,10 @@ A public GitHub repository of small markdown files. Layout:
 
 ```
 knowledge/
-  mcp/operating-rules.md          -> docId "mcp/operating-rules"
-  back/docs/menus-module.md       -> docId "back/docs/menus-module"
-  back/docs/orders-module/index.md      -> docId "back/docs/orders-module"
-  back/docs/orders-module/status-axis.md-> docId "back/docs/orders-module/status-axis"
+  mcp/operating-rules.md                -> docId "mcp/operating-rules"
+  mcp/docs/api/orders.md                -> docId "mcp/docs/api/orders"
+  mcp/docs/server/cms-api-call.md       -> docId "mcp/docs/server/cms-api-call"
+  mcp/docs/api/orders/index.md          -> docId "mcp/docs/api/orders"
 ```
 
 The docId is the path under `knowledge/` without `.md`; `<name>/index.md` collapses back to
@@ -140,10 +141,10 @@ restart is instant and the previous commit is pruned.
 Which repository and which commit is a configuration choice, not a constant: `--knowledge-repo`
 (`ONEENTRY_MCP_KNOWLEDGE_REPO`, default `ONEENTRY-PLATFORM/oneentry-platform-rules`) and
 `--knowledge-ref`
-(`ONEENTRY_MCP_KNOWLEDGE_REF`, default `main`) — a ref may be a branch, a tag or a commit sha, so a
-stand can be frozen on a known-good corpus. `ONEENTRY_GITHUB_TOKEN` is optional and only raises the
-API rate limit; the repo is public. `cms_whoami` reports the repo, ref and 12-character commit the
-running server actually loaded.
+(`ONEENTRY_MCP_KNOWLEDGE_REF`, default `main`) — a ref may be a branch, a tag or a commit sha, so an
+instance can be frozen on a known-good corpus. `ONEENTRY_GITHUB_TOKEN` is optional and only raises
+the API rate limit; the repo is public. `cms_whoami` reports the repo, ref and 12-character commit
+the running server actually loaded.
 
 ### Reading the docs from a local folder instead
 
@@ -165,67 +166,67 @@ look like an empty corpus.
 
 ### Known limitation: retrieval is single-language
 
-Search does not translate. The backend corpus is largely English, so a Russian question will not
-find an English-only document no matter how it is weighted — and the reverse holds too. The fix is
-content, not code: give such a document a short summary section in the other language, or ask in the
-language the document is written in.
+Search does not translate, and the corpus is English. A question asked in another language will not
+find an English-only document no matter how it is weighted. The fix is content, not code.
 
-### Publishing CMS docs into it
+### The corpus is hand-authored
 
-The knowledge repo is what the server reads; the CMS repos remain where the docs are written.
-To move them across:
+The knowledge repository is written for a public audience, one file at a time. There is no import
+script and one must not be added: bulk-copying internal documentation into it would publish source
+paths, storage identifiers and tracker ids in a single command, and a repository that is public and
+mirrored cannot be un-published. `npm run publish:knowledge` exists only to refuse.
 
-```bash
-npm run publish:knowledge -- --back ../dnk-back --front ../dnk-front --out ../oneentry-platform-rules
-```
-
-It copies `.claude/docs`, `.claude/tests` and `.claude/rules` from both checkouts, splits anything
-over 12 KB at `##` boundaries, and reports files in the target it did not produce. It **does not
-commit or push** — that diff is the moment internal text becomes public, and a human owns it.
-`.claude/fixes` and the CMS `CLAUDE.md` files are deliberately not published.
+At release time, copy `knowledge/mcp/operating-rules.md` from the rules repository over this
+package's `knowledge/operating-rules.md` — the rules repository is the source, and the bundled seed
+is never hand-edited.
 
 ## Where the catalog comes from
 
 Two sources, because neither alone is enough:
 
 1. `GET {baseUrl}/workflows/nodes/admin-api/swagger.json?langCode=en_US` — paths, operation ids and
-   schemas, straight from the stand you are pointed at. Cached per base URL, so an unreachable
-   stand still yields the last known catalog.
-2. `data/permissions.json` — the `@GrantByPermission` decorators, which never reach swagger.
-   Regenerate it when the CMS changes its permissions:
+   schemas, straight from the instance you are pointed at. Cached per base URL, so an unreachable
+   instance still yields the last known catalog.
+2. `data/permissions.json` — the permission each operation requires, which the API document does not
+   express. Regenerate it when the platform changes its permissions:
 
 ```bash
-npm run sync:permissions -- --back ../dnk-back
+npm run sync:permissions -- --back <path to a platform checkout>
 ```
 
-That pass walks base classes too, since Nest derives the operation id from the *registered*
-controller while the handler often lives in a parent.
+That pass walks base classes too, since the operation id is derived from the *registered* class
+while the handler often lives in a parent.
 
 Inconsistencies are surfaced as catalog `warnings` (visible in `cms_whoami`) rather than swallowed:
 paths outside `/api/admin` (dropped — this server exposes the Admin API only), operations with no
-`operationId`, handlers whose permission is known but which the stand does not expose, and
-permissions required by controllers but absent from `AdminPermissionsEnum` — no admin can hold
-those, so such endpoints answer 403 forever.
+`operationId`, operations whose permission is known but which the instance does not expose, and
+permissions that operations require but no admin can hold — such endpoints answer 403 forever.
 
-If the stand does not serve its swagger at all, the catalog is **empty** and says so loudly. Empty
-is safe — there is nothing to call — but silence would read as "the CMS has no such endpoint".
+If the instance does not serve its API document at all, the catalog is **empty** and says so loudly.
+Empty is safe — there is nothing to call — but silence would read as "the platform has no such
+endpoint".
 
-### The swagger is not valid JSON Schema
+### The API document is not valid JSON Schema
 
-Many `type` values in the source swagger are TypeScript expressions (`Record<string, any>`,
-`CommonLocalizeInfos`, `AttributesSets`, `image`, `date`). The build normalizes what it can and
-marks the rest `"x-loose": true` with the original under `x-source-type`. For loose fields the
-`example` is the contract, and client-side body validation is deliberately advisory — the server
-is the real validator, so a call is never blocked because a loose field could not be checked.
+Many `type` values in the source document are expressions in the platform's own type language
+(`Record<string, any>`, `CommonLocalizeInfos`, `AttributesSets`, `image`, `date`). The build
+normalizes what it can and marks the rest `"x-loose": true` with the original under `x-source-type`.
+For loose fields the `example` is the contract, and client-side body validation is deliberately
+advisory — the instance is the real validator, so a call is never blocked because a loose field
+could not be checked.
 
 ## Tests
 
 ```bash
-npm test                 # unit + MCP protocol + remote-mode transport (no stand needed)
-npm run test:integration # against a live dnk-back; skips cleanly if unreachable
+npm test                 # unit + MCP protocol + remote-mode transport (no instance needed)
+npm run test:integration # against a live instance; skips cleanly if unreachable
 ```
 
-The integration suite needs backend-app on `:3003` with `API_TYPE=/api/admin` plus
-`ONEENTRY_CMS_LOGIN`/`ONEENTRY_CMS_PASSWORD`. It walks search → describe → call, asserts a read-only refusal
-sends nothing, and runs a full create → confirm-gated delete cycle on a throwaway template while
-checking the audit log.
+The integration suite needs `ONEENTRY_CMS_BASE_URL` pointing at an instance that exposes the Admin
+API, plus `ONEENTRY_CMS_LOGIN`/`ONEENTRY_CMS_PASSWORD`. It walks search → describe → call, asserts a
+read-only refusal sends nothing, and runs a full create → confirm-gated delete cycle on a throwaway
+template while checking the audit log.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/api/audit.d.ts

@@ -1,4 +1,3 @@
-/** Одна запись аудита изменяющего вызова. */
 export interface AuditEntry {
     at: string;
     mode: string;
@@ -10,11 +9,6 @@ export interface AuditEntry {
     outcome: 'denied' | 'needs-confirm' | 'sent';
     status?: number;
 }
-/**
- * Журнал изменяющих вызовов в формате JSONL.
- * Пишем хэш аргументов, а не сами аргументы: тела запросов содержат
- * пользовательские данные, а для разбора инцидента достаточно связать вызовы между собой.
- */
 export declare class AuditLog {
     private readonly path;
     private readonly mode;
@@ -23,10 +17,5 @@ export declare class AuditLog {
         mode: string;
     });
     static hashArgs(args: unknown): string;
-    /**
-     * Пишет запись, не роняя вызов при недоступности файла: аудит важен,
-     * но потеря строки лога — не причина провалить операцию, о которой уже отчитались.
-     */
     record(entry: Omit<AuditEntry, 'at' | 'mode'>): void;
 }
-//# sourceMappingURL=audit.d.ts.map

package/dist/api/audit.js

@@ -1,10 +1,5 @@
 import { appendFileSync } from 'node:fs';
 import { createHash } from 'node:crypto';
-/**
- * Журнал изменяющих вызовов в формате JSONL.
- * Пишем хэш аргументов, а не сами аргументы: тела запросов содержат
- * пользовательские данные, а для разбора инцидента достаточно связать вызовы между собой.
- */
 export class AuditLog {
     path;
     mode;
@@ -15,10 +10,6 @@ export class AuditLog {
     static hashArgs(args) {
         return createHash('sha256').update(JSON.stringify(args ?? null)).digest('hex').slice(0, 16);
     }
-    /**
-     * Пишет запись, не роняя вызов при недоступности файла: аудит важен,
-     * но потеря строки лога — не причина провалить операцию, о которой уже отчитались.
-     */
     record(entry) {
         if (!this.path) {
             return;
@@ -32,4 +23,3 @@ export class AuditLog {
         }
     }
 }
-//# sourceMappingURL=audit.js.map

package/dist/api/auth.d.ts

@@ -1,31 +1,21 @@
 import type { Config } from '../config/config.js';
-/** Пара токенов Admin API, как её отдаёт `POST /auth/login`. */
 export interface TokenPair {
     accessToken: string;
     refreshToken: string;
 }
-/** Данные аутентифицированного админа, восстановленные из токена и API. */
 export interface AdminIdentity {
     id: number;
     login?: string;
     permissions: string[];
 }
-/** Учётные данные одной сессии. В remote-режиме у каждой сессии свои. */
 export interface Credentials {
     login?: string;
     password?: string;
     token?: string;
 }
-/** Ошибка аутентификации с текстом, пригодным для показа модели. */
 export declare class AuthError extends Error {
 }
-/** Достаёт идентификатор админа из payload access-токена. */
 export declare const adminIdFromToken: (token: string) => number;
-/**
- * Держит пару токенов для одного набора учётных данных.
- * Токены живут только в памяти и только внутри сессии: в remote-режиме
- * это то, что не даёт токену одной сессии утечь в другую.
- */
 export declare class TokenStore {
     private pair;
     private readonly baseUrl;
@@ -36,18 +26,10 @@ export declare class TokenStore {
         timeoutMs: number;
         credentials: Credentials;
     });
-    /** Есть ли чем аутентифицироваться вообще. */
     get isConfigured(): boolean;
     private post;
     private static readPair;
-    /** Возвращает access-токен, логинясь при первом обращении. */
     accessToken(): Promise<string>;
-    /**
-     * Обновляет пару после 401. Если refresh невозможен (передан готовый токен
-     * или refresh отвергнут) — пробует полный логин, и только потом сдаётся.
-     */
     refresh(): Promise<string>;
 }
-/** Учётные данные из конфигурации — источник по умолчанию для local-режима. */
 export declare const credentialsFromConfig: (config: Config) => Credentials;
-//# sourceMappingURL=auth.d.ts.map

package/dist/api/auth.js

@@ -1,4 +1,3 @@
-/** Ошибка аутентификации с текстом, пригодным для показа модели. */
 export class AuthError extends Error {
 }
 const decodeJwtPayload = (token) => {
@@ -13,7 +12,6 @@ const decodeJwtPayload = (token) => {
     }
     return parsed;
 };
-/** Достаёт идентификатор админа из payload access-токена. */
 export const adminIdFromToken = (token) => {
     const payload = decodeJwtPayload(token);
     const id = payload['id'] ?? payload['sub'] ?? payload['userId'];
@@ -23,11 +21,6 @@ export const adminIdFromToken = (token) => {
     }
     return numeric;
 };
-/**
- * Держит пару токенов для одного набора учётных данных.
- * Токены живут только в памяти и только внутри сессии: в remote-режиме
- * это то, что не даёт токену одной сессии утечь в другую.
- */
 export class TokenStore {
     pair;
     baseUrl;
@@ -41,7 +34,6 @@ export class TokenStore {
             this.pair = { accessToken: params.credentials.token, refreshToken: '' };
         }
     }
-    /** Есть ли чем аутентифицироваться вообще. */
     get isConfigured() {
         return Boolean(this.credentials.token || (this.credentials.login && this.credentials.password));
     }
@@ -54,11 +46,6 @@ export class TokenStore {
         });
         const text = await response.text();
         if (!response.ok) {
-            /**
-             * Admin API отвечает 401 «Login or password incorrect» и на developer-аккаунт:
-             * контроллер отбрасывает админов с isDeveloper. Без этой подсказки агент
-             * будет бесконечно перепроверять пароль.
-             */
             const hint = response.status === 401
                 ? ' The Admin API also returns 401 for accounts flagged isDeveloper — those belong to the Developer API, which this server does not expose.'
                 : '';
@@ -81,7 +68,6 @@ export class TokenStore {
             refreshToken: typeof refreshToken === 'string' ? refreshToken : '',
         };
     }
-    /** Возвращает access-токен, логинясь при первом обращении. */
     async accessToken() {
         if (this.pair) {
             return this.pair.accessToken;
@@ -95,10 +81,6 @@ export class TokenStore {
         }));
         return this.pair.accessToken;
     }
-    /**
-     * Обновляет пару после 401. Если refresh невозможен (передан готовый токен
-     * или refresh отвергнут) — пробует полный логин, и только потом сдаётся.
-     */
     async refresh() {
         const refreshToken = this.pair?.refreshToken;
         this.pair = undefined;
@@ -117,10 +99,8 @@ export class TokenStore {
         return this.accessToken();
     }
 }
-/** Учётные данные из конфигурации — источник по умолчанию для local-режима. */
 export const credentialsFromConfig = (config) => ({
     ...(config.login ? { login: config.login } : {}),
     ...(config.password ? { password: config.password } : {}),
     ...(config.token ? { token: config.token } : {}),
 });
-//# sourceMappingURL=auth.js.map

package/dist/api/build-catalog.d.ts

@@ -1,24 +1,11 @@
 import type { Catalog } from './types.js';
-/**
- * Связь операция -> требуемое право и полный список прав.
- * Собирается на сборке проходом по исходникам dnk-back: декоратор
- * `@GrantByPermission` в swagger не попадает никогда, ни в файловый, ни в живой.
- */
 export interface PermissionMap {
     byOpId: Record<string, string>;
     permissions: string[];
 }
-/**
- * Строит каталог операций из swagger стенда и карты прав.
- * Два источника, потому что ни одного не хватает: swagger даёт пути и схемы,
- * а требуемое право объявлено декоратором и в swagger не попадает.
- * Классификация риска и список навсегда подтверждаемых путей вычисляются здесь,
- * то есть в коде пакета, — swagger приходит по сети и не должен на них влиять.
- */
 export declare const buildCatalog: (params: {
-    /** Тело `swagger.json` как строка: по нему же считается хэш. */
     rawSwagger: string;
     permissions: PermissionMap;
     builtAt: string;
+    sourceUrl?: string;
 }) => Catalog;
-//# sourceMappingURL=build-catalog.d.ts.map

package/dist/api/build-catalog.js

@@ -2,11 +2,6 @@ import { createHash } from 'node:crypto';
 import { capSchema, normalizeSchema } from './normalize-schema.js';
 const API_PREFIX = '/api/admin';
 const METHODS = ['get', 'post', 'put', 'patch', 'delete'];
-/**
- * Операции, которые остаются за подтверждением при любом уровне `--allow`.
- * Список путей, а не прав: право можно выдать админу по недоразумению,
- * а этот барьер снять нельзя.
- */
 const ALWAYS_CONFIRM = [
     /^\/immutable-settings/,
     /^\/admins/,
@@ -17,42 +12,6 @@ const ALWAYS_CONFIRM = [
     /^\/settings-general/,
     /^\/system\/captcha-keys/,
 ];
-/** Какие разделы документации объясняют операции конкретного тега. */
-const TAG_DOCS = {
-    Orders: ['back/docs/orders-module', 'back/docs/order-status-axis'],
-    Products: [
-        'back/docs/postgres-db-with-attribute-index',
-        'back/docs/product-relations',
-        'back/docs/isPrice-attribute',
-    ],
-    Payments: ['back/docs/payments-module', 'back/docs/isPrice-attribute'],
-    Blocks: ['back/docs/blocks-module'],
-    Pages: ['back/docs/pages-module'],
-    Discounts: ['back/docs/orders-module'],
-    Filters: ['back/docs/filters'],
-    'Attributes Sets': [
-        'back/docs/postgres-db-with-attribute-index',
-        'back/docs/attribute-indexing',
-        'back/tests/attributes-sets-e2e',
-    ],
-    Menus: ['back/docs/menus-module', 'back/tests/menus-e2e'],
-    'Index Attributes': ['back/docs/attribute-indexing'],
-    Modules: ['back/docs/user-permissions'],
-    Subscriptions: ['back/docs/subscriptions-module'],
-    Forms: ['back/docs/forms-and-form-data'],
-    FormData: ['back/docs/forms-and-form-data'],
-    'User Permissions': ['back/docs/user-permissions', 'front/docs/user-permissions'],
-    'User Groups': ['back/docs/user-permissions'],
-    Admins: ['back/docs/user-permissions', 'back/tests/admins-e2e'],
-    'Global Search': ['back/docs/global-search'],
-    'AI Gateway': ['back/docs/ai-gateway'],
-    'AI Gateway / settings': ['back/docs/ai-gateway'],
-    'File Uploading': ['back/docs/file-upload-dev-mode'],
-    System: ['back/docs/captcha-recaptcha'],
-    Templates: ['back/tests/templates-e2e'],
-    'Template previews': ['back/tests/template-previews-e2e'],
-    Import: ['back/tests/import-e2e'],
-};
 const riskOf = (method) => {
     if (method === 'get') {
         return 'read';
@@ -61,7 +20,6 @@ const riskOf = (method) => {
 };
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 const asString = (value) => typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
-/** Собирает одну человекочитаемую строку описания успешного ответа. */
 const responseSummary = (responses) => {
     if (!isRecord(responses)) {
         return undefined;
@@ -124,13 +82,6 @@ const buildBody = (raw, components) => {
         required: raw['required'] === true,
     };
 };
-/**
- * Строит каталог операций из swagger стенда и карты прав.
- * Два источника, потому что ни одного не хватает: swagger даёт пути и схемы,
- * а требуемое право объявлено декоратором и в swagger не попадает.
- * Классификация риска и список навсегда подтверждаемых путей вычисляются здесь,
- * то есть в коде пакета, — swagger приходит по сети и не должен на них влиять.
- */
 export const buildCatalog = (params) => {
     const { rawSwagger } = params;
     const swagger = JSON.parse(rawSwagger);
@@ -143,19 +94,12 @@ export const buildCatalog = (params) => {
         : {};
     const { byOpId, permissions } = params.permissions;
     const operations = [];
-    /** Пути не из Admin API и операции без operationId — оба случая идут в warnings. */
     const foreignPaths = [];
     const withoutOpId = [];
     for (const [fullPath, pathItem] of Object.entries(swagger['paths'])) {
         if (!isRecord(pathItem)) {
             continue;
         }
-        /**
-         * Путь вне `/api/admin` в каталог не попадает никогда: сервер по замыслу
-         * не выпускает наружу Content и Developer API. Документ приходит по сети,
-         * поэтому здесь фильтр, а не исключение — одна лишняя запись не должна
-         * лишать агента всего каталога.
-         */
         if (!fullPath.startsWith(API_PREFIX)) {
             foreignPaths.push(fullPath);
             continue;
@@ -194,7 +138,6 @@ export const buildCatalog = (params) => {
                 ...(responseSummary(operation['responses'])
                     ? { responseSummary: responseSummary(operation['responses']) }
                     : {}),
-                docLinks: [...(TAG_DOCS[tag] ?? []), 'mcp/operating-rules'],
                 searchText: '',
             };
             entry.searchText = [opId, method.toUpperCase(), path, tag, summary, permission ?? '']
@@ -213,26 +156,23 @@ export const buildCatalog = (params) => {
         warnings.push(`${String(withoutOpId.length)} operation(s) have no operationId and cannot be called ` +
             `(e.g. ${withoutOpId.slice(0, 3).join(', ')}). Report it against the CMS.`);
     }
-    /**
-     * Обработчик объявляет право, но живой swagger о нём не знает.
-     * Раньше это означало устаревший снимок swagger; теперь документ приходит
-     * со стенда, поэтому смысл другой: карта прав собрана с другой версии кода,
-     * чем развёрнута на стенде. Агенту это важно так же — иначе он получит 404
-     * на существующий, по его данным, эндпоинт.
-     */
     const known = new Set(operations.map((o) => o.opId));
     const missing = Object.keys(byOpId).filter((opId) => !known.has(opId) && !opId.startsWith('Developer') && !opId.startsWith('Content'));
     if (missing.length > 0) {
-        warnings.push(`${String(missing.length)} admin handler(s) declare a permission but are absent from the ` +
-            `stand's swagger (e.g. ${missing.slice(0, 3).join(', ')}). data/permissions.json was ` +
-            'generated from a different revision of dnk-back than the stand runs — re-run ' +
-            'npm run sync:permissions if the catalog looks incomplete.');
+        const isFiltered = missing.length > Object.keys(byOpId).length / 2;
+        warnings.push(`${String(missing.length)} admin operation(s) declare a permission but are absent from the ` +
+            `document served by ${params.sourceUrl ?? "the instance's API document"} ` +
+            `(e.g. ${missing.slice(0, 3).join(', ')}). ` +
+            (isFiltered
+                ? 'Most of the Admin API is missing, so that URL is serving the operation subset ' +
+                    'whitelisted for the workflow "admin-api" node rather than the whole API. The ' +
+                    'complete document is published by the instance itself at the base URL with ' +
+                    '"-json" appended, but only while it runs with CORS_MODE=DEV. Until this ' +
+                    'instance supports the "full" parameter on the node endpoint, expect the ' +
+                    'catalog to cover only a fraction of the endpoints that exist.'
+                : 'The bundled permission map was generated from a different platform revision than ' +
+                    'this instance runs — update the package if the catalog looks incomplete.'));
     }
-    /**
-     * Право, объявленное контроллером, но отсутствующее в `AdminPermissionsEnum`,
-     * никогда не будет выдано администратору — такой эндпоинт отвечает 403 всегда.
-     * Это дефект dnk-back, и о нём должен знать и агент, и человек.
-     */
     const knownPermissions = new Set(permissions);
     const orphanPermissions = [
         ...new Set(operations
@@ -240,9 +180,9 @@ export const buildCatalog = (params) => {
             .filter((value) => value !== undefined && !knownPermissions.has(value))),
     ];
     if (orphanPermissions.length > 0) {
-        warnings.push(`${orphanPermissions.length} permission(s) are required by controllers but missing from ` +
-            `AdminPermissionsEnum (${orphanPermissions.join(', ')}). No admin can hold them, so those ` +
-            'operations always answer 403 — report it rather than retrying.');
+        warnings.push(`${orphanPermissions.length} permission(s) are required by operations but cannot be held by ` +
+            `any admin (${orphanPermissions.join(', ')}). Those operations answer 403 permanently — ` +
+            'treat them as unavailable and report it rather than retrying.');
     }
     return {
         version: 1,
@@ -254,4 +194,3 @@ export const buildCatalog = (params) => {
         operations,
     };
 };
-//# sourceMappingURL=build-catalog.js.map