bsv-mcp 0.0.14 → 0.0.16

package/README.md

@@ -177,7 +177,7 @@ General-purpose utility functions:
 
 | Tool Name | Description | Example Output |
 |-----------|-------------|----------------|
-| `utils_convertData` | Converts data between different encodings (utf8, hex, base64, binary) | `68656c6c6f20776f726c64` (UTF-8 "hello world" converted to hex) |
+| `utils_convertData` | Converts data between different encoding formats (utf8, hex, base64, binary).<br><br>**Parameters:**<br>- `data` (required): The string to convert<br>- `from` (required): Source encoding format (utf8, hex, base64, or binary)<br>- `to` (required): Target encoding format (utf8, hex, base64, or binary)<br><br>**Examples:**<br>- UTF-8 to hex: `{"data": "hello world", "from": "utf8", "to": "hex"}` → `68656c6c6f20776f726c64`<br>- UTF-8 to base64: `{"data": "Hello World", "from": "utf8", "to": "base64"}` → `SGVsbG8gV29ybGQ=`<br>- base64 to UTF-8: `{"data": "SGVsbG8gV29ybGQ=", "from": "base64", "to": "utf8"}` → `Hello World`<br>- hex to base64: `{"data": "68656c6c6f20776f726c64", "from": "hex", "to": "base64"}` → `aGVsbG8gd29ybGQ=`<br><br>**Notes:**<br>- All parameters are required<br>- The tool returns the converted data as a string<br>- For binary conversion, data is represented as an array of byte values | `"SGVsbG8gV29ybGQ="` (UTF-8 "Hello World" converted to base64) |
 
 ## Using the Tools with MCP
 
@@ -266,6 +266,7 @@ 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}}` |
 
 #### Transaction Data
 | Endpoint | Description | Required Parameters | Example Response |
@@ -292,6 +293,7 @@ The `bsv_explore` tool can be used with natural language prompts like:
 ```
 "Get the current Bitcoin SV blockchain information"
 "Show me block #800000 details"
+"Get tag count statistics for block #800000"
 "Fetch transaction history for address 1ExampleBsvAddressXXXXXXXX"
 "Get unspent outputs for my wallet address"
 "Check transaction details for txid a1b2c3d4e5f6..."

package/index.ts

@@ -37,7 +37,7 @@ const privKey = validatePrivateKey();
 
 const server = new McpServer({
 	name: "Bitcoin SV MCP Server",
-	version: "0.0.14",
+	version: "0.0.16",
 });
 
 // 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.14",
+	"version": "0.0.16",
 	"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,6 +17,7 @@ enum ExploreEndpoint {
   // Block endpoints
   BLOCK_BY_HASH = "block_by_hash",
   BLOCK_BY_HEIGHT = "block_by_height",
+  TAG_COUNT_BY_HEIGHT = "tag_count_by_height",
   
   // Transaction endpoints
   TX_BY_HASH = "tx_by_hash",
@@ -65,7 +66,8 @@ export function registerExploreTool(server: McpServer): void {
     "- 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" +
+    "- 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" +
     "TRANSACTION DATA:\n" +
     "- tx_by_hash: Detailed transaction data (requires txHash parameter)\n" +
     "- tx_raw: Raw transaction hex data (requires txHash parameter)\n" +
@@ -86,8 +88,8 @@ export function registerExploreTool(server: McpServer): void {
           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 ((params.endpoint === ExploreEndpoint.BLOCK_BY_HEIGHT || params.endpoint === ExploreEndpoint.TAG_COUNT_BY_HEIGHT) && params.blockHeight === undefined) {
+          throw new Error("blockHeight is required for block_by_height and tag_count_by_height endpoints");
         }
 
         if ([ExploreEndpoint.TX_BY_HASH, ExploreEndpoint.TX_RAW, ExploreEndpoint.TX_RECEIPT].includes(params.endpoint) && !params.txHash) {
@@ -120,6 +122,9 @@ export function registerExploreTool(server: McpServer): void {
           case ExploreEndpoint.BLOCK_BY_HEIGHT:
             apiUrl += `/block/height/${params.blockHeight}`;
             break;
+          case ExploreEndpoint.TAG_COUNT_BY_HEIGHT:
+            apiUrl += `/block/tagcount/height/${params.blockHeight}/stats`;
+            break;
           case ExploreEndpoint.TX_BY_HASH:
             apiUrl += `/tx/hash/${params.txHash}`;
             break;

package/tools/utils/index.ts

@@ -11,7 +11,20 @@ const encodingSchema = z.enum(["utf8", "hex", "base64", "binary"]);
 export function registerUtilsTools(server: McpServer): void {
 	server.tool(
 		"utils_convertData",
-		"Converts data between different encodings (utf8, hex, base64, binary). Useful for transforming data formats when working with blockchain data, encryption, or file processing.",
+		"Converts data between different encodings (utf8, hex, base64, binary). Useful for transforming data formats when working with blockchain data, encryption, or file processing.\n\n" +
+		"Parameters:\n" +
+		"- data (required): The string to convert\n" +
+		"- from (required): Source encoding format (utf8, hex, base64, or binary)\n" +
+		"- to (required): Target encoding format (utf8, hex, base64, or binary)\n\n" +
+		"Example usage:\n" +
+		"- UTF-8 to hex: {\"data\": \"hello world\", \"from\": \"utf8\", \"to\": \"hex\"} → 68656c6c6f20776f726c64\n" +
+		"- UTF-8 to base64: {\"data\": \"Hello World\", \"from\": \"utf8\", \"to\": \"base64\"} → SGVsbG8gV29ybGQ=\n" +
+		"- base64 to UTF-8: {\"data\": \"SGVsbG8gV29ybGQ=\", \"from\": \"base64\", \"to\": \"utf8\"} → Hello World\n" +
+		"- hex to base64: {\"data\": \"68656c6c6f20776f726c64\", \"from\": \"hex\", \"to\": \"base64\"} → aGVsbG8gd29ybGQ=\n\n" +
+		"Notes:\n" +
+		"- All parameters are required\n" +
+		"- The tool returns the converted data as a string\n" +
+		"- For binary conversion, data is represented as an array of byte values",
 		{
 			args: z.object({
 				data: z.string().describe("The data string to be converted"),

package/tools/wallet/schemas.ts

@@ -76,14 +76,15 @@ export const walletDecryptArgsSchema = z.object({
 export const walletEncryptionArgsSchema = z.object({
 	mode: z.enum(["encrypt", "decrypt"]).describe("Operation mode: 'encrypt' to encrypt data or 'decrypt' to decrypt data"),
 	data: z.array(z.number()).describe("Data to process: plaintext for encryption or ciphertext for decryption"),
-	protocolID: walletProtocolSchema,
-	keyID: z.string(),
-	privilegedReason: z.string().optional(),
+	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(),
-	privileged: z.boolean().optional(),
-}).describe("Combined schema for encryption and decryption operations, with a mode parameter to switch between functions");
+		.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.");
 
 // Create HMAC arguments
 export const createHmacArgsSchema = z.object({

package/tools/wallet/tools.ts

@@ -173,7 +173,29 @@ export function registerWalletTools(
 	// Register combined wallet_encryption tool
 	registerTool(
 		"wallet_encryption",
-		"Combined tool for encrypting and decrypting data using the wallet's cryptographic keys. Supports both encryption of plaintext data and decryption of previously encrypted content. Use the 'mode' parameter to switch between operations.",
+		"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) Array of byte values to process (plaintext for encryption or ciphertext for decryption)\n" +
+		"- protocolID: (required) Protocol to use (commonly \"aes\" or \"ecies\")\n" +
+		"- keyID: (required) Key identifier (use \"default\" or \"primary\" for default wallet key)\n" +
+		"- counterparty: (optional) Set to \"self\" for personal encryption or specific key for recipient\n" +
+		"- privileged: (optional) Boolean indicating if operation requires elevated privileges\n\n" +
+		"EXAMPLES:\n" +
+		"1. Encrypt data:\n" +
+		"   {\n" +
+		"     \"mode\": \"encrypt\",\n" +
+		"     \"data\": [84, 104, 105, 115, 32, 105, 115, 32, 116, 101, 115, 116],\n" +
+		"     \"protocolID\": \"aes\",\n" +
+		"     \"keyID\": \"default\"\n" +
+		"   }\n\n" +
+		"2. Decrypt previously encrypted data:\n" +
+		"   {\n" +
+		"     \"mode\": \"decrypt\",\n" +
+		"     \"data\": [encrypted bytes from previous response],\n" +
+		"     \"protocolID\": \"aes\",\n" +
+		"     \"keyID\": \"default\"\n" +
+		"   }",
 		{ args: walletEncryptionArgsSchema },
 		async (
 			{ args }: { args: z.infer<typeof walletEncryptionArgsSchema> },