Extract (secure by default)
extract_zipExtract files from ZIP archives with security checks, filtering, and size limits, returning content as base64 or saving to a directory.
Instructions
Extract with every engine guard ON unless you name the relaxation: zip-slip / absolute / drive / UNC / NUL / ADS / Windows-device names → ZIP_PATH_TRAVERSAL (rejectTraversal:false SKIPS them, listed in skipped; an unsafe path is never emitted); symlinks → ZIP_SYMLINK_REJECTED (rejectSymlinks:false extracts the target text as data, never a link); duplicate sanitized paths → ZIP_EXTRACT_DUPLICATE_PATH (onDuplicate 'first' | 'last'); declared sizes / ratios beyond limits → ZIP_LIMIT_EXCEEDED; overlapping entries and central/local divergence are always refused. filter keeps a subset. outputMode 'base64' (default) returns files inline (≤ 16 MiB each, ≤ 32 MiB total; includeData:false = dry run of the plan); 'file' streams into a relative outputDir inside ZIPNATIVE_MCP_OUTPUT_DIR (never overwrites) and returns resource links. Directories are implied by paths (emptyDirectories:true creates the explicit ones). The dry run opens eagerly: an overlapping, offset-into-CD or Zip64-spoofed archive is refused before any plan is returned. Prefer read_zip_entry for a single file.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No | Dot-path projection applied after verbosity (e.g. ['entryCount', 'entries.name']); array segments map over elements; unmatched paths are reported in _meta.unmatchedFields. | |
| filter | No | Select entries by name. `names` (exact, case-sensitive), `prefix` (path prefix) and `glob` (patterns: `*` within a segment, `**` across segments, `?` one character; a pattern without `/` matches at any depth, a trailing `/` matches a whole subtree) are ANDed when several are given; `includeDirectories` (default false) keeps explicit directory entries. | |
| 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. | |
| zipPath | No | Relative path of an archive inside the ZIPNATIVE_MCP_OUTPUT_DIR sandbox (no absolute paths, no '..'; container extensions only: .zip .jar .docx .epub …). Exclusive with zipBase64. Lets a create/modify → verify/extract chain avoid re-sending the bytes. | |
| outputDir | No | Relative directory inside the sandbox to extract into (file mode; created if absent; no absolute paths, no '..'). | |
| verbosity | No | 'summary' returns only the scalar verdict fields (drops arrays and payloads) — the token-frugal form. | full |
| zipBase64 | No | The archive bytes as base64 (exactly once; a data: URI prefix is tolerated). Exclusive with zipPath. Decoded size ≤ 128 MiB. | |
| outputMode | No | 'base64' (default): files inline (≤ 16777216 bytes each, ≤ 33554432 bytes total). 'file': stream every file under outputDir inside ZIPNATIVE_MCP_OUTPUT_DIR (never overwrites) and return resource links. | base64 |
| includeData | No | base64 mode: false = dry run — list what WOULD be extracted (paths, sizes) without decompressing or returning bytes. | |
| onDuplicate | No | Two entries mapping to the same sanitized path: 'error' (default, ZIP_EXTRACT_DUPLICATE_PATH), keep the 'first', or keep the 'last'. | error |
| rejectSymlinks | No | true (default): a symlink entry fails the call with ZIP_SYMLINK_REJECTED. false: its target text is extracted as ordinary data (never materialised as a link). | |
| rejectTraversal | No | true (default): an entry whose name escapes the root (zip-slip, absolute, drive/UNC, NUL, ADS, Windows device name) fails the call with ZIP_PATH_TRAVERSAL. false: such entries are SKIPPED and listed in `skipped` — an unsafe path is never emitted either way. | |
| emptyDirectories | No | file mode: also create explicit directory entries (with a safe name) that hold no file. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | ||
| paths | No | summary only: the extracted paths. | |
| dryRun | No | true when includeData was false: nothing was decompressed. | |
| entries | No | One row per extracted file, in central-directory order. base64 mode carries dataBase64 (unless dryRun); file mode carries filePath. | |
| skipped | No | Entries skipped because their name is unsafe (only with rejectTraversal:false). | |
| fileCount | No | ||
| outputDir | No | Absolute sandbox directory (file mode). | |
| totalBytes | No | Sum of the extracted (or planned) uncompressed sizes. | |
| diagnostics | No | 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. | |
| skippedCount | No | summary only: number of skipped (unsafe-path) entries. | |
| diagnosticCount | No | summary only: number of distinct diagnostics. | |
| diagnosticCounts | No | Number of diagnostics received per code (counts every occurrence, including de-duplicated ones). | |
| directoriesCreated | No | ||
| diagnosticsTruncated | No | Present (true) when more than 200 distinct diagnostics were dropped from `diagnostics`. |