bsv-mcp 0.0.36 → 0.2.7

package/tools/utils/index.ts

@@ -1,14 +1,50 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { convertData } from "./conversion";
+import { installAgentMasterTool } from "./installAgentMaster";
 
 const encodingSchema = z.enum(["utf8", "hex", "base64", "binary"]);
 
 /**
- * Register the unified conversion tool with the MCP server
+ * Register utility tools with the MCP server
  * @param server The MCP server instance
  */
 export function registerUtilsTools(server: McpServer): void {
+	// Register install agent master tool
+	server.tool(
+		installAgentMasterTool.name,
+		installAgentMasterTool.description,
+		{ ...installAgentMasterTool.inputSchema.shape },
+		async (params) => {
+			try {
+				const result = await installAgentMasterTool.handler(params);
+				return {
+					content: [
+						{
+							type: "text",
+							text:
+								typeof result === "string"
+									? result
+									: JSON.stringify(result, null, 2),
+						},
+					],
+				};
+			} catch (err: unknown) {
+				const msg = err instanceof Error ? err.message : String(err);
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Error: ${msg}`,
+						},
+					],
+					isError: true,
+				};
+			}
+		},
+	);
+
+	// Register conversion tool
 	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.\n\n" +
@@ -26,22 +62,20 @@ export function registerUtilsTools(server: McpServer): void {
 			"- 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"),
-				from: encodingSchema.describe(
-					"Source encoding format (utf8, hex, base64, or binary)",
-				),
-				to: encodingSchema.describe(
-					"Target encoding format to convert to (utf8, hex, base64, or binary)",
-				),
-			}),
+			data: z.string().describe("The data string to be converted"),
+			from: encodingSchema.describe(
+				"Source encoding format (utf8, hex, base64, or binary)",
+			),
+			to: encodingSchema.describe(
+				"Target encoding format to convert to (utf8, hex, base64, or binary)",
+			),
 		},
-		async ({ args }) => {
+		async ({ data, from, to }) => {
 			try {
 				const result = convertData({
-					data: args.data,
-					from: args.from,
-					to: args.to,
+					data,
+					from,
+					to,
 				});
 				return {
 					content: [
@@ -66,3 +100,11 @@ export function registerUtilsTools(server: McpServer): void {
 		},
 	);
 }
+
+export * from "./aip";
+// Export all utilities for use by other tools
+export * from "./errorHandler";
+export * from "./logger";
+export * from "./toolConfig";
+export * from "./toolRegistration";
+export * from "./transactionBuilder";

package/tools/utils/installAgentMaster.ts

@@ -0,0 +1,84 @@
+import { spawn } from "node:child_process";
+import { platform } from "node:os";
+import { z } from "zod";
+
+const installAgentMasterSchema = z.object({
+	method: z
+		.enum(["go", "source", "auto"])
+		.optional()
+		.describe("Installation method"),
+});
+
+/**
+ * Install the Agent Master CLI tool for managing MCP server configurations
+ */
+export async function installAgentMaster(
+	args: z.infer<typeof installAgentMasterSchema>,
+) {
+	const method = args.method || "auto";
+
+	return new Promise((resolve, reject) => {
+		let command: string;
+		let commandArgs: string[] = [];
+
+		if (method === "auto" || method === "go") {
+			// Try go install first
+			command = "go";
+			commandArgs = ["install", "github.com/b-open-io/agent-master-cli@latest"];
+		} else if (method === "source") {
+			// Install from source
+			reject(
+				new Error(
+					"Source installation requires manual steps. Please run:\ngit clone https://github.com/b-open-io/agent-master-cli.git\ncd agent-master-cli\nmake deps && make build && make install",
+				),
+			);
+			return;
+		}
+
+		console.error(`🔧 Installing Agent Master CLI using ${method} method...`);
+
+		const install = spawn(command, commandArgs, {
+			stdio: "inherit",
+			shell: true,
+		});
+
+		install.on("error", (error) => {
+			if (method === "auto" && command === "go") {
+				// If go install fails in auto mode, provide instructions
+				reject(
+					new Error(
+						"Go installation failed. Please ensure Go is installed or try manual installation:\n\n1. Install Go from https://golang.org/dl/\n2. Run: go install github.com/b-open-io/agent-master-cli@latest\n\nOr install from source:\ngit clone https://github.com/b-open-io/agent-master-cli.git\ncd agent-master-cli\nmake deps && make build && make install",
+					),
+				);
+			} else {
+				reject(error);
+			}
+		});
+
+		install.on("close", (code) => {
+			if (code !== 0) {
+				reject(new Error(`Installation failed with code ${code}`));
+			} else {
+				resolve({
+					success: true,
+					message:
+						"✅ Agent Master CLI installed successfully!\n\nGet started with:\n  agent-master init --with-demo\n  agent-master list\n  agent-master sync --preset claude",
+					nextSteps: [
+						"Initialize configuration: agent-master init --with-demo",
+						"List servers: agent-master list",
+						'Add BSV MCP: agent-master add bsv-mcp --transport stdio --command "bunx" --args "bsv-mcp@latest"',
+						"Sync to Claude: agent-master sync --preset claude",
+					],
+				});
+			}
+		});
+	});
+}
+
+export const installAgentMasterTool = {
+	name: "utils_installAgentMaster",
+	description:
+		"Install the Agent Master CLI tool for managing MCP server configurations across multiple platforms (Claude, VS Code, Cursor, etc.)",
+	inputSchema: installAgentMasterSchema,
+	handler: installAgentMaster,
+};

package/tools/utils/logger.ts

@@ -0,0 +1,20 @@
+/**
+ * Simple logger utility for consistent output formatting
+ */
+export const logger = {
+	info: (message: string) => console.error(`ℹ️ ${message}`),
+	success: (message: string) => console.error(`✅ ${message}`),
+	warn: (message: string) => console.error(`⚠️ ${message}`),
+	error: (message: string, error?: unknown) => {
+		if (error) {
+			console.error(`❌ ${message}:`, error);
+		} else {
+			console.error(`❌ ${message}`);
+		}
+	},
+	debug: (message: string, ...args: unknown[]) => {
+		if (process.env.DEBUG === "true") {
+			console.error(`🐛 ${message}`, ...args);
+		}
+	},
+};

package/tools/utils/toolConfig.ts

@@ -0,0 +1,80 @@
+/**
+ * Tool category configuration
+ */
+export interface ToolCategory {
+	name: string;
+	envVar: string;
+	defaultEnabled: boolean;
+	register: (server: unknown, config?: unknown) => void;
+	dependencies?: string[]; // Other categories this depends on
+}
+
+/**
+ * Check if a tool category is enabled based on environment and config
+ */
+export function isToolEnabled(
+	category: ToolCategory,
+	config: Record<string, boolean | undefined> = {},
+): boolean {
+	const configKey = `enable${category.name}Tools`;
+
+	// Check config override first
+	if (configKey in config && config[configKey] !== undefined) {
+		return config[configKey] as boolean;
+	}
+
+	// Check environment variable
+	const envValue = process.env[category.envVar];
+	if (envValue !== undefined) {
+		// For ENABLE_* vars, check if === "true"
+		// For DISABLE_* vars, check if !== "true"
+		if (category.envVar.startsWith("ENABLE_")) {
+			return envValue === "true";
+		}
+		return envValue !== "true";
+	}
+
+	// Return default
+	return category.defaultEnabled;
+}
+
+/**
+ * Register multiple tool categories with their dependencies
+ */
+export function registerToolCategories(
+	server: unknown,
+	categories: ToolCategory[],
+	config: Record<string, boolean | undefined> = {},
+): void {
+	const enabled: Set<string> = new Set();
+
+	// First pass: determine what's enabled
+	for (const category of categories) {
+		if (isToolEnabled(category, config)) {
+			enabled.add(category.name);
+		}
+	}
+
+	// Second pass: register enabled categories
+	for (const category of categories) {
+		if (enabled.has(category.name)) {
+			// Check dependencies
+			const missingDeps =
+				category.dependencies?.filter((dep) => !enabled.has(dep)) || [];
+			if (missingDeps.length > 0) {
+				console.warn(
+					`⚠️ ${category.name} tools not registered (missing dependencies: ${missingDeps.join(", ")})`,
+				);
+				continue;
+			}
+
+			// Register the category
+			try {
+				category.register(server, config);
+				console.error(`✅ Registered ${category.name} tools`);
+			} catch (error) {
+				console.error(`❌ Failed to register ${category.name} tools:`, error);
+			}
+		}
+	}
+}

package/tools/utils/toolRegistration.ts

@@ -0,0 +1,66 @@
+/**
+ * Common tool registration utilities for the BSV MCP server
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { z } from "zod";
+
+export interface ToolConfig<TArgs = Record<string, unknown>> {
+	name: string;
+	description: string;
+	schema: z.ZodSchema<TArgs>;
+	handler: (args: TArgs) => Promise<ToolResponse>;
+}
+
+export interface ToolResponse {
+	content: Array<{
+		type: "text";
+		text: string;
+	}>;
+	isError?: boolean;
+}
+
+/**
+ * Register a tool with standard error handling and response formatting
+ */
+export function registerTool<TArgs = Record<string, unknown>>(
+	server: McpServer,
+	config: ToolConfig<TArgs>,
+): void {
+	server.tool(config.name, config.schema, async (args: TArgs) => {
+		try {
+			return await config.handler(args);
+		} catch (error) {
+			return {
+				content: [
+					{
+						type: "text" as const,
+						text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+					},
+				],
+				isError: true,
+			};
+		}
+	});
+}
+
+/**
+ * Helper function to create a simple tool registration function
+ */
+export function createToolRegistration<TDeps = undefined>(
+	toolName: string,
+	description: string,
+	schema: z.ZodSchema<Record<string, unknown>>,
+	handler: (
+		args: Record<string, unknown>,
+		deps?: TDeps,
+	) => Promise<ToolResponse>,
+) {
+	return (server: McpServer, deps?: TDeps) => {
+		registerTool(server, {
+			name: toolName,
+			description,
+			schema,
+			handler: (args) => handler(args, deps),
+		});
+	};
+}

package/tools/utils/transactionBuilder.ts

@@ -0,0 +1,196 @@
+import {
+	isBroadcastFailure,
+	isBroadcastResponse,
+	P2PKH,
+	type PrivateKey,
+	Script,
+	Transaction,
+	Utils,
+} from "@bsv/sdk";
+import { V5Broadcaster } from "../../utils/broadcaster";
+import type { Utxo } from "../wallet/utxo";
+
+const DEFAULT_SAT_PER_BYTE = 0.05;
+const DUST_LIMIT = 546;
+
+interface TransactionBuilderConfig {
+	outputs: Array<{
+		script?: Script;
+		address?: string;
+		satoshis: number;
+	}>;
+	utxos: Utxo[];
+	changeAddress: string;
+	paymentKey: PrivateKey;
+	feePerByte?: number;
+}
+
+interface TransactionResult {
+	success: boolean;
+	txid?: string;
+	rawTx?: string;
+	error?: string;
+	fee?: number;
+}
+
+/**
+ * Build and optionally broadcast a transaction with automatic UTXO selection and fee calculation
+ */
+export async function buildAndSendTransaction(
+	config: TransactionBuilderConfig,
+	broadcast = true,
+): Promise<TransactionResult> {
+	const {
+		outputs,
+		utxos,
+		changeAddress,
+		paymentKey,
+		feePerByte = DEFAULT_SAT_PER_BYTE,
+	} = config;
+
+	if (!utxos || utxos.length === 0) {
+		return {
+			success: false,
+			error: "No UTXOs available to fund transaction",
+		};
+	}
+
+	const tx = new Transaction();
+	const p2pkh = new P2PKH();
+
+	// Add all outputs
+	for (const output of outputs) {
+		if (output.script) {
+			tx.addOutput({
+				lockingScript: output.script,
+				satoshis: output.satoshis,
+			});
+		} else if (output.address) {
+			tx.addOutput({
+				lockingScript: p2pkh.lock(output.address),
+				satoshis: output.satoshis,
+			});
+		}
+	}
+
+	// Calculate total output amount
+	const totalOutputSatoshis = outputs.reduce(
+		(sum, out) => sum + out.satoshis,
+		0,
+	);
+
+	// Select UTXOs and add inputs
+	let totalInputSatoshis = 0;
+	const selectedUtxos: Utxo[] = [];
+
+	// Sort UTXOs by value (ascending) to minimize the number of inputs
+	const sortedUtxos = [...utxos].sort((a, b) => a.satoshis - b.satoshis);
+
+	for (const utxo of sortedUtxos) {
+		selectedUtxos.push(utxo);
+		totalInputSatoshis += utxo.satoshis;
+
+		const input = {
+			sourceTransaction: utxo.tx,
+			sourceOutputIndex: utxo.vout,
+			unlockingScriptTemplate: p2pkh.unlock(paymentKey),
+		};
+		tx.addInput(input);
+
+		// Estimate fee with current inputs
+		const estimatedSize = tx.toHex().length / 2 + 150; // rough estimate for unsigned tx
+		const estimatedFee = Math.ceil(estimatedSize * feePerByte);
+
+		// Check if we have enough to cover outputs + fee + potential change
+		if (totalInputSatoshis >= totalOutputSatoshis + estimatedFee + DUST_LIMIT) {
+			break;
+		}
+	}
+
+	// Calculate final fee
+	const estimatedSize = tx.toHex().length / 2 + 35; // more accurate with all inputs
+	const fee = Math.ceil(estimatedSize * feePerByte);
+
+	// Check if we have enough funds
+	if (totalInputSatoshis < totalOutputSatoshis + fee) {
+		return {
+			success: false,
+			error: `Insufficient funds. Have ${totalInputSatoshis} sats, need ${totalOutputSatoshis + fee} sats`,
+		};
+	}
+
+	// Add change output if needed
+	const change = totalInputSatoshis - totalOutputSatoshis - fee;
+	if (change >= DUST_LIMIT) {
+		tx.addOutput({
+			lockingScript: p2pkh.lock(changeAddress),
+			satoshis: change,
+		});
+	}
+
+	// Sign the transaction
+	await tx.sign();
+
+	const rawTx = tx.toHex();
+	const txid = tx.id("hex") as string;
+
+	// Check if broadcasting is disabled
+	if (process.env.DISABLE_BROADCASTING === "true" || !broadcast) {
+		return {
+			success: true,
+			txid,
+			rawTx,
+			fee,
+		};
+	}
+
+	// Broadcast the transaction
+	try {
+		const broadcaster = new V5Broadcaster();
+		const broadcastResult = await tx.broadcast(broadcaster);
+
+		if (isBroadcastResponse(broadcastResult)) {
+			return {
+				success: true,
+				txid: broadcastResult.txid || txid,
+				rawTx,
+				fee,
+			};
+		}
+		if (isBroadcastFailure(broadcastResult)) {
+			return {
+				success: true,
+				txid,
+				rawTx,
+				fee,
+				error: `Transaction created but broadcast failed: ${broadcastResult.description}`,
+			};
+		}
+		return {
+			success: true,
+			txid,
+			rawTx,
+			fee,
+			error: "Transaction created but broadcast status uncertain",
+		};
+	} catch (error) {
+		return {
+			success: true,
+			txid,
+			rawTx,
+			fee,
+			error: `Transaction created but broadcast failed: ${error instanceof Error ? error.message : String(error)}`,
+		};
+	}
+}
+
+/**
+ * Build OP_RETURN script from data arrays
+ */
+export function buildOpReturnScript(dataArrays: Uint8Array[]): Script {
+	return new Script([
+		{ op: 0 }, // OP_0
+		{ op: 106 }, // OP_RETURN
+		...dataArrays.map((data) => ({ data })),
+	]);
+}

package/tools/wallet/a2bPublishAgent.ts

@@ -1,11 +1,5 @@
 import { PrivateKey, Utils } from "@bsv/sdk";
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
-import type {
-	ServerNotification,
-	ServerRequest,
-} from "@modelcontextprotocol/sdk/types.js";
-import { createOrdinals } from "js-1sat-ord";
 import type {
 	ChangeResult,
 	CreateOrdinalsConfig,
@@ -14,9 +8,12 @@ import type {
 	LocalSigner,
 	PreMAP,
 } from "js-1sat-ord";
-import { Sigma } from "sigma-protocol";
+import { createOrdinals } from "js-1sat-ord";
 import { z } from "zod";
+import packageJson from "../../package.json";
+import { V5Broadcaster } from "../../utils/broadcaster";
 import type { Wallet } from "./wallet";
+
 const { toArray, toBase64 } = Utils;
 
 // https://raw.githubusercontent.com/google/A2A/refs/heads/main/specification/json/a2a.json
@@ -152,19 +149,16 @@ export function registerA2bPublishAgentTool(server: McpServer, wallet: Wallet) {
 	server.tool(
 		"wallet_a2bPublish",
 		"Publish an agent.json record on-chain via Ordinal inscription",
-		{ args: a2bPublishArgsSchema },
-		async (
-			{ args }: { args: A2bPublishArgs },
-			extra: RequestHandlerExtra<ServerRequest, ServerNotification>,
-		) => {
+		{ ...a2bPublishArgsSchema.shape },
+		async ({ agentUrl, agentName, description, providerOrganization, providerUrl, version, documentationUrl, streaming, pushNotifications, stateTransitionHistory, defaultInputModes, defaultOutputModes, skills, destinationAddress }) => {
 			try {
-				const paymentPk = wallet.getPrivateKey();
+				const paymentPk = wallet.getPaymentKey();
 				if (!paymentPk) throw new Error("No private key available");
 				const { paymentUtxos } = await wallet.getUtxos();
 				if (!paymentUtxos?.length)
 					throw new Error("No payment UTXOs available to fund inscription");
 
-				// TODO: Get the skills from actually running the MCP instead of trusting the agent args for args.skills
+				// TODO: Get the skills from actually running the MCP instead of trusting the agent args for skills
 				const walletAddress = paymentPk.toAddress().toString();
 
 				// Create pricing plans using the new schema
@@ -209,27 +203,27 @@ export function registerA2bPublishAgentTool(server: McpServer, wallet: Wallet) {
 
 				// Assemble AgentCard with defaults and user overrides
 				const agentCard = {
-					name: args.agentName,
-					description: args.description ?? null,
-					url: args.agentUrl,
+					name: agentName,
+					description: description ?? null,
+					url: agentUrl,
 					provider:
-						args.providerOrganization && args.providerUrl
+						providerOrganization && providerUrl
 							? {
-									organization: args.providerOrganization,
-									url: args.providerUrl,
+									organization: providerOrganization,
+									url: providerUrl,
 								}
 							: null,
-					version: args.version ?? "1.0.0",
-					documentationUrl: args.documentationUrl ?? null,
+					version: version ?? packageJson.version,
+					documentationUrl: documentationUrl ?? null,
 					capabilities: {
-						streaming: args.streaming,
-						pushNotifications: args.pushNotifications,
-						stateTransitionHistory: args.stateTransitionHistory,
+						streaming,
+						pushNotifications,
+						stateTransitionHistory,
 					},
 					authentication: null,
-					defaultInputModes: args.defaultInputModes,
-					defaultOutputModes: args.defaultOutputModes,
-					skills: args.skills,
+					defaultInputModes,
+					defaultOutputModes,
+					skills,
 					"x-payment-config": pricingConfig,
 				};
 				// Validate compliance
@@ -242,7 +236,7 @@ export function registerA2bPublishAgentTool(server: McpServer, wallet: Wallet) {
 					contentType: "application/json",
 				};
 				// Destination for the ordinal
-				const targetAddress = args.destinationAddress ?? walletAddress;
+				const targetAddress = destinationAddress ?? walletAddress;
 				const destinations: Destination[] = [
 					{ address: targetAddress, inscription },
 				];
@@ -272,7 +266,8 @@ export function registerA2bPublishAgentTool(server: McpServer, wallet: Wallet) {
 
 				const disableBroadcasting = process.env.DISABLE_BROADCASTING === "true";
 				if (!disableBroadcasting) {
-					await changeResult.tx.broadcast();
+					const broadcaster = new V5Broadcaster();
+					await changeResult.tx.broadcast(broadcaster);
 
 					// Refresh UTXOs
 					try {