neozip-mcp 0.1.0-beta

package/docs/examples/CLAUDE.md.example

@@ -0,0 +1,22 @@
+# NeoZip MCP
+
+This project uses **neozip-mcp** for ZIP and `.nzip` archive operations via MCP tools.
+
+## Agent behavior
+
+- Use **neozip-mcp** MCP tools for archive work — do not read or search for neozip-mcp source unless this repo is the neozip-mcp development repository.
+- **Archives** (create, read, extract, search, inspect): skills under `.claude/skills/neozip-mcp/` — tools `compress`, `extract`, `list`, `info`, `test`, `read_entry`, `search_entries`, `grep_entries`.
+- **Notarization / recipient encryption** (tokenize, timestamp, verify, encrypt for email): skills under `.claude/skills/neozip-notarization/` — call `connect_status` first; if not ready, tell the user to run `neozip-connect` and start a new session.
+- Use **absolute paths** under the MCP sandbox (`NEOZIP_MCP_SANDBOX_PATHS`, typically `${CLAUDE_PROJECT_DIR:-.}` and `${HOME}`).
+- Surface MCP tool errors (`Error: …`) verbatim to the user.
+
+## Setup (maintainers)
+
+Copy from the installed npm package:
+
+```bash
+cp node_modules/neozip-mcp/docs/examples/mcp.json.claude.example .mcp.json
+cp -R node_modules/neozip-mcp/docs/examples/claude/skills .claude/
+```
+
+Or merge this file from `docs/examples/CLAUDE.md.example`.

package/docs/examples/claude/skills/neozip-mcp/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: neozip-mcp
+description: >-
+  Create, read, extract, search, and inspect ZIP and .nzip archives via
+  neozip-mcp MCP tools. Use when the user mentions zip, nzip, archives, compress,
+  extract, unzip, or NeoZip; or when inspecting archive contents (listing, reading
+  one file, searching names or file bodies) without full disk extraction. For
+  blockchain timestamp/tokenize/verify or recipient encryption, use the
+  neozip-notarization skill instead.
+---
+
+# NeoZip MCP — Archives
+
+Use **neozip-mcp** MCP tools for all ZIP/.nzip work. End users install the published npm package — do not read or search for neozip-mcp source code.
+
+## Archive tools
+
+| Task | Tool |
+|------|------|
+| Create archive | `compress` |
+| Unpack to directory | `extract` |
+| List entries | `list` |
+| Metadata / merkle / blockchain status | `info` |
+| Integrity check | `test` |
+| Read one file inside archive | `read_entry` |
+| Find entries by path/name | `search_entries` |
+| Search file contents in archive | `grep_entries` |
+
+Prefer in-archive tools (`read_entry`, `grep_entries`, `search_entries`) over shell `unzip` or extracting to a temp directory.
+
+## Paths
+
+Use **absolute paths** under the configured sandbox (`NEOZIP_MCP_SANDBOX_PATHS`, typically project root and home). If a tool returns `Path is outside sandbox`, ask the user to widen sandbox paths or use a path inside the allowlist.
+
+## Passwords
+
+For encrypted archives, pass `options.password` to `extract`, `list`, `info`, `test`, `read_entry`, `search_entries`, and `grep_entries`. To create a password ZIP, set `options.password` on `compress`.
+
+## Blockchain and recipient encryption
+
+These need NeoZip Token Service / wallet setup and are covered by the **neozip-notarization** skill:
+
+- `compress` with `options.timestamp`, `options.tokenize`, or `options.recipientEmails`
+- `mint`, `verify`, `stamp`, `upgrade_timestamped`
+
+Before any of those, call `connect_status`; if it is not ready, tell the user to run `neozip-connect` in a terminal and reload MCP.
+
+## Errors
+
+Tools return `Error: …` as text content — surface that message to the user verbatim.
+
+## Reference
+
+Full parameters: `OPERATIONS.md` in the installed `neozip-mcp` package (`node_modules/neozip-mcp/docs/OPERATIONS.md`).

package/docs/examples/claude/skills/neozip-notarization/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: neozip-notarization
+description: >-
+  Blockchain timestamp, tokenize (NFT), verify, and recipient encryption for ZIP
+  and .nzip archives via neozip-mcp MCP tools. Use when the user mentions tokenize,
+  timestamp, notarize, stamp, mint, NFT, on-chain proof, blockchain verification,
+  or encrypting an archive for specific recipients by email. Requires NeoZip
+  Token Service / wallet setup via the neozip-connect CLI.
+---
+
+# NeoZip MCP — Notarization & Recipient Encryption
+
+Use **neozip-mcp** MCP tools for blockchain notarization and recipient encryption of ZIP/.nzip archives. End users install the published npm package — do not read or search for neozip-mcp source code. For plain archive create/read/extract/search, use the **neozip-mcp** (archives) skill.
+
+## Preflight — always run first
+
+Before `compress` with `options.timestamp`, `options.tokenize`, or `options.recipientEmails`, or before `mint` / `stamp`:
+
+1. Call `connect_status`.
+2. If it is not `ready`, tell the user to run **`neozip-connect`** in a terminal and reload MCP. Do not guess wallet or Token Service credentials.
+3. Surface any `Error: …` text verbatim.
+
+`mint`, `stamp`, and `verify` require the `blockchain` capability group, which is added automatically when connect is ready and capabilities are `auto`.
+
+`timestamp` and `tokenize` are **mutually exclusive** on `compress`. Prefer `tokenize: true` when a wallet is configured — tokenized archives provide on-chain proof and supersede the timestamp-only path.
+
+## Tools
+
+| Task | Tool |
+|------|------|
+| Timestamp + on-chain token at compress time | `compress` (`options.timestamp` / `options.tokenize`) |
+| Encrypt for recipients at compress time | `compress` (`options.recipientEmails`) |
+| Submit existing archive's merkle root for timestamping | `stamp` |
+| Replace pending timestamp with confirmed on-chain metadata | `upgrade_timestamped` |
+| Mint a merkle root as an NFT (Base) | `mint` |
+| Verify a tokenized archive against the blockchain | `verify` |
+| Resolve a recipient's public key by email | `lookup_recipient` |
+| Wallet / network status (address, balance) | `wallet_info` |
+| Token Service identity provisioning (decrypt readiness) | `identity_status` |
+| Credential sources + readiness (no secrets) | `wallet_config_status` |
+
+## Notarization workflows
+
+**Timestamp a ZIP**
+
+1. `connect_status` (verified email required)
+2. `compress` with `options.timestamp: true` (or `useSHA256: true` then `stamp`)
+3. `upgrade_timestamped` after the Token Service batch confirms on-chain
+
+**Tokenize and verify**
+
+1. `connect_status` (wallet required)
+2. `compress` with `options.tokenize: true` (mints the merkle root; embeds `META-INF/TOKEN.NZIP`)
+3. `verify` on the tokenized archive
+
+`mint` is the standalone path when you already have a 64-char hex merkle root (e.g. from `info`).
+
+## Recipient encryption
+
+1. `connect_status` and, for each recipient, `lookup_recipient { "email": "user@example.com" }` to confirm a provisioned public key.
+2. `compress` with `options.recipientEmails: ["a@example.com", "b@example.com"]` — embeds `META-INF/ACCESS.NZIP`.
+3. `options.recipientEmails` is **mutually exclusive** with `password`, `timestamp`, and `tokenize`. Do not combine them.
+4. To check whether the current account can open recipient-encrypted archives, use `identity_status`.
+
+## Onboarding
+
+Account setup is handled by the **`neozip-connect`** CLI (email verification, wallet, identity), not by MCP tools. When `connect_status` is not ready, instruct the user to run `neozip-connect` and reload MCP. Credentials live in `~/.neozip/connection/`; never request or echo secrets.
+
+## Errors
+
+Tools return `Error: …` as text content — surface that message to the user verbatim.
+
+## Reference
+
+Full parameters: `OPERATIONS.md` in the installed `neozip-mcp` package — see the "Blockchain Operations" and "NeoZip Token Service" sections (`node_modules/neozip-mcp/docs/OPERATIONS.md`).

package/docs/examples/mcp.json.claude.example

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "neozip-mcp": {
+      "type": "stdio",
+      "command": "neozip-mcp",
+      "env": {
+        "NEOZIP_MCP_SANDBOX_PATHS": "${CLAUDE_PROJECT_DIR:-.},${HOME}"
+      }
+    }
+  }
+}

package/docs/examples/neozip-mcp-cursor-rule.mdc

@@ -0,0 +1,31 @@
+---
+description: Use neozip-mcp MCP tools for ZIP archives; do not read neozip-mcp source
+alwaysApply: true
+---
+
+# NeoZip ZIP operations
+
+For create, read, extract, search, or inspect ZIP/.nzip archives, use **neozip-mcp** MCP tools only:
+
+- `compress` — create archives
+- `extract` — unpack to a directory
+- `list` — entry names (text or JSON)
+- `info` — metadata, merkle root, blockchain status
+- `test` — integrity check
+- `read_entry` — read one file inside an archive
+- `search_entries` — find entries by name/path pattern
+- `grep_entries` — search file contents inside an archive
+
+Do **not** read, search, or assume access to neozip-mcp source code. End users install the published npm package only.
+
+**Paths:** use absolute paths under the configured sandbox (`NEOZIP_MCP_SANDBOX_PATHS`, typically the workspace and home directory).
+
+**Blockchain options** (`compress` with `options.tokenize`, `options.timestamp`, or `options.recipientEmails`):
+
+1. Call `connect_status` first.
+2. If not ready, tell the user to run `neozip-connect` in a terminal and reload MCP.
+3. Do not guess wallet or Token Service credentials.
+
+**Diagnostics:** `connect_status`, `wallet_config_status` — no secrets returned.
+
+**Errors:** tools return `Error: …` text; surface that message to the user.

package/docs/installation-guides/INSTALL_CLAUDE_CODE.md

@@ -0,0 +1,286 @@
+# Install NeoZip MCP in Claude Code
+
+Use **neozip-mcp** with [Claude Code](https://code.claude.com/) (terminal agent). Claude Code spawns the `neozip-mcp` stdio server; the agent calls MCP tools (`compress`, `list`, `info`, …). No neozip-mcp source checkout is required.
+
+**Related:** [INSTALL_CLAUDE_WORKSPACE.md](./INSTALL_CLAUDE_WORKSPACE.md) (team `.mcp.json`), [OPERATIONS.md](../OPERATIONS.md) (tools), [NEOZIP_CONNECT_CLI.md](../NEOZIP_CONNECT_CLI.md) (account setup).
+
+---
+
+## Prerequisites
+
+1. **Node.js 20+** — [nodejs.org](https://nodejs.org/)
+2. **Claude Code** installed and authenticated
+3. Open Claude Code **inside the project directory** you want to work in (recommended for correct sandbox scope)
+4. **Optional:** [neozip-connect](../NEOZIP_CONNECT_CLI.md) account — only for tokenize, timestamp, recipient encryption, mint, and stamp
+
+Plain ZIP operations (`compress` without blockchain options) do **not** require `neozip-connect`.
+
+---
+
+## 1. Install neozip-mcp (beta)
+
+Run in your **system terminal** (not inside a Claude Code session):
+
+```bash
+npm install -g neozip-mcp@beta
+```
+
+This installs:
+
+| Command | Purpose |
+|---------|---------|
+| `neozip-mcp` | MCP server (Claude Code spawns this) |
+| `neozip-connect` | Interactive account setup |
+
+Verify:
+
+```bash
+which neozip-mcp
+which neozip-connect
+neozip-connect status
+```
+
+---
+
+## 2. Choose a configuration scope
+
+Claude Code stores MCP servers at three scopes. Pick one:
+
+| Scope | Stored in | Who gets it | Best for |
+|-------|-----------|-------------|----------|
+| **User** | `~/.claude.json` (top-level `mcpServers`) | You, all projects | Personal default on every machine |
+| **Local** | `~/.claude.json` (under this project path) | You, this project only | Private experiments |
+| **Project** | `.mcp.json` in repo root | Everyone who clones the repo | Team workspace — see [INSTALL_CLAUDE_WORKSPACE.md](./INSTALL_CLAUDE_WORKSPACE.md) |
+
+When the same server name exists in multiple scopes, **local** wins over **project**, which wins over **user**.
+
+---
+
+## 3. User scope (recommended for individuals)
+
+Available in **every project** on your machine. Good default when you use NeoZip across many repos.
+
+### Option A — CLI (Claude Code 2.1.1+)
+
+Run in your **system terminal** from any directory:
+
+```bash
+claude mcp add-json neozip-mcp \
+  '{"type":"stdio","command":"neozip-mcp","env":{"NEOZIP_MCP_SANDBOX_PATHS":"${CLAUDE_PROJECT_DIR:-.},${HOME}"}}' \
+  --scope user
+```
+
+Capabilities default to **`auto`**: blockchain tools appear after `neozip-connect` reaches `phase: ready` and you reload MCP. Pin `NEOZIP_MCP_CAPABILITIES` in `env` to override (see [Capability presets](#capability-presets) below).
+
+### Option B — Edit `~/.claude.json`
+
+Add or merge this block under the top-level `mcpServers` key:
+
+```json
+{
+  "mcpServers": {
+    "neozip-mcp": {
+      "type": "stdio",
+      "command": "neozip-mcp",
+      "env": {
+        "NEOZIP_MCP_SANDBOX_PATHS": "${CLAUDE_PROJECT_DIR:-.},${HOME}"
+      }
+    }
+  }
+}
+```
+
+Copy from: [`docs/examples/mcp.json.claude.example`](../examples/mcp.json.claude.example) (same JSON works for user and project scope; merge into `~/.claude.json` here, or copy to `.mcp.json` for workspace scope).
+
+> **Note:** `~/.claude.json` also stores per-project state. For user-scoped MCP, put `mcpServers` at the **top level**, not nested under a project path. Using `claude mcp add --scope user` avoids editing the file by hand.
+
+---
+
+## 4. Local scope (this project only)
+
+Private to you for the current project. Stored in `~/.claude.json` under that project's entry.
+
+```bash
+cd /path/to/your/project
+
+claude mcp add-json neozip-mcp \
+  '{"type":"stdio","command":"neozip-mcp","env":{"NEOZIP_MCP_SANDBOX_PATHS":"${CLAUDE_PROJECT_DIR:-.},${HOME}"}}' \
+  --scope local
+```
+
+`--scope local` is the default if you omit `--scope`.
+
+---
+
+## 5. One-time account setup (optional)
+
+For **tokenize**, **timestamp**, **recipient encryption**, **mint**, or **stamp**:
+
+```bash
+neozip-connect
+```
+
+Complete the wizard (Token Service URL → email → verification code → wallet). Secrets are saved to `~/.neozip/connection/` with machine-local encryption — **do not** put wallet or Token Service tokens in MCP config.
+
+Then start a **new** Claude Code session in your project.
+
+---
+
+## 6. Verify installation
+
+In your system terminal:
+
+```bash
+claude mcp list
+claude mcp get neozip-mcp
+```
+
+Start Claude Code in your project:
+
+```bash
+cd /path/to/your/project
+claude
+```
+
+Inside Claude Code:
+
+- Run `/mcp` to inspect connected servers and tools
+- Confirm **neozip-mcp** appears with tools such as `compress`, `list`, `info`
+
+**Smoke test prompts:**
+
+- "List entries in `/path/to/archive.nzip`" → should call `list`
+- "Is neozip-connect ready for tokenize?" → should call `connect_status`
+
+---
+
+## Configuration reference
+
+### Capability presets
+
+| Use case | `NEOZIP_MCP_CAPABILITIES` |
+|----------|---------------------------|
+| Default (recommended) | omit or `auto` |
+| ZIP only | `zip` |
+| ZIP + read-only verify | `zip,readonly` |
+| Always expose blockchain | `zip,blockchain,readonly` |
+| Strict startup gate | add `account` and `"NEOZIP_MCP_REQUIRE_ACCOUNT": "true"` |
+
+### Sandbox paths
+
+`NEOZIP_MCP_SANDBOX_PATHS` limits which paths tools may touch. Recommended for Claude Code:
+
+```json
+"NEOZIP_MCP_SANDBOX_PATHS": "${CLAUDE_PROJECT_DIR:-.},${HOME}"
+```
+
+- `${CLAUDE_PROJECT_DIR:-.}` — project root where Claude Code was launched
+- `${HOME}` — archives under your home directory
+
+For a fixed allowlist, use absolute paths:
+
+```json
+"NEOZIP_MCP_SANDBOX_PATHS": "/Users/you/projects,/Users/you/archives"
+```
+
+### Optional environment variables
+
+| Variable | Purpose |
+|----------|---------|
+| `NEOZIP_MCP_REQUIRE_ACCOUNT` | `"true"` — exit at startup until `neozip-connect` is `phase: ready` |
+| `NEOZIP_UNLOCK_PASSPHRASE` | Custom passphrase for `~/.neozip/connection/` (if not using machine-local default) |
+| `NEOZIP_MCP_STARTUP_SUMMARY` | Log account summary to stderr on start (default: on) |
+
+Token Service URL, access token, and wallet key come from **neozip-connect** only — not from MCP env.
+
+Full list: [README.md](../../README.md#configuration) and [OPERATIONS.md](../OPERATIONS.md).
+
+---
+
+## Agent instructions (recommended)
+
+Claude Code loads skills from `.claude/skills/` (project, committable) or `~/.claude/skills/` (personal, all projects). Skills auto-invoke when your prompt matches their description, or invoke directly with `/neozip-mcp` and `/neozip-notarization`.
+
+### Personal skills (all projects)
+
+After `npm install -g`, copy once per machine:
+
+```bash
+pkg="$(npm root -g)/neozip-mcp"
+mkdir -p ~/.claude/skills/neozip-mcp ~/.claude/skills/neozip-notarization
+cp "$pkg/docs/examples/claude/skills/neozip-mcp/SKILL.md" ~/.claude/skills/neozip-mcp/
+cp "$pkg/docs/examples/claude/skills/neozip-notarization/SKILL.md" ~/.claude/skills/neozip-notarization/
+```
+
+If installed to `~/.local`:
+
+```bash
+pkg=~/.local/lib/node_modules/neozip-mcp
+mkdir -p ~/.claude/skills/neozip-mcp ~/.claude/skills/neozip-notarization
+cp "$pkg/docs/examples/claude/skills/neozip-mcp/SKILL.md" ~/.claude/skills/neozip-mcp/
+cp "$pkg/docs/examples/claude/skills/neozip-notarization/SKILL.md" ~/.claude/skills/neozip-notarization/
+```
+
+| Skill | Purpose |
+|-------|---------|
+| `neozip-mcp` | Archives — compress, extract, list, info, test, read_entry, search_entries, grep_entries |
+| `neozip-notarization` | Tokenize, timestamp, verify, stamp, mint, recipient encryption |
+
+Source: [`docs/examples/claude/skills/`](../examples/claude/skills/)
+
+### Project memory (optional)
+
+For always-on instructions in every session, copy or merge [`docs/examples/CLAUDE.md.example`](../examples/CLAUDE.md.example) into your repo's `CLAUDE.md`. For team workspaces, prefer committing `.claude/skills/` instead — see [INSTALL_CLAUDE_WORKSPACE.md](./INSTALL_CLAUDE_WORKSPACE.md).
+
+### Cursor (optional)
+
+Copy the same skill files to `~/.cursor/skills/`:
+
+```bash
+pkg="$(npm root -g)/neozip-mcp"
+mkdir -p ~/.cursor/skills/neozip-mcp ~/.cursor/skills/neozip-notarization
+cp "$pkg/docs/examples/claude/skills/neozip-mcp/SKILL.md" ~/.cursor/skills/neozip-mcp/
+cp "$pkg/docs/examples/claude/skills/neozip-notarization/SKILL.md" ~/.cursor/skills/neozip-notarization/
+```
+
+Always-on Cursor rule (alternative): [`docs/examples/neozip-mcp-cursor-rule.mdc`](../examples/neozip-mcp-cursor-rule.mdc).
+
+---
+
+## Troubleshooting
+
+| Symptom | What to do |
+|---------|------------|
+| `neozip-mcp`: command not found | Re-run `npm install -g neozip-mcp@beta`; ensure npm global bin is on `PATH` |
+| Server not in `claude mcp list` | Re-run `claude mcp add-json …` with correct `--scope`; validate JSON |
+| Tools not appearing | New Claude Code session; run `/mcp`; check stderr from manual `neozip-mcp` |
+| `Path is outside sandbox` | Add directory to `NEOZIP_MCP_SANDBOX_PATHS` |
+| Tokenize / wallet errors | Run `neozip-connect`; new session; ask agent to run `connect_status` |
+| `mint` / `stamp` missing | Run `neozip-connect`, reload MCP (default `auto` adds blockchain when ready), or set `NEOZIP_MCP_CAPABILITIES=zip,blockchain,readonly` |
+| Duplicate server warnings | Same name in user + project scopes — remove one: `claude mcp remove neozip-mcp` |
+
+### Remove and re-add
+
+```bash
+claude mcp remove neozip-mcp --scope user
+# or --scope local / --scope project
+```
+
+Then repeat setup from section 3 or 4.
+
+### Logs
+
+- Inside Claude Code: `/mcp`
+- Manual server test: run `neozip-mcp` in a terminal; logs go to stderr with `[neozip-mcp]` prefix
+
+---
+
+## Team projects
+
+To share MCP config with teammates via git, use **project scope** and a committed `.mcp.json`. See [INSTALL_CLAUDE_WORKSPACE.md](./INSTALL_CLAUDE_WORKSPACE.md).
+
+---
+
+## Repo developers
+
+Contributors building neozip-mcp from source use the repo launcher — not covered in this guide.