Extract (secure by default)
extract_zipExtract ZIP contents safely with guards for path traversal, symlinks, and size limits; select entries by name, prefix, or glob and return inline or to a sandboxed 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.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "extract_zip"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No | Dot-paths to keep, after verbosity (e.g. ['entryCount', 'entries.name']); unmatched ones are listed in _meta.unmatchedFields. | |
| filter | No | Select entries: `names` (exact), `prefix`, `glob` (`*` in a segment, `**` across, `?`, `[a-z]`; no `/` = any depth, trailing `/` = subtree), ANDed; `includeDirectories` (default false). | |
| limits | No | Per-call override of zipnative's security bounds (CWE-400/409); absent keys keep the engine defaults (describe_engine.defaultLimits). A value above its operator ceiling is LIMIT_CEILING_EXCEEDED. Raise only for trusted input. | |
| strict | No | Turn the first engine diagnostic into a ZIP_STRICT_DIAGNOSTIC error. | |
| zipPath | No | Archive path relative to the ZIPNATIVE_MCP_OUTPUT_DIR sandbox (container extensions: .zip .jar .docx .epub …). Exclusive with zipBase64; saves re-sending bytes between calls. | |
| outputDir | No | Relative directory inside the sandbox to extract into (file mode; created if absent; no absolute paths, no '..'). | |
| verbosity | No | 'summary': scalar verdict fields only (the token-frugal form). | full |
| zipBase64 | No | Archive bytes, base64 (≤ 128 MiB decoded). Exclusive with zipPath. | |
| 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 engine concerns (de-duplicated by code + entry, ≤ 200; codes in describe_engine.diagnosticCodes). Empty for a clean archive. | |
| skippedCount | No | summary only: number of skipped (unsafe-path) entries. | |
| diagnosticCount | No | summary only: number of distinct diagnostics. | |
| diagnosticCounts | No | Occurrences per code, duplicates included. | |
| directoriesCreated | No | ||
| diagnosticsTruncated | No | true when rows beyond 200 were dropped. |