neozip-mcp 0.1.0-beta

package/docs/installation-guides/INSTALL_CLAUDE_WORKSPACE.md

@@ -0,0 +1,301 @@
+# Install NeoZip MCP in a Claude Code workspace
+
+Share **neozip-mcp** with your team by committing a **project-scoped** `.mcp.json` at the repository root. Anyone who clones the repo and opens it in Claude Code gets the same MCP server definition after approval.
+
+**Related:** [INSTALL_CLAUDE_CODE.md](./INSTALL_CLAUDE_CODE.md) (user/local scope), [OPERATIONS.md](../OPERATIONS.md) (tools), [NEOZIP_CONNECT_CLI.md](../NEOZIP_CONNECT_CLI.md) (account setup).
+
+---
+
+## What is a Claude Code workspace config?
+
+Claude Code reads MCP servers from several locations. **Project scope** uses:
+
+```
+your-repo/
+├── .mcp.json                    ← shared MCP config (commit to git)
+├── CLAUDE.md                    ← optional always-on memory (recommended)
+├── .claude/
+│   └── skills/
+│       ├── neozip-mcp/          ← archive tools skill (commit to git)
+│       └── neozip-notarization/ ← tokenize/timestamp/verify skill (commit to git)
+└── …
+```
+
+| Scope | File | Commit to git? |
+|-------|------|----------------|
+| **Project** | `.mcp.json` | **Yes** — team shares the same server definition |
+| User | `~/.claude.json` (top-level) | No — personal, all projects |
+| Local | `~/.claude.json` (project entry) | No — personal, one project |
+
+Claude Code **merges** scopes by server name; **local** overrides **project**, which overrides **user**.
+
+---
+
+## Prerequisites
+
+1. **Node.js 20+** on each developer machine
+2. **Claude Code** installed
+3. Each teammate installs the beta package from npm once:
+
+   ```bash
+   npm install -g neozip-mcp@beta
+   ```
+
+4. **Optional:** each developer runs `neozip-connect` for blockchain features (credentials stay on each machine in `~/.neozip/connection/`)
+
+---
+
+## Quick setup (maintainer)
+
+### 1. Add `.mcp.json` to the repo
+
+Copy the example and adjust capabilities/sandbox if needed:
+
+```bash
+cp node_modules/neozip-mcp/docs/examples/mcp.json.claude.example .mcp.json
+```
+
+From a neozip-mcp source checkout:
+
+```bash
+cp docs/examples/mcp.json.claude.example .mcp.json
+```
+
+**Default workspace config** (capabilities default to `auto`):
+
+```json
+{
+  "mcpServers": {
+    "neozip-mcp": {
+      "type": "stdio",
+      "command": "neozip-mcp",
+      "env": {
+        "NEOZIP_MCP_SANDBOX_PATHS": "${CLAUDE_PROJECT_DIR:-.},${HOME}"
+      }
+    }
+  }
+}
+```
+
+After `neozip-connect` reaches `phase: ready`, reload MCP so blockchain tools appear. Pin capabilities explicitly if needed (see [installation-guides/README.md](./README.md#capability-presets)).
+
+### 2. Add agent skills (recommended)
+
+Copy project skills from the npm package so Claude auto-invokes the right procedures. Commit `.claude/skills/` so every teammate gets the same agent behavior.
+
+```bash
+cp -R node_modules/neozip-mcp/docs/examples/claude/skills .claude/
+```
+
+From a neozip-mcp source checkout:
+
+```bash
+cp -R docs/examples/claude/skills .claude/
+```
+
+| 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 — call `connect_status` first |
+
+Optional always-on project memory — copy or merge [`docs/examples/CLAUDE.md.example`](../examples/CLAUDE.md.example) to `CLAUDE.md`:
+
+```bash
+cp node_modules/neozip-mcp/docs/examples/CLAUDE.md.example CLAUDE.md
+# or merge the NeoZip section into an existing CLAUDE.md
+```
+
+**Cursor teammates (optional)** — same skill content, personal install:
+
+```bash
+mkdir -p ~/.cursor/skills/neozip-mcp ~/.cursor/skills/neozip-notarization
+cp node_modules/neozip-mcp/docs/examples/claude/skills/neozip-mcp/SKILL.md ~/.cursor/skills/neozip-mcp/
+cp node_modules/neozip-mcp/docs/examples/claude/skills/neozip-notarization/SKILL.md ~/.cursor/skills/neozip-notarization/
+```
+
+### 3. Commit and push
+
+```bash
+git add .mcp.json .claude/skills CLAUDE.md
+git commit -m "Add NeoZip MCP workspace config for Claude Code"
+git push
+```
+
+`.mcp.json` and `.claude/skills/` are **meant to be committed**. `CLAUDE.md` is optional. Do not add secrets to any of these files (see [Secrets](#secrets-and-credentials) below).
+
+---
+
+## Alternative: CLI project scope
+
+From the repo root, in your **system terminal**:
+
+```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 project
+```
+
+Claude Code creates or updates `.mcp.json` automatically. Review the file, then commit it.
+
+---
+
+## Teammate onboarding
+
+Each developer:
+
+1. **Clone** the repository
+2. **Install** the global binary (once per machine):
+
+   ```bash
+   npm install -g neozip-mcp@beta
+   which neozip-mcp
+   ```
+
+3. **Open Claude Code** in the project root:
+
+   ```bash
+   cd your-repo
+   claude
+   ```
+
+4. **Approve project MCP servers** when prompted (security review of `.mcp.json`)
+
+5. **Optional — blockchain:** run `neozip-connect` once, then start a new Claude Code session
+
+6. **Verify:**
+
+   ```bash
+   claude mcp list
+   ```
+
+   Inside Claude Code: `/mcp` → confirm **neozip-mcp** tools are listed
+
+---
+
+## Secrets and credentials
+
+NeoZip uses a **connect-only** credential model for production use:
+
+| Secret | Where it lives | Commit to git? |
+|--------|----------------|----------------|
+| Wallet / Token Service tokens | `~/.neozip/connection/` via `neozip-connect` | **Never** |
+| MCP capabilities / sandbox | `.mcp.json` | **Yes** |
+| Custom unlock passphrase | Per-user `~/.claude.json` merge (optional) | **Never** |
+
+### Splitting config (optional pattern)
+
+Commit **server definition** in `.mcp.json`. Teammates can merge **personal env** in `~/.claude.json` under the same server name:
+
+**.mcp.json** (committed):
+
+```json
+{
+  "mcpServers": {
+    "neozip-mcp": {
+      "type": "stdio",
+      "command": "neozip-mcp",
+      "env": {
+        "NEOZIP_MCP_SANDBOX_PATHS": "${CLAUDE_PROJECT_DIR:-.},${HOME}"
+      }
+    }
+  }
+}
+```
+
+**~/.claude.json** (personal, not committed):
+
+```json
+{
+  "mcpServers": {
+    "neozip-mcp": {
+      "env": {
+        "NEOZIP_UNLOCK_PASSPHRASE": "your-custom-passphrase-if-used"
+      }
+    }
+  }
+}
+```
+
+Server names must match exactly. Claude Code merges env at session start.
+
+> **Do not** put `NEOZIP_TOKEN_SERVICE_ACCESS_TOKEN`, wallet private keys, or API secrets in `.mcp.json`. Use `neozip-connect` instead.
+
+---
+
+## Sandbox paths for monorepos
+
+Default `${CLAUDE_PROJECT_DIR:-.},${HOME}` allows the repo root and home directory.
+
+**Archive output outside the repo:**
+
+```json
+"NEOZIP_MCP_SANDBOX_PATHS": "${CLAUDE_PROJECT_DIR:-.},${HOME},/shared/archives"
+```
+
+**Restrict to repo only:**
+
+```json
+"NEOZIP_MCP_SANDBOX_PATHS": "${CLAUDE_PROJECT_DIR:-.}"
+```
+
+---
+
+## Project approval and security
+
+Claude Code prompts before running project-scoped servers from `.mcp.json` (they execute commands on your machine). Teammates should read `.mcp.json` before approving.
+
+Reset approval choices:
+
+```bash
+claude mcp reset-project-choices
+```
+
+Pending servers show as `⏸ Pending approval` in `claude mcp list`.
+
+---
+
+## Example team workflow
+
+1. Maintainer adds `.mcp.json`, `.claude/skills/`, and optionally `CLAUDE.md`
+2. Developer clones, runs `npm install -g neozip-mcp@beta`, then `claude` in repo root
+3. Developer approves **neozip-mcp** when prompted
+4. In chat: "Zip the `docs/` folder to `dist/docs.nzip`" → agent calls `compress`
+5. For tokenized archives: developer runs `neozip-connect` once; agent calls `connect_status` then `compress` with `options.tokenize: true`
+
+More example prompts: see [docs/examples/claude/skills/neozip-mcp/SKILL.md](../examples/claude/skills/neozip-mcp/SKILL.md) (archives) and [docs/examples/claude/skills/neozip-notarization/SKILL.md](../examples/claude/skills/neozip-notarization/SKILL.md) (notarization + recipient encryption).
+
+---
+
+## Troubleshooting
+
+| Symptom | What to do |
+|---------|------------|
+| `.mcp.json` ignored | Start Claude Code from repo root; check file name and JSON syntax |
+| Pending approval forever | Run interactively once to approve; or `claude mcp reset-project-choices` |
+| Works for maintainer, not teammate | Teammate needs `npm install -g neozip-mcp@beta` and `which neozip-mcp` on PATH |
+| Sandbox errors on CI paths | Add paths to `NEOZIP_MCP_SANDBOX_PATHS` |
+| Tokenize fails for everyone | Each user needs their own `neozip-connect` profile on their machine |
+| Conflicts with personal config | Check `claude mcp list`; remove duplicate: `claude mcp remove neozip-mcp --scope user` |
+
+---
+
+## Related files in the npm package
+
+After install, examples ship under the package directory:
+
+```bash
+npm root -g
+# e.g. …/node_modules/neozip-mcp/docs/examples/mcp.json.claude.example
+# e.g. …/node_modules/neozip-mcp/docs/examples/claude/skills/
+# e.g. …/node_modules/neozip-mcp/docs/examples/CLAUDE.md.example
+```
+
+See [OPERATIONS.md](../OPERATIONS.md) and the package README for full reference.
+
+---
+
+## Related
+
+The neozip-mcp **development** repository uses different launcher config. Consumer installs use the `neozip-mcp` binary from the npm package only.

package/docs/installation-guides/README.md

@@ -0,0 +1,76 @@
+# NeoZip MCP — installation guides
+
+Step-by-step setup for **neozip-mcp** (**beta**) in common MCP host applications. NeoZip MCP is a **local stdio server** (no remote HTTP endpoint). Install the npm beta package once, then point your host at the `neozip-mcp` binary.
+
+## Guides by host
+
+| Host | Guide | Config location |
+|------|-------|-----------------|
+| **Claude Code** (CLI, user/local scope) | [INSTALL_CLAUDE_CODE.md](./INSTALL_CLAUDE_CODE.md) | `~/.claude.json`, `~/.claude/skills/` |
+| **Claude Code workspace** (shared project `.mcp.json`) | [INSTALL_CLAUDE_WORKSPACE.md](./INSTALL_CLAUDE_WORKSPACE.md) | `.mcp.json`, `.claude/skills/`, `CLAUDE.md` |
+| **Cursor** | [package README](../README.md#cursor-setup) | `~/.cursor/mcp.json` or `.cursor/mcp.json` |
+
+## Before you configure MCP
+
+1. **Install the beta package** (Node.js 20+) from npm:
+
+   ```bash
+   npm install -g neozip-mcp@beta
+   ```
+
+2. **Verify binaries**:
+
+   ```bash
+   which neozip-mcp
+   which neozip-connect
+   neozip-connect status
+   ```
+
+3. **Optional account setup** — required only for tokenize, timestamp, recipient encryption, mint, and stamp:
+
+   ```bash
+   neozip-connect
+   ```
+
+   Credentials are stored in `~/.neozip/connection/` (machine-local encryption). They are **not** passed through MCP config env vars.
+
+## Shared configuration reference
+
+Example JSON blocks live in:
+
+- [`.cursor/mcp.json.global.example`](../../.cursor/mcp.json.global.example) — Cursor global MCP
+- [`docs/examples/mcp.json.claude.example`](../examples/mcp.json.claude.example) — Claude Code (user scope: merge into `~/.claude.json`; project scope: copy to `.mcp.json`)
+- [`docs/examples/claude/skills/neozip-mcp/`](../examples/claude/skills/neozip-mcp/) — Agent skill for archives (Claude: `~/.claude/skills/` or commit `.claude/skills/`; Cursor: `~/.cursor/skills/`)
+- [`docs/examples/claude/skills/neozip-notarization/`](../examples/claude/skills/neozip-notarization/) — Agent skill for tokenize/timestamp/verify + recipient encryption
+- [`docs/examples/CLAUDE.md.example`](../examples/CLAUDE.md.example) — Optional always-on Claude project memory
+- [`docs/examples/neozip-mcp-cursor-rule.mdc`](../examples/neozip-mcp-cursor-rule.mdc) — Cursor rule (always-on alternative to skills)
+
+### Capability presets
+
+Default: **`auto`** (omit `NEOZIP_MCP_CAPABILITIES` or set to `auto`). Resolves to `zip,blockchain,readonly` when `neozip-connect` is `phase: ready`; otherwise `zip,readonly`. Reload MCP after connect finishes.
+
+| Use case | `NEOZIP_MCP_CAPABILITIES` |
+|----------|---------------------------|
+| Default (recommended) | omit or `auto` |
+| ZIP only (no verify/stamp tools) | `zip` |
+| ZIP + read-only verify, no blockchain until ready | `zip,readonly` |
+| Always expose blockchain (startup gate if not ready) | `zip,blockchain,readonly` |
+| Strict startup until account ready | add `account` and `NEOZIP_MCP_REQUIRE_ACCOUNT=true` |
+
+### Sandbox
+
+`NEOZIP_MCP_SANDBOX_PATHS` is a comma-separated allowlist of directories tools may read/write. Use your project root plus home (or specific folders) so archives under the workspace and `~/` are allowed.
+
+Full tool reference: [OPERATIONS.md](../OPERATIONS.md).
+
+Connect CLI reference: [NEOZIP_CONNECT_CLI.md](../NEOZIP_CONNECT_CLI.md).
+
+## Troubleshooting (all hosts)
+
+| Symptom | What to check |
+|---------|----------------|
+| MCP server fails to start | `which neozip-mcp`; Node 20+; run `neozip-mcp` manually and read stderr (`[neozip-mcp]` prefix) |
+| `Path is outside sandbox` | Add the directory to `NEOZIP_MCP_SANDBOX_PATHS` |
+| Tokenize / wallet errors | Run `neozip-connect`, finish wizard, restart MCP session; ask agent to call `connect_status` |
+| Blockchain tools missing | Run `neozip-connect`, finish wizard, **reload MCP** (auto adds `blockchain` when ready). Or set `NEOZIP_MCP_CAPABILITIES=zip,blockchain,readonly` explicitly |
+| Stale connect profile | Run `neozip-connect` — wizard offers reset at startup |

package/package.json

@@ -0,0 +1,99 @@
+{
+  "name": "neozip-mcp",
+  "version": "0.1.0-beta",
+  "release_date": "2026-06-27",
+  "description": "NeoZip MCP server for ZIP archives, blockchain notarization, and AI agent integration (Beta)",
+  "main": "dist/index.js",
+  "bin": {
+    "neozip-connect": "dist/connect-cli.js",
+    "neozip-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "DOCUMENTATION.md",
+    "SECURITY.md",
+    ".cursor/mcp.json.global.example",
+    "docs"
+  ],
+  "preferGlobal": true,
+  "scripts": {
+    "start": "tsx src/index.ts",
+    "connect": "tsx src/connect-cli.ts",
+    "connect:reset": "bash scripts/connect-reset.sh",
+    "init": "bash scripts/mcp-init.sh",
+    "build": "tsc && node scripts/bundle-neozipkit-pro.mjs && node scripts/add-shebang.js && chmod +x dist/index.js dist/connect-cli.js",
+    "prepack": "pnpm run build && node scripts/verify-pack-leaks.mjs && node scripts/prune-dist-pack.mjs",
+    "postpack": "pnpm run build",
+    "pack:local": "pnpm pack",
+    "pack:dry-run": "npm publish --access public --dry-run",
+    "publish:dry-run": "npm publish --access public --dry-run",
+    "prepublishOnly": "pnpm test && node scripts/verify-pack-leaks.mjs",
+    "test": "pnpm run build && node --test dist/config/capabilities.test.js dist/archive/archive.test.js dist/archive/encryption.test.js dist/archive/encryption.integration.test.js dist/archive/recipient-lookup.test.js dist/archive/recipient.integration.test.js dist/archive/crypto-self.test.js dist/archive/grep-content.test.js dist/archive/timestamp-network.test.js dist/tools/wallet-config-status.test.js dist/tools/connect-status.test.js dist/tools/identity-status.test.js dist/util/mask.test.js dist/util/token-service-fetch.test.js dist/token-service/require-configured.test.js dist/connection/credentials.test.js dist/connection/setup-guidance.test.js dist/connection/incomplete-setup.test.js dist/account/profile-store.test.js dist/account/account-state.test.js dist/startup-account-gate.test.js dist/connection/origin.test.js dist/connection/store.test.js dist/connection/migrate.test.js dist/connection/desktop-parity.test.js dist/connection/phone.test.js dist/connection/wallet-setup.test.js dist/connection/onboarding.test.js dist/connection/onboarding-phone.test.js dist/connection/onboarding-wallet.test.js dist/connection/onboarding-cli-polish.test.js dist/connection/magic-link.test.js dist/connection/phase.test.js dist/connection/token-auth.test.js dist/connection/interactive.test.js dist/connection/dump.test.js dist/connection/promote-active.test.js dist/connection/reset.test.js",
+    "test:fixtures:build": "tsx test/scripts/build-archive.ts",
+    "test:fixtures:build-blockchain": "tsx test/scripts/build-blockchain-archives.ts",
+    "test:fixtures:smoke": "tsx test/scripts/smoke.ts",
+    "test:fixtures:smoke-blockchain": "tsx test/scripts/smoke-blockchain.ts",
+    "test:fixtures": "pnpm run test:fixtures:build && pnpm run test:fixtures:smoke",
+    "test:fixtures:blockchain": "pnpm run test:fixtures:build-blockchain && pnpm run test:fixtures:smoke-blockchain",
+    "deps": "node scripts/deps.mjs"
+  },
+  "dependencies": {
+    "dotenv": "^16.4.0",
+    "ethers": "^6.0.0",
+    "fastmcp": "^4.3.2",
+    "minimatch": "^10.0.3",
+    "neozip-blockchain": "^0.7.2",
+    "neozipkit": "^0.7.2",
+    "zod": "^3.23.0"
+  },
+  "overrides": {
+    "@modelcontextprotocol/sdk": "1.21.2"
+  },
+  "devDependencies": {
+    "@neowareinc/neozipkit-pro": "^0.1.1",
+    "@types/node": "^22.13.11",
+    "esbuild": "^0.25.0",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2"
+  },
+  "pnpm": {
+    "overrides": {
+      "@modelcontextprotocol/sdk": "1.21.2"
+    }
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "zip",
+    "compression",
+    "neozip",
+    "blockchain",
+    "tokenization",
+    "archive",
+    "encryption",
+    "neozipkit",
+    "claude",
+    "cursor"
+  ],
+  "author": "NeoWare",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NeoWareInc/neozip-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/NeoWareInc/neozip-support/issues"
+  },
+  "homepage": "https://github.com/NeoWareInc/neozip-mcp#readme",
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "type": "module",
+  "packageManager": "pnpm@10.12.1"
+}