{"_id":"@eddalabs/karbonity-mcp","_rev":"4-aefb16e5f7f0d8597ff0b706b19baa4e","name":"@eddalabs/karbonity-mcp","dist-tags":{"latest":"0.2.2"},"versions":{"0.1.0":{"name":"@eddalabs/karbonity-mcp","version":"0.1.0","license":"MIT","_id":"@eddalabs/karbonity-mcp@0.1.0","maintainers":[{"name":"erickedda","email":"erickrs2esuarez@gmail.com"}],"homepage":"https://github.com/eddalabs/karbonity-gameplay#readme","bugs":{"url":"https://github.com/eddalabs/karbonity-gameplay/issues"},"bin":{"karbonity-mcp":"dist/cli.js"},"dist":{"shasum":"f0c7cbd26402b65a7fec9c8f5b0ad733ed98adf2","tarball":"https://registry.npmjs.org/@eddalabs/karbonity-mcp/-/karbonity-mcp-0.1.0.tgz","fileCount":71,"integrity":"sha512-QYI4ft9Y9raxkfWAhhcbCg7f/jWr9JykkmPWTNJ6ceVZkLoxTPsMNRpGlV7cxPc6KWdzAYyNt2uYzHkvySAXaA==","signatures":[{"sig":"MEYCIQCG48Uy3SE5Hz/dHPlGra+TYIYXyKh17zKxJRjcxPJ4lQIhAKI4QJoHyIrvQ4XmOe//rXpkVQj6P8277DNYXWPL/nch","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":67778395},"type":"module","engines":{"node":">=20"},"gitHead":"bb0be501fa5b98b99093eb031c9ef427aeba33cf","scripts":{"dev":"tsx src/cli.ts","lint":"tsc --noEmit","build":"node scripts/build.mjs","prepack":"node scripts/build.mjs"},"_npmUser":{"name":"erickedda","email":"erickrs2esuarez@gmail.com"},"repository":{"url":"git+https://github.com/eddalabs/karbonity-gameplay.git","type":"git","directory":"packages/mcp-cli"},"_npmVersion":"11.6.2","description":"Karbonity MCP server (stdio) with optional local Midnight agent wallet — connect Claude Code / Claude Desktop to the Karbonity certificate marketplace","directories":{},"_nodeVersion":"23.1.0","dependencies":{"ws":"^8.18.2","zod":"^3.25.0","rxjs":"^7.8.1","@scure/bip39":"^2.0.1","@midnight-ntwrk/ledger-v8":"8.1.0","@midnightntwrk/wallet-sdk":"1.2.0","@modelcontextprotocol/sdk":"^1.30.0","@midnight-ntwrk/compact-js":"2.5.1","@midnight-ntwrk/midnight-js":"4.1.1","@midnight-ntwrk/compact-runtime":"0.16.0","@midnight-ntwrk/midnight-js-types":"4.1.1","@midnight-ntwrk/midnight-js-node-zk-config-provider":"4.1.1","@midnight-ntwrk/midnight-js-http-client-proof-provider":"4.1.1","@midnight-ntwrk/midnight-js-indexer-public-data-provider":"4.1.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.2","esbuild":"^0.25.0","@types/ws":"^8.18.1","typescript":"^5.8.3","@types/node":"^22.10.5","@eddalabs/mcp-core":"workspace:*"},"_npmOperationalInternal":{"tmp":"tmp/karbonity-mcp_0.1.0_1787953072926_0.9224845160514121","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@eddalabs/karbonity-mcp","version":"0.2.0","license":"MIT","_id":"@eddalabs/karbonity-mcp@0.2.0","maintainers":[{"name":"erickedda","email":"erickrs2esuarez@gmail.com"}],"homepage":"https://github.com/eddalabs/karbonity-gameplay#readme","bugs":{"url":"https://github.com/eddalabs/karbonity-gameplay/issues"},"bin":{"karbonity-mcp":"dist/cli.js"},"dist":{"shasum":"b574f22427fdff28d92f496c0ba49dfa76691255","tarball":"https://registry.npmjs.org/@eddalabs/karbonity-mcp/-/karbonity-mcp-0.2.0.tgz","fileCount":71,"integrity":"sha512-VejfWDyEvRMt8MpSSyanZBfdg+pO7lQA277dpvQap5wF7nBm/p8a0PKvCp66pveRy+S8xOKo+mMDFbAiBtbzEw==","signatures":[{"sig":"MEYCIQCbUNBhoG6ozeS8isMHL1q1rg0VvLoHcnAs6lSrZgN6jwIhAPQKcQcsruX1ot7FlWCXk9uNSu5CC5gLqyb9wTSVlhJ4","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":67792312},"type":"module","engines":{"node":">=20"},"gitHead":"534dcf9f2e767460da4b23e2c0eaf206a8f493b9","scripts":{"dev":"tsx src/cli.ts","lint":"tsc --noEmit","build":"node scripts/build.mjs","prepack":"node scripts/build.mjs"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:3a1b3308-115c-4dc3-af38-176dfd8e0f63"}},"repository":{"url":"git+https://github.com/eddalabs/karbonity-gameplay.git","type":"git","directory":"packages/mcp-cli"},"_npmVersion":"12.0.2","description":"Karbonity MCP server (stdio) with optional local Midnight agent wallet — connect Claude Code / Claude Desktop to the Karbonity certificate marketplace","directories":{},"_nodeVersion":"22.23.2","dependencies":{"ws":"^8.18.2","zod":"^3.25.0","rxjs":"^7.8.1","@scure/bip39":"^2.0.1","@midnight-ntwrk/ledger-v8":"8.1.2","@midnightntwrk/wallet-sdk":"1.2.0","@modelcontextprotocol/sdk":"^1.30.0","@midnight-ntwrk/compact-js":"2.5.1","@midnight-ntwrk/midnight-js":"4.1.1","@midnight-ntwrk/compact-runtime":"0.16.0","@midnight-ntwrk/midnight-js-types":"4.1.1","@midnight-ntwrk/midnight-js-node-zk-config-provider":"4.1.1","@midnight-ntwrk/midnight-js-http-client-proof-provider":"4.1.1","@midnight-ntwrk/midnight-js-indexer-public-data-provider":"4.1.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.2","esbuild":"^0.25.0","@types/ws":"^8.18.1","typescript":"^5.8.3","@types/node":"^22.10.5","@eddalabs/mcp-core":"workspace:*"},"_npmOperationalInternal":{"tmp":"tmp/karbonity-mcp_0.2.0_1789070647621_0.25307610607615816","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@eddalabs/karbonity-mcp","version":"0.2.1","license":"MIT","_id":"@eddalabs/karbonity-mcp@0.2.1","maintainers":[{"name":"erickedda","email":"erickrs2esuarez@gmail.com"}],"homepage":"https://github.com/eddalabs/karbonity-gameplay#readme","bugs":{"url":"https://github.com/eddalabs/karbonity-gameplay/issues"},"bin":{"karbonity-mcp":"dist/cli.js"},"dist":{"shasum":"bac2dde2fd8aed8004713bb709104642dbf21e72","tarball":"https://registry.npmjs.org/@eddalabs/karbonity-mcp/-/karbonity-mcp-0.2.1.tgz","fileCount":71,"integrity":"sha512-EaXGrJkuU6Glk78HfxgegM162JLNjmZormbzBRcowr0KzC/KqmPvSRLeqYHb/bYICU19WNR999Fc/6f/MnseMA==","signatures":[{"sig":"MEUCIQD37asClarUlVUHwsj6bkkV5WHNSQjF+Ombc4mh87RRzQIgJQdwXmVROBSHjN5a0HZEdFgt9LrcdeWS9Oeg9DEChuc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":67792325},"type":"module","engines":{"node":">=20"},"gitHead":"6c57b57fb3e8b5f7db154167b4a32c3f6ce79c9f","scripts":{"dev":"tsx src/cli.ts","lint":"tsc --noEmit","build":"node scripts/build.mjs","prepack":"node scripts/build.mjs"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:3a1b3308-115c-4dc3-af38-176dfd8e0f63"}},"repository":{"url":"git+https://github.com/eddalabs/karbonity-gameplay.git","type":"git","directory":"packages/mcp-cli"},"_npmVersion":"12.0.2","description":"Karbonity MCP server (stdio) with optional local Midnight agent wallet — connect Claude Code / Claude Desktop to the Karbonity certificate marketplace","directories":{},"_nodeVersion":"22.23.2","dependencies":{"ws":"^8.18.2","zod":"^3.25.0","rxjs":"^7.8.1","@scure/bip39":"^2.0.1","@midnight-ntwrk/ledger-v8":"8.1.2","@midnightntwrk/wallet-sdk":"1.2.0","@modelcontextprotocol/sdk":"^1.30.0","@midnight-ntwrk/compact-js":"2.5.1","@midnight-ntwrk/midnight-js":"4.1.1","@midnight-ntwrk/compact-runtime":"0.16.0","@midnight-ntwrk/midnight-js-types":"4.1.1","@midnight-ntwrk/midnight-js-node-zk-config-provider":"4.1.1","@midnight-ntwrk/midnight-js-http-client-proof-provider":"4.1.1","@midnight-ntwrk/midnight-js-indexer-public-data-provider":"4.1.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.2","esbuild":"^0.25.0","@types/ws":"^8.18.1","typescript":"^5.8.3","@types/node":"^22.10.5","@eddalabs/mcp-core":"workspace:*"},"_npmOperationalInternal":{"tmp":"tmp/karbonity-mcp_0.2.1_1789079749428_0.10641755168032274","host":"s3://npm-registry-packages-npm-production"}},"0.2.2":{"name":"@eddalabs/karbonity-mcp","version":"0.2.2","type":"module","bin":{"karbonity-mcp":"dist/cli.js"},"scripts":{"build":"node scripts/build.mjs","prepack":"node scripts/build.mjs","dev":"tsx src/cli.ts","lint":"tsc --noEmit"},"dependencies":{"@midnight-ntwrk/compact-js":"2.5.1","@midnight-ntwrk/compact-runtime":"0.16.0","@midnight-ntwrk/ledger-v8":"8.1.2","@midnight-ntwrk/midnight-js":"4.1.1","@midnight-ntwrk/midnight-js-http-client-proof-provider":"4.1.1","@midnight-ntwrk/midnight-js-indexer-public-data-provider":"4.1.1","@midnight-ntwrk/midnight-js-node-zk-config-provider":"4.1.1","@midnight-ntwrk/midnight-js-types":"4.1.1","@midnightntwrk/wallet-sdk":"1.2.0","@modelcontextprotocol/sdk":"^1.30.0","@scure/bip39":"^2.0.1","rxjs":"^7.8.1","ws":"^8.18.2","zod":"^3.25.0"},"devDependencies":{"@types/node":"^22.10.5","@types/ws":"^8.18.1","tsx":"^4.19.2","typescript":"^5.8.3","@eddalabs/mcp-core":"workspace:*","esbuild":"^0.25.0"},"description":"Karbonity MCP server (stdio) with optional local Midnight agent wallet — connect Claude Code / Claude Desktop to the Karbonity certificate marketplace","license":"MIT","repository":{"type":"git","url":"git+https://github.com/eddalabs/karbonity-gameplay.git","directory":"packages/mcp-cli"},"engines":{"node":">=20"},"publishConfig":{"access":"public"},"gitHead":"cd3846ec21e06ebfff3cdd56010cf43bd3fd8709","_id":"@eddalabs/karbonity-mcp@0.2.2","bugs":{"url":"https://github.com/eddalabs/karbonity-gameplay/issues"},"homepage":"https://github.com/eddalabs/karbonity-gameplay#readme","_nodeVersion":"22.23.2","_npmVersion":"12.0.2","dist":{"integrity":"sha512-UKmollaPSwK/n/SnXI95Kfv5xTgj8hJwxkdgq5cS1wckhLQh96IK+bUVzRugowdC1OV/9Tw1/DmSGwxCnGudVg==","shasum":"4318c0173b0f2aff9df8de7ea7e5bd2d7b868668","tarball":"https://registry.npmjs.org/@eddalabs/karbonity-mcp/-/karbonity-mcp-0.2.2.tgz","fileCount":71,"unpackedSize":67793552,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBdSo4pp+dEVGVhQOUXlTX6h0tQ/qnUeubJiMFHXGq+0AiBX7q0+pW19lOdk2xzld16rrTCYA+zBPqjESDlThTQYfw=="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:3a1b3308-115c-4dc3-af38-176dfd8e0f63"}},"directories":{},"maintainers":[{"name":"erickedda","email":"erickrs2esuarez@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/karbonity-mcp_0.2.2_1789090973690_0.269882871644497"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-28T21:37:52.739Z","modified":"2026-09-11T01:42:54.800Z","0.1.0":"2026-08-28T21:37:53.895Z","0.2.0":"2026-09-10T20:04:08.832Z","0.2.1":"2026-09-10T22:35:50.437Z","0.2.2":"2026-09-11T01:42:54.620Z"},"bugs":{"url":"https://github.com/eddalabs/karbonity-gameplay/issues"},"license":"MIT","homepage":"https://github.com/eddalabs/karbonity-gameplay#readme","repository":{"type":"git","url":"git+https://github.com/eddalabs/karbonity-gameplay.git","directory":"packages/mcp-cli"},"description":"Karbonity MCP server (stdio) with optional local Midnight agent wallet — connect Claude Code / Claude Desktop to the Karbonity certificate marketplace","maintainers":[{"name":"erickedda","email":"erickrs2esuarez@gmail.com"}],"readme":"# karbonity-mcp — connect AI agents to Karbonity\n\n[![npm](https://img.shields.io/npm/v/@eddalabs/karbonity-mcp)](https://www.npmjs.com/package/@eddalabs/karbonity-mcp)\n\nKarbonity exposes one MCP tool catalog (`packages/mcp-core`) over two transports.\nPick the one that matches where your agent runs:\n\n| You use… | Transport | Setup |\n|---|---|---|\n| **Claude.ai** (web/desktop/mobile chat), Cowork | **Remote HTTP** — `https://<deployment>.convex.site/mcp` | [A. Remote connector](#a-remote-connector-claudeai) |\n| **Claude Code** or **Claude Desktop** on your machine | **Local stdio** — `karbonity-mcp serve` | [B. Local server](#b-local-server-claude-code--desktop) |\n\nBoth give the same 20 tools (browse the marketplace, your certificates, create/list/price/burn\nvia the bot, and buy/redeem/withdraw/swap). The difference is *wallet actions*:\n\n- **Remote**: `buy` / `redeem` / `withdraw_seller_funds` / `swap_night` return a **URL**. Open it, review, and sign in the web UI with your own wallet (Lace or passkey). The server never holds a key.\n- **Local + agent wallet**: the same tools **execute on your machine** with a dedicated, funded *agent wallet*. See [C](#c-optional-local-agent-wallet).\n\nAmounts everywhere are decimal strings in the smallest Night unit (`2000000` = 2 Night).\n\n---\n\n## One-time backend setup (operator)\n\nDo this once per deployment. Already done for the dev deployment `animated-spoonbill-938`.\n\n1. **Clerk Dashboard → OAuth applications → Create**\n   - Client type **Public** (PKCE, no secret).\n   - Redirect URIs:\n     `https://claude.ai/api/mcp/auth_callback`\n     `http://127.0.0.1:44831/callback`\n     `http://localhost/callback`\n   - Leave **Generate access tokens as JWTs** on.\n   - Optional: enable **Dynamic client registration** so Claude.ai can add the connector by URL alone.\n2. **Convex environment variables** (`npx convex env set …` in `packages/backend`):\n   - `CONTRACT_ADDRESS` — the mini-private-buyer contract (same as `VITE_CONTRACT_ADDRESS`)\n   - `SITE_URL` — web app origin, used for draft links (e.g. `http://localhost:5173`)\n   - `MCP_OAUTH_ISSUER` — optional; defaults to `CLERK_FRONTEND_API_URL`\n   - `MCP_OAUTH_AUDIENCE` — any value enables agent auth; `off` disables it\n3. Deploy: `npx convex dev --once` (use Node 22 — Node 23 segfaults the Convex CLI).\n\nHow auth works: Clerk issues OAuth access tokens as JWTs signed by the same JWKS as your web\nsession. `convex/auth.config.js` trusts them with a *Custom JWT* provider, so `ctx.auth` sees\nthe same Clerk user id and every existing Convex function works unchanged for agents.\n\n---\n\n## A. Remote connector (Claude.ai)\n\n1. Claude.ai → **Settings → Connectors → Add custom connector**.\n2. URL: `https://animated-spoonbill-938.convex.site/mcp`\n3. If Dynamic client registration is **off** in Clerk: open **Advanced settings** and paste the\n   OAuth app's **Client ID** (`GmOu49U0Yux4yxUE` on dev). No secret.\n4. Click Connect → sign in with your Karbonity (Clerk) account → done.\n\nClaude Code can also use the remote server:\n`claude mcp add --transport http karbonity-remote https://animated-spoonbill-938.convex.site/mcp --client-id GmOu49U0Yux4yxUE`\n\n---\n\n## B. Local server (Claude Code / Desktop) — Linux or WSL\n\nRequires Node ≥ 20 on Linux (on Windows, inside WSL). Not supported natively on Windows.\n\n### 1. Install\n\n```bash\nnpm install -g @eddalabs/karbonity-mcp\nkarbonity-mcp doctor        # shows backend, login, wallet and proof-server status\n```\n\nThe production backend is built in — no configuration step. (`karbonity-mcp init --convex-site … --contract …`\nonly if you run your own deployment.)\n\n### 2. Log in\n\n```bash\nkarbonity-mcp login         # opens a browser URL; sign in with your Karbonity account\n```\n\nThe token is stored in `~/.karbonity/auth.json` (mode 0600) and refreshed automatically.\n`karbonity-mcp logout` forgets it.\n\n### 3. Register with Claude\n\n**Claude Code** (run inside the project you want it in):\n\n```bash\nclaude mcp add karbonity -s local -- karbonity-mcp serve\n```\n\n**Claude Desktop on Linux** — paste into `claude_desktop_config.json`:\n\n```json\n{ \"mcpServers\": { \"karbonity\": { \"command\": \"karbonity-mcp\", \"args\": [\"serve\"] } } }\n```\n\n(`karbonity-mcp desktop-config` prints this for you.)\n\n**Per-project, zero install** — drop a `.mcp.json` at the repo root and everyone who opens it gets the\nserver (Claude Code asks each user to approve the project's servers on first use):\n\n```json\n{\n  \"mcpServers\": {\n    \"karbonity\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@eddalabs/karbonity-mcp\", \"serve\"],\n      \"env\": { \"KARBONITY_WALLET_PASSPHRASE\": \"${KARBONITY_WALLET_PASSPHRASE:-}\" }\n    }\n  }\n}\n```\n\nClaude Code expands `${VAR}` and `${VAR:-default}` in `.mcp.json`, so the file references the passphrase\nwithout containing it — each user exports `KARBONITY_WALLET_PASSPHRASE` in their own shell (or leaves it\nunset and gets the draft flow). Keep the `:-` default: without it, an unset variable is passed through as\nthe literal text `${KARBONITY_WALLET_PASSPHRASE}`. Never put the passphrase itself in a committed file.\n\n**No global install?** Any client can run it straight from npm instead:\n\n```json\n{ \"mcpServers\": { \"karbonity\": { \"command\": \"npx\", \"args\": [\"-y\", \"@eddalabs/karbonity-mcp\", \"serve\"] } } }\n```\n\nThe first launch downloads ~66 MB, which can trip the client's startup timeout; after that it is cached.\nA global install starts instantly, so it is the better default.\n\n**Claude Desktop on Windows, code in WSL** — Desktop runs on Windows, so it must start the server inside\nyour distro through `wsl.exe`. Run **in WSL**:\n\n```bash\nkarbonity-mcp desktop-config --windows\n```\n\nand paste the output into `%APPDATA%\\Claude\\claude_desktop_config.json`, then restart Desktop. It looks like:\n\n```json\n{ \"mcpServers\": { \"karbonity\": { \"command\": \"wsl.exe\",\n  \"args\": [\"-d\", \"Ubuntu\", \"--\", \"/home/<you>/.nvm/versions/node/v22.x/bin/node\",\n           \"/home/<you>/.nvm/versions/node/v22.x/lib/node_modules/@eddalabs/karbonity-mcp/dist/cli.js\", \"serve\"] } } }\n```\n\nWindows is the one place absolute paths are unavoidable: `wsl.exe` starts no login shell, so npm's global\nbin (and `nvm`) are not on `PATH` — `karbonity-mcp` alone would not be found. `desktop-config --windows`\nfills the paths in for you. The browser sign-in from `login` opens on Windows and reaches WSL through\nWSL2's localhost forwarding.\n\nThen `/mcp` in Claude Code (or restart Desktop). You should see 20 `karbonity` tools.\nTry: *\"list my certificates\"*, *\"what's for sale?\"*, *\"create a Solar certificate and list it for 2 Night\"*.\n\nNever run `karbonity-mcp serve` by hand for normal use — Claude launches it and talks to it over stdin/stdout.\n\n### From source (contributors)\n\n```bash\npnpm --filter @eddalabs/karbonity-mcp build     # → packages/mcp-cli/dist (bundle + 65 MB prover keys)\nclaude mcp add karbonity -s local -- node $PWD/packages/mcp-cli/dist/cli.js serve\n```\n\n`pnpm dev` runs the TypeScript directly through tsx.\n\n---\n\n## C. Optional: local agent wallet\n\nWithout this, wallet actions return draft URLs (same as the remote connector). With it, the\nlocal server signs and proves on your machine.\n\nWhy a separate wallet: your passkey wallet's seed comes from WebAuthn PRF and cannot run\nheadless; Lace lives in the browser. So the agent gets its own identity. Fund it only with what\nyou're willing to let an agent spend; sweep it to revoke.\n\n```bash\nkarbonity-mcp wallet init            # prints the 24-word phrase ONCE; asks for a passphrase\nkarbonity-mcp wallet show            # addresses + seller id\n```\n\nThe mnemonic is encrypted with your passphrase (scrypt + AES-GCM) in `~/.karbonity/wallet.enc`.\n\n1. Fund the **unshielded address** from `wallet show` at https://faucet.preview.midnight.network/\n2. Run a proof server on `127.0.0.1:6300`:\n\n   ```bash\n   karbonity-mcp proof-server start --max-k 17    # Docker required\n   karbonity-mcp proof-server status | logs | stop\n   ```\n\n   **Why local:** generating a proof means giving the prover your witness (zero-knowledge protects\n   verifiers, not the prover). A remote proof server would therefore see your `secretNonce` on every\n   transaction. Keep it on your machine unless the server is inside your own trust domain.\n\n   **About `--max-k`.** The image fetches PLONK parameters from `srs.midnight.network` automatically —\n   it prefetches k=10..15 at startup and pulls higher k on demand, which stalls the first proof that\n   needs one. `buy` and `redeem` are fine on the defaults; **shield/unshield need k=16 and 17**\n   (≈13 MB and ≈25 MB). `--max-k 17` downloads them up front into `~/.karbonity/zk-params`, which is\n   then bind-mounted — raise the number if other circuits need more (each k doubles: k=18 ≈ 50 MB,\n   k=19 ≈ 100 MB). Files already present are skipped, so re-running is cheap.\n\n   Already have a parameter cache? `--params-dir /path/to/zk-params` mounts it as-is, no downloads.\n   Running your own server elsewhere? `karbonity-mcp init --proof-server URL`.\n3. Give the server the passphrase — it cannot prompt, because stdin is the MCP channel:\n\n   ```bash\n   claude mcp remove karbonity -s local\n   claude mcp add karbonity -s local -e KARBONITY_WALLET_PASSPHRASE='…' -- karbonity-mcp serve\n   # Claude Desktop (incl. Windows+WSL): KARBONITY_WALLET_PASSPHRASE='…' karbonity-mcp desktop-config --windows --with-passphrase\n   ```\n\n   (The passphrase is then stored in plain text in that config file. If you'd rather not, leave it unset and use draft URLs.)\n4. `/mcp` → reconnect. A `wallet_info` tool appears; `buy`, `redeem`, `withdraw_seller_funds`, `swap_night` now execute locally.\n\nThe wallet's private state (`secretNonce` + purchases) is stored encrypted in Convex's\n`walletVaults` table exactly like browser wallets, keyed from the agent seed — Convex cannot\nlink the row to you or to the wallet.\n\n---\n\n## Troubleshooting\n\n| Symptom | Fix |\n|---|---|\n| `karbonity-mcp: command not found` | `npm install -g @eddalabs/karbonity-mcp` with Node ≥ 20; check `npm prefix -g`/bin is on `PATH`. |\n| Tool returns *\"Not logged in\"* | `karbonity-mcp login`. |\n| `whoami` → `authenticated: false` or a \"No auth provider\" error | Backend setup step 2/3 not applied, or the token comes from a different Clerk instance than `CLERK_FRONTEND_API_URL`. |\n| Claude Code shows `karbonity ✘ Failed to connect` | Use `karbonity-mcp desktop-config` output (absolute paths) instead of a bare command; run that exact command from `/` — it must print nothing on stdout until it receives JSON. |\n| Server says *\"wallet found but KARBONITY_WALLET_PASSPHRASE is not set\"* | Expected without step C.3; wallet tools fall back to drafts. |\n| Server says *\"could not unlock the agent wallet\"* | Wrong passphrase (or a `${VAR}` that the client never expanded). The server keeps running — only wallet tools degrade to drafts. |\n| Login page says redirect URI mismatch | Add `http://127.0.0.1:44831/callback` to the Clerk OAuth app. |\n| Windows Desktop: server never connects | Run the `wsl.exe …` line from PowerShell; if it prints an error, fix the distro name or path. The proof server (`pnpm ps`) must also run inside WSL. |\n\n## Commands\n\n```\nkarbonity-mcp login | logout | whoami | doctor | version\nkarbonity-mcp desktop-config [--windows] [--with-passphrase]\nkarbonity-mcp wallet init | import <words…> | show\nkarbonity-mcp serve                      # MCP over stdio (launched by Claude)\nkarbonity-mcp init [--convex-site URL] [--site URL] [--contract HEX] [--proof-server URL] [--issuer URL] [--client-id ID]\n```\n\n## Releasing (maintainers)\n\nPublished as [`@eddalabs/karbonity-mcp`](https://www.npmjs.com/package/@eddalabs/karbonity-mcp)\nunder the `eddalabs` npm org. `packages/mcp-core` stays `private: true` — esbuild inlines it into\n`dist/cli.js`, so it is never resolved from the registry.\n\n**npm credentials (one-time).** Publishing needs a token whose 2FA requirement is satisfied:\neither a **granular access token** created with *Bypass two-factor authentication* checked\n(Access Tokens → Generate New Token → Granular; permissions **Read and write** on the\n**`@eddalabs` scope** — granting access to the *Organization* is not enough, it only covers org\nsettings), or a normal granular token combined with account 2FA set to *\"Authorization only\"*\n(Account settings → Two-factor authentication). Install it with\n`npm config set //registry.npmjs.org/:_authToken npm_xxx` — do **not** pass it to `--otp`,\nwhich expects a 6-digit code.\n\n**Release from CI** (preferred). Bump `version` in `packages/mcp-cli/package.json`, tag\n`mcp-cli-v<version>`, push the tag. `.github/workflows/release-mcp-cli.yml` builds with the\nproduction values from repository variables (`KARBONITY_CONVEX_SITE_URL`, `KARBONITY_SITE_URL`,\n`KARBONITY_CONTRACT_ADDRESS`, `KARBONITY_OAUTH_ISSUER`, `KARBONITY_OAUTH_CLIENT_ID`) and\npublishes with the `NPM_TOKEN` secret.\n\n**Release manually.**\n\n```bash\npnpm --filter @eddalabs/karbonity-mcp build\ncd packages/mcp-cli\nnpm pack                      # inspect: dist/cli.js + dist/contract/**/keys, no src/\nnpm publish --access public   # ~66 MB; the registry document takes a few minutes to propagate\n```\n\nNotes: `prepack` runs the build, so `npm publish` never ships a stale bundle. Right after a first\npublish `npm view`/`npm install` can 404 for a few minutes while the CDN catches up — `npm search`\nand `npm access list packages @eddalabs` confirm it landed.\n","readmeFilename":"README.md"}