@oneentry/mcp-platform-server 0.1.0 → 0.1.3

package/dist/transports/http.js

@@ -2,9 +2,9 @@ import { randomUUID } from 'node:crypto';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
 import express from 'express';
+import { OperationCatalog } from '../api/catalog.js';
 import { createServer, createSharedDeps } from '../server.js';
 import { Session } from '../session.js';
-/** Заголовки, которыми клиент передаёт свои учётные данные CMS. */
 const HEADER_TOKEN = 'x-cms-token';
 const HEADER_LOGIN = 'x-cms-login';
 const HEADER_PASSWORD = 'x-cms-password';
@@ -13,11 +13,6 @@ const headerValue = (request, name) => {
     const value = Array.isArray(raw) ? raw[0] : raw;
     return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
 };
-/**
- * Читает учётные данные сессии из заголовков подключения.
- * Только отсюда и из конфигурации сервера — никогда из аргументов инструмента:
- * иначе внедрённая в текст инструкция могла бы подменить личность.
- */
 const credentialsFromRequest = (request) => {
     const token = headerValue(request, HEADER_TOKEN);
     if (token) {
@@ -30,10 +25,6 @@ const credentialsFromRequest = (request) => {
     }
     return undefined;
 };
-/**
- * Проверка Origin. Транспорт SDK умеет это сам, но помечает как deprecated
- * в пользу внешней middleware — делаем внешнюю.
- */
 const originGuard = (allowedOrigins) => (request, response, next) => {
     const origin = headerValue(request, 'origin');
     if (!origin) {
@@ -48,13 +39,22 @@ const originGuard = (allowedOrigins) => (request, response, next) => {
         error: `Origin "${origin}" is not allowed. Start the server with --allowed-origins to permit it.`,
     });
 };
-/**
- * Запускает сервер поверх Streamable HTTP — remote-режим.
- * На каждое MCP-подключение создаётся своя `Session` со своими токенами
- * и своими подтверждениями; общий каталог и знания строятся один раз.
- */
+const fillCatalog = async (deps, session) => {
+    if (!deps.catalog.isEmpty || !session.isConfigured) {
+        return;
+    }
+    try {
+        const bearer = await session.accessToken();
+        const rebuilt = await OperationCatalog.resolve(deps.config, bearer);
+        if (!rebuilt.isEmpty) {
+            deps.catalog.adopt(rebuilt);
+        }
+    }
+    catch {
+    }
+};
 export const runHttp = async (config) => {
-    const deps = createSharedDeps(config);
+    const deps = await createSharedDeps(config);
     const sessions = new Map();
     const app = express();
     app.use(express.json({ limit: '4mb' }));
@@ -85,6 +85,7 @@ export const runHttp = async (config) => {
             },
         });
         const session = new Session(deps, credentialsFromRequest(request));
+        void fillCatalog(deps, session);
         const server = createServer(deps, () => session);
         transport.onclose = () => {
             if (transport.sessionId) {
@@ -94,7 +95,6 @@ export const runHttp = async (config) => {
         await server.connect(transport);
         await transport.handleRequest(request, response, request.body);
     });
-    /** GET открывает SSE-поток, DELETE закрывает сессию — обе требуют существующей сессии. */
     const requireSession = async (request, response) => {
         const sessionId = headerValue(request, 'mcp-session-id');
         const managed = sessionId ? sessions.get(sessionId) : undefined;
@@ -123,4 +123,3 @@ export const runHttp = async (config) => {
         },
     };
 };
-//# sourceMappingURL=http.js.map

package/dist/transports/stdio.d.ts

@@ -1,8 +1,2 @@
 import type { Config } from '../config/config.js';
-/**
- * Запускает сервер поверх stdio — local-режим.
- * Сессия одна на процесс: клиент сам порождает процесс на подключение,
- * поэтому изоляция обеспечивается операционной системой, а не нашим кодом.
- */
 export declare const runStdio: (config: Config) => Promise<void>;
-//# sourceMappingURL=stdio.d.ts.map

package/dist/transports/stdio.js

@@ -1,15 +1,9 @@
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createServer, createSharedDeps } from '../server.js';
 import { Session } from '../session.js';
-/**
- * Запускает сервер поверх stdio — local-режим.
- * Сессия одна на процесс: клиент сам порождает процесс на подключение,
- * поэтому изоляция обеспечивается операционной системой, а не нашим кодом.
- */
 export const runStdio = async (config) => {
-    const deps = createSharedDeps(config);
+    const deps = await createSharedDeps(config);
     const session = new Session(deps);
     const server = createServer(deps, () => session);
     await server.connect(new StdioServerTransport());
 };
-//# sourceMappingURL=stdio.js.map

package/knowledge/operating-rules.md

@@ -0,0 +1,121 @@
+# Operating rules for the OneEntry Admin API
+
+Read this before your first write. Every rule here has broken a real payload, and each one links to the document that explains it in full.
+
+These rules are short on purpose. When one of them applies to what you are about to do, follow the pointer before you build the body.
+
+→ `mcp/docs/server/doc-map` · `mcp/docs/server/payload-conventions`
+
+## The loop you must follow
+
+1. `cms_guide` once, at the start.
+2. `cms_docs_search` for the entity you are about to touch — **before** you write a payload, not after a 400.
+3. `cms_api_search` to find the operation, then `cms_api_describe` for its exact shape.
+4. `cms_api_call` with `dryRun: true` for anything that mutates, then again with the confirm token if one was issued.
+
+Never invent a path, an operation id or a body key. `cms_api_search` is the only authority on what exists; the documents are the authority on what the values mean.
+
+## Trust the example not the type
+
+The OpenAPI document this catalog is built from contains field types that are not JSON Schema types. `cms_api_describe` normalises what it can and marks the rest `"x-loose": true`, with the original under `x-source-type`.
+
+For a loose field, **the `example` is the contract**. Copy its shape. Client-side validation of your body is advisory only — the instance is the real validator, so a call is never blocked because a loose field could not be checked.
+
+→ `mcp/docs/server/cms-api-describe#loose-fields`
+
+## Content is locale keyed
+
+Titles and descriptive content live under `localizeInfos`, keyed by locale code:
+
+```json
+{ "localizeInfos": { "en_US": { "title": "Summer sale" } } }
+```
+
+Required when creating a product, and effectively required on pages. Do not hardcode `en_US`: read the active locale codes from the instance first, and write every locale the instance has active if the content is meant to be visible in all of them.
+
+→ `mcp/docs/api/locales`
+
+## Attribute values are two level and locale keyed
+
+`attributesSets` is **two levels deep** — locale, then attribute key:
+
+```json
+{ "attributesSets": { "en_US": { "string_id42": "SKU-1" } } }
+```
+
+The inner key is `<attribute type>_id<attribute id>`, taken from the attribute set the entity belongs to. Read the set before you build the body.
+
+A flat single-level map is accepted and stored empty. The call answers 201 and the attributes are silently missing, so always read the entity back by id after creating it.
+
+→ `mcp/docs/api/attribute-sets`
+
+## Positions are lexorank or numeric depending on the endpoint
+
+Ordering is a lexorank **string** on parent-scoped Admin operations, and a **number** on flat lists and the Content API. Never sort a lexorank value numerically, and never reorder by patching the field directly — use the dedicated position operations of that entity.
+
+→ `mcp/docs/server/payload-conventions#position-is-a-lexorank-string-or-a-number`
+
+## A read straight after a write can lag
+
+Reading an entity **by id** shows your write immediately. List and search responses may not, for a few seconds.
+
+If a list does not yet show what you just created, re-read by id to confirm it exists. **Never repeat the write** — you will create a duplicate that consumes instance quota and has to be cleaned up by hand.
+
+## Prefer marker over id
+
+Blocks, forms, menus, templates, general types and modules are addressed by a `marker` or `identifier` that is stable across instances. A numeric `id` is not: an id taken from one instance is meaningless on another, and `404 Not found` on an id you were given is usually that mistake.
+
+Where an operation accepts either, use the marker.
+
+## Baseline data already exists do not recreate it
+
+Every instance arrives populated: a guest user group with its content-API permissions, the admin modules, the general types, the attribute set types and field types, the locales, the dynamic block types and their default templates, and the singleton settings records.
+
+**List first, create second.** Some duplicates fail loudly, which is harmless. The dangerous ones — user groups, modules, attribute set types, settings records — **succeed silently** and leave a shadow record that nothing references.
+
+→ `mcp/docs/api/baseline-data`
+
+## Never touch these without a human saying so
+
+Mutations under `immutable-settings`, `admins`, `backups`, `modules`, `payments/webhook`, `settings-general`, `system/captcha-keys` and `auth/logout/all-users` are permanently confirm-gated by this server, at every allow level.
+
+The gate is not a suggestion. State what you intend to change, show the human the `target` the dry run returned, and wait for them to say yes in this conversation.
+
+→ `mcp/docs/server/allow-levels#paths-that-are-always-confirm-gated`
+
+## Permissions are checked before the request is sent
+
+Each operation declares the permission it requires, and this server refuses locally when the authenticated admin does not hold it. Nothing is sent, so nothing changed.
+
+A permission refusal means **ask for the grant** and stop. Retrying cannot succeed, and neither can a different operation that needs the same permission.
+
+→ `mcp/docs/api/admins-and-permissions`
+
+## Truncated responses are deliberate
+
+Large responses come back with a `_truncated` envelope reporting what was shown and what the total was. That is this server capping what it hands you, not the API limiting itself.
+
+Do not retry hoping for more. Narrow the request with the operation's own `limit`, `offset` and filter parameters.
+
+→ `mcp/docs/server/response-shaping`
+
+## Operations with a single supported path
+
+For the calls below, one route works and the obvious alternative does not. Use the supported one directly — a different body or a retry on the other route will not help.
+
+- **Create a form** — send the payload wrapped in `newForm`. The OpenAPI document shows the fields unwrapped; the wrapped form is the one the endpoint accepts.
+- **Update a product** — always include `blocks` (send `blocks: []` when you have nothing to set), and never include `forms`.
+- **Read locale codes** — use `AdminLocalesController_findAllActive`.
+- **List products** — the list operation is `POST /products/all`; there is no `GET /products`.
+- **Export operations** — `orders.export`, `payments.export` and `users.export` are not grantable on current instances. Treat them as unavailable and tell the human rather than retrying.
+
+If a call outside this list answers 5xx, stop and report it with the operation id and the request you sent. Do not retry it with a modified body.
+
+## Where to look next
+
+With the operation hints removed from `cms_api_describe`, `cms_docs_search` and the map below are how you find anything.
+
+- `mcp/docs/server/doc-map` — every document, with when to read it
+- `mcp/docs/server/payload-conventions` — the rules above, in full
+- `mcp/docs/api/baseline-data` — what already exists on your instance
+- `mcp/docs/server/errors-and-refusals` — what a specific error means and what to do next

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@oneentry/mcp-platform-server",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "MCP server that lets an AI agent operate the OneEntry Admin API, grounded in the project's own rules",
-  "license": "UNLICENSED",
+  "license": "MIT",
   "type": "module",
   "engines": {
     "node": ">=20"
@@ -12,8 +12,20 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://gitlab.com/webdnk1/msvc/mcp-oneentry.git"
+    "url": "git+https://github.com/ONEENTRY-PLATFORM/oneentry-platform-mcp.git"
   },
+  "bugs": {
+    "url": "https://github.com/ONEENTRY-PLATFORM/oneentry-platform-mcp/issues"
+  },
+  "homepage": "https://github.com/ONEENTRY-PLATFORM/oneentry-platform-mcp#readme",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "oneentry",
+    "cms",
+    "admin-api",
+    "ai-agent"
+  ],
   "publishConfig": {
     "access": "public"
   },
@@ -28,16 +40,17 @@
   "files": [
     "dist",
     "data",
-    "README.md"
+    "knowledge",
+    "README.md",
+    "LICENSE"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "prepublishOnly": "npm run build",
-    "prestart": "npm run check:drift",
     "start": "node dist/bin/cli.js",
     "dev": "tsx src/bin/cli.ts",
-    "sync:from-cms": "tsx build/sync.ts",
-    "check:drift": "tsx build/sync.ts --check",
+    "sync:permissions": "tsx build/sync-permissions.ts",
+    "publish:knowledge": "node -e \"console.error('REFUSED: the knowledge repository is hand-authored. Bulk-copying internal docs into it is prohibited.'); process.exit(1)\"",
     "lint": "eslint \"{src,build,__tests__}/**/*.ts\"",
     "test": "vitest run",
     "test:watch": "vitest",