List entries (paged inventory)
list_zip_entriesRead-onlyIdempotent
List ZIP archive entries with filtering by name, prefix, or glob, paging via offset/limit, and selectable detail fields. Supports summary mode for concise output.
Instructions
Read-only central-directory inventory without decompressing anything: every entry (duplicates included) in directory order as a full row — name + encoding, sizes, ratio, CRC-32, method, timestamp, decoded flags, Unix mode, symlink, Zip64, data descriptor, host system, offsets, named extra fields, the sanitized path an extraction would use (null = unsafe name), comment. filter selects by exact names / prefix / globs; offset + limit page (default 200, max 2000, hasMore). Prefer inspect_zip for a one-shot summary and read_zip_entry / extract_zip for content. Token-frugal: verbosity:'summary' → names only; fields:[…].
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Return at most this many entries (default 200, max 2000); `hasMore` tells you to page. | |
| 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. | |
| offset | No | Skip this many matching entries (paging). | |
| 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. | |
| validate | No | 'lazy' (default) parses the central directory only; 'eager' also cross-checks every local header up front. | lazy |
| 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. | |
| includeExtraData | No | Include each extra field payload as base64 (forensics). |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| names | No | summary only: the names on this page. | |
| offset | No | ||
| entries | No | ||
| hasMore | No | ||
| isZip64 | No | ||
| entryCount | No | Entries in the central directory (before filtering). | |
| 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. | |
| matchedCount | No | Entries kept by the filter (before paging). | |
| returnedCount | No | ||
| diagnosticCount | No | summary only: number of distinct diagnostics. | |
| 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`. |