@keeperhub/wallet 0.1.11 → 0.1.13

package/README.md

@@ -5,21 +5,37 @@ Agentic wallet for AI agents. Auto-pays x402 (Base USDC) and MPP (Tempo USDC.e)
 ## Install
 
 ```bash
-npx @keeperhub/wallet skill install
-npx @keeperhub/wallet add
+npx -p @keeperhub/wallet keeperhub-wallet skill install
+npx -p @keeperhub/wallet keeperhub-wallet add
 ```
 
-`skill install` writes the skill file into every detected agent directory AND registers the `keeperhub-wallet-hook` PreToolUse safety hook in `~/.claude/settings.json`. The alternate `npx skills add keeperhub/agentic-wallet-skills` path installs the skill file only — if you use it, follow up with `npx @keeperhub/wallet skill install` to activate the safety hook.
+`skill install` writes the skill file into every detected agent directory AND registers the `keeperhub-wallet-hook` PreToolUse safety hook in `~/.claude/settings.json`. The alternate `npx skills add keeperhub/agentic-wallet-skills` path installs the skill file only — if you use it, follow up with `npx -p @keeperhub/wallet keeperhub-wallet skill install` to activate the safety hook.
 
 The installer probes `PATH` and chooses the form that will resolve later when your shell fires the hook:
 
 - If `keeperhub-wallet-hook` is on `PATH` (global install or `npm link`), the installer writes the bare command for lowest startup latency.
-- Otherwise (the typical `npx @keeperhub/wallet skill install` flow, where the bin is only inside an `npx` cache), it writes `npx -y -p @keeperhub/wallet@<version> keeperhub-wallet-hook` so the hook resolves on every fire without a global install.
+- Otherwise (the typical `npx -p @keeperhub/wallet keeperhub-wallet skill install` flow, where the bin is only inside an `npx` cache), it writes `npx -y -p @keeperhub/wallet@<version> keeperhub-wallet-hook` so the hook resolves on every fire without a global install.
 
-The `npx` form is **pinned to the installer's own version** — never `@latest`. Pinning bounds supply-chain risk: `npx -y` runs whatever is in the registry, so a `latest`-pulling hook would execute new code on every tool call after any future scope compromise. To upgrade, re-run `skill install` from a fresh `npx @keeperhub/wallet@<new-version>`.
+The `npx` form is **pinned to the installer's own version** — never `@latest`. Pinning bounds supply-chain risk: `npx -y` runs whatever is in the registry, so a `latest`-pulling hook would execute new code on every tool call after any future scope compromise. To upgrade, re-run `skill install` from a fresh `npx -p @keeperhub/wallet@<new-version> keeperhub-wallet skill install`.
 
 Override with `KEEPERHUB_WALLET_HOOK_COMMAND` if you need a different command (monorepo bin path, wrapper script, etc.) — it is written verbatim into `settings.json`, so treat it as trusted input. Re-running `skill install` is idempotent across either form: switching between global, npx, or version-bumped npx replaces the existing entry rather than duplicating it. The de-dup matcher only inspects the `command` field of each hook, so unrelated entries that mention `keeperhub-wallet-hook` in their `matcher` or args are preserved.
 
+## MCP server
+
+`skill install` also registers a stdio MCP server (`keeperhub-wallet`) in each detected agent's MCP config so Claude — and any MCP-aware client — can call paid KeeperHub workflows from a tool call without writing a Node script.
+
+Three tools are exposed:
+
+- `call_workflow(slug, body?, paymentHint?, responseFormat?)` — pay-and-invoke a marketplace workflow by slug. Auto-pays x402 on Base USDC or MPP on Tempo USDC.e.
+- `balance()` — Base USDC + Tempo USDC.e on-chain balance.
+- `info()` — public wallet metadata (`subOrgId`, `walletAddress`). The HMAC secret is never returned.
+
+On the very first tool call, if `~/.keeperhub/wallet.json` is missing the server provisions a fresh wallet automatically — there is no manual `keeperhub-wallet add` step to run. The provisioned wallet starts with zero balance; the first 402 round-trip surfaces `INSUFFICIENT_FUNDS` with a Coinbase Onramp URL.
+
+The local `block_threshold_usd` from `~/.keeperhub/safety.json` is enforced inside the MCP server before paymentSigner signs. Calls above the cap return `{code:"POLICY_BLOCKED"}` without contacting Turnkey. Auto/ask thresholds are not enforced by the MCP server in v1 — everything below `block_threshold_usd` is auto-paid.
+
+Auto-registration covers Claude Code, Cursor, Windsurf, and OpenCode. Cline emits a copy-paste notice with the exact entry to paste into its config (the VS Code extension's globalStorage path is too variant-dependent to auto-detect reliably).
+
 ## First use
 
 ```ts

package/bin/keeperhub-wallet-mcp.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { runMcpServer } from "../dist/mcp-server.js";
+
+function reportCrash(label, err) {
+	const detail = err instanceof Error && err.stack ? err.stack : String(err);
+	process.stderr.write(`[keeperhub-wallet] ${label}:\n${detail}\n`);
+}
+
+process.on("uncaughtException", (err) => {
+	reportCrash("uncaughtException", err);
+	process.exit(2);
+});
+process.on("unhandledRejection", (reason) => {
+	reportCrash("unhandledRejection", reason);
+	process.exit(3);
+});
+
+runMcpServer().catch((err) => {
+	reportCrash("mcp server crashed", err);
+	process.exit(1);
+});