pay-per-call-mcp 0.5.1 → 0.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +39 -200
  2. package/dist/index.js +2 -1021
  3. package/package.json +15 -27
package/README.md CHANGED
@@ -1,245 +1,84 @@
1
- # 🍋 LemonCake — AI Agent Wallet & USDC Pay-per-call MCP Server
1
+ # pay-per-call-mcp — AI Agent Payment MCP Server
2
2
 
3
- > 🎮 **Try instantly — no signup needed.** Click **"Try in Browser"** above → leave **BOTH** env var fields **EMPTY** → click **Start Inspector**. Demo Mode hits real Wikipedia / httpbin / live FX APIs. No account, no card, no API key.
3
+ > Pay-per-call USDC micropayments for any HTTP API. Give your AI agent a USDC spending wallet — works with Claude Desktop, Cursor, Cline, and any MCP client. **No signup needed in Demo Mode.**
4
4
 
5
5
  [![npm version](https://img.shields.io/npm/v/pay-per-call-mcp)](https://www.npmjs.com/package/pay-per-call-mcp)
6
6
  [![npm downloads](https://img.shields.io/npm/dm/pay-per-call-mcp)](https://www.npmjs.com/package/pay-per-call-mcp)
7
7
  [![MCP](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io)
8
8
  [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
9
- [![Glama MCP](https://img.shields.io/badge/Listed%20on-Glama-7c3aed)](https://glama.ai/mcp/servers/evidai/lemon-cake)
10
- [![Node.js](https://img.shields.io/node/v/pay-per-call-mcp)](https://nodejs.org)
11
9
 
12
- > 📦 **v0.5.0 rename:** the npm package is now **`pay-per-call-mcp`** (was `lemon-cake-mcp`). The old name still works as a thin wrapper, but new configs should use `npx -y pay-per-call-mcp`.
13
-
14
- > **Give your AI agent a wallet.** Pay-per-call USDC payments for any HTTP API — straight from Claude Desktop, Cursor, Cline, or any MCP client. No human in the loop, no per-API signups, no API key juggling.
15
-
16
- LemonCake の MCP サーバーで、Claude Desktop / Cursor / Cline などの MCP 互換クライアントから、人間の介在なしに USDC で有料 API を呼び出せるようになります。
17
-
18
- **English ↓** [Quickstart](#-3分で始める) · [Tools](#%EF%B8%8F-提供ツール) · [Use Cases](#-use-cases) · [Compatibility](#-tested-clients)
10
+ > 📦 **v0.5.2:** This package forwards to [`agent-payment-mcp`](https://www.npmjs.com/package/agent-payment-mcp). Both names work — `pay-per-call-mcp` is kept for existing configs.
19
11
 
20
12
  ---
21
13
 
22
- ## 🚀 3分で始める
23
-
24
- MCP サーバーの利用には LemonCake アカウントと USDC 残高が必要です。
25
-
26
- 1. **[無料アカウント作成](https://lemoncake.xyz/register?utm_source=mcp-server&utm_medium=npm-readme&utm_campaign=onboard)** — メール1つで完了
27
- 2. **残高チャージ** — 最低 $5 USDC または JPYC（[Billing](https://lemoncake.xyz/dashboard/billing?utm_source=mcp-server&utm_medium=npm-readme&utm_campaign=topup)）
28
- 3. **Buyer JWT をコピー** — [Dashboard → API Keys](https://lemoncake.xyz/dashboard?utm_source=mcp-server&utm_medium=npm-readme) から
29
- 4. 下記の `claude_desktop_config.json` に設定
14
+ ## What it does
30
15
 
31
- > 📚 詳細: [クイックスタート ドキュメント](https://lemoncake.xyz/docs/quickstart?utm_source=mcp-server&utm_medium=npm-readme)
16
+ `pay-per-call-mcp` lets an AI agent pay for HTTP API calls with USDC — no human approval needed per call.
32
17
 
33
- ---
34
-
35
- ## 📦 インストール
18
+ - Agent calls a tool → USDC deducted from its wallet → API responds
19
+ - Kill switch + per-session spend limit built in
20
+ - **Demo Mode**: try instantly without any account or balance
36
21
 
37
- ### Claude Desktop の場合
22
+ ## Try in 30 seconds (Demo Mode)
38
23
 
39
- `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）または
40
- `%APPDATA%\Claude\claude_desktop_config.json`（Windows）に追加:
24
+ In Claude Desktop / Cursor / Cline — add to your MCP config:
41
25
 
42
26
  ```json
43
27
  {
44
28
  "mcpServers": {
45
29
  "pay-per-call": {
46
30
  "command": "npx",
47
- "args": ["-y", "pay-per-call-mcp"],
48
- "env": {
49
- "LEMON_CAKE_BUYER_JWT": "eyJhbGci..."
50
- }
31
+ "args": ["-y", "pay-per-call-mcp"]
51
32
  }
52
33
  }
53
34
  }
54
35
  ```
55
36
 
56
- Claude Desktop を再起動すれば、🔨 ツールアイコンに LemonCake のツールが表示されます。
57
-
58
- ### Cursor / Cline / その他 MCP クライアント
59
-
60
- 同様に、サーバー起動コマンドを `npx -y pay-per-call-mcp` / 環境変数に `LEMON_CAKE_BUYER_JWT` を設定してください。
61
-
62
- **Node.js 要件**: v20 以上
63
-
64
- ---
65
-
66
- ## 🛠️ 提供ツール
67
-
68
- | ツール名 | 用途 | 主なパラメータ |
69
- |---|---|---|
70
- | `setup` | 初回セットアップガイド（アカウント作成・チャージ方法を返す） | — |
71
- | `list_services` | LemonCake マーケットプレイスで利用可能な有料 API 一覧 | `limit?` (1–100) |
72
- | `call_service` | 指定サービスへ Pay Token 経由で課金付き呼び出し | `serviceId`, `path?`, `method?`, `body?`, `idempotencyKey?` |
73
- | `check_balance` | 現在の USDC 残高と KYA 上限を取得 | — |
74
- | `check_tax` | 国税庁 API で適格請求書発行事業者番号を検証 | `registrationNumber` (T+13桁), `description?`, `amountJpy?` |
75
- | `get_service_stats` | サービス別の利用統計・課金履歴集計 | — |
76
-
77
- すべての引数スキーマは MCP Inspector または `tools/list` で取得可能です。
78
-
79
- ---
80
-
81
- ## 🎮 Demo Mode（認証情報なしで試せる）
82
-
83
- `LEMON_CAKE_BUYER_JWT` / `LEMON_CAKE_PAY_TOKEN` を**何も設定せずに**起動すると、自動で **DEMO MODE** になります。サインアップなしで以下が動きます：
84
-
85
- - `list_services` → 実マーケット + `demo_search` (Wikipedia) / `demo_echo` (httpbin) / `demo_fx` (open.er-api) の 3 デモが先頭に
86
- - `call_service` → `demo_*` サービスは**実フリー API を叩いて生データ**を返却（課金なし、認証なし）
87
- - `check_balance` → `$1.00` のモック残高を返却（`mode: "demo"`）
88
- - `check_tax` / `get_service_stats` → 通常通り（元から認証不要）
89
-
90
- → Glama Inspector や [npm の試用環境](https://www.npmjs.com/package/pay-per-call-mcp) でも、何も設定せず実装挙動を確認できます。本番の有料 API を叩きたくなったら `LEMON_CAKE_PAY_TOKEN` を設定してください。
91
-
92
- ---
93
-
94
- ## 💡 Try these prompts（MCP プロンプト）
95
-
96
- このサーバーは MCP の **prompts capability** に対応しています。Glama Inspector / Claude Desktop / Cursor の "prompt picker" に下記のプリセットが表示され、ワンクリックで実行できます：
97
-
98
- | Prompt 名 | 内容 | 認証 |
99
- |---|---|---|
100
- | 🎮 `explore-demo` | デモモードで setup → list_services → demo_search → demo_fx を一気通貫 | 不要 |
101
- | 🛍 `discover-marketplace` | 実マーケットの全サービスを listing して、用途別に top 3 を推薦 | 不要 |
102
- | 🇯🇵 `japan-tax-check` | 適格請求書発行事業者番号を国税庁で検証＋源泉徴収判定 | 不要 |
103
- | 💰 `spend-with-budget` | check_balance → call_service → check_balance のパターンで予算管理を実演 | demo OK / 実 service には PAY_TOKEN |
104
- | 🔄 `real-vs-demo` | 同じクエリを demo_search と実 Serper で叩いて比較 | demo OK / 比較に PAY_TOKEN |
105
- | 🏯 `japan-finance-bundle` | gBizINFO + 国税庁 + e-Gov を組み合わせた日本企業リサーチ | PAY_TOKEN（demo 部分は不要） |
106
-
107
- → Glama / Claude Desktop で `pay-per-call` MCP（旧 `lemon-cake`）を有効にすると、上記が自動で候補に出ます。
108
-
109
- ---
110
-
111
- ## 💡 使い方の例
112
-
113
- Claude Desktop で:
114
-
115
- > 「LemonCake で `demo_agent_search_api` を 0.50 USDC で呼び出して、"AI agent payments" を検索して」
116
-
117
- Claude は自動で:
118
- 1. `setup` でセットアップ状況を確認（初回のみ）
119
- 2. `call_service(serviceId="demo_agent_search_api", limitUsdc="0.50", body={query:"AI agent payments"})`
120
- 3. 結果を要約して返答
121
-
122
- ---
123
-
124
- ## 🎯 Use Cases
37
+ Leave `LEMON_CAKE_BUYER_JWT` unset → Demo Mode activates automatically. Calls hit real APIs (Wikipedia, httpbin, live FX rates) with no charges.
125
38
 
126
- - **Autonomous research agents** — Let your agent pay-per-call for premium search, scraping, or data APIs without giving it your credit card.
127
- - **Multi-API workflows** — One JWT, one balance, dozens of upstream APIs. No per-vendor signup or rotating keys.
128
- - **Compliance-aware spending** — KYA (Know-Your-Agent) limits cap how much an agent can spend per session/day.
129
- - **Japanese tax automation** — `check_tax` validates 適格請求書 numbers against 国税庁 API for invoice compliance.
130
- - **Idempotent retries** — `idempotencyKey` makes call_service safe to retry without double-charging.
39
+ ## Live mode (real USDC)
131
40
 
132
- ---
133
-
134
- ## 🪙 x402-compatible interface (since v0.5.1)
135
-
136
- This server speaks the [x402](https://www.x402.org/) idiom even though settlement happens off-chain via a Pay Token. The same agent code that handles on-chain x402 receipts works against `pay-per-call-mcp` unmodified.
137
-
138
- ### Successful calls return an `x402Receipt`
41
+ 1. Sign up at [lemoncake.xyz](https://lemoncake.xyz)
42
+ 2. Top up with USDC (min $5)
43
+ 3. Copy your Buyer JWT from the dashboard
44
+ 4. Add to config:
139
45
 
140
46
  ```json
141
47
  {
142
- "status": 200,
143
- "chargeId": "ch_abc123",
144
- "amountUsdc": "0.005",
145
- "response": { "...": "upstream payload" },
146
- "x402Receipt": {
147
- "scheme": "lemoncake-pay-token-v1",
148
- "x402Compatible": true,
149
- "chain": "off-chain (LemonCake Pay Token)",
150
- "asset": "USDC",
151
- "amount": "0.005",
152
- "recipient": "serper",
153
- "paymentIntentId": "ch_abc123",
154
- "settledAt": "2026-05-09T14:50:11.019Z"
48
+ "mcpServers": {
49
+ "pay-per-call": {
50
+ "command": "npx",
51
+ "args": ["-y", "pay-per-call-mcp"],
52
+ "env": {
53
+ "LEMON_CAKE_BUYER_JWT": "eyJhbGci..."
54
+ }
55
+ }
155
56
  }
156
57
  }
157
58
  ```
158
59
 
159
- ### Upstream `402` challenges are parsed
160
-
161
- If a service returns an x402 challenge, `call_service` surfaces it as `x402Challenge` for your agent to reason about. Three challenge sources are recognised:
60
+ ## Tools provided
162
61
 
163
- | Source | Example |
62
+ | Tool | Description |
164
63
  |---|---|
165
- | `WWW-Authenticate` header | `WWW-Authenticate: x402 chain="base" asset=USDC amount=0.01 recipient=0xabc` |
166
- | `X-402-*` headers | `X-402-Chain: polygon`, `X-402-Asset: USDC`, ... |
167
- | Body `x402` field | `{ "x402": { "chain": "ethereum", ... } }` |
168
-
169
- > ⚠️ **On-chain auto-pay** of detected challenges (debiting the upstream's address from the Pay Token's USDC balance) is **gated** on the LemonCake `HOT_WALLET` rollout — see [issue #4](https://github.com/evidai/lemon-cake/issues/4). For now, the agent should escalate or pick another service.
170
-
171
- ### `PAYMENT_PENDING` semantics for async settlement
172
-
173
- If upstream returns `202 + Retry-After + X-Payment-Status: pending`, `call_service` returns:
174
-
175
- ```json
176
- {
177
- "status": "PAYMENT_PENDING",
178
- "paymentIntentId": "pi_xyz",
179
- "retryAfterMs": 5000,
180
- "retryContract": "Call call_service again with the SAME idempotencyKey after 5000ms. The original request will resume; no double-charge."
181
- }
182
- ```
183
-
184
- Agents should sleep `retryAfterMs` and retry with the same `idempotencyKey`. Demo Mode shows the same shape so you can write the handler against `demo_search` and ship it unchanged.
185
-
186
- ---
187
-
188
- ## ✅ Tested Clients
189
-
190
- | Client | Status | Notes |
191
- |---|:---:|---|
192
- | Claude Desktop (macOS / Windows) | ✅ | Primary target |
193
- | Cursor | ✅ | stdio transport |
194
- | Cline (VS Code) | ✅ | stdio transport |
195
- | Claude Code CLI | ✅ | stdio transport |
196
- | Continue.dev | ✅ | MCP support since v0.9 |
197
- | Custom MCP clients | ✅ | Any client speaking MCP 1.10+ over stdio |
198
-
199
- ---
200
-
201
- ## 🔐 環境変数
202
-
203
- | 変数名 | 必須 | 説明 |
204
- |---|:---:|---|
205
- | `LEMON_CAKE_BUYER_JWT` | ✅ | Buyer JWT（ダッシュボードの Settings → API Keys から取得）|
206
- | `LEMON_CAKE_PAY_TOKEN` | — | Pay Token JWT（`call_service` で必要、未設定なら demo_* サービスのみ呼べる）|
207
- | `LEMON_CAKE_API_URL` | — | API エンドポイント（デフォルト: `https://api.lemoncake.xyz`）|
64
+ | `fetch_url` | Pay-per-call HTTP GET — any public API |
65
+ | `check_balance` | Show remaining USDC balance |
66
+ | `set_spend_limit` | Cap total spend for this session |
67
+ | `kill_switch` | Halt all further charges immediately |
208
68
 
209
- ---
69
+ ## For MCP server developers
210
70
 
211
- ## 🏃 ローカル開発
71
+ Want to add pay-per-call billing to **your own** MCP server? Use [`@lemon-cake/mcp-sdk`](https://www.npmjs.com/package/@lemon-cake/mcp-sdk):
212
72
 
213
73
  ```bash
214
- git clone https://github.com/evidai/lemon-cake.git
215
- cd lemon-cake/mcp-server
216
- npm install
217
- npm run build
218
- npm start
74
+ npm install @lemon-cake/mcp-sdk
219
75
  ```
220
76
 
221
- ### Docker
222
-
223
- ```bash
224
- docker build -t pay-per-call-mcp .
225
- docker run --rm -i -e LEMON_CAKE_BUYER_JWT=eyJhbGci... pay-per-call-mcp
77
+ ```ts
78
+ const lc = createLemonCakeSDK({ sellerKey: process.env.LEMONCAKE_SELLER_KEY });
79
+ execute: lc.charge({ price: 0.05 })(yourHandler)
226
80
  ```
227
81
 
228
- イメージは Glama Inspector のブラウザ内プレビューにも利用されます。
229
-
230
- ---
231
-
232
- ## 🔗 関連リンク
233
-
234
- - [LemonCake ダッシュボード](https://lemoncake.xyz/dashboard?utm_source=mcp-server&utm_medium=npm-readme)
235
- - [API ドキュメント](https://lemoncake.xyz/docs?utm_source=mcp-server&utm_medium=npm-readme)
236
- - [Glama MCP listing](https://glama.ai/mcp/servers/evidai/lemon-cake)
237
- - [Model Context Protocol](https://modelcontextprotocol.io)
238
- - [GitHub](https://github.com/evidai/lemon-cake)
239
- - [Security Policy](https://github.com/evidai/lemon-cake/blob/main/SECURITY.md) · [Contributing](https://github.com/evidai/lemon-cake/blob/main/CONTRIBUTING.md) · [Code of Conduct](https://github.com/evidai/lemon-cake/blob/main/CODE_OF_CONDUCT.md)
240
-
241
- ---
242
-
243
- ## 📄 ライセンス
82
+ ## License
244
83
 
245
- MIT © [LemonCake](https://lemoncake.xyz)
84
+ MIT — [LemonCake](https://lemoncake.xyz)