paybot-mcp 0.2.1 → 0.3.0

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 (7) hide show
  1. package/LICENSE +189 -189
  2. package/README.md +193 -109
  3. package/dist/server.d.ts +9 -3
  4. package/dist/server.d.ts.map +1 -1
  5. package/dist/server.js +391 -12
  6. package/dist/server.js.map +1 -1
  7. package/package.json +93 -87
package/README.md CHANGED
@@ -1,109 +1,193 @@
1
- # paybot-mcp
2
-
3
- MCP server for [PayBot](https://paybotcore.com) — payment tools for AI agents via the Model Context Protocol.
4
-
5
- ## Install
6
-
7
- ```bash
8
- npm install paybot-mcp paybot-sdk
9
- ```
10
-
11
- ## Usage with Claude Desktop
12
-
13
- Add to `claude_desktop_config.json`:
14
-
15
- ```json
16
- {
17
- "mcpServers": {
18
- "paybot": {
19
- "command": "npx",
20
- "args": ["paybot-mcp"],
21
- "env": {
22
- "PAYBOT_API_KEY": "pb_...",
23
- "PAYBOT_FACILITATOR_URL": "https://facilitator.paybot.dev",
24
- "PAYBOT_BOT_ID": "my-agent"
25
- }
26
- }
27
- }
28
- }
29
- ```
30
-
31
- ## Usage with Claude Code
32
-
33
- ```json
34
- {
35
- "mcpServers": {
36
- "paybot": {
37
- "command": "npx",
38
- "args": ["paybot-mcp"],
39
- "env": {
40
- "PAYBOT_API_KEY": "pb_...",
41
- "PAYBOT_BOT_ID": "my-agent"
42
- }
43
- }
44
- }
45
- }
46
- ```
47
-
48
- ## Environment Variables
49
-
50
- | Variable | Description | Default |
51
- |----------|-------------|---------|
52
- | `PAYBOT_API_KEY` | PayBot API key | (required) |
53
- | `PAYBOT_FACILITATOR_URL` | Facilitator server URL | `http://localhost:3000` |
54
- | `PAYBOT_BOT_ID` | Default bot identifier | `mcp-agent` |
55
- | `PAYBOT_WALLET_KEY` | Wallet private key for real payments | (optional) |
56
-
57
- ## Available Tools
58
-
59
- | Tool | Description |
60
- |------|-------------|
61
- | `paybot_pay` | Make a USDC payment for an API, service, or resource |
62
- | `paybot_balance` | Check trust level, spending limits, and remaining budget |
63
- | `paybot_history` | View recent payment history and audit events |
64
- | `paybot_register` | Register a new bot with the facilitator |
65
-
66
- ### paybot_pay
67
-
68
- ```
69
- amount: string - Amount in USD (e.g., "0.05")
70
- recipient: string - Recipient wallet address (0x...)
71
- resource: string - URL or description of what you're paying for
72
- botId?: string - Bot identifier (defaults to env)
73
- network?: string - Network CAIP-2 ID (default: Base Sepolia)
74
- ```
75
-
76
- ### paybot_balance
77
-
78
- ```
79
- botId?: string - Bot identifier (defaults to env)
80
- ```
81
-
82
- ### paybot_history
83
-
84
- ```
85
- botId?: string - Bot identifier (defaults to env)
86
- limit?: number - Max events to return (default: 10)
87
- ```
88
-
89
- ### paybot_register
90
-
91
- ```
92
- botId: string - Unique bot identifier
93
- trustLevel?: number - Initial trust level 0-5 (default: 1)
94
- ```
95
-
96
- ## Programmatic Usage
97
-
98
- ```typescript
99
- import { createMcpServer } from 'paybot-mcp/server';
100
- import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
101
-
102
- const server = createMcpServer();
103
- const transport = new StdioServerTransport();
104
- await server.connect(transport);
105
- ```
106
-
107
- ## License
108
-
109
- [Apache 2.0](LICENSE)
1
+ # paybot-mcp
2
+
3
+ MCP server for [PayBot](https://paybotcore.com) — payment tools for AI agents via the Model Context Protocol.
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ npm install paybot-mcp paybot-sdk
9
+ ```
10
+
11
+ ## Usage with Claude Desktop
12
+
13
+ Add to `claude_desktop_config.json`:
14
+
15
+ ```json
16
+ {
17
+ "mcpServers": {
18
+ "paybot": {
19
+ "command": "npx",
20
+ "args": ["paybot-mcp"],
21
+ "env": {
22
+ "PAYBOT_API_KEY": "pb_...",
23
+ "PAYBOT_FACILITATOR_URL": "https://api.paybotcore.com",
24
+ "PAYBOT_BOT_ID": "my-agent"
25
+ }
26
+ }
27
+ }
28
+ }
29
+ ```
30
+
31
+ ## Usage with Claude Code
32
+
33
+ ```json
34
+ {
35
+ "mcpServers": {
36
+ "paybot": {
37
+ "command": "npx",
38
+ "args": ["paybot-mcp"],
39
+ "env": {
40
+ "PAYBOT_API_KEY": "pb_...",
41
+ "PAYBOT_BOT_ID": "my-agent"
42
+ }
43
+ }
44
+ }
45
+ }
46
+ ```
47
+
48
+ ## Environment Variables
49
+
50
+ | Variable | Description | Default |
51
+ |----------|-------------|---------|
52
+ | `PAYBOT_API_KEY` | PayBot API key | (required) |
53
+ | `PAYBOT_FACILITATOR_URL` | Facilitator server URL | `https://api.paybotcore.com` |
54
+ | `PAYBOT_BOT_ID` | Default bot identifier | `mcp-agent` |
55
+ | `PAYBOT_WALLET_KEY` | Wallet private key for real payments | (optional) |
56
+
57
+ ## Available Tools
58
+
59
+ | Tool | Description |
60
+ |------|-------------|
61
+ | `paybot_pay` | Make a payment (USDC by default; supports alternate tokens + idempotency) |
62
+ | `paybot_balance` | Check trust level, spending limits, and remaining budget |
63
+ | `paybot_history` | View recent payment history and audit events |
64
+ | `paybot_register` | Register a new bot with the facilitator (optional idempotency key) |
65
+ | `paybot_list_networks_and_tokens` | Discover supported networks and tokens (offline, no API key) |
66
+ | `paybot_health_extended` | Extended facilitator health (status/version/uptime + extras) |
67
+ | `paybot_set_spending_limit` | Set per-transaction / daily / hourly limits and a recipient allowlist |
68
+ | `paybot_commission_inspect` | Inspect commission summary and a filterable ledger |
69
+ | `paybot_pool_create` | Create an in-process bot pool with an optional shared treasury |
70
+ | `paybot_pool_allocate` | Add a bot to a pool, optionally paying as it through the treasury |
71
+ | `paybot_pool_revoke` | Remove a bot from a pool |
72
+ | `paybot_pool_status` | Report pool treasury and per-bot spend counters |
73
+
74
+ ### paybot_pay
75
+
76
+ | Param | Type | Notes |
77
+ |-------|------|-------|
78
+ | `amount` | string | Amount in USD (e.g., `"0.05"`) |
79
+ | `recipient` | string | Recipient wallet address (`0x...`) |
80
+ | `resource` | string | URL or description of what you're paying for |
81
+ | `botId?` | string | Bot identifier (defaults to env) |
82
+ | `network?` | string | Network CAIP-2 ID (default: Base Sepolia) |
83
+ | `token?` | string | Token ticker (default `USDC`); e.g. `USDC`, `EURC`, `DAI` |
84
+ | `idempotencyKey?` | string | Repeat call with the same key returns the cached result |
85
+
86
+ ### paybot_balance
87
+
88
+ | Param | Type | Notes |
89
+ |-------|------|-------|
90
+ | `botId?` | string | Bot identifier (defaults to env) |
91
+
92
+ ### paybot_history
93
+
94
+ | Param | Type | Notes |
95
+ |-------|------|-------|
96
+ | `botId?` | string | Bot identifier (defaults to env) |
97
+ | `limit?` | number | Max events to return (default: 10) |
98
+
99
+ ### paybot_register
100
+
101
+ | Param | Type | Notes |
102
+ |-------|------|-------|
103
+ | `botId` | string | Unique bot identifier |
104
+ | `trustLevel?` | number | Initial trust level 0-5 (default: 1) |
105
+ | `idempotencyKey?` | string | Repeat register with the same key returns the cached result |
106
+
107
+ ### paybot_list_networks_and_tokens
108
+
109
+ Read-only discovery. Requires no API key and makes zero network calls. Surfaces
110
+ only the **public** open-core registry — operator-private mainnet addresses are
111
+ never shown (e.g. EURC advertises its Base Sepolia testnet deployment only).
112
+
113
+ _No parameters._
114
+
115
+ ### paybot_health_extended
116
+
117
+ | Param | Type | Notes |
118
+ |-------|------|-------|
119
+ | `botId?` | string | Bot identifier (defaults to env) |
120
+
121
+ Returns `status`, `version`, `uptime`, `timestamp`, plus any extra fields the
122
+ facilitator reports.
123
+
124
+ ### paybot_set_spending_limit
125
+
126
+ Tightens an agent's own limits. The facilitator enforces the operator ceiling
127
+ and may reject attempts to loosen beyond policy.
128
+
129
+ | Param | Type | Notes |
130
+ |-------|------|-------|
131
+ | `botId?` | string | Bot identifier (defaults to env) |
132
+ | `maxTransactionUsd?` | number | Max USD per transaction |
133
+ | `maxDailySpendUsd?` | number | Max USD spend per day |
134
+ | `maxTransactionsPerHour?` | number | Max transactions per hour |
135
+ | `allowedRecipients?` | string[] | Allowlist of recipient addresses |
136
+
137
+ ### paybot_commission_inspect
138
+
139
+ | Param | Type | Notes |
140
+ |-------|------|-------|
141
+ | `botId?` | string | Bot identifier (defaults to env) |
142
+ | `status?` | enum | Filter ledger by `pending` \| `forwarded` \| `deferred` |
143
+ | `startDate?` | string | Ledger start date (ISO 8601) |
144
+ | `endDate?` | string | Ledger end date (ISO 8601) |
145
+ | `limit?` | number | Max ledger entries (default: 50) |
146
+ | `offset?` | number | Ledger pagination offset |
147
+
148
+ ### paybot_pool_create
149
+
150
+ Creates an in-process bot pool for this MCP session. Treasury accounting is
151
+ in-memory; the facilitator remains the authoritative limit.
152
+
153
+ | Param | Type | Notes |
154
+ |-------|------|-------|
155
+ | `poolId` | string | Identifier for this pool (used by allocate/revoke/status) |
156
+ | `sharedDailyLimitUsd?` | number | Optional shared daily spend cap across all bots |
157
+
158
+ ### paybot_pool_allocate
159
+
160
+ | Param | Type | Notes |
161
+ |-------|------|-------|
162
+ | `poolId` | string | Pool identifier |
163
+ | `botId` | string | Bot identifier to add to the pool |
164
+ | `trustLevel?` | number | Initial trust level 0-5 |
165
+ | `pay?` | object | Optional `{ amount, recipient, resource, network?, token? }` to pay as this bot |
166
+
167
+ ### paybot_pool_revoke
168
+
169
+ | Param | Type | Notes |
170
+ |-------|------|-------|
171
+ | `poolId` | string | Pool identifier |
172
+ | `botId` | string | Bot identifier to remove |
173
+
174
+ ### paybot_pool_status
175
+
176
+ | Param | Type | Notes |
177
+ |-------|------|-------|
178
+ | `poolId` | string | Pool identifier |
179
+
180
+ ## Programmatic Usage
181
+
182
+ ```typescript
183
+ import { createMcpServer } from 'paybot-mcp/server';
184
+ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
185
+
186
+ const server = createMcpServer();
187
+ const transport = new StdioServerTransport();
188
+ await server.connect(transport);
189
+ ```
190
+
191
+ ## License
192
+
193
+ [Apache 2.0](LICENSE)
package/dist/server.d.ts CHANGED
@@ -2,11 +2,17 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
2
2
  /**
3
3
  * Create a PayBot MCP server exposing payment tools to AI agents.
4
4
  *
5
- * Tools:
6
- * - paybot_pay — make a USDC payment
5
+ * Tools (v0.3.0):
6
+ * - paybot_pay — make a payment (USDC default; optional token + idempotencyKey)
7
7
  * - paybot_balance — check spending limits and budget
8
8
  * - paybot_history — view recent payment history
9
- * - paybot_register — register a new bot
9
+ * - paybot_register — register a new bot (optional idempotencyKey)
10
+ * - paybot_list_networks_and_tokens — discover supported networks/tokens (offline, public registry only)
11
+ * - paybot_health_extended — facilitator health (status/version/uptime + extras)
12
+ * - paybot_set_spending_limit — tighten an agent's own spending limits
13
+ * - paybot_commission_inspect — commission summary + ledger
14
+ * - paybot_pool_create / paybot_pool_allocate / paybot_pool_revoke / paybot_pool_status —
15
+ * in-process multi-bot pool with a shared daily treasury
10
16
  */
11
17
  export declare function createMcpServer(): McpServer;
12
18
  //# sourceMappingURL=server.d.ts.map
package/dist/server.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAKpE;;;;;;;;GAQG;AACH,wBAAgB,eAAe,IAAI,SAAS,CAwJ3C"}
1
+ {"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAgDpE;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,IAAI,SAAS,CA8iB3C"}