zipnative-mcp — AI client integration

zipnative-mcp 1.0.0 is the MCP server that gives AI assistants the zipnative engine as thirteen typed tools — inspect, list, read, verify, extract, scan, sanitise, create, modify, CRC, inflate, describe, draft — plus seven prompts and sandboxed file resources, over stdio or loopback Streamable HTTP, with no network access, ever. Pins zipnative ^1.0.0.

zipnative-mcp exposes the engine to any client that speaks the Model Context Protocol — Claude Desktop, Claude Code, Cursor, VS Code, Continue, Zed, Windsurf, Cline, Roo Code, ChatGPT over Streamable HTTP, the MCP Inspector, or anything built on the MCP SDKs. With it installed you can say to your assistant:

"Verify this build artefact, confirm it is reproducible and contains no encrypted or unsafe entries, then extract the manifest."

…and the assistant will call verify_zip, inspect_zip with its CI checks, and read_zip_entry, reasoning on structured results instead of prose. The server adds only the MCP SDK and zod to the engine — three runtime dependencies in total; the engine itself keeps zero.

Installation#

# Run directly with npx — the recommended form for MCP clients
npx -y zipnative-mcp

# Or install globally
npm install -g zipnative-mcp
zipnative-mcp

Requirements: Node.js ≥ 22. The published package carries npm provenance and an MCP registry manifest (server.json, name io.github.Nizoka/zipnative-mcp).

Configuration by client#

Every configuration below sets ZIPNATIVE_MCP_OUTPUT_DIR. It is optional — without it the tools work on base64 only — but it is what enables zipPath / sourcePath inputs, outputMode: 'file' and the zipnative://output/ resources.

Claude Desktop#

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows), then restart Claude Desktop:

{
  "mcpServers": {
    "zipnative": {
      "command": "npx",
      "args": ["-y", "zipnative-mcp"],
      "env": { "ZIPNATIVE_MCP_OUTPUT_DIR": "/Users/you/Documents/mcp-archives" }
    }
  }
}

Claude Code#

claude mcp add zipnative --env ZIPNATIVE_MCP_OUTPUT_DIR=/path/to/mcp-archives -- npx -y zipnative-mcp

Or commit a project-scoped .mcp.json with the same mcpServers shape as Claude Desktop — the zipnative-mcp repository ships one.

Cursor · Continue · Zed · Windsurf · Cline · Roo Code#

Any stdio-capable client takes the same command + args + env triple. Cursor (~/.cursor/mcp.json or the project .cursor/mcp.json):

{
  "mcpServers": {
    "zipnative": {
      "command": "npx",
      "args": ["-y", "zipnative-mcp"],
      "env": { "ZIPNATIVE_MCP_OUTPUT_DIR": "/Users/you/Documents/mcp-archives" }
    }
  }
}

VS Code#

.vscode/mcp.json:

{
  "servers": {
    "zipnative": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "zipnative-mcp"],
      "env": { "ZIPNATIVE_MCP_OUTPUT_DIR": "${workspaceFolder}/.mcp-archives" }
    }
  }
}

Streamable HTTP (ChatGPT and other HTTP hosts)#

ZIPNATIVE_MCP_PORT=3000 ZIPNATIVE_MCP_HTTP_TOKEN="$(openssl rand -hex 24)" npx -y zipnative-mcp
# → POST http://127.0.0.1:3000/mcp   (Authorization: Bearer <token>)

The endpoint binds loopback only and accepts POST /mcp alone: any other path answers 404, GET / DELETE answer 405, a foreign Host / Origin answers 403 (DNS-rebinding guard — and because the SDK's own check is port-agnostic, an Origin whose port differs from the server's port is refused too, so a local web page on another port is still cross-site), bodies above 256 MiB answer 413. Without ZIPNATIVE_MCP_HTTP_TOKEN the endpoint has no authentication — other local processes can reach it; with the token, a missing or wrong bearer answers 401 + WWW-Authenticate.

Environment variables#

An invalid ceiling refuses to start with one [zipnative-mcp] fatal: line and exit 1.

The same seven variables are declared in the package's MCP registry manifest, server.json (runtimeHint: "npx" with -y zipnative-mcp, transport stdio): each carries isRequired: false, a format (filepath for the two directories, number for the port and the three ceilings) and isSecret: true on ZIPNATIVE_MCP_HTTP_TOKEN alone, so a registry-driven host can prompt for them correctly.

Protocol and transport#

• MCP 2026-07-28 on the MCP TypeScript SDK v2: stateless serving (server/discover), the _meta envelope, and cache hints (tools/list and prompts/list public for 24 h, server/discover public for 1 h, the resource methods private with ttlMs: 0).
• Schemas are declared, not re-validated on the way out. Every tool advertises an inputSchema and an outputSchema; inputs are enforced at the boundary by Zod twins of those schemas, and structuredContent is built to follow the output schema — but the server deliberately stays on the SDK's low-level Server surface and does not run a runtime validator over its own results (the McpServer helper that would do so cannot express the verbosity / fields projections, hence the read tools' output schemas mark every property optional). A validating host is free to check.
• instructions. The initialize / server/discover response carries a server-instructions block — a decision tree (which tool for which question), the security posture and the common pitfalls — that a host may inject into the assistant's context; the seven prompts repeat the same material on demand.
• tools/list _meta. Every tool entry carries _meta.apiVersion (the tool-API version, 1.0.0, independent from the package version and bumped only when a schema changes) and _meta.examples — one or two self-contained, executable inputs per tool (<zip-base64> stands for the archive).
• Automatic legacy fallback for clients that open with initialize: 2024-10-07, 2024-11-05, 2025-03-26, 2025-06-18 and 2025-11-25 are negotiated on both transports; the tools/call payload is identical on every path.
• stdio raises the SDK's frame cap to 256 MiB so multi-MiB base64 archives fit in one call; nothing is ever printed to stdout except JSON-RPC.
• Protocol errors are JSON-RPC errors (-32602 for an unknown tool, resource or prompt), as the specification requires; isError: true is reserved for execution failures.
• SIGINT / SIGTERM close the server gracefully, exit 0.

Tool reference#

Thirteen tools, in the order tools/list returns them. Every archive-consuming tool takes exactly one of zipBase64 (the raw archive as base64, a data:…;base64, prefix tolerated, decoded ≤ 128 MiB) or zipPath (a relative path inside the sandbox, container extensions only — .zip .jar .war .ear .docx .xlsx .pptx .odt .ods .odp .epub .vsix .nupkg .whl .apk .ipa .xpi .crx .kmz; ≤ 1 GiB).

The shared inputs are not on every tool — the table below says which:

• limits (the eight ZipLimits bounds — maxEntries, maxEntryUncompressedSize, maxTotalUncompressedSize, maxCompressionRatio, maxNameBytes, maxExtraFieldBytes, maxCommentBytes, maxCentralDirectoryBytes; above the operator ceilings → LIMIT_CEILING_EXCEEDED) on the eight archive-consuming and archive-producing tools: inspect_zip, list_zip_entries, read_zip_entry, verify_zip, extract_zip, scan_zip_forward, create_zip, modify_zip.
• strict (escalate the first diagnostic to ZIP_STRICT_DIAGNOSTIC) on seven of those — not on verify_zip, whose whole point is to report rather than throw.
• verbosity ('full' | 'summary') and fields (≤ 16 dot paths) on the read tools: inspect_zip, list_zip_entries, read_zip_entry, verify_zip, extract_zip, scan_zip_forward, sanitize_entry_paths, describe_engine.
• diagnostics[] and diagnosticCounts (de-duplicated by code and entry, 200 kept, diagnosticsTruncated: true beyond) on the seven strict tools; verify_zip carries diagnostics[] alone (the engine report's own list); inflate_raw carries an always-empty diagnostics: []; compute_crc32, sanitize_entry_paths, describe_engine and draft_governance_issue carry neither.

Tool annotations: the read tools are readOnlyHint: true; every tool is idempotentHint: true, destructiveHint: false, openWorldHint: false. Each tool also has a human title, listed here as tools/list returns it.

inspect_zip#

Read-only report in one call — the zipnative inspect --json shape: size, entry / file / directory counts, Zip64, comment, compressed vs uncompressed totals and ratio, per-method counts, encrypted / symlink / data-descriptor / Zip64 / cp437 / duplicate / unsafe-name counts, date range, prependedData / multipleEocd, a determinism verdict (epochTimestamps, canonicalOrder, utf8Flags, noDataDescriptors, canonicalLayout, deterministic) and every diagnostic. Opens eagerly by default: overlapping entries, entries reaching past EOF and Zip64 spoofing are refused with their ZIP_* code rather than summarised.

Outputs the report plus checks[] ({ check, ok, detail }) and checksPassed when check / assert was supplied.

{ "zipBase64": "<base64 ZIP>", "check": ["deterministic", "no-encryption", "safe-names"], "assert": { "maxEntries": 5000, "has": ["manifest.json"] }, "verbosity": "summary", "fields": ["checksPassed", "checks"] }

list_zip_entries#

Every entry (duplicates included) in directory order as a full row — name and encoding, sizes, ratio, CRC-32, method, timestamp, decoded flags, Unix mode, symlink, Zip64, data descriptor, host system, offsets, named extra fields, sanitizedPath (null = the extraction gate would refuse it), comment — without decompressing anything.

One asymmetry to know: with no filter at all, explicit directory entries are listed; as soon as any filter object is given, its includeDirectories default of false applies (the default exists for extraction) — pass includeDirectories: true to keep them.

{ "zipBase64": "<base64 ZIP>", "filter": { "prefix": "src/", "glob": ["**/*.json"] }, "limit": 50, "fields": ["entries.name", "entries.uncompressedSize", "hasMore"] }

read_zip_entry#

One entry by name (exact; the last duplicate wins) or index (disambiguates duplicates). mode: 'data' returns the decompressed content, CRC-verified, as base64 or UTF-8 text; a range reads a byte window through the chunked stream (no CRC for a window). mode: 'raw' returns the compressed payload verbatim — feed it to inflate_raw. mode: 'verify' returns { ok, crcMatch, sizeMatch, localHeaderMatch } only. Encrypted entries are refused with ZIP_UNSUPPORTED_ENCRYPTION.

Inline cap 16 MiB per entry (ENTRY_TOO_LARGE, remedy range or extract_zip file mode).

{ "zipBase64": "<base64 ZIP>", "name": "META-INF/MANIFEST.MF", "encoding": "utf8" }

verify_zip#

The engine's verifyZip report verbatim: eager structural validation, then every entry's CRC-32 / size / local-header agreement. Never fails for a problem with the archive — a structural refusal lands in error: { code: 'ZIP_*', message }, an encrypted or stream-only-codec entry is skipped, an entry with no codec here is reported failed. Only caller mistakes are isError. Verify before you trust.

Outputs ok, error, entryCount, verifiedCount, failedCount, skippedCount, entries[], entriesTruncated, diagnostics[].

{ "zipBase64": "<base64 ZIP>", "entries": "failed", "verbosity": "summary" }

extract_zip#

Extract with every engine guard on unless you name the relaxation: unsafe names → ZIP_PATH_TRAVERSAL (rejectTraversal: false skips them — 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), sizes beyond limits → ZIP_LIMIT_EXCEEDED; overlapping entries and central / local divergence are always refused. The archive is opened eagerly before any plan in both modes.

Outputs mode, dryRun, fileCount, totalBytes, entries[] ({ path, entryName, index, sizeBytes, crc32, method, dataBase64? | filePath? }), skipped[], outputDir, directoriesCreated, diagnostics[]; file mode adds up to 50 resource_link blocks.

{ "zipBase64": "<base64 ZIP>", "outputMode": "file", "outputDir": "unpacked/report", "filter": { "glob": ["docs/", "*.json"] } }

scan_zip_forward#

Walk local headers in stream order with bounded memory — the engine's central-directory-less reader iterateZipEntries. The only tool that works on a truncated archive or a stream cut mid-way, and the only one whose result is not authoritative: forward iteration trusts local headers alone, so a hostile archive can present different content here than inspect_zip reports. The stream must start at a local header — an SFX or prepended prefix is refused with ZIP_SIGNATURE_MISMATCH (route such archives to inspect_zip; modify_zip mode: 'compact' drops the prefix). Use it for forensics; prefer the authoritative tools whenever the whole archive is available.

Outputs trust: 'local-headers-only', entryCount, keptCount, entries[], stoppedAt ('central-directory' | 'eof' | 'max-entries' | 'error'), truncated, inputBytes, bytesDelivered, maxEntries, error, diagnostics[].

{ "zipBase64": "<base64 of a truncated download>", "tolerateTruncation": true, "verbosity": "summary" }

sanitize_entry_paths#

The engine's single traversal gate sanitizeEntryPath() over a list of names: the safe /-separated relative form each maps to, or null with the rule that fired (empty, nul, absolute, drive, unc, traversal, ads, device-name, no-segments). No archive needed — use it before an external filesystem sink.

{ "names": ["docs/readme.md", "../../etc/passwd", "C:\\Windows\\win.ini", "aux.txt", "a/./b//c.txt"] }

create_zip#

Write a ZIP from inline entries (dataBase64 | text | sourcePath in the sandbox, or directory: true). Reproducible on one runtime by default — canonical order, DOS-epoch timestamps, UTF-8 names — and identical on every runtime under compression.deterministic: true (summary.deflateTier: 'pure-pinned'). order: 'insertion' keeps call order for EPUB / JAR; stream: true on a sourcePath feeds the file through addStream (bounded memory, > 4 GiB refused); parallel compresses with the worker pool, byte-identical. Zip64 is emitted exactly when a field overflows. Every archive it writes is ISO/IEC 21320-1 conformant.

Outputs the archive as an embedded resource (≤ 50 MiB inline) or a resource_link, plus summary (entryCount, fileCount, directoryCount, streamedCount, uncompressedBytes, order, deterministic, deflateTier, parallel, sha256) and diagnostics[].

{
  "entries": [
    { "name": "mimetype", "text": "application/epub+zip", "compression": { "method": "store" } },
    { "name": "META-INF/container.xml", "text": "<container/>" },
    { "name": "OEBPS/", "directory": true }
  ],
  "order": "insertion",
  "compression": { "deterministic": true },
  "includeSha256": true
}

modify_zip#

Edit an existing archive without recompressing anything: operations applied in order. mode: 'append' = save() — the original bytes stay verbatim and edits are appended, but removed or replaced payloads remain in the file (data remanence; a ZIP_DEAD_BYTES_RATIO diagnostic fires past 50 % dead bytes; 7-Zip is known to read the stale payload). mode: 'compact' = saveCompact() — canonical rewrite, still no recompression, removed data truly gone, SFX prefix dropped. Archives with duplicate names are refused.

Outputs the archive plus summary (saveMode, operationsApplied, entryCountBefore, entryCountAfter, inputBytes, outputBytes, grewByBytes, noOp, sha256).

{ "zipBase64": "<base64 ZIP>", "operations": [{ "op": "remove", "name": ".env" }, { "op": "rename", "from": "config.json", "to": "config/app.json" }], "mode": "compact" }

compute_crc32#

The ZIP checksum (IEEE CRC-32) of inline bytes, text or a sandbox file (streamed, ≤ 1 GiB). seed continues a running CRC; expect compares against a known value — cross-check an entry's crc32 from list_zip_entries against a file on disk.

Outputs crc32, hex, byteLength, seed, matches.

{ "text": "hello world", "expect": "0d4a1185" }

inflate_raw#

Decompress a raw DEFLATE stream — for instance the payload from read_zip_entry mode: 'raw' — through the engine's resumable inflater under a mandatory maxOutput bound (ZIP_INFLATE_OUTPUT_OVERFLOW past it). method: 'store' is a bounded pass-through; only methods 0 and 8 exist in this server.

{ "dataBase64": "<raw deflate payload>", "maxOutput": 1048576 }

describe_engine#

Offline preflight, no archive needed: server / engine / tool-API versions, the deflate tier in use and the pinned deterministic tier, runtime codecs and worker threads, the codec registry, the engine's default limits, the operator ceilings, every server cap, whether the sandbox and the cache are enabled, the 39 frozen ZIP_* error codes and 11 diagnostic codes, and the engine exports this server deliberately does not expose (with why). network is always 'none'. Never cached.

{ "fields": ["defaultLimits", "ceilings", "caps", "sandbox"] }

draft_governance_issue#

Draft a governance-compliant GitHub issue locally for a human to review and submit — for zipnative or zipnative-mcp. The server never contacts GitHub (it has no network code path); it returns the draft Markdown and a machine-readable compliance report. Present both, then stop: the human submits under their own identity.

A draft that proposes a runtime dependency, omits a reproduction or sets duplicateSearchPerformed: false is GOVERNANCE_VIOLATION.

Prompts#

Seven read-only prompts (no arguments) that teach the assistant the workflows and the rules:

Resources#

With ZIPNATIVE_MCP_OUTPUT_DIR set, every regular file in the sandbox is a resource under the zipnative://output/{+path} template: resources/list walks the sandbox (≤ 1000 files, depth ≤ 8), resources/templates/list advertises the one template (named sandbox-file, declared mimeType: application/zip), and resources/read returns { uri, mimeType, blob } up to 50 MiB. Without a sandbox both lists are empty. The MIME type is chosen by extension from a fixed table of 32 — the nineteen container extensions (.zip, .jar / .war / .ear as application/java-archive, the Office and OpenDocument types, .epub, .apk, .xpi, .crx, .kmz, and .vsix / .nupkg / .whl / .ipa as plain application/zip) plus .md .txt .json .xml .html .css .js .png .jpg .jpeg .gif .svg .pdf — and application/octet-stream for anything else.

Token-frugal reads#

Every read tool accepts verbosity: 'summary' (only the scalar summary fields) and fields: [...] (≤ 16 dot paths). When a fields entry matches nothing the result carries _meta.unmatchedFields and _meta.availableFields so the assistant can correct itself in one turn. Archive-producing tools deliver the bytes once, as an embedded resource with a data: URI (never duplicated into structuredContent); file mode returns a resource_link instead.

Error model#

An execution failure is { content: [{ type: 'text', text: '<tool> failed [CODE]: message' }], isError: true, _meta: { error: { code, message, data? } } }. Sixteen wrapper codes — VALIDATION_ERROR, INPUT_TOO_LARGE, INPUT_NOT_FOUND, ENTRY_TOO_LARGE, ENTRY_NOT_UTF8, OUTPUT_TOO_LARGE, OUTPUT_EXISTS, IO_ERROR, SECURITY_VIOLATION, MISSING_OUTPUT_PATH, INVALID_PATH, INVALID_EXTENSION, LIMIT_CEILING_EXCEEDED, UNKNOWN_RESOURCE, GOVERNANCE_VIOLATION, ENGINE_ERROR — sit next to the engine's 39 frozen ZIP_* codes, passed through verbatim (ZIP_PATH_TRAVERSAL, ZIP_LIMIT_EXCEEDED, ZIP_UNSUPPORTED_ENCRYPTION, …), and ZIP_STRICT_DIAGNOSTIC under strict: true. data.remedy names the way out where one exists (a range, a tool to call first, a ceiling).

Security model#

• Every archive is untrusted input, and the engine's guards are on by default: zip-slip and device names (CWE-22 / 67), bombs (CWE-400 / 409, enforced while inflating), symlinks (CWE-59), overlapping entries (CWE-405, no opt-out), parser-differential smuggling (CWE-436, the central directory is authoritative), Zip64 spoofing (CWE-1288, no opt-out), duplicate names (CWE-694).
• The sandbox is the one filesystem boundary for reads and writes; paths must be relative, real paths must stay inside, files are opened exclusively, a failed write removes the partial file.
• Inputs are validated at the boundary by strict JSON Schemas and Zod — unknown or misspelt keys are VALIDATION_ERROR.
• No encryption, ever: encrypted entries are detected, skipped by verify_zip, refused by the read paths. There is no password input — see Case 5 for how confidentiality is delegated to the document layer.
• No network, ever: no telemetry, no GitHub, no update check, no URL from any argument, no operator-configurable endpoint of any kind. describe_engine reports network: 'none'.

Further reading#

• MCP playground — the thirteen tools with their real payloads, most of them executable in your browser against the published engine.
• Choosing your surface · CLI guide — the same engine for scripts and CI.
• Security model · Errors and error codes · Use cases.
• The full README, AGENTS.md (with the complete error reference), server.json and thirty executable JSON examples live in the zipnative-mcp repository.