Read one entry (random access)
read_zip_entryRead-onlyIdempotent
Read a single entry from a ZIP archive by name or index, returning its content as base64, text, or raw bytes, or verifying its integrity.
Instructions
Read ONE entry without extracting the archive, by name (exact; the last duplicate wins) or index (central-directory position — disambiguates duplicates). mode 'data' (default): decompressed content as base64 or UTF-8 text (encoding:'utf8'; ENTRY_NOT_UTF8 otherwise), CRC-verified; a range {offset,length} reads a byte window through the chunked stream (bounded memory, no CRC). mode 'raw': the compressed payload verbatim (feed it to inflate_raw). mode 'verify': CRC / size / local-header agreement only. Inline cap 16 MiB per entry (ENTRY_TOO_LARGE → use a range or extract_zip file mode). Encrypted entries → ZIP_UNSUPPORTED_ENCRYPTION (no decryption in this engine).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | 'data' (default): decompressed content; 'raw': the compressed payload bytes verbatim (zero-copy, no decompression); 'verify': CRC / size / local-header check only, no payload. | data |
| name | No | Entry name (exact, case-sensitive; the LAST duplicate wins). Exclusive with index. | |
| index | No | Central-directory position (from list_zip_entries) — disambiguates duplicate names. Exclusive with name. | |
| range | No | Read only a byte window of the decompressed content through the chunked stream (bounded memory; CRC is not verified for a window). length ≤ 16777216. | |
| 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. | |
| 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. | |
| encoding | No | Content encoding for mode 'data': base64 (default) or UTF-8 text (invalid UTF-8 → ENTRY_NOT_UTF8). | base64 |
| verbosity | No | 'summary' returns only the scalar verdict fields (drops arrays and payloads) — the token-frugal form. | full |
| verifyCrc | No | Verify the decompressed CRC-32 against the central directory (mode data, no range). | |
| zipBase64 | No | The archive bytes as base64 (exactly once; a data: URI prefix is tolerated). Exclusive with zipPath. Decoded size ≤ 128 MiB. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | ||
| name | No | summary only: the entry name. | |
| text | No | ||
| entry | No | ||
| index | No | summary only: the entry index. | |
| range | No | ||
| encoding | No | ||
| sizeBytes | No | Bytes returned (data / raw) or the declared uncompressed size (verify). | |
| dataBase64 | No | ||
| textLength | No | ||
| crcVerified | No | ||
| 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. | |
| verification | 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`. |