drain-mcp 0.2.2 → 0.2.3

package/README.md

@@ -1,6 +1,12 @@
 # DRAIN MCP Server
 
-MCP server for the DRAIN payment protocol. Agents discover service providers, open USDC payment channels on Polygon, and call any service — LLM inference, web scraping, image generation, VPN, and more. No API keys, no subscriptions.
+**Payments for AI Agents** — No API keys, no credit cards, no subscriptions.
+
+MCP server for the DRAIN payment protocol. Agents discover service providers, open USDC payment channels on Polygon, and call any service — LLM inference, web scraping, image generation, VPN, and more.
+
+- **One-time gas cost:** ~$0.02 to open a channel
+- **Per request:** $0.0001–$0.01 depending on service
+- **Setup time:** 30 seconds
 
 ## When to Use DRAIN
 
@@ -12,7 +18,6 @@ Use DRAIN when you need to:
 Do NOT use DRAIN when:
 - You already have API keys for the service you need
 - The task doesn't require external services
-- Cost is not a concern (DRAIN adds ~$0.04 blockchain overhead per session)
 
 ---
 
@@ -25,15 +30,57 @@ Do NOT use DRAIN when:
 4. drain_approve()              → Approve USDC spending (once)
 5. drain_open_channel(...)      → Deposit USDC, get channelId
 6. drain_chat(...)              → Send requests (repeat as needed)
-7. drain_channels()             → Check all channels
+7. drain_cooperative_close(...) → Close early, instant refund (when task is done)
+   — OR after expiry —
 8. drain_close_channel(...)     → Reclaim funds (after expiry)
 ```
 
 ---
 
+## When to Close a Channel
+
+- **Done with your task?** → Use `drain_cooperative_close(channelId)`.
+  Instant refund of unspent deposit. Always do this when finished.
+
+- **Planning more requests soon?** → Keep the channel open.
+  No need to close and reopen — saves $0.04 in gas fees.
+
+- **Channel expired?** → Use `drain_close_channel(channelId)`.
+  Reclaims unspent USDC after the expiry timestamp.
+  Funds do NOT return automatically.
+
+**Rule of thumb:** Close when the task is done. Keep open while working.
+
+---
+
+## Already Hit a 402?
+
+DRAIN providers return `402 Payment Required` with headers when no payment voucher is sent:
+
+| Header | Value |
+|---|---|
+| `X-Payment-Protocol` | `drain-v2` |
+| `X-Payment-Provider` | Provider wallet address (open channel to this) |
+| `X-Payment-Contract` | DRAIN contract address |
+| `X-Payment-Chain` | `137` (Polygon Mainnet) |
+| `X-Payment-Signing` | URL for EIP-712 signing parameters |
+| `X-Payment-Docs` | Provider docs endpoint |
+
+**Flow:**
+1. Call a provider endpoint (no voucher) → get `402` with headers
+2. Install `drain-mcp` or use the signing API at the `X-Payment-Signing` URL
+3. Open a channel to the `X-Payment-Provider` address
+4. Retry the request with an `X-DRAIN-Voucher` header
+
+Everything you need is in the 402 response. No prior registration required.
+
+---
+
 ## Tools Reference
 
-### drain_providers
+### Discovery
+
+#### drain_providers
 Find service providers. Filter by model name, category, or online status.
 
 ```json
@@ -46,24 +93,28 @@ Find service providers. Filter by model name, category, or online status.
 
 Categories: `llm`, `image`, `audio`, `code`, `scraping`, `vpn`, `multi-modal`, `other`
 
-### drain_provider_info
+#### drain_provider_info
 Get details about a provider including usage instructions (docs). The docs explain how to format requests for that provider.
 
 ```json
 { "providerId": "hs58-openai" }
 ```
 
-### drain_balance
+### Wallet
+
+#### drain_balance
 Check wallet USDC balance, POL for gas, and DRAIN contract allowance.
 
-### drain_approve
+#### drain_approve
 Approve USDC spending for the DRAIN contract. Required once before opening channels.
 
 ```json
 { "amount": "100" }
 ```
 
-### drain_open_channel
+### Channels
+
+#### drain_open_channel
 Open a payment channel. Locks USDC for the specified duration.
 
 ```json
@@ -74,9 +125,17 @@ Open a payment channel. Locks USDC for the specified duration.
 }
 ```
 
-Returns channelId, expiry time, and provider usage docs. **Set a cron/timer for the expiry time to call drain_close_channel and recover funds.**
+Returns channelId, expiry time, and provider usage docs.
+
+#### drain_channel_status
+Check a channel's deposit, spending, remaining balance, and expiry.
 
-### drain_chat
+#### drain_channels
+List all known channels with status (active/expired/closed). Find expired channels that need closing.
+
+### Usage
+
+#### drain_chat
 Send a paid request through a channel. Works for ALL provider types:
 
 - **LLM providers:** Standard chat messages
@@ -90,14 +149,42 @@ Send a paid request through a channel. Works for ALL provider types:
 }
 ```
 
-### drain_channel_status
-Check a channel's deposit, spending, remaining balance, and expiry.
+### Settlement
 
-### drain_channels
-List all known channels with status (active/expired/closed). Find expired channels that need closing.
+#### drain_cooperative_close
+Close a channel early with provider consent. **Use this when your task is done** — instant refund of unspent deposit. No need to wait for expiry.
+
+```json
+{ "channelId": "0x..." }
+```
+
+#### drain_close_channel
+Close an expired channel and reclaim unspent USDC. Use when the channel has passed its expiry timestamp.
+
+```json
+{ "channelId": "0x..." }
+```
+
+---
+
+## Economics Example
 
-### drain_close_channel
-Close an expired channel and reclaim unspent USDC.
+Opening a GPT-4o channel:
+
+```
+Gas to open channel:     $0.02   (one-time)
+Deposit:                 $0.50   (refundable remainder)
+Per request:            ~$0.001755
+Requests possible:      ~285
+
+Cost for 10 requests:    $0.02 gas + $0.01755 usage = $0.04
+Refund after close:      $0.50 - $0.01755 = $0.48
+Gas to close:            $0.02
+```
+
+- Protocol fee: 2% on provider claims (on-chain)
+- Session fee: none
+- Live pricing: `GET https://handshake58.com/api/mcp/providers`
 
 ---
 
@@ -107,11 +194,11 @@ Providers are not limited to LLM chat. Each provider has a `category` field and
 
 | Category | Description | Message Format |
 |----------|-------------|----------------|
-| llm | Language models | Standard chat messages |
+| llm | Language models (GPT-4o, Claude, Grok, Gemini) | Standard chat messages |
 | image | Image generation | JSON in user content (see docs) |
 | audio | Audio/TTS/STT | JSON in user content (see docs) |
 | code | Code generation | Standard chat or JSON (see docs) |
-| scraping | Web scraping | JSON in user content (see docs) |
+| scraping | Web scraping, data extraction | JSON in user content (see docs) |
 | vpn | VPN services | JSON in user content (see docs) |
 | multi-modal | Multi-modal models | Standard chat messages |
 | other | Everything else | Always check docs |
@@ -139,6 +226,16 @@ Do I have an active channel?
     │       │           └── drain_chat() → Send requests
 ```
 
+### Ending a Session
+
+```
+Am I done with this task?
+├── YES → drain_cooperative_close(channelId) → Instant refund
+└── NO →
+    ├── More requests soon? → Keep channel open
+    └── Channel expired? → drain_close_channel(channelId) → Reclaim funds
+```
+
 ### Choosing Amount and Duration
 
 | Use Case | Amount | Duration |
@@ -175,17 +272,36 @@ Do I have an active channel?
 
 ## Setup
 
-### Agent Can Do
+### 1. Install
+
+```bash
+npm install -g drain-mcp
+```
+
+### 2. Create a Wallet (locally)
 
-1. **Install** — `npm install -g drain-mcp`
-2. **Create wallet** — `require('viem').generatePrivateKey()` or ask user for existing key
-3. **Configure** — Add to MCP client config (see below)
+Generate a key on your own machine — nothing is sent over the network:
 
-### Requires Human
+```bash
+node -e "const w=require('ethers').Wallet.createRandom();console.log('Address:', w.address, '\nKey:', w.privateKey)"
+```
+
+### 3. Fund the Wallet
+
+Send **$1–5 USDC** on **Polygon Mainnet** to your wallet address.
+Use a dedicated low-value wallet — never your main wallet.
+
+**No POL needed** — if your wallet holds $5+ USDC, free gas is provided:
+
+```bash
+curl -X POST https://handshake58.com/api/gas-station \
+  -H "Content-Type: application/json" \
+  -d '{"address": "0x_your_wallet_address"}'
+```
 
-4. **Fund wallet** — Send $1-5 USDC + $0.10 POL on Polygon to the wallet address
+Returns 0.1 POL (~10K transactions). Sends only your public address.
 
-### MCP Config
+### 4. Configure MCP Client
 
 ```json
 {
@@ -204,7 +320,7 @@ Do I have an active channel?
 |----------|----------|---------|
 | `DRAIN_PRIVATE_KEY` | Yes | — |
 | `DRAIN_CHAIN_ID` | No | 137 (Polygon) |
-| `DRAIN_RPC_URL` | No | polygon-rpc.com |
+| `DRAIN_RPC_URL` | No | Public RPC |
 
 ---
 
@@ -221,7 +337,7 @@ The key is never transmitted to any server. Providers verify signatures against
 Exposure is capped by the smart contract:
 - Maximum spend = channel deposit (you choose the amount)
 - Channel has a fixed duration (you choose)
-- After expiry, unspent funds are reclaimable via drain_close_channel
+- After expiry, unspent funds are reclaimable via `drain_close_channel`
 - No recurring charges, no stored payment methods
 
 ### What Leaves Your Machine
@@ -243,14 +359,17 @@ Every network request the MCP server makes:
 | handshake58.com/api/mcp/providers | GET | Nothing (public catalog) | No |
 | handshake58.com/api/directory/config | GET | Nothing (reads fee wallet) | No |
 | handshake58.com/api/channels/status | GET | channelId (public on-chain data) | No |
+| handshake58.com/api/gas-station | POST | Wallet address | No |
 | Provider apiUrl /v1/docs | GET | Nothing (fetches usage docs) | No |
 | Provider apiUrl /v1/chat/completions | POST | Request messages + signed voucher | No |
+| Provider apiUrl /v1/close-channel | POST | channelId + close signature | No |
 | Polygon RPC (on-chain tx) | POST | Signed transactions | No |
 
 ### Safeguards
-- Use a **dedicated wallet** with $1-5 USDC. Never reuse your main wallet.
-- **Audit the source**: https://github.com/kimbo128/DRAIN
-- Run in an **isolated environment** if handling sensitive data
+- Use a **dedicated wallet** with $1–5 USDC. Never reuse your main wallet.
+- Always generate keys **locally**. The key stays on your machine.
+- **Open source**: [github.com/kimbo128/DRAIN](https://github.com/kimbo128/DRAIN) (MIT licensed)
+- Open channels with small deposits. Close promptly when done.
 
 ---
 
@@ -259,4 +378,5 @@ Every network request the MCP server makes:
 - NPM: https://www.npmjs.com/package/drain-mcp
 - GitHub: https://github.com/kimbo128/DRAIN
 - Marketplace: https://handshake58.com
-- Contract: `0x1C1918C99b6DcE977392E4131C91654d8aB71e64` (Polygon)
+- Provider Directory: https://handshake58.com/directory
+- Contract: `0x0C2B3aA1e80629D572b1f200e6DF3586B3946A8A` (Polygon Mainnet)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drain-mcp",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "mcpName": "io.github.kimbo128/drain-mcp",
   "description": "MCP server for DRAIN protocol. Agents discover providers, open USDC payment channels, and call any service — LLM, scraping, image, VPN, and more.",
   "repository": {