bsv-mcp 0.2.15 → 0.3.0

package/tools/wallet/cancelListing.ts

@@ -1,80 +1,72 @@
-import type { OneSatContext } from '@1sat/actions'
-import { cancelListing } from '@1sat/actions'
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
-import { z } from 'zod'
-
-const walletOutputSchema = z.object({
-	outpoint: z.string(),
-	satoshis: z.number().optional(),
-	tags: z.array(z.string()).optional(),
-	customInstructions: z.string().optional(),
-	lockingScript: z.string().optional(),
-})
+import type { OneSatContext } from "@1sat/actions";
+import { cancelOrdinalListing } from "@1sat/actions";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { assertBroadcastAllowed } from "../../utils/broadcastGuard";
 
 const cancelListingArgsSchema = z.object({
-	listing: walletOutputSchema.describe(
-		'WalletOutput of the listing to cancel (must include lockingScript)',
-	),
-	inputBEEF: z
-		.array(z.number())
+	id: z
+		.string()
 		.describe(
-			"BEEF bytes from listOutputs (include: 'entire transactions')",
+			"Tracking id of the listing in the ordinals basket (the 'id:' tag from wallet_getOrdinals)",
 		),
-})
+});
 
 export function registerCancelListingTool(
 	server: McpServer,
 	ctx: OneSatContext | undefined,
 ) {
 	server.tool(
-		'wallet_cancelListing',
-		'Cancel an ordinal marketplace listing',
+		"wallet_cancelListing",
+		"Cancel an ordinal marketplace listing",
 		{ ...cancelListingArgsSchema.shape },
-		async ({ listing, inputBEEF }) => {
+		async ({ id }) => {
 			if (!ctx) {
 				return {
 					content: [
 						{
-							type: 'text',
-							text: 'Wallet not initialized. Please configure a wallet before cancelling.',
+							type: "text",
+							text: "Wallet not initialized. Please configure a wallet before cancelling.",
 						},
 					],
 					isError: true,
-				}
+				};
 			}
 
 			try {
-				const result = await cancelListing.execute(ctx, {
-					listing: listing as Parameters<typeof cancelListing.execute>[1]['listing'],
-					inputBEEF,
-				})
+				assertBroadcastAllowed("wallet_cancelListing");
+				const result = await cancelOrdinalListing.execute(ctx, { id });
 
 				if (result.error) {
 					return {
-						content: [{ type: 'text', text: result.error }],
+						content: [{ type: "text", text: result.error }],
 						isError: true,
-					}
+					};
 				}
 
 				return {
 					content: [
 						{
-							type: 'text',
-							text: JSON.stringify(result, (_, v) => typeof v === 'bigint' ? v.toString() : v, 2),
+							type: "text",
+							text: JSON.stringify(
+								result,
+								(_, v) => (typeof v === "bigint" ? v.toString() : v),
+								2,
+							),
 						},
 					],
-				}
+				};
 			} catch (err: unknown) {
 				return {
 					content: [
 						{
-							type: 'text',
+							type: "text",
 							text: err instanceof Error ? err.message : String(err),
 						},
 					],
 					isError: true,
-				}
+				};
 			}
 		},
-	)
+	);
 }

package/tools/wallet/createOrdinals.ts

@@ -1,87 +1,103 @@
-import type { OneSatContext } from '@1sat/actions'
-import { inscribe } from '@1sat/actions'
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
-import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js'
-import { z } from 'zod'
+import type { OneSatContext } from "@1sat/actions";
+import { inscribe } from "@1sat/actions";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { assertBroadcastAllowed } from "../../utils/broadcastGuard";
 
 export const createOrdinalsArgsSchema = z.object({
-	dataB64: z.string().describe('Base64-encoded content to inscribe'),
-	contentType: z.string().describe('MIME type of the content'),
+	dataB64: z.string().describe("Base64-encoded content to inscribe"),
+	contentType: z.string().describe("MIME type of the content"),
 	destinationAddress: z
 		.string()
 		.optional()
-		.describe('Optional destination address for the ordinal'),
+		.describe("Optional destination address for the ordinal"),
 	metadata: z
 		.record(z.string(), z.string())
 		.optional()
-		.describe('Optional MAP metadata for the inscription'),
+		.describe("Optional MAP metadata for the inscription"),
 	signWithBAP: z
 		.boolean()
 		.optional()
-		.describe('Sign with BAP identity (Sigma protocol). Uses anchor+inscription two-step flow.'),
-})
+		.describe(
+			"Sign with BAP identity (Sigma protocol). Uses anchor+inscription two-step flow.",
+		),
+});
 
-export type CreateOrdinalsArgs = z.infer<typeof createOrdinalsArgsSchema>
+export type CreateOrdinalsArgs = z.infer<typeof createOrdinalsArgsSchema>;
 
 export function registerCreateOrdinalsTool(
 	server: McpServer,
 	ctx: OneSatContext | undefined,
 ) {
 	server.tool(
-		'wallet_createOrdinals',
-		'Creates and inscribes ordinals (NFTs) on the Bitcoin SV blockchain. This tool lets you mint new digital artifacts by encoding data directly into the blockchain. Supports various content types including images, text, JSON, and HTML. The tool handles transaction creation, fee calculation, and broadcasting.',
+		"wallet_createOrdinals",
+		"Creates and inscribes ordinals (NFTs) on the Bitcoin SV blockchain. This tool lets you mint new digital artifacts by encoding data directly into the blockchain. Supports various content types including images, text, JSON, and HTML. The tool handles transaction creation, fee calculation, and broadcasting.",
 		{ ...createOrdinalsArgsSchema.shape },
-		async ({ dataB64, contentType, destinationAddress, metadata, signWithBAP }): Promise<CallToolResult> => {
+		async ({
+			dataB64,
+			contentType,
+			destinationAddress,
+			metadata,
+			signWithBAP,
+		}): Promise<CallToolResult> => {
 			if (!ctx) {
 				return {
 					content: [
 						{
-							type: 'text',
-							text: 'Wallet not initialized. Please configure a wallet before creating ordinals.',
+							type: "text",
+							text: "Wallet not initialized. Please configure a wallet before creating ordinals.",
 						},
 					],
 					isError: true,
-				}
+				};
 			}
 
 			try {
+				assertBroadcastAllowed("wallet_createOrdinals");
 				const result = await inscribe.execute(ctx, {
 					base64Content: dataB64,
 					contentType,
 					map: metadata,
 					signWithBAP,
-				})
+					// Without this the inscription locks to a wallet-derived self
+					// key, so a caller-supplied address has to be forwarded or the
+					// ordinal silently mints to the wrong owner.
+					...(destinationAddress && {
+						destination: { address: destinationAddress },
+					}),
+				});
 
 				if (result.error) {
 					return {
-						content: [{ type: 'text', text: result.error }],
+						content: [{ type: "text", text: result.error }],
 						isError: true,
-					}
+					};
 				}
 
 				return {
 					content: [
 						{
-							type: 'text',
+							type: "text",
 							text: JSON.stringify({
 								txid: result.txid,
-								rawtx: result.rawtx,
+								contentHash: result.contentHash,
 								contentType,
 							}),
 						},
 					],
-				}
+				};
 			} catch (err: unknown) {
 				return {
 					content: [
 						{
-							type: 'text',
+							type: "text",
 							text: err instanceof Error ? err.message : String(err),
 						},
 					],
 					isError: true,
-				}
+				};
 			}
 		},
-	)
+	);
 }

package/tools/wallet/fetchPaymentUtxos.ts

@@ -1,9 +1,9 @@
-import { P2PKH, Transaction, Utils } from "@bsv/sdk";
+import { Utils } from "@bsv/sdk";
 import type { Utxo } from "js-1sat-ord";
 import { V5_API_URL } from "../constants";
-import { getBeefTransactionById, getTransactionById } from "./utxo";
+import { getBeefTransactionById } from "./utxo";
 
-const { toBase64, toHex, toArray } = Utils;
+const { toHex, toArray } = Utils;
 
 /**
  * Type definition for WhatsOnChain UTXO response
@@ -105,7 +105,9 @@ export async function fetchPaymentUtxosFromV5(
 		console.error(`Fetching UTXOs from V5: ${url}`);
 		const response = await fetch(url);
 		if (!response.ok) {
-			console.error(`V5 UTXO fetch failed: ${response.status} ${response.statusText}`);
+			console.error(
+				`V5 UTXO fetch failed: ${response.status} ${response.statusText}`,
+			);
 			return undefined;
 		}
 		const data = (await response.json()) as V5Utxo[] | null;
@@ -126,7 +128,7 @@ export async function fetchPaymentUtxosFromV5(
 			}
 			utxos.push({
 				txid,
-				vout: Number.parseInt(vout),
+				vout: Number.parseInt(vout, 10),
 				satoshis: utxo.satoshis,
 				script: toHex(toArray(utxo.script, "base64")),
 			} as Utxo);

package/tools/wallet/gatherCollectionInfo.ts

@@ -11,8 +11,6 @@ const gatherCollectionInfoArgsSchema = z.object({
 		.describe("Path to folder containing images to analyze for collection"),
 });
 
-type GatherCollectionInfoArgs = z.infer<typeof gatherCollectionInfoArgsSchema>;
-
 interface ImageInfo {
 	fileName: string;
 	filePath: string;
@@ -172,7 +170,7 @@ export function registerGatherCollectionInfoTool(
 					if (!folderStat.isDirectory()) {
 						throw new Error(`Path is not a directory: ${folderPath}`);
 					}
-				} catch (error) {
+				} catch (_error) {
 					analysis.errors.push(
 						`Folder not found or inaccessible: ${folderPath}`,
 					);
@@ -188,7 +186,7 @@ export function registerGatherCollectionInfoTool(
 				}
 
 				// Get wallet info
-				const paymentPk = wallet.getPrivateKey();
+				const paymentPk = wallet.getPaymentKey();
 				if (!paymentPk) {
 					analysis.errors.push("No payment key available in wallet");
 					return {
@@ -213,7 +211,7 @@ export function registerGatherCollectionInfoTool(
 					);
 					analysis.walletInfo.balance = balance;
 					analysis.walletInfo.balanceBSV = balance / 100000000;
-				} catch (error) {
+				} catch (_error) {
 					analysis.warnings.push("Could not fetch wallet balance");
 				}
 

package/tools/wallet/getAddress.ts

@@ -1,7 +1,4 @@
-import {
-	deriveDepositAddresses,
-	type OneSatContext,
-} from "@1sat/actions";
+import { deriveDepositAddresses, type OneSatContext } from "@1sat/actions";
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
 const MCP_ADDRESS_PREFIX = "mcp";

package/tools/wallet/getBalance.ts

@@ -1,39 +1,39 @@
-import type { OneSatContext } from '@1sat/actions'
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
-import { toBitcoin } from 'satoshi-token'
+import type { OneSatContext } from "@1sat/actions";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { toBitcoin } from "satoshi-token";
 
 export function registerWalletGetBalanceTool(
 	server: McpServer,
 	ctx: OneSatContext | undefined,
 ) {
 	server.tool(
-		'wallet_getBalance',
-		'Retrieves the current BSV balance for the wallet.',
+		"wallet_getBalance",
+		"Retrieves the current BSV balance for the wallet.",
 		{},
 		async () => {
 			if (!ctx) {
 				return {
 					content: [
 						{
-							type: 'text',
-							text: 'Wallet not initialized. Please configure a wallet before checking balance.',
+							type: "text",
+							text: "Wallet not initialized. Please configure a wallet before checking balance.",
 						},
 					],
 					isError: true,
-				}
+				};
 			}
 
 			try {
-				const result = await ctx.wallet.listOutputs({ basket: 'default' })
+				const result = await ctx.wallet.listOutputs({ basket: "default" });
 				const totalSatoshis = result.outputs.reduce(
 					(sum, output) => sum + output.satoshis,
 					0,
-				)
+				);
 
 				return {
 					content: [
 						{
-							type: 'text',
+							type: "text",
 							text: JSON.stringify({
 								satoshis: totalSatoshis,
 								bsv: toBitcoin(totalSatoshis),
@@ -41,18 +41,18 @@ export function registerWalletGetBalanceTool(
 							}),
 						},
 					],
-				}
+				};
 			} catch (error) {
 				return {
 					content: [
 						{
-							type: 'text',
+							type: "text",
 							text: error instanceof Error ? error.message : String(error),
 						},
 					],
 					isError: true,
-				}
+				};
 			}
 		},
-	)
+	);
 }

package/tools/wallet/{getBalanceDroplet.ts → getBalanceDroplit.ts}

@@ -1,20 +1,20 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import type { DropletClient } from "../../utils/droplet";
+import type { DroplitClient } from "../../utils/droplit";
 
 /**
- * Register the getBalance tool for Droplet API mode
+ * Register the getBalance tool for Droplit API mode
  */
-export function registerWalletGetBalanceDropletTool(
+export function registerWalletGetBalanceDroplitTool(
 	server: McpServer,
-	dropletClient: DropletClient,
+	droplitClient: DroplitClient,
 ) {
 	server.tool(
 		"wallet_getBalance",
-		"Gets the current balance of the wallet (Droplet mode)",
+		"Gets the current balance of the wallet (Droplit mode)",
 		{},
 		async () => {
 			try {
-				const status = await dropletClient.getFaucetStatus();
+				const status = await droplitClient.getFaucetStatus();
 
 				return {
 					content: [

package/tools/wallet/getBsv21Balances.ts

@@ -1,28 +1,34 @@
-import { getBsv21Balances, type OneSatContext } from '@1sat/actions'
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { getBsv21Balances, type OneSatContext } from "@1sat/actions";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
 export function registerGetBsv21BalancesTool(
 	server: McpServer,
 	ctx?: OneSatContext,
 ) {
 	server.tool(
-		'wallet_getBsv21Balances',
-		'Get aggregated BSV21 token balances grouped by token ID',
+		"wallet_getBsv21Balances",
+		"Get aggregated BSV21 token balances grouped by token ID",
 		{},
 		async () => {
 			try {
-				if (!ctx) throw new Error('BRC-100 wallet context not available')
-				const result = await getBsv21Balances.execute(ctx, {})
+				if (!ctx) throw new Error("BRC-100 wallet context not available");
+				const result = await getBsv21Balances.execute(ctx, {});
 				return {
-					content: [{
-						type: 'text',
-						text: JSON.stringify(result, (_, v) => typeof v === 'bigint' ? v.toString() : v, 2),
-					}],
-				}
+					content: [
+						{
+							type: "text",
+							text: JSON.stringify(
+								result,
+								(_, v) => (typeof v === "bigint" ? v.toString() : v),
+								2,
+							),
+						},
+					],
+				};
 			} catch (err: unknown) {
-				const msg = err instanceof Error ? err.message : String(err)
-				return { content: [{ type: 'text', text: msg }], isError: true }
+				const msg = err instanceof Error ? err.message : String(err);
+				return { content: [{ type: "text", text: msg }], isError: true };
 			}
 		},
-	)
+	);
 }

package/tools/wallet/getLockData.ts

@@ -1,25 +1,25 @@
-import { getLockData, type OneSatContext } from '@1sat/actions'
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { getLockData, type OneSatContext } from "@1sat/actions";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
 export function registerGetLockDataTool(
 	server: McpServer,
 	ctx?: OneSatContext,
 ) {
 	server.tool(
-		'wallet_getLockData',
-		'Get summary of time-locked BSV (total, unlockable, next unlock height)',
+		"wallet_getLockData",
+		"Get summary of time-locked BSV (total, unlockable, next unlock height)",
 		{},
 		async () => {
 			try {
-				if (!ctx) throw new Error('BRC-100 wallet context not available')
-				const result = await getLockData.execute(ctx, {})
+				if (!ctx) throw new Error("BRC-100 wallet context not available");
+				const result = await getLockData.execute(ctx, {});
 				return {
-					content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-				}
+					content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+				};
 			} catch (err: unknown) {
-				const msg = err instanceof Error ? err.message : String(err)
-				return { content: [{ type: 'text', text: msg }], isError: true }
+				const msg = err instanceof Error ? err.message : String(err);
+				return { content: [{ type: "text", text: msg }], isError: true };
 			}
 		},
-	)
+	);
 }

package/tools/wallet/getOrdinals.ts

@@ -1,35 +1,41 @@
-import { getOrdinals, type OneSatContext } from '@1sat/actions'
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
-import { z } from 'zod'
+import { listOrdinals, type OneSatContext } from "@1sat/actions";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
 
 export function registerGetOrdinalsTool(
 	server: McpServer,
 	ctx?: OneSatContext,
 ) {
 	server.tool(
-		'wallet_getOrdinals',
-		'List ordinals/inscriptions in the wallet with metadata',
+		"wallet_getOrdinals",
+		"List ordinals/inscriptions in the wallet with metadata. Each result carries an 'id:' tag; that tracking id is the handle the transfer, listing and cancel tools take.",
 		{
-			limit: z.number().int().optional().describe('Max number of results to return'),
-			offset: z.number().int().optional().describe('Number of results to skip'),
+			limit: z
+				.number()
+				.int()
+				.optional()
+				.describe("Max number of results to return"),
+			offset: z.number().int().optional().describe("Number of results to skip"),
+			tags: z
+				.array(z.string())
+				.optional()
+				.describe("Filter by output tags (e.g. 'type:image/png')"),
+			tagQueryMode: z
+				.enum(["all", "any"])
+				.optional()
+				.describe("Whether results must match all tags or any tag"),
 		},
 		async (params) => {
 			try {
-				if (!ctx) throw new Error('BRC-100 wallet context not available')
-				const result = await getOrdinals.execute(ctx, params)
-				const outputs = result.outputs.map((o: any) => ({
-					outpoint: o.outpoint,
-					satoshis: o.satoshis,
-					tags: o.tags,
-					customInstructions: o.customInstructions,
-				}))
+				if (!ctx) throw new Error("BRC-100 wallet context not available");
+				const result = await listOrdinals.execute(ctx, params);
 				return {
-					content: [{ type: 'text', text: JSON.stringify(outputs, null, 2) }],
-				}
+					content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+				};
 			} catch (err: unknown) {
-				const msg = err instanceof Error ? err.message : String(err)
-				return { content: [{ type: 'text', text: msg }], isError: true }
+				const msg = err instanceof Error ? err.message : String(err);
+				return { content: [{ type: "text", text: msg }], isError: true };
 			}
 		},
-	)
+	);
 }