@one-source/mcp 5.3.1 → 5.3.3

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 (15) hide show
  1. package/README.repo.md +98 -87
  2. package/dist/analytics.d.ts +1 -0
  3. package/dist/analytics.d.ts.map +1 -1
  4. package/dist/analytics.js.map +1 -1
  5. package/dist/cli.js +1 -1
  6. package/dist/create-server.d.ts +2 -2
  7. package/dist/create-server.d.ts.map +1 -1
  8. package/dist/create-server.js +3 -2
  9. package/dist/create-server.js.map +1 -1
  10. package/dist/register-api-tools.d.ts +2 -0
  11. package/dist/register-api-tools.d.ts.map +1 -1
  12. package/dist/register-api-tools.js +5 -0
  13. package/dist/register-api-tools.js.map +1 -1
  14. package/package.json +2 -2
  15. package/skills/onesource-mcp-setup/SKILL.md +308 -308
package/README.repo.md CHANGED
@@ -40,90 +40,102 @@ npx -y @one-source/mcp@latest --http
40
40
  npx -y @one-source/mcp@latest --http --port=8080
41
41
  ```
42
42
 
43
- Then connect your MCP client to `http://localhost:3000/`.
43
+ Then connect your MCP client to `http://localhost:8080/`.
44
44
 
45
- Health check: `GET http://localhost:3000/health`
45
+ Health check: `GET http://localhost:8080/health`
46
46
 
47
47
  ## Tools (29)
48
48
 
49
49
  ### Blockchain API — Live Chain (12 tools)
50
50
 
51
- | Tool | Description |
52
- |------|-------------|
53
- | `1s_allowance_live` | ERC20 allowance check |
54
- | `1s_contract_info_live` | Contract type detection via ERC165 |
55
- | `1s_erc1155_balance_live` | ERC1155 balance via RPC |
56
- | `1s_erc20_balance_live` | ERC20 balance via balanceOf |
51
+
52
+ | Tool | Description |
53
+ | ------------------------- | ----------------------------------- |
54
+ | `1s_allowance_live` | ERC20 allowance check |
55
+ | `1s_contract_info_live` | Contract type detection via ERC165 |
56
+ | `1s_erc1155_balance_live` | ERC1155 balance via RPC |
57
+ | `1s_erc20_balance_live` | ERC20 balance via balanceOf |
57
58
  | `1s_erc20_transfers_live` | ERC20 Transfer logs via eth_getLogs |
58
- | `1s_erc721_tokens_live` | ERC721 token enumeration |
59
- | `1s_events_live` | Event logs via eth_getLogs |
60
- | `1s_multi_balance_live` | ETH + multiple ERC20 balances |
61
- | `1s_nft_metadata_live` | NFT metadata via tokenURI |
62
- | `1s_nft_owner_live` | NFT owner via ownerOf |
63
- | `1s_total_supply_live` | Token total supply |
64
- | `1s_tx_details_live` | Transaction + receipt via RPC |
59
+ | `1s_erc721_tokens_live` | ERC721 token enumeration |
60
+ | `1s_events_live` | Event logs via eth_getLogs |
61
+ | `1s_multi_balance_live` | ETH + multiple ERC20 balances |
62
+ | `1s_nft_metadata_live` | NFT metadata via tokenURI |
63
+ | `1s_nft_owner_live` | NFT owner via ownerOf |
64
+ | `1s_total_supply_live` | Token total supply |
65
+ | `1s_tx_details_live` | Transaction + receipt via RPC |
66
+
65
67
 
66
68
  ### Blockchain API — Chain Utilities (13 tools)
67
69
 
68
70
  RPC only.
69
71
 
70
- | Tool | Description |
71
- |------|-------------|
72
- | `1s_block_by_number` | Block details by number via RPC |
73
- | `1s_block_number` | Latest block number |
74
- | `1s_chain_id` | EIP-155 chain ID |
75
- | `1s_contract_code` | Contract bytecode |
76
- | `1s_ens_resolve` | ENS name/address resolution |
77
- | `1s_estimate_gas` | Gas estimation |
78
- | `1s_network_info` | Chain ID, block number, gas price |
79
- | `1s_nonce` | Transaction count |
80
- | `1s_pending_block` | Pending block from mempool |
81
- | `1s_proxy_detect` | Proxy contract detection |
82
- | `1s_simulate_call` | Simulate eth_call |
83
- | `1s_storage_read` | Read storage slot |
84
- | `1s_tx_receipt` | Transaction receipt |
72
+
73
+ | Tool | Description |
74
+ | -------------------- | --------------------------------- |
75
+ | `1s_block_by_number` | Block details by number via RPC |
76
+ | `1s_block_number` | Latest block number |
77
+ | `1s_chain_id` | EIP-155 chain ID |
78
+ | `1s_contract_code` | Contract bytecode |
79
+ | `1s_ens_resolve` | ENS name/address resolution |
80
+ | `1s_estimate_gas` | Gas estimation |
81
+ | `1s_network_info` | Chain ID, block number, gas price |
82
+ | `1s_nonce` | Transaction count |
83
+ | `1s_pending_block` | Pending block from mempool |
84
+ | `1s_proxy_detect` | Proxy contract detection |
85
+ | `1s_simulate_call` | Simulate eth_call |
86
+ | `1s_storage_read` | Read storage slot |
87
+ | `1s_tx_receipt` | Transaction receipt |
88
+
85
89
 
86
90
  ### Payments (2 tools)
87
91
 
88
- | Tool | Description |
89
- |------|-------------|
92
+
93
+ | Tool | Description |
94
+ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
90
95
  | `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 |
96
+ | `1s_refund` | Refund unused `batch` channel balance back to your wallet on demand |
97
+
92
98
 
93
99
  ### Setup & Ops (2 tools)
94
100
 
95
101
  No authentication required.
96
102
 
97
- | Tool | Purpose | When to use |
98
- |------|---------|-------------|
103
+
104
+ | Tool | Purpose | When to use |
105
+ | ---------------- | ------------------------------------------------------- | -------------------------------------------------------- |
99
106
  | `1s_setup_check` | Server health, version, auth status, setup instructions | First thing to call — checks if everything is configured |
100
- | `1s_report_bug` | Report bugs to Slack (or GitHub Issues fallback) | When a tool errors or user wants to report an issue |
107
+ | `1s_report_bug` | Report bugs to Slack (or GitHub Issues fallback) | When a tool errors or user wants to report an issue |
108
+
101
109
 
102
110
  ## Networks
103
111
 
104
112
  All blockchain API tools accept an optional `network` parameter:
105
113
 
106
- | Network | Description |
107
- |---------|-------------|
114
+
115
+ | Network | Description |
116
+ | ---------- | -------------------------- |
108
117
  | `ethereum` | Ethereum mainnet (default) |
109
- | `sepolia` | Ethereum Sepolia testnet |
110
- | `avax` | Avalanche C-Chain |
118
+ | `sepolia` | Ethereum Sepolia testnet |
119
+ | `avax` | Avalanche C-Chain |
120
+
111
121
 
112
122
  ## Authentication
113
123
 
114
124
  Blockchain API tools require authentication. Two options are available — if both are set, API key takes priority.
115
125
 
116
- | Method | Variable | Description |
117
- |--------|----------|-------------|
118
- | API key | `ONESOURCE_API_KEY` | Unlimited calls, no per-call cost |
119
- | x402 micropayments | `X402_PRIVATE_KEY` | Pay-per-call via USDC on Base, no account required |
126
+
127
+ | Method | Variable | Description |
128
+ | ------------------ | ------------------- | -------------------------------------------------- |
129
+ | API key | `ONESOURCE_API_KEY` | Unlimited calls, no per-call cost |
130
+ | x402 micropayments | `X402_PRIVATE_KEY` | Pay-per-call via USDC on Base, no account required |
131
+
120
132
 
121
133
  ### Option 1: API Key
122
134
 
123
135
  1. Go to [app.onesource.io](https://app.onesource.io) and create an account.
124
136
  2. Subscribe to a developer plan (Stripe checkout).
125
137
  3. Navigate to **API Keys** and generate a key.
126
- 4. Copy the key — it starts with `sk_`.
138
+ 4. Copy the key — it starts with `sk`_.
127
139
 
128
140
  #### Claude Code
129
141
 
@@ -201,13 +213,15 @@ X402_PRIVATE_KEY=<key> npx -y @one-source/mcp@latest
201
213
 
202
214
  If you prefer editing the config file directly instead of using CLI commands:
203
215
 
204
- | Client | Config file path |
205
- |--------|-----------------|
206
- | Claude Code | Run `claude mcp get onesource` to see the file path |
207
- | Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
208
- | Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
209
- | Cursor (macOS) | `~/.cursor/mcp.json` |
210
- | Cursor (Windows) | `%USERPROFILE%\.cursor\mcp.json` |
216
+
217
+ | Client | Config file path |
218
+ | ------------------------ | ----------------------------------------------------------------- |
219
+ | Claude Code | Run `claude mcp get onesource` to see the file path |
220
+ | Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
221
+ | Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
222
+ | Cursor (macOS) | `~/.cursor/mcp.json` |
223
+ | Cursor (Windows) | `%USERPROFILE%\.cursor\mcp.json` |
224
+
211
225
 
212
226
  Add the `onesource` entry inside `"mcpServers"` using the JSON block shown above.
213
227
 
@@ -227,22 +241,23 @@ Never commit keys to source control. Use environment variables, a `.env` file (e
227
241
 
228
242
  ## Environment Variables
229
243
 
230
- | Variable | Default | Description |
231
- |----------|---------|-------------|
232
- | `ONESOURCE_API_KEY` | — | OneSource API key for Bearer token auth. Takes priority over x402. |
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). |
238
- | `ONESOURCE_BASE_URL` | `https://skills.onesource.io` | API base URL |
239
- | `ONESOURCE_ANALYTICS` | — | Set to `false` to disable analytics |
240
- | `ONESOURCE_ANALYTICS_URL` | — | Dashboard endpoint for analytics |
241
- | `X402_ANALYTICS_KEY` | — | API key for dashboard analytics |
244
+
245
+ | Variable | Default | Description |
246
+ | ------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
247
+ | `ONESOURCE_API_KEY` | — | OneSource API key for Bearer token auth. Takes priority over x402. |
248
+ | `X402_PRIVATE_KEY` | — | EVM private key (64-char hex, `0x` prefix optional) for automatic x402 USDC payments on Base |
249
+ | `X402_PAYMENT_MODE` | `exact` | Initial x402 scheme: `exact` (per-call) or `batch` (payment channel). Switch in-session with `1s_payment_mode`. |
250
+ | `X402_DEPOSIT_MULTIPLIER` | `10` | Batch mode: deposit = price × this multiplier, funding that many calls per channel. Unused balance is reclaimable via `1s_refund`. | |
251
+ | `X402_CHANNEL_DIR` | — | Directory to persist batch channel state across restarts. Unset = in-memory (channel lost on restart).
252
+ | `ONESOURCE_BASE_URL` | `https://skills.onesource.io` | API base URL |
253
+ | `ONESOURCE_ANALYTICS` | — | Set to `false` to disable analytics |
254
+ | `ONESOURCE_ANALYTICS_URL` | — | Dashboard endpoint for analytics |
255
+ | `X402_ANALYTICS_KEY` | — | API key for dashboard analytics |
256
+
242
257
 
243
258
  ## Troubleshooting
244
259
 
245
- **`1s_setup_check` shows "Not configured"**
260
+ `**1s_setup_check` shows "Not configured"**
246
261
  Set either `ONESOURCE_API_KEY` or `X402_PRIVATE_KEY`. Reload the MCP server after setting either variable (see note above). If the key still isn't reaching the server, set it as a shell environment variable directly.
247
262
 
248
263
  **Getting 403 / wrong key active despite correct setup**
@@ -257,7 +272,7 @@ Run `claude mcp remove onesource` first, then re-add with your updated config.
257
272
  **Windows: `npx` requires `cmd /c` wrapper**
258
273
  Claude Code's `/doctor` command may warn about this. Update your MCP config to use `"command": "cmd"` with `"args": ["/c", "npx", "-y", "@one-source/mcp@latest"]`.
259
274
 
260
- **`npx` hangs with no output**
275
+ `**npx` hangs with no output**
261
276
  That's normal — stdio mode waits for JSON-RPC input on stdin. Use `--http` if you want an HTTP server you can curl.
262
277
 
263
278
  **Port already in use**
@@ -323,17 +338,17 @@ If you need to regenerate the keypair (this invalidates the current DNS record a
323
338
 
324
339
  1. Generate a new ed25519 keypair (e.g., `openssl genpkey -algorithm Ed25519 -out key.pem`)
325
340
  2. Extract the raw 32-byte private key seed and convert to hex:
326
- ```bash
341
+ ```bash
327
342
  openssl pkey -in key.pem -outform DER | tail -c 32 | xxd -p -c 32
328
- ```
343
+ ```
329
344
  3. Extract the public key in base64 for the DNS TXT record:
330
- ```bash
345
+ ```bash
331
346
  openssl pkey -in key.pem -pubout -outform DER | tail -c 32 | base64
332
- ```
347
+ ```
333
348
  4. Update the DNS TXT record on `onesource.io` with the new public key:
334
- ```
349
+ ```
335
350
  v=MCPv1; k=ed25519; p=<base64-public-key>
336
- ```
351
+ ```
337
352
  5. Wait for DNS propagation before attempting to log in.
338
353
 
339
354
  #### Publishing a New Version
@@ -341,35 +356,31 @@ If you need to regenerate the keypair (this invalidates the current DNS record a
341
356
  Every time you release a new npm version, update the MCP Registry:
342
357
 
343
358
  1. **Publish to npm** (the registry validates the package exists, so this must happen first):
344
- ```bash
359
+ ```bash
345
360
  npm run build
346
361
  npm publish --access public
347
- ```
348
-
362
+ ```
349
363
  2. **Update `server.json`** — set both `version` fields to match the new npm version:
350
- ```json
364
+ ```json
351
365
  {
352
366
  "version": "x.y.z",
353
367
  ...
354
368
  "packages": [{ "version": "x.y.z", ... }]
355
369
  }
356
- ```
370
+ ```
357
371
  The `mcpName` field in `package.json` must be `"io.onesource/mcp"` and must match the `name` field in `server.json`. This is already set — don't remove it.
358
-
359
372
  3. **Authenticate** (tokens expire, so do this each time):
360
- ```bash
373
+ ```bash
361
374
  mcp-publisher login dns --domain onesource.io --private-key <ed25519-hex-private-key>
362
- ```
363
-
375
+ ```
364
376
  4. **Publish to the registry:**
365
- ```bash
377
+ ```bash
366
378
  mcp-publisher publish
367
- ```
368
-
379
+ ```
369
380
  5. **Verify:**
370
- ```bash
381
+ ```bash
371
382
  curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=onesource"
372
- ```
383
+ ```
373
384
 
374
385
  ### Glama
375
386
 
@@ -377,4 +388,4 @@ Glama auto-syncs from the GitHub repo daily. No manual steps needed after a rele
377
388
 
378
389
  ## License
379
390
 
380
- Apache 2.0 — see [LICENSE](LICENSE) for details.
391
+ Apache 2.0 — see [LICENSE](LICENSE) for details.
package/dist/analytics.d.ts CHANGED
@@ -11,6 +11,7 @@ import { type Analytics as _Analytics, type ToolCallEvent as _ToolCallEvent, typ
11
11
  export type ToolCallEvent = Omit<_ToolCallEvent, 'category' | 'auth_method'> & {
12
12
  category: _ToolCallEvent['category'] | 'docs' | 'ops';
13
13
  auth_method: _ToolCallEvent['auth_method'] | 'api_key';
14
+ wallet_id?: string;
14
15
  source?: string;
15
16
  };
16
17
  export type HttpCallEvent = _HttpCallEvent & {
package/dist/analytics.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"analytics.d.ts","sourceRoot":"","sources":["../src/analytics.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAEL,KAAK,SAAS,IAAI,UAAU,EAC5B,KAAK,aAAa,IAAI,cAAc,EACpC,KAAK,aAAa,IAAI,cAAc,EACpC,KAAK,YAAY,IAAI,aAAa,EACnC,MAAM,+BAA+B,CAAC;AAEvC,4FAA4F;AAC5F,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,cAAc,EAAE,UAAU,GAAG,aAAa,CAAC,GAAG;IAC7E,QAAQ,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,MAAM,GAAG,KAAK,CAAC;IACtD,WAAW,EAAE,cAAc,CAAC,aAAa,CAAC,GAAG,SAAS,CAAC;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AACjE,MAAM,MAAM,YAAY,GAAG,aAAa,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/D,0EAA0E;AAC1E,MAAM,WAAW,SAAU,SAAQ,IAAI,CAAC,UAAU,EAAE,WAAW,GAAG,WAAW,GAAG,cAAc,CAAC;IAC7F,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IACtC,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IACtC,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;CACzC;AAED,mFAAmF;AACnF,wBAAgB,eAAe,IAAI,SAAS,CAK3C"}
1
+ {"version":3,"file":"analytics.d.ts","sourceRoot":"","sources":["../src/analytics.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAEL,KAAK,SAAS,IAAI,UAAU,EAC5B,KAAK,aAAa,IAAI,cAAc,EACpC,KAAK,aAAa,IAAI,cAAc,EACpC,KAAK,YAAY,IAAI,aAAa,EACnC,MAAM,+BAA+B,CAAC;AAEvC,4FAA4F;AAC5F,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,cAAc,EAAE,UAAU,GAAG,aAAa,CAAC,GAAG;IAC7E,QAAQ,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,MAAM,GAAG,KAAK,CAAC;IACtD,WAAW,EAAE,cAAc,CAAC,aAAa,CAAC,GAAG,SAAS,CAAC;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AACjE,MAAM,MAAM,YAAY,GAAG,aAAa,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/D,0EAA0E;AAC1E,MAAM,WAAW,SAAU,SAAQ,IAAI,CAAC,UAAU,EAAE,WAAW,GAAG,WAAW,GAAG,cAAc,CAAC;IAC7F,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IACtC,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IACtC,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;CACzC;AAED,mFAAmF;AACnF,wBAAgB,eAAe,IAAI,SAAS,CAK3C"}
package/dist/analytics.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"analytics.js","sourceRoot":"","sources":["../src/analytics.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,eAAe,IAAI,gBAAgB,GAKpC,MAAM,+BAA+B,CAAC;AAmBvC,mFAAmF;AACnF,MAAM,UAAU,eAAe;IAC7B,8GAA8G;IAC9G,OAAO,CAAC,GAAG,CAAC,uBAAuB,KAAK,iCAAiC,CAAC;IAC1E,OAAO,CAAC,GAAG,CAAC,kBAAkB,KAAK,eAAe,CAAC;IACnD,OAAO,gBAAgB,EAAe,CAAC;AACzC,CAAC"}
1
+ {"version":3,"file":"analytics.js","sourceRoot":"","sources":["../src/analytics.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,eAAe,IAAI,gBAAgB,GAKpC,MAAM,+BAA+B,CAAC;AAoBvC,mFAAmF;AACnF,MAAM,UAAU,eAAe;IAC7B,8GAA8G;IAC9G,OAAO,CAAC,GAAG,CAAC,uBAAuB,KAAK,iCAAiC,CAAC;IAC1E,OAAO,CAAC,GAAG,CAAC,kBAAkB,KAAK,eAAe,CAAC;IACnD,OAAO,gBAAgB,EAAe,CAAC;AACzC,CAAC"}
package/dist/cli.js CHANGED
@@ -31,7 +31,7 @@ function buildInstructions(currentVersion, latestVersion, authMethod) {
31
31
  ? 'Blockchain API tools require x402 payment (USDC on Base). If a tool returns a 402 error, the user needs to configure X402_PRIVATE_KEY. Call 1s_setup_check for diagnostics and setup instructions.'
32
32
  : 'Blockchain API tools require authentication. Set ONESOURCE_API_KEY (API key) or X402_PRIVATE_KEY (x402 micropayments) to access them. Call 1s_setup_check for setup instructions.';
33
33
  const baseline = [
34
- 'OneSource MCP — 28 tools for blockchain data.',
34
+ 'OneSource MCP — 29 tools for blockchain data.',
35
35
  '',
36
36
  authLine,
37
37
  '',
package/dist/create-server.d.ts CHANGED
@@ -1,8 +1,8 @@
1
1
  /**
2
2
  * Unified MCP Server Factory
3
3
  *
4
- * Creates a single McpServer named 'onesource' with all 28 tools
5
- * (26 API incl. payment-mode + 1 setup check + 1 bug report) by delegating to the register modules.
4
+ * Creates a single McpServer named 'onesource' with all 29 tools
5
+ * (27 API incl. payment-mode + 1 setup check + 1 bug report) by delegating to the register modules.
6
6
  */
7
7
  import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
8
8
  import type { OneSourceClient } from '@one-source/api-mcp/client';
package/dist/create-server.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"create-server.d.ts","sourceRoot":"","sources":["../src/create-server.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAIlE,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AACjE,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,MAAM,WAAW,mBAAmB;IAGlC,kFAAkF;IAClF,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC7B,2DAA2D;IAC3D,UAAU,CAAC,EAAE,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;IACzC,8FAA8F;IAC9F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gFAAgF;IAChF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,SAAS,CAAC;IAClB,SAAS,EAAE,SAAS,CAAC;IACrB,MAAM,EAAE,eAAe,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,CAAC,EAAE,mBAAmB,GAAG,kBAAkB,CAkC9E;AAGD,OAAO,EAAE,OAAO,EAAE,CAAC;AACnB,OAAO,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAC"}
1
+ {"version":3,"file":"create-server.d.ts","sourceRoot":"","sources":["../src/create-server.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAIlE,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AACjE,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,MAAM,WAAW,mBAAmB;IAGlC,kFAAkF;IAClF,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC7B,2DAA2D;IAC3D,UAAU,CAAC,EAAE,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;IACzC,8FAA8F;IAC9F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gFAAgF;IAChF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,SAAS,CAAC;IAClB,SAAS,EAAE,SAAS,CAAC;IACrB,MAAM,EAAE,eAAe,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,CAAC,EAAE,mBAAmB,GAAG,kBAAkB,CAmC9E;AAGD,OAAO,EAAE,OAAO,EAAE,CAAC;AACnB,OAAO,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAC"}
package/dist/create-server.js CHANGED
@@ -1,8 +1,8 @@
1
1
  /**
2
2
  * Unified MCP Server Factory
3
3
  *
4
- * Creates a single McpServer named 'onesource' with all 28 tools
5
- * (26 API incl. payment-mode + 1 setup check + 1 bug report) by delegating to the register modules.
4
+ * Creates a single McpServer named 'onesource' with all 29 tools
5
+ * (27 API incl. payment-mode + 1 setup check + 1 bug report) by delegating to the register modules.
6
6
  */
7
7
  import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
8
8
  import { registerApiTools } from './register-api-tools.js';
@@ -23,6 +23,7 @@ export function createMcpServer(opts) {
23
23
  transport,
24
24
  client: opts?.client,
25
25
  authMethod: opts?.authMethod,
26
+ x402Address: opts?.x402Address,
26
27
  });
27
28
  const docsCount = registerDocsTools({
28
29
  server,
package/dist/create-server.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"create-server.js","sourceRoot":"","sources":["../src/create-server.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EAAE,eAAe,EAAkB,MAAM,gBAAgB,CAAC;AACjE,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AA4BvC;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,IAA0B;IACxD,MAAM,SAAS,GAAG,IAAI,EAAE,SAAS,IAAI,eAAe,EAAE,CAAC;IACvD,MAAM,SAAS,GAAG,IAAI,EAAE,SAAS,CAAC;IAElC,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,EACvC,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,SAAS,CACrE,CAAC;IAEF,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,gBAAgB,CAAC;QACnD,MAAM;QACN,SAAS;QACT,SAAS;QACT,MAAM,EAAE,IAAI,EAAE,MAAM;QACpB,UAAU,EAAE,IAAI,EAAE,UAAU;KAC7B,CAAC,CAAC;IAEH,MAAM,SAAS,GAAG,iBAAiB,CAAC;QAClC,MAAM;QACN,SAAS;QACT,SAAS;QACT,wBAAwB;QACxB,UAAU,EAAE,IAAI,EAAE,UAAU;QAC5B,WAAW,EAAE,IAAI,EAAE,WAAW;KAC/B,CAAC,CAAC;IAEH,MAAM,QAAQ,GAAG,qBAAqB,CAAC;QACrC,MAAM;QACN,SAAS;QACT,SAAS;QACT,YAAY,EAAE,IAAI,EAAE,YAAY;KACjC,CAAC,CAAC;IAEH,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,EAAE,CAAC;AACnF,CAAC;AAED,wCAAwC;AACxC,OAAO,EAAE,OAAO,EAAE,CAAC;AACnB,OAAO,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAC"}
1
+ {"version":3,"file":"create-server.js","sourceRoot":"","sources":["../src/create-server.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EAAE,eAAe,EAAkB,MAAM,gBAAgB,CAAC;AACjE,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AA4BvC;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,IAA0B;IACxD,MAAM,SAAS,GAAG,IAAI,EAAE,SAAS,IAAI,eAAe,EAAE,CAAC;IACvD,MAAM,SAAS,GAAG,IAAI,EAAE,SAAS,CAAC;IAElC,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,EACvC,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,SAAS,CACrE,CAAC;IAEF,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,gBAAgB,CAAC;QACnD,MAAM;QACN,SAAS;QACT,SAAS;QACT,MAAM,EAAE,IAAI,EAAE,MAAM;QACpB,UAAU,EAAE,IAAI,EAAE,UAAU;QAC5B,WAAW,EAAE,IAAI,EAAE,WAAW;KAC/B,CAAC,CAAC;IAEH,MAAM,SAAS,GAAG,iBAAiB,CAAC;QAClC,MAAM;QACN,SAAS;QACT,SAAS;QACT,wBAAwB;QACxB,UAAU,EAAE,IAAI,EAAE,UAAU;QAC5B,WAAW,EAAE,IAAI,EAAE,WAAW;KAC/B,CAAC,CAAC;IAEH,MAAM,QAAQ,GAAG,qBAAqB,CAAC;QACrC,MAAM;QACN,SAAS;QACT,SAAS;QACT,YAAY,EAAE,IAAI,EAAE,YAAY;KACjC,CAAC,CAAC;IAEH,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,EAAE,CAAC;AACnF,CAAC;AAED,wCAAwC;AACxC,OAAO,EAAE,OAAO,EAAE,CAAC;AACnB,OAAO,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAC"}
package/dist/register-api-tools.d.ts CHANGED
@@ -16,6 +16,8 @@ export interface RegisterApiToolsOptions {
16
16
  client?: OneSourceClient;
17
17
  /** Active authentication method, determined at startup. */
18
18
  authMethod?: 'api_key' | 'x402' | 'none';
19
+ /** Wallet address derived from X402_PRIVATE_KEY — hashed to wallet_id for analytics. */
20
+ x402Address?: string;
19
21
  }
20
22
  /**
21
23
  * Register all API tools and return the client instance + tool count.
package/dist/register-api-tools.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"register-api-tools.d.ts","sourceRoot":"","sources":["../src/register-api-tools.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGzE,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,4BAA4B,CAAC;AACvF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAQhD,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,SAAS,CAAC;IAClB,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC7B,6EAA6E;IAC7E,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;CAC1C;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,uBAAuB,GAC5B;IAAE,MAAM,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAiI5C"}
1
+ {"version":3,"file":"register-api-tools.d.ts","sourceRoot":"","sources":["../src/register-api-tools.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGzE,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,4BAA4B,CAAC;AACvF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAQhD,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,SAAS,CAAC;IAClB,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC7B,6EAA6E;IAC7E,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;IACzC,wFAAwF;IACxF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,uBAAuB,GAC5B;IAAE,MAAM,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAsI5C"}
package/dist/register-api-tools.js CHANGED
@@ -21,6 +21,9 @@ export function registerApiTools(opts) {
21
21
  const { server, analytics, transport } = opts;
22
22
  const authMethod = opts.authMethod;
23
23
  const client = opts.client ?? createClientFromEnv();
24
+ const walletId = opts.x402Address
25
+ ? createHash('sha256').update(opts.x402Address.toLowerCase()).digest('hex').slice(0, 16)
26
+ : undefined;
24
27
  // Wire HTTP-level analytics from base client (default handler for non-overridden calls)
25
28
  client.onHttpEvent = (event) => {
26
29
  analytics.trackHttp({
@@ -91,6 +94,7 @@ export function registerApiTools(opts) {
91
94
  client_name: clientInfo?.name,
92
95
  client_version: clientInfo?.version,
93
96
  session_id: sessionHash,
97
+ wallet_id: walletId,
94
98
  transport,
95
99
  source: 'unified',
96
100
  });
@@ -118,6 +122,7 @@ export function registerApiTools(opts) {
118
122
  client_name: clientInfo?.name,
119
123
  client_version: clientInfo?.version,
120
124
  session_id: sessionHash,
125
+ wallet_id: walletId,
121
126
  transport,
122
127
  source: 'unified',
123
128
  });
package/dist/register-api-tools.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"register-api-tools.js","sourceRoot":"","sources":["../src/register-api-tools.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"register-api-tools.js","sourceRoot":"","sources":["../src/register-api-tools.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,9 +1,9 @@
1
1
  {
2
2
  "name": "@one-source/mcp",
3
3
  "mcpName": "io.onesource/mcp",
4
- "version": "5.3.1",
4
+ "version": "5.3.3",
5
5
  "type": "module",
6
- "description": "Unified MCP server for OneSource — 28 tools for blockchain data",
6
+ "description": "Unified MCP server for OneSource — 29 tools for blockchain data",
7
7
  "bin": {
8
8
  "onesource-mcp": "./dist/cli.js"
9
9
  },
package/skills/onesource-mcp-setup/SKILL.md CHANGED
@@ -1,308 +1,308 @@
1
- ---
2
- name: onesource-mcp-setup
3
- description: >-
4
- Guide for installing and configuring the OneSource MCP server. Covers both
5
- authentication options (API key and x402 micropayments), wallet setup, USDC
6
- funding on Base, and verification. Use when a user needs help setting up
7
- OneSource MCP or configuring either auth method.
8
- ---
9
-
10
- # OneSource MCP Setup Guide
11
-
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
-
14
- ## Before You Start
15
-
16
- **Always call `1s_setup_check` before using any other OneSource tools.** This checks the installed version against the latest release and reports authentication status.
17
-
18
- - **If an update is available:** Tell the user and help them update before proceeding. Run `npx -y @one-source/mcp@latest` to get the latest version. The update takes effect on the next session — the user will need to restart their MCP client.
19
- - **If `1s_setup_check` is not available:** The MCP is either not installed or running a version before this tool existed. Help the user install or update using the instructions in Step 2 below.
20
- - **If auth is not configured:** The tool will include setup instructions. Walk the user through them before attempting API calls.
21
-
22
- Do not skip this step — outdated versions may be missing tools, fixes, or protocol changes.
23
-
24
- ## Step 1: Check Current Installation
25
-
26
- Call the `1s_setup_check` tool. It reports:
27
- - Server version (current vs latest)
28
- - Which auth method is active (API key, x402), or whether auth is not yet configured
29
- - Wallet address (if x402 is configured)
30
- - API backend connectivity
31
-
32
- If the tool is not available, the MCP is not installed — go to Step 2.
33
-
34
- ## Step 2: Install or Update
35
-
36
- ### Claude Code
37
-
38
- ```bash
39
- claude mcp add onesource -- npx -y @one-source/mcp@latest
40
- ```
41
-
42
- ### Claude Desktop / Cursor
43
-
44
- Add to your MCP configuration file:
45
-
46
- ```json
47
- {
48
- "mcpServers": {
49
- "onesource": {
50
- "command": "npx",
51
- "args": ["-y", "@one-source/mcp@latest"]
52
- }
53
- }
54
- }
55
- ```
56
-
57
- ### Any MCP Client (stdio)
58
-
59
- ```bash
60
- npx -y @one-source/mcp@latest
61
- ```
62
-
63
- ### Check for Updates
64
-
65
- Compare the installed version (shown in `1s_setup_check` output) against the latest:
66
-
67
- ```bash
68
- npm view @one-source/mcp version
69
- ```
70
-
71
- To update, reinstall with `@latest` or clear the npx cache: `npx -y @one-source/mcp@latest`.
72
-
73
- ## Step 3: Configure Authentication
74
-
75
- Choose one option. If both are set, API key takes priority.
76
-
77
- ### Option A: API Key
78
-
79
- 1. Go to [app.onesource.io](https://app.onesource.io) and create an account.
80
- 2. Subscribe to a developer plan (Stripe checkout).
81
- 3. Navigate to **API Keys** and generate a key.
82
- 4. Copy the key — it starts with `sk_`.
83
-
84
- #### Claude Code
85
-
86
- ```bash
87
- claude mcp remove onesource
88
- claude mcp add onesource -e ONESOURCE_API_KEY=<key> -- npx -y @one-source/mcp@latest
89
- ```
90
-
91
- #### Claude Desktop / Cursor
92
-
93
- Add the `env` block to your MCP config:
94
-
95
- ```json
96
- {
97
- "mcpServers": {
98
- "onesource": {
99
- "command": "npx",
100
- "args": ["-y", "@one-source/mcp@latest"],
101
- "env": {
102
- "ONESOURCE_API_KEY": "<key>"
103
- }
104
- }
105
- }
106
- }
107
- ```
108
-
109
- #### Any MCP Client (stdio)
110
-
111
- ```bash
112
- ONESOURCE_API_KEY=<key> npx -y @one-source/mcp@latest
113
- ```
114
-
115
- After adding the key, reload the MCP server (run `/reload-plugins` in Claude Code, or restart Claude Desktop / Cursor), then call `1s_setup_check`. It should show `Status: Configured (API key)`. You're done — skip to Step 7 to verify a live tool call.
116
-
117
- ---
118
-
119
- ### Option B: x402 Micropayments
120
-
121
- Pay-per-call using USDC on Base. No account required — just an EVM wallet funded with USDC. The server handles payments transparently. Continue with Steps 3B through 6 below.
122
-
123
- ## Step 3B: Get an EVM Private Key
124
-
125
- The `X402_PRIVATE_KEY` is an EVM wallet private key — the same kind used by MetaMask, Coinbase Wallet, or Foundry. It is a 64-character hex string. The `0x` prefix is optional — both formats are accepted.
126
-
127
- ### Option A: Export from MetaMask
128
-
129
- 1. Open MetaMask
130
- 2. Click the three dots next to the account name
131
- 3. Go to **Account details** > **Show private key**
132
- 4. Enter your MetaMask password
133
- 5. Copy the key
134
-
135
- ### Option B: Export from Coinbase Wallet
136
-
137
- 1. Open Coinbase Wallet > Settings > Developer settings
138
- 2. Export your private key
139
-
140
- ### Option C: Generate a New Wallet
141
-
142
- ```bash
143
- # Using OpenSSL (macOS/Linux, or Git Bash on Windows)
144
- openssl rand -hex 32
145
-
146
- # Using Foundry (if installed)
147
- cast wallet new
148
- ```
149
-
150
- ```powershell
151
- # PowerShell (Windows)
152
- -join ((1..32) | ForEach-Object { "{0:x2}" -f (Get-Random -Max 256) })
153
- ```
154
-
155
- **Important:** Use a dedicated wallet for MCP payments — do not use your primary wallet with large holdings. Transfer only what you need.
156
-
157
- ## Step 4: Set the Private Key (x402)
158
-
159
- ### Claude Code
160
-
161
- ```bash
162
- claude mcp remove onesource
163
- claude mcp add onesource -e X402_PRIVATE_KEY=0x... -- npx -y @one-source/mcp@latest
164
- ```
165
-
166
- > **Scope tip:** Claude Code stores MCP configs at three levels — `user`, `project`, and `local`. Use `local` scope (the default for `claude mcp add`) for faster debugging and testing. You can check which scope your config is in by looking at `.claude/settings.local.json` (local), `.claude/settings.json` (project), or `~/.claude/settings.json` (user).
167
-
168
- ### Claude Desktop / Cursor
169
-
170
- Add the `env` block to your MCP config:
171
-
172
- ```json
173
- {
174
- "mcpServers": {
175
- "onesource": {
176
- "command": "npx",
177
- "args": ["-y", "@one-source/mcp@latest"],
178
- "env": {
179
- "X402_PRIVATE_KEY": "0x..."
180
- }
181
- }
182
- }
183
- }
184
- ```
185
-
186
- ### Any MCP Client (stdio)
187
-
188
- ```bash
189
- X402_PRIVATE_KEY=0x... npx -y @one-source/mcp@latest
190
- ```
191
-
192
- ### Manual Setup (Editing the Config File Directly)
193
-
194
- The CLI commands above write to a JSON config file. You can also edit this file directly — this is useful for debugging or if you want to understand what the setup actually does.
195
-
196
- **Claude Code** — Find which file your config is in by running `claude mcp get onesource`. Depending on the scope:
197
- - **Local:** `.claude/settings.local.json` in your project directory
198
- - **Project:** `.claude/settings.json` in your project directory
199
- - **User:** `~/.claude/settings.json` (macOS/Linux) or `%USERPROFILE%\.claude\settings.json` (Windows)
200
-
201
- **Claude Desktop:**
202
- - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
203
- - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
204
-
205
- **Cursor:**
206
- - **macOS:** `~/.cursor/mcp.json`
207
- - **Windows:** `%USERPROFILE%\.cursor\mcp.json`
208
-
209
- Open the config file and add (or update) the `onesource` entry inside `"mcpServers"`:
210
-
211
- ```json
212
- {
213
- "mcpServers": {
214
- "onesource": {
215
- "command": "npx",
216
- "args": ["-y", "@one-source/mcp@latest"],
217
- "env": {
218
- "X402_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY_HERE"
219
- }
220
- }
221
- }
222
- }
223
- ```
224
-
225
- Save the file, then reload (see below).
226
-
227
- ### Important: Reload After Config Changes
228
-
229
- Changing the config file (via `claude mcp add` or manual edit) does **not** automatically restart the running MCP server. You must reload:
230
-
231
- - **Claude Code:** Run `/reload-plugins` (preferred — no restart needed), or restart Claude Code entirely.
232
- - **Claude Desktop / Cursor:** Restart the app — close it completely and reopen.
233
-
234
- Without reloading, the old server process keeps running with the old config, and `1s_setup_check` will still show "Not configured" even though the key is in the file.
235
-
236
- ### Alternative: Set the Key as an Environment Variable
237
-
238
- If the `env` block in the config isn't reaching the server after reloading, you can set the key as an environment variable directly instead:
239
-
240
- **bash / zsh (macOS / Linux):**
241
-
242
- ```bash
243
- export X402_PRIVATE_KEY=0x...
244
- ```
245
-
246
- To make it persistent, add the line to your `~/.bashrc`, `~/.zshrc`, or `~/.profile`.
247
-
248
- **PowerShell (Windows):**
249
-
250
- ```powershell
251
- $env:X402_PRIVATE_KEY = "0x..."
252
- ```
253
-
254
- This only lasts for the current session. To make it persistent, either:
255
- - Add it to your PowerShell profile (`notepad $PROFILE`, add the line, restart PowerShell)
256
- - Or set it as a system environment variable: **Settings > System > About > Advanced system settings > Environment Variables > User variables > New** — name: `X402_PRIVATE_KEY`, value: `0x...`
257
-
258
- After setting the variable, restart your MCP client and run `1s_setup_check` to confirm.
259
-
260
- > **Windows note:** Claude Code's `/doctor` command may warn that Windows requires a `cmd /c` wrapper to execute `npx`. If you encounter issues, update the config to use `"command": "cmd"` with `"args": ["/c", "npx", "-y", "@one-source/mcp@latest"]`.
261
-
262
- ### Security
263
-
264
- - **Never** commit your private key to source control.
265
- - Use environment variables, a `.env` file (excluded from git), or a secrets manager.
266
- - Use a dedicated wallet with minimal funds — only what you need for API calls.
267
-
268
- ## Step 5: Find Your Wallet Address (x402)
269
-
270
- After setting the key and reloading the MCP server:
271
-
272
- 1. Call `1s_setup_check` — it shows the wallet address derived from your key under "Wallet address". This is the address you need to fund.
273
- 2. Alternatively, import the key into MetaMask to see the address.
274
-
275
- ## Step 6: Fund the Wallet with USDC on Base (x402)
276
-
277
- The wallet must hold **USDC on the Base network** (not Ethereum mainnet, not other tokens).
278
-
279
- 1. Send USDC to the wallet address from Step 5 **on the Base network**.
280
- 2. A few dollars ($1–5 USDC) is enough for hundreds of API calls.
281
-
282
- If your USDC is on Ethereum mainnet, bridge it to Base using the [Base Bridge](https://bridge.base.org) or any cross-chain bridge that supports Base.
283
-
284
- ## Step 7: Verify
285
-
286
- After setting your auth (either option) and reloading:
287
-
288
- 1. **Check MCP connection** — Run `/mcp` to confirm the `onesource` server is connected.
289
- 2. **Run `1s_setup_check`** — You should see:
290
- - **Authentication:** `Configured (API key)` or `Configured (x402)` — not "Not configured"
291
- - **Wallet address:** Your wallet address (x402 only)
292
- - **API backend:** Reachable
293
- 3. **Test a live tool** — Call `1s_network_info` for ethereum. If it returns a block number and gas price, auth is working end-to-end.
294
-
295
- > **Tip:** If you edited the config file manually (instead of using `claude mcp add`), you must run `/reload-plugins` for changes to take effect. Restarting Claude Code also works.
296
-
297
- ## Troubleshooting
298
-
299
- | Problem | Solution |
300
- |---------|----------|
301
- | `1s_setup_check` shows "Not configured" | Most common cause: config was changed but the MCP server wasn't reloaded. Run `/reload-plugins` in Claude Code, or restart Claude Desktop / Cursor. If the key still isn't reaching the server, try setting it as an environment variable directly — see **Alternative: Set the Key as an Environment Variable** above. |
302
- | `1s_setup_check` shows API key configured but tools return 402 | The key may be invalid or the account may not have a developer plan. Verify the key at app.onesource.io. |
303
- | "MCP server onesource already exists" error | Run `claude mcp remove onesource` first, then re-add it with your updated config. |
304
- | Config changed but nothing happened | Run `/reload-plugins` in Claude Code to reload MCP servers, then `/mcp` to check connection status. |
305
- | Tool returns HTTP 402 error (x402 path) | x402 is not configured, or the wallet has insufficient USDC on Base. Check `1s_setup_check` for wallet address and balance. |
306
- | "x402 setup failed" in server logs | The private key format is wrong. It must be a 64-character hex string (with or without `0x` prefix). |
307
- | Key is set but wallet shows 0 USDC | Make sure USDC is on the **Base** network, not Ethereum mainnet or another chain. |
308
- | Tools work but results seem stale | Check `1s_setup_check` for version — you may need to update to the latest. |
1
+ ---
2
+ name: onesource-mcp-setup
3
+ description: >-
4
+ Guide for installing and configuring the OneSource MCP server. Covers both
5
+ authentication options (API key and x402 micropayments), wallet setup, USDC
6
+ funding on Base, and verification. Use when a user needs help setting up
7
+ OneSource MCP or configuring either auth method.
8
+ ---
9
+
10
+ # OneSource MCP Setup Guide
11
+
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
+
14
+ ## Before You Start
15
+
16
+ **Always call `1s_setup_check` before using any other OneSource tools.** This checks the installed version against the latest release and reports authentication status.
17
+
18
+ - **If an update is available:** Tell the user and help them update before proceeding. Run `npx -y @one-source/mcp@latest` to get the latest version. The update takes effect on the next session — the user will need to restart their MCP client.
19
+ - **If `1s_setup_check` is not available:** The MCP is either not installed or running a version before this tool existed. Help the user install or update using the instructions in Step 2 below.
20
+ - **If auth is not configured:** The tool will include setup instructions. Walk the user through them before attempting API calls.
21
+
22
+ Do not skip this step — outdated versions may be missing tools, fixes, or protocol changes.
23
+
24
+ ## Step 1: Check Current Installation
25
+
26
+ Call the `1s_setup_check` tool. It reports:
27
+ - Server version (current vs latest)
28
+ - Which auth method is active (API key, x402), or whether auth is not yet configured
29
+ - Wallet address (if x402 is configured)
30
+ - API backend connectivity
31
+
32
+ If the tool is not available, the MCP is not installed — go to Step 2.
33
+
34
+ ## Step 2: Install or Update
35
+
36
+ ### Claude Code
37
+
38
+ ```bash
39
+ claude mcp add onesource -- npx -y @one-source/mcp@latest
40
+ ```
41
+
42
+ ### Claude Desktop / Cursor
43
+
44
+ Add to your MCP configuration file:
45
+
46
+ ```json
47
+ {
48
+ "mcpServers": {
49
+ "onesource": {
50
+ "command": "npx",
51
+ "args": ["-y", "@one-source/mcp@latest"]
52
+ }
53
+ }
54
+ }
55
+ ```
56
+
57
+ ### Any MCP Client (stdio)
58
+
59
+ ```bash
60
+ npx -y @one-source/mcp@latest
61
+ ```
62
+
63
+ ### Check for Updates
64
+
65
+ Compare the installed version (shown in `1s_setup_check` output) against the latest:
66
+
67
+ ```bash
68
+ npm view @one-source/mcp version
69
+ ```
70
+
71
+ To update, reinstall with `@latest` or clear the npx cache: `npx -y @one-source/mcp@latest`.
72
+
73
+ ## Step 3: Configure Authentication
74
+
75
+ Choose one option. If both are set, API key takes priority.
76
+
77
+ ### Option A: API Key
78
+
79
+ 1. Go to [app.onesource.io](https://app.onesource.io) and create an account.
80
+ 2. Subscribe to a developer plan (Stripe checkout).
81
+ 3. Navigate to **API Keys** and generate a key.
82
+ 4. Copy the key — it starts with `sk_`.
83
+
84
+ #### Claude Code
85
+
86
+ ```bash
87
+ claude mcp remove onesource
88
+ claude mcp add onesource -e ONESOURCE_API_KEY=<key> -- npx -y @one-source/mcp@latest
89
+ ```
90
+
91
+ #### Claude Desktop / Cursor
92
+
93
+ Add the `env` block to your MCP config:
94
+
95
+ ```json
96
+ {
97
+ "mcpServers": {
98
+ "onesource": {
99
+ "command": "npx",
100
+ "args": ["-y", "@one-source/mcp@latest"],
101
+ "env": {
102
+ "ONESOURCE_API_KEY": "<key>"
103
+ }
104
+ }
105
+ }
106
+ }
107
+ ```
108
+
109
+ #### Any MCP Client (stdio)
110
+
111
+ ```bash
112
+ ONESOURCE_API_KEY=<key> npx -y @one-source/mcp@latest
113
+ ```
114
+
115
+ After adding the key, reload the MCP server (run `/reload-plugins` in Claude Code, or restart Claude Desktop / Cursor), then call `1s_setup_check`. It should show `Status: Configured (API key)`. You're done — skip to Step 7 to verify a live tool call.
116
+
117
+ ---
118
+
119
+ ### Option B: x402 Micropayments
120
+
121
+ Pay-per-call using USDC on Base. No account required — just an EVM wallet funded with USDC. The server handles payments transparently. Continue with Steps 3B through 6 below.
122
+
123
+ ## Step 3B: Get an EVM Private Key
124
+
125
+ The `X402_PRIVATE_KEY` is an EVM wallet private key — the same kind used by MetaMask, Coinbase Wallet, or Foundry. It is a 64-character hex string. The `0x` prefix is optional — both formats are accepted.
126
+
127
+ ### Option A: Export from MetaMask
128
+
129
+ 1. Open MetaMask
130
+ 2. Click the three dots next to the account name
131
+ 3. Go to **Account details** > **Show private key**
132
+ 4. Enter your MetaMask password
133
+ 5. Copy the key
134
+
135
+ ### Option B: Export from Coinbase Wallet
136
+
137
+ 1. Open Coinbase Wallet > Settings > Developer settings
138
+ 2. Export your private key
139
+
140
+ ### Option C: Generate a New Wallet
141
+
142
+ ```bash
143
+ # Using OpenSSL (macOS/Linux, or Git Bash on Windows)
144
+ openssl rand -hex 32
145
+
146
+ # Using Foundry (if installed)
147
+ cast wallet new
148
+ ```
149
+
150
+ ```powershell
151
+ # PowerShell (Windows)
152
+ -join ((1..32) | ForEach-Object { "{0:x2}" -f (Get-Random -Max 256) })
153
+ ```
154
+
155
+ **Important:** Use a dedicated wallet for MCP payments — do not use your primary wallet with large holdings. Transfer only what you need.
156
+
157
+ ## Step 4: Set the Private Key (x402)
158
+
159
+ ### Claude Code
160
+
161
+ ```bash
162
+ claude mcp remove onesource
163
+ claude mcp add onesource -e X402_PRIVATE_KEY=0x... -- npx -y @one-source/mcp@latest
164
+ ```
165
+
166
+ > **Scope tip:** Claude Code stores MCP configs at three levels — `user`, `project`, and `local`. Use `local` scope (the default for `claude mcp add`) for faster debugging and testing. You can check which scope your config is in by looking at `.claude/settings.local.json` (local), `.claude/settings.json` (project), or `~/.claude/settings.json` (user).
167
+
168
+ ### Claude Desktop / Cursor
169
+
170
+ Add the `env` block to your MCP config:
171
+
172
+ ```json
173
+ {
174
+ "mcpServers": {
175
+ "onesource": {
176
+ "command": "npx",
177
+ "args": ["-y", "@one-source/mcp@latest"],
178
+ "env": {
179
+ "X402_PRIVATE_KEY": "0x..."
180
+ }
181
+ }
182
+ }
183
+ }
184
+ ```
185
+
186
+ ### Any MCP Client (stdio)
187
+
188
+ ```bash
189
+ X402_PRIVATE_KEY=0x... npx -y @one-source/mcp@latest
190
+ ```
191
+
192
+ ### Manual Setup (Editing the Config File Directly)
193
+
194
+ The CLI commands above write to a JSON config file. You can also edit this file directly — this is useful for debugging or if you want to understand what the setup actually does.
195
+
196
+ **Claude Code** — Find which file your config is in by running `claude mcp get onesource`. Depending on the scope:
197
+ - **Local:** `.claude/settings.local.json` in your project directory
198
+ - **Project:** `.claude/settings.json` in your project directory
199
+ - **User:** `~/.claude/settings.json` (macOS/Linux) or `%USERPROFILE%\.claude\settings.json` (Windows)
200
+
201
+ **Claude Desktop:**
202
+ - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
203
+ - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
204
+
205
+ **Cursor:**
206
+ - **macOS:** `~/.cursor/mcp.json`
207
+ - **Windows:** `%USERPROFILE%\.cursor\mcp.json`
208
+
209
+ Open the config file and add (or update) the `onesource` entry inside `"mcpServers"`:
210
+
211
+ ```json
212
+ {
213
+ "mcpServers": {
214
+ "onesource": {
215
+ "command": "npx",
216
+ "args": ["-y", "@one-source/mcp@latest"],
217
+ "env": {
218
+ "X402_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY_HERE"
219
+ }
220
+ }
221
+ }
222
+ }
223
+ ```
224
+
225
+ Save the file, then reload (see below).
226
+
227
+ ### Important: Reload After Config Changes
228
+
229
+ Changing the config file (via `claude mcp add` or manual edit) does **not** automatically restart the running MCP server. You must reload:
230
+
231
+ - **Claude Code:** Run `/reload-plugins` (preferred — no restart needed), or restart Claude Code entirely.
232
+ - **Claude Desktop / Cursor:** Restart the app — close it completely and reopen.
233
+
234
+ Without reloading, the old server process keeps running with the old config, and `1s_setup_check` will still show "Not configured" even though the key is in the file.
235
+
236
+ ### Alternative: Set the Key as an Environment Variable
237
+
238
+ If the `env` block in the config isn't reaching the server after reloading, you can set the key as an environment variable directly instead:
239
+
240
+ **bash / zsh (macOS / Linux):**
241
+
242
+ ```bash
243
+ export X402_PRIVATE_KEY=0x...
244
+ ```
245
+
246
+ To make it persistent, add the line to your `~/.bashrc`, `~/.zshrc`, or `~/.profile`.
247
+
248
+ **PowerShell (Windows):**
249
+
250
+ ```powershell
251
+ $env:X402_PRIVATE_KEY = "0x..."
252
+ ```
253
+
254
+ This only lasts for the current session. To make it persistent, either:
255
+ - Add it to your PowerShell profile (`notepad $PROFILE`, add the line, restart PowerShell)
256
+ - Or set it as a system environment variable: **Settings > System > About > Advanced system settings > Environment Variables > User variables > New** — name: `X402_PRIVATE_KEY`, value: `0x...`
257
+
258
+ After setting the variable, restart your MCP client and run `1s_setup_check` to confirm.
259
+
260
+ > **Windows note:** Claude Code's `/doctor` command may warn that Windows requires a `cmd /c` wrapper to execute `npx`. If you encounter issues, update the config to use `"command": "cmd"` with `"args": ["/c", "npx", "-y", "@one-source/mcp@latest"]`.
261
+
262
+ ### Security
263
+
264
+ - **Never** commit your private key to source control.
265
+ - Use environment variables, a `.env` file (excluded from git), or a secrets manager.
266
+ - Use a dedicated wallet with minimal funds — only what you need for API calls.
267
+
268
+ ## Step 5: Find Your Wallet Address (x402)
269
+
270
+ After setting the key and reloading the MCP server:
271
+
272
+ 1. Call `1s_setup_check` — it shows the wallet address derived from your key under "Wallet address". This is the address you need to fund.
273
+ 2. Alternatively, import the key into MetaMask to see the address.
274
+
275
+ ## Step 6: Fund the Wallet with USDC on Base (x402)
276
+
277
+ The wallet must hold **USDC on the Base network** (not Ethereum mainnet, not other tokens).
278
+
279
+ 1. Send USDC to the wallet address from Step 5 **on the Base network**.
280
+ 2. A few dollars ($1–5 USDC) is enough for hundreds of API calls.
281
+
282
+ If your USDC is on Ethereum mainnet, bridge it to Base using the [Base Bridge](https://bridge.base.org) or any cross-chain bridge that supports Base.
283
+
284
+ ## Step 7: Verify
285
+
286
+ After setting your auth (either option) and reloading:
287
+
288
+ 1. **Check MCP connection** — Run `/mcp` to confirm the `onesource` server is connected.
289
+ 2. **Run `1s_setup_check`** — You should see:
290
+ - **Authentication:** `Configured (API key)` or `Configured (x402)` — not "Not configured"
291
+ - **Wallet address:** Your wallet address (x402 only)
292
+ - **API backend:** Reachable
293
+ 3. **Test a live tool** — Call `1s_network_info` for ethereum. If it returns a block number and gas price, auth is working end-to-end.
294
+
295
+ > **Tip:** If you edited the config file manually (instead of using `claude mcp add`), you must run `/reload-plugins` for changes to take effect. Restarting Claude Code also works.
296
+
297
+ ## Troubleshooting
298
+
299
+ | Problem | Solution |
300
+ |---------|----------|
301
+ | `1s_setup_check` shows "Not configured" | Most common cause: config was changed but the MCP server wasn't reloaded. Run `/reload-plugins` in Claude Code, or restart Claude Desktop / Cursor. If the key still isn't reaching the server, try setting it as an environment variable directly — see **Alternative: Set the Key as an Environment Variable** above. |
302
+ | `1s_setup_check` shows API key configured but tools return 402 | The key may be invalid or the account may not have a developer plan. Verify the key at app.onesource.io. |
303
+ | "MCP server onesource already exists" error | Run `claude mcp remove onesource` first, then re-add it with your updated config. |
304
+ | Config changed but nothing happened | Run `/reload-plugins` in Claude Code to reload MCP servers, then `/mcp` to check connection status. |
305
+ | Tool returns HTTP 402 error (x402 path) | x402 is not configured, or the wallet has insufficient USDC on Base. Check `1s_setup_check` for wallet address and balance. |
306
+ | "x402 setup failed" in server logs | The private key format is wrong. It must be a 64-character hex string (with or without `0x` prefix). |
307
+ | Key is set but wallet shows 0 USDC | Make sure USDC is on the **Base** network, not Ethereum mainnet or another chain. |
308
+ | Tools work but results seem stale | Check `1s_setup_check` for version — you may need to update to the latest. |