@one-source/mcp 3.0.0 → 3.1.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 +42 -2
- package/README.npm.md +42 -2
- package/README.repo.md +295 -255
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -106,9 +106,49 @@ All blockchain API tools accept an optional `network` parameter:
|
|
|
106
106
|
|
|
107
107
|
## Payment (x402)
|
|
108
108
|
|
|
109
|
-
Blockchain API endpoints are priced in USDC on Base via [x402](https://github.com/coinbase/x402). When the
|
|
109
|
+
Blockchain API endpoints are priced in USDC on Base via [x402](https://github.com/coinbase/x402). When you set `X402_PRIVATE_KEY`, the server automatically handles payments — tool calls that return HTTP 402 are paid and retried without any extra work from the agent.
|
|
110
110
|
|
|
111
|
-
Documentation tools are always free — no
|
|
111
|
+
Documentation tools are always free — no key or payment needed.
|
|
112
|
+
|
|
113
|
+
### Setup
|
|
114
|
+
|
|
115
|
+
1. **Get an EVM private key** — export one from MetaMask, Coinbase Wallet, or any EVM wallet. The key is a hex string starting with `0x`.
|
|
116
|
+
2. **Fund the wallet with USDC on Base** — the wallet address derived from the key must hold USDC on the [Base](https://base.org) network. Bridge or transfer USDC to it.
|
|
117
|
+
3. **Pass the key to the server** using one of the methods below.
|
|
118
|
+
|
|
119
|
+
### Claude Code
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
claude mcp add onesource -e X402_PRIVATE_KEY=0x... -- npx @one-source/mcp
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
### Claude Desktop / Cursor
|
|
126
|
+
|
|
127
|
+
Add the `env` block to your MCP config:
|
|
128
|
+
|
|
129
|
+
```json
|
|
130
|
+
{
|
|
131
|
+
"mcpServers": {
|
|
132
|
+
"onesource": {
|
|
133
|
+
"command": "npx",
|
|
134
|
+
"args": ["-y", "@one-source/mcp"],
|
|
135
|
+
"env": {
|
|
136
|
+
"X402_PRIVATE_KEY": "0x..."
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
### Any MCP Client (stdio)
|
|
144
|
+
|
|
145
|
+
```bash
|
|
146
|
+
X402_PRIVATE_KEY=0x... npx @one-source/mcp
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
### Security
|
|
150
|
+
|
|
151
|
+
Never commit your private key to source control. Use environment variables, a `.env` file (excluded from git), or a secrets manager.
|
|
112
152
|
|
|
113
153
|
## License
|
|
114
154
|
|
package/README.npm.md
CHANGED
|
@@ -106,9 +106,49 @@ All blockchain API tools accept an optional `network` parameter:
|
|
|
106
106
|
|
|
107
107
|
## Payment (x402)
|
|
108
108
|
|
|
109
|
-
Blockchain API endpoints are priced in USDC on Base via [x402](https://github.com/coinbase/x402). When the
|
|
109
|
+
Blockchain API endpoints are priced in USDC on Base via [x402](https://github.com/coinbase/x402). When you set `X402_PRIVATE_KEY`, the server automatically handles payments — tool calls that return HTTP 402 are paid and retried without any extra work from the agent.
|
|
110
110
|
|
|
111
|
-
Documentation tools are always free — no
|
|
111
|
+
Documentation tools are always free — no key or payment needed.
|
|
112
|
+
|
|
113
|
+
### Setup
|
|
114
|
+
|
|
115
|
+
1. **Get an EVM private key** — export one from MetaMask, Coinbase Wallet, or any EVM wallet. The key is a hex string starting with `0x`.
|
|
116
|
+
2. **Fund the wallet with USDC on Base** — the wallet address derived from the key must hold USDC on the [Base](https://base.org) network. Bridge or transfer USDC to it.
|
|
117
|
+
3. **Pass the key to the server** using one of the methods below.
|
|
118
|
+
|
|
119
|
+
### Claude Code
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
claude mcp add onesource -e X402_PRIVATE_KEY=0x... -- npx @one-source/mcp
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
### Claude Desktop / Cursor
|
|
126
|
+
|
|
127
|
+
Add the `env` block to your MCP config:
|
|
128
|
+
|
|
129
|
+
```json
|
|
130
|
+
{
|
|
131
|
+
"mcpServers": {
|
|
132
|
+
"onesource": {
|
|
133
|
+
"command": "npx",
|
|
134
|
+
"args": ["-y", "@one-source/mcp"],
|
|
135
|
+
"env": {
|
|
136
|
+
"X402_PRIVATE_KEY": "0x..."
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
### Any MCP Client (stdio)
|
|
144
|
+
|
|
145
|
+
```bash
|
|
146
|
+
X402_PRIVATE_KEY=0x... npx @one-source/mcp
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
### Security
|
|
150
|
+
|
|
151
|
+
Never commit your private key to source control. Use environment variables, a `.env` file (excluded from git), or a secrets manager.
|
|
112
152
|
|
|
113
153
|
## License
|
|
114
154
|
|
package/README.repo.md
CHANGED
|
@@ -1,255 +1,295 @@
|
|
|
1
|
-
# @one-source/mcp
|
|
2
|
-
|
|
3
|
-
Unified MCP server for [OneSource](https://docs.onesource.io) — 31 tools for blockchain data, live chain queries, and API documentation in a single server.
|
|
4
|
-
|
|
5
|
-
Combines [`@one-source/api-mcp`](https://www.npmjs.com/package/@one-source/api-mcp) (22 tools) and [`@one-source/docs-mcp`](https://www.npmjs.com/package/@one-source/docs-mcp) (9 tools) so your AI assistant gets full access to OneSource with one MCP connection.
|
|
6
|
-
|
|
7
|
-
> **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.
|
|
8
|
-
|
|
9
|
-
## Quick Start
|
|
10
|
-
|
|
11
|
-
### Claude Code
|
|
12
|
-
|
|
13
|
-
```bash
|
|
14
|
-
claude mcp add onesource -- npx @one-source/mcp
|
|
15
|
-
```
|
|
16
|
-
|
|
17
|
-
### Claude Desktop / Cursor
|
|
18
|
-
|
|
19
|
-
Add to your MCP config:
|
|
20
|
-
|
|
21
|
-
```json
|
|
22
|
-
{
|
|
23
|
-
"mcpServers": {
|
|
24
|
-
"onesource": {
|
|
25
|
-
"command": "npx",
|
|
26
|
-
"args": ["-y", "@one-source/mcp"]
|
|
27
|
-
}
|
|
28
|
-
}
|
|
29
|
-
}
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
### Any MCP Client (stdio)
|
|
33
|
-
|
|
34
|
-
```bash
|
|
35
|
-
npx @one-source/mcp
|
|
36
|
-
```
|
|
37
|
-
|
|
38
|
-
### HTTP Server (self-hosted)
|
|
39
|
-
|
|
40
|
-
```bash
|
|
41
|
-
npx @one-source/mcp --http
|
|
42
|
-
npx @one-source/mcp --http --port=8080
|
|
43
|
-
```
|
|
44
|
-
|
|
45
|
-
Then connect your MCP client to `http://localhost:3000/`.
|
|
46
|
-
|
|
47
|
-
Health check: `GET http://localhost:3000/health`
|
|
48
|
-
|
|
49
|
-
## Tools (31)
|
|
50
|
-
|
|
51
|
-
### Blockchain API — Live Chain (12 tools)
|
|
52
|
-
|
|
53
|
-
| Tool | Description |
|
|
54
|
-
|------|-------------|
|
|
55
|
-
| `1s_allowance_live` | ERC20 allowance check |
|
|
56
|
-
| `1s_contract_info_live` | Contract type detection via ERC165 |
|
|
57
|
-
| `1s_erc1155_balance_live` | ERC1155 balance via RPC |
|
|
58
|
-
| `1s_erc20_balance_live` | ERC20 balance via balanceOf |
|
|
59
|
-
| `1s_erc20_transfers_live` | ERC20 Transfer logs via eth_getLogs |
|
|
60
|
-
| `1s_erc721_tokens_live` | ERC721 token enumeration |
|
|
61
|
-
| `1s_events_live` | Event logs via eth_getLogs |
|
|
62
|
-
| `1s_multi_balance_live` | ETH + multiple ERC20 balances |
|
|
63
|
-
| `1s_nft_metadata_live` | NFT metadata via tokenURI |
|
|
64
|
-
| `1s_nft_owner_live` | NFT owner via ownerOf |
|
|
65
|
-
| `1s_total_supply_live` | Token total supply |
|
|
66
|
-
| `1s_tx_details_live` | Transaction + receipt via RPC |
|
|
67
|
-
|
|
68
|
-
### Blockchain API — Chain Utilities (10 tools)
|
|
69
|
-
|
|
70
|
-
RPC only.
|
|
71
|
-
|
|
72
|
-
| Tool | Description |
|
|
73
|
-
|------|-------------|
|
|
74
|
-
| `1s_contract_code` | Contract bytecode |
|
|
75
|
-
| `1s_ens_resolve` | ENS name/address resolution |
|
|
76
|
-
| `1s_estimate_gas` | Gas estimation |
|
|
77
|
-
| `1s_network_info` | Chain ID, block number, gas price |
|
|
78
|
-
| `1s_nonce` | Transaction count |
|
|
79
|
-
| `1s_pending_block` | Pending block from mempool |
|
|
80
|
-
| `1s_proxy_detect` | Proxy contract detection |
|
|
81
|
-
| `1s_simulate_call` | Simulate eth_call |
|
|
82
|
-
| `1s_storage_read` | Read storage slot |
|
|
83
|
-
| `1s_tx_receipt` | Transaction receipt |
|
|
84
|
-
|
|
85
|
-
### Documentation (9 tools)
|
|
86
|
-
|
|
87
|
-
Read-only, no API key required.
|
|
88
|
-
|
|
89
|
-
| Tool | Purpose | When to use |
|
|
90
|
-
|------|---------|-------------|
|
|
91
|
-
| `search_docs` | Keyword search across all documentation | Finding guides, concepts, or API patterns |
|
|
92
|
-
| `get_query_reference` | Full reference for a root GraphQL query | Building a specific query with correct args/filters |
|
|
93
|
-
| `get_type_definition` | Schema definition for any type/enum/input | Understanding field shapes and return types |
|
|
94
|
-
| `list_examples` | Browse or search working GraphQL examples | Finding ready-to-use query patterns |
|
|
95
|
-
| `list_supported_chains` | All supported blockchain networks + endpoints | First question: "What chains are supported?" |
|
|
96
|
-
| `get_filter_reference` | Filter fields and operators for a list query | Building filtered queries with correct syntax |
|
|
97
|
-
| `get_pagination_guide` | Cursor-based pagination pattern with examples | Implementing pagination for list queries |
|
|
98
|
-
| `get_schema_overview` | High-level summary of the entire schema | Exploring the API surface before diving in |
|
|
99
|
-
| `get_authentication_guide` | API key format, headers, and endpoints | Setting up authentication for the first time |
|
|
100
|
-
|
|
101
|
-
## Networks
|
|
102
|
-
|
|
103
|
-
All blockchain API tools accept an optional `network` parameter:
|
|
104
|
-
|
|
105
|
-
| Network | Description |
|
|
106
|
-
|---------|-------------|
|
|
107
|
-
| `ethereum` | Ethereum mainnet (default) |
|
|
108
|
-
| `sepolia` | Ethereum Sepolia testnet |
|
|
109
|
-
| `avax` | Avalanche C-Chain |
|
|
110
|
-
|
|
111
|
-
## Payment (x402)
|
|
112
|
-
|
|
113
|
-
Blockchain API endpoints are priced in USDC on Base via [x402](https://github.com/coinbase/x402). When the
|
|
114
|
-
|
|
115
|
-
Documentation tools are always free — no
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
```bash
|
|
246
|
-
|
|
247
|
-
```
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
1
|
+
# @one-source/mcp
|
|
2
|
+
|
|
3
|
+
Unified MCP server for [OneSource](https://docs.onesource.io) — 31 tools for blockchain data, live chain queries, and API documentation in a single server.
|
|
4
|
+
|
|
5
|
+
Combines [`@one-source/api-mcp`](https://www.npmjs.com/package/@one-source/api-mcp) (22 tools) and [`@one-source/docs-mcp`](https://www.npmjs.com/package/@one-source/docs-mcp) (9 tools) so your AI assistant gets full access to OneSource with one MCP connection.
|
|
6
|
+
|
|
7
|
+
> **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.
|
|
8
|
+
|
|
9
|
+
## Quick Start
|
|
10
|
+
|
|
11
|
+
### Claude Code
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
claude mcp add onesource -- npx @one-source/mcp
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
### Claude Desktop / Cursor
|
|
18
|
+
|
|
19
|
+
Add to your MCP config:
|
|
20
|
+
|
|
21
|
+
```json
|
|
22
|
+
{
|
|
23
|
+
"mcpServers": {
|
|
24
|
+
"onesource": {
|
|
25
|
+
"command": "npx",
|
|
26
|
+
"args": ["-y", "@one-source/mcp"]
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
### Any MCP Client (stdio)
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
npx @one-source/mcp
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
### HTTP Server (self-hosted)
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
npx @one-source/mcp --http
|
|
42
|
+
npx @one-source/mcp --http --port=8080
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Then connect your MCP client to `http://localhost:3000/`.
|
|
46
|
+
|
|
47
|
+
Health check: `GET http://localhost:3000/health`
|
|
48
|
+
|
|
49
|
+
## Tools (31)
|
|
50
|
+
|
|
51
|
+
### Blockchain API — Live Chain (12 tools)
|
|
52
|
+
|
|
53
|
+
| Tool | Description |
|
|
54
|
+
|------|-------------|
|
|
55
|
+
| `1s_allowance_live` | ERC20 allowance check |
|
|
56
|
+
| `1s_contract_info_live` | Contract type detection via ERC165 |
|
|
57
|
+
| `1s_erc1155_balance_live` | ERC1155 balance via RPC |
|
|
58
|
+
| `1s_erc20_balance_live` | ERC20 balance via balanceOf |
|
|
59
|
+
| `1s_erc20_transfers_live` | ERC20 Transfer logs via eth_getLogs |
|
|
60
|
+
| `1s_erc721_tokens_live` | ERC721 token enumeration |
|
|
61
|
+
| `1s_events_live` | Event logs via eth_getLogs |
|
|
62
|
+
| `1s_multi_balance_live` | ETH + multiple ERC20 balances |
|
|
63
|
+
| `1s_nft_metadata_live` | NFT metadata via tokenURI |
|
|
64
|
+
| `1s_nft_owner_live` | NFT owner via ownerOf |
|
|
65
|
+
| `1s_total_supply_live` | Token total supply |
|
|
66
|
+
| `1s_tx_details_live` | Transaction + receipt via RPC |
|
|
67
|
+
|
|
68
|
+
### Blockchain API — Chain Utilities (10 tools)
|
|
69
|
+
|
|
70
|
+
RPC only.
|
|
71
|
+
|
|
72
|
+
| Tool | Description |
|
|
73
|
+
|------|-------------|
|
|
74
|
+
| `1s_contract_code` | Contract bytecode |
|
|
75
|
+
| `1s_ens_resolve` | ENS name/address resolution |
|
|
76
|
+
| `1s_estimate_gas` | Gas estimation |
|
|
77
|
+
| `1s_network_info` | Chain ID, block number, gas price |
|
|
78
|
+
| `1s_nonce` | Transaction count |
|
|
79
|
+
| `1s_pending_block` | Pending block from mempool |
|
|
80
|
+
| `1s_proxy_detect` | Proxy contract detection |
|
|
81
|
+
| `1s_simulate_call` | Simulate eth_call |
|
|
82
|
+
| `1s_storage_read` | Read storage slot |
|
|
83
|
+
| `1s_tx_receipt` | Transaction receipt |
|
|
84
|
+
|
|
85
|
+
### Documentation (9 tools)
|
|
86
|
+
|
|
87
|
+
Read-only, no API key required.
|
|
88
|
+
|
|
89
|
+
| Tool | Purpose | When to use |
|
|
90
|
+
|------|---------|-------------|
|
|
91
|
+
| `search_docs` | Keyword search across all documentation | Finding guides, concepts, or API patterns |
|
|
92
|
+
| `get_query_reference` | Full reference for a root GraphQL query | Building a specific query with correct args/filters |
|
|
93
|
+
| `get_type_definition` | Schema definition for any type/enum/input | Understanding field shapes and return types |
|
|
94
|
+
| `list_examples` | Browse or search working GraphQL examples | Finding ready-to-use query patterns |
|
|
95
|
+
| `list_supported_chains` | All supported blockchain networks + endpoints | First question: "What chains are supported?" |
|
|
96
|
+
| `get_filter_reference` | Filter fields and operators for a list query | Building filtered queries with correct syntax |
|
|
97
|
+
| `get_pagination_guide` | Cursor-based pagination pattern with examples | Implementing pagination for list queries |
|
|
98
|
+
| `get_schema_overview` | High-level summary of the entire schema | Exploring the API surface before diving in |
|
|
99
|
+
| `get_authentication_guide` | API key format, headers, and endpoints | Setting up authentication for the first time |
|
|
100
|
+
|
|
101
|
+
## Networks
|
|
102
|
+
|
|
103
|
+
All blockchain API tools accept an optional `network` parameter:
|
|
104
|
+
|
|
105
|
+
| Network | Description |
|
|
106
|
+
|---------|-------------|
|
|
107
|
+
| `ethereum` | Ethereum mainnet (default) |
|
|
108
|
+
| `sepolia` | Ethereum Sepolia testnet |
|
|
109
|
+
| `avax` | Avalanche C-Chain |
|
|
110
|
+
|
|
111
|
+
## Payment (x402)
|
|
112
|
+
|
|
113
|
+
Blockchain API endpoints are priced in USDC on Base via [x402](https://github.com/coinbase/x402). When you set `X402_PRIVATE_KEY`, the server automatically handles payments — tool calls that return HTTP 402 are paid and retried without any extra work from the agent.
|
|
114
|
+
|
|
115
|
+
Documentation tools are always free — no key or payment needed.
|
|
116
|
+
|
|
117
|
+
### Setup
|
|
118
|
+
|
|
119
|
+
1. **Get an EVM private key** — export one from MetaMask, Coinbase Wallet, or any EVM wallet. The key is a hex string starting with `0x`.
|
|
120
|
+
2. **Fund the wallet with USDC on Base** — the wallet address derived from the key must hold USDC on the [Base](https://base.org) network. Bridge or transfer USDC to it.
|
|
121
|
+
3. **Pass the key to the server** using one of the methods below.
|
|
122
|
+
|
|
123
|
+
### Claude Code
|
|
124
|
+
|
|
125
|
+
```bash
|
|
126
|
+
claude mcp add onesource -e X402_PRIVATE_KEY=0x... -- npx @one-source/mcp
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
### Claude Desktop / Cursor
|
|
130
|
+
|
|
131
|
+
Add the `env` block to your MCP config:
|
|
132
|
+
|
|
133
|
+
```json
|
|
134
|
+
{
|
|
135
|
+
"mcpServers": {
|
|
136
|
+
"onesource": {
|
|
137
|
+
"command": "npx",
|
|
138
|
+
"args": ["-y", "@one-source/mcp"],
|
|
139
|
+
"env": {
|
|
140
|
+
"X402_PRIVATE_KEY": "0x..."
|
|
141
|
+
}
|
|
142
|
+
}
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
### Any MCP Client (stdio)
|
|
148
|
+
|
|
149
|
+
```bash
|
|
150
|
+
X402_PRIVATE_KEY=0x... npx @one-source/mcp
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
### Security
|
|
154
|
+
|
|
155
|
+
Never commit your private key to source control. Use environment variables, a `.env` file (excluded from git), or a secrets manager.
|
|
156
|
+
|
|
157
|
+
## Environment Variables
|
|
158
|
+
|
|
159
|
+
| Variable | Default | Description |
|
|
160
|
+
|----------|---------|-------------|
|
|
161
|
+
| `ONESOURCE_BASE_URL` | `https://skills.onesource.io` | API base URL |
|
|
162
|
+
| `ONESOURCE_ANALYTICS` | — | Set to `false` to disable analytics |
|
|
163
|
+
| `ONESOURCE_ANALYTICS_URL` | — | Dashboard endpoint for analytics |
|
|
164
|
+
| `X402_ANALYTICS_KEY` | — | API key for dashboard analytics |
|
|
165
|
+
| `X402_PRIVATE_KEY` | — | EVM private key (hex, 0x-prefixed) for automatic x402 USDC payments on Base |
|
|
166
|
+
|
|
167
|
+
## Troubleshooting
|
|
168
|
+
|
|
169
|
+
**`npx` hangs with no output**
|
|
170
|
+
That's normal — stdio mode waits for JSON-RPC input on stdin. Use `--http` if you want an HTTP server you can curl.
|
|
171
|
+
|
|
172
|
+
**Port already in use**
|
|
173
|
+
Specify a different port: `npx @one-source/mcp --http --port=8080`
|
|
174
|
+
|
|
175
|
+
**Tools return "Data files may be missing"**
|
|
176
|
+
Try reinstalling: `npm install @one-source/mcp`
|
|
177
|
+
|
|
178
|
+
**"Type not found" even though it exists**
|
|
179
|
+
Type names are case-insensitive but must match the GraphQL name (e.g. `Transaction`, not `transaction_type`). The tool will suggest close matches.
|
|
180
|
+
|
|
181
|
+
## Registry Publishing
|
|
182
|
+
|
|
183
|
+
This package is listed on the [official MCP Registry](https://registry.modelcontextprotocol.io) under the verified namespace `io.onesource/mcp` and on [Glama](https://glama.ai/mcp/servers). When releasing a new version, update both registries.
|
|
184
|
+
|
|
185
|
+
### MCP Registry
|
|
186
|
+
|
|
187
|
+
#### First-Time Setup
|
|
188
|
+
|
|
189
|
+
##### 1. Install Go
|
|
190
|
+
|
|
191
|
+
Download the installer for your platform from [go.dev/dl](https://go.dev/dl/) and run it. Verify:
|
|
192
|
+
|
|
193
|
+
```bash
|
|
194
|
+
go version
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
##### 2. Install mcp-publisher
|
|
198
|
+
|
|
199
|
+
```bash
|
|
200
|
+
go install github.com/modelcontextprotocol/registry/cmd/mcp-publisher@latest
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
If the Go module path has changed and the command fails, download the binary directly from the [mcp-publisher GitHub releases](https://github.com/modelcontextprotocol/registry/releases) page instead.
|
|
204
|
+
|
|
205
|
+
On Windows, add Go's bin directory to your PATH if the command isn't recognized:
|
|
206
|
+
|
|
207
|
+
```powershell
|
|
208
|
+
$env:PATH += ";$env:USERPROFILE\go\bin"
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
Verify:
|
|
212
|
+
|
|
213
|
+
```bash
|
|
214
|
+
mcp-publisher --help
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
##### 3. DNS Authentication (already done)
|
|
218
|
+
|
|
219
|
+
The `onesource.io` domain has a DNS TXT record that proves ownership of the `io.onesource` namespace. This is already configured — you don't need to redo it.
|
|
220
|
+
|
|
221
|
+
The record is on the root domain (`onesource.io`, not `_mcp-registry.onesource.io`):
|
|
222
|
+
|
|
223
|
+
```
|
|
224
|
+
v=MCPv1; k=ed25519; p=7D3U5rufgNXb/lH2MthTRZdDzEGeE7/Jvg8YkiArQc8=
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
You can verify it resolves:
|
|
228
|
+
|
|
229
|
+
```bash
|
|
230
|
+
nslookup -type=TXT onesource.io 8.8.8.8
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
##### 4. Get the Private Key
|
|
234
|
+
|
|
235
|
+
Authentication requires the ed25519 private key in **hex format** that corresponds to the public key in the DNS record. Ask the team lead for this key — it's stored in the team's password manager / vault.
|
|
236
|
+
|
|
237
|
+
If you need to regenerate the keypair (this invalidates the current DNS record and requires updating it):
|
|
238
|
+
|
|
239
|
+
1. Generate a new ed25519 keypair (e.g., `openssl genpkey -algorithm Ed25519 -out key.pem`)
|
|
240
|
+
2. Extract the raw 32-byte private key seed and convert to hex:
|
|
241
|
+
```bash
|
|
242
|
+
openssl pkey -in key.pem -outform DER | tail -c 32 | xxd -p -c 32
|
|
243
|
+
```
|
|
244
|
+
3. Extract the public key in base64 for the DNS TXT record:
|
|
245
|
+
```bash
|
|
246
|
+
openssl pkey -in key.pem -pubout -outform DER | tail -c 32 | base64
|
|
247
|
+
```
|
|
248
|
+
4. Update the DNS TXT record on `onesource.io` with the new public key:
|
|
249
|
+
```
|
|
250
|
+
v=MCPv1; k=ed25519; p=<base64-public-key>
|
|
251
|
+
```
|
|
252
|
+
5. Wait for DNS propagation before attempting to log in.
|
|
253
|
+
|
|
254
|
+
#### Publishing a New Version
|
|
255
|
+
|
|
256
|
+
Every time you release a new npm version, update the MCP Registry:
|
|
257
|
+
|
|
258
|
+
1. **Publish to npm** (the registry validates the package exists, so this must happen first):
|
|
259
|
+
```bash
|
|
260
|
+
npm run build
|
|
261
|
+
npm publish --access public
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
2. **Update `server.json`** — set both `version` fields to match the new npm version:
|
|
265
|
+
```json
|
|
266
|
+
{
|
|
267
|
+
"version": "x.y.z",
|
|
268
|
+
...
|
|
269
|
+
"packages": [{ "version": "x.y.z", ... }]
|
|
270
|
+
}
|
|
271
|
+
```
|
|
272
|
+
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.
|
|
273
|
+
|
|
274
|
+
3. **Authenticate** (tokens expire, so do this each time):
|
|
275
|
+
```bash
|
|
276
|
+
mcp-publisher login dns --domain onesource.io --private-key <ed25519-hex-private-key>
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
4. **Publish to the registry:**
|
|
280
|
+
```bash
|
|
281
|
+
mcp-publisher publish
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
5. **Verify:**
|
|
285
|
+
```bash
|
|
286
|
+
curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=onesource"
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
### Glama
|
|
290
|
+
|
|
291
|
+
Glama auto-syncs from the GitHub repo daily. No manual steps needed after a release — just make sure changes are pushed to `main`. The `glama.json` file in the repo root controls ownership. Manual re-sync is available from the [Glama admin panel](https://glama.ai/mcp/servers) after claiming the server.
|
|
292
|
+
|
|
293
|
+
## License
|
|
294
|
+
|
|
295
|
+
Apache 2.0 — see [LICENSE](LICENSE) for details.
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@one-source/mcp",
|
|
3
3
|
"mcpName": "io.onesource/mcp",
|
|
4
|
-
"version": "3.
|
|
4
|
+
"version": "3.1.0",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"description": "Unified MCP server for OneSource — 31 tools for blockchain data and API documentation",
|
|
7
7
|
"bin": {
|
|
@@ -28,8 +28,8 @@
|
|
|
28
28
|
},
|
|
29
29
|
"dependencies": {
|
|
30
30
|
"@modelcontextprotocol/sdk": "^1.27.1",
|
|
31
|
-
"@one-source/api-mcp": "^3.
|
|
32
|
-
"@one-source/docs-mcp": "^3.
|
|
31
|
+
"@one-source/api-mcp": "^3.1.0",
|
|
32
|
+
"@one-source/docs-mcp": "^3.1.0",
|
|
33
33
|
"zod": "^3.24.0"
|
|
34
34
|
},
|
|
35
35
|
"devDependencies": {
|