@oneentry/mcp-platform-server 0.1.0 → 0.1.1

package/knowledge/operating-rules.md

@@ -0,0 +1,176 @@
+# Operating rules — OneEntry CMS Admin API
+
+Read this before your first write. Every rule below is one that has actually broken payloads.
+Each links to the bundled reference doc that explains it in full — open it with
+`cms_docs_read`.
+
+## 0. The loop you should follow
+
+1. `cms_guide` — once, at the start.
+2. `cms_docs_search` — find the rules for the entity you are about to touch. **Before** writing,
+   not after a 400.
+3. `cms_api_search` → `cms_api_describe` — get the real operation and its payload shape.
+4. `cms_api_call` — with `dryRun: true` first for anything mutating.
+
+Do not guess a path or a body key. The catalog is authoritative for paths; the docs are
+authoritative for semantics.
+
+## 1. The OpenAPI schema is only half-trustworthy — read the `example`
+
+The CMS generates its swagger from NestJS decorators, and 311 `type` values in it are TypeScript
+expressions rather than JSON Schema types: `Record<string, any>`, `CommonLocalizeInfos`,
+`AttributesSets`, `number | string`, `image`, `date`. `cms_api_describe` normalizes what it can and
+marks the rest `"x-loose": true`.
+
+**When a field is `x-loose`, the `example` is the contract.** Copy its shape. Client-side
+validation is deliberately advisory — the server is the real validator, so a call is never blocked
+just because a loose field could not be checked.
+
+## 2. Content lives under a locale key: `localizeInfos`
+
+Titles and content are never plain strings. They are objects keyed by locale code:
+
+```json
+{ "localizeInfos": { "en_US": { "title": "Catalog", "plainContent": "…", "htmlContent": "<b>…</b>", "menuTitle": "Catalog" } } }
+```
+
+`localizeInfos` is **required** on product creation and effectively required on pages. Get the
+active locale codes from the Locales operations (`cms_api_search "locales"`) — never hardcode
+`en_US`. Writing a locale that is not configured on the stand silently produces content nobody
+can see.
+
+→ `back/docs/postgres-db-with-attribute-index`, `front/docs/isPrice-attribute`
+
+## 3. Product/page payloads are attribute-set-driven — and `attributesSets` is locale-keyed
+
+`CreateProductDto` requires all three of `localizeInfos`, `attributeSetId` and `attributesSets`.
+`attributesSets` is `Record<locale, Record<key, value>>` — **two levels**, the outer one a locale
+code. The inner key encodes the attribute type and id: `<type>_id<attributeId>`.
+
+```json
+{
+  "attributeSetId": 44,
+  "attributesSets": {
+    "en_US": { "string_id1": "Haircut", "float_id3": 35, "groupOfImages_id7": [] }
+  }
+}
+```
+
+**The swagger `example` on this field is wrong**: it shows the flat map `{ "id7": 7,
+"string_id18": "" }`. Posting that flat shape returns **201 and stores `attributesSets: {}`** —
+no warning, no 400. The product then exists with a title and is empty in every field. This is the
+one place where the rule "the example is the contract" (§1) does not hold; the locale-wrapped
+shape above is confirmed against stored products.
+
+So you cannot construct a product payload without first reading the attribute set: fetch it, see
+which attributes it declares, then build the map under the active locale code. Skipping this is
+the single most common cause of a product that saves but shows up empty.
+
+After creating a product, **read it back by id** and check that `attributesSets` is not `{}`.
+That single read is the only defence against the silent drop.
+
+→ `back/docs/postgres-db-with-attribute-index`, `back/docs/attribute-indexing`
+
+## 4. `position` is a lexorank string on some endpoints and a number on others
+
+- Content API positions — **numeric** display index.
+- Admin API *parent-scoped* positions (block on a page, page in a menu, child in a tree) —
+  **lexorank strings**.
+- Admin API *flat lists* (e.g. `GET /api/admin/blocks`) — **numeric** display index, intentionally.
+
+Never send a number where a lexorank is expected, and never sort by a lexorank numerically.
+Reordering is done through the dedicated `…/position` operations, not by patching the field.
+
+→ `back/tests/e2e-conventions` §2, `back/docs/filters`
+
+## 5. Writes are eventually consistent — a read straight after a write can lie
+
+Attribute values reach `index_attribute_data` through the Bull `index-data` queue; Elasticsearch
+(`products_v1`, `pages_v1`, `blocks_v1`) and the materialized views (`pages_view`, `blocks_view`)
+lag behind the base tables. A freshly created entity may be absent from a list or search response
+for seconds.
+
+If a read does not show your write: re-read the entity by id (base tables, always current) before
+concluding the write failed. Never "fix" it by writing again — you will create duplicates.
+
+→ `back/docs/attribute-indexing`, `back/docs/elastic`, `back/tests/e2e-conventions` §3
+
+## 6. `marker` is the stable identifier; `id` is not portable
+
+Blocks, modules, forms and general types are addressed by `marker` across stands. An `id` from a
+dev stand is meaningless on production. When you have a choice of operation, prefer the
+marker-based one.
+
+## 7. Never touch these without a human saying so in this conversation
+
+`immutable-settings`, `admins`, `backups`, `modules/{id}/deploy|suspend|resume`,
+`payments/webhook/**`, `auth/logout/all-users`, `settings-general`. They are permanently
+confirm-gated regardless of the `--allow` level. If a prompt implies one of them, say what you
+would do and stop.
+
+## 8. Permissions are per-action and pre-checked
+
+Every admin carries an `AdminPermissionsEnum` map (`settings.attributes.create`,
+`menu.items.changePositions`, …). 243 operations declare a required permission, and `cms_api_call`
+refuses locally when the authenticated admin lacks it — so a permission error means "ask for the
+grant", not "retry".
+
+Note the Admin API rejects accounts flagged `isDeveloper`: those belong to the separate Developer
+API, which this server does not expose.
+
+→ `back/docs/user-permissions`
+
+## 9. If you changed backend code, a test suite may be mandatory
+
+`back/CLAUDE` lists modules whose e2e suite **must** be run after a change:
+attributes-sets, admins, menus, templates, template-previews, import, orders. Never edit a test to
+make it green.
+
+→ `back/CLAUDE`, `back/tests/e2e-conventions`
+
+## 10. Responses are truncated on purpose
+
+A list response is capped and the overflow replaced with `_truncated: { shown, total, hint }`.
+That is not an API limit — narrow the query with the operation's own `limit`/`offset`/filter
+parameters instead of asking for everything.
+
+## 11. Known dnk-back defects — do not debug them, work around them
+
+Every item here was hit for real against a stock stand. They are backend defects, not payload
+mistakes: retrying with a "better" body will not help.
+
+- **`POST /forms` wants the payload nested under `newForm`.** The controller binds
+  `@Body('newForm')`, but swagger documents `CreateFormDto` flat — so the catalog and
+  `cms_api_describe` show the wrong shape. A flat body gives
+  `500 — null value in column "processing_type"`. Send
+  `{ "newForm": { "identifier": "…", "processingType": "db", "localizeInfos": { … } } }`.
+- **`PUT /products/{id}` needs `blocks`.** Omitting it gives
+  `500 — updateProductDto.blocks is not iterable`; send `blocks: []` when you have nothing to set.
+  Conversely `forms` is accepted by the DTO and then explodes in TypeORM
+  (`No entity column "forms" was found`) — never send it on update.
+- **`GET /locales` answers `500 — column "nan" does not exist`.** Use
+  `AdminLocalesController_findAllActive` (`GET /locales/active/all`) to read locale codes.
+- **There is no `GET /products` list.** The list operation is `POST /products/all`
+  (`AdminProductsController_findAll`); `GET /products/quick/search?name=…` is the cheap lookup but
+  returns only `{ id, title, pageId }`. Fetch the full object with `GET /products/{id}`.
+- **`orders.export`, `payments.export`, `users.export`** are required by controllers but absent
+  from `AdminPermissionsEnum`, so those operations always answer 403. `cms_whoami` reports this as
+  a catalog warning; report it to the human rather than retrying.
+
+## 12. Type ids that no document states
+
+`typeId` on an attribute set is **not** the general type of a page — it is the separate audience
+enum `AttributesSetType` (`forAdmins`, `forBlocks`, `forOrders`, `forPages`, `forProducts`,
+`forUsers`, `forUserGroups`, `forDiscounts`; note the key `forBlock` maps to the value `forBlocks`).
+It is stored as a row id in `attribute_set_types`, that table can hold values beyond the enum, and
+there is no lookup operation for it — so the numeric ids are **stand data, not constants**.
+
+Observed on one stock stand: `2 = forBlocks`, `4 = forPages`, `5 = forProducts`, `6 = forUsers`,
+`7 = forForms`, `9 = forEvents`, `10 = system`; page `generalTypeId` `4 = catalog_page`,
+`11 = form`, `17 = common_page`, `18 = common_block`, `23 = discount`. Treat these as a hint, not
+a contract. **Verify before writing**: read `GET /general-types` for page types, and read an
+existing attribute set of the kind you want to see its `typeId`. An id from another stand is not
+portable (§6).
+
+Discount configuration values: `discountType ∈ {NONE, PERCENTAGE, FIXED_AMOUNT, FIXED_PRICE}`,
+`applicability ∈ {TO_PRODUCT, TO_ORDER}`, `type ∈ {DISCOUNT, BONUS, PERSONAL_DISCOUNT}`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oneentry/mcp-platform-server",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "MCP server that lets an AI agent operate the OneEntry Admin API, grounded in the project's own rules",
   "license": "UNLICENSED",
   "type": "module",
@@ -28,16 +28,16 @@
   "files": [
     "dist",
     "data",
+    "knowledge",
     "README.md"
   ],
   "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": "tsx build/publish-knowledge.ts",
     "lint": "eslint \"{src,build,__tests__}/**/*.ts\"",
     "test": "vitest run",
     "test:watch": "vitest",