bsv-mcp 0.0.8 → 0.0.10

package/README.md

@@ -138,45 +138,46 @@ The toolkit is organized into several categories:
 
 Wallet tools provide core BSV wallet functionality:
 
-| Tool Name | Description |
-|-----------|-------------|
-| `wallet_getPublicKey` | Retrieves a public key for a specified protocol and key ID |
-| `wallet_createSignature` | Creates a cryptographic signature for the provided data |
-| `wallet_verifySignature` | Verifies a cryptographic signature against the provided data |
-| `wallet_encryption` | Combined tool for encrypting and decrypting data using the wallet's cryptographic keys (replaces separate encrypt/decrypt tools) |
-| `wallet_getAddress` | Returns a BSV address for the current wallet or a derived path |
-| `wallet_sendToAddress` | Sends BSV to a specified address (supports BSV or USD amounts) |
-| `wallet_purchaseListing` | Purchases NFTs or BSV-20/BSV-21 tokens from marketplace listings |
-| `wallet_createOrdinals` | Creates and inscribes ordinals on the BSV blockchain |
+| Tool Name | Description | Example Output |
+|-----------|-------------|----------------|
+| `wallet_getPublicKey` | Retrieves a public key for a specified protocol and key ID | `{"publicKey":"032d0c73eb9270e9e009fd1f9dd77e19cf764fbad5f799560c4e8fd414e40d6fc2"}` |
+| `wallet_createSignature` | Creates a cryptographic signature for the provided data | `{"signature":[144,124,85,193,226,45,140,249,9,177,11,167,33,215,209,38,...]}` |
+| `wallet_verifySignature` | Verifies a cryptographic signature against the provided data | `{"isValid":true}` |
+| `wallet_encryption` | Combined tool for encrypting and decrypting data using the wallet's cryptographic keys (replaces separate encrypt/decrypt tools) | Encrypt: `{"ciphertext":[89,32,155,38,125,22,49,226,26,...]}` <br> Decrypt: `{"plaintext":[104,101,108,108,111,32,119,111,114,108,100]}` |
+| `wallet_getAddress` | Returns a BSV address for the current wallet or a derived path | `{"address":"1ExampleBsvAddressXXXXXXXXXXXXXXXXX","status":"ok"}` |
+| `wallet_sendToAddress` | Sends BSV to a specified address (supports BSV or USD amounts) | `{"status":"success","txid":"a1b2c3d4e5f6...","satoshis":1000000}` |
+| `wallet_purchaseListing` | Purchases NFTs or BSV-20/BSV-21 tokens from marketplace listings | `{"status":"success","txid":"a1b2c3d4e5f6...","type":"nft","origin":"abcdef123456..."}` |
+| `wallet_createOrdinals` | Creates and inscribes ordinals on the BSV blockchain | `{"txid":"a1b2c3d4e5f6...","inscriptionAddress":"1ExampleAddress...","contentType":"image/png"}` |
 
 ### BSV Tools
 
 Tools for interacting with the BSV blockchain and network:
 
-| Tool Name | Description |
-|-----------|-------------|
-| `bsv_getPrice` | Gets the current BSV price from an exchange API |
-| `bsv_decodeTransaction` | Decodes a BSV transaction and returns detailed information |
+| Tool Name | Description | Example Output |
+|-----------|-------------|----------------|
+| `bsv_getPrice` | Gets the current BSV price from an exchange API | `Current BSV price: $38.75 USD` |
+| `bsv_decodeTransaction` | Decodes a BSV transaction and returns detailed information | `{"txid":"a1b2c3d4e5f6...","version":1,"locktime":0,"size":225,"inputs":[...],"outputs":[...]}` |
+| `bsv_explore` | Comprehensive blockchain explorer tool accessing WhatsOnChain API endpoints | `{"chain_info":{"chain":"main","blocks":826458,"headers":826458,"bestblockhash":"0000000000..."}}` |
 
 ### Ordinals Tools
 
 Tools for working with ordinals (NFTs) on BSV:
 
-| Tool Name | Description |
-|-----------|-------------|
-| `ordinals_getInscription` | Retrieves detailed information about a specific inscription |
-| `ordinals_searchInscriptions` | Searches for inscriptions based on various criteria |
-| `ordinals_marketListings` | Retrieves market listings for NFTs, BSV-20, and BSV-21 tokens with unified interface |
-| `ordinals_marketSales` | Gets information about BSV-20 and BSV-21 token market sales |
-| `ordinals_getBsv20ById` | Retrieves details about a specific BSV20 token by ID |
+| Tool Name | Description | Example Output |
+|-----------|-------------|----------------|
+| `ordinals_getInscription` | Retrieves detailed information about a specific inscription | `{"id":"a1b2c3d4e5f6...","origin":"a1b2c3d4e5f6...","contentType":"image/png","content":"iVBORw0KGgoAAA..."}` |
+| `ordinals_searchInscriptions` | Searches for inscriptions based on various criteria | `{"results":[{"id":"a1b2c3...","contentType":"image/png","owner":"1Example..."},...]}` |
+| `ordinals_marketListings` | Retrieves market listings for NFTs, BSV-20, and BSV-21 tokens with unified interface | `{"results":[{"txid":"a1b2c3...","price":9990000,"tick":"PEPE","listing":true},...]}` |
+| `ordinals_marketSales` | Gets information about BSV-20 and BSV-21 token market sales | `{"results":[{"txid":"a1b2c3...","price":34710050,"tick":"$BTC","sale":true},...]}` |
+| `ordinals_getTokenByIdOrTicker` | Retrieves details about a specific BSV20 token by ID | `{"tick":"PEPE","max":"21000000","lim":"1000","dec":"2"}` |
 
 ### Utility Tools
 
 General-purpose utility functions:
 
-| Tool Name | Description |
-|-----------|-------------|
-| `utils_convertData` | Converts data between different encodings (utf8, hex, base64, binary) |
+| Tool Name | Description | Example Output |
+|-----------|-------------|----------------|
+| `utils_convertData` | Converts data between different encodings (utf8, hex, base64, binary) | `68656c6c6f20776f726c64` (UTF-8 "hello world" converted to hex) |
 
 ## Using the Tools with MCP
 
@@ -201,6 +202,11 @@ Once connected, you can use natural language to interact with Bitcoin SV through
 ### Blockchain Operations
 - "What is the current BSV price?"
 - "Decode this BSV transaction: (transaction hex or ID)"
+- "Get the latest Bitcoin SV chain information"
+- "Show me block details for height 800000"
+- "Explore transaction history for address 1ExampleBsvAddressXXXX"
+- "Check unspent outputs (UTXOs) for my wallet address"
+- "Get details for transaction with hash a1b2c3d4e5f6..."
 
 ### Data Conversion
 - "Convert 'Hello World' from UTF-8 to hex format"
@@ -233,17 +239,81 @@ For Cursor, check the Cursor MCP logs in Settings → Extensions → Model Conte
 
 ## Recent Updates
 
-### Unified Encryption Tool
-- **Combined Wallet Encryption**: The `wallet_encrypt` and `wallet_decrypt` tools have been merged into a single `wallet_encryption` tool with a mode parameter to switch between encryption and decryption operations.
+- **Blockchain Explorer**: Added `bsv_explore` tool for WhatsOnChain API access with mainnet/testnet support
+- **Unified Tools**: Merged `wallet_encrypt`/`wallet_decrypt` into single `wallet_encryption` tool
+- **Enhanced Marketplace**: Support for NFTs, BSV-20/21 tokens in listings, sales and purchases
+- **Performance**: Added price caching and optimized API endpoint structure
+- **Improved Validation**: Better error handling for private keys and parameters
 
-### Enhanced Marketplace Tools
-- **Unified Market Listings**: The `ordinals_marketListings` tool now supports NFTs, BSV-20, and BSV-21 tokens through a single interface with appropriate filtering.
-- **Improved Market Sales**: The `ordinals_marketSales` tool (renamed from `ordinals_bsv20MarketSales`) now supports both BSV-20 and BSV-21 token sales.
-- **Token Purchases**: The `wallet_purchaseListing` tool has been enhanced to support purchasing both NFTs and BSV-20/BSV-21 tokens.
+## Bitcoin SV Blockchain Explorer
 
-### API Refinements
-- Standardized endpoint structure for interactions with the GorillaPool API.
-- Improved parameter handling for different token types and marketplace actions.
+The `bsv_explore` tool provides comprehensive access to the Bitcoin SV blockchain through the WhatsOnChain API. This powerful explorer tool allows you to query various aspects of the blockchain, including chain data, blocks, transactions, and address information.
+
+### Available Endpoints
+
+The tool supports the following endpoint categories and specific endpoints:
+
+#### Chain Data
+| Endpoint | Description | Required Parameters | Example Response |
+|----------|-------------|---------------------|------------------|
+| `chain_info` | Network statistics, difficulty, and chain work | None | `{"chain":"main","blocks":826458,"headers":826458,"bestblockhash":"000000000000..."}` |
+| `chain_tips` | Current chain tips including heights and states | None | `[{"height":826458,"hash":"000000000000...","branchlen":0,"status":"active"}]` |
+| `circulating_supply` | Current BSV circulating supply | None | `{"bsv":21000000}` |
+| `peer_info` | Connected peer statistics | None | `[{"addr":"1.2.3.4:8333","services":"000000000000...","lastsend":1621234567}]` |
+
+#### Block Data
+| Endpoint | Description | Required Parameters | Example Response |
+|----------|-------------|---------------------|------------------|
+| `block_by_hash` | Complete block data via hash | `blockHash` | `{"hash":"000000000000...","confirmations":1000,"size":1000000,...}` |
+| `block_by_height` | Complete block data via height | `blockHeight` | `{"hash":"000000000000...","confirmations":1000,"size":1000000,...}` |
+
+#### Transaction Data
+| Endpoint | Description | Required Parameters | Example Response |
+|----------|-------------|---------------------|------------------|
+| `tx_by_hash` | Detailed transaction data | `txHash` | `{"txid":"a1b2c3d4e5f6...","version":1,"locktime":0,"size":225,...}` |
+| `tx_raw` | Raw transaction hex data | `txHash` | `"01000000012345abcdef..."` |
+| `tx_receipt` | Transaction receipt | `txHash` | `{"blockHash":"000000000000...","blockHeight":800000,"confirmations":26458}` |
+
+#### Address Data
+| Endpoint | Description | Required Parameters | Example Response |
+|----------|-------------|---------------------|------------------|
+| `address_history` | Transaction history for address | `address`, optional: `limit` | `[{"tx_hash":"a1b2c3d4e5f6...","height":800000},...]` |
+| `address_utxos` | Unspent outputs for address | `address` | `[{"tx_hash":"a1b2c3d4e5f6...","tx_pos":0,"value":100000},...]` |
+
+#### Network
+| Endpoint | Description | Required Parameters | Example Response |
+|----------|-------------|---------------------|------------------|
+| `health` | API health check | None | `{"status":"synced"}` |
+
+### Usage Examples
+
+The `bsv_explore` tool can be used with natural language prompts like:
+
+```
+"Get the current Bitcoin SV blockchain information"
+"Show me block #800000 details"
+"Fetch transaction history for address 1ExampleBsvAddressXXXXXXXX"
+"Get unspent outputs for my wallet address"
+"Check transaction details for txid a1b2c3d4e5f6..."
+"What is the current BSV circulating supply?"
+```
+
+Under the hood, the tool accepts parameters to specify which data to retrieve:
+
+- `endpoint`: The specific WhatsOnChain endpoint to query (e.g., `chain_info`, `tx_by_hash`)
+- `network`: The BSV network to use (`main` or `test`)
+- Additional parameters as required by the specific endpoint:
+  - `blockHash`: For block_by_hash endpoint
+  - `blockHeight`: For block_by_height endpoint
+  - `txHash`: For transaction-related endpoints
+  - `address`: For address-related endpoints
+  - `limit`: Optional pagination limit for address_history
+
+### Network Options
+
+The tool supports both mainnet and testnet:
+- `main`: Bitcoin SV mainnet (default)
+- `test`: Bitcoin SV testnet
 
 ## Development
 
@@ -261,4 +331,4 @@ bun test
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/index.ts

@@ -6,16 +6,43 @@ import { registerAllTools } from "./tools";
 import { registerWalletTools } from "./tools/wallet/tools";
 import { Wallet } from "./tools/wallet/wallet";
 
+/**
+ * Validate the private key from environment variables
+ * Exits the process with an error message if validation fails
+ */
+function validatePrivateKey(): PrivateKey {
+	const privateKeyWif = process.env.PRIVATE_KEY_WIF;
+	
+	// Check if private key is set
+	if (!privateKeyWif) {
+		console.error("\x1b[31mError: PRIVATE_KEY_WIF environment variable is not set\x1b[0m");
+		console.error("Please set this variable with a valid Bitcoin SV private key in WIF format");
+		console.error("Example: PRIVATE_KEY_WIF=your_private_key_wif bun run index.ts");
+		process.exit(1);
+	}
+	
+	// Validate the private key format
+	try {
+		return PrivateKey.fromWif(privateKeyWif);
+	} catch (error) {
+		console.error("\x1b[31mError: Invalid private key format\x1b[0m");
+		console.error("The PRIVATE_KEY_WIF provided is not a valid Bitcoin SV private key in WIF format");
+		console.error("Please check your key and try again");
+		process.exit(1);
+	}
+}
+
+// Validate private key early before starting the server
+const privKey = validatePrivateKey();
+console.log("\x1b[32mPrivate key validated successfully\x1b[0m");
+
 const server = new McpServer({
 	name: "Bitcoin SV MCP",
 	version: "0.0.1",
 });
 
-// Singleton wallet instance (for demo, could be replaced with real key management)
-// If PRIVATE_KEY_WIF is set in the environment, use it to instantiate the Wallet
-const privateKeyWif = process.env.PRIVATE_KEY_WIF;
-const privKey = privateKeyWif ? PrivateKey.fromWif(privateKeyWif) : undefined;
-const wallet = privKey ? new Wallet(privKey) : new Wallet();
+// Initialize wallet with the validated private key
+const wallet = new Wallet(privKey);
 
 // Register wallet tools separately (needs wallet instance)
 registerWalletTools(server, wallet);
@@ -25,7 +52,7 @@ registerAllTools(server);
 
 // Debug: Log all registered tools
 console.log("Registered tools:", Object.keys(server));
-console.log("MCP Server:", server);
+console.log("MCP Server ready 🚀");
 
 // Connect to the transport
 const transport = new StdioServerTransport();

package/package.json

@@ -2,7 +2,31 @@
 	"name": "bsv-mcp",
 	"module": "index.ts",
 	"type": "module",
-	"version": "0.0.8",
+	"version": "0.0.10",
+	"license": "MIT",
+	"author": "satchmo",
+	"description": "A collection of Bitcoin SV (BSV) tools for the Model Context Protocol (MCP) framework",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/b-open-io/bsv-mcp"
+	},
+	"keywords": [
+		"bitcoin",
+		"bsv",
+		"bitcoin-sv",
+		"mcp",
+		"model-context-protocol",
+		"wallet",
+		"ordinals",
+		"blockchain"
+	],
+	"files": [
+		"index.ts",
+		"tools/**/*.ts",
+		"LICENSE",
+		"README.md",
+		"smithery.yaml"
+	],
 	"bin": {
 		"bsv-mcp": "./index.ts"
 	},
@@ -20,7 +44,6 @@
 		"@types/node": "^22.14.1",
 		"js-1sat-ord": "^0.1.80",
 		"satoshi-token": "^0.0.4",
-		"tsx": "^4.19.3",
 		"zod": "^3.24.2"
 	},
 	"scripts": {

package/tools/bsv/explore.ts

@@ -0,0 +1,177 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// Base URL for WhatsOnChain API
+const WOC_API_BASE_URL = "https://api.whatsonchain.com/v1/bsv";
+
+/**
+ * WhatsOnChain API endpoints available for exploration
+ */
+enum ExploreEndpoint {
+  // Chain endpoints
+  CHAIN_INFO = "chain_info",
+  CHAIN_TIPS = "chain_tips",
+  CIRCULATING_SUPPLY = "circulating_supply",
+  PEER_INFO = "peer_info",
+  
+  // Block endpoints
+  BLOCK_BY_HASH = "block_by_hash",
+  BLOCK_BY_HEIGHT = "block_by_height",
+  
+  // Transaction endpoints
+  TX_BY_HASH = "tx_by_hash",
+  TX_RAW = "tx_raw",
+  TX_RECEIPT = "tx_receipt",
+  ADDRESS_HISTORY = "address_history",
+  ADDRESS_UTXOS = "address_utxos",
+  
+  // Health endpoint
+  HEALTH = "health",
+}
+
+enum Network {
+  MAIN = "main",
+  TEST = "test",
+}
+
+// Schema for the bsv_explore tool arguments
+const exploreArgsSchema = z.object({
+  endpoint: z.nativeEnum(ExploreEndpoint).describe("WhatsOnChain API endpoint to call"),
+  network: z.nativeEnum(Network).default(Network.MAIN).describe("Network to use (main or test)"),
+  
+  // Parameters for specific endpoints
+  blockHash: z.string().optional().describe("Block hash (required for block_by_hash endpoint)"),
+  blockHeight: z.number().optional().describe("Block height (required for block_by_height endpoint)"),
+  txHash: z.string().optional().describe("Transaction hash (required for tx_by_hash, tx_raw, and tx_receipt endpoints)"),
+  address: z.string().optional().describe("Bitcoin address (required for address_history and address_utxos endpoints)"),
+  limit: z.number().optional().describe("Limit for paginated results (optional for address_history)"),
+});
+
+// Type for the tool arguments
+type ExploreArgs = z.infer<typeof exploreArgsSchema>;
+
+/**
+ * Register the bsv_explore tool with the MCP server
+ * @param server The MCP server instance
+ */
+export function registerExploreTool(server: McpServer): void {
+  server.tool(
+    "bsv_explore",
+    "Explore Bitcoin SV blockchain data using the WhatsOnChain API. Access multiple data types:\n\n" +
+    "CHAIN DATA:\n" +
+    "- chain_info: Network stats, difficulty, and chain work\n" +
+    "- chain_tips: Current chain tips including heights and states\n" +
+    "- circulating_supply: Current BSV circulating supply\n" +
+    "- peer_info: Connected peer statistics\n\n" +
+    "BLOCK DATA:\n" +
+    "- block_by_hash: Complete block data via hash (requires blockHash parameter)\n" +
+    "- block_by_height: Complete block data via height (requires blockHeight parameter)\n\n" +
+    "TRANSACTION DATA:\n" +
+    "- tx_by_hash: Detailed transaction data (requires txHash parameter)\n" +
+    "- tx_raw: Raw transaction hex data (requires txHash parameter)\n" +
+    "- tx_receipt: Transaction receipt (requires txHash parameter)\n\n" +
+    "ADDRESS DATA:\n" +
+    "- address_history: Transaction history for address (requires address parameter, optional limit)\n" +
+    "- address_utxos: Unspent outputs for address (requires address parameter)\n\n" +
+    "NETWORK:\n" +
+    "- health: API health check\n\n" +
+    "Use the appropriate parameters for each endpoint type and specify 'main' or 'test' network.",
+    { args: exploreArgsSchema },
+    async ({ args }) => {
+      try {
+        const params = exploreArgsSchema.parse(args);
+        
+        // Validate required parameters for specific endpoints
+        if (params.endpoint === ExploreEndpoint.BLOCK_BY_HASH && !params.blockHash) {
+          throw new Error("blockHash is required for block_by_hash endpoint");
+        }
+        
+        if (params.endpoint === ExploreEndpoint.BLOCK_BY_HEIGHT && params.blockHeight === undefined) {
+          throw new Error("blockHeight is required for block_by_height endpoint");
+        }
+
+        if ([ExploreEndpoint.TX_BY_HASH, ExploreEndpoint.TX_RAW, ExploreEndpoint.TX_RECEIPT].includes(params.endpoint) && !params.txHash) {
+          throw new Error("txHash is required for transaction endpoints");
+        }
+
+        if ([ExploreEndpoint.ADDRESS_HISTORY, ExploreEndpoint.ADDRESS_UTXOS].includes(params.endpoint) && !params.address) {
+          throw new Error("address is required for address endpoints");
+        }
+        
+        // Build API URL based on the selected endpoint
+        let apiUrl = `${WOC_API_BASE_URL}/${params.network}`;
+        
+        switch (params.endpoint) {
+          case ExploreEndpoint.CHAIN_INFO:
+            apiUrl += "/chain/info";
+            break;
+          case ExploreEndpoint.CHAIN_TIPS:
+            apiUrl += "/chain/tips";
+            break;
+          case ExploreEndpoint.CIRCULATING_SUPPLY:
+            apiUrl += "/circulatingsupply";
+            break;
+          case ExploreEndpoint.PEER_INFO:
+            apiUrl += "/peer/info";
+            break;
+          case ExploreEndpoint.BLOCK_BY_HASH:
+            apiUrl += `/block/hash/${params.blockHash}`;
+            break;
+          case ExploreEndpoint.BLOCK_BY_HEIGHT:
+            apiUrl += `/block/height/${params.blockHeight}`;
+            break;
+          case ExploreEndpoint.TX_BY_HASH:
+            apiUrl += `/tx/hash/${params.txHash}`;
+            break;
+          case ExploreEndpoint.TX_RAW:
+            apiUrl += `/tx/${params.txHash}/hex`;
+            break;
+          case ExploreEndpoint.TX_RECEIPT:
+            apiUrl += `/tx/${params.txHash}/receipt`;
+            break;
+          case ExploreEndpoint.ADDRESS_HISTORY:
+            apiUrl += `/address/${params.address}/history`;
+            if (params.limit !== undefined) {
+              apiUrl += `?limit=${params.limit}`;
+            }
+            break;
+          case ExploreEndpoint.ADDRESS_UTXOS:
+            apiUrl += `/address/${params.address}/unspent`;
+            break;
+          case ExploreEndpoint.HEALTH:
+            apiUrl += "/woc";
+            break;
+          default:
+            throw new Error(`Unsupported endpoint: ${params.endpoint}`);
+        }
+        
+        // Make the API request
+        const response = await fetch(apiUrl);
+        if (!response.ok) {
+          throw new Error(`API error: ${response.status} ${response.statusText}`);
+        }
+        
+        const result = await response.json();
+        
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: "text", 
+              text: `Error: ${error instanceof Error ? error.message : String(error)}`
+            }
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+} 

package/tools/bsv/getPrice.ts

@@ -1,6 +1,48 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 
+// Define cache duration (5 minutes in milliseconds)
+const PRICE_CACHE_DURATION = 5 * 60 * 1000;
+
+// Cache object to store price data
+let cachedPrice: { value: number; timestamp: number } | null = null;
+
+/**
+ * Get the BSV price with caching mechanism
+ * @returns The current BSV price in USD
+ */
+async function getBsvPriceWithCache(): Promise<number> {
+	// Return cached price if it's still valid
+	if (cachedPrice && (Date.now() - cachedPrice.timestamp) < PRICE_CACHE_DURATION) {
+		console.log("Using cached BSV price");
+		return cachedPrice.value;
+	}
+
+	console.log("Fetching fresh BSV price");
+	// If no valid cache, fetch new price
+	const res = await fetch(
+		"https://api.whatsonchain.com/v1/bsv/main/exchangerate",
+	);
+	if (!res.ok) throw new Error("Failed to fetch price");
+	
+	const data = (await res.json()) as {
+		currency: string;
+		rate: string;
+		time: number;
+	};
+	
+	const price = Number(data.rate);
+	if (Number.isNaN(price) || price <= 0) throw new Error("Invalid price received");
+	
+	// Update cache
+	cachedPrice = { 
+		value: price, 
+		timestamp: Date.now() 
+	};
+	
+	return price;
+}
+
 /**
  * Register the BSV price lookup tool
  * @param server The MCP server instance
@@ -14,23 +56,12 @@ export function registerGetPriceTool(server: McpServer): void {
 		},
 		async () => {
 			try {
-				const res = await fetch(
-					"https://api.whatsonchain.com/v1/bsv/main/exchangerate",
-				);
-				if (!res.ok) throw new Error("Failed to fetch price");
-				const data = (await res.json()) as {
-					currency: string;
-					rate: string;
-					time: number;
-				};
-				const price = data.rate;
-				if (typeof price !== "string" && typeof price !== "number")
-					throw new Error("Price not found");
+				const price = await getBsvPriceWithCache();
 				return {
 					content: [
 						{
 							type: "text",
-							text: `Current BSV price: $${Number(price).toFixed(2)} USD`,
+							text: `Current BSV price: $${price.toFixed(2)} USD`,
 						},
 					],
 				};
@@ -43,3 +74,6 @@ export function registerGetPriceTool(server: McpServer): void {
 		},
 	);
 }
+
+// Export the cached price getter for use in other modules
+export { getBsvPriceWithCache };

package/tools/bsv/index.ts

@@ -1,6 +1,7 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { registerDecodeTransactionTool } from "./decodeTransaction";
 import { registerGetPriceTool } from "./getPrice";
+import { registerExploreTool } from "./explore";
 
 /**
  * Register all BSV tools with the MCP server
@@ -10,4 +11,5 @@ export function registerBsvTools(server: McpServer): void {
 	// Register BSV-related tools
 	registerGetPriceTool(server);
 	registerDecodeTransactionTool(server);
+	registerExploreTool(server);
 }

package/tools/wallet/sendToAddress.ts

@@ -5,33 +5,7 @@ import { toSatoshi } from "satoshi-token";
 import type { z } from "zod";
 import { sendToAddressArgsSchema } from "./schemas";
 import type { Wallet } from "./wallet";
-
-/**
- * Fetch the current BSV price from whatsonchain API
- * @returns The BSV price in USD
- */
-async function getBsvPrice(): Promise<number> {
-	try {
-		const res = await fetch(
-			"https://api.whatsonchain.com/v1/bsv/main/exchangerate",
-		);
-		if (!res.ok) throw new Error("Failed to fetch BSV price");
-
-		// Parse the response with proper type casting
-		const data = (await res.json()) as {
-			rate: string;
-			currency: string;
-			time: number;
-		};
-		const price = Number(data.rate);
-
-		if (Number.isNaN(price) || price <= 0) throw new Error("Invalid BSV price");
-		return price;
-	} catch (error) {
-		console.error("BSV price fetch error:", error);
-		throw error;
-	}
-}
+import { getBsvPriceWithCache } from "../bsv/getPrice";
 
 // Use the schema imported from schemas.ts
 export type SendToAddressArgs = z.infer<typeof sendToAddressArgsSchema>;
@@ -62,7 +36,7 @@ export function registerSendToAddressTool(server: McpServer, wallet: Wallet) {
 				let satoshis: number;
 				if (currency === "USD") {
 					// Get current BSV price
-					const bsvPriceUsd = await getBsvPrice();
+					const bsvPriceUsd = await getBsvPriceWithCache();
 
 					// Convert USD to BSV
 					const bsvAmount = amount / bsvPriceUsd;

package/tools/wallet/tools.test.ts

@@ -11,15 +11,13 @@ type WalletToolName =
 	| "wallet_getPublicKey"
 	| "wallet_createSignature"
 	| "wallet_verifySignature"
-	| "wallet_encrypt"
-	| "wallet_decrypt";
+	| "wallet_encryption";	
 
 const toolNames: WalletToolName[] = [
 	"wallet_getPublicKey",
 	"wallet_createSignature",
 	"wallet_verifySignature",
-	"wallet_encrypt",
-	"wallet_decrypt",
+	"wallet_encryption",
 ];
 
 // Helper function to get dummy arguments for each tool
@@ -36,10 +34,12 @@ function getDummyArgs(tool: WalletToolName): Record<string, unknown> {
 				signature: "sig",
 				publicKey: "pubkey",
 			};
-		case "wallet_encrypt":
-			return { data: "test", publicKey: "pubkey" };
-		case "wallet_decrypt":
-			return { encryptedData: "data" };
+			// TODO we merged encrypt and decrypt into encryption we need to update the test file
+		// case "wallet_encryption":
+		// 	if 
+		// 	return { data: "test", publicKey: "pubkey" };
+		// case "wallet_decryption":
+		// 	return { encryptedData: "data" };
 		default:
 			return {};
 	}

package/Dockerfile

@@ -1,20 +0,0 @@
-# Use the official Bun image
-FROM oven/bun:1
-
-# Set working directory
-WORKDIR /app
-
-# Copy all application code first
-COPY . .
-
-# Install dependencies
-RUN bun install --frozen-lockfile
-
-# Set user for security
-USER bun
-
-# Expose port (if needed)
-EXPOSE 3000
-
-# Run the application
-CMD ["bun", "run", "index.ts"] 

package/biome.json

@@ -1,30 +0,0 @@
-{
-	"$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
-	"vcs": {
-		"enabled": false,
-		"clientKind": "git",
-		"useIgnoreFile": false
-	},
-	"files": {
-		"ignoreUnknown": false,
-		"ignore": []
-	},
-	"formatter": {
-		"enabled": true,
-		"indentStyle": "tab"
-	},
-	"organizeImports": {
-		"enabled": true
-	},
-	"linter": {
-		"enabled": true,
-		"rules": {
-			"recommended": true
-		}
-	},
-	"javascript": {
-		"formatter": {
-			"quoteStyle": "double"
-		}
-	}
-}

package/tests/integration/wallet-server.test.ts

@@ -1,216 +0,0 @@
-import { expect, test } from "bun:test";
-import { PrivateKey } from "@bsv/sdk";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
-import { registerWalletTools } from "../../tools/wallet/tools";
-import { Wallet } from "../../tools/wallet/wallet";
-
-// List of expected wallet tool names
-const EXPECTED_WALLET_TOOLS = [
-	"wallet_getPublicKey",
-	"wallet_createSignature",
-	"wallet_verifySignature",
-	"wallet_encrypt",
-	"wallet_decrypt",
-	"wallet_createAction",
-	"wallet_signAction",
-	"wallet_listActions",
-	"wallet_listOutputs",
-	"wallet_getNetwork",
-	"wallet_getVersion",
-	"wallet_revealCounterpartyKeyLinkage",
-	"wallet_revealSpecificKeyLinkage",
-	"wallet_createHmac",
-	"wallet_verifyHmac",
-	"wallet_abortAction",
-	"wallet_internalizeAction",
-	"wallet_relinquishOutput",
-	"wallet_acquireCertificate",
-	"wallet_listCertificates",
-	"wallet_proveCertificate",
-	"wallet_relinquishCertificate",
-	"wallet_discoverByIdentityKey",
-	"wallet_discoverByAttributes",
-	"wallet_isAuthenticated",
-	"wallet_waitForAuthentication",
-	"wallet_getHeaderForHeight",
-];
-
-// Mock wallet with test responses
-class TestWallet extends Wallet {
-	constructor() {
-		super(PrivateKey.fromRandom());
-	}
-
-	// Override with test implementations that actually return something
-	async getPublicKey() {
-		return { publicKey: "mockPublicKey123" };
-	}
-
-	// Note: other methods will still return 'not implemented' errors
-}
-
-test("MCP server registers all expected wallet tools", async () => {
-	// Create an MCP server
-	const server = new McpServer({
-		name: "Wallet Server Test",
-		version: "0.0.1",
-	});
-
-	// Create test wallet and register tools
-	const wallet = new TestWallet();
-	const handlers = registerWalletTools(server, wallet);
-
-	// Check that we have all expected tool handlers
-	for (const toolName of EXPECTED_WALLET_TOOLS) {
-		expect(handlers[toolName as keyof typeof handlers]).toBeDefined();
-		expect(typeof handlers[toolName as keyof typeof handlers]).toBe("function");
-	}
-
-	// Check that we don't have any unexpected handlers
-	const actualToolNames = Object.keys(handlers);
-	expect(actualToolNames.length).toBe(EXPECTED_WALLET_TOOLS.length);
-
-	for (const toolName of actualToolNames) {
-		expect(EXPECTED_WALLET_TOOLS).toContain(toolName);
-	}
-});
-
-test("MCP server with wallet tools", async () => {
-	// Create an MCP server
-	const server = new McpServer({
-		name: "Wallet Server Test",
-		version: "0.0.1",
-	});
-
-	// Create test wallet and register tools
-	const wallet = new TestWallet();
-	const handlers = registerWalletTools(server, wallet);
-
-	// Mock the request handler extra
-	const mockExtra = {
-		signal: new AbortController().signal,
-	};
-
-	// Test the overridden getPublicKey handler which should return data
-	const getPublicKeyHandler = handlers.wallet_getPublicKey;
-	const getPublicKeyResult = await getPublicKeyHandler({ args: {} }, mockExtra);
-
-	// Check the success result based on the actual structure
-	expect(getPublicKeyResult.content).toBeDefined();
-	expect(getPublicKeyResult.content?.[0]?.type).toBe("text");
-
-	const publicKeyContent = getPublicKeyResult.content?.[0]?.text;
-	if (typeof publicKeyContent === "string") {
-		expect(JSON.parse(publicKeyContent)).toEqual({
-			publicKey: "mockPublicKey123",
-		});
-	}
-});
-
-// For a more complete integration test, we could create a real HTTP server
-// and use fetch to make requests to it
-test.skip("MCP server with HTTP requests", async () => {
-	// Create MCP server
-	const server = new McpServer({
-		name: "Wallet Server Test",
-		version: "0.0.1",
-	});
-
-	// Register wallet tools
-	const wallet = new TestWallet();
-	const handlers = registerWalletTools(server, wallet);
-
-	// Define expected request type
-	type ToolCallRequest = {
-		type: string;
-		name: string;
-		args?: Record<string, unknown>;
-	};
-
-	// Create a simple HTTP server
-	const httpServer = Bun.serve({
-		port: 0, // Use random available port
-		async fetch(req) {
-			if (req.method === "POST") {
-				const bodyText = await req.text();
-				let body: unknown;
-
-				try {
-					body = JSON.parse(bodyText);
-				} catch (err) {
-					return new Response("Invalid JSON", { status: 400 });
-				}
-
-				// Type guard for the request body
-				const isToolCallRequest = (obj: unknown): obj is ToolCallRequest => {
-					return (
-						typeof obj === "object" &&
-						obj !== null &&
-						"type" in obj &&
-						"name" in obj &&
-						typeof (obj as ToolCallRequest).type === "string" &&
-						typeof (obj as ToolCallRequest).name === "string"
-					);
-				};
-
-				// Handle MCP requests by calling the appropriate tool
-				if (
-					isToolCallRequest(body) &&
-					body.type === "tool_call" &&
-					body.name.startsWith("wallet_")
-				) {
-					// Get handler from our handlers object
-					const toolName = body.name as keyof typeof handlers;
-					const handler = handlers[toolName];
-					if (handler) {
-						const result = await handler(
-							{ args: body.args || {} },
-							{
-								signal: new AbortController().signal,
-							},
-						);
-
-						return new Response(JSON.stringify(result), {
-							headers: { "Content-Type": "application/json" },
-						});
-					}
-				}
-			}
-
-			return new Response("Not found", { status: 404 });
-		},
-	});
-
-	try {
-		const port = httpServer.port;
-		const baseUrl = `http://localhost:${port}`;
-
-		// Test calling the getPublicKey tool
-		const response = await fetch(`${baseUrl}`, {
-			method: "POST",
-			headers: { "Content-Type": "application/json" },
-			body: JSON.stringify({
-				type: "tool_call",
-				name: "wallet_getPublicKey",
-				args: {},
-			}),
-		});
-
-		const resultData = (await response.json()) as {
-			isError?: boolean;
-			content?: Array<{ type: string; text: string }>;
-		};
-
-		expect(resultData.content).toBeDefined();
-		expect(resultData.content?.[0]?.type).toBe("text");
-
-		if (resultData.content?.[0]?.text) {
-			const parsedContent = JSON.parse(resultData.content[0].text);
-			expect(parsedContent).toEqual({ publicKey: "mockPublicKey123" });
-		}
-	} finally {
-		// Shutdown the server
-		httpServer.stop();
-	}
-});

package/tsconfig.json

@@ -1,28 +0,0 @@
-{
-	"compilerOptions": {
-		// Environment setup & latest features
-		"lib": ["ESNext"],
-		"target": "ESNext",
-		"module": "ESNext",
-		"moduleDetection": "force",
-		"jsx": "react-jsx",
-		"allowJs": true,
-
-		// Bundler mode
-		"moduleResolution": "bundler",
-		"allowImportingTsExtensions": true,
-		"verbatimModuleSyntax": true,
-		"noEmit": true,
-
-		// Best practices
-		"strict": true,
-		"skipLibCheck": true,
-		"noFallthroughCasesInSwitch": true,
-		"noUncheckedIndexedAccess": true,
-
-		// Some stricter flags (disabled by default)
-		"noUnusedLocals": false,
-		"noUnusedParameters": false,
-		"noPropertyAccessFromIndexSignature": false
-	}
-}