@vapi-network/mcp 0.1.0

package/README.md

@@ -0,0 +1,176 @@
+# Agent Cash (`@vapi-network/mcp`)
+
+Agent Cash gives Claude, Cursor, and other MCP clients a small local wallet that
+can discover and pay x402 APIs directly.
+
+For the Call launch, this buyer-local client is the npm-distributed payment path
+for native and external Bazaar listings. The browser-wallet flow is also
+available where a provider permits a direct browser request. Legacy wrapped
+rows remain hidden and non-callable while the optional Wrap gateway is disabled.
+The hosted Go MCP remains free (`echo` and `search`).
+
+The private key is generated locally and stored only in the Agent Cash home
+(default `~/.vapi/agent-cash`, overridden by `VAPI_AGENT_CASH_HOME`), encrypted
+with scrypt (`N=2^15`) and AES-256-GCM. Your MCP client signs each exact
+EIP-3009 payment locally. vAPI supplies public discovery metadata; it never
+receives the private key and cannot spend the wallet balance. Fund this like
+pocket money, not a treasury.
+
+Direct x402 calls need no vAPI account or API key: the agent pays the selected
+API directly from the buyer-controlled wallet.
+
+## Install and run
+
+Create the encrypted local wallet:
+
+```sh
+npx -y @vapi-network/mcp init
+```
+
+Running `npx -y @vapi-network/mcp` with no command starts the MCP stdio server.
+
+Fund the printed address with a small amount of canonical Base-mainnet USDC
+(`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`). Agent Cash does not need ETH to
+authorize ordinary x402 calls; send a little Base ETH only if you want it to
+sweep USDC back to another wallet later.
+
+Configure an MCP client to launch the package through npm:
+
+```json
+{
+  "mcpServers": {
+    "agent-cash": {
+      "command": "npx",
+      "args": ["-y", "@vapi-network/mcp", "serve"],
+      "env": {
+        "VAPI_KEYSTORE_PASSWORD": "replace-with-your-keystore-passphrase"
+      }
+    }
+  }
+}
+```
+
+`VAPI_AGENT_CASH_HOME` optionally moves the wallet directory from
+`~/.vapi/agent-cash`. Desktop MCP hosts normally need
+`VAPI_KEYSTORE_PASSWORD` in the process environment because they cannot answer
+an interactive passphrase prompt. Protect that configuration with the same
+care as the pocket-money wallet.
+
+For a workspace-only development run, build from the repository root and keep
+the test wallet isolated under the gitignored `.context` directory:
+
+```sh
+pnpm --filter @vapi-network/mcp build
+VAPI_AGENT_CASH_HOME="$PWD/.context/agent-cash" \
+  pnpm --filter @vapi-network/mcp exec node dist/cli.js init
+```
+
+For the first staging test, send a small amount of Base USDC to the printed
+address. Also send a little Base ETH only if you intend to test sweep-back.
+
+Then point the MCP client at the built CLI. Replace both absolute paths with
+this checkout's paths:
+
+```json
+{
+  "mcpServers": {
+    "agent-cash": {
+      "command": "node",
+      "args": ["/absolute/path/to/vapi-app/packages/vapi-mcp/dist/cli.js", "serve"],
+      "env": {
+        "VAPI_AGENT_CASH_HOME": "/absolute/path/to/vapi-app/.context/agent-cash",
+        "VAPI_KEYSTORE_PASSWORD": "replace-with-your-keystore-passphrase"
+      }
+    }
+  }
+}
+```
+
+Base uses its public RPC by default. Leave `ARC_TESTNET_RPC_URL` unset for the
+Base-only staging slice.
+
+Restart the MCP client. The agent can now:
+
+- `search {query?, kinds?, network?, limit?, cursor?}` across the public
+  marketplace. API results are callable; other results carry their canonical
+  vAPI web action.
+- `call {id|url, method?, body?, maxPriceUsd?, network?}` and pay an x402
+  `exact` challenge directly over HTTPS. An `id` must be an API ref returned by
+  `search` in the current Agent Cash process; an explicit published `url` may be
+  called directly. Set `network` to require a specific configured CAIP-2
+  network before Agent Cash signs.
+- `wallet {}` to inspect the address and USDC balance on each network.
+
+`tools/list` exposes exactly these three tools: `search`, `call`, and `wallet`.
+
+## Spend caps
+
+The Agent Cash home's `config.json` contains atomic-USDC caps (USDC has 6 decimals):
+
+```json
+{
+  "spendCaps": {
+    "perCallAtomic": "100000",
+    "perDayAtomic": "1000000"
+  }
+}
+```
+
+Those defaults are $0.10 per call and $1.00 per UTC day. Agent Cash checks both caps and reserves the quote in its atomic local daily ledger **before signing**. `maxPriceUsd` can set a still-lower ceiling for one tool call. The ledger is `spend-ledger.json` in the same Agent Cash home and rolls over when the UTC date changes.
+
+The `call` tool requires HTTPS and blocks private, loopback, and link-local destinations by default. It validates every redirect before carrying a method or body forward. For local development only, setting `"allowPrivateNetwork": true` in `~/.vapi/agent-cash/config.json` permits an unpaid HTTP `localhost`, `*.localhost`, or loopback request; it does not permit HTTP calls to remote hosts, and Agent Cash still refuses to send a signed payment over HTTP.
+
+`discoveryUrl` remains the Calls compatibility endpoint used to resolve a
+searched native vAPI ref into its payable endpoint. `marketplaceDiscoveryUrl`
+is the unified search route. Override them independently with
+`VAPI_DISCOVERY_URL` and `VAPI_MARKETPLACE_DISCOVERY_URL`. Agent Cash rejects an
+uncached or evicted `id` because its source and marketplace kind are no longer
+known; run `search` again or use the result's explicit published URL. It never
+attempts to call a service offer or open request; those actions continue in the
+web marketplace.
+
+## Paid-call receipts
+
+The `call` result keeps both payment receipt surfaces under `payment`:
+
+- `settlement` is the decoded x402 `Payment-Response` (or compatible `X-Payment-Response`) header.
+- `proof` is normally `null` for launch-approved native endpoints. Agent Cash
+  preserves an `X-VAPI-Payment-Proof` value if a future reviewed Wrap endpoint
+  returns one.
+
+A proof value alone is not verification. A future Wrap consumer must pin and
+verify its signer and fields and enforce replay protection.
+
+## Balances and sweep-back
+
+```sh
+VAPI_AGENT_CASH_HOME="$PWD/.context/agent-cash" pnpm --filter @vapi-network/mcp exec node dist/cli.js balance
+VAPI_AGENT_CASH_HOME="$PWD/.context/agent-cash" pnpm --filter @vapi-network/mcp exec node dist/cli.js sweep-back 0xYourMainWallet
+VAPI_AGENT_CASH_HOME="$PWD/.context/agent-cash" pnpm --filter @vapi-network/mcp exec node dist/cli.js sweep-back 0xYourMainWallet --network eip155:8453
+```
+
+Without `--network`, sweep-back attempts every configured network. Base transfers the full USDC balance because gas is paid in ETH. Arc gas is paid in USDC, so Agent Cash keeps 0.05 USDC by default instead of stranding the sweep transaction. Configure that reserve with `VAPI_ARC_GAS_HEADROOM_USDC` (for example, `0.10`).
+
+## Networks
+
+| Network      | CAIP-2           | Chain ID | USDC                                         | Gas token | RPC                                                    |
+| ------------ | ---------------- | -------: | -------------------------------------------- | --------- | ------------------------------------------------------ |
+| Base mainnet | `eip155:8453`    |     8453 | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` | ETH       | `BASE_RPC_URL`, defaults to `https://mainnet.base.org` |
+| Arc testnet  | `eip155:5042002` |  5042002 | `0x3600000000000000000000000000000000000000` | USDC      | `ARC_TESTNET_RPC_URL` is required                      |
+
+Agent Cash configures Base only by default. For the staging test, first run
+`search {"query":"<capability>","kinds":["api"],"network":"eip155:8453"}`.
+In the same Agent Cash process, call the returned ref with
+`call {"id":"<search-result-ref>","network":"eip155:8453","maxPriceUsd":"0.02"}`.
+Arc remains opt-in: set a nonblank `ARC_TESTNET_RPC_URL` to add it. The same
+exact-scheme EIP-3009 code path handles both CAIP-2 networks. You can also edit
+the `networks` map in `~/.vapi/agent-cash/config.json`; entries with blank RPC
+URLs are ignored and cannot be selected for payment. A custom token/network
+entry must pin its EIP-712 domain as `"eip712Domain": { "name": "…", "version":
+"…" }`; provider-supplied domain text is never trusted on its own.
+
+## Custody and recovery
+
+This package is self-custodied software: the encrypted payment key and spend ledger live on your machine. vAPI is discovery only in this lane. Vendors receive only narrowly scoped EIP-3009 authorizations for the exact quoted amount, recipient, token, chain, nonce, and validity window. A stolen unlocked key or passphrase can still drain the wallet, so keep only a small working balance and sweep unused funds back.
+
+Back up the encrypted keystore if you need recovery. Losing both the keystore and its backup permanently loses access to its funds; losing the passphrase does too. Never share the decrypted private key.