bsv-mcp 0.0.33 → 0.0.35

package/CHANGELOG.md

@@ -1,10 +1,38 @@
 # BSV MCP Server Changelog
 
+## v0.0.35 - A2B Overlay Integration & Improved MCP Server Publishing
+
+### Features
+- **A2B Overlay Integration**: Implemented a robust connection to the A2B Overlay API
+  - Updated `a2b_discover` tool to search for on-chain MCP servers and agents
+  - Enhanced search capabilities with relevance-based result ranking
+  - User-friendly formatted output with command suggestions
+  - Support for filtering by type (agent/tool/all), block range, and free text search
+- **Improved MCP Server Publishing**: Enhanced the wallet_a2bPublishMcp tool
+  - Better identity key integration via LocalSigner
+  - More robust configuration for sigma signing
+  - Improved transaction handling and error reporting
+
+### Technical Improvements
+- Updated API endpoint to use production overlay service
+- Implemented enhanced search for better relevance scoring
+- Better error handling for API responses
+- Improved response formatting for readability
+- Updated type definitions for consistency
+
+## v0.0.34 - Transaction Broadcast Control
+
+### Features
+- Added `DISABLE_BROADCASTING` environment variable to control transaction broadcasting behavior
+  - When set to "true", transactions are created but not broadcast to the network
+  - Returns raw transaction hex instead of broadcasting, useful for testing and review
+- Code cleanup and organization improvements
+
 ## v0.0.33 - Identity Key Sigma Signing
 
 ### Features
 - Added optional `IDENTITY_KEY_WIF` environment variable for sigma-protocol signing.
-- `wallet_a2bPublishMcp`, `wallet_createOrdinals`, and `wallet_purchaseListing` tools now support signing with an identity key.
+-  `wallet_createOrdinals`, and `wallet_purchaseListing` tools now support signing with an identity key.
 - Updated `README.md` to document `IDENTITY_KEY_WIF` usage and JSON configuration examples.
 
 ## v0.0.32 - Reliability Improvements

package/README.md

@@ -365,6 +365,7 @@ The BSV MCP server can be customized using environment variables to enable or di
 | `DISABLE_ORDINALS_TOOLS` | `false` | Set to `true` to disable Ordinals/NFT tools |
 | `DISABLE_UTILS_TOOLS` | `false` | Set to `true` to disable utility tools |
 | `IDENTITY_KEY_WIF`    | `not set` | Optional WIF for identity key; if set, ordinals inscriptions will be signed with sigma-protocol for authentication, curation, and web-of-trust. |
+| `DISABLE_BROADCASTING` | `false` | Set to `true` to disable transaction broadcasting; returns raw transaction hex instead - useful for testing and transaction review before broadcasting |
 
 ### Examples
 
@@ -386,6 +387,12 @@ Use all tools except wallet operations:
 DISABLE_WALLET_TOOLS=true bunx bsv-mcp@latest
 ```
 
+Create transactions without broadcasting them (dry-run mode):
+
+```bash
+DISABLE_BROADCASTING=true bunx bsv-mcp@latest
+```
+
 ## Troubleshooting
 
 If you're having issues with the BSV MCP server:
@@ -427,6 +434,7 @@ For Cursor, check the Cursor MCP logs in Settings → Extensions → Model Conte
 
 ## Recent Updates
 
+- **Transaction Broadcast Control**: Added `DISABLE_BROADCASTING` environment variable to prevent transactions from being broadcast to the network
 - **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

package/index.ts

@@ -24,7 +24,10 @@ const CONFIG = {
 	loadBsvTools: process.env.DISABLE_BSV_TOOLS !== "true",
 	loadOrdinalsTools: process.env.DISABLE_ORDINALS_TOOLS !== "true",
 	loadUtilsTools: process.env.DISABLE_UTILS_TOOLS !== "true",
-	loadA2bTools: process.env.DISABLE_A2B_TOOLS !== "true",
+	loadA2bTools: process.env.ENABLE_A2B_TOOLS === "true",
+
+	// Transaction broadcasting control
+	disableBroadcasting: process.env.DISABLE_BROADCASTING === "true",
 };
 
 /**
@@ -70,7 +73,7 @@ function initializePrivateKey(): PrivateKey | undefined {
 const privKey = initializePrivateKey();
 
 const server = new McpServer(
-	{ name: "Bitcoin SV", version: "0.0.33" },
+	{ name: "Bitcoin SV", version: "0.0.35" },
 	// {
 	// 	// Advertise only what you actually implement
 	// 	capabilities: {
@@ -102,7 +105,10 @@ if (CONFIG.loadTools) {
 		// Initialize wallet with the private key if wallet tools are enabled
 		if (CONFIG.loadWalletTools) {
 			wallet = new Wallet(privKey);
-			registerWalletTools(server, wallet);
+			registerWalletTools(server, wallet, {
+				disableBroadcasting: CONFIG.disableBroadcasting,
+				enableA2bTools: CONFIG.loadA2bTools,
+			});
 		}
 	}
 

package/package.json

@@ -2,7 +2,7 @@
 	"name": "bsv-mcp",
 	"module": "index.ts",
 	"type": "module",
-	"version": "0.0.33",
+	"version": "0.0.35",
 	"license": "MIT",
 	"author": "satchmo",
 	"description": "A collection of Bitcoin SV (BSV) tools for the Model Context Protocol (MCP) framework",
@@ -14,11 +14,12 @@
 		"bitcoin",
 		"bsv",
 		"bitcoin-sv",
-		"mcp",
-		"model-context-protocol",
 		"wallet",
 		"ordinals",
-		"blockchain"
+		"blockchain",
+		"1sat-ordinals",
+		"explorer",
+		"block explorer"
 	],
 	"files": [
 		"package.json",

package/resources/junglebus.ts

@@ -0,0 +1,242 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// Main JungleBus API documentation URL
+const JUNGLEBUS_DOCS_URL = "https://junglebus.gorillapool.io/docs/";
+
+/**
+ * Manually structured JungleBus API documentation
+ * Provides a clean summary of key JungleBus API endpoints and functionality
+ */
+export function getJungleBusDocumentation(): string {
+	return `# JungleBus API Documentation
+
+## Overview
+
+JungleBus is a transaction monitoring service for Bitcoin SV that allows applications to subscribe to transaction events and filter them based on specific criteria. The API provides both subscription and querying capabilities.
+
+## API Endpoints
+
+### Base URL
+\`\`\`
+https://junglebus.gorillapool.io/v1
+\`\`\`
+
+### Transaction API
+
+#### Get Transaction by ID
+\`\`\`
+GET /transaction/get/{txid}
+\`\`\`
+
+Returns detailed information about a specific transaction, including:
+- Transaction data (hex format)
+- Block information (hash, height, time)
+- Input and output details
+- Address information
+
+#### Get Transactions by Block Hash
+\`\`\`
+GET /block/{blockhash}/transactions
+\`\`\`
+
+Returns all transactions within a specific block.
+
+### Subscription API
+
+#### Create Subscription
+\`\`\`
+POST /subscribe
+\`\`\`
+
+Create a new subscription to monitor transactions based on filtering criteria.
+
+Example request body:
+\`\`\`json
+{
+  "callback": "https://your-callback-url.com",
+  "fromBlock": 0,
+  "query": {
+    "find": {
+      "out.tape.cell.s": "BEEF"
+    }
+  }
+}
+\`\`\`
+
+#### Delete Subscription
+\`\`\`
+DELETE /subscribe/{id}
+\`\`\`
+
+Deletes an existing subscription.
+
+### Network API
+
+#### Get Network Info
+\`\`\`
+GET /network/info
+\`\`\`
+
+Returns current blockchain network information, including block height and other statistics.
+
+## Client Implementations
+
+### TypeScript Client
+
+Installation:
+\`\`\`bash
+$ npm install @gorillapool/js-junglebus
+\`\`\`
+
+Usage:
+\`\`\`javascript
+import { JungleBusClient } from '@gorillapool/js-junglebus';
+
+const server = "junglebus.gorillapool.io";
+const jungleBusClient = new JungleBusClient(server, {
+  onConnected(ctx) {
+    // add your own code here
+    console.log(ctx);
+  },
+  onConnecting(ctx) {
+    // add your own code here
+    console.log(ctx);
+  },
+  onDisconnected(ctx) {
+    // add your own code here
+    console.log(ctx);
+  },
+  onError(ctx) {
+    // add your own code here
+    console.error(ctx);
+  }
+});
+
+// create subscriptions in the dashboard of the JungleBus website
+const subId = "...."; // fill in the ID for the subscription
+const fromBlock = 750000;
+
+const subscription = jungleBusClient.Subscribe(
+  subId,
+  fromBlock,
+  onPublish(tx) => {
+    // add your own code here
+    console.log(tx);
+  },
+  onStatus(ctx) => {
+    // add your own code here
+    console.log(ctx);
+  },
+  onError(ctx) => {
+    // add your own code here
+    console.log(ctx);
+  },
+  onMempool(tx) => {
+    // add your own code here
+    console.log(tx);
+  }
+);
+
+// For lite mode (transaction hash and block height only)
+await client.Subscribe("a5e2fa655c41753331539a2a86546bf9335ff6d9b7a512dc9acddb00ab9985c0", 1550000, onPublish, onStatus, onError, onMempool, true);
+\`\`\`
+
+### Go Client
+
+Installation:
+\`\`\`bash
+go get github.com/GorillaPool/go-junglebus
+\`\`\`
+
+Usage:
+\`\`\`go
+package main
+
+import (
+  "context"
+  "log"
+  "sync"
+  "github.com/GorillaPool/go-junglebus"
+  "github.com/GorillaPool/go-junglebus/models"
+)
+
+func main() {
+  wg := &sync.WaitGroup{}
+  
+  junglebusClient, err := junglebus.New(
+    junglebus.WithHTTP("https://junglebus.gorillapool.io"),
+  )
+  if err != nil {
+    log.Fatalln(err.Error())
+  }
+  
+  subscriptionID := "..." // fill in the ID for the subscription
+  fromBlock := uint64(750000)
+  
+  eventHandler := junglebus.EventHandler{
+    // do not set this function to leave out mined transactions
+    OnTransaction: func(tx *models.TransactionResponse) {
+      log.Printf("[TX]: %d: %v", tx.BlockHeight, tx.Id)
+    },
+    // do not set this function to leave out mempool transactions
+    OnMempool: func(tx *models.TransactionResponse) {
+      log.Printf("[MEMPOOL TX]: %v", tx.Id)
+    },
+    OnStatus: func(status *models.ControlResponse) {
+      log.Printf("[STATUS]: %v", status)
+    },
+    OnError: func(err error) {
+      log.Printf("[ERROR]: %v", err)
+    },
+  }
+  
+  var subscription *junglebus.Subscription
+  if subscription, err = junglebusClient.Subscribe(context.Background(), subscriptionID, fromBlock, eventHandler); err != nil {
+    log.Printf("ERROR: failed getting subscription %s", err.Error())
+  }
+  
+  // For lite mode
+  if subscription, err := junglebusClient.SubscribeWithQueue(context.Background(), subscriptionID, fromBlock, 0, eventHandler, &junglebus.SubscribeOptions{
+    QueueSize: 100000,
+    LiteMode: true,
+  }); err != nil {
+    log.Printf("ERROR: failed getting subscription %s", err.Error())
+  }
+  
+  wg.Add(1)
+  wg.Wait()
+}
+\`\`\`
+
+## Further Reading
+
+For complete API documentation, visit [JungleBus Docs](${JUNGLEBUS_DOCS_URL})
+`;
+}
+
+/**
+ * Register the JungleBus API documentation resource with the MCP server
+ * @param server The MCP server instance
+ */
+export function registerJungleBusResource(server: McpServer): void {
+	server.resource(
+		"junglebus-api-docs",
+		JUNGLEBUS_DOCS_URL,
+		{
+			title: "JungleBus API Documentation",
+			description:
+				"API documentation for JungleBus, a transaction monitoring service for Bitcoin SV",
+		},
+		async (uri) => {
+			const documentationContent = getJungleBusDocumentation();
+			return {
+				contents: [
+					{
+						uri: uri.href,
+						text: documentationContent,
+					},
+				],
+			};
+		},
+	);
+}

package/resources/resources.ts

@@ -1,6 +1,7 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { registerBRCsResources } from "./brcs";
 import { registerChangelogResource } from "./changelog";
+import { registerJungleBusResource } from "./junglebus";
 
 /**
  * Register all resources with the MCP server
@@ -13,5 +14,8 @@ export function registerResources(server: McpServer): void {
 	// Register changelog resource
 	registerChangelogResource(server);
 
+	// Register JungleBus API documentation resource
+	registerJungleBusResource(server);
+
 	// Add more resource categories here as needed
 }

package/tools/a2b/discover.ts

@@ -6,25 +6,34 @@ import type {
 } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 
-type OverlayRequest = {
+// API endpoint for the A2B Overlay service
+const OVERLAY_API_URL = "https://a2b-overlay-production.up.railway.app/v1";
+
+type A2BDiscoveryItem = {
+	txid: string;
+	outpoint: string;
 	type: "agent" | "tool";
-	query: string;
-	limit: number;
-	offset: number;
-	fromBlock?: number;
-	toBlock?: number;
+	app: string;
+	serverName: string;
+	command: string;
+	description: string;
+	keywords: string[];
+	args: Record<string, string>;
+	env: Record<string, string>;
+	blockHeight: number;
+	timestamp: string;
+	tools?: string[];
+	prompts?: string[];
+	resources?: string[];
 };
 
-type OverlayResponse = {
-	agents: {
-		name: string;
-		description: string;
-		capabilities: string[];
-	}[];
-	tools: {
-		name: string;
-		description: string;
-	}[];
+type OverlaySearchResponse = {
+	items: A2BDiscoveryItem[];
+	total: number;
+	limit: number;
+	offset: number;
+	queryType: "agent" | "tool" | "all";
+	query: string;
 };
 
 // Schema for agent discovery parameters
@@ -38,6 +47,73 @@ export const a2bDiscoverArgsSchema = z.object({
 });
 export type A2bDiscoverArgs = z.infer<typeof a2bDiscoverArgsSchema>;
 
+/**
+ * Format the response in a user-friendly way
+ */
+function formatSearchResults(data: unknown, queryType: string): string {
+	// console.log(`Received data: ${JSON.stringify(data).substring(0, 200)}...`); // Debug log
+
+	// Check if data is an object with items property
+	if (!data) {
+		return `No ${queryType} results found.`;
+	}
+
+	// Handle the new API format where data is an object with 'items' array
+	const items = Array.isArray(data)
+		? data
+		: (data as { items?: A2BDiscoveryItem[] }).items;
+
+	// Ensure items is an array
+	if (!items || !Array.isArray(items) || items.length === 0) {
+		return `No ${queryType} results found.`;
+	}
+
+	let result = `Found ${items.length} ${queryType === "all" ? "items" : `${queryType}s`}:\n\n`;
+
+	items.forEach((item, index) => {
+		if (!item) return;
+
+		// Agent or MCP server name with description
+		result += `${index + 1}. **${item.serverName || "Unknown"}** - ${item.description || "No description"}\n`;
+
+		// Display command to run
+		if (item.command) {
+			const args = item.args ? Object.values(item.args).join(" ") : "";
+			result += `   Command: \`${item.command} ${args}\`\n`;
+		}
+
+		// Add tools count if available
+		if (item.tools && Array.isArray(item.tools)) {
+			result += `   Tools: ${item.tools.length} available\n`;
+		}
+
+		// Add keywords if available
+		if (
+			item.keywords &&
+			Array.isArray(item.keywords) &&
+			item.keywords.length > 0
+		) {
+			result += `   Keywords: ${item.keywords.join(", ")}\n`;
+		}
+
+		// Add blockchain details
+		if (item.outpoint) {
+			result += `   Outpoint: ${item.outpoint}\n`;
+		}
+
+		if (item.blockHeight !== undefined) {
+			const date = item.timestamp
+				? new Date(item.timestamp).toLocaleDateString()
+				: "Unknown date";
+			result += `   Block: ${item.blockHeight}, ${date}\n`;
+		}
+
+		result += "\n";
+	});
+
+	return result;
+}
+
 /**
  * Registers the a2b_discover tool for on-chain agent discovery
  */
@@ -50,49 +126,113 @@ export function registerA2bDiscoverTool(server: McpServer) {
 			{ args }: { args: A2bDiscoverArgs },
 			extra: RequestHandlerExtra<ServerRequest, ServerNotification>,
 		) => {
-			if (args.queryType === "agent") {
-				return {
-					content: [
-						{ type: "text", text: "Agent discovery is not supported yet" },
-					],
-					isError: true,
-				};
-			}
-
-			if (args.queryType !== "tool") {
-				return {
-					content: [
-						{
-							type: "text",
-							text: "Only tool discovery is supported currently",
-						},
-					],
-					isError: true,
-				};
-			}
-
 			try {
 				const params = new URLSearchParams();
+
+				// Set query type (agent, tool, or all)
 				params.set("type", args.queryType);
-				params.set("query", args.query);
-				params.set("limit", args.limit?.toString() ?? "5");
+
+				// Use enhanced search for better relevance scoring
+				let searchEndpoint = "/search/enhanced";
+
+				// For empty queries, use the regular search endpoint
+				if (!args.query || !args.query.trim()) {
+					searchEndpoint = "/search";
+				} else {
+					params.set("q", args.query); // enhanced search uses 'q' parameter
+				}
+
+				// Add pagination parameters
+				params.set("limit", args.limit?.toString() ?? "10");
 				params.set("offset", args.offset?.toString() ?? "0");
+
+				// Add block range if specified
 				if (args.fromBlock) {
 					params.set("fromBlock", args.fromBlock.toString());
 				}
 				if (args.toBlock) {
 					params.set("toBlock", args.toBlock.toString());
 				}
-				const OVERLAY_URL = `https://overlay.a2b.network/v1/search?${params.toString()}`;
-				const response = await fetch(OVERLAY_URL);
-				const data = (await response.json()) as OverlayResponse;
+
+				// Construct the full URL
+				const searchUrl = `${OVERLAY_API_URL}${searchEndpoint}?${params.toString()}`;
+				//console.log(`Searching URL: ${searchUrl}`);
+
+				// Make the request to the overlay API
+				const response = await fetch(searchUrl, {
+					method: "GET",
+					headers: {
+						Accept: "application/json",
+					},
+				});
+
+				if (!response.ok) {
+					throw new Error(
+						`API returned status ${response.status}: ${response.statusText}`,
+					);
+				}
+
+				const data = (await response.json()) as OverlaySearchResponse;
+
+				// Format the results for better readability
+				let result = "";
+
+				if (data?.items?.length > 0) {
+					result = `Found ${data.items.length} ${args.queryType}(s):\n\n`;
+
+					data.items.forEach((item: A2BDiscoveryItem, index: number) => {
+						// Server name and description
+						result += `${index + 1}. **${item.serverName || "Unknown"}** - ${item.description || "No description"}\n`;
+
+						// Command to run
+						if (item.command) {
+							const cmdArgs = item.args
+								? Object.values(item.args).join(" ")
+								: "";
+							result += `   Command: \`${item.command} ${cmdArgs}\`\n`;
+						}
+
+						// Tools available
+						if (item.tools?.length) {
+							result += `   Tools: ${item.tools.length} available\n`;
+						}
+
+						// Keywords
+						if (item.keywords?.length) {
+							result += `   Keywords: ${item.keywords.join(", ")}\n`;
+						}
+
+						// Blockchain details
+						if (item.outpoint) {
+							result += `   Outpoint: ${item.outpoint}\n`;
+						}
+
+						if (item.blockHeight !== undefined) {
+							const date = item.timestamp
+								? new Date(item.timestamp).toLocaleDateString()
+								: "Unknown date";
+							result += `   Block: ${item.blockHeight}, ${date}\n`;
+						}
+
+						result += "\n";
+					});
+				} else {
+					result = `No ${args.queryType} results found.`;
+				}
+
 				return {
-					content: [{ type: "text", text: JSON.stringify(data) }],
+					content: [{ type: "text", text: result }],
 					isError: false,
 				};
 			} catch (error) {
+				console.error("Search error:", error);
 				return {
-					content: [{ type: "text", text: `Error querying overlay: ${error}` }],
+					content: [
+						{
+							type: "text",
+							text: `Error querying A2B Overlay: ${error instanceof Error ? error.message : String(error)}`,
+						},
+					],
 					isError: true,
 				};
 			}

package/tools/index.ts

@@ -32,14 +32,14 @@ export function registerAllTools(
 		enableBsvTools: true,
 		enableOrdinalsTools: true,
 		enableUtilsTools: true,
-		enableA2bTools: true,
+		enableA2bTools: false,
 	},
 ): void {
 	const {
 		enableBsvTools = true,
 		enableOrdinalsTools = true,
 		enableUtilsTools = true,
-		enableA2bTools = true,
+		enableA2bTools = false,
 	} = config;
 
 	// Register BSV-related tools