@oneentry/mcp-platform-server 0.1.4 → 0.1.6

package/README.md

@@ -71,7 +71,7 @@ arguments, so a prompt-injected instruction cannot swap identities:
 
 Sessions never share tokens or confirm tokens. `GET /health` reports liveness and session count.
 
-## The seven tools
+## The nine tools
 
 | tool | what it does |
 |---|---|
@@ -79,12 +79,39 @@ Sessions never share tokens or confirm tokens. `GET /health` reports liveness an
 | `cms_docs_search` | search the knowledge base, returns sections with snippets |
 | `cms_docs_read` | read one section, with its sibling sections listed for paging |
 | `cms_api_search` | find operations by keyword / tag / method / mutating |
-| `cms_api_describe` | params, body schema, required permission, risk, confirm gating |
+| `cms_api_describe` | params, body schema, required permission, risk, confirm gating, and `curatedBody` where a shape has been verified on a live instance |
 | `cms_api_call` | execute one operation; `dryRun` and confirm-gating for mutations |
+| `cms_upload_file` | upload one file from this machine as `multipart/form-data` (local mode only) |
+| `cms_import_file_from_url` | fetch one file over http(s) and upload it in a single step |
 | `cms_whoami` | mode, base URL, admin + permissions, knowledge commit, catalog state and warnings |
 
 Plus two MCP resources: `oneentry://knowledge/mcp/operating-rules` and `oneentry://knowledge/index`.
 
+### Uploading files
+
+`cms_api_call` sends JSON only, and the upload endpoint wants `multipart/form-data` — which is why
+the two upload tools exist rather than a note telling the agent to go around the server. They run
+through the same gate as any other write: `--allow=write`, the local permission check, `dryRun`, and
+the audit line.
+
+Both bound their **source**, because a path or a URL arrives as a tool argument and a tool argument
+can be prompt-injected:
+
+| flag | env | default | what it bounds |
+|---|---|---|---|
+| `--upload-root` | `ONEENTRY_MCP_UPLOAD_ROOT` | the process working directory | `cms_upload_file` reads nothing outside this directory, symlinks resolved first |
+| `--upload-max-bytes` | `ONEENTRY_MCP_UPLOAD_MAX_BYTES` | 25 MiB | size of one file, checked on disk and on the wire |
+| `--upload-allowed-hosts` | `ONEENTRY_MCP_UPLOAD_ALLOWED_HOSTS` | empty | hosts `cms_import_file_from_url` may fetch from |
+
+`cms_upload_file` is refused in remote mode: there is no shared filesystem, and a session-supplied
+path would read the host's files. `cms_import_file_from_url` refuses any address resolving to a
+loopback, private, link-local or carrier-grade-NAT range, re-checks every redirect hop, and in remote
+mode stays disabled until the operator sets an allowlist.
+
+Pass `template` — the **numeric id** of a `/template-previews` record — on the first upload. Without
+it the file is stored with no `previewLink`, nothing reports the omission, and the only repair is
+uploading the file again.
+
 ## Write safety
 
 Read-only by default. `--allow` (or `ONEENTRY_MCP_ALLOW`) raises it:

package/dist/api/build-catalog.js

@@ -1,24 +1,69 @@
 import { createHash } from 'node:crypto';
 import { capSchema, normalizeSchema } from './normalize-schema.js';
+import { ALWAYS_CONFIRM_PREFIXES, OPERATION_NOTES } from './operation-notes.js';
 const API_PREFIX = '/api/admin';
 const METHODS = ['get', 'post', 'put', 'patch', 'delete'];
-const ALWAYS_CONFIRM = [
-    /^\/immutable-settings/,
-    /^\/admins/,
-    /^\/backups/,
-    /^\/modules/,
-    /^\/payments\/webhook/,
-    /^\/auth\/logout\/all-users/,
-    /^\/settings-general/,
-    /^\/system\/captcha-keys/,
-];
-const riskOf = (method) => {
+const ALWAYS_CONFIRM = ALWAYS_CONFIRM_PREFIXES.map((prefix) => new RegExp(`^${prefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`));
+const isGated = (path) => ALWAYS_CONFIRM.some((pattern) => pattern.test(path));
+const riskOf = (method, opId, path) => {
     if (method === 'get') {
         return 'read';
     }
+    if (method === 'post' && OPERATION_NOTES[opId]?.readOnly === true && !isGated(path)) {
+        return 'read';
+    }
     return method === 'delete' ? 'destructive' : 'write';
 };
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const jsonTypeOf = (value) => {
+    if (value === null) {
+        return 'null';
+    }
+    if (Array.isArray(value)) {
+        return 'array';
+    }
+    if (typeof value === 'number') {
+        return Number.isInteger(value) ? 'integer' : 'number';
+    }
+    return typeof value;
+};
+const typeFits = (declared, actual) => declared === actual ||
+    (declared === 'number' && actual === 'integer') ||
+    (declared === 'integer' && actual === 'number');
+const markExampleMismatch = (schema, field) => {
+    if (schema['x-loose'] === true || schema.example === undefined || schema.type === undefined) {
+        return undefined;
+    }
+    const actual = jsonTypeOf(schema.example);
+    if (!typeFits(schema.type, actual)) {
+        const message = `declared "${schema.type}", example is ${actual}`;
+        schema['x-example-mismatch'] = message;
+        return `${field} (${message})`;
+    }
+    if (schema.type === 'array' && schema.items?.type !== undefined && schema.items['x-loose'] !== true) {
+        const first = schema.example[0];
+        if (first !== undefined && !typeFits(schema.items.type, jsonTypeOf(first))) {
+            const message = `items declared "${schema.items.type}", example items are ${jsonTypeOf(first)}`;
+            schema['x-example-mismatch'] = message;
+            return `${field} (${message})`;
+        }
+    }
+    return undefined;
+};
+const exampleMismatches = (body) => {
+    const properties = body?.schema.properties;
+    if (!properties) {
+        return [];
+    }
+    const found = [];
+    for (const [name, schema] of Object.entries(properties)) {
+        const mismatch = markExampleMismatch(schema, name);
+        if (mismatch) {
+            found.push(mismatch);
+        }
+    }
+    return found;
+};
 const asString = (value) => typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
 const responseSummary = (responses) => {
     if (!isRecord(responses)) {
@@ -60,6 +105,21 @@ const buildParams = (raw, components) => {
     }
     return params;
 };
+const bodyExample = (media) => {
+    if (media['example'] !== undefined) {
+        return media['example'];
+    }
+    const examples = media['examples'];
+    if (!isRecord(examples)) {
+        return undefined;
+    }
+    for (const entry of Object.values(examples)) {
+        if (isRecord(entry) && entry['value'] !== undefined) {
+            return entry['value'];
+        }
+    }
+    return undefined;
+};
 const buildBody = (raw, components) => {
     if (!isRecord(raw)) {
         return undefined;
@@ -76,9 +136,18 @@ const buildBody = (raw, components) => {
     if (!isRecord(media)) {
         return undefined;
     }
+    const schema = capSchema(normalizeSchema(media['schema'], components));
+    const example = bodyExample(media);
+    if (example !== undefined && schema.example === undefined) {
+        schema.example = example;
+    }
+    const description = asString(raw['description']);
+    if (description && schema['x-unresolved'] === true) {
+        schema.description = description.replace(/\s+/g, ' ').slice(0, 240);
+    }
     return {
         contentType,
-        schema: capSchema(normalizeSchema(media['schema'], components)),
+        schema,
         required: raw['required'] === true,
     };
 };
@@ -96,6 +165,8 @@ export const buildCatalog = (params) => {
     const operations = [];
     const foreignPaths = [];
     const withoutOpId = [];
+    const unresolvedBodies = [];
+    const contradictoryExamples = [];
     for (const [fullPath, pathItem] of Object.entries(swagger['paths'])) {
         if (!isRecord(pathItem)) {
             continue;
@@ -118,9 +189,18 @@ export const buildCatalog = (params) => {
             const tags = operation['tags'];
             const tag = (Array.isArray(tags) ? asString(tags[0]) : undefined) ?? 'Other';
             const summary = asString(operation['summary']) ?? asString(operation['description']) ?? '';
-            const risk = riskOf(method);
-            const alwaysConfirm = method !== 'get' && ALWAYS_CONFIRM.some((pattern) => pattern.test(path));
+            const risk = riskOf(method, opId, path);
+            const alwaysConfirm = method !== 'get' && isGated(path);
             const permission = byOpId[opId];
+            const body = buildBody(operation['requestBody'], components);
+            if (body?.schema['x-unresolved'] === true) {
+                unresolvedBodies.push(body.schema.example === undefined ? `${opId} (no example)` : opId);
+            }
+            const mismatches = exampleMismatches(body);
+            if (mismatches.length > 0) {
+                contradictoryExamples.push(`${opId}: ${mismatches.join('; ')}`);
+            }
+            const notes = OPERATION_NOTES[opId];
             const entry = {
                 opId,
                 method,
@@ -132,12 +212,14 @@ export const buildCatalog = (params) => {
                 risk,
                 alwaysConfirm,
                 params: buildParams(operation['parameters'], components),
-                ...(buildBody(operation['requestBody'], components)
-                    ? { body: buildBody(operation['requestBody'], components) }
-                    : {}),
+                ...(body ? { body } : {}),
                 ...(responseSummary(operation['responses'])
                     ? { responseSummary: responseSummary(operation['responses']) }
                     : {}),
+                ...(notes?.note ? { note: notes.note } : {}),
+                ...(notes?.example !== undefined ? { curatedExample: notes.example } : {}),
+                ...(notes?.verifyWith ? { verifyWith: notes.verifyWith } : {}),
+                ...(notes?.silentNoOp ? { silentNoOp: notes.silentNoOp } : {}),
                 searchText: '',
             };
             entry.searchText = [opId, method.toUpperCase(), path, tag, summary, permission ?? '']
@@ -156,6 +238,26 @@ export const buildCatalog = (params) => {
         warnings.push(`${String(withoutOpId.length)} operation(s) have no operationId and cannot be called ` +
             `(e.g. ${withoutOpId.slice(0, 3).join(', ')}). Report it against the CMS.`);
     }
+    if (unresolvedBodies.length > 0) {
+        warnings.push(`${String(unresolvedBodies.length)} operation(s) declare a request body whose schema ` +
+            `does not resolve in the document (${unresolvedBodies.slice(0, 5).join(', ')}). ` +
+            'Their body schema is marked "x-unresolved": true — build the body from the example ' +
+            'cms_api_describe returns, and never from the empty schema. Report it against the CMS.');
+    }
+    if (contradictoryExamples.length > 0) {
+        warnings.push(`${String(contradictoryExamples.length)} field(s) carry an example that contradicts their ` +
+            `own declared type (${contradictoryExamples.slice(0, 3).join(' | ')}). ` +
+            'Those fields are marked "x-example-mismatch" and listed by cms_api_describe — ' +
+            'copy the example, not the type. 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) {
+        warnings.push(`${String(notedButAbsent.length)} operation(s) carry a curated behaviour note but are ` +
+            `absent from this catalog (${notedButAbsent.slice(0, 5).join(', ')}). ` +
+            'Either this instance does not expose them, or the note table has gone stale — ' +
+            'the note is not shown for an operation that is not there.');
+    }
     const known = new Set(operations.map((o) => o.opId));
     const missing = Object.keys(byOpId).filter((opId) => !known.has(opId) && !opId.startsWith('Developer') && !opId.startsWith('Content'));
     if (missing.length > 0) {
@@ -173,6 +275,8 @@ export const buildCatalog = (params) => {
                 : 'The bundled permission map was generated from a different platform revision than ' +
                     'this instance runs — update the package if the catalog looks incomplete.'));
     }
+    const mappedPermissions = new Set(Object.values(byOpId));
+    const permissionsWithoutOperation = permissions.filter((permission) => !mappedPermissions.has(permission));
     const knownPermissions = new Set(permissions);
     const orphanPermissions = [
         ...new Set(operations
@@ -191,6 +295,7 @@ export const buildCatalog = (params) => {
         swaggerHash: createHash('sha256').update(rawSwagger).digest('hex').slice(0, 16),
         permissions,
         warnings,
+        coverage: { unexposedOpIds: missing, permissionsWithoutOperation },
         operations,
     };
 };

package/dist/api/catalog.d.ts

@@ -26,6 +26,7 @@ export declare class OperationCatalog {
     get(opId: string): Operation | undefined;
     operations(): readonly Operation[];
     suggest(opId: string, limit?: number): string[];
+    unexposedMatches(query: string, limit?: number): string[];
     search(params: {
         query: string;
         tag?: string;

package/dist/api/catalog.js

@@ -28,7 +28,11 @@ export class OperationCatalog {
         if (catalog.version !== 1) {
             throw new Error(`Unsupported catalog version ${String(catalog.version)}`);
         }
-        this.catalog = { ...catalog, warnings: catalog.warnings ?? [] };
+        this.catalog = {
+            ...catalog,
+            warnings: catalog.warnings ?? [],
+            coverage: catalog.coverage ?? { unexposedOpIds: [], permissionsWithoutOperation: [] },
+        };
         this.byOpId = new Map(catalog.operations.map((o) => [o.opId, o]));
     }
     static permissionMap() {
@@ -70,6 +74,7 @@ export class OperationCatalog {
                         'answers 200 with an OpenAPI document.',
                     ...(auth.error === undefined ? [] : [loginWarning(auth.error)]),
                 ],
+                coverage: { unexposedOpIds: [], permissionsWithoutOperation: [] },
                 operations: [],
             });
         }
@@ -96,6 +101,22 @@ export class OperationCatalog {
             .slice(0, limit)
             .map((entry) => entry.opId);
     }
+    unexposedMatches(query, limit = 5) {
+        const terms = query
+            .toLowerCase()
+            .split(/[\s/.]+/)
+            .filter((term) => term.length > 2);
+        if (terms.length === 0) {
+            return [];
+        }
+        const { unexposedOpIds, permissionsWithoutOperation } = this.catalog.coverage;
+        return [...unexposedOpIds, ...permissionsWithoutOperation]
+            .filter((name) => {
+            const haystack = name.toLowerCase();
+            return terms.some((term) => haystack.includes(term));
+        })
+            .slice(0, limit);
+    }
     search(params) {
         const terms = params.query
             .toLowerCase()

package/dist/api/client.d.ts

@@ -21,6 +21,7 @@ export type CallResult = {
 export declare class RequestBuildError extends Error {
 }
 export declare const normalizeBody: (body: unknown) => unknown;
+export declare const unsupportedBodyFormat: (operation: Operation) => string | undefined;
 export declare const buildUrl: (baseUrl: string, operation: Operation, args: CallArgs) => string;
 export declare class AdminApiClient {
     private readonly baseUrl;
@@ -32,5 +33,11 @@ export declare class AdminApiClient {
         timeoutMs: number;
     });
     call(operation: Operation, args: CallArgs): Promise<CallResult>;
+    upload(operation: Operation, args: CallArgs, payload: {
+        bytes: Uint8Array;
+        filename: string;
+        contentType: string;
+    }): Promise<CallResult>;
+    private send;
     fetchPermissions(adminId: number): Promise<string[]>;
 }

package/dist/api/client.js

@@ -16,6 +16,21 @@ export const normalizeBody = (body) => {
         return body;
     }
 };
+export const unsupportedBodyFormat = (operation) => {
+    const contentType = operation.body?.contentType;
+    if (contentType === undefined || /^application\/(\w[\w.+-]*\+)?json$/.test(contentType)) {
+        return undefined;
+    }
+    const base = `Operation ${operation.opId} expects a "${contentType}" request body, and cms_api_call ` +
+        'can only send application/json. The call is not executable through cms_api_call — no ' +
+        'body shape will help.';
+    if (contentType === 'multipart/form-data') {
+        return (`${base} Upload through cms_upload_file (a file on the machine running this server) or ` +
+            'cms_import_file_from_url (this server fetches it). Both keep the allow level, the ' +
+            'confirm gate and the audit line.');
+    }
+    return `${base} Report it to the human and use another route to that instance.`;
+};
 export const buildUrl = (baseUrl, operation, args) => {
     let path = operation.path;
     const provided = args.path ?? {};
@@ -48,6 +63,10 @@ const hintFor = (status, operation) => {
     if (status === 400 || status === 422) {
         const loose = operation.body?.schema['x-loose'] === true;
         return (`Validation rejected the payload. ${loose ? 'This body has loosely typed fields — copy the shape from the example in cms_api_describe. ' : ''}` +
+            (operation.curatedExample !== undefined
+                ? 'A body shape verified on a live instance is in cms_api_describe under "curatedBody" — ' +
+                    'compare yours with it before changing anything else. '
+                : '') +
             'Search the knowledge base with cms_docs_search before retrying.');
     }
     if (status === 403) {
@@ -75,6 +94,12 @@ 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 extractMessage = (body, fallback) => {
     if (typeof body === 'string') {
         return body.slice(0, 500);
@@ -101,7 +126,7 @@ export class AdminApiClient {
     }
     async call(operation, args) {
         const url = buildUrl(this.baseUrl, operation, args);
-        const send = async (token) => {
+        return this.send(operation, url, (token) => {
             const headers = { authorization: `Bearer ${token}` };
             let payload;
             if (args.body !== undefined && operation.method !== 'get') {
@@ -114,12 +139,46 @@ export class AdminApiClient {
                 ...(payload !== undefined ? { body: payload } : {}),
                 signal: AbortSignal.timeout(this.timeoutMs),
             });
-        };
+        });
+    }
+    async upload(operation, args, payload) {
+        const url = buildUrl(this.baseUrl, operation, args);
+        return this.send(operation, url, (token) => {
+            const form = new FormData();
+            form.append('file', new Blob([payload.bytes], { type: payload.contentType }), payload.filename);
+            return fetch(url, {
+                method: operation.method.toUpperCase(),
+                headers: { authorization: `Bearer ${token}` },
+                body: form,
+                signal: AbortSignal.timeout(this.timeoutMs),
+            });
+        });
+    }
+    async send(operation, url, attempt) {
         let response;
+        let body;
         try {
-            response = await send(await this.tokens.accessToken());
+            response = await attempt(await this.tokens.accessToken());
             if (response.status === 401) {
-                response = await send(await this.tokens.refresh());
+                response = await attempt(await this.tokens.refresh());
+            }
+            body = await readBody(response);
+            if (response.ok && isLoginPage(response, body)) {
+                response = await attempt(await this.tokens.refresh());
+                body = await readBody(response);
+                if (response.ok && isLoginPage(response, 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.',
+                            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.',
+                        },
+                    };
+                }
             }
         }
         catch (error) {
@@ -132,7 +191,6 @@ export class AdminApiClient {
                 },
             };
         }
-        const body = await readBody(response);
         if (!response.ok) {
             const hint = hintFor(response.status, operation);
             return {

package/dist/api/normalize-schema.js

@@ -36,7 +36,12 @@ export const normalizeSchema = (node, components, depth = 0, refStack = []) => {
         }
         const target = components[name];
         if (target === undefined) {
-            return { type: 'object', description: `(unresolved ${name})` };
+            return {
+                type: 'object',
+                description: `(unresolved ${name})`,
+                'x-loose': true,
+                'x-unresolved': true,
+            };
         }
         return normalizeSchema(target, components, depth, [...refStack, name]);
     }

package/dist/api/operation-notes.d.ts

@@ -0,0 +1,11 @@
+import type { VerifyWith } from './types.js';
+export interface OperationNote {
+    note?: string;
+    example?: unknown;
+    verifyWith?: VerifyWith;
+    silentNoOp?: string;
+    readOnly?: true;
+}
+export declare const ALWAYS_CONFIRM_PREFIXES: readonly string[];
+export declare const OPERATION_NOTES: Readonly<Record<string, OperationNote>>;
+export declare const readOnlyOpIds: () => string[];