From 3f47faf9922e58b06513368fc0d591b3a2dd05d7 Mon Sep 17 00:00:00 2001 From: Alex Cheng Date: Thu, 13 Feb 2025 10:20:38 -0600 Subject: [PATCH] UTXO queries support by xchainjs --- README.md | 69 ++++++++-- package.json | 5 + src/chains/xchain.ts | 319 ++++++++++++++++++++++++++----------------- src/index.ts | 4 +- 4 files changed, 252 insertions(+), 145 deletions(-) diff --git a/README.md b/README.md index 4f7a990..fbb06ce 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Web3 MCP -A Model-Context-Protocol server for interacting with multiple blockchains including Solana and Ethereum. This server provides simple RPC endpoints for common blockchain operations, allowing secure interactions with various blockchains through environment variables. +A Model-Context-Protocol server for interacting with multiple blockchains including Solana, Ethereum, and UTXO chains. This server provides simple RPC endpoints for common blockchain operations, allowing secure interactions with various blockchains through environment variables. ## Features @@ -19,6 +19,28 @@ Ethereum & EVM Chain Operations: - Send ERC-20 tokens (using private key from .env) - Approve ERC-20 token spending (using private key from .env) +UTXO Chain Operations: +- Bitcoin (BTC) + - Check address balances + - View transaction history + - Validate addresses + - Get network info and fees +- Litecoin (LTC) + - Check address balances + - View transaction history + - Validate addresses + - Get network info and fees +- Dogecoin (DOGE) + - Check address balances + - View transaction history + - Validate addresses + - Get network info and fees +- Bitcoin Cash (BCH) + - Check address balances + - View transaction history + - Validate addresses + - Get network info and fees + Supported EVM Networks: - Ethereum - Base @@ -31,19 +53,19 @@ Supported EVM Networks: ## Setup 1. Clone and install dependencies: -```bash +\`\`\`bash git clone https://github.com/strangelove-ventures/web3-mcp.git cd web3-mcp npm install -``` +\`\`\` 2. Create a .env file in the root directory: -```bash +\`\`\`bash cp .env.example .env -``` +\`\`\` 3. Configure your environment variables in .env: -```env +\`\`\`env # Network RPC URLs (optional - will use public endpoints if not specified) SOLANA_RPC_URL=https://api.mainnet-beta.solana.com ETH_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/your-api-key @@ -57,15 +79,19 @@ AVALANCHE_RPC_URL=https://api.avax.network/ext/bc/C/rpc # Private keys (required for transactions) ETH_PRIVATE_KEY=your-ethereum-private-key SOLANA_PRIVATE_KEY=your-base58-encoded-solana-private-key -``` + +# Optional API keys for UTXO chain data providers +BLOCKCYPHER_API_KEY=your-blockcypher-api-key +SOCHAIN_API_KEY=your-sochain-api-key +\`\`\` 4. Build the tool: -```bash +\`\`\`bash npm run build -``` +\`\`\` 5. Add the tool to your claude_desktop_config.json: -```json +\`\`\`json { "web3-rpc": { "command": "node", @@ -74,7 +100,7 @@ npm run build ] } } -``` +\`\`\` ## Usage Examples @@ -94,6 +120,13 @@ Ask Claude: - "What's the current gas price on Arbitrum?" - "Send 100 USDC to 0x556437c4d22ceaeeebf82006b85bdcc0ae67d933 on Polygon" +### UTXO Chain Operations +- "What's the BTC balance of 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa?" +- "Show me the transaction history for bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh" +- "Is ltc1qgj73yjsc4tm5kgv2zgf9zqt74pac4peugvxhuy a valid Litecoin address?" +- "What are the current network fees for Bitcoin Cash?" +- "Check DOGE balance for D6T2SsXPQPqFBcYzX3EXJvYG1F8BsNAk4z" + ## Security Notes 1. **Environment Variables**: All private keys are stored in the .env file and never exposed in the conversation history @@ -109,13 +142,21 @@ You can configure custom RPC endpoints in your .env file for better reliability ### Network Selection For EVM operations, you can specify the network by name (ethereum, base, arbitrum, optimism, bsc, polygon, avalanche). The tool will automatically use the appropriate RPC endpoint and network configuration. +### UTXO Chain Data Providers +The tool uses several data providers for UTXO chains: +- BlockCypher +- SoChain +- Haskoin (for Bitcoin Cash) + +You can configure API keys for these providers in the .env file for better rate limits. + ## Development To modify or extend the tool: -1. Source code is in the `src` directory -2. Chain-specific code in `src/chains` -3. Run `npm run build` after making changes +1. Source code is in the \`src\` directory +2. Chain-specific code in \`src/chains\` +3. Run \`npm run build\` after making changes 4. Use TypeScript for all new code ## Contributing diff --git a/package.json b/package.json index 5da0617..9e5c476 100644 --- a/package.json +++ b/package.json @@ -47,9 +47,14 @@ }, "dependencies": { "@xchainjs/xchain-bitcoin": "^1.2.2", + "@xchainjs/xchain-bitcoincash": "^1.0.10", "@xchainjs/xchain-client": "^0.16.2", "@xchainjs/xchain-crypto": "^0.3.7", + "@xchainjs/xchain-doge": "^1.0.10", + "@xchainjs/xchain-litecoin": "^1.0.10", "@xchainjs/xchain-util": "^0.13.1", + "@psf/bitcoincashjs-lib": "^4.0.3", + "bchaddrjs": "^0.5.2", "bitcoinjs-lib": "^6.1.5", "wif": "^4.0.0", "@jup-ag/api": "^6.0.12", diff --git a/src/chains/xchain.ts b/src/chains/xchain.ts index 4ba4718..d2000a4 100644 --- a/src/chains/xchain.ts +++ b/src/chains/xchain.ts @@ -1,4 +1,7 @@ -import { Client as BitcoinClient, defaultBTCParams, BlockcypherDataProviders } from '@xchainjs/xchain-bitcoin' +import { Client as BitcoinClient, defaultBTCParams, BlockcypherDataProviders as BTCBlockcypherDataProviders } from '@xchainjs/xchain-bitcoin' +import { Client as LitecoinClient, defaultLtcParams } from '@xchainjs/xchain-litecoin' +import { Client as DogeClient, defaultDogeParams } from '@xchainjs/xchain-doge' +import { Client as BitcoinCashClient, defaultBchParams } from '@xchainjs/xchain-bitcoincash' import { Network } from '@xchainjs/xchain-client' import { Asset } from '@xchainjs/xchain-util' import { z } from "zod" @@ -6,21 +9,35 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js" import { config } from 'dotenv' config() -const BTC_ASSET: Asset = { - chain: 'BTC', - symbol: 'BTC', - ticker: 'BTC', - synth: false -} - -// Initialize Bitcoin client with mainnet by default +// Initialize clients with mainnet by default const bitcoinClient = new BitcoinClient({ ...defaultBTCParams, network: Network.Mainnet, - dataProviders: [BlockcypherDataProviders], + dataProviders: [BTCBlockcypherDataProviders], }) -export function registerBitcoinTools(server: McpServer) { +const litecoinClient = new LitecoinClient({ + ...defaultLtcParams, + network: Network.Mainnet, +}) + +const dogeClient = new DogeClient({ + ...defaultDogeParams, + network: Network.Mainnet, +}) + +const bitcoinCashClient = new BitcoinCashClient({ + ...defaultBchParams, + network: Network.Mainnet, +}) + +// Helper function to format base amounts for all UTXO chains +function formatBaseAmount(baseAmount: any): string { + return baseAmount.amount().toString() +} + +export function registerUtxoTools(server: McpServer) { + // Bitcoin Tools server.tool( "getBitcoinBalance", "Get balance for a Bitcoin address", @@ -34,179 +51,223 @@ export function registerBitcoinTools(server: McpServer) { content: [ { type: "text", - text: `Bitcoin Balance for ${address}:\n${balances[0].amount.amount().toString()} BTC`, + text: `Bitcoin Balance for ${address}:\n${formatBaseAmount(balances[0].amount)} BTC`, }, ], } } catch (err) { const error = err as Error return { - content: [ - { - type: "text", - text: `Failed to retrieve balance: ${error.message}`, - }, - ], + content: [{ type: "text", text: `Failed to retrieve BTC balance: ${error.message}` }], } } } ) + // Litecoin Tools server.tool( - "validateBitcoinAddress", - "Validate a Bitcoin address format", + "getLitecoinBalance", + "Get balance for a Litecoin address", { - address: z.string().describe("Bitcoin address to validate"), + address: z.string().describe("Litecoin address to check"), }, async ({ address }) => { try { - const isValid = bitcoinClient.validateAddress(address) + const balances = await litecoinClient.getBalance(address) return { content: [ { type: "text", - text: isValid - ? `The address ${address} is a valid Bitcoin address` - : `The address ${address} is NOT a valid Bitcoin address`, + text: `Litecoin Balance for ${address}:\n${formatBaseAmount(balances[0].amount)} LTC`, }, ], } } catch (err) { const error = err as Error return { - content: [ - { - type: "text", - text: `Error validating address: ${error.message}`, - }, - ], + content: [{ type: "text", text: `Failed to retrieve LTC balance: ${error.message}` }], } } } ) + // Dogecoin Tools server.tool( - "getBitcoinTransactionData", - "Get transaction details for a Bitcoin transaction", + "getDogeBalance", + "Get balance for a Dogecoin address", { - txId: z.string().describe("Bitcoin transaction ID/hash"), + address: z.string().describe("Dogecoin address to check"), }, - async ({ txId }) => { + async ({ address }) => { try { - const txData = await bitcoinClient.getTransactionData(txId) + const balances = await dogeClient.getBalance(address) + return { + content: [ + { + type: "text", + text: `Dogecoin Balance for ${address}:\n${formatBaseAmount(balances[0].amount)} DOGE`, + }, + ], + } + } catch (err) { + const error = err as Error + return { + content: [{ type: "text", text: `Failed to retrieve DOGE balance: ${error.message}` }], + } + } + } + ) + + // Bitcoin Cash Tools + server.tool( + "getBitcoinCashBalance", + "Get balance for a Bitcoin Cash address", + { + address: z.string().describe("Bitcoin Cash address to check"), + }, + async ({ address }) => { + try { + const balances = await bitcoinCashClient.getBalance(address) + return { + content: [ + { + type: "text", + text: `Bitcoin Cash Balance for ${address}:\n${formatBaseAmount(balances[0].amount)} BCH`, + }, + ], + } + } catch (err) { + const error = err as Error + return { + content: [{ type: "text", text: `Failed to retrieve BCH balance: ${error.message}` }], + } + } + } + ) + + // Common Tools for all UTXO chains + // Transaction History + const getTransactionHistory = async (client: any, address: string, chain: string, limit = 10, offset = 0) => { + try { + const txs = await client.getTransactions({ address, limit, offset }) + const txList = txs.txs.map((tx: any) => { + const fromAmount = tx.from[0]?.amount ? `${formatBaseAmount(tx.from[0].amount)} ${chain}` : 'Unknown' + const toAmount = tx.to[0]?.amount ? `${formatBaseAmount(tx.to[0].amount)} ${chain}` : 'Unknown' - // Format amounts if available using amount.amount() - const fromAmount = txData.from[0]?.amount ? `${txData.from[0].amount.amount().toString()} BTC` : 'Unknown' - const toAmount = txData.to[0]?.amount ? `${txData.to[0].amount.amount().toString()} BTC` : 'Unknown' - - return { - content: [ - { - type: "text", - text: `Transaction Details for ${txId}: -Hash: ${txData.hash} -From: ${txData.from[0]?.from || 'Unknown'} (${fromAmount}) -To: ${txData.to[0]?.to || 'Unknown'} (${toAmount}) -Asset: ${txData.asset.ticker} -Type: ${txData.type}`, - }, - ], - } - } catch (err) { - const error = err as Error - return { - content: [ - { - type: "text", - text: `Failed to retrieve transaction data: ${error.message}`, - }, - ], - } - } - } - ) - - server.tool( - "getBitcoinTransactionHistory", - "Get transaction history for a Bitcoin address", - { - address: z.string().describe("Bitcoin address to check"), - limit: z.number().optional().describe("Maximum number of transactions to return"), - offset: z.number().optional().describe("Number of transactions to skip"), - }, - async ({ address, limit = 10, offset = 0 }) => { - try { - const txs = await bitcoinClient.getTransactions({ - address, - limit, - offset - }) - - const txList = txs.txs.map(tx => { - const fromAmount = tx.from[0]?.amount ? `${tx.from[0].amount.amount().toString()} BTC` : 'Unknown' - const toAmount = tx.to[0]?.amount ? `${tx.to[0].amount.amount().toString()} BTC` : 'Unknown' - - return ` + return ` Transaction: ${tx.hash} Type: ${tx.type} From: ${tx.from[0]?.from || 'Unknown'} (${fromAmount}) To: ${tx.to[0]?.to || 'Unknown'} (${toAmount}) Asset: ${tx.asset.ticker} Date: ${new Date(tx.date).toLocaleString()}` - }).join('\n---\n') + }).join('\n---\n') + return { success: true, content: txList } + } catch (err) { + const error = err as Error + return { success: false, error: error.message } + } + } + + // Register history tools for each chain + const chains = [ + { name: 'Bitcoin', symbol: 'BTC', client: bitcoinClient }, + { name: 'Litecoin', symbol: 'LTC', client: litecoinClient }, + { name: 'Dogecoin', symbol: 'DOGE', client: dogeClient }, + { name: 'Bitcoin Cash', symbol: 'BCH', client: bitcoinCashClient }, + ] + + chains.forEach(({ name, symbol, client }) => { + server.tool( + `get${symbol}TransactionHistory`, + `Get transaction history for a ${name} address`, + { + address: z.string().describe(`${name} address to check`), + limit: z.number().optional().describe("Maximum number of transactions to return"), + offset: z.number().optional().describe("Number of transactions to skip"), + }, + async ({ address, limit = 10, offset = 0 }) => { + const result = await getTransactionHistory(client, address, symbol, limit, offset) return { content: [ { type: "text", - text: `Transaction History for ${address}:\n${txList}`, - }, - ], - } - } catch (err) { - const error = err as Error - return { - content: [ - { - type: "text", - text: `Failed to retrieve transaction history: ${error.message}`, + text: result.success + ? `${name} Transaction History for ${address}:\n${result.content}` + : `Failed to retrieve ${name} transaction history: ${result.error}`, }, ], } } - } - ) + ) - server.tool( - "getBitcoinNetworkInfo", - "Get current Bitcoin network information", - {}, - async () => { - try { - const fees = await bitcoinClient.getFeeRates() - return { - content: [ - { - type: "text", - text: `Bitcoin Network Information: -Current Network: ${bitcoinClient.getNetwork()} + // Add address validation + server.tool( + `validate${symbol}Address`, + `Validate a ${name} address format`, + { + address: z.string().describe(`${name} address to validate`), + }, + async ({ address }) => { + try { + const isValid = client.validateAddress(address) + return { + content: [ + { + type: "text", + text: isValid + ? `The address ${address} is a valid ${name} address` + : `The address ${address} is NOT a valid ${name} address`, + }, + ], + } + } catch (err) { + const error = err as Error + return { + content: [ + { + type: "text", + text: `Error validating ${name} address: ${error.message}`, + }, + ], + } + } + } + ) + + // Add network info + server.tool( + `get${symbol}NetworkInfo`, + `Get current ${name} network information`, + {}, + async () => { + try { + const fees = await client.getFeeRates() + return { + content: [ + { + type: "text", + text: `${name} Network Information: +Current Network: ${client.getNetwork()} Fee Rates (sats/byte): Fast: ${fees.fast} Average: ${fees.average}`, - }, - ], - } - } catch (err) { - const error = err as Error - return { - content: [ - { - type: "text", - text: `Failed to retrieve network information: ${error.message}`, - }, - ], + }, + ], + } + } catch (err) { + const error = err as Error + return { + content: [ + { + type: "text", + text: `Failed to retrieve ${name} network information: ${error.message}`, + }, + ], + } } } - } - ) + ) + }) } diff --git a/src/index.ts b/src/index.ts index 87f3a16..66a3c0c 100644 --- a/src/index.ts +++ b/src/index.ts @@ -24,7 +24,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { registerSolanaTools } from "./chains/solana.js"; import { registerEthereumTools } from "./chains/ethereum.js"; -import { registerBitcoinTools } from "./chains/xchain.js"; +import { registerUtxoTools } from "./chains/xchain.js"; // Create server instance const server = new McpServer({ @@ -35,7 +35,7 @@ const server = new McpServer({ // Register chain-specific tools registerSolanaTools(server); registerEthereumTools(server); -registerBitcoinTools(server); +registerUtxoTools(server); async function main() { const transport = new StdioServerTransport();