@one-source/mcp 4.0.4 → 5.0.0

package/README.md

@@ -1,8 +1,6 @@
 # @one-source/mcp
 
-Unified MCP server for [OneSource](https://docs.onesource.io) — 34 tools for blockchain data, live chain queries, and API documentation in a single server.
-
-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) (11 tools) so your AI assistant gets full access to OneSource with one MCP connection.
+Unified MCP server for [OneSource](https://docs.onesource.io) — 24 tools for blockchain data and live chain queries in a single server.
 
 > **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.
 
@@ -46,7 +44,7 @@ Then connect your MCP client to `http://localhost:3000/`.
 
 Health check: `GET http://localhost:3000/health`
 
-## Tools (34)
+## Tools (24)
 
 ### Blockchain API — Live Chain (12 tools)
 
@@ -82,24 +80,14 @@ RPC only.
 | `1s_storage_read` | Read storage slot |
 | `1s_tx_receipt` | Transaction receipt |
 
-### Documentation, Setup & Ops (12 tools)
+### Setup & Ops (2 tools)
 
-Read-only, no API key required.
+No authentication required.
 
 | Tool | Purpose | When to use |
 |------|---------|-------------|
-| `1s_setup_check` | Server health, version, x402 status, setup instructions | First thing to call — checks if everything is configured |
+| `1s_setup_check` | Server health, version, auth status, setup instructions | First thing to call — checks if everything is configured |
 | `1s_report_bug` | Report bugs to Slack (or GitHub Issues fallback) | When a tool errors or user wants to report an issue |
-| `search_docs` | Keyword search across all documentation | Finding guides, concepts, or API patterns |
-| `get_query_reference` | Full reference for a root GraphQL query | Building a specific query with correct args/filters |
-| `get_type_definition` | Schema definition for any type/enum/input | Understanding field shapes and return types |
-| `list_examples` | Browse or search working GraphQL examples | Finding ready-to-use query patterns |
-| `list_supported_chains` | All supported blockchain networks + endpoints | First question: "What chains are supported?" |
-| `get_filter_reference` | Filter fields and operators for a list query | Building filtered queries with correct syntax |
-| `get_pagination_guide` | Cursor-based pagination pattern with examples | Implementing pagination for list queries |
-| `get_schema_overview` | High-level summary of the entire schema | Exploring the API surface before diving in |
-| `get_authentication_guide` | API key format, headers, and endpoints | Setting up authentication for the first time |
-| `get_mcp_setup_guide` | MCP installation, setup, x402 config guide | Setting up the MCP server or configuring payments |
 
 ## Networks
 
@@ -111,27 +99,24 @@ All blockchain API tools accept an optional `network` parameter:
 | `sepolia` | Ethereum Sepolia testnet |
 | `avax` | Avalanche C-Chain |
 
-## Payment (x402)
-
-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.
+## Authentication
 
-Documentation tools are always free — no key or payment needed.
+Blockchain API tools require authentication. Two options are available — API key takes priority if both are set.
 
-### Setup
+| Method | Variable | Description |
+|--------|----------|-------------|
+| API key | `ONESOURCE_API_KEY` | Unlimited calls, no per-call cost |
+| x402 micropayments | `X402_PRIVATE_KEY` | Pay-per-call via USDC on Base |
 
-1. **Get an EVM private key** — export one from MetaMask, Coinbase Wallet, or any EVM wallet. The key must start with `0x` followed by 64 hex characters (e.g. `0x4c08...7e3d`). Some wallets export the key without the `0x` prefix — if yours is just letters and numbers without `0x` at the start, add `0x` to the beginning yourself.
-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.
-3. **Pass the key to the server** using one of the methods below.
+### Option 1: API Key (recommended)
 
-### Claude Code
+#### Claude Code
 
 ```bash
-claude mcp add onesource -e X402_PRIVATE_KEY=0x... -- npx -y @one-source/mcp@latest
+claude mcp add onesource -e ONESOURCE_API_KEY=<key> -- npx -y @one-source/mcp@latest
 ```
 
-### Claude Desktop / Cursor
-
-Add the `env` block to your MCP config:
+#### Claude Desktop / Cursor
 
 ```json
 {
@@ -140,40 +125,56 @@ Add the `env` block to your MCP config:
       "command": "npx",
       "args": ["-y", "@one-source/mcp@latest"],
       "env": {
-        "X402_PRIVATE_KEY": "0x..."
+        "ONESOURCE_API_KEY": "<key>"
       }
     }
   }
 }
 ```
 
-### Any MCP Client (stdio)
+#### Any MCP Client (stdio)
 
 ```bash
-X402_PRIVATE_KEY=0x... npx -y @one-source/mcp@latest
+ONESOURCE_API_KEY=<key> npx -y @one-source/mcp@latest
 ```
 
-### Config File Locations
+### Option 2: x402 Micropayments
 
-If you prefer editing the config file directly instead of using CLI commands:
+1. **Get an EVM private key** — export from MetaMask, Coinbase Wallet, or generate one. The key is a 64-character hex string. The `0x` prefix is optional — both formats are accepted.
+2. **Fund the wallet with USDC on Base** — bridge or transfer USDC to the derived wallet address on [Base](https://base.org).
+3. **Pass the key to the server:**
 
-| Client | Config file path |
-|--------|-----------------|
-| Claude Code | Run `claude mcp get onesource` to see the file path |
-| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
-| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
-| Cursor (macOS) | `~/.cursor/mcp.json` |
-| Cursor (Windows) | `%USERPROFILE%\.cursor\mcp.json` |
+#### Claude Code
 
-Add the `onesource` entry inside `"mcpServers"` using the JSON block shown above.
+```bash
+claude mcp add onesource -e X402_PRIVATE_KEY=0x... -- npx -y @one-source/mcp@latest
+```
+
+#### Claude Desktop / Cursor
+
+```json
+{
+  "mcpServers": {
+    "onesource": {
+      "command": "npx",
+      "args": ["-y", "@one-source/mcp@latest"],
+      "env": {
+        "X402_PRIVATE_KEY": "0x..."
+      }
+    }
+  }
+}
+```
 
-### Alternative: Set as an Environment Variable
+#### Any MCP Client (stdio)
 
-Instead of the `env` config block, you can set `X402_PRIVATE_KEY` as a shell or system environment variable: `export X402_PRIVATE_KEY=0x...` (bash/zsh) or `$env:X402_PRIVATE_KEY = "0x..."` (PowerShell). Set it at the OS level for persistence across sessions.
+```bash
+X402_PRIVATE_KEY=0x... npx -y @one-source/mcp@latest
+```
 
 ### Security
 
-Never commit your private key to source control. Use environment variables, a `.env` file (excluded from git), or a secrets manager.
+Never commit keys to source control. Use environment variables, a `.env` file (excluded from git), or a secrets manager.
 
 > **After any config change:** Run `/reload-plugins` in Claude Code, or restart Claude Desktop / Cursor. The MCP server must be reloaded to pick up new environment variables.
 
@@ -181,13 +182,14 @@ Never commit your private key to source control. Use environment variables, a `.
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `X402_PRIVATE_KEY` | — | EVM private key (hex, 0x-prefixed) for automatic x402 USDC payments on Base |
+| `ONESOURCE_API_KEY` | — | OneSource API key for Bearer token auth. Takes priority over x402. |
+| `X402_PRIVATE_KEY` | — | EVM private key (64-char hex, `0x` prefix optional) for automatic x402 USDC payments on Base |
 | `ONESOURCE_BASE_URL` | `https://skills.onesource.io` | API base URL |
 | `ONESOURCE_ANALYTICS` | — | Set to `false` to disable analytics |
 
 ## Troubleshooting
 
-**`1s_setup_check` shows "Not configured"** — Reload the MCP server first (see note above). If the key still isn't reaching the server after reloading, set it as an environment variable directly.
+**`1s_setup_check` shows "Not configured"** — Set either `ONESOURCE_API_KEY` or `X402_PRIVATE_KEY`. Reload the MCP server after setting either variable. If the key still isn't reaching the server, set it as a shell environment variable directly.
 
 **"MCP server onesource already exists" error** — Run `claude mcp remove onesource` first, then re-add.
 

package/README.npm.md

@@ -1,8 +1,6 @@
 # @one-source/mcp
 
-Unified MCP server for [OneSource](https://docs.onesource.io) — 34 tools for blockchain data, live chain queries, and API documentation in a single server.
-
-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) (11 tools) so your AI assistant gets full access to OneSource with one MCP connection.
+Unified MCP server for [OneSource](https://docs.onesource.io) — 24 tools for blockchain data and live chain queries in a single server.
 
 > **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.
 
@@ -46,7 +44,7 @@ Then connect your MCP client to `http://localhost:3000/`.
 
 Health check: `GET http://localhost:3000/health`
 
-## Tools (34)
+## Tools (24)
 
 ### Blockchain API — Live Chain (12 tools)
 
@@ -82,24 +80,14 @@ RPC only.
 | `1s_storage_read` | Read storage slot |
 | `1s_tx_receipt` | Transaction receipt |
 
-### Documentation, Setup & Ops (12 tools)
+### Setup & Ops (2 tools)
 
-Read-only, no API key required.
+No authentication required.
 
 | Tool | Purpose | When to use |
 |------|---------|-------------|
-| `1s_setup_check` | Server health, version, x402 status, setup instructions | First thing to call — checks if everything is configured |
+| `1s_setup_check` | Server health, version, auth status, setup instructions | First thing to call — checks if everything is configured |
 | `1s_report_bug` | Report bugs to Slack (or GitHub Issues fallback) | When a tool errors or user wants to report an issue |
-| `search_docs` | Keyword search across all documentation | Finding guides, concepts, or API patterns |
-| `get_query_reference` | Full reference for a root GraphQL query | Building a specific query with correct args/filters |
-| `get_type_definition` | Schema definition for any type/enum/input | Understanding field shapes and return types |
-| `list_examples` | Browse or search working GraphQL examples | Finding ready-to-use query patterns |
-| `list_supported_chains` | All supported blockchain networks + endpoints | First question: "What chains are supported?" |
-| `get_filter_reference` | Filter fields and operators for a list query | Building filtered queries with correct syntax |
-| `get_pagination_guide` | Cursor-based pagination pattern with examples | Implementing pagination for list queries |
-| `get_schema_overview` | High-level summary of the entire schema | Exploring the API surface before diving in |
-| `get_authentication_guide` | API key format, headers, and endpoints | Setting up authentication for the first time |
-| `get_mcp_setup_guide` | MCP installation, setup, x402 config guide | Setting up the MCP server or configuring payments |
 
 ## Networks
 
@@ -111,27 +99,24 @@ All blockchain API tools accept an optional `network` parameter:
 | `sepolia` | Ethereum Sepolia testnet |
 | `avax` | Avalanche C-Chain |
 
-## Payment (x402)
-
-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.
+## Authentication
 
-Documentation tools are always free — no key or payment needed.
+Blockchain API tools require authentication. Two options are available — API key takes priority if both are set.
 
-### Setup
+| Method | Variable | Description |
+|--------|----------|-------------|
+| API key | `ONESOURCE_API_KEY` | Unlimited calls, no per-call cost |
+| x402 micropayments | `X402_PRIVATE_KEY` | Pay-per-call via USDC on Base |
 
-1. **Get an EVM private key** — export one from MetaMask, Coinbase Wallet, or any EVM wallet. The key must start with `0x` followed by 64 hex characters (e.g. `0x4c08...7e3d`). Some wallets export the key without the `0x` prefix — if yours is just letters and numbers without `0x` at the start, add `0x` to the beginning yourself.
-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.
-3. **Pass the key to the server** using one of the methods below.
+### Option 1: API Key (recommended)
 
-### Claude Code
+#### Claude Code
 
 ```bash
-claude mcp add onesource -e X402_PRIVATE_KEY=0x... -- npx -y @one-source/mcp@latest
+claude mcp add onesource -e ONESOURCE_API_KEY=<key> -- npx -y @one-source/mcp@latest
 ```
 
-### Claude Desktop / Cursor
-
-Add the `env` block to your MCP config:
+#### Claude Desktop / Cursor
 
 ```json
 {
@@ -140,40 +125,56 @@ Add the `env` block to your MCP config:
       "command": "npx",
       "args": ["-y", "@one-source/mcp@latest"],
       "env": {
-        "X402_PRIVATE_KEY": "0x..."
+        "ONESOURCE_API_KEY": "<key>"
       }
     }
   }
 }
 ```
 
-### Any MCP Client (stdio)
+#### Any MCP Client (stdio)
 
 ```bash
-X402_PRIVATE_KEY=0x... npx -y @one-source/mcp@latest
+ONESOURCE_API_KEY=<key> npx -y @one-source/mcp@latest
 ```
 
-### Config File Locations
+### Option 2: x402 Micropayments
 
-If you prefer editing the config file directly instead of using CLI commands:
+1. **Get an EVM private key** — export from MetaMask, Coinbase Wallet, or generate one. The key is a 64-character hex string. The `0x` prefix is optional — both formats are accepted.
+2. **Fund the wallet with USDC on Base** — bridge or transfer USDC to the derived wallet address on [Base](https://base.org).
+3. **Pass the key to the server:**
 
-| Client | Config file path |
-|--------|-----------------|
-| Claude Code | Run `claude mcp get onesource` to see the file path |
-| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
-| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
-| Cursor (macOS) | `~/.cursor/mcp.json` |
-| Cursor (Windows) | `%USERPROFILE%\.cursor\mcp.json` |
+#### Claude Code
 
-Add the `onesource` entry inside `"mcpServers"` using the JSON block shown above.
+```bash
+claude mcp add onesource -e X402_PRIVATE_KEY=0x... -- npx -y @one-source/mcp@latest
+```
+
+#### Claude Desktop / Cursor
+
+```json
+{
+  "mcpServers": {
+    "onesource": {
+      "command": "npx",
+      "args": ["-y", "@one-source/mcp@latest"],
+      "env": {
+        "X402_PRIVATE_KEY": "0x..."
+      }
+    }
+  }
+}
+```
 
-### Alternative: Set as an Environment Variable
+#### Any MCP Client (stdio)
 
-Instead of the `env` config block, you can set `X402_PRIVATE_KEY` as a shell or system environment variable: `export X402_PRIVATE_KEY=0x...` (bash/zsh) or `$env:X402_PRIVATE_KEY = "0x..."` (PowerShell). Set it at the OS level for persistence across sessions.
+```bash
+X402_PRIVATE_KEY=0x... npx -y @one-source/mcp@latest
+```
 
 ### Security
 
-Never commit your private key to source control. Use environment variables, a `.env` file (excluded from git), or a secrets manager.
+Never commit keys to source control. Use environment variables, a `.env` file (excluded from git), or a secrets manager.
 
 > **After any config change:** Run `/reload-plugins` in Claude Code, or restart Claude Desktop / Cursor. The MCP server must be reloaded to pick up new environment variables.
 
@@ -181,13 +182,14 @@ Never commit your private key to source control. Use environment variables, a `.
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `X402_PRIVATE_KEY` | — | EVM private key (hex, 0x-prefixed) for automatic x402 USDC payments on Base |
+| `ONESOURCE_API_KEY` | — | OneSource API key for Bearer token auth. Takes priority over x402. |
+| `X402_PRIVATE_KEY` | — | EVM private key (64-char hex, `0x` prefix optional) for automatic x402 USDC payments on Base |
 | `ONESOURCE_BASE_URL` | `https://skills.onesource.io` | API base URL |
 | `ONESOURCE_ANALYTICS` | — | Set to `false` to disable analytics |
 
 ## Troubleshooting
 
-**`1s_setup_check` shows "Not configured"** — Reload the MCP server first (see note above). If the key still isn't reaching the server after reloading, set it as an environment variable directly.
+**`1s_setup_check` shows "Not configured"** — Set either `ONESOURCE_API_KEY` or `X402_PRIVATE_KEY`. Reload the MCP server after setting either variable. If the key still isn't reaching the server, set it as a shell environment variable directly.
 
 **"MCP server onesource already exists" error** — Run `claude mcp remove onesource` first, then re-add.