@oneentry/mcp-platform-server 0.1.3 → 0.1.5

package/dist/tools/api-discovery.js

@@ -1,5 +1,56 @@
 import { z } from 'zod';
+import { unsupportedBodyFormat } from '../api/client.js';
 import { errorResult, jsonResult } from './result.js';
+const sampleValue = (schema, example) => {
+    if (example !== undefined) {
+        return example;
+    }
+    if (schema.example !== undefined) {
+        return schema.example;
+    }
+    if (schema.enum && schema.enum.length > 0) {
+        return schema.enum[0];
+    }
+    switch (schema.type) {
+        case 'number':
+        case 'integer':
+            return 0;
+        case 'boolean':
+            return false;
+        case 'array':
+            return [];
+        case 'object':
+            return {};
+        default:
+            return `<${schema['x-source-type'] ?? schema.type ?? 'value'}>`;
+    }
+};
+const isWorthShowing = (param) => param.required ||
+    param.example !== undefined ||
+    param.schema.example !== undefined ||
+    param.schema.default !== undefined;
+const argsFor = (params, location, filter) => {
+    const out = {};
+    for (const param of params) {
+        if (param.location !== location || !filter(param)) {
+            continue;
+        }
+        out[param.name] = sampleValue(param.schema, param.example);
+    }
+    return out;
+};
+const callExample = (operation) => {
+    const path = argsFor(operation.params, 'path', () => true);
+    const query = argsFor(operation.params, 'query', isWorthShowing);
+    return {
+        opId: operation.opId,
+        ...(Object.keys(path).length > 0 ? { path } : {}),
+        ...(Object.keys(query).length > 0 ? { query } : {}),
+        ...(operation.body?.schema.example !== undefined
+            ? { body: operation.body.schema.example }
+            : {}),
+    };
+};
 export const registerApiDiscovery = (server, deps) => {
     const { catalog } = deps;
     server.registerTool('cms_api_search', {
@@ -22,10 +73,16 @@ export const registerApiDiscovery = (server, deps) => {
             ...(limit ? { limit } : {}),
         });
         if (hits.length === 0) {
+            const unexposed = catalog.unexposedMatches(query);
             return jsonResult({
                 hits: [],
                 tags: [...new Set(catalog.operations().map((o) => o.tag))].sort(),
-                hint: 'Nothing matched. Try a bare entity name, or filter by one of the tags listed here.',
+                ...(unexposed.length > 0 ? { knownButNotExposed: unexposed } : {}),
+                hint: unexposed.length > 0
+                    ? 'Nothing matched in this catalog, but the platform does know the names under ' +
+                        '"knownButNotExposed" — this instance simply does not serve them, so no path ' +
+                        'you construct will reach them. Do not guess URLs: report them as unavailable here.'
+                    : 'Nothing matched. Try a bare entity name, or filter by one of the tags listed here.',
             });
         }
         return jsonResult({
@@ -35,7 +92,7 @@ export const registerApiDiscovery = (server, deps) => {
     });
     server.registerTool('cms_api_describe', {
         title: 'Describe an Admin API operation',
-        description: 'Full detail for one operation: path and query parameters, request-body schema, required permission, risk level, and whether it is permanently confirm-gated. Fields marked "x-loose": true could not be converted to a JSON Schema type — trust their example, not their type.',
+        description: 'Full detail for one operation: a ready-to-copy "example" call, path and query parameters, request-body schema, required permission, risk level, and whether it is permanently confirm-gated. Fields marked "x-loose": true could not be converted to a JSON Schema type — trust their example, not their type. Where the operation is known to answer success without doing the work, "silentNoOp" and "verifyWith" say so and name the read that proves it.',
         inputSchema: {
             opId: z.string().min(1).describe('Operation id from cms_api_search, e.g. "AdminPagesController_findAllRoot".'),
         },
@@ -43,18 +100,28 @@ export const registerApiDiscovery = (server, deps) => {
     }, ({ opId }) => {
         const operation = catalog.get(opId);
         if (!operation) {
+            const unexposed = catalog.unexposedMatches(opId);
             return errorResult(`Unknown opId "${opId}".`, {
                 didYouMean: catalog.suggest(opId),
-                hint: 'Operation ids come from cms_api_search — do not construct them by hand.',
+                ...(unexposed.length > 0 ? { knownButNotExposed: unexposed } : {}),
+                hint: unexposed.length > 0
+                    ? 'The platform knows this name, but this instance does not serve the operation, ' +
+                        'so it cannot be called from here by any path. Report it as unavailable.'
+                    : 'Operation ids come from cms_api_search — do not construct them by hand.',
             });
         }
-        const loose = [
-            ...(operation.body?.schema.properties
-                ? Object.entries(operation.body.schema.properties)
-                    .filter(([, schema]) => schema['x-loose'] === true)
-                    .map(([name, schema]) => ({ field: name, sourceType: schema['x-source-type'] }))
-                : []),
-        ];
+        const formatDenial = unsupportedBodyFormat(operation);
+        const properties = operation.body?.schema.properties;
+        const loose = properties
+            ? Object.entries(properties)
+                .filter(([, schema]) => schema['x-loose'] === true)
+                .map(([name, schema]) => ({ field: name, sourceType: schema['x-source-type'] }))
+            : [];
+        const mismatched = properties
+            ? Object.entries(properties)
+                .filter(([, schema]) => schema['x-example-mismatch'] !== undefined)
+                .map(([name, schema]) => ({ field: name, problem: schema['x-example-mismatch'] }))
+            : [];
         return jsonResult({
             opId: operation.opId,
             method: operation.method.toUpperCase(),
@@ -66,12 +133,41 @@ export const registerApiDiscovery = (server, deps) => {
             risk: operation.risk,
             alwaysConfirm: operation.alwaysConfirm,
             params: operation.params,
+            paramsByLocation: {
+                path: operation.params.filter((p) => p.location === 'path').map((p) => p.name),
+                query: operation.params.filter((p) => p.location === 'query').map((p) => p.name),
+            },
             body: operation.body ?? null,
+            example: callExample(operation),
             looseFields: loose,
+            ...(mismatched.length > 0
+                ? {
+                    exampleMismatches: mismatched,
+                    exampleMismatchHint: 'These fields declare one type and give an example of another. The example is ' +
+                        'the contract — the instance accepts what the example shows.',
+                }
+                : {}),
+            ...(operation.note ? { note: operation.note } : {}),
+            ...(operation.silentNoOp ? { silentNoOp: operation.silentNoOp } : {}),
+            ...(operation.verifyWith ? { verifyWith: operation.verifyWith } : {}),
+            ...(operation.body?.schema['x-unresolved'] === true
+                ? {
+                    bodySchemaUnresolved: 'The document does not resolve this body schema, so the empty "properties" ' +
+                        'above means "unknown", not "no fields". Build the body from "example"; ' +
+                        'if there is none, ask the human rather than guessing.',
+                }
+                : {}),
+            ...(formatDenial ? { notExecutable: formatDenial } : {}),
             responseSummary: operation.responseSummary ?? null,
-            next: operation.risk === 'read'
-                ? 'Call it with cms_api_call { opId, path, query }.'
-                : 'Search the knowledge base with cms_docs_search for this entity, then call cms_api_call with dryRun: true first.',
+            next: formatDenial
+                ? 'Do not call this operation — report it as unavailable through MCP.'
+                : operation.risk === 'read'
+                    ? 'Call it with cms_api_call, copying the "example" above.'
+                    : operation.verifyWith
+                        ? 'Search the knowledge base with cms_docs_search for this entity, call cms_api_call ' +
+                            `with dryRun: true first, and afterwards read the result back with ` +
+                            `${operation.verifyWith.opId} — a success status is not evidence here.`
+                        : 'Search the knowledge base with cms_docs_search for this entity, then call cms_api_call with dryRun: true first.',
         });
     });
 };

package/dist/tools/api-discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-discovery.js","sourceRoot":"","sources":["../../src/tools/api-discovery.ts"],"names":[],"mappings":"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"}

package/dist/tools/docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/tools/docs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAMhD,wDAAwD;AACxD,eAAO,MAAM,YAAY,GAAI,QAAQ,SAAS,EAAE,MAAM,UAAU,KAAG,IA0IlE,CAAC"}

package/dist/tools/docs.js

@@ -16,7 +16,10 @@ export const registerDocs = (server, deps) => {
         if (hits.length === 0) {
             return jsonResult({
                 hits: [],
-                hint: 'Nothing matched. Try a module name (menus, orders, blocks, attributes) or an entity field name.',
+                hint: 'Nothing matched. The knowledge base is written in English — ask in English, even ' +
+                    'when the conversation is not. Try a module name (menus, orders, blocks, ' +
+                    'attributes) or an entity field name. An empty result means this query found ' +
+                    'nothing, not that the CMS has no documentation for it.',
             });
         }
         return jsonResult({

package/dist/tools/docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.js","sourceRoot":"","sources":["../../src/tools/docs.ts"],"names":[],"mappings":"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"}

package/dist/tools/guide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guide.d.ts","sourceRoot":"","sources":["../../src/tools/guide.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAMhD;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,UAAU,KAAG,MAoD9C,CAAC;AAEF,gCAAgC;AAChC,eAAO,MAAM,aAAa,GAAI,QAAQ,SAAS,EAAE,MAAM,UAAU,KAAG,IAWnE,CAAC"}

package/dist/tools/guide.js

@@ -1,3 +1,4 @@
+import { ALWAYS_CONFIRM_PREFIXES } from '../api/operation-notes.js';
 import { textResult } from './result.js';
 const TAG_LIMIT = 24;
 export const renderGuide = (deps) => {
@@ -50,8 +51,19 @@ export const renderGuide = (deps) => {
         '## Hard limits',
         '',
         '- Admin API only. The Content and Developer APIs are deliberately not exposed.',
-        '- `immutable-settings`, `admins`, `backups`, `modules`, `payments/webhook`, `settings-general`,',
-        '  `system/captcha-keys` and `auth/logout/all-users` are permanently confirm-gated.',
+        `- Mutations under ${ALWAYS_CONFIRM_PREFIXES.map((p) => `\`${p}\``).join(', ')} are`,
+        '  permanently confirm-gated, at every allow level.',
+        '- **Request bodies are sent as JSON only.** An operation that declares another format —',
+        '  file upload is `multipart/form-data` — cannot be called through this server at all.',
+        '  `cms_api_describe` marks it `notExecutable`; no body shape will help. Upload files',
+        '  outside MCP and read `mcp/docs/api/files-and-uploads` first, because doing so gives up',
+        '  the confirmations, permission checks and `dryRun` this server provides.',
+        '- **The knowledge base is written in English.** Search it in English whatever language the',
+        '  conversation is in; an empty result is a failed query, not a missing document.',
+        '- A success status is not evidence that the write landed. Where an operation is known to',
+        '  answer success without doing the work, `cms_api_describe` says so under `silentNoOp` and',
+        '  names the read that proves it under `verifyWith`. Verify with the read the *consumer*',
+        '  uses, not the one you wrote to.',
         '- Responses are capped; overflow is reported as `_truncated`. Narrow the query instead.',
         ...(catalog.catalog.warnings.length > 0
             ? ['', '## Warnings', '', ...catalog.catalog.warnings.map((w) => `- ${w}`)]

package/dist/tools/guide.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guide.js","sourceRoot":"","sources":["../../src/tools/guide.ts"],"names":[],"mappings":"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"}

package/dist/tools/result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../src/tools/result.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAC/C,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,+BAA+B;AAC/B,eAAO,MAAM,UAAU,GAAI,SAAS,OAAO,KAAG,UAE5C,CAAC;AAEH,kEAAkE;AAClE,eAAO,MAAM,UAAU,GAAI,MAAM,MAAM,KAAG,UAExC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,WAAW,GAAI,SAAS,MAAM,EAAE,QAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,UAK7E,CAAC"}

package/dist/tools/result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.js","sourceRoot":"","sources":["../../src/tools/result.ts"],"names":[],"mappings":"AAOA,+BAA+B;AAC/B,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,OAAgB,EAAc,EAAE,CAAC,CAAC;IAC3D,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;CACpE,CAAC,CAAC;AAEH,kEAAkE;AAClE,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,IAAY,EAAc,EAAE,CAAC,CAAC;IACvD,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;CAClC,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,OAAe,EAAE,KAA+B,EAAc,EAAE,CAAC,CAAC;IAC5F,OAAO,EAAE;QACP,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE;KACtF;IACD,OAAO,EAAE,IAAI;CACd,CAAC,CAAC"}

package/dist/tools/whoami.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"whoami.d.ts","sourceRoot":"","sources":["../../src/tools/whoami.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAG7C,4EAA4E;AAC5E,eAAO,MAAM,cAAc,GAAI,QAAQ,SAAS,EAAE,YAAY,MAAM,OAAO,KAAG,IA4C7E,CAAC"}

package/dist/tools/whoami.js

@@ -26,6 +26,11 @@ export const registerWhoami = (server, getSession) => {
                 swaggerHash: catalog.catalog.swaggerHash,
                 builtAt: catalog.catalog.builtAt,
                 knownPermissions: catalog.catalog.permissions.length,
+                coverage: {
+                    unexposedOperations: catalog.catalog.coverage.unexposedOpIds.length,
+                    permissionsWithoutOperation: catalog.catalog.coverage.permissionsWithoutOperation.length,
+                    hint: 'This catalog is what the instance serves, not everything the platform has. When cms_api_search finds nothing, it reports whether the name exists but is unexposed — trust that over constructing a path.',
+                },
                 warnings: catalog.catalog.warnings,
             },
             knowledge: {

package/dist/tools/whoami.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"whoami.js","sourceRoot":"","sources":["../../src/tools/whoami.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,4EAA4E;AAC5E,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,MAAiB,EAAE,UAAyB,EAAQ,EAAE;IACnF,MAAM,CAAC,YAAY,CACjB,YAAY,EACZ;QACE,KAAK,EAAE,UAAU;QACjB,WAAW,EACT,0JAA0J;QAC5J,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE;KACzD,EACD,KAAK,IAAI,EAAE;QACT,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;QAC7B,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;QACtD,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,QAAQ,EAAE,CAAC;QAE1C,OAAO,UAAU,CAAC;YAChB,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,aAAa,EAAE,QAAQ,KAAK,SAAS;YACrC,GAAG,CAAC,QAAQ;gBACV,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,QAAQ,CAAC,EAAE,EAAE,eAAe,EAAE,QAAQ,CAAC,WAAW,CAAC,MAAM,EAAE,WAAW,EAAE,QAAQ,CAAC,WAAW,EAAE,EAAE;gBACjH,CAAC,CAAC;oBACE,KAAK,EAAE,IAAI;oBACX,IAAI,EAAE,OAAO,CAAC,YAAY;wBACxB,CAAC,CAAC,0IAA0I;wBAC5I,CAAC,CAAC,oGAAoG;iBACzG,CAAC;YACN,OAAO,EAAE;gBACP,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC,MAAM;gBACvC,WAAW,EAAE,OAAO,CAAC,OAAO,CAAC,WAAW;gBACxC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,OAAO;gBAChC,gBAAgB,EAAE,OAAO,CAAC,OAAO,CAAC,WAAW,CAAC,MAAM;gBACpD,QAAQ,EAAE,OAAO,CAAC,OAAO,CAAC,QAAQ;aACnC;YACD,SAAS,EAAE;gBACT,MAAM,EAAE,SAAS,CAAC,IAAI,CAAC,MAAM;gBAC7B,OAAO,EAAE,SAAS,CAAC,IAAI,CAAC,OAAO;gBAC/B,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,CAAC,MAAM;gBAC7B,QAAQ,EAAE,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM;aACvC;YACD,KAAK,EAAE,MAAM,CAAC,SAAS,IAAI,IAAI;SAChC,CAAC,CAAC;IACL,CAAC,CACF,CAAC;AACJ,CAAC,CAAC"}

package/dist/transports/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/transports/http.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AA6DlD;;;;GAIG;AACH,eAAO,MAAM,OAAO,GAAU,QAAQ,MAAM,KAAG,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAiFpF,CAAC"}

package/dist/transports/http.js

@@ -45,7 +45,7 @@ const fillCatalog = async (deps, session) => {
     }
     try {
         const bearer = await session.accessToken();
-        const rebuilt = await OperationCatalog.resolve(deps.config, bearer);
+        const rebuilt = await OperationCatalog.resolve(deps.config, { bearer });
         if (!rebuilt.isEmpty) {
             deps.catalog.adopt(rebuilt);
         }

package/dist/transports/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/transports/http.ts"],"names":[],"mappings":"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"}

package/dist/transports/stdio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.d.ts","sourceRoot":"","sources":["../../src/transports/stdio.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAGlD;;;;GAIG;AACH,eAAO,MAAM,QAAQ,GAAU,QAAQ,MAAM,KAAG,OAAO,CAAC,IAAI,CAK3D,CAAC"}

package/dist/transports/stdio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.js","sourceRoot":"","sources":["../../src/transports/stdio.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAE9D,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAExC;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,KAAK,EAAE,MAAc,EAAiB,EAAE;IAC9D,MAAM,IAAI,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACtC,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,CAAC;IACjD,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC;AACnD,CAAC,CAAC"}

package/knowledge/operating-rules.md

@@ -1,25 +1,23 @@
 # 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.
+Read this before your first write. Every rule here has broken a real payload; each links to the document explaining it in full. When one 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.
+2. `cms_docs_search` for the entity you are about to touch — **before** the payload, not after a 400.
+3. `cms_api_search` for the operation, then `cms_api_describe` for its 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.
+Never invent a path, an operation id or a body key. `cms_api_search` is the only authority on what exists.
 
 ## 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`.
+The API document carries field types that are not JSON Schema types. `cms_api_describe` normalises what it can and marks the rest `"x-loose": true`.
 
-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.
+For those, **the `example` is the contract** — copy its shape. Validation here is advisory; the instance is the real validator, so a call is never blocked over a field we could not check. A field flagged `x-example-mismatch` contradicts its own type, and the example wins there too.
 
 → `mcp/docs/server/cms-api-describe#loose-fields`
 
@@ -31,7 +29,7 @@ Titles and descriptive content live under `localizeInfos`, keyed by locale code:
 { "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.
+Required on a product, effectively required on a page. Do not hardcode `en_US`: read the active locales with `AdminLocalesController_findAllActive` and write every one the content is meant to appear in.
 
 → `mcp/docs/api/locales`
 
@@ -43,79 +41,90 @@ Required when creating a product, and effectively required on pages. Do not hard
 { "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.
+The inner key is `<attribute type>_id<attribute id>`, read from the entity's attribute set. A flat one-level map is accepted, answers 201 and stores nothing — so 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.
+Ordering is a lexorank **string** on parent-scoped Admin operations and a **number** on flat lists and the Content API. Never sort a lexorank numerically, and never reorder by patching the field — use that entity's position operation.
 
 → `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.
+Reading an entity **by id** shows your write immediately. Lists and searches 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.
+If a list does not show what you just created, re-read by id. **Never repeat the write** — you get a duplicate that consumes quota and has to be cleaned up by hand. And never swallow a failed read into an empty result: "empty" and "malformed" then look alike, and the next run recreates everything.
 
-## Prefer marker over id
+## A 200 means accepted not applied
+
+Several endpoints take the body as one opaque value, so a wrong **shape** is stored as happily as a right one and the answer is still `200`.
+
+Confirm a write by its effect, and **through the read its consumer uses**. The raw record echoes your input back, wrong shape included, while the projection a site receives shows nothing — verifying through the endpoint you wrote to proves little.
+
+→ `mcp/docs/api/silent-no-ops`
+
+## An omitted field can mean clear it
+
+Most updates merge. A few apply an omitted field as **"set it to nothing"**, and still answer `200`: a page without `parentId` moves to the root, a block without `blockPages` detaches from every page, a menu item without its parent reference flattens, a user without `formData` loses it.
+
+Products, `generalTypeId` and `attributeSetId` merge, so "PUT always replaces" is the wrong lesson. Read, change what you meant to, send it back whole — then check the fields that were **not** in your body.
 
-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.
+→ `mcp/docs/server/payload-conventions#an-omitted-field-can-mean-clear-it`
 
-Where an operation accepts either, use the marker.
+## Prefer marker over id
+
+Blocks, forms, menus, templates, general types and modules are addressed by a `marker` or `identifier` stable across instances. A numeric `id` is not, and a `404` on an id you were given is usually that. 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.
+Every instance arrives populated: user groups, modules, general types, attribute set and field types, locales, block types with their default templates, the singleton settings.
+
+**List first, create second.** Some duplicates fail loudly, which is harmless. The dangerous ones — user groups, modules, attribute set types, settings — **succeed silently**.
 
-**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.
+Two lists are the exception and start **empty**: product statuses and template previews. Nothing seeds them, nothing reports their absence, and without them no product is sellable and no upload gets a preview. There, create.
 
 → `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.
+Mutations on the instance's own configuration — admins, modules, backups, settings — are permanently confirm-gated at every allow level. `cms_guide` prints the exact list.
 
-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.
+The gate is not a suggestion. State what you intend to change, show the human the dry run's `target`, and wait for a yes here.
 
 → `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.
+Each operation declares the permission it needs, and this server refuses locally when the admin does not hold it. Nothing is sent, so nothing changed. A refusal means **ask for the grant** and stop — no retry and no sibling operation gets past it.
 
 → `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.
+A large response comes 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. Do not retry hoping for more — narrow the request with the operation's own `limit`, `offset` and filters.
 
 → `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.
+One route works and the obvious alternative does not. Use it directly.
 
-- **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.
+- **Create a form** — wrap in `newForm`, with `type` (`data` for a contact form) though the schema omits it.
+- **Replace an attribute set schema** — send the schema object itself. Wrapped as `{ "schema": … }` it answers 200 and destroys it.
+- **Update a product** — include `blocks` (`[]` if nothing to set), never `forms`.
+- **Create a menu** — with `pagesIds: []`, attaching pages later. Non-empty on create answers 500.
+- **Set a product status** — `statusId` in the product update. Bulk `set-status` takes it in a field named `id`, and given `statusId` it nulls the status and answers `201 true`.
 
-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.
+## List products and other calls whose input is split
 
-## Where to look next
+`POST /products/all` is the only way to list products, and its input is split: **paging and `langCode` go in the query, the body is an array of filters** — `[]` for none. Sent in the body they are ignored, and the 400 blames `langCode` for a value you never sent.
+
+Copy `example` from `cms_api_describe` whole: separate `params` and `body` schemas do not assemble into an obvious call, and `example` is already one.
 
-With the operation hints removed from `cms_api_describe`, `cms_docs_search` and the map below are how you find anything.
+A 5xx outside these two lists means stop and report it, with the operation id and the request.
+
+## Where to look next
 
-- `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
+`mcp/docs/server/doc-map` lists every document with a reason to read it. The corpus is **English** — search it in English whatever language you answer in.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oneentry/mcp-platform-server",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "MCP server that lets an AI agent operate the OneEntry Admin API, grounded in the project's own rules",
   "license": "MIT",
   "type": "module",
@@ -50,6 +50,7 @@
     "start": "node dist/bin/cli.js",
     "dev": "tsx src/bin/cli.ts",
     "sync:permissions": "tsx build/sync-permissions.ts",
+    "docs:audit": "tsx build/docs-audit.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",