@one-source/mcp 5.2.1 → 5.3.1

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/README.md +12 -3
  2. package/README.npm.md +12 -3
  3. package/README.repo.md +12 -3
  4. package/dist/register-api-tools.d.ts +1 -1
  5. package/dist/register-api-tools.js +1 -1
  6. package/package.json +2 -2
  7. package/skills/onesource-mcp-setup/SKILL.md +1 -1
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @one-source/mcp
2
2
 
3
- Unified MCP server for [OneSource](https://docs.onesource.io) — 28 tools for blockchain data and live chain queries in a single server.
3
+ Unified MCP server for [OneSource](https://docs.onesource.io) — 29 tools for blockchain data and live chain queries in a single server.
4
4
 
5
5
  > **What is MCP?** The [Model Context Protocol](https://modelcontextprotocol.io) lets AI assistants call tools and access data sources. This server exposes both the OneSource blockchain API and its documentation as tools.
6
6
 
@@ -44,7 +44,7 @@ Then connect your MCP client to `http://localhost:3000/`.
44
44
 
45
45
  Health check: `GET http://localhost:3000/health`
46
46
 
47
- ## Tools (28)
47
+ ## Tools (29)
48
48
 
49
49
  ### Blockchain API — Live Chain (12 tools)
50
50
 
@@ -83,11 +83,12 @@ RPC only.
83
83
  | `1s_storage_read` | Read storage slot |
84
84
  | `1s_tx_receipt` | Transaction receipt |
85
85
 
86
- ### Payments (1 tool)
86
+ ### Payments (2 tools)
87
87
 
88
88
  | Tool | Description |
89
89
  |------|-------------|
90
90
  | `1s_payment_mode` | View or switch the x402 payment scheme — `exact` (per-call) vs `batch` (payment channel: one deposit funds many off-chain calls, settled with a single claim) |
91
+ | `1s_refund` | Refund unused `batch` channel balance back to your wallet on demand |
91
92
 
92
93
  ### Setup & Ops (2 tools)
93
94
 
@@ -193,6 +194,10 @@ X402_PRIVATE_KEY=<key> npx -y @one-source/mcp@latest
193
194
  4. **Fund that address with USDC on Base** — send USDC to the address shown, on the [Base](https://base.org) network. A few dollars ($1–5 USDC) is enough for hundreds of calls. Bridge from Ethereum mainnet if needed using the [Base Bridge](https://bridge.base.org).
194
195
  5. **Verify** — call `1s_network_info` for ethereum. If it returns chain data, payments are working.
195
196
 
197
+ #### Batch payments (optional)
198
+
199
+ By default each paid call signs one USDC payment (`exact`). For a burst of calls, switch to a **batch** payment channel — one on-chain deposit funds many off-chain calls, settled with a single claim — by calling `1s_payment_mode` with `{ "mode": "batch" }` (or setting `X402_PAYMENT_MODE=batch`). The first batch call deposits `price × X402_DEPOSIT_MULTIPLIER` (default 10), so a session usually over-funds the channel. Reclaim the unused balance any time with the `1s_refund` tool; idle channels are also auto-refunded after a few hours. The residual is always recoverable.
200
+
196
201
  ### Security
197
202
 
198
203
  Never commit keys to source control. Use environment variables, a `.env` file (excluded from git), or a secrets manager.
@@ -205,6 +210,10 @@ Never commit keys to source control. Use environment variables, a `.env` file (e
205
210
  |----------|---------|-------------|
206
211
  | `ONESOURCE_API_KEY` | — | OneSource API key for Bearer token auth. Takes priority over x402. |
207
212
  | `X402_PRIVATE_KEY` | — | EVM private key (64-char hex, `0x` prefix optional) for automatic x402 USDC payments on Base |
213
+ | `X402_PAYMENT_MODE` | `exact` | Initial x402 scheme: `exact` (per-call) or `batch` (payment channel). Switch in-session with `1s_payment_mode`. |
214
+ | `X402_DEPOSIT_MULTIPLIER` | `10` | Batch mode: deposit = price × this multiplier, funding that many calls per channel. Unused balance is reclaimable via `1s_refund`. |
215
+ | `X402_RPC_URL` | Base default | Base RPC endpoint used to submit channel deposits in batch mode |
216
+ | `X402_CHANNEL_DIR` | — | Directory to persist batch channel state across restarts. Unset = in-memory (channel lost on restart). |
208
217
 
209
218
  ## Troubleshooting
210
219
 
package/README.npm.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @one-source/mcp
2
2
 
3
- Unified MCP server for [OneSource](https://docs.onesource.io) — 28 tools for blockchain data and live chain queries in a single server.
3
+ Unified MCP server for [OneSource](https://docs.onesource.io) — 29 tools for blockchain data and live chain queries in a single server.
4
4
 
5
5
  > **What is MCP?** The [Model Context Protocol](https://modelcontextprotocol.io) lets AI assistants call tools and access data sources. This server exposes both the OneSource blockchain API and its documentation as tools.
6
6
 
@@ -44,7 +44,7 @@ Then connect your MCP client to `http://localhost:3000/`.
44
44
 
45
45
  Health check: `GET http://localhost:3000/health`
46
46
 
47
- ## Tools (28)
47
+ ## Tools (29)
48
48
 
49
49
  ### Blockchain API — Live Chain (12 tools)
50
50
 
@@ -83,11 +83,12 @@ RPC only.
83
83
  | `1s_storage_read` | Read storage slot |
84
84
  | `1s_tx_receipt` | Transaction receipt |
85
85
 
86
- ### Payments (1 tool)
86
+ ### Payments (2 tools)
87
87
 
88
88
  | Tool | Description |
89
89
  |------|-------------|
90
90
  | `1s_payment_mode` | View or switch the x402 payment scheme — `exact` (per-call) vs `batch` (payment channel: one deposit funds many off-chain calls, settled with a single claim) |
91
+ | `1s_refund` | Refund unused `batch` channel balance back to your wallet on demand |
91
92
 
92
93
  ### Setup & Ops (2 tools)
93
94
 
@@ -193,6 +194,10 @@ X402_PRIVATE_KEY=<key> npx -y @one-source/mcp@latest
193
194
  4. **Fund that address with USDC on Base** — send USDC to the address shown, on the [Base](https://base.org) network. A few dollars ($1–5 USDC) is enough for hundreds of calls. Bridge from Ethereum mainnet if needed using the [Base Bridge](https://bridge.base.org).
194
195
  5. **Verify** — call `1s_network_info` for ethereum. If it returns chain data, payments are working.
195
196
 
197
+ #### Batch payments (optional)
198
+
199
+ By default each paid call signs one USDC payment (`exact`). For a burst of calls, switch to a **batch** payment channel — one on-chain deposit funds many off-chain calls, settled with a single claim — by calling `1s_payment_mode` with `{ "mode": "batch" }` (or setting `X402_PAYMENT_MODE=batch`). The first batch call deposits `price × X402_DEPOSIT_MULTIPLIER` (default 10), so a session usually over-funds the channel. Reclaim the unused balance any time with the `1s_refund` tool; idle channels are also auto-refunded after a few hours. The residual is always recoverable.
200
+
196
201
  ### Security
197
202
 
198
203
  Never commit keys to source control. Use environment variables, a `.env` file (excluded from git), or a secrets manager.
@@ -205,6 +210,10 @@ Never commit keys to source control. Use environment variables, a `.env` file (e
205
210
  |----------|---------|-------------|
206
211
  | `ONESOURCE_API_KEY` | — | OneSource API key for Bearer token auth. Takes priority over x402. |
207
212
  | `X402_PRIVATE_KEY` | — | EVM private key (64-char hex, `0x` prefix optional) for automatic x402 USDC payments on Base |
213
+ | `X402_PAYMENT_MODE` | `exact` | Initial x402 scheme: `exact` (per-call) or `batch` (payment channel). Switch in-session with `1s_payment_mode`. |
214
+ | `X402_DEPOSIT_MULTIPLIER` | `10` | Batch mode: deposit = price × this multiplier, funding that many calls per channel. Unused balance is reclaimable via `1s_refund`. |
215
+ | `X402_RPC_URL` | Base default | Base RPC endpoint used to submit channel deposits in batch mode |
216
+ | `X402_CHANNEL_DIR` | — | Directory to persist batch channel state across restarts. Unset = in-memory (channel lost on restart). |
208
217
 
209
218
  ## Troubleshooting
210
219
 
package/README.repo.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @one-source/mcp
2
2
 
3
- Unified MCP server for [OneSource](https://docs.onesource.io) — 28 tools for blockchain data and live chain queries in a single server.
3
+ Unified MCP server for [OneSource](https://docs.onesource.io) — 29 tools for blockchain data and live chain queries in a single server.
4
4
 
5
5
  > **What is MCP?** The [Model Context Protocol](https://modelcontextprotocol.io) lets AI assistants call tools and access data sources. This server exposes both the OneSource blockchain API and its documentation as tools.
6
6
 
@@ -44,7 +44,7 @@ Then connect your MCP client to `http://localhost:3000/`.
44
44
 
45
45
  Health check: `GET http://localhost:3000/health`
46
46
 
47
- ## Tools (28)
47
+ ## Tools (29)
48
48
 
49
49
  ### Blockchain API — Live Chain (12 tools)
50
50
 
@@ -83,11 +83,12 @@ RPC only.
83
83
  | `1s_storage_read` | Read storage slot |
84
84
  | `1s_tx_receipt` | Transaction receipt |
85
85
 
86
- ### Payments (1 tool)
86
+ ### Payments (2 tools)
87
87
 
88
88
  | Tool | Description |
89
89
  |------|-------------|
90
90
  | `1s_payment_mode` | View or switch the x402 payment scheme — `exact` (per-call) vs `batch` (payment channel: one deposit funds many off-chain calls, settled with a single claim) |
91
+ | `1s_refund` | Refund unused `batch` channel balance back to your wallet on demand |
91
92
 
92
93
  ### Setup & Ops (2 tools)
93
94
 
@@ -214,6 +215,10 @@ Add the `onesource` entry inside `"mcpServers"` using the JSON block shown above
214
215
 
215
216
  Instead of the `env` config block, you can set either variable as a shell or system environment variable: `export ONESOURCE_API_KEY=<key>` (bash/zsh) or `$env:ONESOURCE_API_KEY = "<key>"` (PowerShell). Set it at the OS level for persistence across sessions.
216
217
 
218
+ ### Batch payments (optional)
219
+
220
+ By default each paid call signs one USDC payment (`exact`). For a burst of calls, switch to a **batch** payment channel — one on-chain deposit funds many off-chain calls, settled with a single claim — by calling `1s_payment_mode` with `{ "mode": "batch" }` (or setting `X402_PAYMENT_MODE=batch`). The first batch call deposits `price × X402_DEPOSIT_MULTIPLIER` (default 10), so a session usually over-funds the channel. Reclaim the unused balance any time with the `1s_refund` tool; idle channels are also auto-refunded after a few hours. The residual is always recoverable.
221
+
217
222
  ### Security
218
223
 
219
224
  Never commit keys to source control. Use environment variables, a `.env` file (excluded from git), or a secrets manager.
@@ -226,6 +231,10 @@ Never commit keys to source control. Use environment variables, a `.env` file (e
226
231
  |----------|---------|-------------|
227
232
  | `ONESOURCE_API_KEY` | — | OneSource API key for Bearer token auth. Takes priority over x402. |
228
233
  | `X402_PRIVATE_KEY` | — | EVM private key (64-char hex, `0x` prefix optional) for automatic x402 USDC payments on Base |
234
+ | `X402_PAYMENT_MODE` | `exact` | Initial x402 scheme: `exact` (per-call) or `batch` (payment channel). Switch in-session with `1s_payment_mode`. |
235
+ | `X402_DEPOSIT_MULTIPLIER` | `10` | Batch mode: deposit = price × this multiplier, funding that many calls per channel. Unused balance is reclaimable via `1s_refund`. |
236
+ | `X402_RPC_URL` | Base default | Base RPC endpoint used to submit channel deposits in batch mode |
237
+ | `X402_CHANNEL_DIR` | — | Directory to persist batch channel state across restarts. Unset = in-memory (channel lost on restart). |
229
238
  | `ONESOURCE_BASE_URL` | `https://skills.onesource.io` | API base URL |
230
239
  | `ONESOURCE_ANALYTICS` | — | Set to `false` to disable analytics |
231
240
  | `ONESOURCE_ANALYTICS_URL` | — | Dashboard endpoint for analytics |
package/dist/register-api-tools.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Register all 25 API tools from @one-source/api-mcp onto a shared McpServer.
2
+ * Register all 27 API tools from @one-source/api-mcp onto a shared McpServer.
3
3
  *
4
4
  * Replicates the exact instrumentation pattern from api-mcp's create-server.ts:
5
5
  * per-call client context, x402 detection, performance timing, session hashing,
package/dist/register-api-tools.js CHANGED
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Register all 25 API tools from @one-source/api-mcp onto a shared McpServer.
2
+ * Register all 27 API tools from @one-source/api-mcp onto a shared McpServer.
3
3
  *
4
4
  * Replicates the exact instrumentation pattern from api-mcp's create-server.ts:
5
5
  * per-call client context, x402 detection, performance timing, session hashing,
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@one-source/mcp",
3
3
  "mcpName": "io.onesource/mcp",
4
- "version": "5.2.1",
4
+ "version": "5.3.1",
5
5
  "type": "module",
6
6
  "description": "Unified MCP server for OneSource — 28 tools for blockchain data",
7
7
  "bin": {
@@ -29,7 +29,7 @@
29
29
  },
30
30
  "dependencies": {
31
31
  "@modelcontextprotocol/sdk": "^1.27.1",
32
- "@one-source/api-mcp": "^5.2.1",
32
+ "@one-source/api-mcp": "^5.3.1",
33
33
  "@one-source/docs-mcp": "^4.0.3",
34
34
  "zod": "^3.24.0"
35
35
  },
package/skills/onesource-mcp-setup/SKILL.md CHANGED
@@ -9,7 +9,7 @@ description: >-
9
9
 
10
10
  # OneSource MCP Setup Guide
11
11
 
12
- OneSource MCP provides 27 tools for blockchain data and live chain queries. Blockchain API tools require authentication — either an API key (`ONESOURCE_API_KEY`) or x402 micropayments in USDC on the Base network (`X402_PRIVATE_KEY`). If both are set, API key takes priority.
12
+ OneSource MCP provides 29 tools for blockchain data and live chain queries. Blockchain API tools require authentication — either an API key (`ONESOURCE_API_KEY`) or x402 micropayments in USDC on the Base network (`X402_PRIVATE_KEY`). If both are set, API key takes priority.
13
13
 
14
14
  ## Before You Start
15
15