@panelwave/mcp 0.0.0-stage → 0.1.0

package/dist/upload.js

@@ -0,0 +1,582 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uploadFiles = exports.MAX_ATTEMPTS = exports.MAX_FILES = exports.UPLOADABLE_KINDS = void 0;
+exports.sha256File = sha256File;
+exports.remoteData = remoteData;
+exports.assertUploadTarget = assertUploadTarget;
+exports.safeUploadHeaders = safeUploadHeaders;
+exports.uploadBatch = uploadBatch;
+exports.ensureFolder = ensureFolder;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const fs = __importStar(require("node:fs/promises"));
+const path = __importStar(require("node:path"));
+const zod_1 = require("zod");
+const errors_1 = require("./errors");
+const files_1 = require("./files");
+const sandbox_1 = require("./sandbox");
+const tool_1 = require("./tool");
+/** Kinds the asset library accepts. */
+exports.UPLOADABLE_KINDS = new Set(['image', 'video', 'audio', 'font']);
+exports.MAX_FILES = 500;
+exports.MAX_ATTEMPTS = 3;
+async function sha256File(file, signal) {
+    const hash = (0, node_crypto_1.createHash)('sha256');
+    const stream = (0, node_fs_1.createReadStream)(file, { highWaterMark: 1024 * 1024, signal });
+    for await (const chunk of stream)
+        hash.update(chunk);
+    return hash.digest('hex');
+}
+async function readRange(file, offset, length) {
+    const handle = await fs.open(file, 'r');
+    try {
+        const buf = Buffer.alloc(length);
+        let read = 0;
+        while (read < length) {
+            const { bytesRead } = await handle.read(buf, read, length - read, offset + read);
+            if (!bytesRead)
+                break;
+            read += bytesRead;
+        }
+        if (read !== length)
+            throw new errors_1.BridgeError('PRECONDITION_FAILED', `${path.basename(file)} changed while uploading (expected ${length} bytes at offset ${offset}, read ${read}).`);
+        return buf;
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Call a hosted tool and return its structured result; an isError result is re-raised with the remote code. */
+async function remoteData(call, name, args, signal) {
+    let res;
+    try {
+        res = await call(name, args, signal);
+    }
+    catch (e) {
+        const err = e;
+        // the gateway only lists the tools the token's scopes allow — an unknown tool means a missing scope
+        if (typeof err?.code === 'number' && /not found/i.test(err.message ?? '')) {
+            throw new errors_1.BridgeError('PERMISSION_DENIED', `${name} is not available on this connection — the access token probably lacks the scope (uploads need assets:write, folder lookups assets:read). Create a token with those scopes.`);
+        }
+        throw (0, errors_1.toBridgeError)(e);
+    }
+    const body = (res.structuredContent ?? {});
+    if (res.isError) {
+        const code = (0, errors_1.isBridgeErrorCode)(body.code) ? body.code : 'INTERNAL';
+        const text = res.content?.find((c) => c.type === 'text')?.text;
+        throw new errors_1.BridgeError(code, String(body.message ?? text ?? `${name} failed`), body.details);
+    }
+    return body;
+}
+const sleep = (ms, signal) => new Promise((resolve, reject) => {
+    if (signal?.aborted)
+        return reject(new errors_1.BridgeError('CANCELLED', 'The call was cancelled.'));
+    const t = setTimeout(resolve, ms);
+    signal?.addEventListener('abort', () => {
+        clearTimeout(t);
+        reject(new errors_1.BridgeError('CANCELLED', 'The call was cancelled.'));
+    }, { once: true });
+});
+/** Storage refusals that retrying will not fix (403 is retried with a fresh URL). */
+const RETRYABLE_STATUS = new Set([403, 408, 425, 429, 500, 502, 503, 504]);
+/**
+ * PUT one body with up to MAX_ATTEMPTS attempts. `target(attempt, lastStatus)`
+ * supplies the URL — callers re-sign after an expired/refused URL (403).
+ * Returns the ETag (may be empty) and the number of attempts used.
+ */
+async function putWithRetry(opts, label, target, body) {
+    const doFetch = opts.fetch ?? fetch;
+    let last;
+    let lastStatus;
+    for (let attempt = 1; attempt <= exports.MAX_ATTEMPTS; attempt++) {
+        if (opts.signal?.aborted)
+            throw new errors_1.BridgeError('CANCELLED', 'The call was cancelled.');
+        // signing (a hosted tool call) and reading the file are not retried here
+        const next = await target(attempt, lastStatus);
+        const url = assertUploadTarget(next.url, opts);
+        const headers = safeUploadHeaders(next.headers);
+        const bytes = await body();
+        let res;
+        try {
+            res = await doFetch(url, { method: 'PUT', headers, body: bytes, signal: opts.signal });
+        }
+        catch (e) {
+            if (opts.signal?.aborted)
+                throw new errors_1.BridgeError('CANCELLED', 'The call was cancelled.');
+            lastStatus = undefined;
+            last = new errors_1.BridgeError('UPSTREAM_UNAVAILABLE', `Uploading ${label} failed: ${e instanceof Error ? (e.cause instanceof Error ? e.cause.message : e.message) : String(e)}.`);
+        }
+        if (res?.ok) {
+            await res.arrayBuffer().catch(() => undefined);
+            return { etag: res.headers.get('etag') ?? '', attempts: attempt };
+        }
+        if (res) {
+            lastStatus = res.status;
+            const snippet = (await res.text().catch(() => '')).replace(/\s+/g, ' ').slice(0, 200);
+            last = new errors_1.BridgeError('UPSTREAM_UNAVAILABLE', `Storage refused ${label} (HTTP ${res.status}${snippet ? `: ${snippet}` : ''}).`);
+            if (!RETRYABLE_STATUS.has(res.status))
+                throw last;
+        }
+        if (attempt < exports.MAX_ATTEMPTS)
+            await sleep((opts.retryDelayMs ?? 500) * 3 ** (attempt - 1), opts.signal);
+    }
+    throw new errors_1.BridgeError('UPSTREAM_UNAVAILABLE', `${last?.message ?? `Uploading ${label} failed.`} Gave up after ${exports.MAX_ATTEMPTS} attempts — run the tool again to resume (finished files are skipped).`);
+}
+/**
+ * Upload URLs come from the hosted server. Accept only https, or plain http to a
+ * loopback host (a local MinIO in development) — never another scheme or a
+ * plain-http host on the network (security review 2026-09-30).
+ */
+function assertUploadTarget(url, opts = {}) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new errors_1.BridgeError('UPSTREAM_UNAVAILABLE', 'The server returned an invalid upload URL.');
+    }
+    const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(parsed.hostname);
+    const ok = parsed.protocol === 'https:' || (parsed.protocol === 'http:' && (loopback || opts.allowInsecureUploadHosts === true));
+    if (!ok || parsed.username || parsed.password) {
+        throw new errors_1.BridgeError('PRECONDITION_FAILED', `Refusing to upload to ${parsed.protocol}//${parsed.host}: uploads go to https storage only.`);
+    }
+    return parsed.toString();
+}
+/** Headers for the storage PUT: never credentials or hop-by-hop headers, whatever the server suggests. */
+function safeUploadHeaders(headers) {
+    const out = {};
+    for (const [k, v] of Object.entries(headers ?? {})) {
+        if (/^(authorization|proxy-authorization|cookie|host|connection|transfer-encoding|content-length)$/i.test(k))
+            continue;
+        if (typeof v === 'string')
+            out[k] = v;
+    }
+    return out;
+}
+/**
+ * Upload local files into a work's asset library through the hosted tools
+ * (pw_assets_begin_upload → PUT / multipart parts → pw_assets_complete_upload).
+ * Files run `concurrency` at a time; parts of one file run in order, each read
+ * from disk just before its PUT, so memory stays at one part per file.
+ */
+async function uploadBatch(opts) {
+    const total = opts.files.reduce((n, f) => n + f.size, 0);
+    let done = 0;
+    const advance = (bytes, message) => {
+        if (bytes <= 0)
+            return;
+        done += bytes;
+        opts.onProgress?.(done, total, message);
+    };
+    const prepared = await (0, tool_1.mapLimit)(opts.files, opts.concurrency, async (file) => {
+        const filename = path.basename(file.abs);
+        const mimeType = (0, files_1.mimeOf)(filename);
+        const kind = (0, files_1.kindOfMime)(mimeType);
+        const row = { path: file.abs, filename, ok: false, status: 'failed', deduplicated: false, mimeType, sizeBytes: file.size, warnings: [] };
+        try {
+            if (opts.signal?.aborted)
+                throw new errors_1.BridgeError('CANCELLED', 'The call was cancelled.');
+            if (!exports.UPLOADABLE_KINDS.has(kind))
+                throw new errors_1.BridgeError('INVALID_INPUT', `${filename} is not an image, video, audio or font file (${mimeType}).`);
+            if (file.size <= 0)
+                throw new errors_1.BridgeError('INVALID_INPUT', `${filename} is empty.`);
+            row.kind = kind;
+            const sha256 = await sha256File(file.abs, opts.signal);
+            row.sha256 = sha256;
+            if (kind === 'image') {
+                const dim = await (0, files_1.imageDimensions)(file.abs);
+                if (dim) {
+                    row.width = dim.width;
+                    row.height = dim.height;
+                }
+                else
+                    row.warnings.push('Image dimensions could not be read locally; the server fills them in.');
+            }
+            return { file, row, sha256 };
+        }
+        catch (e) {
+            return { file, row, error: opts.signal?.aborted ? new errors_1.BridgeError('CANCELLED', 'The call was cancelled.') : (0, errors_1.toBridgeError)(e) };
+        }
+    });
+    // The first file per content hash owns the upload; later ones reuse its asset.
+    const owners = new Map();
+    prepared.forEach((p, index) => {
+        if (!p.sha256 || owners.has(p.sha256))
+            return;
+        let settle;
+        const promise = new Promise((r) => (settle = r));
+        owners.set(p.sha256, { index, promise, settle });
+    });
+    const finish = (p, e, accounted) => {
+        const err = (0, errors_1.toBridgeError)(e);
+        p.row.ok = false;
+        p.row.status = err.code === 'CANCELLED' ? 'cancelled' : 'failed';
+        p.row.error = { code: err.code, message: err.message };
+        advance(p.file.size - accounted, `${p.row.filename}: ${p.row.status}`);
+        return p.row;
+    };
+    // Phase 2 — transfer one file: begin → PUT (single) or signed parts (multipart) → complete.
+    const transfer = async (p, account) => {
+        const { file, row } = p;
+        const sha256 = p.sha256;
+        const { filename, mimeType } = row;
+        const kind = row.kind;
+        let multipart;
+        try {
+            const begin = await remoteData(opts.callRemote, 'pw_assets_begin_upload', { workId: opts.workId, filename, mimeType, sizeBytes: file.size, sha256, kind }, opts.signal);
+            const beginWarnings = begin.warnings ?? [];
+            row.warnings.push(...beginWarnings);
+            if (begin.mode === 'exists') {
+                if (!opts.skipDuplicates)
+                    throw new errors_1.BridgeError('CONFLICT', `${filename} is already in the library (asset ${String(begin.assetId)}); skipDuplicates is false.`);
+                Object.assign(row, { ok: true, status: 'exists', assetId: String(begin.assetId), deduplicated: true });
+                account(file.size, `${filename}: already in the library`);
+                return row;
+            }
+            let s3Key = String(begin.s3Key ?? '');
+            let parts;
+            if (begin.mode === 'single') {
+                row.mode = 'single';
+                let current = { url: String(begin.uploadUrl ?? ''), headers: begin.headers ?? { 'Content-Type': mimeType } };
+                const put = await putWithRetry(opts, filename, async (attempt, lastStatus) => {
+                    if (attempt > 1 && lastStatus === 403) {
+                        // the presigned URL expired or was refused — ask for a fresh one
+                        const again = await remoteData(opts.callRemote, 'pw_assets_begin_upload', { workId: opts.workId, filename, mimeType, sizeBytes: file.size, sha256, kind }, opts.signal);
+                        if (again.mode !== 'single')
+                            throw new errors_1.BridgeError('CONFLICT', `${filename}: the server changed the upload mode to ${String(again.mode)}; run the tool again.`);
+                        s3Key = String(again.s3Key ?? '');
+                        current = { url: String(again.uploadUrl ?? ''), headers: again.headers ?? { 'Content-Type': mimeType } };
+                    }
+                    return current;
+                }, () => fs.readFile(file.abs));
+                row.attempts = put.attempts;
+                account(file.size, `${filename}: uploaded`);
+            }
+            else if (begin.mode === 'multipart') {
+                row.mode = 'multipart';
+                const uploadId = String(begin.uploadId ?? '');
+                multipart = { uploadId, s3Key };
+                const partSize = Number(begin.partSize) || 5 * 1024 * 1024;
+                const partCount = Math.ceil(file.size / partSize);
+                parts = [];
+                let attempts = 0;
+                for (let partNumber = 1; partNumber <= partCount; partNumber++) {
+                    const offset = (partNumber - 1) * partSize;
+                    const length = Math.min(partSize, file.size - offset);
+                    const put = await putWithRetry(opts, `${filename} part ${partNumber}/${partCount}`, async () => {
+                        const signed = await remoteData(opts.callRemote, 'pw_assets_sign_part', { workId: opts.workId, uploadId, s3Key, partNumber }, opts.signal);
+                        return { url: String(signed.url ?? ''), headers: {} };
+                    }, () => readRange(file.abs, offset, length));
+                    attempts = Math.max(attempts, put.attempts);
+                    parts.push({ partNumber, ...(put.etag ? { etag: put.etag } : {}) });
+                    account(length, `${filename}: part ${partNumber}/${partCount}`);
+                }
+                row.attempts = attempts;
+            }
+            else {
+                throw new errors_1.BridgeError('INTERNAL', `Unknown upload mode ${String(begin.mode)} for ${filename}.`);
+            }
+            const complete = await remoteData(opts.callRemote, 'pw_assets_complete_upload', {
+                workId: opts.workId,
+                s3Key,
+                sha256,
+                kind,
+                mimeType,
+                sizeBytes: file.size,
+                filename,
+                ...(row.width && row.height ? { width: row.width, height: row.height } : {}),
+                ...(opts.folderId ? { folderId: opts.folderId } : {}),
+                ...(opts.tags?.length ? { tags: opts.tags } : {}),
+                ...(multipart && parts ? { multipart: { uploadId: multipart.uploadId, parts } } : {}),
+            }, opts.signal);
+            multipart = undefined;
+            row.assetId = String(complete.id ?? '');
+            row.deduplicated = complete.deduplicated === true;
+            row.status = row.deduplicated ? 'exists' : 'uploaded';
+            row.processing = complete.processing === true;
+            row.ok = true;
+            // the asset's own warnings replace the provisional ones from begin (same facts, final state)
+            const finalWarnings = complete.warnings ?? [];
+            if (finalWarnings.length)
+                row.warnings = row.warnings.filter((w) => !beginWarnings.includes(w));
+            for (const w of finalWarnings)
+                if (!row.warnings.includes(w))
+                    row.warnings.push(w);
+            return row;
+        }
+        catch (e) {
+            if (multipart) {
+                // best effort: let storage discard the parts of the unfinished upload
+                await remoteData(opts.callRemote, 'pw_assets_abort_upload', { workId: opts.workId, uploadId: multipart.uploadId, s3Key: multipart.s3Key }).catch(() => undefined);
+            }
+            throw e;
+        }
+    };
+    return (0, tool_1.mapLimit)(prepared, opts.concurrency, async (p, index) => {
+        let accounted = 0;
+        const account = (bytes, message) => {
+            accounted += bytes;
+            advance(bytes, message);
+        };
+        if (p.error)
+            return finish(p, p.error, 0);
+        const owner = owners.get(p.sha256);
+        if (owner.index !== index) {
+            // same bytes as an earlier file of this batch: wait for it and reuse its asset
+            const prior = await owner.promise;
+            try {
+                if (!prior.ok || !prior.assetId)
+                    throw new errors_1.BridgeError('PRECONDITION_FAILED', `Same content as ${prior.filename}, which was not uploaded.`);
+                if (!opts.skipDuplicates)
+                    throw new errors_1.BridgeError('CONFLICT', `${p.row.filename} has the same content as ${prior.filename} in this batch (skipDuplicates is false).`);
+            }
+            catch (e) {
+                return finish(p, e, 0);
+            }
+            Object.assign(p.row, { ok: true, status: 'exists', assetId: prior.assetId, deduplicated: true });
+            p.row.warnings.push(`Same content as ${prior.filename} — reused its asset.`);
+            account(p.file.size, `${p.row.filename}: duplicate of ${prior.filename}`);
+            return p.row;
+        }
+        try {
+            if (opts.signal?.aborted)
+                throw new errors_1.BridgeError('CANCELLED', 'The call was cancelled.');
+            return await transfer(p, account);
+        }
+        catch (e) {
+            return finish(p, e, accounted);
+        }
+        finally {
+            owner.settle(p.row);
+        }
+    });
+}
+/** Resolve (and create when missing) a folder path like "Chapter 1/Panels". */
+async function ensureFolder(call, workId, folderPath, signal) {
+    const segments = folderPath
+        .split('/')
+        .map((s) => s.trim())
+        .filter(Boolean);
+    if (!segments.length)
+        throw new errors_1.BridgeError('INVALID_INPUT', 'folderName is empty.');
+    let items = [];
+    try {
+        items = (await remoteData(call, 'pw_folders_list', { workId }, signal)).items ?? [];
+    }
+    catch (e) {
+        const err = (0, errors_1.toBridgeError)(e);
+        if (err.code !== 'PERMISSION_DENIED')
+            throw err; // without assets:read, fall back to creating
+    }
+    let parentId;
+    let created = false;
+    for (let i = 0; i < segments.length; i++) {
+        const wanted = segments.slice(0, i + 1).join('/').toLowerCase();
+        const hit = items.find((f) => f.path.toLowerCase() === wanted);
+        if (hit) {
+            parentId = hit.id;
+            continue;
+        }
+        const res = await remoteData(call, 'pw_folders_manage', { action: 'create', workId, name: segments[i], ...(parentId ? { parentId } : {}) }, signal);
+        parentId = String(res.folderId ?? '');
+        if (!parentId)
+            throw new errors_1.BridgeError('INTERNAL', `Creating folder ${segments[i]} returned no id.`);
+        items = res.items ?? items;
+        created = true;
+    }
+    return { folderId: parentId, created };
+}
+// ---------------------------------------------------------------------------
+// pw_local_upload_files
+// ---------------------------------------------------------------------------
+const MEDIA_GLOB_HINT = 'images, videos, audio and fonts';
+const uploadInput = zod_1.z
+    .object({
+    workId: zod_1.z.string().min(1).describe('Work whose asset library receives the files.'),
+    folder: zod_1.z.string().optional().describe('Upload the media files of this local folder (absolute, or relative to the first allowed folder).'),
+    glob: zod_1.z.string().max(500).optional().describe(`File-name filter for folder, e.g. "*.{png,jpg}" — default: all ${MEDIA_GLOB_HINT}.`),
+    recursive: zod_1.z.boolean().default(false).describe('Include subfolders of folder.'),
+    paths: zod_1.z.array(zod_1.z.string().min(1)).max(exports.MAX_FILES).optional().describe('Explicit files to upload (instead of or in addition to folder).'),
+    folderName: zod_1.z.string().min(1).max(250).optional().describe('Asset-library folder to file the uploads into; created when missing. "A/B" = nested.'),
+    folderId: zod_1.z.string().optional().describe('Existing asset-library folder id (instead of folderName).'),
+    tags: zod_1.z.array(zod_1.z.string().min(1).max(60)).max(30).optional(),
+    skipDuplicates: zod_1.z
+        .boolean()
+        .default(true)
+        .describe('Files whose bytes are already in the library (or twice in this batch) are not uploaded again; their row reports the existing assetId. false = report them as CONFLICT instead.'),
+    concurrency: zod_1.z.number().int().min(1).max(6).default(3).describe('Files uploaded in parallel.'),
+})
+    .refine((a) => a.folder || a.paths?.length, { message: 'Pass folder or paths.', path: ['folder'] })
+    .refine((a) => !(a.folderName && a.folderId), { message: 'Pass folderName or folderId, not both.', path: ['folderId'] });
+const zRow = zod_1.z.object({
+    path: zod_1.z.string(),
+    filename: zod_1.z.string(),
+    ok: zod_1.z.boolean(),
+    status: zod_1.z.enum(['uploaded', 'exists', 'failed', 'cancelled']),
+    assetId: zod_1.z.string().optional(),
+    deduplicated: zod_1.z.boolean(),
+    kind: zod_1.z.string().optional(),
+    mimeType: zod_1.z.string(),
+    sizeBytes: zod_1.z.number().int(),
+    sha256: zod_1.z.string().optional(),
+    width: zod_1.z.number().int().optional(),
+    height: zod_1.z.number().int().optional(),
+    mode: zod_1.z.enum(['single', 'multipart']).optional(),
+    attempts: zod_1.z.number().int().optional(),
+    processing: zod_1.z.boolean().optional(),
+    warnings: zod_1.z.array(zod_1.z.string()),
+    error: zod_1.z.object({ code: zod_1.z.string(), message: zod_1.z.string() }).optional(),
+});
+const uploadOutput = zod_1.z.object({
+    workId: zod_1.z.string(),
+    folderId: zod_1.z.string().optional(),
+    folderCreated: zod_1.z.boolean().optional(),
+    files: zod_1.z.array(zRow),
+    uploaded: zod_1.z.number().int(),
+    existing: zod_1.z.number().int(),
+    failed: zod_1.z.number().int(),
+    totalBytes: zod_1.z.number().int(),
+    durationMs: zod_1.z.number().int(),
+    skipped: zod_1.z.array(zod_1.z.string()).describe('Folder entries left out (not media, unreadable or outside the allowed folders).'),
+});
+exports.uploadFiles = (0, tool_1.defineLocalTool)({
+    name: 'pw_local_upload_files',
+    title: 'Upload local files to PanelWave',
+    description: 'Upload images, videos, audio or fonts from this computer into a work’s asset library — a whole folder (optionally filtered by glob) or a list of paths. Each file is hashed (sha-256) so content already in the library is reused instead of uploaded again; image dimensions are read locally (EXIF orientation applied). Files ≥ 10 MB go up in 5 MiB parts with retries. Optionally files everything into an asset folder (folderName is created when missing). Re-running after a failure resumes: finished files are recognised and skipped. Afterwards attach artwork with pw_panels_attach_artwork (by file name).',
+    input: uploadInput,
+    output: uploadOutput,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    async run(args, ctx) {
+        if (!ctx.callRemote)
+            throw new errors_1.BridgeError('UPSTREAM_UNAVAILABLE', 'Uploading needs the connection to the PanelWave server.');
+        const started = Date.now();
+        const files = [];
+        const skipped = [];
+        const seen = new Set();
+        const add = (abs, display, size) => {
+            const key = process.platform === 'win32' ? abs.toLowerCase() : abs;
+            if (seen.has(key))
+                return;
+            seen.add(key);
+            files.push({ abs, display, size });
+        };
+        if (args.folder) {
+            const scan = await (0, files_1.scanFolder)(args.folder, ctx.allowedDirs, {
+                glob: args.glob,
+                accept: args.glob ? undefined : (name) => exports.UPLOADABLE_KINDS.has((0, files_1.kindOfMime)((0, files_1.mimeOf)(name))),
+                recursive: args.recursive,
+                limit: exports.MAX_FILES,
+                signal: ctx.signal,
+            });
+            if (scan.truncated)
+                throw new errors_1.BridgeError('INVALID_INPUT', `More than ${exports.MAX_FILES} files match in ${scan.root}; narrow the glob or upload subfolders one at a time.`);
+            skipped.push(...scan.skipped);
+            for (const f of scan.found)
+                add(f.abs, f.rel, f.size);
+        }
+        for (const p of args.paths ?? []) {
+            const abs = (0, sandbox_1.resolveAllowed)(p, ctx.allowedDirs);
+            const stat = await fs.stat(abs).catch((e) => {
+                throw new errors_1.BridgeError((0, errors_1.toBridgeError)(e).code, `${p}: ${(0, errors_1.toBridgeError)(e).message}`);
+            });
+            if (!stat.isFile())
+                throw new errors_1.BridgeError('INVALID_INPUT', `${p} is not a file.`);
+            add(abs, p, stat.size);
+        }
+        if (files.length > exports.MAX_FILES)
+            throw new errors_1.BridgeError('INVALID_INPUT', `At most ${exports.MAX_FILES} files per call.`);
+        if (!files.length)
+            throw new errors_1.BridgeError('NOT_FOUND', `No ${args.glob ? `files matching ${args.glob}` : MEDIA_GLOB_HINT} to upload.`);
+        if (!args.paths?.length)
+            files.sort((a, b) => (0, files_1.naturalCompare)(a.display, b.display));
+        let folderId = args.folderId;
+        let folderCreated;
+        if (args.folderName) {
+            const f = await ensureFolder(ctx.callRemote, args.workId, args.folderName, ctx.signal);
+            folderId = f.folderId;
+            folderCreated = f.created;
+        }
+        let lastSent = 0;
+        const rows = await uploadBatch({
+            workId: args.workId,
+            files,
+            callRemote: ctx.callRemote,
+            folderId,
+            tags: args.tags,
+            skipDuplicates: args.skipDuplicates,
+            concurrency: args.concurrency,
+            signal: ctx.signal,
+            onProgress: (doneBytes, totalBytes, message) => {
+                // throttle: every 2 % (and always the last one)
+                if (doneBytes < totalBytes && doneBytes - lastSent < totalBytes / 50)
+                    return;
+                lastSent = doneBytes;
+                void ctx.progress?.(doneBytes, totalBytes, message);
+            },
+        });
+        // existing assets were not uploaded with the folder — file them too
+        const warnings = [];
+        const reused = rows.filter((r) => r.ok && r.status === 'exists' && r.assetId).map((r) => r.assetId);
+        if (folderId && reused.length) {
+            try {
+                await remoteData(ctx.callRemote, 'pw_folders_manage', { action: 'assign', workId: args.workId, assetIds: [...new Set(reused)], folderIds: [folderId], mode: 'add' }, ctx.signal);
+            }
+            catch (e) {
+                warnings.push(`Existing assets could not be filed into the folder (${(0, errors_1.toBridgeError)(e).message}).`);
+            }
+        }
+        const uploaded = rows.filter((r) => r.status === 'uploaded').length;
+        const existing = rows.filter((r) => r.status === 'exists').length;
+        const failed = rows.filter((r) => !r.ok).length;
+        const totalBytes = files.reduce((n, f) => n + f.size, 0);
+        const durationMs = Date.now() - started;
+        const lines = rows.slice(0, 200).map((r) => r.ok
+            ? `- ${r.filename} → ${r.assetId}${r.status === 'exists' ? ' (already in the library)' : ''}${r.width ? ` ${r.width}×${r.height}` : ''}`
+            : `- ${r.filename}: ${r.status === 'cancelled' ? 'cancelled' : `${r.error?.code}: ${r.error?.message}`}`);
+        const text = [
+            `${uploaded} uploaded, ${existing} already in the library, ${failed} failed — ${rows.length} file${rows.length === 1 ? '' : 's'}, ${(0, tool_1.formatBytes)(totalBytes)} in ${(durationMs / 1000).toFixed(1)} s${folderId ? `, filed into folder ${args.folderName ?? folderId}` : ''}.`,
+            ...lines,
+            ...(rows.length > lines.length ? [`… and ${rows.length - lines.length} more.`] : []),
+            ...warnings,
+            ...(failed ? ['Run the tool again to retry the failed files — finished ones are skipped.'] : []),
+            ...(uploaded || existing ? ['Next: pw_panels_attach_artwork attaches the images to panels by file name.'] : []),
+        ].join('\n');
+        return {
+            text,
+            data: { workId: args.workId, ...(folderId ? { folderId } : {}), ...(folderCreated !== undefined ? { folderCreated } : {}), files: rows, uploaded, existing, failed, totalBytes, durationMs, skipped },
+        };
+    },
+});

package/package.json

@@ -1,6 +1,50 @@
-{
-  "name": "@panelwave/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@panelwave/mcp",
+  "version": "0.1.0",
+  "description": "Local MCP bridge for PanelWave: connects Claude Desktop, Claude Code, Cursor and other MCP clients to the hosted PanelWave MCP server and adds local file tools (list, read, upload a folder of panels).",
+  "main": "dist/index.js",
+  "bin": {
+    "panelwave-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "jest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "panelwave",
+    "mcp",
+    "model-context-protocol",
+    "graphic-novel",
+    "claude"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/panelwave/packages/tree/master/packages/mcp#readme",
+  "bugs": {
+    "url": "https://github.com/panelwave/packages/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/panelwave/packages.git",
+    "directory": "packages/mcp"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/client": "^2.2.0",
+    "@modelcontextprotocol/server": "^2.2.0",
+    "image-size": "^2.0.2",
+    "zod": "^4.2.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "@types/node": "^20.14.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.5",
+    "typescript": "^5.4.0"
+  }
+}