bsv-mcp 0.0.35 → 0.2.0

package/tools/wallet/fetchPaymentUtxos.ts

@@ -1,6 +1,9 @@
 import { P2PKH, Transaction, Utils } from "@bsv/sdk";
 import type { Utxo } from "js-1sat-ord";
-const { toBase64 } = Utils;
+import { V5_API_URL } from "../constants";
+import { getBeefTransactionById, getTransactionById } from "./utxo";
+
+const { toBase64, toHex, toArray } = Utils;
 
 /**
  * Type definition for WhatsOnChain UTXO response
@@ -56,13 +59,10 @@ export async function fetchPaymentUtxos(
 		const utxos: (Utxo | null)[] = await Promise.all(
 			data.map(async (utxo: WhatsOnChainUtxo) => {
 				// Get the transaction hex to extract the correct script
-				const script = await getScriptFromTransaction(
-					utxo.tx_hash,
-					utxo.tx_pos,
-				);
-
+				const tx = await getBeefTransactionById(utxo.tx_hash);
+				const script = tx?.outputs[utxo.tx_pos]?.lockingScript.toHex();
 				if (!script) {
-					console.warn(
+					console.error(
 						`Could not get script for UTXO: ${utxo.tx_hash}:${utxo.tx_pos}`,
 					);
 					return null;
@@ -72,7 +72,7 @@ export async function fetchPaymentUtxos(
 					txid: utxo.tx_hash,
 					vout: utxo.tx_pos,
 					satoshis: utxo.value,
-					script: script,
+					script,
 				};
 			}),
 		);
@@ -87,44 +87,45 @@ export async function fetchPaymentUtxos(
 	}
 }
 
-/**
- * Gets the script from a transaction for a specific output index
- *
- * @param txid - The transaction ID
- * @param vout - The output index
- * @returns The script as hex string or undefined if an error occurs
- */
-async function getScriptFromTransaction(
-	txid: string,
-	vout: number,
-): Promise<string | undefined> {
+type V5Utxo = {
+	outpoint: string;
+	height: number;
+	idx: number;
+	satoshis: number;
+	script: string;
+	owners: string[];
+	data: Record<string, unknown>;
+};
+
+export async function fetchPaymentUtxosFromV5(
+	address: string,
+): Promise<Utxo[] | undefined> {
 	try {
-		const response = await fetch(
-			`https://api.whatsonchain.com/v1/bsv/main/tx/${txid}/hex`,
-		);
-
-		if (!response.ok) {
-			console.error(
-				`WhatsOnChain API error fetching tx hex: ${response.status} ${response.statusText}`,
-			);
-			return undefined;
-		}
-
-		const txHex = await response.text();
-		const tx = Transaction.fromHex(txHex);
-		const output = tx.outputs[vout];
-
-		if (!output) {
-			console.error(`Output index ${vout} not found in transaction ${txid}`);
-			return undefined;
+		const url = `${V5_API_URL}/own/${address}/utxos?refresh=true&txo=true&script=true&limit=250&tags=p2pkh`;
+		console.error(`Fetching UTXOs from V5: ${url}`);
+		const response = await fetch(url);
+		const data = (await response.json()) as V5Utxo[];
+		const utxos: Utxo[] = [];
+		for (const utxo of data) {
+			if (!utxo.data.p2pkh) {
+				// Skip if not a P2PKH
+				continue;
+			}
+			const [txid, vout] = utxo.outpoint.split("_");
+			if (!txid || !vout) {
+				console.error(`Invalid outpoint: ${utxo.outpoint}`);
+				continue;
+			}
+			utxos.push({
+				txid,
+				vout: Number.parseInt(vout),
+				satoshis: utxo.satoshis,
+				script: toHex(toArray(utxo.script, "base64")),
+			} as Utxo);
 		}
-
-		return toBase64(output.lockingScript.toBinary());
+		return utxos;
 	} catch (error) {
-		console.error(
-			`Error getting script for transaction ${txid}:${vout}:`,
-			error,
-		);
+		console.error("Error fetching payment UTXOs from V5:", error);
 		return undefined;
 	}
 }

package/tools/wallet/gatherCollectionInfo.ts

@@ -0,0 +1,374 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import type { Wallet } from "./wallet";
+
+const gatherCollectionInfoArgsSchema = z.object({
+	folderPath: z
+		.string()
+		.describe("Path to folder containing images to analyze for collection"),
+});
+
+type GatherCollectionInfoArgs = z.infer<typeof gatherCollectionInfoArgsSchema>;
+
+interface ImageInfo {
+	fileName: string;
+	filePath: string;
+	size: number;
+	sizeKB: number;
+	contentType: string;
+	valid: boolean;
+	error?: string;
+}
+
+interface CollectionAnalysis {
+	folderPath: string;
+	totalImages: number;
+	validImages: number;
+	invalidImages: number;
+	totalSizeKB: number;
+	imageTypes: Record<string, number>;
+	images: ImageInfo[];
+	suggestedMetadata: {
+		collectionName: string;
+		description: string;
+		quantity: number;
+	};
+	costEstimate: {
+		collectionInscriptionCost: number;
+		perItemCost: number;
+		totalItemsCost: number;
+		totalCost: number;
+		totalCostBSV: number;
+	};
+	walletInfo: {
+		address: string;
+		balance: number;
+		balanceBSV: number;
+		hasEnoughFunds: boolean;
+		shortfall?: number;
+	};
+	warnings: string[];
+	errors: string[];
+}
+
+async function analyzeImageFile(filePath: string): Promise<ImageInfo> {
+	const fileName = path.basename(filePath);
+	const ext = path.extname(fileName).toLowerCase();
+
+	const contentTypeMap: Record<string, string> = {
+		".jpg": "image/jpeg",
+		".jpeg": "image/jpeg",
+		".png": "image/png",
+		".gif": "image/gif",
+		".webp": "image/webp",
+		".svg": "image/svg+xml",
+	};
+
+	try {
+		const stat = await fs.stat(filePath);
+		const contentType = contentTypeMap[ext];
+
+		if (!contentType) {
+			return {
+				fileName,
+				filePath,
+				size: stat.size,
+				sizeKB: Math.round(stat.size / 1024),
+				contentType: "unknown",
+				valid: false,
+				error: `Unsupported file type: ${ext}`,
+			};
+		}
+
+		// Check file size (warn if over 50KB)
+		const sizeKB = Math.round(stat.size / 1024);
+		const warnings: string[] = [];
+
+		if (sizeKB > 50) {
+			warnings.push(
+				`Large file size: ${sizeKB}KB (consider optimizing for lower fees)`,
+			);
+		}
+
+		return {
+			fileName,
+			filePath,
+			size: stat.size,
+			sizeKB,
+			contentType,
+			valid: true,
+			error: warnings.length > 0 ? warnings.join("; ") : undefined,
+		};
+	} catch (error) {
+		return {
+			fileName,
+			filePath,
+			size: 0,
+			sizeKB: 0,
+			contentType: "unknown",
+			valid: false,
+			error: error instanceof Error ? error.message : "Unknown error",
+		};
+	}
+}
+
+function estimateInscriptionCost(sizeKB: number): number {
+	// Base cost for inscription (1 sat)
+	const baseCost = 1;
+	// Additional cost based on size (rough estimate: 10 sats per KB)
+	const sizeCost = Math.ceil(sizeKB * 10);
+	// Mining fee estimate
+	const miningFee = 500;
+
+	return baseCost + sizeCost + miningFee;
+}
+
+export function registerGatherCollectionInfoTool(
+	server: McpServer,
+	wallet: Wallet,
+) {
+	server.tool(
+		"wallet_gatherCollectionInfo",
+		"Analyzes a folder of images and gathers all necessary information for minting an ordinals collection. This includes validating images, checking wallet balance, estimating costs, and suggesting metadata. Use this before minting to ensure everything is ready.",
+		{ args: gatherCollectionInfoArgsSchema },
+		async ({
+			args,
+		}: {
+			args: GatherCollectionInfoArgs;
+		}): Promise<CallToolResult> => {
+			try {
+				const analysis: CollectionAnalysis = {
+					folderPath: args.folderPath,
+					totalImages: 0,
+					validImages: 0,
+					invalidImages: 0,
+					totalSizeKB: 0,
+					imageTypes: {},
+					images: [],
+					suggestedMetadata: {
+						collectionName: "",
+						description: "",
+						quantity: 0,
+					},
+					costEstimate: {
+						collectionInscriptionCost: 0,
+						perItemCost: 0,
+						totalItemsCost: 0,
+						totalCost: 0,
+						totalCostBSV: 0,
+					},
+					walletInfo: {
+						address: "",
+						balance: 0,
+						balanceBSV: 0,
+						hasEnoughFunds: false,
+					},
+					warnings: [],
+					errors: [],
+				};
+
+				// Check if folder exists
+				try {
+					const folderStat = await fs.stat(args.folderPath);
+					if (!folderStat.isDirectory()) {
+						throw new Error(`Path is not a directory: ${args.folderPath}`);
+					}
+				} catch (error) {
+					analysis.errors.push(
+						`Folder not found or inaccessible: ${args.folderPath}`,
+					);
+					return {
+						content: [
+							{
+								type: "text",
+								text: JSON.stringify(analysis, null, 2),
+							},
+						],
+						isError: true,
+					};
+				}
+
+				// Get wallet info
+				const paymentPk = wallet.getPrivateKey();
+				if (!paymentPk) {
+					analysis.errors.push("No payment key available in wallet");
+					return {
+						content: [
+							{
+								type: "text",
+								text: JSON.stringify(analysis, null, 2),
+							},
+						],
+						isError: true,
+					};
+				}
+
+				analysis.walletInfo.address = paymentPk.toAddress().toString();
+
+				// Get wallet balance
+				try {
+					const { paymentUtxos } = await wallet.getUtxos();
+					const balance = paymentUtxos.reduce(
+						(sum, utxo) => sum + utxo.satoshis,
+						0,
+					);
+					analysis.walletInfo.balance = balance;
+					analysis.walletInfo.balanceBSV = balance / 100000000;
+				} catch (error) {
+					analysis.warnings.push("Could not fetch wallet balance");
+				}
+
+				// Scan folder for images
+				const files = await fs.readdir(args.folderPath);
+				const imageExtensions = [
+					".jpg",
+					".jpeg",
+					".png",
+					".gif",
+					".webp",
+					".svg",
+				];
+
+				for (const file of files) {
+					const filePath = path.join(args.folderPath, file);
+					const stat = await fs.stat(filePath);
+
+					if (stat.isFile()) {
+						const ext = path.extname(file).toLowerCase();
+						if (imageExtensions.includes(ext)) {
+							const imageInfo = await analyzeImageFile(filePath);
+							analysis.images.push(imageInfo);
+							analysis.totalImages++;
+
+							if (imageInfo.valid) {
+								analysis.validImages++;
+								analysis.totalSizeKB += imageInfo.sizeKB;
+
+								// Track image types
+								const type = imageInfo.contentType.split("/")[1] || "unknown";
+								analysis.imageTypes[type] =
+									(analysis.imageTypes[type] || 0) + 1;
+							} else {
+								analysis.invalidImages++;
+								if (imageInfo.error) {
+									analysis.errors.push(
+										`${imageInfo.fileName}: ${imageInfo.error}`,
+									);
+								}
+							}
+						}
+					}
+				}
+
+				// Sort images by name for consistent ordering
+				analysis.images.sort((a, b) => a.fileName.localeCompare(b.fileName));
+
+				if (analysis.validImages === 0) {
+					analysis.errors.push("No valid images found in the folder");
+					return {
+						content: [
+							{
+								type: "text",
+								text: JSON.stringify(analysis, null, 2),
+							},
+						],
+						isError: true,
+					};
+				}
+
+				// Suggest metadata based on folder name
+				const folderName = path.basename(args.folderPath);
+				analysis.suggestedMetadata = {
+					collectionName: folderName
+						.replace(/[-_]/g, " ")
+						.replace(/\b\w/g, (l) => l.toUpperCase()),
+					description: `A collection of ${analysis.validImages} unique digital artifacts`,
+					quantity: analysis.validImages,
+				};
+
+				// Estimate costs
+				const collectionIconSizeKB = 1; // SVG icon is small
+				analysis.costEstimate.collectionInscriptionCost =
+					estimateInscriptionCost(collectionIconSizeKB);
+
+				// Average cost per item
+				const avgItemSizeKB = analysis.totalSizeKB / analysis.validImages;
+				analysis.costEstimate.perItemCost =
+					estimateInscriptionCost(avgItemSizeKB);
+				analysis.costEstimate.totalItemsCost =
+					analysis.costEstimate.perItemCost * analysis.validImages;
+				analysis.costEstimate.totalCost =
+					analysis.costEstimate.collectionInscriptionCost +
+					analysis.costEstimate.totalItemsCost;
+				analysis.costEstimate.totalCostBSV =
+					analysis.costEstimate.totalCost / 100000000;
+
+				// Check if wallet has enough funds
+				analysis.walletInfo.hasEnoughFunds =
+					analysis.walletInfo.balance >= analysis.costEstimate.totalCost;
+				if (!analysis.walletInfo.hasEnoughFunds) {
+					analysis.walletInfo.shortfall =
+						analysis.costEstimate.totalCost - analysis.walletInfo.balance;
+					analysis.warnings.push(
+						`Insufficient funds: need ${analysis.costEstimate.totalCost} sats, have ${analysis.walletInfo.balance} sats (shortfall: ${analysis.walletInfo.shortfall} sats)`,
+					);
+				}
+
+				// Add warnings for large collections
+				if (analysis.validImages > 100) {
+					analysis.warnings.push(
+						`Large collection (${analysis.validImages} items) will take time and multiple transactions to mint`,
+					);
+				}
+
+				if (analysis.totalSizeKB > 1000) {
+					analysis.warnings.push(
+						`Large total size (${Math.round(analysis.totalSizeKB / 1024)}MB) will result in higher fees`,
+					);
+				}
+
+				// Generate summary
+				const summary = {
+					ready:
+						analysis.errors.length === 0 && analysis.walletInfo.hasEnoughFunds,
+					summary: `Found ${analysis.validImages} valid images in "${folderName}". Total size: ${Math.round(analysis.totalSizeKB)}KB. Estimated cost: ${analysis.costEstimate.totalCost} sats (${analysis.costEstimate.totalCostBSV.toFixed(8)} BSV). Wallet balance: ${analysis.walletInfo.balance} sats. ${
+						analysis.walletInfo.hasEnoughFunds
+							? "Ready to mint!"
+							: "Insufficient funds."
+					}`,
+				};
+
+				return {
+					content: [
+						{
+							type: "text",
+							text: JSON.stringify(
+								{
+									...analysis,
+									...summary,
+								},
+								null,
+								2,
+							),
+						},
+					],
+				};
+			} catch (error) {
+				const errorMessage =
+					error instanceof Error ? error.message : String(error);
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Error analyzing collection: ${errorMessage}`,
+						},
+					],
+					isError: true,
+				};
+			}
+		},
+	);
+}

package/tools/wallet/getAddress.ts

@@ -1,12 +1,16 @@
-import { PrivateKey } from "@bsv/sdk";
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
+import type { Wallet } from "./wallet";
 
 /**
  * Register the tool to get the wallet address
  * @param server The MCP server instance
+ * @param wallet The initialized custom Wallet instance
  */
-export function registerGetAddressTool(server: McpServer): void {
+export function registerGetAddressTool(
+	server: McpServer,
+	wallet: Wallet,
+): void {
 	server.tool(
 		"wallet_getAddress",
 		"Retrieves the current wallet's Bitcoin SV address. This address can be used to receive BSV, ordinals, or tokens, and is derived from the wallet's private key.",
@@ -20,26 +24,14 @@ export function registerGetAddressTool(server: McpServer): void {
 		},
 		async () => {
 			try {
-				const wif = process.env.PRIVATE_KEY_WIF;
-				if (!wif) {
-					return {
-						content: [
-							{
-								type: "text",
-								text: JSON.stringify({
-									error: "No private key available",
-									message:
-										"Please set PRIVATE_KEY_WIF environment variable with a valid Bitcoin SV private key in WIF format.",
-									status: "error",
-								}),
-							},
-						],
-						isError: true,
-					};
+				const address = wallet.getAddress();
+
+				if (!address) {
+					throw new Error(
+						"Could not retrieve address from wallet instance. Key might be missing or getAddress method failed.",
+					);
 				}
 
-				const privKey = PrivateKey.fromWif(wif);
-				const address = privKey.toAddress();
 				return {
 					content: [
 						{
@@ -55,7 +47,7 @@ export function registerGetAddressTool(server: McpServer): void {
 						{
 							type: "text",
 							text: JSON.stringify({
-								error: "Invalid private key",
+								error: "Failed to get wallet address",
 								message: msg,
 								status: "error",
 							}),

package/tools/wallet/getBalance.ts

@@ -0,0 +1,66 @@
+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 { toBitcoin } from "satoshi-token"; // For converting satoshis to BSV string
+import { z } from "zod";
+import type { Wallet } from "./wallet";
+
+export const walletGetBalanceArgsSchema = z.object({}).optional();
+export type WalletGetBalanceArgs = z.infer<typeof walletGetBalanceArgsSchema>;
+
+/**
+ * Registers the wallet_getBalance tool
+ */
+export function registerWalletGetBalanceTool(
+	server: McpServer,
+	wallet: Wallet,
+) {
+	server.tool(
+		"wallet_getBalance",
+		"Retrieves the current BSV balance for the wallet based on its UTXOs.",
+		{ args: walletGetBalanceArgsSchema },
+		async (
+			args: WalletGetBalanceArgs, // Args are empty but present for schema consistency
+			extra: RequestHandlerExtra<ServerRequest, ServerNotification>,
+		) => {
+			try {
+				const { paymentUtxos } = await wallet.getUtxos();
+
+				let totalSatoshis = 0;
+				if (paymentUtxos && paymentUtxos.length > 0) {
+					for (const utxo of paymentUtxos) {
+						totalSatoshis += utxo.satoshis || 0;
+					}
+				}
+
+				const bsvAmount = toBitcoin(totalSatoshis); // Convert to BSV string
+
+				return {
+					content: [
+						{
+							type: "text",
+							text: JSON.stringify({
+								satoshis: totalSatoshis,
+								bsv: bsvAmount,
+								utxoCount: paymentUtxos ? paymentUtxos.length : 0,
+							}),
+						},
+					],
+				};
+			} catch (error) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: error instanceof Error ? error.message : String(error),
+						},
+					],
+					isError: true,
+				};
+			}
+		},
+	);
+}

package/tools/wallet/getBalanceDroplet.ts

@@ -0,0 +1,59 @@
+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 type { DropletClient } from "../../utils/droplet";
+import { emptyArgsSchema } from "./schemas";
+
+/**
+ * Register the getBalance tool for Droplet API mode
+ */
+export function registerWalletGetBalanceDropletTool(
+	server: McpServer,
+	dropletClient: DropletClient,
+) {
+	server.tool(
+		"wallet_getBalance",
+		"Gets the current balance of the wallet (Droplet mode)",
+		{
+			args: emptyArgsSchema,
+		},
+		async (
+			{ args }: { args: unknown },
+			extra: RequestHandlerExtra<ServerRequest, ServerNotification>,
+		) => {
+			try {
+				const status = await dropletClient.getFaucetStatus();
+
+				return {
+					content: [
+						{
+							type: "text",
+							text: JSON.stringify({
+								balance: status.balance_satoshis,
+								unspentUtxoCount: status.unspent_utxo_count,
+								spendableUtxoCount: status.spendable_utxo_count,
+								consolidatingBalance: status.consolidating_balance_satoshis,
+								consolidatingUtxoCount: status.consolidating_utxo_count,
+								fixedDropSats: status.fixed_drop_sats,
+								faucetName: status.faucet_name,
+							}),
+						},
+					],
+				};
+			} catch (error) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: error instanceof Error ? error.message : String(error),
+						},
+					],
+					isError: true,
+				};
+			}
+		},
+	);
+}