Create archive (reproducible; deterministic:true for cross-runtime identical bytes)
create_zipCreates ZIP archives from text, base64, or file entries with configurable compression and timestamps. Supports deterministic reproducible output, streaming, and resource limits for safe programmatic use.
Instructions
Write a ZIP from inline entries (dataBase64 | text | sourcePath in the sandbox, or directory:true). Reproducible by default: canonical order (raw UTF-8 name bytes), DOS-epoch timestamps, UTF-8 names, constant attributes — defaultDate:'now' or per-entry date opts out (ZIP_TIMESTAMP_NOT_PINNED diagnostic). compression {method store|deflate, level 0–9, deterministic:true = pinned pure-TS encoder ⇒ identical bytes on every runtime} at archive or entry level; order:'insertion' for EPUB / JAR (mimetype first, stored); comment, per-entry comment / unixMode / externalAttributes / raw extraFields. stream:true on a sourcePath feeds the file through addStream (data-descriptor layout, bounded memory). parallel compresses with the worker pool — byte-identical output. Zip64 is emitted exactly when a field overflows. Output base64 (≤ 50 MiB) or a sandbox file (streamed, never overwritten); summary.deterministic is true ONLY with compression.deterministic:true (cross-runtime identity); a default call is reproducible on the same runtime (deflateTier 'node-zlib') and reports false; sha256 (includeSha256, base64 and file modes) is the proof. Every archive it writes is ISO/IEC 21320-1 conformant (CI-validated).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| order | No | 'canonical' (default): entries sorted by raw UTF-8 name bytes (reproducible). 'insertion': call order preserved (EPUB / JAR mimetype-first layouts). | canonical |
| limits | No | Override zipnative's named security bounds for this call (CWE-400 / CWE-409 guards). Every key is optional; absent keys keep the engine defaults (maxEntries 100000, maxEntryUncompressedSize 1 GiB, maxTotalUncompressedSize 8 GiB, maxCompressionRatio 1024, maxNameBytes 4096, maxExtraFieldBytes 65535, maxCommentBytes 65535, maxCentralDirectoryBytes 256 MiB). Values above the operator ceilings (ZIPNATIVE_MCP_MAX_UNCOMPRESSED_BYTES, ZIPNATIVE_MCP_MAX_ENTRIES) are refused with LIMIT_CEILING_EXCEEDED. Raise a bound for trusted input only. | |
| strict | No | Escalate the first engine diagnostic (prepended data, duplicate name, name mismatch, …) to a ZIP_STRICT_DIAGNOSTIC error instead of reporting it. | |
| comment | No | Archive comment (UTF-8, ≤ 65535 bytes). | |
| entries | Yes | The entries to write (0–100000; an empty array writes a valid empty archive). Each takes exactly one of dataBase64 / text / sourcePath, or directory: true. | |
| parallel | No | Compress with the worker pool (zipnative/worker). Byte-identical to the sequential writer; only worth it for many large entries. `workers` 0 keeps everything on the calling thread. | |
| chunkSize | No | file mode: output chunk size for the streaming assembler (default 64 KiB). Never changes the bytes. | |
| outputMode | No | 'base64' (default) returns the bytes inline as an embedded resource (≤ 50 MiB). 'file' writes them inside ZIPNATIVE_MCP_OUTPUT_DIR (never overwrites; ≤ 4 GiB, streamed) and returns a resource_link. | base64 |
| outputPath | No | Relative path inside the sandbox (only when outputMode='file'); must end in a container extension (.zip recommended). | |
| compression | No | Compression settings. `method` 'deflate' (default) or 'store'; `level` 0–9 (default 6); `deterministic: true` pins the pure-TS encoder so the bytes are identical on every runtime (slower). | |
| defaultDate | No | Timestamp for entries that set no `date`: an ISO-8601 instant (1980-01-01 … 2107-12-31, 2-second DOS granularity) or 'now' (wall clock — emits the ZIP_TIMESTAMP_NOT_PINNED diagnostic and makes the bytes non-reproducible). Omitted: the DOS epoch 1980-01-01T00:00:00 (reproducible). | |
| includeSha256 | No | Add `summary.sha256` of the produced bytes (determinism proofs). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | ||
| summary | Yes | create_zip summary. | |
| filePath | No | Sandboxed absolute path (file mode). | |
| sizeBytes | Yes | ||
| diagnostics | Yes | Non-fatal conformance concerns the engine raised while parsing or writing (de-duplicated by code + entry, at most 200). Empty for a clean archive. Codes: ZIP_PREPENDED_DATA, ZIP_MULTIPLE_EOCD, ZIP_NAME_MISMATCH, ZIP_UNICODE_PATH_CONFLICT, ZIP_INVALID_UTF8_NAME, ZIP_DUPLICATE_NAME, ZIP_EXTRA_FIELD_MALFORMED, ZIP_ZIP64_EXTRA_IGNORED, ZIP_TIMESTAMP_NOT_PINNED, ZIP_NONDETERMINISTIC_CODEC, ZIP_DEAD_BYTES_RATIO. | |
| diagnosticCounts | No | Number of diagnostics received per code (counts every occurrence, including de-duplicated ones). | |
| diagnosticsTruncated | No | Present (true) when more than 200 distinct diagnostics were dropped from `diagnostics`. |