@oneentry/mcp-platform-server 0.1.4 → 0.1.6

package/dist/tools/upload.js

@@ -0,0 +1,229 @@
+import { z } from 'zod';
+import { AuditLog } from '../api/audit.js';
+import { buildUrl, RequestBuildError } from '../api/client.js';
+import { checkLevel, decide } from '../api/policy.js';
+import { shapeResponse } from '../api/shape.js';
+import { fetchRemoteUpload, readLocalUpload, resolveUploadOperation, UploadSourceError, } from '../api/upload.js';
+import { errorResult, jsonResult } from './result.js';
+const targetingSchema = {
+    type: z
+        .string()
+        .optional()
+        .describe('What kind of file this is, e.g. "image" or "file". Copy the values cms_api_describe lists.'),
+    entity: z
+        .string()
+        .optional()
+        .describe('The entity kind the file belongs to, e.g. "product", "page", "block".'),
+    id: z.number().int().optional().describe('Id of the entity the file belongs to.'),
+    template: z
+        .number()
+        .int()
+        .optional()
+        .describe('NUMERIC id of a /template-previews record. Without a valid one no previewLink is ever generated and nothing reports it.'),
+    compress: z.boolean().optional().describe('Ask the instance to compress the image.'),
+    edit: z.boolean().optional().describe('Replace an existing file rather than adding one.'),
+    dryRun: z
+        .boolean()
+        .optional()
+        .describe('Do not send: return the resolved request, the resolved source and the policy decision.'),
+    confirm: z.string().optional().describe('Confirm token from a dryRun of this exact call.'),
+};
+const queryOf = (args) => {
+    const query = {};
+    for (const key of ['type', 'entity', 'id', 'template', 'compress', 'edit']) {
+        const value = args[key];
+        if (value !== undefined) {
+            query[key] = value;
+        }
+    }
+    return query;
+};
+const runUpload = async (params) => {
+    const { session, toolName, args, load, source } = params;
+    const { config, catalog, audit } = session.shared;
+    const operation = resolveUploadOperation(catalog);
+    if (!operation) {
+        return errorResult('This instance does not expose a file upload operation, so there is nothing to send to. ' +
+            'Report it rather than trying another path.', { tool: toolName });
+    }
+    const query = queryOf(args);
+    const callArgs = { ...(Object.keys(query).length > 0 ? { query } : {}) };
+    const argsHash = AuditLog.hashArgs({ ...callArgs, body: source });
+    const auditBase = {
+        opId: operation.opId,
+        method: operation.method.toUpperCase(),
+        path: operation.path,
+        argsHash,
+    };
+    const levelDenial = checkLevel(operation, config.allow);
+    if (levelDenial) {
+        audit.record({ ...auditBase, outcome: 'denied' });
+        return errorResult(levelDenial.reason, {
+            tool: toolName,
+            policy: config.allow,
+            risk: operation.risk,
+        });
+    }
+    const identity = operation.permission ? await session.identity() : undefined;
+    if (identity) {
+        Object.assign(auditBase, { adminId: identity.id });
+    }
+    const confirmValid = args.confirm !== undefined && session.confirms.verify(args.confirm, operation.opId, callArgs);
+    if (args.confirm !== undefined && !confirmValid) {
+        return errorResult('Confirm token is expired, already used, or does not match these arguments. Re-run with dryRun: true to get a fresh one.', { tool: toolName });
+    }
+    const decision = decide({
+        operation,
+        allow: config.allow,
+        ...(identity ? { identity } : {}),
+        confirmValid,
+    });
+    if (decision.kind === 'deny') {
+        audit.record({ ...auditBase, outcome: 'denied' });
+        return errorResult(decision.reason, {
+            tool: toolName,
+            policy: config.allow,
+            risk: operation.risk,
+        });
+    }
+    let url;
+    try {
+        url = buildUrl(config.baseUrl, operation, callArgs);
+    }
+    catch (error) {
+        if (error instanceof RequestBuildError) {
+            return errorResult(error.message, { tool: toolName, params: operation.params });
+        }
+        throw error;
+    }
+    if (decision.kind === 'needsConfirm') {
+        const token = session.confirms.issue(operation.opId, callArgs);
+        audit.record({ ...auditBase, outcome: 'needs-confirm' });
+        return jsonResult({
+            needsConfirm: true,
+            reason: decision.reason,
+            request: { method: operation.method.toUpperCase(), url },
+            source,
+            confirm: token,
+            expiresInSeconds: 300,
+            next: 'Show the source and the target to the human, then repeat this exact call with the confirm token added.',
+        });
+    }
+    if (args.dryRun === true) {
+        return jsonResult({
+            dryRun: true,
+            request: { method: operation.method.toUpperCase(), url },
+            source,
+            policy: { allow: config.allow, risk: operation.risk, decision: 'would be sent' },
+            ...(args.template === undefined
+                ? {
+                    warning: 'No "template" given. The file will be stored without a previewLink, no error will ' +
+                        'be reported, and the only repair is uploading it again. Read /template-previews ' +
+                        'first and pass the numeric id.',
+                }
+                : {}),
+        });
+    }
+    if (args.confirm !== undefined && !session.confirms.consume(args.confirm, operation.opId, callArgs)) {
+        return errorResult('Confirm token was consumed concurrently. Re-run with dryRun: true to get a fresh one.', { tool: toolName });
+    }
+    let payload;
+    try {
+        payload = await load();
+    }
+    catch (error) {
+        if (error instanceof UploadSourceError) {
+            return errorResult(error.message, { tool: toolName, sent: false });
+        }
+        throw error;
+    }
+    const result = await session.client.upload(operation, callArgs, payload);
+    audit.record({
+        ...auditBase,
+        outcome: 'sent',
+        status: result.ok ? result.status : result.error.status,
+    });
+    if (!result.ok) {
+        return errorResult(result.error.message, {
+            tool: toolName,
+            status: result.error.status,
+            ...(result.error.hint ? { hint: result.error.hint } : {}),
+        });
+    }
+    const shaped = shapeResponse(result.body, config.maxResponseBytes);
+    return jsonResult({
+        tool: toolName,
+        opId: operation.opId,
+        status: result.status,
+        uploaded: { filename: payload.filename, contentType: payload.contentType, bytes: payload.bytes.byteLength },
+        truncated: shaped.truncated,
+        body: shaped.body,
+        next: 'Keep the WHOLE record as the attribute value, and check "previewLink": an upload with no ' +
+            'valid template id stores the file without one and reports no error. The record carries no ' +
+            '"alt" — alternative text needs a sibling attribute.',
+        ...(operation.note ? { note: operation.note } : {}),
+    });
+};
+export const registerUpload = (server, getSession) => {
+    server.registerTool('cms_upload_file', {
+        title: 'Upload a local file',
+        description: 'Upload one file from the machine running this server to the instance, as multipart — the one thing cms_api_call cannot send. Requires --allow=write, is audited, and supports dryRun. Local mode only: in remote mode there is no shared filesystem, so use cms_import_file_from_url. Pass "template" (the numeric id of a /template-previews record) or the file is stored with no preview and nothing reports it.',
+        inputSchema: {
+            path: z
+                .string()
+                .min(1)
+                .describe('Path to the file, absolute or relative to the server\'s upload root.'),
+            ...targetingSchema,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    }, async ({ path, ...args }) => {
+        const session = getSession();
+        const { config } = session.shared;
+        if (config.mode === 'remote') {
+            return errorResult('cms_upload_file reads a file from the machine running this server, and in remote mode ' +
+                'that machine is not yours: nothing was read and nothing was sent. Use ' +
+                'cms_import_file_from_url with a URL the operator allowed.', { tool: 'cms_upload_file', mode: config.mode });
+        }
+        return runUpload({
+            session,
+            toolName: 'cms_upload_file',
+            args,
+            source: { path, root: config.upload.root },
+            load: () => readLocalUpload({ path, root: config.upload.root, maxBytes: config.upload.maxBytes }),
+        });
+    });
+    server.registerTool('cms_import_file_from_url', {
+        title: 'Import a file from a URL',
+        description: 'Fetch one file over http(s) and upload it to the instance in a single step — the usual "take the image from the customer\'s site into the CMS" move. Requires --allow=write, is audited, and supports dryRun. Addresses resolving to private or loopback networks are refused, and in remote mode an operator allowlist is required. Pass "template" (the numeric id of a /template-previews record) or the file is stored with no preview.',
+        inputSchema: {
+            url: z.string().min(1).describe('Absolute http or https address of the file.'),
+            filename: z
+                .string()
+                .optional()
+                .describe('Override the stored file name; by default it comes from the URL.'),
+            ...targetingSchema,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    }, async ({ url, filename, ...args }) => {
+        const session = getSession();
+        const { config } = session.shared;
+        if (config.mode === 'remote' && config.upload.allowedHosts.length === 0) {
+            return errorResult('cms_import_file_from_url is disabled in remote mode until the operator sets ' +
+                '--upload-allowed-hosts: a URL supplied over a session would otherwise make this ' +
+                'server fetch anything reachable from where it runs. Nothing was fetched.', { tool: 'cms_import_file_from_url', mode: config.mode });
+        }
+        return runUpload({
+            session,
+            toolName: 'cms_import_file_from_url',
+            args,
+            source: { url, ...(filename !== undefined ? { filename } : {}) },
+            load: () => fetchRemoteUpload({
+                url,
+                allowedHosts: config.upload.allowedHosts,
+                maxBytes: config.upload.maxBytes,
+                timeoutMs: config.requestTimeoutMs,
+                ...(filename !== undefined ? { filename } : {}),
+            }),
+        });
+    });
+};

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/knowledge/operating-rules.md

@@ -1,25 +1,21 @@
 # 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, and each links to the document explaining it. When one applies, 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.
+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. Files go through `cms_upload_file` or `cms_import_file_from_url`.
 
-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`.
-
-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.
+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`, and for those **the `example` is the contract**. A field flagged `x-example-mismatch` contradicts its own type, and the example wins there too; a `curatedBody` beats both.
 
 → `mcp/docs/server/cms-api-describe#loose-fields`
 
@@ -31,7 +27,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. Never hardcode `en_US`: read the active locales and write every one the content is meant to appear in. The one structure that is **not** locale keyed is an option's extra value.
 
 → `mcp/docs/api/locales`
 
@@ -43,79 +39,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>`, from the entity's attribute set. A flat one-level map is accepted, answers 201 and stores nothing — read the entity back by id.
 
 → `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 public reads. Never sort a lexorank numerically, never reorder by patching the field, and never send a string one back to an update.
 
 → `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 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.
 
-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.
+## A 200 means accepted not applied
 
-## Prefer marker over id
+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, **through the read its consumer uses** — the raw record echoes your input back, wrong shape included.
+
+→ `mcp/docs/api/silent-no-ops`
 
-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.
+## 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 loses `parentId` to the root, a block loses every page attachment, a menu item flattens, a form loses its bindings and their submissions. Products 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.
+
+→ `mcp/docs/server/payload-conventions#an-omitted-field-can-mean-clear-it`
+
+## Prefer marker over id
 
-Where an operation accepts either, use the marker.
+Blocks, forms, menus, templates, general types and modules carry a `marker` or `identifier` stable across instances. A numeric `id` is not, and a `404` on an id you were handed is usually that. Where both are accepted, 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, the singleton settings. **List first, create second** — the dangerous duplicates (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 start **empty**: product statuses and template previews. Nothing reports their absence, yet 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.
-
-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.
+Mutations on the instance's own configuration — admins, modules, backups, settings — are confirm-gated at every allow level, and `cms_guide` prints the list. State what you intend to change, show the dry run's `target`, wait for a yes.
 
 → `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. **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 saying what was shown and what the total was — this server capping the answer, not the API. Do not retry for more; narrow the request with the operation's `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.
 
-- **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** — wrapped in `newForm`, with `type`, which the schema omits.
+- **Replace an attribute set schema** — 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: []`; non-empty answers 500. Nesting and labels come later.
+- **Set a product status** — `statusId` in the product update, not bulk `set-status`.
+- **Upload a file** — `cms_upload_file` or `cms_import_file_from_url`; `cms_api_call` sends JSON only.
 
-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` in the query, the body 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, and prefer `curatedBody` where it appears.
+
+A 5xx outside these two lists means stop and report it, with the operation id and the request.
 
-With the operation hints removed from `cms_api_describe`, `cms_docs_search` and the map below are how you find anything.
+## Reading it back is not always verifying
+
+Two cases where the habit is not enough:
+
+- **A batch write** can miss one entity while every response reports success. Re-read **all** of them — for products, by ids in one call — and retry the mismatches. Calculated values such as ratings arrive after a delay: wait, then check again.
+- **A field that exists for the admin panel** — an option's extra value, a flag like `multiselect` — comes back from every read exactly as sent, while the panel still shows it empty. Get a human to look, or report the check as incomplete and say what is unverified.
+
+→ `mcp/docs/api/bulk-content-migration#panel-facing-fields-cannot-be-verified-by-reading`
+
+## 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, and `mcp/docs/api/content-modelling` covers where content should go. 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.4",
+  "version": "0.1.6",
   "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",