bsv-mcp 0.0.36 → 0.2.7

package/tools/wallet/gatherCollectionInfo.ts

@@ -0,0 +1,370 @@
+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.",
+		{ ...gatherCollectionInfoArgsSchema.shape },
+		async ({ folderPath }): Promise<CallToolResult> => {
+			try {
+				const analysis: CollectionAnalysis = {
+					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(folderPath);
+					if (!folderStat.isDirectory()) {
+						throw new Error(`Path is not a directory: ${folderPath}`);
+					}
+				} catch (error) {
+					analysis.errors.push(
+						`Folder not found or inaccessible: ${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(folderPath);
+				const imageExtensions = [
+					".jpg",
+					".jpeg",
+					".png",
+					".gif",
+					".webp",
+					".svg",
+				];
+
+				for (const file of files) {
+					const filePath = path.join(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(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,45 +1,29 @@
-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.",
-		{
-			args: z
-				.object({})
-				.optional()
-				.describe(
-					"No parameters required - simply returns the current wallet address",
-				),
-		},
+		{},
 		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 +39,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,54 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { toBitcoin } from "satoshi-token"; // For converting satoshis to BSV string
+import type { Wallet } from "./wallet";
+
+/**
+ * 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.",
+		{},
+		async () => {
+			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,48 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { DropletClient } from "../../utils/droplet";
+
+/**
+ * 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)",
+		{},
+		async () => {
+			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,
+				};
+			}
+		},
+	);
+}

package/tools/wallet/getPublicKey.ts

@@ -1,16 +1,6 @@
 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 { z } from "zod";
-import { getPublicKeyArgsSchema } from "./schemas";
 import type { Wallet } from "./wallet";
 
-// Use the schema imported from schemas.ts
-export type GetPublicKeyArgs = z.infer<typeof getPublicKeyArgsSchema>;
-
 /**
  * Register the getPublicKey tool
  */
@@ -18,13 +8,10 @@ export function registerGetPublicKeyTool(server: McpServer, wallet: Wallet) {
 	server.tool(
 		"wallet_getPublicKey",
 		"Retrieves the current wallet's public key. This public key can be used for cryptographic operations like signature verification or encryption.",
-		{ args: getPublicKeyArgsSchema },
-		async (
-			{ args }: { args: GetPublicKeyArgs },
-			extra: RequestHandlerExtra<ServerRequest, ServerNotification>,
-		) => {
+		{},
+		async () => {
 			try {
-				const result = await wallet.getPublicKey(args);
+				const result = await wallet.getPublicKey({});
 				return { content: [{ type: "text", text: JSON.stringify(result) }] };
 			} catch (err: unknown) {
 				const msg = err instanceof Error ? err.message : String(err);

package/tools/wallet/integratedWallet.ts

@@ -0,0 +1,120 @@
+import { P2PKH, type PrivateKey, Script } from "@bsv/sdk";
+import { DropletClient, type DropletConfig } from "../../utils/droplet";
+import { Wallet } from "./wallet";
+
+export interface IntegratedWalletConfig {
+	// Local wallet config
+	paymentKey?: PrivateKey;
+	identityKey?: PrivateKey;
+
+	// Droplet API config
+	useDropletApi?: boolean;
+	dropletConfig?: DropletConfig;
+}
+
+/**
+ * Integrated wallet that can use either local keys or Droplet API
+ */
+export class IntegratedWallet {
+	private localWallet?: Wallet;
+	private dropletClient?: DropletClient;
+
+	constructor(private config: IntegratedWalletConfig) {
+		if (config.useDropletApi && config.dropletConfig) {
+			// If we have a payment key, use it for auth with Droplet API
+			if (config.paymentKey) {
+				config.dropletConfig.authKey = config.paymentKey;
+			}
+			this.dropletClient = new DropletClient(config.dropletConfig);
+			console.error("IntegratedWallet: Using Droplet API mode");
+		} else if (config.paymentKey) {
+			this.localWallet = new Wallet(config.paymentKey, config.identityKey);
+			console.error("IntegratedWallet: Using local wallet mode");
+		} else {
+			console.error(
+				"IntegratedWallet: No wallet configured (limited functionality)",
+			);
+		}
+	}
+
+	get isDropletMode(): boolean {
+		return !!this.dropletClient;
+	}
+
+	get hasWallet(): boolean {
+		return !!this.localWallet || !!this.dropletClient;
+	}
+
+	async getBalance(): Promise<number> {
+		if (this.dropletClient) {
+			const status = await this.dropletClient.getFaucetStatus();
+			return status.balance_satoshis;
+		}
+		if (this.localWallet) {
+			return this.localWallet.getTotalBalance();
+		}
+		throw new Error("No wallet configured");
+	}
+
+	async sendToAddress(
+		address: string,
+		satoshis: number,
+		description?: string,
+	): Promise<{ txid: string }> {
+		if (this.dropletClient) {
+			// For Droplet API, we use the tap endpoint which sends the faucet's fixed amount
+			// Note: Droplet API doesn't support custom amounts, it uses fixed_drop_sats
+			const response = await this.dropletClient.tap(address);
+			return { txid: response.txid };
+		}
+		if (this.localWallet) {
+			const tx = await this.localWallet.createAction({
+				description: description || "Send to address",
+				outputs: [
+					{
+						lockingScript: new P2PKH().lock(address).toHex(),
+						satoshis,
+						outputDescription: `Payment to ${address}`,
+					},
+				],
+			});
+			return { txid: tx.txid };
+		}
+		throw new Error("No wallet configured");
+	}
+
+	async pushData(data: string[], encoding = "hex"): Promise<{ txid: string }> {
+		if (this.dropletClient) {
+			const response = await this.dropletClient.push(data, encoding);
+			return { txid: response.txid };
+		}
+		if (this.localWallet) {
+			// For local wallet, we need to implement OP_RETURN transaction
+			// This is a simplified version - you might want to enhance this
+			const opReturnScript = Script.fromASM(
+				`OP_FALSE OP_RETURN ${data.join(" ")}`,
+			);
+			const tx = await this.localWallet.createAction({
+				description: "Push data",
+				outputs: [
+					{
+						lockingScript: opReturnScript.toHex(),
+						satoshis: 0,
+						outputDescription: "OP_RETURN data",
+					},
+				],
+			});
+			return { txid: tx.txid };
+		}
+		throw new Error("No wallet configured");
+	}
+
+	// Delegate other methods to the appropriate implementation
+	getLocalWallet(): Wallet | undefined {
+		return this.localWallet;
+	}
+
+	getDropletClient(): DropletClient | undefined {
+		return this.dropletClient;
+	}
+}