bsv-mcp 0.0.1

package/tools/wallet/purchaseListing.ts

@@ -0,0 +1,175 @@
+import { PrivateKey } from "@bsv/sdk";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import {
+	type ExistingListing,
+	type Utxo,
+	oneSatBroadcaster,
+	purchaseOrdListing,
+} from "js-1sat-ord";
+import type { z } from "zod";
+import { purchaseListingArgsSchema } from "./schemas";
+import type { Wallet } from "./wallet";
+
+// Define types for 1Sat API response
+interface ListingResponse {
+	txid: string;
+	vout: number;
+	satoshis: number;
+	script: string;
+	data?: {
+		list?: {
+			price: number;
+			payout: string;
+		};
+	};
+}
+
+/**
+ * Register the purchaseListing tool
+ *
+ * This tool:
+ * 1. Parses the listing outpoint to get the txid and vout
+ * 2. Fetches the listing UTXO from the ordinals API
+ * 3. Gets the wallet's payment UTXOs (using the wallet's internal UTXO management)
+ * 4. Uses purchaseOrdListing to create a purchase transaction
+ * 5. Broadcasts the transaction
+ * 6. Returns the transaction details
+ */
+export function registerPurchaseListingTool(server: McpServer, wallet: Wallet) {
+	// Store a reference to check if wallet is persistent
+	console.log("Registering purchaseListing tool with wallet:", wallet);
+
+	server.tool(
+		"wallet_purchaseListing",
+		{ args: purchaseListingArgsSchema },
+		async (
+			{ args }: { args: z.infer<typeof purchaseListingArgsSchema> },
+			extra: RequestHandlerExtra,
+		) => {
+			try {
+				console.log(`Attempting to purchase listing: ${args.listingOutpoint}`);
+				console.log("Using wallet instance:", wallet);
+				console.log("Wallet has UTXOs:", await wallet.getUtxos());
+
+				// Fetch the listing info directly from the API
+				const response = await fetch(
+					`https://ordinals.gorillapool.io/api/txos/${args.listingOutpoint}?script=true`,
+				);
+				if (!response.ok) {
+					throw new Error(
+						`Failed to fetch listing data: ${response.statusText}`,
+					);
+				}
+
+				const listingData = (await response.json()) as ListingResponse;
+
+				// Check if the listing is valid and has a price
+				if (!listingData.data?.list?.price) {
+					throw new Error("Listing is either not for sale or invalid");
+				}
+
+				// Check if payout is available
+				if (!listingData.data.list.payout) {
+					throw new Error("Listing doesn't have payout information");
+				}
+
+				// Parse the listing outpoint to get txid and vout
+				const [txid, voutStr] = args.listingOutpoint.split("_");
+				if (!txid) {
+					throw new Error("Invalid outpoint format. Expected txid_vout");
+				}
+				const vout = Number.parseInt(voutStr || "0", 10);
+
+				// Create listing UTXO object in the format required by js-1sat-ord
+				const listingUtxo: Utxo = {
+					txid,
+					vout,
+					script: listingData.script,
+					satoshis: listingData.satoshis,
+				};
+
+				// Create the ExistingListing object
+				const listing: ExistingListing = {
+					payout: listingData.data.list.payout,
+					listingUtxo,
+				};
+
+				// Get private key from the wallet
+				const paymentPk = wallet.getPrivateKey();
+				if (!paymentPk) {
+					throw new Error("No private key available in wallet");
+				}
+
+				// Get payment address
+				const paymentAddress = paymentPk.toAddress().toString();
+				console.log(`Using payment address: ${paymentAddress}`);
+
+				// Get payment UTXOs from the wallet's managed UTXOs
+				const { paymentUtxos } = await wallet.getUtxos();
+				if (!paymentUtxos || paymentUtxos.length === 0) {
+					// Provide more helpful error message with instructions
+					throw new Error(
+						`No payment UTXOs available for address ${paymentAddress}. 
+Please fund this wallet address with enough BSV to cover the purchase price 
+(${listingData.data.list.price} satoshis) plus transaction fees.`,
+					);
+				}
+
+				// Create the purchase transaction using the library's config type
+				const transaction = await purchaseOrdListing({
+					utxos: paymentUtxos,
+					paymentPk,
+					ordAddress: args.ordAddress,
+					listing,
+				});
+
+				// After successful transaction creation, refresh the wallet's UTXOs
+				// This ensures the wallet doesn't try to reuse spent UTXOs
+				try {
+					await wallet.refreshUtxos();
+				} catch (refreshError) {
+					console.warn(
+						"Failed to refresh UTXOs after transaction:",
+						refreshError,
+					);
+				}
+
+				// Broadcast the transaction
+				const broadcastResult = await transaction.tx.broadcast(
+					oneSatBroadcaster(),
+				);
+
+				// Handle broadcast response
+				const resultStatus =
+					typeof broadcastResult === "object" && "status" in broadcastResult
+						? broadcastResult.status
+						: "unknown";
+
+				const resultMessage =
+					typeof broadcastResult === "object" && "error" in broadcastResult
+						? broadcastResult.error
+						: "Transaction broadcast successful";
+
+				return {
+					content: [
+						{
+							type: "text",
+							text: JSON.stringify({
+								status: resultStatus,
+								message: resultMessage,
+								txid: transaction.tx.id("hex"),
+								listingOutpoint: args.listingOutpoint,
+								destinationAddress: args.ordAddress,
+								price: listingData.data.list.price,
+							}),
+						},
+					],
+				};
+			} catch (err: unknown) {
+				const msg = err instanceof Error ? err.message : String(err);
+				return { content: [{ type: "text", text: msg }], isError: true };
+			}
+		},
+	);
+}

package/tools/wallet/schemas.ts

@@ -0,0 +1,284 @@
+import type { SecurityLevel } from "@bsv/sdk";
+import { z } from "zod";
+
+// Define SecurityLevel to match the BSV SDK exactly
+const SecurityLevelEnum = z.union([z.literal(0), z.literal(1), z.literal(2)]);
+
+// Create a custom validator without tuples
+export const walletProtocolSchema = z.custom<[SecurityLevel, string]>((val) => {
+	return (
+		Array.isArray(val) &&
+		val.length === 2 &&
+		(val[0] === 0 || val[0] === 1 || val[0] === 2) &&
+		typeof val[1] === "string"
+	);
+});
+
+// Empty args schema for functions that don't take arguments
+export const emptyArgsSchema = z.object({});
+
+// Get public key arguments
+export const getPublicKeyArgsSchema = z.object({});
+
+// Create signature arguments
+export const createSignatureArgsSchema = z.object({
+	data: z.array(z.number()).optional(),
+	hashToDirectlySign: z.array(z.number()).optional(),
+	protocolID: walletProtocolSchema,
+	keyID: z.string(),
+	privilegedReason: z.string().optional(),
+	counterparty: z
+		.union([z.string(), z.literal("self"), z.literal("anyone")])
+		.optional(),
+	privileged: z.boolean().optional(),
+});
+
+// Verify signature arguments
+export const verifySignatureArgsSchema = z.object({
+	data: z.array(z.number()).optional(),
+	hashToDirectlyVerify: z.array(z.number()).optional(),
+	signature: z.array(z.number()),
+	protocolID: walletProtocolSchema,
+	keyID: z.string(),
+	privilegedReason: z.string().optional(),
+	counterparty: z
+		.union([z.string(), z.literal("self"), z.literal("anyone")])
+		.optional(),
+	forSelf: z.boolean().optional(),
+	privileged: z.boolean().optional(),
+});
+
+// Wallet encryption args
+export const walletEncryptArgsSchema = z.object({
+	plaintext: z.array(z.number()),
+	protocolID: walletProtocolSchema,
+	keyID: z.string(),
+	privilegedReason: z.string().optional(),
+	counterparty: z
+		.union([z.string(), z.literal("self"), z.literal("anyone")])
+		.optional(),
+	privileged: z.boolean().optional(),
+});
+
+// Wallet decryption args
+export const walletDecryptArgsSchema = z.object({
+	ciphertext: z.array(z.number()),
+	protocolID: walletProtocolSchema,
+	keyID: z.string(),
+	privilegedReason: z.string().optional(),
+	counterparty: z
+		.union([z.string(), z.literal("self"), z.literal("anyone")])
+		.optional(),
+	privileged: z.boolean().optional(),
+});
+
+// Create HMAC arguments
+export const createHmacArgsSchema = z.object({
+	message: z.string(),
+	encoding: z.enum(["utf8", "hex", "base64"]).optional(),
+});
+
+// Verify HMAC arguments
+export const verifyHmacArgsSchema = z.object({
+	message: z.string(),
+	hmac: z.string(),
+	publicKey: z.string(),
+	encoding: z.enum(["utf8", "hex", "base64"]).optional(),
+});
+
+// Transaction input schema
+export const transactionInputSchema = z.object({
+	outpoint: z.string(),
+	inputDescription: z.string(), // Required field
+	sequence: z.number().optional(),
+});
+
+// Transaction output schema
+export const transactionOutputSchema = z.object({
+	lockingScript: z.string(),
+	satoshis: z.number(),
+	outputDescription: z.string(), // Required field
+	change: z.boolean().optional(),
+});
+
+// Create action args
+export const createActionArgsSchema = z.object({
+	description: z.string(),
+	labels: z.array(z.string()).optional(),
+	lockTime: z.number().optional(),
+	version: z.number().optional(),
+	inputBEEF: z.array(z.number()).optional(),
+	inputs: z.array(transactionInputSchema).optional(),
+	outputs: z.array(transactionOutputSchema).optional(),
+	options: z.record(z.union([z.string(), z.number(), z.boolean()])).optional(),
+});
+
+// Sign action args
+export const signActionArgsSchema = z.object({
+	reference: z.string(),
+	spends: z.record(z.any()).optional(),
+	options: z.record(z.union([z.string(), z.number(), z.boolean()])).optional(),
+});
+
+// List actions args
+export const listActionsArgsSchema = z.object({
+	labels: z.array(z.string()),
+	labelQueryMode: z.enum(["any", "all"]).optional(),
+	limit: z.number().optional(),
+	offset: z.number().optional(),
+	includeInputs: z.boolean().optional(),
+	includeOutputs: z.boolean().optional(),
+	includeLabels: z.boolean().optional(),
+	includeInputSourceLockingScripts: z.boolean().optional(),
+	includeInputUnlockingScripts: z.boolean().optional(),
+	seekPermission: z.boolean().optional(),
+});
+
+// List outputs args
+export const listOutputsArgsSchema = z.object({
+	basket: z.string(),
+	tags: z.array(z.string()).optional(),
+	tagQueryMode: z.enum(["all", "any"]).optional(),
+	limit: z.number().optional(),
+	offset: z.number().optional(),
+	include: z.enum(["locking scripts", "entire transactions"]).optional(),
+	includeLabels: z.boolean().optional(),
+	includeTags: z.boolean().optional(),
+	includeCustomInstructions: z.boolean().optional(),
+	seekPermission: z.boolean().optional(),
+});
+
+// Reveal counterparty key linkage args
+export const revealCounterpartyKeyLinkageArgsSchema = z.object({
+	counterparty: z.string(),
+	verifier: z.string(),
+	privileged: z.boolean().optional(),
+	privilegedReason: z.string().optional(),
+});
+
+// Reveal specific key linkage args
+export const revealSpecificKeyLinkageArgsSchema = z.object({
+	keyID: z.number(),
+	verifier: z.string(),
+	privileged: z.boolean().optional(),
+	privilegedReason: z.string().optional(),
+});
+
+// Abort action args
+export const abortActionArgsSchema = z.object({
+	reference: z.string(),
+});
+
+// Internalize action args
+export const internalizeActionArgsSchema = z.object({
+	tx: z.array(z.number()),
+	outputs: z.array(
+		z.object({
+			outputIndex: z.number(),
+			protocol: z.enum(["wallet payment", "basket insertion"]),
+			lockingScript: z.string(),
+			satoshis: z.number(),
+		}),
+	),
+	description: z.string(),
+	labels: z.array(z.string()).optional(),
+	seekPermission: z.boolean().optional(),
+});
+
+// Relinquish output args
+export const relinquishOutputArgsSchema = z.object({
+	basket: z.string(),
+	output: z.string(),
+});
+
+// Acquire certificate args
+export const acquireCertificateArgsSchema = z.object({
+	type: z.string(),
+	certifier: z.string(),
+	acquisitionProtocol: z.enum(["direct", "issuance"]),
+	fields: z.record(z.string()),
+	certifierUrl: z.string().optional(),
+	serialNumber: z.string().optional(),
+	signature: z.string().optional(),
+	revocationOutpoint: z.string().optional(),
+	keyringForSubject: z.record(z.string()).optional(),
+	keyringRevealer: z.string().optional(),
+	privileged: z.boolean().optional(),
+	privilegedReason: z.string().optional(),
+});
+
+// List certificates args
+export const listCertificatesArgsSchema = z.object({
+	certifiers: z.array(z.string()),
+	types: z.array(z.string()),
+	limit: z.number().optional(),
+	offset: z.number().optional(),
+	privileged: z.boolean().optional(),
+	privilegedReason: z.string().optional(),
+});
+
+// Prove certificate args
+export const proveCertificateArgsSchema = z.object({
+	certificate: z.object({}),
+	fieldsToReveal: z.array(z.string()),
+	verifier: z.string(),
+	privileged: z.boolean().optional(),
+	privilegedReason: z.string().optional(),
+});
+
+// Relinquish certificate args
+export const relinquishCertificateArgsSchema = z.object({
+	type: z.string(),
+	serialNumber: z.string(),
+	certifier: z.string(),
+});
+
+// Discover by identity key args
+export const discoverByIdentityKeyArgsSchema = z.object({
+	identityKey: z.string(),
+	limit: z.number().optional(),
+	offset: z.number().optional(),
+	seekPermission: z.boolean().optional(),
+});
+
+// Discover by attributes args
+export const discoverByAttributesArgsSchema = z.object({
+	attributes: z.record(z.string()),
+	limit: z.number().optional(),
+	offset: z.number().optional(),
+	seekPermission: z.boolean().optional(),
+});
+
+// Get header for height args
+export const getHeaderArgsSchema = z.object({
+	height: z.number(),
+});
+
+// Get address args
+export const getAddressArgsSchema = z.object({});
+
+// Send to address args
+export const sendToAddressArgsSchema = z.object({
+	address: z.string(),
+	amount: z.number(),
+	currency: z.enum(["BSV", "USD"]).optional(),
+	description: z.string().optional(),
+});
+
+/**
+ * Schema for purchase listing arguments
+ */
+export const purchaseListingArgsSchema = z.object({
+	listingOutpoint: z
+		.string()
+		.describe("The outpoint of the listing to purchase (txid_vout format)"),
+	ordAddress: z
+		.string()
+		.describe("The ordinal address to receive the purchased item"),
+	description: z
+		.string()
+		.optional()
+		.describe("Optional description for the transaction"),
+});
+
+export type PurchaseListingArgs = z.infer<typeof purchaseListingArgsSchema>;

package/tools/wallet/sendToAddress.ts

@@ -0,0 +1,112 @@
+import { P2PKH } from "@bsv/sdk";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import type { z } from "zod";
+import { sendToAddressArgsSchema } from "./schemas";
+import type { Wallet } from "./wallet";
+
+/**
+ * Fetch the current BSV price from whatsonchain API
+ * @returns The BSV price in USD
+ */
+async function getBsvPrice(): Promise<number> {
+	try {
+		const res = await fetch(
+			"https://api.whatsonchain.com/v1/bsv/main/exchangerate",
+		);
+		if (!res.ok) throw new Error("Failed to fetch BSV price");
+
+		// Parse the response with proper type casting
+		const data = (await res.json()) as {
+			rate: string;
+			currency: string;
+			time: number;
+		};
+		const price = Number(data.rate);
+
+		if (Number.isNaN(price) || price <= 0) throw new Error("Invalid BSV price");
+		return price;
+	} catch (error) {
+		console.error("BSV price fetch error:", error);
+		throw error;
+	}
+}
+
+// Use the schema imported from schemas.ts
+export type SendToAddressArgs = z.infer<typeof sendToAddressArgsSchema>;
+
+/**
+ * Register the sendToAddress tool
+ */
+export function registerSendToAddressTool(server: McpServer, wallet: Wallet) {
+	server.tool(
+		"wallet_sendToAddress",
+		{
+			args: sendToAddressArgsSchema,
+		},
+		async (
+			{ args }: { args: SendToAddressArgs },
+			extra: RequestHandlerExtra,
+		) => {
+			try {
+				const {
+					address,
+					amount,
+					currency = "BSV",
+					description = "Send to address",
+				} = args;
+
+				// Convert USD to satoshis if needed
+				let satoshis = amount;
+				if (currency === "USD") {
+					// Get current BSV price
+					const bsvPriceUsd = await getBsvPrice();
+
+					// Convert USD to BSV, then to satoshis
+					satoshis = Math.floor((amount / bsvPriceUsd) * 100000000);
+				} else {
+					// Convert BSV to satoshis
+					satoshis = Math.floor(amount * 100000000);
+				}
+
+				// Create P2PKH script from address
+				const lockingScript = new P2PKH().lock(address);
+
+				// Create the transaction
+				const tx = await wallet.createAction({
+					description,
+					outputs: [
+						{
+							lockingScript: lockingScript.toHex(),
+							satoshis,
+							outputDescription: `Payment to ${address}`,
+						},
+					],
+				});
+
+				return {
+					content: [
+						{
+							type: "text",
+							text: JSON.stringify({
+								status: "success",
+								txid: tx.txid,
+								satoshis,
+							}),
+						},
+					],
+				};
+			} catch (error) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: error instanceof Error ? error.message : String(error),
+						},
+					],
+					isError: true,
+				};
+			}
+		},
+	);
+}

package/tools/wallet/tools.test.ts

@@ -0,0 +1,76 @@
+import { expect, test } from "bun:test";
+import { PrivateKey } from "@bsv/sdk";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import { getPublicKeyArgsSchema } from "./schemas";
+import { registerWalletTools } from "./tools";
+import { Wallet } from "./wallet";
+
+// Define type for tool names to ensure they match what's in tools.ts
+type WalletToolName =
+	| "wallet_getPublicKey"
+	| "wallet_createSignature"
+	| "wallet_verifySignature"
+	| "wallet_encrypt"
+	| "wallet_decrypt";
+
+const toolNames: WalletToolName[] = [
+	"wallet_getPublicKey",
+	"wallet_createSignature",
+	"wallet_verifySignature",
+	"wallet_encrypt",
+	"wallet_decrypt",
+];
+
+// Helper function to get dummy arguments for each tool
+function getDummyArgs(tool: WalletToolName): Record<string, unknown> {
+	switch (tool) {
+		case "wallet_getPublicKey":
+			return getPublicKeyArgsSchema.parse({});
+		case "wallet_createSignature":
+			return { data: "test", keyType: "identity" };
+		case "wallet_verifySignature":
+			return {
+				data: "test",
+				keyType: "identity",
+				signature: "sig",
+				publicKey: "pubkey",
+			};
+		case "wallet_encrypt":
+			return { data: "test", publicKey: "pubkey" };
+		case "wallet_decrypt":
+			return { encryptedData: "data" };
+		default:
+			return {};
+	}
+}
+
+// Bun test
+for (const tool of toolNames) {
+	test(`tool ${tool} returns not implemented error`, async () => {
+		const server = new McpServer({ name: "Test", version: "0.0.1" });
+		const wallet = new Wallet(
+			PrivateKey.fromWif(
+				"KyqU1boXYdksJKyxfsCtvBxfbt2a8XQd2aPhVZHNxMzvms9hRAvz",
+			),
+		);
+		const handlers = registerWalletTools(server, wallet);
+
+		// Get the handler for this tool
+		const handler = handlers[tool];
+		if (!handler) {
+			throw new Error(`Tool ${tool} not registered`);
+		}
+
+		// Create a mock RequestHandlerExtra with required properties
+		const mockExtra: RequestHandlerExtra = {
+			signal: new AbortController().signal,
+		};
+
+		// Call the handler with dummy arguments
+		const result = await handler({ args: getDummyArgs(tool) }, mockExtra);
+
+		expect(result.isError).toBe(true);
+		expect(result.content?.[0]?.text ?? "").toMatch(/not implemented/i);
+	});
+}