@papervault/mcp 0.1.0 → 0.1.1

package/README.md

@@ -16,37 +16,48 @@ An agent is about to do something it can't undo. Before it does, it asks PaperVa
 
 ## 🚀 Quick Start
 
+### Claude Code (one command)
+
 ```bash
-npm install -g @papervault/mcp
+claude mcp add -s user papervault -- npx -y @papervault/mcp
+claude mcp list   # confirm it's registered
 ```
 
-Add to your MCP client config. For **Claude Code** (`~/.claude/claude_code_config.json` or project `.claude/`):
+`-s user` makes the server available across all your projects. Drop the flag for current-project-only. Start a new Claude Code conversation to use it.
+
+### Other MCP clients (Cursor, Claude Desktop, manual config)
+
+The server runs over stdio, so any MCP client works. Add this to the client's MCP config file:
 
 ```json
 {
   "mcpServers": {
     "papervault": {
-      "command": "papervault-mcp"
+      "command": "npx",
+      "args": ["-y", "@papervault/mcp"]
     }
   }
 }
 ```
 
-For **Cursor** / **Claude Desktop**: same shape, check your client's docs for the config path.
+For faster startup on each call (skips the `npx` lookup), install globally and use the binary directly:
 
-If you'd rather not install globally:
+```bash
+npm install -g @papervault/mcp
+```
 
 ```json
 {
   "mcpServers": {
     "papervault": {
-      "command": "npx",
-      "args": ["-y", "@papervault/mcp"]
+      "command": "papervault-mcp"
     }
   }
 }
 ```
 
+Restart the client to load the new server.
+
 Requires Node.js ≥ 24.
 
 ## 🔑 Tools Advertised

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@papervault/mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "MCP server for PaperVault. Lets AI agents trigger paper-based secret backups as a safety step before sensitive operations — agents never see secret values.",
   "type": "module",
   "bin": {
@@ -46,7 +46,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.4",
-    "@papervault/cli": "^0.1.0",
-    "@papervault/core": "^0.1.0"
+    "@papervault/cli": "^0.1.1",
+    "@papervault/core": "^0.1.1"
   }
 }

package/src/tools.js

@@ -11,7 +11,7 @@ import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { createHash } from 'node:crypto';
 
-import { createKit } from '@papervault/core';
+import { createKit, LIMITS } from '@papervault/core';
 import { resolveSource, SUPPORTED_SOURCES } from '@papervault/cli/sources';
 import { audit } from '@papervault/cli/audit';
 
@@ -21,6 +21,21 @@ import {
     makeGlobFilter,
 } from './safety.js';
 
+// Rough per-secret value-length guess. Conservative; real values vary
+// widely (passwords ~16, BIP39 seeds ~100+, JWTs >150). Used only to give
+// agents a "will this fit?" signal in dry_run before they fetch values.
+const TYPICAL_VALUE_CHAR_GUESS = 60;
+
+function estimateChars(refs) {
+    const lower = refs.reduce((sum, r) => sum + (r.name?.length ?? 0), 0);
+    return {
+        lower_bound: lower,
+        rough_estimate: lower + refs.length * TYPICAL_VALUE_CHAR_GUESS,
+        max_allowed: LIMITS.MAX_STORAGE,
+        note: `lower_bound is exact (sum of secret-name lengths). rough_estimate adds ~${TYPICAL_VALUE_CHAR_GUESS} chars per secret as a value-length guess. Actual count is only known after fetch; backup will refuse if over max_allowed.`,
+    };
+}
+
 /** Helper: wrap structured data in MCP's content-array format. */
 function ok(data) {
     return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
@@ -212,8 +227,10 @@ export async function handleDryRun(args) {
             secret_count: selectedRefs.length,
             name_fingerprint: fp,
             kinds_summary: summarizeKinds(selectedRefs),
+            char_estimate: estimateChars(selectedRefs),
             note: 'Run papervault_backup_from_source with the same source_uri and select to commit. ' +
-                'Compare name_fingerprint between runs to confirm the same set of secrets.',
+                'Compare name_fingerprint between runs to confirm the same set of secrets. ' +
+                'If rough_estimate is near or above max_allowed, tighten select before backup.',
         });
     } catch (err) {
         try { await src.close(); } catch {}