bsv-mcp 0.0.17 → 0.0.19

package/README.md

@@ -267,6 +267,15 @@ The tool supports the following endpoint categories and specific endpoints:
 | `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,...}` |
 | `tag_count_by_height` | Stats on tag count for a specific block | `blockHeight` | `{"tags":{"amp":3,"bitkey":5,"metanet":12,"planaria":7,"b":120}}` |
+| `block_headers` | Retrieves the last 10 block headers | None | `[{"hash":"000000000000...","height":826458,"version":536870912,...},...]` |
+| `block_pages` | Retrieves pages of transaction IDs for large blocks | `blockHash`, optional: `pageNumber` | `["tx1hash","tx2hash","tx3hash",...]` |
+
+#### Stats Data
+| Endpoint | Description | Required Parameters | Example Response |
+|----------|-------------|---------------------|------------------|
+| `block_stats_by_height` | Block statistics for a specific height | `blockHeight` | `{"size":123456,"txCount":512,"outputTotal":54.12345678,"outputTotalUsd":2345.67,...}` |
+| `block_miner_stats` | Block mining statistics for a time period | optional: `days` (default 7) | `{"blocks":{"miner1":412,"miner2":208,...},"total":1008}` |
+| `miner_summary_stats` | Summary of mining statistics | optional: `days` (default 7) | `{"totalBlocks":1008,"totalFees":1.23456789,"totalFeesUsd":53.67,...}` |
 
 #### Transaction Data
 | Endpoint | Description | Required Parameters | Example Response |
@@ -274,6 +283,7 @@ The tool supports the following endpoint categories and specific endpoints:
 | `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}` |
+| `bulk_tx_details` | Retrieve multiple transactions in one request | `txids` (array) | `[{"txid":"a1b2c3d4e5f6...","version":1,...}, {"txid":"b2c3d4e5f6a7...","version":1,...}]` |
 
 #### Address Data
 | Endpoint | Description | Required Parameters | Example Response |
@@ -298,6 +308,12 @@ The `bsv_explore` tool can be used with natural language prompts like:
 "Get unspent outputs for my wallet address"
 "Check transaction details for txid a1b2c3d4e5f6..."
 "What is the current BSV circulating supply?"
+"Show me the latest block headers"
+"Get transaction IDs for page 2 of a large block"
+"Show me block statistics for height 800000"
+"What are the mining statistics for the last 14 days?"
+"Get a summary of mining activity over the past 30 days"
+"Retrieve details for multiple transactions in a single query"
 ```
 
 Under the hood, the tool accepts parameters to specify which data to retrieve:
@@ -305,9 +321,12 @@ 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
+  - `blockHash`: For block_by_hash and block_pages endpoints
+  - `blockHeight`: For block_by_height, tag_count_by_height, and block_stats_by_height endpoints
+  - `pageNumber`: For block_pages endpoint (pagination)
+  - `days`: For block_miner_stats and miner_summary_stats endpoints (defaults to 7)
+  - `txHash`: For transaction-related endpoints (tx_by_hash, tx_raw, tx_receipt)
+  - `txids`: For bulk_tx_details endpoint (array of transaction IDs)
   - `address`: For address-related endpoints
   - `limit`: Optional pagination limit for address_history
 

package/index.ts

@@ -37,7 +37,7 @@ const privKey = validatePrivateKey();
 
 const server = new McpServer({
 	name: "Bitcoin SV MCP Server",
-	version: "0.0.17",
+	version: "0.0.19",
 });
 
 // Initialize wallet with the validated private key

package/package.json

@@ -2,7 +2,7 @@
 	"name": "bsv-mcp",
 	"module": "index.ts",
 	"type": "module",
-	"version": "0.0.17",
+	"version": "0.0.19",
 	"license": "MIT",
 	"author": "satchmo",
 	"description": "A collection of Bitcoin SV (BSV) tools for the Model Context Protocol (MCP) framework",

package/tools/bsv/explore.ts

@@ -17,12 +17,20 @@ enum ExploreEndpoint {
   // Block endpoints
   BLOCK_BY_HASH = "block_by_hash",
   BLOCK_BY_HEIGHT = "block_by_height",
+  BLOCK_HEADERS = "block_headers",
+  BLOCK_PAGES = "block_pages",
+  
+  // Stats endpoints
   TAG_COUNT_BY_HEIGHT = "tag_count_by_height",
+  BLOCK_STATS_BY_HEIGHT = "block_stats_by_height",
+  BLOCK_MINER_STATS = "block_miner_stats", 
+  MINER_SUMMARY_STATS = "miner_summary_stats",
   
   // Transaction endpoints
   TX_BY_HASH = "tx_by_hash",
   TX_RAW = "tx_raw",
   TX_RECEIPT = "tx_receipt",
+  BULK_TX_DETAILS = "bulk_tx_details",
   ADDRESS_HISTORY = "address_history",
   ADDRESS_UTXOS = "address_utxos",
   
@@ -42,10 +50,13 @@ const exploreArgsSchema = z.object({
   
   // 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)"),
+  blockHeight: z.number().optional().describe("Block height (required for block_by_height and block_stats_by_height endpoints)"),
   txHash: z.string().optional().describe("Transaction hash (required for tx_by_hash, tx_raw, and tx_receipt endpoints)"),
+  txids: z.array(z.string()).optional().describe("Array of transaction IDs for bulk_tx_details endpoint"),
   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)"),
+  pageNumber: z.number().optional().describe("Page number for block_pages endpoint (defaults to 1)"),
+  days: z.number().optional().describe("Number of days for miner stats endpoints (defaults to 7)"),
 });
 
 // Type for the tool arguments
@@ -67,11 +78,18 @@ export function registerExploreTool(server: McpServer): void {
     "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" +
-    "- tag_count_by_height: Stats on tag count for a specific block via height (requires blockHeight parameter)\n\n" +
+    "- tag_count_by_height: Stats on tag count for a specific block via height (requires blockHeight parameter)\n" +
+    "- block_headers: Retrieves the last 10 block headers\n" +
+    "- block_pages: Retrieves pages of transaction IDs for large blocks (requires blockHash and optional pageNumber)\n\n" +
+    "STATS DATA:\n" +
+    "- block_stats_by_height: Block statistics for a specific height (requires blockHeight parameter)\n" +
+    "- block_miner_stats: Block mining statistics for a time period (optional days parameter, default 7)\n" +
+    "- miner_summary_stats: Summary of mining statistics (optional days parameter, default 7)\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" +
+    "- tx_receipt: Transaction receipt (requires txHash parameter)\n" +
+    "- bulk_tx_details: Bulk transaction details (requires txids parameter as array of transaction hashes)\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" +
@@ -99,6 +117,18 @@ export function registerExploreTool(server: McpServer): void {
         if ([ExploreEndpoint.ADDRESS_HISTORY, ExploreEndpoint.ADDRESS_UTXOS].includes(params.endpoint) && !params.address) {
           throw new Error("address is required for address endpoints");
         }
+
+        if (params.endpoint === ExploreEndpoint.BLOCK_PAGES && !params.blockHash) {
+          throw new Error("blockHash is required for block_pages endpoint");
+        }
+        
+        if (params.endpoint === ExploreEndpoint.BLOCK_STATS_BY_HEIGHT && params.blockHeight === undefined) {
+          throw new Error("blockHeight is required for block_stats_by_height endpoint");
+        }
+        
+        if (params.endpoint === ExploreEndpoint.BULK_TX_DETAILS && (!params.txids || params.txids.length === 0)) {
+          throw new Error("txids array is required for bulk_tx_details endpoint");
+        }
         
         // Build API URL based on the selected endpoint
         let apiUrl = `${WOC_API_BASE_URL}/${params.network}`;
@@ -125,6 +155,27 @@ export function registerExploreTool(server: McpServer): void {
           case ExploreEndpoint.TAG_COUNT_BY_HEIGHT:
             apiUrl += `/block/tagcount/height/${params.blockHeight}/stats`;
             break;
+          case ExploreEndpoint.BLOCK_HEADERS:
+            apiUrl += "/block/headers";
+            break;
+          case ExploreEndpoint.BLOCK_PAGES: {
+            const pageNumber = params.pageNumber || 1;
+            apiUrl += `/block/hash/${params.blockHash}/page/${pageNumber}`;
+            break;
+          }
+          case ExploreEndpoint.BLOCK_STATS_BY_HEIGHT:
+            apiUrl += `/block/height/${params.blockHeight}/stats`;
+            break;
+          case ExploreEndpoint.BLOCK_MINER_STATS: {
+            const days = params.days !== undefined ? params.days : 7;
+            apiUrl += `/miner/blocks/stats?days=${days}`;
+            break;
+          }
+          case ExploreEndpoint.MINER_SUMMARY_STATS: {
+            const days = params.days !== undefined ? params.days : 7;
+            apiUrl += `/miner/summary/stats?days=${days}`;
+            break;
+          }
           case ExploreEndpoint.TX_BY_HASH:
             apiUrl += `/tx/hash/${params.txHash}`;
             break;
@@ -134,6 +185,9 @@ export function registerExploreTool(server: McpServer): void {
           case ExploreEndpoint.TX_RECEIPT:
             apiUrl += `/tx/${params.txHash}/receipt`;
             break;
+          case ExploreEndpoint.BULK_TX_DETAILS:
+            apiUrl += "/txs";
+            break;
           case ExploreEndpoint.ADDRESS_HISTORY:
             apiUrl += `/address/${params.address}/history`;
             if (params.limit !== undefined) {
@@ -150,10 +204,64 @@ export function registerExploreTool(server: McpServer): void {
             throw new Error(`Unsupported endpoint: ${params.endpoint}`);
         }
         
-        // Make the API request
+        // Special handling for bulk_tx_details which requires a POST request
+        if (params.endpoint === ExploreEndpoint.BULK_TX_DETAILS) {
+          const response = await fetch(apiUrl, {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ txids: params.txids }),
+          });
+          
+          if (!response.ok) {
+            let errorMsg = `API error: ${response.status} ${response.statusText}`;
+            if (response.status === 404) {
+              errorMsg += " - One or more transaction IDs not found";
+            }
+            throw new Error(errorMsg);
+          }
+          
+          const result = await response.json();
+          
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(result, null, 2),
+              },
+            ],
+          };
+        }
+        
+        // For all other endpoints, use GET request
         const response = await fetch(apiUrl);
         if (!response.ok) {
-          throw new Error(`API error: ${response.status} ${response.statusText}`);
+          let errorMsg = `API error: ${response.status} ${response.statusText}`;
+          // Provide helpful tips for specific error codes
+          if (response.status === 404) {
+            switch (params.endpoint) {
+              case ExploreEndpoint.BLOCK_BY_HASH:
+                errorMsg += ` - Block hash "${params.blockHash}" not found`;
+                break;
+              case ExploreEndpoint.BLOCK_BY_HEIGHT:
+                errorMsg += ` - Block at height ${params.blockHeight} not found`;
+                break;
+              case ExploreEndpoint.BLOCK_PAGES:
+                errorMsg += ` - Block hash "${params.blockHash}" not found or page ${params.pageNumber || 1} does not exist`;
+                break;
+              case ExploreEndpoint.TX_BY_HASH:
+              case ExploreEndpoint.TX_RAW:
+              case ExploreEndpoint.TX_RECEIPT:
+                errorMsg += ` - Transaction hash "${params.txHash}" not found`;
+                break;
+              case ExploreEndpoint.ADDRESS_HISTORY:
+              case ExploreEndpoint.ADDRESS_UTXOS:
+                errorMsg += ` - No data found for address "${params.address}"`;
+                break;
+            }
+          }
+          throw new Error(errorMsg);
         }
         
         const result = await response.json();

package/tools/wallet/schemas.ts

@@ -74,21 +74,13 @@ export const walletDecryptArgsSchema = z.object({
 
 // Combined wallet encryption/decryption args
 export const walletEncryptionArgsSchema = z.object({
-	mode: z.enum(["encrypt", "decrypt"]).describe("Operation mode: 'encrypt' to encrypt data or 'decrypt' to decrypt data"),
+	mode: z.enum(["encrypt", "decrypt"]).describe("Operation mode: 'encrypt' to encrypt plaintext or 'decrypt' to decrypt data"),
 	data: z.union([
-		z.string().describe("Text data (with encoding specified by the encoding parameter)"),
-		z.array(z.number()).describe("Binary data as an array of numbers")
-	]).describe("Data to process: plaintext for encryption or ciphertext for decryption"),
+		z.string().describe("Text data to encrypt or decrypt"),
+		z.array(z.number()).describe("Binary data to encrypt or decrypt")
+	]).describe("Data to process: text/data for encryption or decryption"),
 	encoding: z.enum(["utf8", "hex", "base64"]).optional().default("utf8").describe("Encoding of text data (default: utf8)"),
-	protocolID: walletProtocolSchema.describe("Protocol identifier - common values are 'aes' for symmetric encryption or 'ecies' for asymmetric encryption"),
-	keyID: z.string().describe("Key identifier - use 'default' or 'primary' for the default wallet key"),
-	privilegedReason: z.string().optional().describe("Required reason for privileged operations"),
-	counterparty: z
-		.union([z.string(), z.literal("self"), z.literal("anyone")])
-		.optional()
-		.describe("Recipient of encryption. Use 'self' for personal encryption, or provide a specific key for a recipient"),
-	privileged: z.boolean().optional().describe("Indicates if operation requires elevated privileges"),
-}).describe("Combined schema for encryption and decryption operations. Use 'mode' to specify the operation type, with required parameters data, protocolID, and keyID.");
+}).describe("Schema for encryption and decryption operations");
 
 // Create HMAC arguments
 export const createHmacArgsSchema = z.object({

package/tools/wallet/tools.ts

@@ -39,7 +39,7 @@ import type { createOrdinalsArgsSchema } from "./createOrdinals";
 import { registerGetAddressTool } from "./getAddress";
 import { registerPurchaseListingTool } from "./purchaseListing";
 import { registerSendToAddressTool } from "./sendToAddress";
-import { Utils } from "@bsv/sdk";
+import { Utils, type WalletProtocol } from "@bsv/sdk";
 
 // Define mapping from tool names to argument schemas
 type ToolArgSchemas = {
@@ -177,24 +177,18 @@ export function registerWalletTools(
 		"Combined tool for encrypting and decrypting data using the wallet's cryptographic keys.\n\n" +
 		"PARAMETERS:\n" +
 		"- mode: (required) Either \"encrypt\" to encrypt plaintext or \"decrypt\" to decrypt ciphertext\n" +
-		"- data: (required) Text string or array of numbers to process (plaintext for encryption or ciphertext for decryption)\n" +
-		"- encoding: (optional) For text input, the encoding format (utf8, hex, base64) - default is utf8\n" +
-		"- protocolID: (required) Protocol identifier - common values are 'aes' for symmetric encryption or 'ecies' for asymmetric encryption\n" +
-		"- keyID: (required) Key identifier - use 'default' or 'primary' for the default wallet key\n\n" +
+		"- data: (required) Text string or array of numbers to process\n" +
+		"- encoding: (optional) For text input, the encoding format (utf8, hex, base64) - default is utf8\n\n" +
 		"EXAMPLES:\n" +
 		"1. Encrypt text data:\n" +
 		"   {\n" +
 		"     \"mode\": \"encrypt\",\n" +
-		"     \"data\": \"Hello World\",\n" +
-		"     \"protocolID\": [1, \"aes\"],\n" +
-		"     \"keyID\": \"default\"\n" +
+		"     \"data\": \"Hello World\"\n" +
 		"   }\n\n" +
 		"2. Decrypt previously encrypted data:\n" +
 		"   {\n" +
 		"     \"mode\": \"decrypt\",\n" +
-		"     \"data\": [encrypted bytes from previous response],\n" +
-		"     \"protocolID\": [1, \"aes\"],\n" +
-		"     \"keyID\": \"default\"\n" +
+		"     \"data\": [encrypted bytes from previous response]\n" +
 		"   }",
 		{ args: walletEncryptionArgsSchema },
 		async (
@@ -202,7 +196,11 @@ export function registerWalletTools(
 			extra: RequestHandlerExtra,
 		) => {
 			try {
-				const { mode, data, protocolID, keyID, encoding } = args;
+				const { mode, data, encoding } = args;
+				
+				// Set default values for required parameters
+				const protocolID: WalletProtocol = [1, "aes256"];
+				const keyID = "default";
 				
 				// Convert string data to binary if needed
 				let binaryData: number[];
@@ -214,7 +212,7 @@ export function registerWalletTools(
 					binaryData = toArray(data, encoding || "utf8");
 				}
 				
-				let result: { ciphertext?: number[]; plaintext?: number[] } = {};
+				let result: { ciphertext?: number[]; plaintext?: number[] | string } = {};
 				if (mode === "encrypt") {
 					result = await wallet.encrypt({
 						plaintext: binaryData,
@@ -229,10 +227,10 @@ export function registerWalletTools(
 					});
 					
 					// For decryption, convert plaintext back to string if it's likely UTF-8 text
-					if (result.plaintext) {
+					if (result.plaintext as number[]) {
 						try {
 							const { toUTF8 } = Utils;
-							const textResult = toUTF8(result.plaintext);
+							const textResult = toUTF8(result.plaintext as number[]);
 							// If conversion succeeds and seems like valid text, return as string
 							if (textResult && textResult.length > 0) {
 								return {