web3agent 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 DeFi Zoo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+# web3agent
+
+> Web3 MCP proxy server — gives AI agents (Claude Code, Cursor, Windsurf, OpenCode) complete Web3 capabilities through a single install.
+
+## Install
+
+```bash
+npx web3agent init
+```
+
+Detects your AI agent host and configures it automatically.
+
+## Usage
+
+```bash
+# Configure your AI agent host
+npx web3agent init
+
+# Start the MCP server (stdio)
+npx web3agent
+
+# Options
+npx web3agent --help
+npx web3agent --version
+```
+
+## What you get
+
+- **Blockscout** — indexed blockchain data (address info, tx history, NFTs, contract ABIs)
+- **EVM MCP** — live on-chain state (balances, contract reads, gas, ENS)
+- **GOAT plugins** — Uniswap, Balancer, ERC-20/721, DexScreener
+- **LI.FI** — cross-chain bridging and swaps
+- **Orbs** — Liquidity Hub aggregated swaps, dTWAP, dLIMIT orders
+- **Wallet management** — generate, persist, derive addresses
+
+## Supported Hosts
+
+| Host | Config Location |
+|------|----------------|
+| Claude Code | `~/.claude/mcp.json` |
+| Cursor | `.cursor/mcp.json` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+| OpenCode | `.opencode/config.json` |
+
+## Supported Chains
+
+Ethereum, Base, Arbitrum, Optimism, Polygon, Linea, BSC, Avalanche, zkSync Era, Scroll, Mode, Blast, Mantle, Celo, Gnosis, Sepolia, Base Sepolia.
+
+Default: **Base (8453)**. Override with `CHAIN_ID` env var or `chainId` parameter per call.
+
+## Environment Variables
+
+See [WEB3_CONTEXT.md](./WEB3_CONTEXT.md) for the full environment variable table.
+
+## Requirements
+
+- Node.js 18+
+- pnpm (for development)
+
+## License
+
+MIT

package/WEB3_CONTEXT.md

@@ -0,0 +1,91 @@
+# Web3Agent — MCP Proxy Context
+
+All Web3 tools are accessible through a single `web3agent` MCP server entry.
+
+## Tool Routing Guide
+
+### Blockscout tools (prefix: `blockscout_`)
+Indexed blockchain data: address info, token balances, transaction history, NFT metadata, contract ABI, contract source code, ENS resolution, block info. Works on 3000+ chains.
+
+Tools: `blockscout_get_address_info`, `blockscout_get_tokens_by_address`, `blockscout_get_transactions_by_address`, `blockscout_get_token_transfers_by_address`, `blockscout_nft_tokens_by_address`, `blockscout_get_block_info`, `blockscout_get_transaction_info`, `blockscout_get_contract_abi`, `blockscout_inspect_contract_code`, `blockscout_read_contract`, `blockscout_get_block_number`, `blockscout_lookup_token_by_symbol`, `blockscout_get_address_by_ens_name`, `blockscout_get_chains_list`, `blockscout_direct_api_call`
+
+### EVM tools (prefix: `evm_`)
+Live on-chain state: current balances, contract reads, gas estimation, ENS resolution, multicall, signing. Writes require a configured wallet.
+
+### Wallet tools (prefix: `wallet_`)
+- `wallet_generate` — generate new wallet (key shown once, never stored)
+- `wallet_generate_mnemonic` — generate BIP-39 mnemonic
+- `wallet_from_mnemonic` — derive address from mnemonic
+- `wallet_derive_addresses` — batch derive 1-20 addresses
+- `wallet_get_active` — get current wallet address, chain, mode
+
+### Transaction management
+- `transaction_confirm(id)` — execute a queued write operation
+- `transaction_deny(id)` — discard a queued operation
+- `transaction_list()` — list pending operations
+
+### DeFi tools
+
+**GOAT plugins** (Uniswap, Balancer, ERC-20, ERC-721, ENS, DexScreener):
+- All accept optional `chainId` parameter (defaults to active chain)
+- Uniswap: chains 1, 137, 43114, 8453, 10, 42161, 42220
+- Balancer: chains 34443, 8453, 137, 100, 42161, 43114, 10
+
+**LI.FI cross-chain bridging** (prefix: `lifi_`):
+- `lifi_get_chains` — list supported chains
+- `lifi_get_quote` — get bridge/swap quote
+- `lifi_execute_bridge` — execute cross-chain bridge (write, confirmation-gated)
+
+**Orbs DeFi** (prefix: `orbs_`):
+- `orbs_get_quote` — Liquidity Hub aggregated swap quote (chains: 137, 56, 8453, 59144, 81457, 42161)
+- `orbs_swap` — execute swap (write, confirmation-gated)
+- `orbs_place_twap` — place dTWAP order (write, confirmation-gated)
+- `orbs_place_limit` — place dLIMIT order (write, confirmation-gated)
+- `orbs_list_orders` — list open TWAP/dLIMIT orders
+
+### Utilities
+- `server_status` — wallet mode, active chain, confirmation setting, backend health
+- `list_supported_chains` — all 17 supported chains with IDs and names
+
+## Chain Selection
+Default chain: **Base (8453)**. Override per-call with `chainId` parameter.
+
+Supported chains:
+| Chain | ID |
+|-------|-----|
+| Ethereum | 1 |
+| Base | 8453 |
+| Arbitrum | 42161 |
+| Optimism | 10 |
+| Polygon | 137 |
+| Linea | 59144 |
+| BSC | 56 |
+| Avalanche | 43114 |
+| zkSync Era | 324 |
+| Scroll | 534352 |
+| Mode | 34443 |
+| Blast | 81457 |
+| Mantle | 5000 |
+| Celo | 42220 |
+| Gnosis | 100 |
+| Sepolia | 11155111 |
+| Base Sepolia | 84532 |
+
+## Confirmation Queue
+Write operations (swaps, bridges, transfers) are queued by default. Use `transaction_confirm(id)` to execute. Disable with `CONFIRM_WRITES=false`.
+
+## Environment Variables
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CHAIN_ID` | 8453 | Default chain (Base) |
+| `PRIVATE_KEY` | — | Wallet private key |
+| `MNEMONIC` | — | BIP-39 mnemonic |
+| `WALLET_ACCOUNT_INDEX` | 0 | HD account index |
+| `WALLET_ADDRESS_INDEX` | 0 | HD address index |
+| `RPC_URL` | — | Custom RPC for default chain |
+| `CONFIRM_WRITES` | true | Require confirmation for writes |
+| `BLOCKSCOUT_MCP_URL` | https://mcp.blockscout.com/mcp | Blockscout MCP endpoint |
+| `ETHERSCAN_API_KEY` | — | Etherscan API key |
+| `LIFI_API_KEY` | — | LI.Fi API key |
+| `ZEROX_API_KEY` | — | 0x API key (enables 0x plugin) |
+| `COINGECKO_API_KEY` | — | CoinGecko API key (enables CoinGecko plugin) |

package/dist/chunk-4GQR4EEY.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+// src/version.ts
+var VERSION = true ? "0.1.0" : "0.0.0-dev";
+
+export {
+  VERSION
+};

package/dist/chunk-BF4PA46E.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+
+// src/chains/registry.ts
+import * as viemChains from "viem/chains";
+var CHAINS_BY_ID = /* @__PURE__ */ new Map();
+var CHAINS_BY_NAME = /* @__PURE__ */ new Map();
+for (const value of Object.values(viemChains)) {
+  if (value && typeof value === "object" && "id" in value && "name" in value) {
+    const chain = value;
+    CHAINS_BY_ID.set(chain.id, chain);
+    CHAINS_BY_NAME.set(chain.name.toLowerCase(), chain);
+  }
+}
+function getChainById(id) {
+  return CHAINS_BY_ID.get(id);
+}
+function isSupported(id) {
+  return CHAINS_BY_ID.has(id);
+}
+
+// src/config/env.ts
+var BLOCKSCOUT_DEFAULT_URL = "https://mcp.blockscout.com/mcp";
+var ETHERSCAN_DEFAULT_URL = "https://mcp.etherscan.io/mcp";
+var ValidationError = class extends Error {
+  field;
+  rawValue;
+  constructor(field, rawValue, message) {
+    super(message);
+    this.name = "ValidationError";
+    this.field = field;
+    this.rawValue = rawValue;
+  }
+};
+var FALSE_VALUES = /* @__PURE__ */ new Set(["false", "0", "no"]);
+function parseBoolean(value, fallback) {
+  if (value === void 0 || value === "") return fallback;
+  return !FALSE_VALUES.has(value.toLowerCase());
+}
+function parseIntStrict(field, value, fallback) {
+  if (value === void 0 || value === "") return fallback;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed)) {
+    throw new ValidationError(field, value, `${field} must be an integer, got "${value}"`);
+  }
+  return parsed;
+}
+var RPC_URL_PREFIX = "RPC_URL_";
+function parseChainRpcUrls(env) {
+  const urls = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (key.startsWith(RPC_URL_PREFIX) && value) {
+      const chainId = Number(key.slice(RPC_URL_PREFIX.length));
+      if (Number.isInteger(chainId) && chainId > 0) {
+        urls[chainId] = value;
+      }
+    }
+  }
+  return urls;
+}
+function parseEnv(env = {}) {
+  const chainId = parseIntStrict("CHAIN_ID", env.CHAIN_ID, 8453);
+  if (!isSupported(chainId)) {
+    throw new ValidationError(
+      "CHAIN_ID",
+      env.CHAIN_ID ?? String(chainId),
+      `Unsupported chain ID: ${chainId}`
+    );
+  }
+  return {
+    chainId,
+    privateKey: env.PRIVATE_KEY || void 0,
+    mnemonic: env.MNEMONIC || void 0,
+    walletAccountIndex: parseIntStrict("WALLET_ACCOUNT_INDEX", env.WALLET_ACCOUNT_INDEX, 0),
+    walletAddressIndex: parseIntStrict("WALLET_ADDRESS_INDEX", env.WALLET_ADDRESS_INDEX, 0),
+    rpcUrl: env.RPC_URL || void 0,
+    chainRpcUrls: parseChainRpcUrls(env),
+    confirmWrites: parseBoolean(env.CONFIRM_WRITES, true),
+    blockscoutMcpUrl: env.BLOCKSCOUT_MCP_URL || BLOCKSCOUT_DEFAULT_URL,
+    etherscanMcpUrl: env.ETHERSCAN_MCP_URL || ETHERSCAN_DEFAULT_URL,
+    etherscanApiKey: env.ETHERSCAN_API_KEY || void 0,
+    lifiApiKey: env.LIFI_API_KEY || void 0,
+    zeroxApiKey: env.ZEROX_API_KEY || void 0,
+    coingeckoApiKey: env.COINGECKO_API_KEY || void 0,
+    orbsPartner: env.ORBS_PARTNER || void 0
+  };
+}
+var cached;
+function setConfig(config) {
+  cached = config;
+}
+function getConfig() {
+  if (!cached) {
+    throw new Error("Config not initialized \u2014 call setConfig() during startup");
+  }
+  return cached;
+}
+
+export {
+  getChainById,
+  isSupported,
+  BLOCKSCOUT_DEFAULT_URL,
+  ETHERSCAN_DEFAULT_URL,
+  ValidationError,
+  parseEnv,
+  setConfig,
+  getConfig
+};

package/dist/index.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import {
+  VERSION
+} from "./chunk-4GQR4EEY.js";
+
+// src/index.ts
+var args = process.argv.slice(2);
+if (args[0] === "init") {
+  import("./init-DKWQSYDZ.js").then(({ runInit }) => {
+    runInit(args.slice(1)).catch((e) => {
+      process.stderr.write(`Error: ${e.message}
+`);
+      process.exit(1);
+    });
+  });
+} else if (args.includes("--version")) {
+  process.stderr.write(`web3agent ${VERSION}
+`);
+  process.exit(0);
+} else if (args.includes("--help")) {
+  process.stderr.write(
+    `${[
+      "web3agent \u2014 Web3 MCP proxy server",
+      "",
+      "Usage:",
+      "  web3agent        Start MCP proxy server (stdio)",
+      "  web3agent init   Configure your AI agent host",
+      "",
+      "Options:",
+      "  --version        Print version",
+      "  --help           Print this help"
+    ].join("\n")}
+`
+  );
+  process.exit(0);
+} else {
+  import("./startup-PHXZQ2SL.js").then(({ startServer }) => {
+    startServer().catch((e) => {
+      process.stderr.write(`Fatal: ${e.message}
+`);
+      process.exit(1);
+    });
+  });
+}