@one-source/api-mcp 1.0.0 → 1.2.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.
- package/README.md +8 -56
- package/README.npm.md +99 -0
- package/README.repo.md +153 -0
- package/package.json +19 -1
package/README.md
CHANGED
|
@@ -25,7 +25,8 @@ claude mcp add onesource-api -- npx onesource-api-mcp
|
|
|
25
25
|
|
|
26
26
|
## Tools (34)
|
|
27
27
|
|
|
28
|
-
|
|
28
|
+
|
|
29
|
+
### Indexed Data (12 tools)
|
|
29
30
|
|
|
30
31
|
| Tool | Description |
|
|
31
32
|
|------|-------------|
|
|
@@ -42,7 +43,8 @@ claude mcp add onesource-api -- npx onesource-api-mcp
|
|
|
42
43
|
| `1s_tx_details` | Transaction with decoded events |
|
|
43
44
|
| `1s_wallet_nfts` | Wallet NFT portfolio |
|
|
44
45
|
|
|
45
|
-
|
|
46
|
+
|
|
47
|
+
### Live Chain Data (12 tools)
|
|
46
48
|
|
|
47
49
|
| Tool | Description |
|
|
48
50
|
|------|-------------|
|
|
@@ -59,7 +61,8 @@ claude mcp add onesource-api -- npx onesource-api-mcp
|
|
|
59
61
|
| `1s_total_supply_live` | Token total supply |
|
|
60
62
|
| `1s_tx_details_live` | Transaction + receipt via RPC |
|
|
61
63
|
|
|
62
|
-
|
|
64
|
+
|
|
65
|
+
### Chain Utilities (10 tools)
|
|
63
66
|
|
|
64
67
|
| Tool | Description |
|
|
65
68
|
|------|-------------|
|
|
@@ -74,6 +77,7 @@ claude mcp add onesource-api -- npx onesource-api-mcp
|
|
|
74
77
|
| `1s_storage_read` | Read storage slot |
|
|
75
78
|
| `1s_tx_receipt` | Transaction receipt |
|
|
76
79
|
|
|
80
|
+
|
|
77
81
|
## Networks
|
|
78
82
|
|
|
79
83
|
All tools accept an optional `network` parameter:
|
|
@@ -84,63 +88,11 @@ All tools accept an optional `network` parameter:
|
|
|
84
88
|
| `sepolia` | Ethereum Sepolia testnet |
|
|
85
89
|
| `avax` | Avalanche C-Chain |
|
|
86
90
|
|
|
91
|
+
|
|
87
92
|
## Payment (x402)
|
|
88
93
|
|
|
89
94
|
Endpoints are priced in USDC on Base via [x402](https://github.com/coinbase/x402). When the backend has payments enabled, tool calls return a 402 with payment details. Agents using [`@x402/fetch`](https://www.npmjs.com/package/@x402/fetch) handle this automatically.
|
|
90
95
|
|
|
91
|
-
## Configuration
|
|
92
|
-
|
|
93
|
-
| Variable | Default | Description |
|
|
94
|
-
|----------|---------|-------------|
|
|
95
|
-
| `ONESOURCE_BASE_URL` | `https://skills.onesource.io` | Skills API endpoint |
|
|
96
|
-
| `ONESOURCE_ANALYTICS` | `true` | Set `false` to disable analytics |
|
|
97
|
-
| `ONESOURCE_ANALYTICS_URL` | — | Dashboard endpoint for event ingestion |
|
|
98
|
-
| `ONESOURCE_ANALYTICS_KEY` | — | API key for the analytics dashboard |
|
|
99
|
-
|
|
100
|
-
## Transport Modes
|
|
101
|
-
|
|
102
|
-
```sh
|
|
103
|
-
# stdio (default — for MCP clients)
|
|
104
|
-
npx onesource-api-mcp
|
|
105
|
-
|
|
106
|
-
# HTTP (for testing or remote access)
|
|
107
|
-
npx onesource-api-mcp --http
|
|
108
|
-
npx onesource-api-mcp --http --port=8080
|
|
109
|
-
```
|
|
110
|
-
|
|
111
|
-
HTTP mode binds to `127.0.0.1` by default.
|
|
112
|
-
|
|
113
|
-
## Adding a New Tool
|
|
114
|
-
|
|
115
|
-
When a new SKILL.md is added to `skills/OneSource*/`, a corresponding MCP tool file needs to be created here.
|
|
116
|
-
|
|
117
|
-
**Step 1:** Create the SKILL.md in the skills repo (see the skills README for format).
|
|
118
|
-
|
|
119
|
-
**Step 2:** Scaffold the tool file:
|
|
120
|
-
|
|
121
|
-
```sh
|
|
122
|
-
cd mcp/
|
|
123
|
-
npm run new-tool
|
|
124
|
-
```
|
|
125
|
-
|
|
126
|
-
This prompts for:
|
|
127
|
-
- **Tool name** — `1s_` prefix, snake_case (e.g. `1s_token_info`)
|
|
128
|
-
- **Category** — `indexed` (OpenSearch), `live` (RPC with indexed counterpart), or `chain` (RPC-only utility)
|
|
129
|
-
- **Description** — one-liner for the tool
|
|
130
|
-
- **Endpoint** — REST API path (e.g. `/api/chain/my-endpoint`)
|
|
131
|
-
- **Method** — GET or POST
|
|
132
|
-
|
|
133
|
-
It generates a tool file in `src/tools/{category}/` with TODO markers.
|
|
134
|
-
|
|
135
|
-
**Step 3:** Edit the generated file — fill in the Zod schema parameters and handler logic. Use the shared params from `src/types.ts` (`addressParam`, `txHashParam`, `tokenIdParam`, `hexDataParam`, `networkParam`, `limitParam`, `blockNumberParam`).
|
|
136
|
-
|
|
137
|
-
**Step 4:** Build:
|
|
138
|
-
|
|
139
|
-
```sh
|
|
140
|
-
npm run build
|
|
141
|
-
```
|
|
142
|
-
|
|
143
|
-
This auto-regenerates the tool index and compiles. The new tool is immediately available in the MCP server.
|
|
144
96
|
|
|
145
97
|
## License
|
|
146
98
|
|
package/README.npm.md
ADDED
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
# onesource-api-mcp
|
|
2
|
+
|
|
3
|
+
MCP server for OneSource blockchain data. 34 named tools for balances, NFTs, transactions, events, and live chain queries via x402 micropayments.
|
|
4
|
+
|
|
5
|
+
```
|
|
6
|
+
npx onesource-api-mcp
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
## Install
|
|
10
|
+
|
|
11
|
+
```sh
|
|
12
|
+
# Claude Code
|
|
13
|
+
claude mcp add onesource-api -- npx onesource-api-mcp
|
|
14
|
+
|
|
15
|
+
# Claude Desktop / Cursor — add to MCP config:
|
|
16
|
+
{
|
|
17
|
+
"mcpServers": {
|
|
18
|
+
"onesource-api": {
|
|
19
|
+
"command": "npx",
|
|
20
|
+
"args": ["-y", "onesource-api-mcp"]
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## Tools (34)
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
### Indexed Data (12 tools)
|
|
30
|
+
|
|
31
|
+
| Tool | Description |
|
|
32
|
+
|------|-------------|
|
|
33
|
+
| `1s_address_txs` | Address transaction history |
|
|
34
|
+
| `1s_block` | Block details by number |
|
|
35
|
+
| `1s_contract_info` | Contract metadata |
|
|
36
|
+
| `1s_erc1155_balance` | ERC1155 token balance |
|
|
37
|
+
| `1s_erc20_balance` | ERC20 token balance |
|
|
38
|
+
| `1s_erc20_transfers` | ERC20 transfer history |
|
|
39
|
+
| `1s_events` | Event log search |
|
|
40
|
+
| `1s_nft_media` | NFT processed media URLs |
|
|
41
|
+
| `1s_nft_metadata` | NFT metadata and traits |
|
|
42
|
+
| `1s_nft_owner` | NFT current owner |
|
|
43
|
+
| `1s_tx_details` | Transaction with decoded events |
|
|
44
|
+
| `1s_wallet_nfts` | Wallet NFT portfolio |
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
### Live Chain Data (12 tools)
|
|
48
|
+
|
|
49
|
+
| Tool | Description |
|
|
50
|
+
|------|-------------|
|
|
51
|
+
| `1s_allowance_live` | ERC20 allowance check |
|
|
52
|
+
| `1s_contract_info_live` | Contract type detection via ERC165 |
|
|
53
|
+
| `1s_erc1155_balance_live` | ERC1155 balance via RPC |
|
|
54
|
+
| `1s_erc20_balance_live` | ERC20 balance via balanceOf |
|
|
55
|
+
| `1s_erc20_transfers_live` | ERC20 Transfer logs via eth_getLogs |
|
|
56
|
+
| `1s_erc721_tokens_live` | ERC721 token enumeration |
|
|
57
|
+
| `1s_events_live` | Event logs via eth_getLogs |
|
|
58
|
+
| `1s_multi_balance_live` | ETH + multiple ERC20 balances |
|
|
59
|
+
| `1s_nft_metadata_live` | NFT metadata via tokenURI |
|
|
60
|
+
| `1s_nft_owner_live` | NFT owner via ownerOf |
|
|
61
|
+
| `1s_total_supply_live` | Token total supply |
|
|
62
|
+
| `1s_tx_details_live` | Transaction + receipt via RPC |
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
### Chain Utilities (10 tools)
|
|
66
|
+
|
|
67
|
+
| Tool | Description |
|
|
68
|
+
|------|-------------|
|
|
69
|
+
| `1s_contract_code` | Contract bytecode |
|
|
70
|
+
| `1s_ens_resolve` | ENS name/address resolution |
|
|
71
|
+
| `1s_estimate_gas` | Gas estimation |
|
|
72
|
+
| `1s_network_info` | Chain ID, block number, gas price |
|
|
73
|
+
| `1s_nonce` | Transaction count |
|
|
74
|
+
| `1s_pending_block` | Pending block from mempool |
|
|
75
|
+
| `1s_proxy_detect` | Proxy contract detection |
|
|
76
|
+
| `1s_simulate_call` | Simulate eth_call |
|
|
77
|
+
| `1s_storage_read` | Read storage slot |
|
|
78
|
+
| `1s_tx_receipt` | Transaction receipt |
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
## Networks
|
|
82
|
+
|
|
83
|
+
All tools accept an optional `network` parameter:
|
|
84
|
+
|
|
85
|
+
| Network | Description |
|
|
86
|
+
|---------|-------------|
|
|
87
|
+
| `ethereum` | Ethereum mainnet (default) |
|
|
88
|
+
| `sepolia` | Ethereum Sepolia testnet |
|
|
89
|
+
| `avax` | Avalanche C-Chain |
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
## Payment (x402)
|
|
93
|
+
|
|
94
|
+
Endpoints are priced in USDC on Base via [x402](https://github.com/coinbase/x402). When the backend has payments enabled, tool calls return a 402 with payment details. Agents using [`@x402/fetch`](https://www.npmjs.com/package/@x402/fetch) handle this automatically.
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
## License
|
|
98
|
+
|
|
99
|
+
MIT
|
package/README.repo.md
ADDED
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
# onesource-api-mcp
|
|
2
|
+
|
|
3
|
+
MCP server for OneSource blockchain data. 34 named tools for balances, NFTs, transactions, events, and live chain queries via x402 micropayments.
|
|
4
|
+
|
|
5
|
+
```
|
|
6
|
+
npx onesource-api-mcp
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
## Install
|
|
10
|
+
|
|
11
|
+
```sh
|
|
12
|
+
# Claude Code
|
|
13
|
+
claude mcp add onesource-api -- npx onesource-api-mcp
|
|
14
|
+
|
|
15
|
+
# Claude Desktop / Cursor — add to MCP config:
|
|
16
|
+
{
|
|
17
|
+
"mcpServers": {
|
|
18
|
+
"onesource-api": {
|
|
19
|
+
"command": "npx",
|
|
20
|
+
"args": ["-y", "onesource-api-mcp"]
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## Tools (34)
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
### Indexed Data (12 tools) — OpenSearch, cheaper, slight sync delay
|
|
30
|
+
|
|
31
|
+
| Tool | Description |
|
|
32
|
+
|------|-------------|
|
|
33
|
+
| `1s_address_txs` | Address transaction history |
|
|
34
|
+
| `1s_block` | Block details by number |
|
|
35
|
+
| `1s_contract_info` | Contract metadata |
|
|
36
|
+
| `1s_erc1155_balance` | ERC1155 token balance |
|
|
37
|
+
| `1s_erc20_balance` | ERC20 token balance |
|
|
38
|
+
| `1s_erc20_transfers` | ERC20 transfer history |
|
|
39
|
+
| `1s_events` | Event log search |
|
|
40
|
+
| `1s_nft_media` | NFT processed media URLs |
|
|
41
|
+
| `1s_nft_metadata` | NFT metadata and traits |
|
|
42
|
+
| `1s_nft_owner` | NFT current owner |
|
|
43
|
+
| `1s_tx_details` | Transaction with decoded events |
|
|
44
|
+
| `1s_wallet_nfts` | Wallet NFT portfolio |
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
### Live Chain Data (12 tools) — Direct RPC, real-time
|
|
48
|
+
|
|
49
|
+
| Tool | Description |
|
|
50
|
+
|------|-------------|
|
|
51
|
+
| `1s_allowance_live` | ERC20 allowance check |
|
|
52
|
+
| `1s_contract_info_live` | Contract type detection via ERC165 |
|
|
53
|
+
| `1s_erc1155_balance_live` | ERC1155 balance via RPC |
|
|
54
|
+
| `1s_erc20_balance_live` | ERC20 balance via balanceOf |
|
|
55
|
+
| `1s_erc20_transfers_live` | ERC20 Transfer logs via eth_getLogs |
|
|
56
|
+
| `1s_erc721_tokens_live` | ERC721 token enumeration |
|
|
57
|
+
| `1s_events_live` | Event logs via eth_getLogs |
|
|
58
|
+
| `1s_multi_balance_live` | ETH + multiple ERC20 balances |
|
|
59
|
+
| `1s_nft_metadata_live` | NFT metadata via tokenURI |
|
|
60
|
+
| `1s_nft_owner_live` | NFT owner via ownerOf |
|
|
61
|
+
| `1s_total_supply_live` | Token total supply |
|
|
62
|
+
| `1s_tx_details_live` | Transaction + receipt via RPC |
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
### Chain Utilities (10 tools) — RPC only
|
|
66
|
+
|
|
67
|
+
| Tool | Description |
|
|
68
|
+
|------|-------------|
|
|
69
|
+
| `1s_contract_code` | Contract bytecode |
|
|
70
|
+
| `1s_ens_resolve` | ENS name/address resolution |
|
|
71
|
+
| `1s_estimate_gas` | Gas estimation |
|
|
72
|
+
| `1s_network_info` | Chain ID, block number, gas price |
|
|
73
|
+
| `1s_nonce` | Transaction count |
|
|
74
|
+
| `1s_pending_block` | Pending block from mempool |
|
|
75
|
+
| `1s_proxy_detect` | Proxy contract detection |
|
|
76
|
+
| `1s_simulate_call` | Simulate eth_call |
|
|
77
|
+
| `1s_storage_read` | Read storage slot |
|
|
78
|
+
| `1s_tx_receipt` | Transaction receipt |
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
## Networks
|
|
82
|
+
|
|
83
|
+
All tools accept an optional `network` parameter:
|
|
84
|
+
|
|
85
|
+
| Network | Description |
|
|
86
|
+
|---------|-------------|
|
|
87
|
+
| `ethereum` | Ethereum mainnet (default) |
|
|
88
|
+
| `sepolia` | Ethereum Sepolia testnet |
|
|
89
|
+
| `avax` | Avalanche C-Chain |
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
## Payment (x402)
|
|
93
|
+
|
|
94
|
+
Endpoints are priced in USDC on Base via [x402](https://github.com/coinbase/x402). When the backend has payments enabled, tool calls return a 402 with payment details. Agents using [`@x402/fetch`](https://www.npmjs.com/package/@x402/fetch) handle this automatically.
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
## Configuration
|
|
98
|
+
|
|
99
|
+
| Variable | Default | Description |
|
|
100
|
+
|----------|---------|-------------|
|
|
101
|
+
| `ONESOURCE_BASE_URL` | `https://skills.onesource.io` | Skills API endpoint |
|
|
102
|
+
| `ONESOURCE_ANALYTICS` | `true` | Set `false` to disable analytics |
|
|
103
|
+
| `ONESOURCE_ANALYTICS_URL` | — | Dashboard endpoint for event ingestion |
|
|
104
|
+
| `ONESOURCE_ANALYTICS_KEY` | — | API key for the analytics dashboard |
|
|
105
|
+
|
|
106
|
+
## Transport Modes
|
|
107
|
+
|
|
108
|
+
```sh
|
|
109
|
+
# stdio (default — for MCP clients)
|
|
110
|
+
npx onesource-api-mcp
|
|
111
|
+
|
|
112
|
+
# HTTP (for testing or remote access)
|
|
113
|
+
npx onesource-api-mcp --http
|
|
114
|
+
npx onesource-api-mcp --http --port=8080
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
HTTP mode binds to `127.0.0.1` by default.
|
|
118
|
+
|
|
119
|
+
## Adding a New Tool
|
|
120
|
+
|
|
121
|
+
When a new SKILL.md is added to `skills/OneSource*/`, a corresponding MCP tool file needs to be created here.
|
|
122
|
+
|
|
123
|
+
**Step 1:** Create the SKILL.md in the skills repo (see the skills README for format).
|
|
124
|
+
|
|
125
|
+
**Step 2:** Scaffold the tool file:
|
|
126
|
+
|
|
127
|
+
```sh
|
|
128
|
+
cd mcp/
|
|
129
|
+
npm run new-tool
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
This prompts for:
|
|
133
|
+
- **Tool name** — `1s_` prefix, snake_case (e.g. `1s_token_info`)
|
|
134
|
+
- **Category** — `indexed` (OpenSearch), `live` (RPC with indexed counterpart), or `chain` (RPC-only utility)
|
|
135
|
+
- **Description** — one-liner for the tool
|
|
136
|
+
- **Endpoint** — REST API path (e.g. `/api/chain/my-endpoint`)
|
|
137
|
+
- **Method** — GET or POST
|
|
138
|
+
|
|
139
|
+
It generates a tool file in `src/tools/{category}/` with TODO markers.
|
|
140
|
+
|
|
141
|
+
**Step 3:** Edit the generated file — fill in the Zod schema parameters and handler logic. Use the shared params from `src/types.ts` (`addressParam`, `txHashParam`, `tokenIdParam`, `hexDataParam`, `networkParam`, `limitParam`, `blockNumberParam`).
|
|
142
|
+
|
|
143
|
+
**Step 4:** Build:
|
|
144
|
+
|
|
145
|
+
```sh
|
|
146
|
+
npm run build
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
This auto-regenerates the tool index and compiles. The new tool is immediately available in the MCP server.
|
|
150
|
+
|
|
151
|
+
## License
|
|
152
|
+
|
|
153
|
+
MIT
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@one-source/api-mcp",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.2.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "MCP server for OneSource blockchain data — 34 named tools for balances, NFTs, transactions, events, and live chain queries via x402",
|
|
6
6
|
"bin": {
|
|
@@ -12,6 +12,22 @@
|
|
|
12
12
|
".": {
|
|
13
13
|
"types": "./dist/create-server.d.ts",
|
|
14
14
|
"default": "./dist/create-server.js"
|
|
15
|
+
},
|
|
16
|
+
"./tools": {
|
|
17
|
+
"types": "./dist/tools/index.d.ts",
|
|
18
|
+
"default": "./dist/tools/index.js"
|
|
19
|
+
},
|
|
20
|
+
"./client": {
|
|
21
|
+
"types": "./dist/client.d.ts",
|
|
22
|
+
"default": "./dist/client.js"
|
|
23
|
+
},
|
|
24
|
+
"./analytics": {
|
|
25
|
+
"types": "./dist/analytics.d.ts",
|
|
26
|
+
"default": "./dist/analytics.js"
|
|
27
|
+
},
|
|
28
|
+
"./types": {
|
|
29
|
+
"types": "./dist/types.d.ts",
|
|
30
|
+
"default": "./dist/types.js"
|
|
15
31
|
}
|
|
16
32
|
},
|
|
17
33
|
"files": [
|
|
@@ -36,6 +52,8 @@
|
|
|
36
52
|
"new-tool": "node scripts/new-tool.mjs",
|
|
37
53
|
"prebuild": "npm run gen",
|
|
38
54
|
"build": "tsc",
|
|
55
|
+
"prepack": "node -e \"fs=require('fs');fs.copyFileSync('README.md','README.repo.md');fs.copyFileSync('README.npm.md','README.md')\"",
|
|
56
|
+
"postpack": "node -e \"fs=require('fs');fs.renameSync('README.repo.md','README.md')\"",
|
|
39
57
|
"prepublishOnly": "npm run build",
|
|
40
58
|
"dev": "tsc --watch",
|
|
41
59
|
"test": "vitest run",
|