@blockrun/mcp 0.5.2 → 0.6.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 (6) hide show
  1. package/README.md +28 -219
  2. package/dist/index.js +968 -20
  3. package/package.json +3 -3
  4. package/dist/chunk-H2DXT5AJ.js +0 -961
  5. package/dist/http-server.d.ts +0 -20
  6. package/dist/http-server.js +0 -59
package/README.md CHANGED
@@ -1,238 +1,79 @@
1
1
  # @blockrun/mcp
2
2
 
3
- **The payment layer for AI agents.**
3
+ **Give your AI agent superpowers — web search, deep research, prediction markets, crypto data, X/Twitter intelligence.**
4
4
 
5
5
  [![npm version](https://img.shields.io/npm/v/@blockrun/mcp)](https://www.npmjs.com/package/@blockrun/mcp)
6
6
  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
7
7
 
8
- BlockRun MCP is a Model Context Protocol server that gives any AI agent (Claude, GPT, Cursor, etc.) access to 41 LLM models, real-time web search, prediction markets, crypto DEX data, whale tracking, image generation, and token swaps — all paid via x402 micropayments in USDC on Base. No API keys. No subscriptions. No accounts.
9
-
10
- ---
11
-
12
- ## Why blockrun-mcp
13
-
14
- Claude Code has task systems, token budgets, and multi-agent coordination. What it does not have: per-agent wallets, spending enforcement across sessions, or a way for a parent agent to delegate a budget to a child agent and block it when that budget is exhausted.
15
-
16
- BlockRun fills this gap. Every tool call is a real micropayment — authorized locally by a wallet the agent controls. Parent agents can delegate spending limits to child agents by `agent_id`. Usage is auditable on-chain at any time.
17
-
18
- This makes BlockRun the financial infrastructure layer for multi-agent systems, not just a model proxy.
8
+ BlockRun MCP is a Model Context Protocol server that gives Claude Code (and any MCP-compatible agent) access to real-time web search, neural research, prediction markets, crypto DEX data, X/Twitter intelligence, and 41 LLM models — all paid via x402 micropayments in USDC. No API keys. No subscriptions. No accounts.
19
9
 
20
10
  ---
21
11
 
22
12
  ## Quick Start
23
13
 
24
- ### Option 1: Hosted (zero install)
14
+ ### Option 1: Local (recommended — wallet auto-created, private key stays on your machine)
25
15
 
26
16
  ```bash
27
- claude mcp add blockrun --transport http https://mcp.blockrun.ai/mcp
17
+ claude mcp add blockrun -- npx @blockrun/mcp
28
18
  ```
29
19
 
30
- No Node.js. No npm. Works from any agent, CI/CD pipeline, or cloud environment. Pass your wallet key per-request via `X-Wallet-Key` header.
20
+ A wallet is automatically created on first use. Fund it with USDC on Base and every tool is immediately available.
31
21
 
32
- ### Option 2: Local (self-hosted, private key never leaves your machine)
22
+ ### Option 2: Hosted (zero install)
33
23
 
34
24
  ```bash
35
- claude mcp add blockrun npx @blockrun/mcp
36
- ```
37
-
38
- ```bash
39
- # Optional: bring your own wallet
40
- claude mcp add blockrun npx @blockrun/mcp --env BLOCKRUN_WALLET_KEY=0x...
25
+ claude mcp add blockrun --transport http https://mcp.blockrun.ai/mcp
41
26
  ```
42
27
 
43
- A wallet is automatically created on first use. Fund it with USDC on Base network and every tool is immediately available.
28
+ No Node.js. No npm. Works from any MCP client. Pass your wallet key via `X-Wallet-Key` header, or run `blockrun_wallet` for setup instructions.
44
29
 
45
30
  ---
46
31
 
47
- ## What Your Agent Gets
32
+ ## Tools
48
33
 
49
34
  | Tool | What it does | Cost |
50
35
  |------|-------------|------|
51
- | `blockrun_chat` | 41 AI models (GPT-5, Claude, Gemini, NVIDIA free) | per token |
52
- | `blockrun_wallet` | Wallet management + multi-agent budget orchestration | free |
53
- | `blockrun_search` | Web + news search with AI-summarized results | ~$0.01/search |
54
- | `blockrun_exa` | Neural web search (Exa) — understands meaning, not just keywords | $0.01/call |
55
- | `blockrun_twitter` | Real-time X/Twitter search via Grok | per token |
56
- | `blockrun_markets` | Prediction markets — Polymarket, Kalshi, dFlow, Binance Futures | $0.001/call |
57
- | `blockrun_image` | Image generation and editing (DALL-E 3, Flux) | $0.02–0.08 |
36
+ | `blockrun_search` | Real-time web + news search | ~$0.01/search |
37
+ | `blockrun_exa` | Neural research (Exa) — finds papers, competitors, similar products | $0.01/call |
38
+ | `blockrun_twitter` | X/Twitter intelligence via Grok — search, trends, user analysis | per token |
39
+ | `blockrun_markets` | Prediction markets — Polymarket, Kalshi | $0.001/call |
58
40
  | `blockrun_dex` | Real-time DEX prices and liquidity via DexScreener | FREE |
59
- | `blockrun_whale` | On-chain whale tracking — large ETH transfers via Etherscan | FREE |
60
- | `blockrun_analyze` | Token technical analysis combining multiple data sources with AI | per token |
61
- | `blockrun_signal` | Trading signals — RSI + MACD + EMA strategy | FREE |
62
- | `blockrun_swap` | Token swap quotes on Base via 0x aggregator | FREE |
63
- | `blockrun_models` | List all 41 models with pricing and context windows | FREE |
64
-
65
- ---
66
-
67
- ## Multi-Agent Budget Orchestration
68
-
69
- A parent agent can allocate spending limits to child agents. Child agents self-identify via `agent_id`. When a child agent hits its limit, further calls are automatically blocked without any coordination logic needed in your code.
70
-
71
- ```typescript
72
- // Parent agent allocates budgets to child agents
73
- mcp.call("blockrun_wallet", { action: "delegate", agent_id: "researcher", agent_limit: 2.00 })
74
- mcp.call("blockrun_wallet", { action: "delegate", agent_id: "writer", agent_limit: 0.50 })
75
-
76
- // Child agents self-identify — auto-blocked at limit
77
- mcp.call("blockrun_chat", { message: "...", routing: "smart", agent_id: "researcher" })
78
-
79
- // Audit spending across all agents
80
- mcp.call("blockrun_wallet", { action: "report" })
81
- // researcher: $1.84/$2.00 (23 calls), writer: $0.31/$0.50 (4 calls)
82
- ```
83
-
84
- This pattern works across sessions. The spending record is tied to the wallet, not the process.
85
-
86
- ---
87
-
88
- ## Smart Routing (ClawRouter)
89
-
90
- Agents do not need to pick models. Pass `routing: "smart"` and ClawRouter selects the optimal model for the task based on the routing profile.
91
-
92
- ```typescript
93
- // Auto-selects optimal model — agents never need to pick
94
- blockrun_chat({ message: "...", routing: "smart", routing_profile: "eco" })
95
- // Returns: [nvidia/deepseek-v3.2 | SIMPLE | $0.0001 | 94% savings]
96
- ```
97
-
98
- | Profile | Description |
99
- |---------|-------------|
100
- | `free` | Zero cost — NVIDIA-hosted models only |
101
- | `eco` | Budget-optimized — best quality per dollar |
102
- | `auto` | Balanced — default |
103
- | `premium` | Highest quality available |
41
+ | `blockrun_image` | Image generation and editing (DALL-E 3, Flux) | $0.02–0.08 |
42
+ | `blockrun_chat` | 41 AI models — get a second opinion or use a specialized model | per token |
43
+ | `blockrun_wallet` | Wallet balance, agent budgets, spending reports | FREE |
44
+ | `blockrun_models` | List all models with pricing | FREE |
104
45
 
105
46
  ---
106
47
 
107
- ## All 41 Models
108
-
109
- ### OpenAI (13 models)
110
-
111
- | Model ID | Context | Input ($/M) | Output ($/M) |
112
- |----------|---------|-------------|--------------|
113
- | `openai/gpt-5.2` | 128k | $21.00 | $84.00 |
114
- | `openai/gpt-5` | 128k | $15.00 | $60.00 |
115
- | `openai/gpt-5-mini` | 128k | $0.40 | $1.60 |
116
- | `openai/gpt-4o` | 128k | $2.50 | $10.00 |
117
- | `openai/gpt-4o-mini` | 128k | $0.15 | $0.60 |
118
- | `openai/o3` | 200k | $10.00 | $40.00 |
119
- | `openai/o3-mini` | 200k | $1.10 | $4.40 |
120
- | `openai/o4-mini` | 200k | $1.10 | $4.40 |
121
- | `openai/o1` | 200k | $15.00 | $60.00 |
122
- | `openai/o1-mini` | 128k | $1.10 | $4.40 |
123
- | `openai/o1-pro` | 200k | $150.00 | $600.00 |
124
- | `openai/gpt-4.1` | 128k | $2.00 | $8.00 |
125
- | `openai/gpt-4.1-mini` | 128k | $0.40 | $1.60 |
126
-
127
- ### Anthropic (4 models)
128
-
129
- | Model ID | Context | Input ($/M) | Output ($/M) |
130
- |----------|---------|-------------|--------------|
131
- | `anthropic/claude-opus-4` | 200k | $15.00 | $75.00 |
132
- | `anthropic/claude-sonnet-4` | 200k | $3.00 | $15.00 |
133
- | `anthropic/claude-sonnet-3-7` | 200k | $3.00 | $15.00 |
134
- | `anthropic/claude-haiku-3-5` | 200k | $0.25 | $1.25 |
135
-
136
- ### Google (7 models)
137
-
138
- | Model ID | Context | Input ($/M) | Output ($/M) |
139
- |----------|---------|-------------|--------------|
140
- | `google/gemini-3-pro` | 1M | $2.50 | $15.00 |
141
- | `google/gemini-2.5-pro` | 1M | $1.25 | $10.00 |
142
- | `google/gemini-2.5-flash` | 1M | $0.15 | $0.60 |
143
- | `google/gemini-2.0-flash` | 1M | $0.10 | $0.40 |
144
- | `google/gemini-2.0-flash-lite` | 1M | $0.075 | $0.30 |
145
- | `google/gemini-1.5-pro` | 2M | $1.25 | $5.00 |
146
- | `google/gemini-1.5-flash` | 1M | $0.075 | $0.30 |
147
-
148
- ### DeepSeek (2 models)
149
-
150
- | Model ID | Context | Input ($/M) | Output ($/M) |
151
- |----------|---------|-------------|--------------|
152
- | `deepseek/deepseek-chat` | 64k | $0.14 | $0.28 |
153
- | `deepseek/deepseek-reasoner` | 64k | $0.55 | $2.19 |
154
-
155
- ### NVIDIA (12 models — FREE)
156
-
157
- All NVIDIA-hosted models are free via the `routing_profile: "free"` option or by specifying directly.
158
-
159
- | Model ID |
160
- |----------|
161
- | `nvidia/deepseek-v3.2` |
162
- | `nvidia/llama-3.3-70b` |
163
- | `nvidia/llama-3.1-405b` |
164
- | `nvidia/mistral-nemo-12b` |
165
- | `nvidia/phi-4-mini` |
166
- | `nvidia/qwen2.5-72b` |
167
- | `nvidia/nemotron-70b` |
168
- | `nvidia/nemotron-253b` |
169
- | `nvidia/llama-3.1-nemotron-nano-8b` |
170
- | `nvidia/llama-3.1-nemotron-ultra-253b` |
171
- | `nvidia/mistral-small-3.1` |
172
- | `nvidia/qwen3-235b` |
173
-
174
- ### ZAI (2 models)
175
-
176
- | Model ID | Context | Input ($/M) | Output ($/M) |
177
- |----------|---------|-------------|--------------|
178
- | `zai/grok-3` | 131k | $5.00 | $25.00 |
179
- | `zai/grok-3-mini` | 131k | $3.00 | $15.00 |
180
-
181
- ### MiniMax (1 model)
182
-
183
- | Model ID | Context | Input ($/M) | Output ($/M) |
184
- |----------|---------|-------------|--------------|
185
- | `minimax/minimax-m1` | 1M | $0.80 | $2.40 |
48
+ ## Why BlockRun
186
49
 
187
- ---
50
+ Your AI agent already has an LLM. What it doesn't have: access to the live internet, research tools, market data, or a way to pay for services autonomously.
188
51
 
189
- ## How Payments Work
52
+ BlockRun fills this gap. Every tool call is a real micropayment — authorized locally by a wallet the agent controls. No API keys to manage, no vendor accounts to create. Just a wallet and USDC.
190
53
 
191
- Every request is paid via the x402 protocol — an open payment standard for machine-to-machine micropayments. Payments settle in USDC on Base network. Your wallet is created automatically on first use and stored locally at `~/.blockrun/.session`. The private key is used only to sign payment authorizations locally — it is never transmitted to any server. You can verify all transactions on [Basescan](https://basescan.org).
54
+ For multi-agent systems: parent agents can delegate spending limits to child agents by `agent_id`. When a child hits its limit, further calls are automatically blocked.
192
55
 
193
56
  ---
194
57
 
195
58
  ## Funding Your Wallet
196
59
 
197
60
  ```
198
- # Get your wallet address
199
- blockrun_wallet({ action: "balance" })
200
- # Returns: 0x... (QR code available for mobile wallets)
61
+ # Check your wallet address
62
+ blockrun_wallet action:"status"
201
63
  ```
202
64
 
203
- Send USDC on Base network to that address. $5 gets you started — approximately 50,000 Gemini Flash requests or 125 DALL-E 3 images. There is no minimum. You pay only for what you use.
65
+ Send USDC on Base network to your wallet address. $5 gets you started — that's ~500 Exa searches or ~50,000 Gemini Flash calls.
204
66
 
205
67
  | Method | Steps |
206
68
  |--------|-------|
207
69
  | Coinbase | Send → USDC → Select "Base" network → Paste address |
208
70
  | Bridge | [bridge.base.org](https://bridge.base.org) → Bridge USDC to Base |
209
- | Buy direct | [Coinbase Onramp](https://www.coinbase.com/onramp) → Buy USDC on Base |
210
71
 
211
72
  ---
212
73
 
213
- ## Architecture
214
-
215
- ```
216
- Claude Code / Any MCP Client
217
- |
218
- | stdio (local) or HTTP (remote, coming soon)
219
- |
220
- blockrun-mcp server
221
- |
222
- | x402 micropayments (USDC on Base)
223
- |
224
- blockrun.ai gateway
225
- |
226
- +-- OpenAI
227
- +-- Anthropic
228
- +-- Google
229
- +-- NVIDIA
230
- +-- DeepSeek
231
- +-- ZAI / MiniMax
232
- +-- DexScreener / Etherscan / Polymarket / Kalshi / Exa / 0x
233
- ```
74
+ ## How Payments Work
234
75
 
235
- The MCP server runs locally (stdio transport). Each tool call that requires payment triggers a local wallet signature. The signed payment authorization is sent to the blockrun.ai gateway alongside the API request. No API keys pass through your machine.
76
+ Every request is paid via the [x402 protocol](https://x402.org) — an open standard for machine-to-machine micropayments. Payments settle in USDC on Base (or Solana). Your wallet is created automatically on first use and stored locally at `~/.blockrun/.session`. The private key is used only to sign payment authorizations locally — it is never transmitted to any server.
236
77
 
237
78
  ---
238
79
 
@@ -240,7 +81,7 @@ The MCP server runs locally (stdio transport). Each tool call that requires paym
240
81
 
241
82
  | Variable | Description |
242
83
  |----------|-------------|
243
- | `BLOCKRUN_WALLET_KEY` | Bring your own private key (hex string, starts with 0x). Optional — a wallet is auto-generated if not set. |
84
+ | `BLOCKRUN_WALLET_KEY` | Bring your own private key (hex for Base, bs58 for Solana). Optional — a wallet is auto-generated if not set. |
244
85
 
245
86
  Wallet resolution order:
246
87
  1. `BLOCKRUN_WALLET_KEY` environment variable
@@ -249,44 +90,12 @@ Wallet resolution order:
249
90
 
250
91
  ---
251
92
 
252
- ## Development
253
-
254
- ```bash
255
- git clone https://github.com/BlockRunAI/blockrun-mcp
256
- cd blockrun-mcp
257
- npm install
258
- npm run build
259
- npm run dev # tsx watch — auto-reloads on changes
260
- ```
261
-
262
- To test the server manually:
263
-
264
- ```bash
265
- echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node dist/index.js
266
- ```
267
-
268
- ---
269
-
270
- ## Roadmap
271
-
272
- - [x] 14 tools covering LLMs, search, crypto, markets, image generation
273
- - [x] Multi-agent budget delegation via `agent_id`
274
- - [x] ClawRouter intelligent model routing
275
- - [x] Multi-turn conversation support
276
- - [ ] HTTP/SSE transport (deploy to mcp.blockrun.ai — no local install needed)
277
- - [ ] Per-tool LLM-optimized descriptions
278
- - [ ] Official MCP registry listing
279
- - [ ] Persistent cross-session spending records tied to wallet
280
-
281
- ---
282
-
283
93
  ## Links
284
94
 
285
95
  - **Website:** [blockrun.ai](https://blockrun.ai)
286
96
  - **npm:** [@blockrun/mcp](https://www.npmjs.com/package/@blockrun/mcp)
97
+ - **Hosted MCP:** [mcp.blockrun.ai](https://mcp.blockrun.ai)
287
98
  - **GitHub:** [github.com/blockrunai/blockrun-mcp](https://github.com/blockrunai/blockrun-mcp)
288
- - **Issues:** [github.com/blockrunai/blockrun-mcp/issues](https://github.com/blockrunai/blockrun-mcp/issues)
289
- - **Pricing:** [blockrun.ai/pricing](https://blockrun.ai/pricing)
290
99
  - **Telegram:** [t.me/+mroQv4-4hGgzOGUx](https://t.me/+mroQv4-4hGgzOGUx)
291
100
  - **X:** [@BlockRunAI](https://x.com/BlockRunAI)
292
101