@oneentry/mcp-platform-server 0.1.5 → 0.1.7

package/dist/api/upload.js

@@ -0,0 +1,189 @@
+import { lookup } from 'node:dns/promises';
+import { readFile, realpath, stat } from 'node:fs/promises';
+import { basename, extname, isAbsolute, relative, resolve } from 'node:path';
+export class UploadSourceError extends Error {
+}
+const CONTENT_TYPES = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.svg': 'image/svg+xml',
+    '.avif': 'image/avif',
+    '.ico': 'image/x-icon',
+    '.pdf': 'application/pdf',
+    '.mp4': 'video/mp4',
+    '.webm': 'video/webm',
+    '.mov': 'video/quicktime',
+    '.mp3': 'audio/mpeg',
+    '.zip': 'application/zip',
+    '.csv': 'text/csv',
+    '.json': 'application/json',
+    '.txt': 'text/plain',
+};
+export const contentTypeOf = (filename) => CONTENT_TYPES[extname(filename).toLowerCase()] ?? 'application/octet-stream';
+export const resolveUploadOperation = (catalog) => catalog
+    .operations()
+    .find((operation) => operation.method === 'post' && operation.body?.contentType === 'multipart/form-data');
+const asMegabytes = (bytes) => `${(bytes / 1_048_576).toFixed(1)} MB`;
+export const readLocalUpload = async (params) => {
+    const { path, root, maxBytes } = params;
+    const requested = isAbsolute(path) ? path : resolve(root, path);
+    let realRoot;
+    try {
+        realRoot = await realpath(root);
+    }
+    catch {
+        throw new UploadSourceError(`The upload root "${root}" does not exist. Point --upload-root at a directory that holds ` +
+            'the files to upload.');
+    }
+    let real;
+    try {
+        real = await realpath(requested);
+    }
+    catch {
+        throw new UploadSourceError(`No file at "${requested}". Paths are resolved against the upload root "${realRoot}".`);
+    }
+    const inside = relative(realRoot, real);
+    if (inside === '' || inside.startsWith('..') || isAbsolute(inside)) {
+        throw new UploadSourceError(`"${requested}" resolves to "${real}", which is outside the upload root "${realRoot}". ` +
+            'Only files under that root can be uploaded — move the file there or start the server ' +
+            'with a different --upload-root.');
+    }
+    const info = await stat(real);
+    if (!info.isFile()) {
+        throw new UploadSourceError(`"${real}" is not a regular file. Upload one file per call.`);
+    }
+    if (info.size === 0) {
+        throw new UploadSourceError(`"${real}" is empty. An empty upload consumes quota and stores nothing useful.`);
+    }
+    if (info.size > maxBytes) {
+        throw new UploadSourceError(`"${real}" is ${asMegabytes(info.size)}, over the ${asMegabytes(maxBytes)} upload limit. ` +
+            'Raise --upload-max-bytes deliberately or upload a smaller file.');
+    }
+    const filename = basename(real);
+    return { bytes: await readFile(real), filename, contentType: contentTypeOf(filename) };
+};
+const isPrivateAddress = (address, family) => {
+    if (family === 6) {
+        const normalized = address.toLowerCase().split('%')[0] ?? '';
+        if (normalized === '::1' || normalized === '::') {
+            return true;
+        }
+        if (/^f[cd]/.test(normalized) || normalized.startsWith('fe8') || normalized.startsWith('fe9') ||
+            normalized.startsWith('fea') || normalized.startsWith('feb')) {
+            return true;
+        }
+        const dotted = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/.exec(normalized);
+        if (dotted?.[1] !== undefined) {
+            return isPrivateAddress(dotted[1], 4);
+        }
+        const hex = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(normalized);
+        if (hex?.[1] !== undefined && hex[2] !== undefined) {
+            const high = Number.parseInt(hex[1], 16);
+            const low = Number.parseInt(hex[2], 16);
+            const octets = [high >> 8, high & 0xff, low >> 8, low & 0xff];
+            return isPrivateAddress(octets.join('.'), 4);
+        }
+        return false;
+    }
+    const parts = address.split('.').map(Number);
+    if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part))) {
+        return true;
+    }
+    const [a = 0, b = 0] = parts;
+    return (a === 0 ||
+        a === 10 ||
+        a === 127 ||
+        (a === 100 && b >= 64 && b <= 127) ||
+        (a === 169 && b === 254) ||
+        (a === 172 && b >= 16 && b <= 31) ||
+        (a === 192 && b === 168) ||
+        (a === 198 && (b === 18 || b === 19)) ||
+        a >= 224);
+};
+const assertPublicUrl = async (raw, allowedHosts) => {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new UploadSourceError(`"${raw}" is not a URL. Pass an absolute http or https address.`);
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+        throw new UploadSourceError(`The scheme "${url.protocol}" is not supported. Only http and https addresses are fetched.`);
+    }
+    const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, '');
+    if (allowedHosts.length > 0 && !allowedHosts.includes(host)) {
+        throw new UploadSourceError(`The host "${host}" is not in the upload allowlist (${allowedHosts.join(', ')}). ` +
+            'Ask the operator to add it with --upload-allowed-hosts.');
+    }
+    const resolved = await lookup(host, { all: true, verbatim: true }).catch(() => {
+        throw new UploadSourceError(`The host "${host}" does not resolve. Check the address.`);
+    });
+    const blocked = resolved.filter((entry) => isPrivateAddress(entry.address, entry.family));
+    if (blocked.length > 0) {
+        throw new UploadSourceError(`The host "${host}" resolves to a private or loopback address (${blocked[0]?.address ?? ''}). ` +
+            'This server does not fetch from the network it runs in — download the file and use ' +
+            'cms_upload_file instead.');
+    }
+    return url;
+};
+const filenameFromUrl = (url, override) => {
+    const fromOverride = override?.trim();
+    if (fromOverride) {
+        return basename(fromOverride);
+    }
+    const last = basename(decodeURIComponent(url.pathname));
+    return last === '' || last === '/' ? 'upload' : last;
+};
+const MAX_REDIRECTS = 3;
+export const fetchRemoteUpload = async (params) => {
+    const { allowedHosts, maxBytes, timeoutMs } = params;
+    let target = await assertPublicUrl(params.url, allowedHosts);
+    for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+        let response;
+        try {
+            response = await fetch(target, {
+                redirect: 'manual',
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+        }
+        catch (error) {
+            throw new UploadSourceError(`Fetching ${target.toString()} failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (response.status >= 300 && response.status < 400) {
+            const location = response.headers.get('location');
+            if (!location) {
+                throw new UploadSourceError(`${target.toString()} answered ${String(response.status)} with no location header.`);
+            }
+            if (hop === MAX_REDIRECTS) {
+                throw new UploadSourceError(`${params.url} redirects more than ${String(MAX_REDIRECTS)} times. Pass the final address.`);
+            }
+            target = await assertPublicUrl(new URL(location, target).toString(), allowedHosts);
+            continue;
+        }
+        if (!response.ok) {
+            throw new UploadSourceError(`${target.toString()} answered ${String(response.status)}. Nothing was uploaded.`);
+        }
+        const declared = Number(response.headers.get('content-length') ?? '');
+        if (Number.isFinite(declared) && declared > maxBytes) {
+            throw new UploadSourceError(`${target.toString()} declares ${asMegabytes(declared)}, over the ${asMegabytes(maxBytes)} ` +
+                'upload limit. Nothing was downloaded.');
+        }
+        const bytes = new Uint8Array(await response.arrayBuffer());
+        if (bytes.byteLength === 0) {
+            throw new UploadSourceError(`${target.toString()} returned an empty body.`);
+        }
+        if (bytes.byteLength > maxBytes) {
+            throw new UploadSourceError(`${target.toString()} returned ${asMegabytes(bytes.byteLength)}, over the ` +
+                `${asMegabytes(maxBytes)} upload limit.`);
+        }
+        const filename = filenameFromUrl(target, params.filename);
+        const headerType = (response.headers.get('content-type') ?? '').split(';')[0]?.trim();
+        const contentType = headerType && headerType !== 'application/octet-stream' ? headerType : contentTypeOf(filename);
+        return { bytes, filename, contentType };
+    }
+    throw new UploadSourceError(`${params.url} could not be fetched within ${String(MAX_REDIRECTS)} redirects.`);
+};

package/dist/bin/cli.js

@@ -19,6 +19,11 @@ Options
   --request-timeout <ms>  per-request timeout, default 30000
   --max-response-bytes <n> response cap handed to the model, default 24576
 
+File uploads (cms_upload_file, cms_import_file_from_url)
+  --upload-root <dir>     directory cms_upload_file may read from, default the working directory
+  --upload-max-bytes <n>  size limit of one upload, default 26214400
+  --upload-allowed-hosts a,b  hosts cms_import_file_from_url may fetch from; required in remote mode
+
 Knowledge (documentation is fetched from GitHub, not bundled)
   --knowledge-repo <o/n>  knowledge repository, default ONEENTRY-PLATFORM/oneentry-platform-rules
   --knowledge-ref <ref>   branch, tag or commit, default main
@@ -31,7 +36,8 @@ Environment
   ONEENTRY_CMS_LOGIN, ONEENTRY_CMS_PASSWORD, ONEENTRY_CMS_TOKEN, ONEENTRY_CMS_BASE_URL, ONEENTRY_MCP_ALLOW,
   ONEENTRY_MCP_AUDIT_PATH, ONEENTRY_MCP_PORT, ONEENTRY_MCP_HOST, ONEENTRY_MCP_CACHE_DIR,
   ONEENTRY_MCP_KNOWLEDGE_REPO, ONEENTRY_MCP_KNOWLEDGE_REF, ONEENTRY_MCP_KNOWLEDGE_PATH,
-  ONEENTRY_MCP_KNOWLEDGE_TTL_MS, ONEENTRY_MCP_OFFLINE, ONEENTRY_GITHUB_TOKEN
+  ONEENTRY_MCP_KNOWLEDGE_TTL_MS, ONEENTRY_MCP_OFFLINE, ONEENTRY_GITHUB_TOKEN,
+  ONEENTRY_MCP_UPLOAD_ROOT, ONEENTRY_MCP_UPLOAD_MAX_BYTES, ONEENTRY_MCP_UPLOAD_ALLOWED_HOSTS
 `;
 const main = async () => {
     const argv = process.argv.slice(2);

package/dist/config/config.d.ts

@@ -26,6 +26,20 @@ export declare const KnowledgeConfigSchema: z.ZodObject<{
     token?: string | undefined;
 }>;
 export type KnowledgeSettings = z.infer<typeof KnowledgeConfigSchema>;
+export declare const UploadConfigSchema: z.ZodObject<{
+    root: z.ZodString;
+    maxBytes: z.ZodNumber;
+    allowedHosts: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    root: string;
+    maxBytes: number;
+    allowedHosts: string[];
+}, {
+    root: string;
+    maxBytes: number;
+    allowedHosts: string[];
+}>;
+export type UploadSettings = z.infer<typeof UploadConfigSchema>;
 export declare const ConfigSchema: z.ZodObject<{
     mode: z.ZodEnum<["local", "remote"]>;
     baseUrl: z.ZodString;
@@ -59,6 +73,19 @@ export declare const ConfigSchema: z.ZodObject<{
     auditPath: z.ZodOptional<z.ZodString>;
     requestTimeoutMs: z.ZodNumber;
     maxResponseBytes: z.ZodNumber;
+    upload: z.ZodObject<{
+        root: z.ZodString;
+        maxBytes: z.ZodNumber;
+        allowedHosts: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        root: string;
+        maxBytes: number;
+        allowedHosts: string[];
+    }, {
+        root: string;
+        maxBytes: number;
+        allowedHosts: string[];
+    }>;
     http: z.ZodObject<{
         port: z.ZodNumber;
         host: z.ZodString;
@@ -87,6 +114,11 @@ export declare const ConfigSchema: z.ZodObject<{
     cacheDir: string;
     requestTimeoutMs: number;
     maxResponseBytes: number;
+    upload: {
+        root: string;
+        maxBytes: number;
+        allowedHosts: string[];
+    };
     http: {
         port: number;
         host: string;
@@ -111,6 +143,11 @@ export declare const ConfigSchema: z.ZodObject<{
     cacheDir: string;
     requestTimeoutMs: number;
     maxResponseBytes: number;
+    upload: {
+        root: string;
+        maxBytes: number;
+        allowedHosts: string[];
+    };
     http: {
         port: number;
         host: string;

package/dist/config/config.js

@@ -12,6 +12,11 @@ export const KnowledgeConfigSchema = z.object({
     offline: z.boolean(),
     token: z.string().min(1).optional(),
 });
+export const UploadConfigSchema = z.object({
+    root: z.string().min(1),
+    maxBytes: z.number().int().positive(),
+    allowedHosts: z.array(z.string()),
+});
 export const ConfigSchema = z.object({
     mode: ServerModeSchema,
     baseUrl: z.string().url(),
@@ -24,6 +29,7 @@ export const ConfigSchema = z.object({
     auditPath: z.string().optional(),
     requestTimeoutMs: z.number().int().positive(),
     maxResponseBytes: z.number().int().positive(),
+    upload: UploadConfigSchema,
     http: z.object({
         port: z.number().int().min(1).max(65535),
         host: z.string().min(1),
@@ -40,6 +46,7 @@ const DEFAULTS = {
     knowledgeRepo: 'ONEENTRY-PLATFORM/oneentry-platform-rules',
     knowledgeRef: 'main',
     knowledgeTtlMs: 3_600_000,
+    uploadMaxBytes: 26_214_400,
 };
 export const parseFlags = (argv) => {
     const flags = {};
@@ -132,6 +139,7 @@ export const loadConfig = (argv, env = process.env, cwd = process.cwd()) => {
     const pickKnowledge = (flagKey, envKey, fileKey) => asString(flags[flagKey]) ?? asString(env[envKey]) ?? knowledgeFile(fileKey);
     const mode = flags['http'] === true || asString(flags['http']) ? 'remote' : 'local';
     const originsRaw = pick('allowed-origins', 'ONEENTRY_MCP_ALLOWED_ORIGINS', 'allowedOrigins');
+    const uploadHostsRaw = pick('upload-allowed-hosts', 'ONEENTRY_MCP_UPLOAD_ALLOWED_HOSTS', 'uploadAllowedHosts');
     const candidate = {
         mode,
         baseUrl: normalizeBaseUrl(pick('base-url', 'ONEENTRY_CMS_BASE_URL', 'baseUrl') ?? DEFAULTS.baseUrl),
@@ -153,6 +161,13 @@ export const loadConfig = (argv, env = process.env, cwd = process.cwd()) => {
         auditPath: pick('audit', 'ONEENTRY_MCP_AUDIT_PATH', 'auditPath'),
         requestTimeoutMs: asNumber(pick('request-timeout', 'ONEENTRY_MCP_REQUEST_TIMEOUT_MS', 'requestTimeoutMs'), DEFAULTS.requestTimeoutMs),
         maxResponseBytes: asNumber(pick('max-response-bytes', 'ONEENTRY_MCP_MAX_RESPONSE_BYTES', 'maxResponseBytes'), DEFAULTS.maxResponseBytes),
+        upload: {
+            root: pick('upload-root', 'ONEENTRY_MCP_UPLOAD_ROOT', 'uploadRoot') ?? cwd,
+            maxBytes: asNumber(pick('upload-max-bytes', 'ONEENTRY_MCP_UPLOAD_MAX_BYTES', 'uploadMaxBytes'), DEFAULTS.uploadMaxBytes),
+            allowedHosts: uploadHostsRaw
+                ? uploadHostsRaw.split(',').map((host) => host.trim().toLowerCase()).filter(Boolean)
+                : [],
+        },
         http: {
             port: asNumber(pick('port', 'ONEENTRY_MCP_PORT', 'port'), DEFAULTS.httpPort),
             host: pick('host', 'ONEENTRY_MCP_HOST', 'host') ?? DEFAULTS.httpHost,

package/dist/server.js

@@ -9,6 +9,7 @@ import { registerApiCall } from './tools/api-call.js';
 import { registerApiDiscovery } from './tools/api-discovery.js';
 import { registerDocs } from './tools/docs.js';
 import { registerGuide } from './tools/guide.js';
+import { registerUpload } from './tools/upload.js';
 import { registerWhoami } from './tools/whoami.js';
 const SERVER_VERSION = (() => {
     try {
@@ -58,6 +59,7 @@ export const createServer = (deps, getSession) => {
     const server = new McpServer({ name: 'oneentry-mcp-platform', version: SERVER_VERSION }, {
         instructions: 'OneEntry CMS Admin API. Call cms_guide first, then cms_docs_read on "mcp/operating-rules" before any write. ' +
             'Discover endpoints with cms_api_search, get payload shapes with cms_api_describe, execute with cms_api_call. ' +
+            'Files are the exception: cms_api_call cannot send multipart, so upload with cms_upload_file or cms_import_file_from_url. ' +
             'Never construct paths or operation ids by hand.',
     });
     registerGuide(server, deps);
@@ -65,5 +67,6 @@ export const createServer = (deps, getSession) => {
     registerDocs(server, deps);
     registerApiDiscovery(server, deps);
     registerApiCall(server, getSession);
+    registerUpload(server, getSession);
     return server;
 };

package/dist/tools/api-discovery.js

@@ -92,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: 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.',
+        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 a body shape has been verified on a live instance it is returned as "curatedBody", which wins over the document\'s own example wherever the two disagree. 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".'),
         },
@@ -147,6 +147,14 @@ export const registerApiDiscovery = (server, deps) => {
                         'the contract — the instance accepts what the example shows.',
                 }
                 : {}),
+            ...(operation.curatedExample !== undefined
+                ? {
+                    curatedBody: operation.curatedExample,
+                    curatedBodySource: 'Verified on a live instance. Where this disagrees with "example" or with the ' +
+                        'body schema above, this is the shape the instance and the admin panel read — ' +
+                        'copy it and read "note" for what each part of it prevents.',
+                }
+                : {}),
             ...(operation.note ? { note: operation.note } : {}),
             ...(operation.silentNoOp ? { silentNoOp: operation.silentNoOp } : {}),
             ...(operation.verifyWith ? { verifyWith: operation.verifyWith } : {}),
@@ -160,7 +168,9 @@ export const registerApiDiscovery = (server, deps) => {
             ...(formatDenial ? { notExecutable: formatDenial } : {}),
             responseSummary: operation.responseSummary ?? null,
             next: formatDenial
-                ? 'Do not call this operation — report it as unavailable through MCP.'
+                ? 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.'
                 : operation.risk === 'read'
                     ? 'Call it with cms_api_call, copying the "example" above.'
                     : operation.verifyWith

package/dist/tools/guide.js

@@ -40,7 +40,10 @@ export const renderGuide = (deps) => {
         '2. `cms_docs_search` — find the reference doc for the entity you are touching;',
         '   `mcp/docs/server/doc-map` lists every document with a one-line "read this when".',
         '3. `cms_api_search` → `cms_api_describe` — get the real operation and its payload shape.',
-        '4. `cms_api_call` — `dryRun: true` first for anything that mutates.',
+        '   Where `cms_api_describe` returns `curatedBody`, that shape was verified on a live instance',
+        '   and wins over the document\'s own example.',
+        '4. `cms_api_call` — `dryRun: true` first for anything that mutates. Files go through',
+        '   `cms_upload_file` or `cms_import_file_from_url` instead.',
         '',
         'Never invent a path: `cms_api_search` is the only authority on what exists.',
         '',
@@ -53,11 +56,12 @@ export const renderGuide = (deps) => {
         '- Admin API only. The Content and Developer APIs are deliberately not exposed.',
         `- 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.',
+        '- **`cms_api_call` sends JSON only.** The file upload endpoint wants `multipart/form-data`,',
+        '  so it has two tools of its own: `cms_upload_file` for a file on the machine running this',
+        '  server, `cms_import_file_from_url` for one this server downloads. Both need',
+        '  `--allow=write`, both are audited, both support `dryRun`, and both refuse a source outside',
+        '  the operator\'s bounds. Pass `template` — the numeric id of a `/template-previews` record —',
+        '  or the file is stored with no preview and nothing reports it.',
         '- **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',

package/dist/tools/upload.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { Session } from '../session.js';
+export declare const registerUpload: (server: McpServer, getSession: () => Session) => void;

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 } : {}),
+            }),
+        });
+    });
+};