zipnative-mcp

Overview Schema Source Related Servers Discussions Admin

Sanitize entry paths (the traversal gate)

sanitize_entry_paths

Read-onlyIdempotent

Maps archive entry names to safe '/' separated relative paths or rejects unsafe ones with the triggering rule, covering traversal, absolute, reserved, and NTFS-stream risks before external extraction.

Instructions

Apply zipnative's single traversal gate sanitizeEntryPath() to a list of names: the safe '/'-separated relative form each maps to (join it under your extraction root — never the raw name), or null with the rule that fired (empty, NUL byte, absolute, drive letter, UNC, '..' traversal, NTFS alternate data stream ':', Windows reserved device name CON/NUL/COM1…). Use it when you extract with another tool or plan an external filesystem sink. No archive needed.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "names": "<names>"
    },
    "name": "sanitize_entry_paths"
  }
}

Input Schema

Name	Required	Description	Default
`names`	Yes	Entry names to check (as stored in an archive).
`fields`	No	Dot-paths to keep, after verbosity (e.g. ['entryCount', 'entries.name']); unmatched ones are listed in _meta.unmatchedFields.
`verbosity`	No	'summary': scalar verdict fields only (the token-frugal form).	full

Output Schema

Name	Required	Description
`count`	No
`results`	No
`rejectedCount`	No
`rejectedNames`	No	summary only: the rejected names.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv1.0.1Oct 27, 2026

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 / 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)."

First observedv1.0.0Sep 8, 2026

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds real value beyond them: it enumerates the specific rejection rules (empty, NUL byte, absolute, drive letter, UNC, '..', NTFS ADS ':', Windows reserved device names) and gives an operational instruction to join the result under an extraction root rather than trusting the raw name. It does not discuss batching cost or ordering of results across the 10,000-item cap, which keeps it from a 5.

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?

One dense but front-loaded sentence delivers purpose, return shape, and the safety caveat, followed by a short usage sentence. The long parenthetical rule list is high-value content, though the sentence is heavy enough that a reader must parse carefully; no sentence is wasted.

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 an output schema present and rich annotations, the description need not document return structure, and it correctly focuses on when to call it and the critical safety instruction. The only gap is that the `fields`/`verbosity` projection controls, which shape what the caller sees, are left entirely to the schema.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents `names`, `fields`, and `verbosity`. The description reinforces what `names` means (entry names as stored in an archive, each producing either a safe path or null) but says nothing about the field-projection or verbosity parameters. Baseline 3 is warranted when the schema carries the parameter burden.

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?

The description gives a specific verb and resource — apply the `sanitizeEntryPath()` traversal gate to a list of entry names — and states exactly what each name maps to (a safe '/'-separated relative form, or null plus the rule that fired). This is clearly distinguishable from siblings like extract_zip or inspect_zip, which operate on archives rather than bare name lists.

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

Usage Guidelines4/5

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

It explicitly states the condition for use: 'Use it when you extract with another tool or plan an external filesystem sink,' which implicitly routes archive-writing work to extract_zip instead. The 'No archive needed' note removes a common false precondition. It stops short of naming a sibling alternative outright, so it lands at 4 rather than 5.

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

Deploy Server