@oneentry/mcp-platform-server 0.1.8 → 0.1.9

package/dist/api/build-catalog.js

@@ -1,4 +1,5 @@
 import { createHash } from 'node:crypto';
+import { phantomPathParams } from './client.js';
 import { capSchema, normalizeSchema } from './normalize-schema.js';
 import { ALWAYS_CONFIRM_PREFIXES, OPERATION_NOTES } from './operation-notes.js';
 const API_PREFIX = '/api/admin';
@@ -167,6 +168,7 @@ export const buildCatalog = (params) => {
     const withoutOpId = [];
     const unresolvedBodies = [];
     const contradictoryExamples = [];
+    const undeliverableParams = [];
     for (const [fullPath, pathItem] of Object.entries(swagger['paths'])) {
         if (!isRecord(pathItem)) {
             continue;
@@ -225,6 +227,10 @@ export const buildCatalog = (params) => {
             entry.searchText = [opId, method.toUpperCase(), path, tag, summary, permission ?? '']
                 .join(' ')
                 .toLowerCase();
+            const phantom = phantomPathParams(entry);
+            if (phantom.length > 0) {
+                undeliverableParams.push(`${opId} (${phantom.join(', ')} on ${path})`);
+            }
             operations.push(entry);
         }
     }
@@ -250,6 +256,13 @@ export const buildCatalog = (params) => {
             'Those fields are marked "x-example-mismatch" and listed by cms_api_describe — ' +
             'copy the example, not the type. Report it against the CMS.');
     }
+    if (undeliverableParams.length > 0) {
+        warnings.push(`${String(undeliverableParams.length)} operation(s) declare a path parameter that their ` +
+            `own path does not contain (${undeliverableParams.slice(0, 5).join(', ')}). ` +
+            'The value has nowhere to go, so this server refuses those calls instead of sending ' +
+            'the request without it. cms_api_describe marks them "notExecutable" and names a ' +
+            'working route where one is known. Report it against the CMS.');
+    }
     const noted = Object.keys(OPERATION_NOTES);
     const notedButAbsent = noted.filter((opId) => !operations.some((operation) => operation.opId === opId));
     if (notedButAbsent.length > 0 && notedButAbsent.length <= noted.length / 2) {

package/dist/api/client.d.ts

@@ -22,6 +22,8 @@ export declare class RequestBuildError extends Error {
 }
 export declare const normalizeBody: (body: unknown) => unknown;
 export declare const unsupportedBodyFormat: (operation: Operation) => string | undefined;
+export declare const phantomPathParams: (operation: Operation) => string[];
+export declare const undeliverablePathParams: (operation: Operation) => string | undefined;
 export declare const buildUrl: (baseUrl: string, operation: Operation, args: CallArgs) => string;
 export declare class AdminApiClient {
     private readonly baseUrl;

package/dist/api/client.js

@@ -31,7 +31,26 @@ export const unsupportedBodyFormat = (operation) => {
     }
     return `${base} Report it to the human and use another route to that instance.`;
 };
+export const phantomPathParams = (operation) => operation.params
+    .filter((param) => param.location === 'path' && !operation.path.includes(`{${param.name}}`))
+    .map((param) => param.name);
+export const undeliverablePathParams = (operation) => {
+    const phantom = phantomPathParams(operation);
+    if (phantom.length === 0) {
+        return undefined;
+    }
+    return (`Operation ${operation.opId} declares ${phantom.map((name) => `"${name}"`).join(', ')} as a ` +
+        `path parameter, but its path ${operation.path} has no place to put it. The value cannot ` +
+        'reach the API, so the request would go out without it and do something other than what ' +
+        'you asked. The call is not executable through this server — find the operation that ' +
+        'takes the same values where the API really expects them with cms_api_search, and read ' +
+        '"note" in cms_api_describe for a route that has been verified.');
+};
 export const buildUrl = (baseUrl, operation, args) => {
+    const undeliverable = undeliverablePathParams(operation);
+    if (undeliverable !== undefined) {
+        throw new RequestBuildError(undeliverable);
+    }
     let path = operation.path;
     const provided = args.path ?? {};
     for (const param of operation.params) {
@@ -94,11 +113,11 @@ const readBody = async (response) => {
         return text.slice(0, 2000);
     }
 };
-const isLoginPage = (response, body) => {
-    if ((response.headers.get('content-type') ?? '').includes('text/html')) {
-        return true;
-    }
-    return typeof body === 'string' && body.trimStart().startsWith('<');
+const isLoginPage = (body) => typeof body === 'string' && body.trimStart().startsWith('<');
+const describeResponse = (response, body) => {
+    const contentType = response.headers.get('content-type') ?? 'no content type';
+    const text = typeof body === 'string' ? body : JSON.stringify(body ?? null);
+    return `${contentType}, body starts with "${text.trimStart().slice(0, 80).replace(/\s+/g, ' ')}"`;
 };
 const extractMessage = (body, fallback) => {
     if (typeof body === 'string') {
@@ -163,17 +182,18 @@ export class AdminApiClient {
                 response = await attempt(await this.tokens.refresh());
             }
             body = await readBody(response);
-            if (response.ok && isLoginPage(response, body)) {
+            if (response.ok && isLoginPage(body)) {
                 response = await attempt(await this.tokens.refresh());
                 body = await readBody(response);
-                if (response.ok && isLoginPage(response, body)) {
+                if (response.ok && isLoginPage(body)) {
                     return {
                         ok: false,
                         error: {
                             status: response.status,
                             message: `${operation.method.toUpperCase()} ${url} answered ${String(response.status)} with ` +
                                 'the instance login page instead of a result: the admin session is not valid and ' +
-                                're-authenticating did not change that. Nothing was written by this call.',
+                                're-authenticating did not change that. Nothing was written by this call. ' +
+                                `The response was ${describeResponse(response, body)}.`,
                             hint: 'Check the credentials this server runs with, then retry. Treat every write since ' +
                                 'the last verified read as unconfirmed and read those entities back.',
                         },

package/dist/api/operation-notes.js

@@ -57,6 +57,16 @@ export const OPERATION_NOTES = {
             'A body of { limit, offset, langCode } answers 400 complaining about langCode, because ' +
             'the validator is describing the query parameter you did not send.',
     },
+    AdminProductsController_removeMany: {
+        note: 'Not executable through this server: the document declares "ids" as a path parameter ' +
+            'while the path is /products, so the value has nowhere to go and the request would go ' +
+            'out as a bare DELETE /products. The verified way to delete a chosen set is the ' +
+            'operation on DELETE /api/admin/products/category/{pageId} with a body of ' +
+            '{ "ids": [ … ] } — find it with cms_api_search { "query": "products category delete" }. ' +
+            'The same route with the ids in the query string answers 500 instead, so send them in ' +
+            'the body. Deleting products one by one with AdminProductsController_remove is the other ' +
+            'route and needs no category.',
+    },
     AdminProductsController_setStatusForProducts: {
         note: 'The status id goes in "statusId". The older field name "id" is accepted for the same ' +
             'value, and a body carrying neither answers 400 rather than writing an empty status. ' +
@@ -223,7 +233,14 @@ export const OPERATION_NOTES = {
         note: '"formModuleConfigs" is a full replacement list, not a patch. Omitting it deletes every ' +
             'module binding of the form AND the submissions recorded against those bindings, and the ' +
             'call still answers 200 true. Read the form first and send its current formModuleConfigs ' +
-            'back unless changing them is the point. This is also the only operation that creates a ' +
+            'back unless changing them is the point. An existing binding is matched by its own "id" ' +
+            'and by nothing else: an entry carrying the same formId, moduleId and entityIdentifiers ' +
+            'but no id is created as a NEW binding, the previous one is deleted, and the submissions ' +
+            'counted against it stop being counted — the count route for the form goes to zero. ' +
+            'Worse, a public read of the entity keeps naming the previous binding for as long as its ' +
+            'answer is cached, so a site submitting against it answers 400 "Incorrect formIdentifier ' +
+            'for provided config" after the edit rather than during it. Echo formModuleConfigs[].id ' +
+            'back on every entry you are keeping. This is also the only operation that creates a ' +
             'binding: an entry with formId, moduleId and either isGlobal or entityIdentifiers. ' +
             'The rating behaviour of a review form lives in that same entry and has no operation of ' +
             'its own: isRating, ratingCalculation, maxRatingScale, allowHalfRatings, allowRerating ' +
@@ -247,8 +264,9 @@ export const OPERATION_NOTES = {
         },
         verifyWith: {
             opId: 'AdminFormsController_findOne',
-            check: 'formModuleConfigs',
-            why: 'an omitted formModuleConfigs is applied as "unbind everything", submissions included',
+            check: 'formModuleConfigs[].id',
+            why: 'an omitted formModuleConfigs is applied as "unbind everything", submissions included, ' +
+                'and a binding sent without its id comes back with a new one, which is the same loss',
         },
     },
     AdminFormDataController_create: {
@@ -263,9 +281,13 @@ export const OPERATION_NOTES = {
             'not mean the config is optional. A form with type null fails earlier with "Form has ' +
             'incorrect type". Field validation is wired into the Content API only: through the Admin ' +
             'API a missing required field is stored rather than rejected, so a submission accepted ' +
-            'here does not prove a visitor\'s submission would pass. A field of type text takes ' +
-            '[{ "htmlValue": "…" }] — a bare string, a list of strings and [{ "value": … }] are all ' +
-            'rejected. On a rating form the score attribute must be marked isRatingValue, or the ' +
+            'here does not prove a visitor\'s submission would pass. A field of type text takes a ' +
+            'list of ONE object carrying EXACTLY ONE of plainValue, htmlValue or mdValue and no ' +
+            'other key: [{ "plainValue": "…" }]. A bare string, a list of strings, ' +
+            '[{ "value": … }], two of the three keys together and the four-key shape an entity ' +
+            'attribute of type text uses (htmlValue, mdValue, plainValue, params) are each ' +
+            'rejected, the last two with a message that names no field. On a rating form the score ' +
+            'attribute must be marked isRatingValue, or the ' +
             'form is invalid with "Form must have a rating marker". This route also treats one ' +
             'authenticated author as one submission per entity, so it rejects the second review of a ' +
             'product with "You have already rated": a bulk import of visitor reviews cannot go ' +

package/dist/tools/api-discovery.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { unsupportedBodyFormat } from '../api/client.js';
+import { undeliverablePathParams, unsupportedBodyFormat } from '../api/client.js';
 import { errorResult, jsonResult } from './result.js';
 const sampleValue = (schema, example) => {
     if (example !== undefined) {
@@ -110,7 +110,7 @@ export const registerApiDiscovery = (server, deps) => {
                     : 'Operation ids come from cms_api_search — do not construct them by hand.',
             });
         }
-        const formatDenial = unsupportedBodyFormat(operation);
+        const formatDenial = unsupportedBodyFormat(operation) ?? undeliverablePathParams(operation);
         const properties = operation.body?.schema.properties;
         const loose = properties
             ? Object.entries(properties)
@@ -170,7 +170,8 @@ export const registerApiDiscovery = (server, deps) => {
             next: formatDenial
                 ? operation.body?.contentType === 'multipart/form-data'
                     ? 'Do not call this with cms_api_call — upload with cms_upload_file or cms_import_file_from_url.'
-                    : 'Do not call this operation — report it as unavailable through MCP.'
+                    : 'Do not call this operation. Take the route named in "notExecutable" or in ' +
+                        '"note" above, and report it as unavailable through MCP when there is none.'
                 : operation.risk === 'read'
                     ? 'Call it with cms_api_call, copying the "example" above.'
                     : operation.verifyWith

package/knowledge/operating-rules.md

@@ -51,7 +51,7 @@ Ordering is a lexorank **string** on parent-scoped Admin operations and a **numb
 
 ## A read straight after a write can lag
 
-Reading an entity **by id** shows your write immediately; lists and searches may lag by seconds. So re-read by id and **never repeat the write** — that makes a duplicate somebody cleans up by hand. Never swallow a failed read into an empty result either: the next run then recreates everything.
+An **admin** read by id shows your write immediately; admin lists and **every public read**, one entity included, lag by seconds. So re-read after a pause and **never repeat the write** — that makes a duplicate somebody cleans up by hand. Never swallow a failed read into an empty result either: the next run then recreates everything.
 
 ## A 200 means accepted not applied
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oneentry/mcp-platform-server",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "MCP server that lets an AI agent operate the OneEntry Admin API, grounded in the project's own rules",
   "license": "MIT",
   "type": "module",