bsv-mcp 0.0.18 → 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.18",
+	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.18",
+	"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();