Skip to main content
Glama
zipnative-mcp

zipnative-mcp

List entries (paged inventory)

list_zip_entries
Read-onlyIdempotent

List every entry in a ZIP archive from its central directory without extracting, with filters, paging, and detailed metadata for auditing or selecting files.

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:[…].

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": "list_zip_entries"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoReturn at most this many entries (default 200, max 2000); `hasMore` tells you to page.
accessNo'auto' (default): in memory, and a zipPath above 1073741824 bytes by byte ranges. 'range': always by byte ranges over the sandbox file (never a URL; memory ≈ the central directory). 'memory': always buffered (INPUT_TOO_LARGE above the cap).auto
fieldsNoDot-paths to keep, after verbosity (e.g. ['entryCount', 'entries.name']); unmatched ones are listed in _meta.unmatchedFields.
filterNoSelect entries: `names` (exact), `prefix`, `glob` (`*` in a segment, `**` across, `?`, `[a-z]`; no `/` = any depth, trailing `/` = subtree), ANDed; `includeDirectories` (default false).
limitsNoPer-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.
offsetNoSkip this many matching entries (paging).
strictNoTurn the first engine diagnostic into a ZIP_STRICT_DIAGNOSTIC error.
zipPathNoArchive path relative to the ZIPNATIVE_MCP_OUTPUT_DIR sandbox (container extensions: .zip .jar .docx .epub …). Exclusive with zipBase64; saves re-sending bytes between calls.
validateNo'lazy' (default) parses the central directory only; 'eager' also cross-checks every local header up front.lazy
verbosityNo'summary': scalar verdict fields only (the token-frugal form).full
zipBase64NoArchive bytes, base64 (≤ 128 MiB decoded). Exclusive with zipPath.
includeUnixIdsNoAdd each entry's `unixIds` (zipnative getUnixIds: the Info-ZIP ux uid / gid, or null).
includeExtraDataNoInclude each extra field payload as base64 (forensics).
includeExtendedTimestampsNoAdd each entry's `extendedTimestamps` (zipnative getExtendedTimestamps: UT, then NTFS, then the DOS fields; ISO-8601, UTC).

Output Schema

NameRequiredDescriptionDefault
limitNo
namesNosummary only: the names on this page.
accessNoPresent when the archive was read by byte ranges (access 'range', or a zipPath above the in-memory cap).
offsetNo
entriesNo
hasMoreNo
isZip64No
entryCountNoEntries in the central directory (before filtering).
diagnosticsNoNon-fatal engine concerns (de-duplicated by code + entry, ≤ 200; codes in describe_engine.diagnosticCodes). Empty for a clean archive.
matchedCountNoEntries kept by the filter (before paging).
returnedCountNo
diagnosticCountNosummary only: number of distinct diagnostics.
diagnosticCountsNoOccurrences per code, duplicates included.
diagnosticsTruncatedNotrue when rows beyond 200 were dropped.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed29 schema fields changedv1.0.1
    • addedInput schema / properties / access
      Added value: +{
      +  "default": "auto",
      +  "description": "'auto' (default): in memory, and a zipPath above 1073741824 bytes by byte ranges. 'range': always by byte ranges over the sandbox file (never a URL; memory ≈ the central directory). 'memory': always buffered (INPUT_TOO_LARGE above the cap).",
      +  "enum": [
      +    "auto",
      +    "memory",
      +    "range"
      +  ],
      +  "type": "string"
      +}
    • changedInput schema / properties / fields / description
      Previous value: -"Dot-path projection applied after verbosity (e.g. ['entryCount', 'entries.name']); array segments map over elements; unmatched paths are reported in _meta.unmatchedFields."New value: +"Dot-paths to keep, after verbosity (e.g. ['entryCount', 'entries.name']); unmatched ones are listed in _meta.unmatchedFields."
    • addedInput schema / properties / fields / items / pattern
      Added value: +"^(?!(?:[^.]*\\.)*(?:__proto__|constructor|prototype)(?:\\.|$)).+$"
    • changedInput schema / properties / filter / description
      Previous value: -"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."New value: +"Select entries: `names` (exact), `prefix`, `glob` (`*` in a segment, `**` across, `?`, `[a-z]`; no `/` = any depth, trailing `/` = subtree), ANDed; `includeDirectories` (default false)."
    • changedInput schema / properties / filter / properties / glob / description
      Previous value: -"Glob patterns; an entry matching ANY pattern is kept (e.g. ['**/*.json', 'docs/'])."New value: +"Patterns (≤ 1024 characters); ANY match keeps the entry (e.g. ['**/*.json', 'docs/'])."
    • addedInput schema / properties / filter / properties / glob / items / maxLength
      Added value: +1024
    • addedInput schema / properties / includeExtendedTimestamps
      Added value: +{
      +  "default": false,
      +  "description": "Add each entry's `extendedTimestamps` (zipnative getExtendedTimestamps: UT, then NTFS, then the DOS fields; ISO-8601, UTC).",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / includeUnixIds
      Added value: +{
      +  "default": false,
      +  "description": "Add each entry's `unixIds` (zipnative getUnixIds: the Info-ZIP ux uid / gid, or null).",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / limits / description
      Previous value: -"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."New value: +"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."
    • changedInput schema / properties / limits / properties / maxCentralDirectoryBytes / description
      Previous value: -"Maximum central-directory size in bytes."New value: +"Bytes."
    • changedInput schema / properties / limits / properties / maxCommentBytes / description
      Previous value: -"Maximum comment length in bytes."New value: +"Bytes."
    • changedInput schema / properties / limits / properties / maxCompressionRatio / description
      Previous value: -"Maximum declared uncompressed/compressed ratio for entries >= 1 KiB compressed (zip-bomb guard)."New value: +"Declared ratio (entries ≥ 1 KiB compressed)."
    • changedInput schema / properties / limits / properties / maxEntries / description
      Previous value: -"Maximum central-directory entry count."New value: +"Entries."
    • addedInput schema / properties / limits / properties / maxEntryCompressedSize
      Added value: +{
      +  "description": "Bytes, one compressed payload fetched by the byte-range reader (access range).",
      +  "minimum": 1,
      +  "type": "integer"
      +}
    • changedInput schema / properties / limits / properties / maxEntryUncompressedSize / description
      Previous value: -"Maximum decompressed size of one entry, bytes."New value: +"Bytes, one entry decompressed."
    • changedInput schema / properties / limits / properties / maxExtraFieldBytes / description
      Previous value: -"Maximum extra-field block length in bytes."New value: +"Bytes."
    • changedInput schema / properties / limits / properties / maxNameBytes / description
      Previous value: -"Maximum entry-name length in bytes."New value: +"Bytes."
    • changedInput schema / properties / limits / properties / maxTotalUncompressedSize / description
      Previous value: -"Maximum total decompressed size across an extraction, bytes."New value: +"Bytes, all entries decompressed."
    • changedInput schema / properties / strict / description
      Previous value: -"Escalate the first engine diagnostic (prepended data, duplicate name, name mismatch, …) to a ZIP_STRICT_DIAGNOSTIC error instead of reporting it."New value: +"Turn the first engine diagnostic into a ZIP_STRICT_DIAGNOSTIC error."
    • changedInput schema / properties / verbosity / description
      Previous value: -"'summary' returns only the scalar verdict fields (drops arrays and payloads) — the token-frugal form."New value: +"'summary': scalar verdict fields only (the token-frugal form)."
    • changedInput schema / properties / zipBase64 / description
      Previous value: -"The archive bytes as base64 (exactly once; a data: URI prefix is tolerated). Exclusive with zipPath. Decoded size ≤ 128 MiB."New value: +"Archive bytes, base64 (≤ 128 MiB decoded). Exclusive with zipPath."
    • changedInput schema / properties / zipPath / description
      Previous value: -"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."New value: +"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."
    • addedOutput schema / properties / access
      Added value: +{
      +  "description": "Present when the archive was read by byte ranges (access 'range', or a zipPath above the in-memory cap).",
      +  "enum": [
      +    "range"
      +  ],
      +  "type": "string"
      +}
    • changedOutput schema / properties / diagnosticCounts / description
      Previous value: -"Number of diagnostics received per code (counts every occurrence, including de-duplicated ones)."New value: +"Occurrences per code, duplicates included."
    • changedOutput schema / properties / diagnostics / description
      Previous value: -"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."New value: +"Non-fatal engine concerns (de-duplicated by code + entry, ≤ 200; codes in describe_engine.diagnosticCodes). Empty for a clean archive."
    • changedOutput schema / properties / diagnosticsTruncated / description
      Previous value: -"Present (true) when more than 200 distinct diagnostics were dropped from `diagnostics`."New value: +"true when rows beyond 200 were dropped."
    • addedOutput schema / properties / entries / items / properties / extendedTimestamps
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "With includeExtendedTimestamps: modification / access / creation instants (ISO-8601, UTC) from the UT (0x5455) extra, else the NTFS (0x000a) extra, else the DOS fields (source names which); a missing one is null.",
      +  "properties": {
      +    "atime": {
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "ctime": {
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "mtime": {
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "source": {
      +      "enum": [
      +        "ut",
      +        "ntfs",
      +        "dos"
      +      ],
      +      "type": "string"
      +    }
      +  },
      +  "type": "object"
      +}
    • changedOutput schema / properties / entries / items / properties / nameEncoding / enum
      Previous value: -[
      -  "utf-8",
      -  "cp437"
      -]New value: +[
      +  "utf-8",
      +  "cp437",
      +  "custom"
      +]
    • addedOutput schema / properties / entries / items / properties / unixIds
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "With includeUnixIds: the Unix owner uid / gid from the Info-ZIP ux (0x7875) extra; null when the archive carries none.",
      +  "properties": {
      +    "gid": {
      +      "minimum": 0,
      +      "type": "integer"
      +    },
      +    "uid": {
      +      "minimum": 0,
      +      "type": "integer"
      +    }
      +  },
      +  "type": [
      +    "object",
      +    "null"
      +  ]
      +}
  2. First observedv1.0.0

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive, but the description adds real behavioral context: no decompression occurs, duplicates are included, order is directory order, paging defaults (200) and cap (2000) with hasMore, and that a null sanitized path means an unsafe name. It does not touch on access-mode costs or limits overrides, but those are documented in the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three dense sentences, front-loaded with the core operation and ending with token-saving knobs. The long mid-sentence field enumeration is heavy but each item conveys what a row contains; nothing is redundant with the title or annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 14 parameters, an output schema and annotations, the description covers what an agent needs to select and call it: what is returned, how to filter and page, and when a sibling is better. Behavior of the advanced knobs is delegated to a fully-described schema, which is acceptable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3; the description still earns above that by compressing the meaning of filter (exact / prefix / globs), offset+limit paging with hasMore, and verbosity/fields into one readable sentence. The remaining 14 parameters (access, limits, validate, strict, include*) are left entirely to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource+mechanism: 'Read-only central-directory inventory without decompressing anything', and immediately enumerates the returned row. It is clearly differentiated from inspect_zip, read_zip_entry and extract_zip, which it names.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent: 'Prefer inspect_zip for a one-shot summary and read_zip_entry / extract_zip for content', and points to verbosity:'summary' / fields:[…] when tokens are a constraint. The selection condition is stated, not inferred.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.