@one-source/mcp 4.0.3 → 5.0.0

package/README.md

@@ -1,8 +1,6 @@
 # @one-source/mcp
 
-Unified MCP server for [OneSource](https://docs.onesource.io) — 33 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.
 
@@ -44,7 +42,9 @@ npx -y @one-source/mcp@latest --http --port=8080
 
 Then connect your MCP client to `http://localhost:3000/`.
 
-## Tools (33)
+Health check: `GET http://localhost:3000/health`
+
+## Tools (24)
 
 ### Blockchain API — Live Chain (12 tools)
 
@@ -65,6 +65,8 @@ Then connect your MCP client to `http://localhost:3000/`.
 
 ### Blockchain API — Chain Utilities (10 tools)
 
+RPC only.
+
 | Tool | Description |
 |------|-------------|
 | `1s_contract_code` | Contract bytecode |
@@ -78,23 +80,14 @@ Then connect your MCP client to `http://localhost:3000/`.
 | `1s_storage_read` | Read storage slot |
 | `1s_tx_receipt` | Transaction receipt |
 
-### Documentation & Setup (11 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 |
-| `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 |
+| `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 |
 
 ## Networks
 
@@ -106,27 +99,58 @@ All blockchain API tools accept an optional `network` parameter:
 | `sepolia` | Ethereum Sepolia testnet |
 | `avax` | Avalanche C-Chain |
 
-## Payment (x402)
+## Authentication
 
-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.
+Blockchain API tools require authentication. Two options are available — API key takes priority if both are set.
 
-Documentation tools are always free — no key or payment needed.
+| 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 |
 
-### Setup
+### Option 1: API Key (recommended)
 
-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`.
-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.
+#### Claude Code
 
-### Claude Code
+```bash
+claude mcp add onesource -e ONESOURCE_API_KEY=<key> -- npx -y @one-source/mcp@latest
+```
+
+#### Claude Desktop / Cursor
+
+```json
+{
+  "mcpServers": {
+    "onesource": {
+      "command": "npx",
+      "args": ["-y", "@one-source/mcp@latest"],
+      "env": {
+        "ONESOURCE_API_KEY": "<key>"
+      }
+    }
+  }
+}
+```
+
+#### Any MCP Client (stdio)
 
 ```bash
-claude mcp add onesource -e X402_PRIVATE_KEY=0x... -- npx -y @one-source/mcp@latest
+ONESOURCE_API_KEY=<key> npx -y @one-source/mcp@latest
 ```
 
-### Claude Desktop / Cursor
+### Option 2: x402 Micropayments
+
+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:**
+
+#### Claude Code
+
+```bash
+claude mcp add onesource -e X402_PRIVATE_KEY=0x... -- npx -y @one-source/mcp@latest
+```
 
-Add the `env` block to your MCP config:
+#### Claude Desktop / Cursor
 
 ```json
 {
@@ -142,7 +166,7 @@ Add the `env` block to your MCP config:
 }
 ```
 
-### Any MCP Client (stdio)
+#### Any MCP Client (stdio)
 
 ```bash
 X402_PRIVATE_KEY=0x... npx -y @one-source/mcp@latest
@@ -150,7 +174,36 @@ 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.
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `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"** — 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.
+
+**Windows: `npx` requires `cmd /c` wrapper** — Update your MCP config to use `"command": "cmd"` with `"args": ["/c", "npx", "-y", "@one-source/mcp@latest"]`. Claude Code's `/doctor` command can diagnose this.
+
+**`npx` hangs with no output** — That's normal in stdio mode. Use `--http` for an HTTP server.
+
+**Port already in use** — Specify a different port: `npx -y @one-source/mcp@latest --http --port=8080`
+
+## Links
+
+- [GitHub Repository](https://github.com/blockparty-global/1s-mcp)
+- [OneSource Documentation](https://docs.onesource.io)
+- [Report an Issue](https://github.com/blockparty-global/1s-mcp/issues)
 
 ## License
 

package/README.npm.md

@@ -1,8 +1,6 @@
 # @one-source/mcp
 
-Unified MCP server for [OneSource](https://docs.onesource.io) — 33 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.
 
@@ -44,7 +42,9 @@ npx -y @one-source/mcp@latest --http --port=8080
 
 Then connect your MCP client to `http://localhost:3000/`.
 
-## Tools (33)
+Health check: `GET http://localhost:3000/health`
+
+## Tools (24)
 
 ### Blockchain API — Live Chain (12 tools)
 
@@ -65,6 +65,8 @@ Then connect your MCP client to `http://localhost:3000/`.
 
 ### Blockchain API — Chain Utilities (10 tools)
 
+RPC only.
+
 | Tool | Description |
 |------|-------------|
 | `1s_contract_code` | Contract bytecode |
@@ -78,23 +80,14 @@ Then connect your MCP client to `http://localhost:3000/`.
 | `1s_storage_read` | Read storage slot |
 | `1s_tx_receipt` | Transaction receipt |
 
-### Documentation & Setup (11 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 |
-| `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 |
+| `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 |
 
 ## Networks
 
@@ -106,27 +99,58 @@ All blockchain API tools accept an optional `network` parameter:
 | `sepolia` | Ethereum Sepolia testnet |
 | `avax` | Avalanche C-Chain |
 
-## Payment (x402)
+## Authentication
 
-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.
+Blockchain API tools require authentication. Two options are available — API key takes priority if both are set.
 
-Documentation tools are always free — no key or payment needed.
+| 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 |
 
-### Setup
+### Option 1: API Key (recommended)
 
-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`.
-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.
+#### Claude Code
 
-### Claude Code
+```bash
+claude mcp add onesource -e ONESOURCE_API_KEY=<key> -- npx -y @one-source/mcp@latest
+```
+
+#### Claude Desktop / Cursor
+
+```json
+{
+  "mcpServers": {
+    "onesource": {
+      "command": "npx",
+      "args": ["-y", "@one-source/mcp@latest"],
+      "env": {
+        "ONESOURCE_API_KEY": "<key>"
+      }
+    }
+  }
+}
+```
+
+#### Any MCP Client (stdio)
 
 ```bash
-claude mcp add onesource -e X402_PRIVATE_KEY=0x... -- npx -y @one-source/mcp@latest
+ONESOURCE_API_KEY=<key> npx -y @one-source/mcp@latest
 ```
 
-### Claude Desktop / Cursor
+### Option 2: x402 Micropayments
+
+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:**
+
+#### Claude Code
+
+```bash
+claude mcp add onesource -e X402_PRIVATE_KEY=0x... -- npx -y @one-source/mcp@latest
+```
 
-Add the `env` block to your MCP config:
+#### Claude Desktop / Cursor
 
 ```json
 {
@@ -142,7 +166,7 @@ Add the `env` block to your MCP config:
 }
 ```
 
-### Any MCP Client (stdio)
+#### Any MCP Client (stdio)
 
 ```bash
 X402_PRIVATE_KEY=0x... npx -y @one-source/mcp@latest
@@ -150,7 +174,36 @@ 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.
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `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"** — 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.
+
+**Windows: `npx` requires `cmd /c` wrapper** — Update your MCP config to use `"command": "cmd"` with `"args": ["/c", "npx", "-y", "@one-source/mcp@latest"]`. Claude Code's `/doctor` command can diagnose this.
+
+**`npx` hangs with no output** — That's normal in stdio mode. Use `--http` for an HTTP server.
+
+**Port already in use** — Specify a different port: `npx -y @one-source/mcp@latest --http --port=8080`
+
+## Links
+
+- [GitHub Repository](https://github.com/blockparty-global/1s-mcp)
+- [OneSource Documentation](https://docs.onesource.io)
+- [Report an Issue](https://github.com/blockparty-global/1s-mcp/issues)
 
 ## License