neozip-mcp 0.1.0-beta

package/docs/OPERATIONS.md

@@ -0,0 +1,992 @@
+# NeoZip MCP Operations Reference
+
+> **Beta:** This package is in beta (`neozip-mcp@beta`). Tool names, parameters, and behavior may change before a stable release.
+
+This document describes every MCP tool exposed by **neozip-mcp**, including parameters, options, requirements, and typical output.
+
+Tools are enabled via capability groups (`NEOZIP_MCP_CAPABILITIES`, default **`auto`**):
+
+| Group | Tools |
+|-------|-------|
+| `zip` | `compress`, `extract`, `list`, `info`, `test`, `read_entry`, `search_entries`, `grep_entries`, `upgrade_timestamped`, `token_service_status`, `lookup_recipient`, `wallet_config_status`, `identity_status`, **`connect_status`** |
+| `blockchain` | `mint`, `verify`, `stamp`, `upgrade_timestamped`, `wallet_info`, `wallet_config_status`, `identity_status`, `token_service_status`, `token_service_register`, `token_service_verify`, `lookup_recipient`, **`connect_status`** |
+| `readonly` | `list`, `info`, `test`, `verify`, `wallet_info`, `wallet_config_status`, `identity_status`, `read_entry`, `search_entries`, `grep_entries`, `upgrade_timestamped`, `token_service_status`, `lookup_recipient`, **`connect_status`** |
+| `account` | `account_status`, `account_list`, `account_create`, `account_select`, `account_register_email`, `account_verify_email`, `account_create_wallet`, `account_import_wallet`, `account_link_wallet`, `account_provision_identity`, `account_remove`, `account_logout`, `account_initialize`, `wallet_config_status`, `identity_status`, **`connect_status`** |
+
+### `auto` capabilities (default)
+
+When unset or set to `auto`, the server resolves capabilities at startup from the NeoZip connection store:
+
+| Connect state | Resolved groups |
+|---------------|-----------------|
+| `phase: ready` and access token valid | `zip`, `blockchain`, `readonly` |
+| Otherwise (no profile, incomplete setup, expired token) | `zip`, `readonly` |
+
+After `neozip-connect` finishes, reload MCP in your host (Cursor Settings, `claude mcp list`, etc.) so blockchain tools appear. Use an explicit comma list (e.g. `zip,readonly` or `zip`) to pin behavior regardless of connect state.
+
+### Installed stdio: startup vs Token Service tools
+
+The MCP server **starts by default** without requiring Token Service setup. With **`auto`** capabilities (default), blockchain tools are exposed only after `neozip-connect` reaches `phase: ready`. Tools that need the service (`stamp`, `compress` with `timestamp`/`tokenize`/`recipientEmails`, etc.) return a setup message at runtime when connect is incomplete.
+
+Optional **startup gate** (server exits until `phase: ready`):
+
+- Resolved capabilities include `blockchain` or `account` (happens automatically when `auto` and connect is ready)
+- `NEOZIP_MCP_REQUIRE_ACCOUNT=true`
+
+For strict stdio installs: run `neozip-connect`, then reload MCP.
+
+**Host setup:** [installation-guides/INSTALL_CLAUDE_CODE.md](./installation-guides/INSTALL_CLAUDE_CODE.md), [installation-guides/INSTALL_CLAUDE_WORKSPACE.md](./installation-guides/INSTALL_CLAUDE_WORKSPACE.md), Cursor — package README and [`.cursor/mcp.json.global.example`](../.cursor/mcp.json.global.example).
+
+All file paths must fall within the configured sandbox (`NEOZIP_MCP_SANDBOX_PATHS`, default: current working directory and home directory). Operations that read or write files validate paths before execution.
+
+All tools return MCP text content. Errors are returned as `Error: <message>` rather than thrown.
+
+---
+
+## ZIP Operations
+
+### `compress`
+
+Create a ZIP archive from one or more files or directories.
+
+**Parameters**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `input` | `string` or `string[]` | Yes | File or directory path(s) to include in the archive. Directories are expanded recursively. |
+| `output` | `string` | Yes | Output archive path (`.zip` or `.nzip`). Parent directories are created if needed. |
+| `options` | `object` | No | Compression and metadata options (see below). |
+
+**Options**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `level` | `number` (0–9) | `6` | Compression level. Higher values generally produce smaller files at the cost of speed. |
+| `method` | `"deflate"` \| `"zstd"` \| `"store"` | `"zstd"` | Compression method. Default is Zstandard; use `deflate` or `store` to override. |
+| `password` | `string` | — | Password for encrypted archives. When set, entries are encrypted (default method: **NeoZip AES-256**). |
+| `encryptionMethod` | `"zipcrypto"` \| `"aes256"` \| `"neo-aes256"` | `"neo-aes256"` (when `password` set) | PKZIP ZipCrypto, WinZip AES-256, or NeoZip AES-256. |
+| `encryptionStrength` | `1` \| `2` \| `3` | — | **Deprecated.** Maps to `encryptionMethod`: `1` → zipcrypto, `2` → aes256, `3` → neo-aes256. Ignored when `encryptionMethod` is set. |
+| `useSHA256` | `boolean` | `false` | Per-entry SHA-256 hashes and merkle root. **Auto-enabled** when `timestamp` or `tokenize` is `true`. Only needed for plain archives when you want merkle metadata without Token Service or on-chain steps. |
+| `timestamp` | `boolean` | `false` | After compression, submit the merkle root to the **NeoZip Token Service** and embed `META-INF/TS-SUBMIT.NZIP`. Requires verified email via **neozip-connect** (or `options.recipientEmail`). Implies `useSHA256`. Mutually exclusive with `tokenize`. |
+| `tokenize` | `boolean` | `false` | After compression, mint the merkle root on-chain and embed `META-INF/TOKEN.NZIP`. Requires wallet from **neozip-connect** (`finish`). Implies `useSHA256`. Mutually exclusive with `timestamp` — use this when a wallet is available; tokenized archives provide on-chain proof and supersede the timestamp-only path. |
+| `recipientEmail` | `string` | connect profile email | Verified email for Token Service timestamp submission (used when `timestamp: true`). Also used as sender when `includeSenderAsRecipient` is true. |
+| `recipientEmails` | `string[]` | — | Token Service emails for **recipient encryption** (`META-INF/ACCESS.NZIP`). Mutually exclusive with `password`, `timestamp`, and `tokenize`. |
+| `includeSenderAsRecipient` | `boolean` | `true` | When `recipientEmails` is set, also encrypt for the neozip-connect profile email if that account has a provisioned public key. |
+| `serverUrl` | `string` | connect profile URL | NeoZip Token Service base URL. |
+| `network` | `string` | `NEOZIP_NETWORK` | Blockchain network for `tokenize` (e.g. `base-sepolia`). |
+| `comment` | `string` | — | Archive comment stored in ZIP metadata. |
+| `overwrite` | `boolean` | `false` | Overwrite `output` if it already exists. When `false`, the operation fails if the file exists. |
+
+**Archive types**
+
+| Goal | Options |
+|------|---------|
+| Plain archive (default) | Omit `useSHA256`, `timestamp`, and `tokenize` |
+| SHA-256 archive only | `useSHA256: true` |
+| Timestamped `.nzip` | `timestamp: true` (+ verified recipient email) |
+| Tokenized `.nzip` | `tokenize: true` (+ wallet on supported network) |
+| Password-protected | `password` (+ optional `encryptionMethod`) |
+| Recipient-encrypted | `recipientEmails` (public keys from Token Service) |
+
+**Recipient encryption (public-key)**
+
+- Uses `@neowareinc/neozipkit-pro`: inner NeoZip AES-256 payload + ECIES-wrapped keys in `META-INF/ACCESS.NZIP`.
+- Recipients must have provisioned X25519 keys on the Token Service (`GET /crypto/public?email=`). Use **`lookup_recipient`** before compress to verify an email.
+- **Opening** archives: configure identity private key in MCP env only — `NEOZIP_IDENTITY_PRIVATE_KEY_HEX`, or `NEOZIP_TOKEN_SERVICE_ACCESS_TOKEN` + `NEOZIP_WALLET_PASSKEY` (wallet unwrap). Not supported via tool arguments.
+- Cannot combine with `password`, `timestamp`, or `tokenize` in one `compress` call.
+
+**Example — recipient-encrypted archive**
+
+```json
+{
+  "input": ["test/fixtures/calgary/bib"],
+  "output": "test/output/sample-recipient.nzip",
+  "options": {
+    "recipientEmails": ["colleague@example.com"],
+    "includeSenderAsRecipient": true,
+    "overwrite": true
+  }
+}
+```
+
+**Password encryption**
+
+- Supported via neozipkit: legacy **ZipCrypto** (`zipcrypto`), **WinZip AES-256** (`aes256`), and **NeoZip AES-256** (`neo-aes256`, default when only `password` is provided).
+- When `password` is set, compression uses **deflate** instead of zstd (neozipkit encrypted path).
+- **Security:** passwords appear in MCP tool-call JSON (visible to the model). Prefer env-driven fixture scripts (`NEOZIP_FIXTURE_PASSWORD`) for automation, not chat-inline secrets for production archives.
+- **Blockchain:** `useSHA256`, `timestamp`, and `tokenize` operate on encrypted payloads; verification tools still need `options.password` to decrypt entries first.
+
+**Example — encrypted archive**
+
+```json
+{
+  "input": ["docs/OPERATIONS.md"],
+  "output": "test/output/encrypted.nzip",
+  "options": {
+    "password": "your-secret",
+    "encryptionMethod": "neo-aes256",
+    "overwrite": true
+  }
+}
+```
+
+**Example — plain archive**
+
+```json
+{
+  "input": ["test/fixtures/calgary"],
+  "output": "test/output/sample.nzip",
+  "options": {
+    "overwrite": true
+  }
+}
+```
+
+**Example — timestamped archive**
+
+```json
+{
+  "input": ["test/fixtures/calgary"],
+  "output": "test/output/sample-timestamped.nzip",
+  "options": {
+    "timestamp": true,
+    "overwrite": true
+  }
+}
+```
+
+**Example — tokenized archive**
+
+```json
+{
+  "input": ["test/fixtures/calgary"],
+  "output": "test/output/sample-tokenized.nzip",
+  "options": {
+    "tokenize": true,
+    "overwrite": true
+  }
+}
+```
+
+**Legacy example — explicit SHA-256 only**
+
+```json
+{
+  "input": ["/home/user/documents/report.pdf", "/home/user/documents/data/"],
+  "output": "/home/user/archives/report.nzip",
+  "options": {
+    "method": "zstd",
+    "level": 9,
+    "useSHA256": true,
+    "overwrite": true
+  }
+}
+```
+
+**Output**
+
+Summary including output path, file count, archive size, and when applicable merkle root / Token Service batch ID / on-chain token ID.
+
+---
+
+### `extract`
+
+Extract a ZIP archive to a directory.
+
+**Parameters**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `input` | `string` | Yes | Path to the ZIP archive. |
+| `output` | `string` | Yes | Destination directory for extracted files. |
+| `options` | `object` | No | Extraction behavior (see below). |
+
+**Options**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `password` | `string` | — | Password for encrypted archives. |
+| `overwrite` | `boolean` | `false` | Overwrite existing files at the destination. When `false`, existing files are skipped. |
+| `createDirectories` | `boolean` | `true` | Create the output directory (and parent paths) if it does not exist. |
+| `preserveTimestamps` | `boolean` | `false` | Preserve original file modification times from the archive. |
+
+**Example**
+
+```json
+{
+  "input": "/home/user/archives/report.nzip",
+  "output": "/home/user/extracted/report",
+  "options": {
+    "overwrite": true,
+    "preserveTimestamps": true
+  }
+}
+```
+
+**Output**
+
+Summary with extracted file count, output path, and skipped file count (if any).
+
+---
+
+### `list`
+
+List the contents of a ZIP archive.
+
+**Parameters**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `input` | `string` | Yes | Path to the ZIP archive. |
+| `options` | `object` | No | Listing format options (see below). |
+
+**Options**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `password` | `string` | — | Password for encrypted archives. |
+| `verbose` | `boolean` | `false` | Include compressed size, compression method, and modification date per entry. |
+| `format` | `"text"` \| `"json"` | `"text"` | Return terminal-style text or a structured JSON manifest with `isTextSafe` per entry. |
+
+**Example**
+
+```json
+{
+  "input": "/home/user/archives/report.nzip",
+  "options": { "verbose": true }
+}
+```
+
+**Output**
+
+Formatted listing with entry names, sizes, optional compression details, and archive totals (uncompressed size, compressed size, compression ratio).
+
+---
+
+### `info`
+
+Get detailed metadata about a ZIP archive.
+
+**Parameters**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `input` | `string` | Yes | Path to the ZIP archive. |
+| `options` | `object` | No | Archive access options (see below). |
+
+**Options**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `password` | `string` | — | Password for encrypted archives. |
+| `format` | `"text"` \| `"json"` | `"text"` | Return terminal-style text or a structured JSON manifest with entry summaries and merkle root. |
+
+**Example**
+
+```json
+{
+  "input": "/home/user/archives/report.nzip"
+}
+```
+
+**Output**
+
+Archive path, file size on disk, entry count, uncompressed/compressed totals, compression ratio, compression methods used, encrypted entry count and **encryption schemes** (if any), per-entry `encryptionScheme` in JSON manifests, archive comment (if present), **merkle root** (when entries contain SHA-256 hashes), **archiveKind** (`plain`, `timestamped-pending`, `timestamped-confirmed`, `tokenized`), and **blockchain** verification object when timestamp/token metadata is present (JSON format).
+
+---
+
+### `test`
+
+Test the integrity of a ZIP archive by verifying each file entry.
+
+**Parameters**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `input` | `string` | Yes | Path to the ZIP archive. |
+| `options` | `object` | No | Verification options (see below). |
+
+**Options**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `password` | `string` | — | Password for encrypted archives. |
+| `verifyPassword` | `boolean` | `false` | Decrypt encrypted payload entries with `password` and confirm a wrong password does not yield the same plaintext. Requires `password`. |
+| `skipHashCheck` | `boolean` | `false` | Skip SHA-256 / merkle hash verification during entry tests. |
+| `skipBlockchainCheck` | `boolean` | `false` | Skip Token Service / on-chain verification for timestamped or tokenized archives. |
+
+For archives with `META-INF/TS-SUBMIT.NZIP`, `META-INF/TIMESTAMP.NZIP`, or `META-INF/TOKEN.NZIP`, **test** also reports blockchain verification status (`VERIFIED`, `PENDING`, or `FAILED`) without failing payload integrity when the timestamp is still pending confirmation. When on-chain status is **PENDING**, output explains that the digest is queued at the Token Service until the batch is submitted to the blockchain. Archives that still contain `META-INF/TS-SUBMIT.NZIP` after the batch is confirmed emit a **WARNING**: on-chain checks go through the Token Service and cannot be verified independently until **upgrade** replaces submission metadata with `META-INF/TIMESTAMP.NZIP`.
+
+**Example**
+
+```json
+{
+  "input": "/home/user/archives/report.nzip",
+  "options": { "skipHashCheck": false }
+}
+```
+
+**Example — verify password on encrypted archive**
+
+```json
+{
+  "input": "test/output/sample-encrypted.nzip",
+  "options": {
+    "password": "test-password",
+    "verifyPassword": true
+  }
+}
+```
+
+Fixture and cursor scenarios use the standard test password **`test-password`** (see `FIXTURE_TEST_PASSWORD` in `src/archive/encryption.ts`).
+
+**Output**
+
+Per-entry pass/fail status, overall integrity summary (`PASSED` or `FAILED`), optional **Password decrypt verification** when `verifyPassword` is true, and when metadata is present, blockchain verification status for timestamped or tokenized archives.
+
+---
+
+### `read_entry`
+
+Read the text contents of a specific file inside a ZIP archive **without extracting the entire package**. Supports pagination to protect LLM context limits.
+
+**Parameters**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `input` | `string` | Yes | Path to the ZIP archive. |
+| `entryPath` | `string` | Yes | Relative path of the file inside the archive. |
+| `options` | `object` | No | Archive access options (see below). |
+| `offset` | `number` | No | Character offset to start reading from (default `0`). |
+| `maxChars` | `number` | No | Maximum characters to return (default from `NEOZIP_MCP_DEFAULT_MAX_CHARS`, capped by `NEOZIP_MCP_MAX_READ_CHARS`). |
+| `translate` | `boolean` | No | Apply content translators for JSON/CSV (default `true`). |
+
+**Options (`options`)**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `password` | `string` | — | Password when the target entry (or archive) is encrypted. |
+
+**Example**
+
+```json
+{
+  "input": "/home/user/archives/project.nzip",
+  "entryPath": "src/index.ts",
+  "offset": 0,
+  "maxChars": 8000
+}
+```
+
+**Output (JSON)**
+
+```json
+{
+  "file_path": "src/index.ts",
+  "total_characters": 45000,
+  "has_more": true,
+  "next_offset": 8000,
+  "content": "/* file contents... */"
+}
+```
+
+Content translators (Phase 1): plain text passthrough, JSON pretty-print/summarize, CSV to Markdown table. PDF, DOCX, XLSX, and XML are deferred.
+
+---
+
+### `search_entries`
+
+Search file names inside a ZIP archive by keyword or regex without reading file contents.
+
+**Parameters**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `input` | `string` | Yes | Path to the ZIP archive. |
+| `query` | `string` | Yes | Keyword, glob pattern (`*`, `?`), or regex pattern. |
+| `options` | `object` | No | Search options (see below). |
+
+**Options**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `mode` | `"keyword"` \| `"regex"` | `"keyword"` | Match mode for the query. |
+| `caseSensitive` | `boolean` | `false` | Case-sensitive matching. |
+| `password` | `string` | — | Password for encrypted archives (required to read encrypted entry metadata). |
+
+**Example**
+
+```json
+{
+  "input": "/home/user/archives/project.nzip",
+  "query": "src/**/*.ts",
+  "options": { "mode": "keyword" }
+}
+```
+
+**Output**
+
+JSON object with `matchCount` and `matches[]` including `path`, `uncompressedSize`, `isTextSafe`, and `contentType`.
+
+---
+
+### `grep_entries`
+
+Search for text strings or regex matches **inside file contents** within a ZIP archive without extracting files to disk. Only scans `isTextSafe` entries.
+
+**Parameters**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `input` | `string` | Yes | Path to the ZIP archive. |
+| `pattern` | `string` | Yes | Text or regex pattern to search for in file contents. |
+| `options` | `object` | No | Grep options (see below). |
+
+**Options**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `mode` | `"keyword"` \| `"regex"` | `"keyword"` | Match mode for the pattern. |
+| `caseSensitive` | `boolean` | `false` | Case-sensitive matching. |
+| `pathFilter` | `string` | — | Optional glob or path prefix to limit scanned entries (e.g. `src/**/*.ts`). |
+| `maxMatches` | `number` | `NEOZIP_MCP_GREP_MAX_MATCHES` | Cap total matches returned. |
+| `contextLines` | `number` | `0` | Lines of context before/after each match. |
+| `maxSnippetChars` | `number` | `NEOZIP_MCP_GREP_MAX_SNIPPET_CHARS` | Max characters per match snippet. |
+| `password` | `string` | — | Password for encrypted archives (required to decrypt and scan entry bodies). |
+
+**Example**
+
+```json
+{
+  "input": "/home/user/archives/project.nzip",
+  "pattern": "function handleError",
+  "options": {
+    "mode": "keyword",
+    "pathFilter": "src/**/*.js",
+    "contextLines": 1
+  }
+}
+```
+
+**Output (JSON)**
+
+```json
+{
+  "archive": "/home/user/archives/project.nzip",
+  "pattern": "function handleError",
+  "mode": "keyword",
+  "filesScanned": 12,
+  "filesSkipped": 3,
+  "matchCount": 1,
+  "truncated": false,
+  "matches": [
+    {
+      "path": "src/utils.js",
+      "line": 87,
+      "column": 10,
+      "snippet": "export function handleError(err) {",
+      "contextBefore": ["..."],
+      "contextAfter": ["..."]
+    }
+  ]
+}
+```
+
+Entries larger than `NEOZIP_MCP_GREP_MAX_FILE_BYTES` (default 1 MB) are skipped. Binary or non-text-safe files are skipped without error.
+
+---
+
+## MCP Resources (`zip://`)
+
+When ZIP read tools are enabled, the server exposes a resource template for direct archive entry access:
+
+| URI pattern | Description |
+|-------------|-------------|
+| `zip://{archivePath}` | JSON manifest of archive entries |
+| `zip://{archivePath}/{entryPath}` | Translated text content of a single entry |
+
+Example: `zip:///home/user/archives/project.nzip/src/index.ts`
+
+Pass optional resource argument **`password`** when reading encrypted entries (same as `read_entry` / `grep_entries`).
+
+Resources reuse the same sandbox validation, in-memory extraction, and translators as `read_entry`.
+
+---
+
+## Blockchain Operations
+
+Blockchain tools use [neozip-blockchain](https://www.npmjs.com/package/neozip-blockchain). Wallet-backed operations require a wallet configured via **neozip-connect** (`~/.neozip/connection/`).
+
+Default network: `base-sepolia` (`NEOZIP_NETWORK`).
+
+---
+
+### `mint`
+
+Mint a ZIP merkle root as an NFT on the blockchain (Base network).
+
+**Requirements**
+
+- Wallet private key configured
+- Valid 64-character hex merkle root (typically from a SHA-256-enabled archive)
+
+**Parameters**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `merkleRoot` | `string` | Yes | 64-character hex SHA-256 merkle root to mint. |
+| `options` | `object` | No | Minting options (see below). |
+
+**Options**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `network` | `string` | `NEOZIP_NETWORK` | Target blockchain network (e.g. `base-sepolia`, `base`). |
+
+**Example**
+
+```json
+{
+  "merkleRoot": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456",
+  "options": {
+    "network": "base-sepolia"
+  }
+}
+```
+
+**Output**
+
+Token ID, transaction hash, network, and merkle root on success.
+
+---
+
+### `verify`
+
+Verify a tokenized ZIP file by checking `META-INF/TOKEN.NZIP` metadata against the blockchain.
+
+**Parameters**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `input` | `string` | Yes | Path to the tokenized ZIP archive. |
+| `options` | `object` | No | Verification options (see below). |
+
+**Options**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `password` | `string` | — | Password when payload entries are encrypted. |
+| `network` | `string` | — | Network hint for verification (passed through to verifier when supported). |
+| `skipHash` | `boolean` | `false` | Skip local merkle root / hash comparison during verification. |
+
+**Example**
+
+```json
+{
+  "input": "/home/user/archives/tokenized.nzip",
+  "options": { "skipHash": false }
+}
+```
+
+**Output**
+
+Verification status (`VERIFIED` or `FAILED`), token ID, network, calculated merkle root, and any verifier message.
+
+---
+
+### `stamp`
+
+Submit a ZIP archive's merkle root to the **NeoZip Token Service** for blockchain timestamping.
+
+The archive must contain per-entry SHA-256 hashes (create with `compress` and `options.timestamp: true`, or `useSHA256: true`). Stamping requires a verified recipient email on the Token Service. Metadata is embedded as `META-INF/TS-SUBMIT.NZIP`.
+
+**Parameters**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `input` | `string` | Yes | Path to the SHA-256-enabled ZIP archive. |
+| `options` | `object` | No | Token Service options (see below). |
+
+**Options**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `recipientEmail` | `string` | connect profile email | Verified email address for Token Service authentication. |
+| `serverUrl` | `string` | connect profile URL or library default | NeoZip Token Service base URL. |
+
+**Configuration source**
+
+| Source | Setting |
+|--------|---------|
+| `neozip-connect` (`~/.neozip/connection/`) | Verified email, access token, wallet key, Token Service URL |
+
+**Example**
+
+```json
+{
+  "input": "/home/user/archives/report.nzip",
+  "options": {
+    "recipientEmail": "user@example.com",
+    "serverUrl": "https://testnet.token-service.neozip.io"
+  }
+}
+```
+
+**Output**
+
+Submission confirmation with merkle root, server URL, digest, status, and batch ID (when returned by the service).
+
+---
+
+### `upgrade_timestamped`
+
+Upgrade Timestamped archive: replace pending submission metadata with confirmed timestamp metadata once the batch is on-chain.
+
+Looks for timestamp metadata entries:
+
+- Pending: `META-INF/TS-SUBMIT.NZIP`
+- Confirmed: `META-INF/TIMESTAMP.NZIP`
+
+**Parameters**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `input` | `string` | Yes | Path to the timestamped ZIP archive. |
+| `output` | `string` | No | Output path for the upgraded archive. Defaults to `<input>-upgraded.<ext>`. |
+| `options` | `object` | No | Token Service options (see below). |
+
+**Options**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `serverUrl` | `string` | `TOKEN_SERVICE_URL` or library default | NeoZip Token Service base URL. |
+| `wait` | `boolean` | `true` | Poll Token Service until the batch is confirmed (5-minute timeout, 5-second interval). Set `false` for a single verify check. |
+| `overwrite` | `boolean` | `false` | Overwrite `output` if it already exists. |
+
+**Example**
+
+```json
+{
+  "input": "/home/user/archives/pending.nzip",
+  "output": "/home/user/archives/confirmed.nzip",
+  "options": {
+    "serverUrl": "https://testnet.token-service.neozip.io",
+    "overwrite": true
+  }
+}
+```
+
+**Output**
+
+Upgrade status, input/output paths, merkle root, and transaction hash when the batch is confirmed. Returns an informational message if the timestamp is already confirmed or not yet ready.
+
+*(Legacy tool name `upgrade` was renamed to `upgrade_timestamped`.)*
+
+---
+
+### `wallet_info`
+
+Display wallet and network status. Does not require a wallet key to run, but balance and address details are only shown when a key is configured.
+
+**Parameters**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `options` | `object` | No | Network selection (see below). |
+
+**Options**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `network` | `string` | `NEOZIP_NETWORK` | Network to query for chain ID, contract address, and balance. |
+
+**Example**
+
+```json
+{
+  "options": { "network": "base-sepolia" }
+}
+```
+
+**Output**
+
+Network name, chain ID, contract address, masked wallet key, wallet address, ETH balance (when RPC is available), and list of supported networks.
+
+---
+
+## NeoZip Token Service
+
+NeoZip Token Service tools manage the **account, identity, and recipient keys** used for timestamping and recipient encryption. They talk to the Token Service API (or report local neozip-connect readiness) and are configured via **neozip-connect** (`~/.neozip/connection/`) — they do **not** operate on ZIP archives directly.
+
+The default service URL comes from the neozip-connect profile; override per call with `options.serverUrl` where supported.
+
+---
+
+### `lookup_recipient`
+
+Look up a recipient's Token Service X25519 public key by verified email (unauthenticated `GET /crypto/public`). Does not return private keys. Use before `compress` with `options.recipientEmails` to confirm an email is provisioned.
+
+**Parameters**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `email` | `string` | Yes | Verified recipient email on the Token Service. |
+| `options` | `object` | No | Optional `serverUrl` override. |
+
+**Example**
+
+```json
+{
+  "email": "colleague@example.com"
+}
+```
+
+**Output (JSON)**
+
+Success object with `identity`, `identityType` (`zipstamp`), `evmAddress`, `recipientSuites`, and `cryptoProvisionedAt` when available.
+
+---
+
+### `token_service_status`
+
+Check whether an email is registered and verified on the NeoZip Token Service (required before timestamping).
+
+**Parameters**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `email` | `string` | No | Email to check. Defaults to neozip-connect profile email when configured. |
+| `options` | `object` | No | Token Service options (see below). |
+
+**Options**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `serverUrl` | `string` | `TOKEN_SERVICE_URL` or library default | NeoZip Token Service base URL. |
+
+**Example**
+
+```json
+{
+  "email": "user@example.com"
+}
+```
+
+**Output**
+
+Service URL, masked email, verified yes/no, and next-step hints.
+
+---
+
+### `token_service_register`
+
+Register an email and send a 6-digit verification code. Requires `blockchain` capability.
+
+**Parameters**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `email` | `string` | Yes | Email address to register or re-send verification for. |
+| `options` | `object` | No | Token Service options (see below). |
+
+**Options**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `serverUrl` | `string` | `TOKEN_SERVICE_URL` or library default | NeoZip Token Service base URL. |
+
+**Example**
+
+```json
+{
+  "email": "user@example.com"
+}
+```
+
+**Output**
+
+Confirmation that a verification email was sent; instructs user to call `token_service_verify` with the code.
+
+---
+
+### `token_service_verify`
+
+Complete email verification with the 6-digit code from the registration email. Requires `blockchain` capability.
+
+**Parameters**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `email` | `string` | Yes | Email address being verified. |
+| `code` | `string` | Yes | 6-digit verification code from email. |
+| `options` | `object` | No | Token Service options (see below). |
+
+**Options**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `serverUrl` | `string` | `TOKEN_SERVICE_URL` or library default | NeoZip Token Service base URL. |
+
+**Example**
+
+```json
+{
+  "email": "user@example.com",
+  "code": "123456"
+}
+```
+
+**Output**
+
+Verification success and reminder to run `neozip-connect verify` to store credentials, then reload MCP. Does not return or store Bearer session tokens in MCP env.
+
+---
+
+### `connect_status`
+
+Fast **neozip-connect readiness** check for agents and users. No network calls; no secret values.
+
+Call this **before** `compress` with `options.timestamp`, `options.tokenize`, or `options.recipientEmails`, or when setup errors mention neozip-connect.
+
+**Parameters**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `options` | `object` | No | Output format (see below). |
+
+**Options**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `format` | `"text"` \| `"json"` | `"text"` | Structured JSON for agents. |
+
+**Example**
+
+```json
+{
+  "options": { "format": "json" }
+}
+```
+
+**Output**
+
+- **Phase** — `no_profile`, `email_unverified`, `no_wallet`, `ready`, etc.
+- **Store** — path, connection counts, readable vs locked accounts
+- **Store health** — `ok` or `unrecoverable` (corrupt / wrong-machine credentials; reset via `neozip-connect`)
+- **compress options** — readiness for `timestamp`, `tokenize`, `recipientEmails`
+- **Tool readiness** — `stamp`, `mint`, `tokenize`
+- **Next commands** — interactive wizard (`neozip-connect`) and scriptable CLI step when different
+- **Token expiry** — flag and re-auth guidance when the access token is expired
+
+**Related:** `wallet_config_status` (credential sources), `identity_status` (Token Service `/crypto/self`).
+
+---
+
+### `wallet_config_status`
+
+Report how MCP credentials are configured: capability groups, **neozip-connect** profile phase and store path, boolean flags for optional secret env vars (never values), and **readiness** for mint, tokenize, timestamp, and recipient decrypt. No network calls.
+
+**Parameters**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `options` | `object` | No | Output format (see below). |
+
+**Options**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `format` | `"text"` \| `"json"` | `"text"` | Structured JSON for agents. |
+
+**Example**
+
+```json
+{
+  "options": { "format": "json" }
+}
+```
+
+**Output**
+
+Capabilities, wallet key source, network source, masked recipient email, Token Service URL, connection phase, secret flags, readiness (`mintReady`, `tokenizeReady`, `timestampReady`, `recipientDecryptConfigured`, `recipientDecryptUnwrapPath`), and pointers to `wallet_info` / `identity_status`.
+
+---
+
+### `identity_status`
+
+Query Token Service `GET /crypto/self` with the neozip-connect access token (Bearer). Reports provisioned X25519 identity (`walletId`, `identityKeyId`, masked public key fingerprint, `recipientSuites`) and whether recipient-encrypted archives can be opened. Does **not** unwrap or return private keys.
+
+**Parameters**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `options` | `object` | No | Server URL and output format. |
+
+**Options**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `serverUrl` | `string` | `TOKEN_SERVICE_URL` / library default | Token Service base URL. |
+| `format` | `"text"` \| `"json"` | `"text"` | Structured JSON for agents. |
+
+**Requirements**
+
+- neozip-connect access token; optional `NEOZIP_IDENTITY_PRIVATE_KEY_HEX` for decrypt readiness without calling `/crypto/self`.
+- neozip-connect wallet required for the wallet+token unwrap path when env hex is not set.
+
+**Output**
+
+Access token configured, `/crypto/self` result (or error/hint on 404), `recipientDecryptReady`, optional warning if the connect profile email does not match the Token Service account email.
+
+---
+
+## Global Limits and Configuration
+
+These settings apply across operations (not per-tool parameters):
+
+| Variable | Default | Effect |
+|----------|---------|--------|
+| `NEOZIP_MCP_SANDBOX_PATHS` | cwd, home | Allowed directories for file paths |
+| `NEOZIP_MCP_RATE_LIMIT` | `60` | ZIP tool requests per minute |
+| `NEOZIP_MCP_BLOCKCHAIN_RATE_LIMIT` | `10` | Blockchain tool requests per minute |
+| `NEOZIP_MCP_MAX_FILE_SIZE` | `524288000` (500 MB) | Maximum input file size |
+| `NEOZIP_MCP_MAX_ENTRIES` | `10000` | Maximum ZIP entries per archive |
+| `NEOZIP_MCP_TIMEOUT` | `300` | Operation timeout in seconds |
+| `NEOZIP_MCP_DEFAULT_MAX_CHARS` | `10000` | Default `maxChars` for `read_entry` |
+| `NEOZIP_MCP_MAX_READ_CHARS` | `100000` | Hard cap on characters returned by `read_entry` |
+| `NEOZIP_MCP_GREP_MAX_MATCHES` | `100` | Default max matches for `grep_entries` |
+| `NEOZIP_MCP_GREP_MAX_SNIPPET_CHARS` | `200` | Max snippet length per grep match |
+| `NEOZIP_MCP_GREP_MAX_FILE_BYTES` | `1048576` (1 MB) | Skip grepping individual entries larger than this |
+| `NEOZIP_NETWORK` | `base-sepolia` | Default blockchain network |
+| `NEOZIP_TOKEN_SERVICE_INFO_URL` | `{profile URL}/info` | Setup docs link in Token Service error messages |
+
+Token Service email, access token, wallet key, and service URL are loaded from **neozip-connect** only (`~/.neozip/connection/`).
+
+---
+
+## Typical Workflows
+
+### Timestamp a ZIP
+
+1. **compress** with `options.timestamp: true` (or `useSHA256: true` then **stamp**)
+2. **stamp** with a verified `recipientEmail`
+3. **upgrade_timestamped** after the batch is confirmed on-chain
+
+### Tokenize and verify
+
+1. **compress** with `options.timestamp: true` (or `useSHA256: true` then **stamp**)
+2. **mint** with the merkle root from **info**
+3. **verify** on the tokenized archive
+
+### Integrity check
+
+1. **list** or **info** for a quick overview
+2. **test** for full per-entry integrity verification
+
+### AI archive inspection (no full extraction)
+
+1. **info** or **list** with `options.format: "json"` for a token-aware manifest (`isTextSafe` per entry)
+2. **search_entries** to locate files by name or pattern
+3. **grep_entries** to find matching lines across file contents
+4. **read_entry** with `offset` / `maxChars` for paginated in-archive reading
+5. Optionally fetch `zip://{archive}/{entry}` MCP resources for direct client binding