bsv-mcp 0.0.4 → 0.0.6

package/package.json

@@ -2,7 +2,7 @@
 	"name": "bsv-mcp",
 	"module": "index.ts",
 	"type": "module",
-	"version": "0.0.4",
+	"version": "0.0.6",
 	"bin": {
 		"bsv-mcp": "./index.ts"
 	},

package/tools/bsv/decodeTransaction.ts

@@ -118,6 +118,7 @@ function isTxid(str: string): boolean {
 export function registerDecodeTransactionTool(server: McpServer): void {
 	server.tool(
 		"bsv_decodeTransaction",
+		"Decodes and analyzes Bitcoin SV transactions to provide detailed insights. This powerful tool accepts either a transaction ID or raw transaction data and returns comprehensive information including inputs, outputs, fee calculations, script details, and blockchain context. Supports both hex and base64 encoded transactions and automatically fetches additional on-chain data when available.",
 		{
 			args: decodeTransactionArgsSchema,
 		},

package/tools/bsv/getPrice.ts

@@ -8,8 +8,9 @@ import { z } from "zod";
 export function registerGetPriceTool(server: McpServer): void {
 	server.tool(
 		"bsv_getPrice",
+		"Retrieves the current price of Bitcoin SV (BSV) in USD from a reliable exchange API. This tool provides real-time market data that can be used for calculating transaction values, monitoring market conditions, or converting between BSV and fiat currencies.",
 		{
-			args: z.object({}).optional(),
+			args: z.object({}).optional().describe("No parameters required - simply returns the current BSV price in USD"),
 		},
 		async () => {
 			try {

package/tools/ordinals/getInscription.ts

@@ -40,6 +40,7 @@ interface InscriptionResponse {
 export function registerGetInscriptionTool(server: McpServer): void {
 	server.tool(
 		"ordinals_getInscription",
+		"Retrieves detailed information about a specific ordinal inscription by its outpoint. Returns complete inscription data including content type, file information, inscription origin, and current status. Useful for verifying NFT authenticity or retrieving metadata about digital artifacts.",
 		{
 			args: getInscriptionArgsSchema,
 		},

package/tools/ordinals/getTokenByIdOrTicker.ts

@@ -0,0 +1,109 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import { z } from "zod";
+
+// Schema for get token by ID or ticker arguments
+export const getTokenByIdOrTickerArgsSchema = z.object({
+	id: z.string().optional().describe("BSV20 token ID in outpoint format (txid_vout)"),
+	tick: z.string().optional().describe("BSV20 token ticker symbol"),
+}).refine(data => data.id || data.tick, {
+	message: "Either id or tick must be provided",
+});
+
+export type GetTokenByIdOrTickerArgs = z.infer<typeof getTokenByIdOrTickerArgsSchema>;
+
+// BSV20 token response type
+interface TokenResponse {
+	id: string;
+	tick?: string;
+	sym?: string;
+	max?: string;
+	lim?: string;
+	dec?: number;
+	supply?: string;
+	amt?: string;
+	status?: number;
+	icon?: string;
+	height?: number;
+	[key: string]: unknown;
+}
+
+/**
+ * Register the BSV20 token lookup tool
+ */
+export function registerGetTokenByIdOrTickerTool(server: McpServer): void {
+	server.tool(
+		"ordinals_getTokenByIdOrTicker",
+		"Retrieves detailed information about a specific BSV-20 token by its ID or ticker symbol. Returns complete token data including ticker symbol, supply information, decimals, and current status. This tool is useful for verifying token authenticity or checking supply metrics.",
+		{
+			args: getTokenByIdOrTickerArgsSchema,
+		},
+		async (
+			{ args }: { args: GetTokenByIdOrTickerArgs },
+			extra: RequestHandlerExtra,
+		) => {
+			try {
+				const { id, tick } = args;
+
+				// Validate that at least one of id or tick is provided
+				if (!id && !tick) {
+					throw new Error("Either token ID or ticker symbol must be provided");
+				}
+
+				// Validate ID format if provided
+				if (id && !/^[0-9a-f]{64}_\d+$/i.test(id)) {
+					throw new Error("Invalid BSV20 ID format. Expected 'txid_vout'");
+				}
+
+				// Determine which endpoint to use based on provided parameters
+				let endpoint: string;
+				if (id) {
+					endpoint = `https://ordinals.gorillapool.io/api/bsv20/id/${id}`;
+				} else {
+					endpoint = `https://ordinals.gorillapool.io/api/bsv20/tick/${tick}`;
+				}
+
+				// Fetch BSV20 token data from GorillaPool API
+				const response = await fetch(endpoint);
+
+				if (response.status === 404) {
+					return {
+						content: [
+							{
+								type: "text",
+								text: JSON.stringify({ error: "BSV20 token not found" }),
+							},
+						],
+					};
+				}
+
+				if (!response.ok) {
+					throw new Error(
+						`API error: ${response.status} ${response.statusText}`,
+					);
+				}
+
+				const data = (await response.json()) as TokenResponse;
+
+				return {
+					content: [
+						{
+							type: "text",
+							text: JSON.stringify(data, null, 2),
+						},
+					],
+				};
+			} catch (error) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: error instanceof Error ? error.message : String(error),
+						},
+					],
+					isError: true,
+				};
+			}
+		},
+	);
+}

package/tools/ordinals/index.ts

@@ -1,6 +1,6 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { registerGetBsv20ByIdTool } from "./getBsv20ById";
 import { registerGetInscriptionTool } from "./getInscription";
+import { registerGetTokenByIdOrTickerTool } from "./getTokenByIdOrTicker";
 import { registerMarketListingsTool } from "./marketListings";
 import { registerMarketSalesTool } from "./marketSales";
 import { registerSearchInscriptionsTool } from "./searchInscriptions";
@@ -15,5 +15,5 @@ export function registerOrdinalsTools(server: McpServer): void {
 	registerSearchInscriptionsTool(server);
 	registerMarketListingsTool(server);
 	registerMarketSalesTool(server);
-	registerGetBsv20ByIdTool(server);
+	registerGetTokenByIdOrTickerTool(server);
 }

package/tools/ordinals/marketListings.ts

@@ -89,6 +89,7 @@ interface MarketListingResponse {
 export function registerMarketListingsTool(server: McpServer): void {
 	server.tool(
 		"ordinals_marketListings",
+		"Retrieves current marketplace listings for Bitcoin SV ordinals with flexible filtering. Supports multiple asset types (NFTs, BSV-20 tokens, BSV-21 tokens) through a unified interface. Results include listing prices, details about the assets, and seller information.",
 		{
 			args: marketListingsArgsSchema,
 		},
@@ -130,7 +131,6 @@ export function registerMarketListingsTool(server: McpServer): void {
 				url.searchParams.append("limit", limit.toString());
 				url.searchParams.append("offset", offset.toString());
 				url.searchParams.append("dir", dir);
-				url.searchParams.append("script", "true");
 				
 				// Add sort parameter based on token type
 				if (useTokenParams) {

package/tools/ordinals/marketSales.ts

@@ -67,6 +67,7 @@ interface MarketSaleResponse {
 export function registerMarketSalesTool(server: McpServer): void {
 	server.tool(
 		"ordinals_marketSales",
+		"Retrieves recent sales data for BSV-20 and BSV-21 tokens on the ordinals marketplace. This tool provides insights into market activity, including sale prices, transaction details, and token information. Supports filtering by token ID, ticker symbol, or seller address to help analyze market trends and track specific token sales.",
 		{
 			args: marketSalesArgsSchema,
 		},
@@ -97,7 +98,6 @@ export function registerMarketSalesTool(server: McpServer): void {
 				url.searchParams.append("limit", limit.toString());
 				url.searchParams.append("offset", offset.toString());
 				url.searchParams.append("dir", dir);
-				url.searchParams.append("script", "true");
 				
 				// Add type parameter for bsv21 if needed
 				if (tokenType === "bsv21") {

package/tools/ordinals/searchInscriptions.ts

@@ -57,6 +57,7 @@ interface InscriptionSearchResponse {
 export function registerSearchInscriptionsTool(server: McpServer): void {
 	server.tool(
 		"ordinals_searchInscriptions",
+		"Searches for Bitcoin SV ordinal inscriptions using flexible criteria. This powerful search tool supports filtering by address, inscription content, MIME type, MAP fields, and other parameters. Results include detailed information about each matched inscription. Ideal for discovering NFTs and exploring the ordinals ecosystem.",
 		{
 			args: searchInscriptionsArgsSchema,
 		},

package/tools/utils/index.ts

@@ -11,11 +11,12 @@ const encodingSchema = z.enum(["utf8", "hex", "base64", "binary"]);
 export function registerUtilsTools(server: McpServer): void {
 	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.",
 		{
 			args: z.object({
-				data: z.string(),
-				from: encodingSchema,
-				to: encodingSchema,
+				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 }) => {

package/tools/wallet/createOrdinals.ts

@@ -37,6 +37,7 @@ export type CreateOrdinalsArgs = z.infer<typeof createOrdinalsArgsSchema>;
 export function registerCreateOrdinalsTool(server: McpServer, wallet: Wallet) {
 	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.",
 		{ args: createOrdinalsArgsSchema },
 		async (
 			{ args }: { args: CreateOrdinalsArgs },

package/tools/wallet/getAddress.ts

@@ -9,8 +9,9 @@ import { z } from "zod";
 export function registerGetAddressTool(server: McpServer): 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(),
+			args: z.object({}).optional().describe("No parameters required - simply returns the current wallet address"),
 		},
 		async () => {
 			try {

package/tools/wallet/purchaseListing.ts

@@ -6,6 +6,7 @@ import {
 	type ChangeResult,
 	type ExistingListing,
 	type Payment,
+	type Royalty,
 	type TokenUtxo,
 	type Utxo,
 	TokenType,
@@ -23,11 +24,27 @@ import { purchaseListingArgsSchema } from "./schemas";
 import type { Wallet } from "./wallet";
 
 // Define types for 1Sat API response
-interface ListingResponse {
+interface OrdUtxo {
 	txid: string;
 	vout: number;
 	satoshis: number;
 	script: string;
+	origin?: {
+		outpoint: string;
+		data?: {
+			map?: {
+				royalties?: string;
+				[key: string]: string | number | boolean | null | undefined;
+			};
+			insc?: {
+				text?: string;
+				file?: {
+					type?: string;
+					size?: number;
+				};
+			};
+		};
+	};
 	data?: {
 		list?: {
 			price: number;
@@ -44,13 +61,17 @@ interface ListingResponse {
 /**
  * Register the purchaseListing tool
  *
- * This tool:
+ * This tool enables purchasing listed ordinals (NFTs or tokens) from the marketplace:
  * 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 or purchaseOrdTokenListing based on the listing type
- * 5. Broadcasts the transaction
- * 6. Returns the transaction details
+ * 5. For NFTs, automatically detects and processes royalty payments to original creators
+ * 6. Broadcasts the transaction
+ * 7. Returns the transaction details including success status and txid
+ *
+ * The tool supports both NFT and token listings with appropriate type-specific handling.
+ * Royalty payments are supported for NFT purchases only (based on creator-defined metadata).
  */
 export function registerPurchaseListingTool(server: McpServer, wallet: Wallet) {
 	// Store a reference to check if wallet is persistent
@@ -58,6 +79,7 @@ export function registerPurchaseListingTool(server: McpServer, wallet: Wallet) {
 
 	server.tool(
 		"wallet_purchaseListing",
+		"Purchases a listing from the Bitcoin SV ordinals marketplace. Supports both NFT purchases (with royalty payments to original creators) and BSV-20/BSV-21 token purchases. The tool handles all aspects of the transaction - from fetching listing details, calculating fees, creating and broadcasting the transaction.",
 		{ args: purchaseListingArgsSchema },
 		async (
 			{ args }: { args: z.infer<typeof purchaseListingArgsSchema> },
@@ -79,7 +101,7 @@ export function registerPurchaseListingTool(server: McpServer, wallet: Wallet) {
 					);
 				}
 
-				const listingData = (await response.json()) as ListingResponse;
+				const listingData = (await response.json()) as OrdUtxo;
 
 				// Check if the listing is valid and has a price
 				if (!listingData.data?.list?.price) {
@@ -183,7 +205,7 @@ Please fund this wallet address with enough BSV to cover the purchase price
 						satoshis: 1, // TokenUtxo's satoshis must be exactly 1
 						amt: listingData.data.bsv20.amt,
 						id: args.tokenID,
-            payout: listingData.data.list.payout,
+						payout: listingData.data.list.payout,
 					};
 					
 					transaction = await purchaseOrdTokenListing({
@@ -211,6 +233,19 @@ Please fund this wallet address with enough BSV to cover the purchase price
 						listingUtxo,
 					};
 					
+					// Check for royalties in the NFT origin data
+					// Royalties are only supported for NFTs, not for tokens
+					// The royalties are defined by the original creator as a JSON string
+					// in the NFT's metadata and parsed into a Royalty[] array
+					let royalties: Royalty[] = [];
+					if (listingData.origin?.data?.map?.royalties) {
+						try {
+							royalties = JSON.parse(listingData.origin.data.map.royalties);
+						} catch (error) {
+							console.warn("Failed to parse royalties:", error);
+						}
+					}
+					
 					transaction = await purchaseOrdListing({
 						utxos: paymentUtxos,
 						paymentPk,
@@ -218,6 +253,7 @@ Please fund this wallet address with enough BSV to cover the purchase price
 						listing,
 						additionalPayments,
 						metaData,
+						royalties,
 					});
 				}
 
@@ -264,6 +300,8 @@ Please fund this wallet address with enough BSV to cover the purchase price
 								price: listingData.data.list.price,
 								marketFee,
 								marketFeeAddress: MARKET_WALLET_ADDRESS,
+								royaltiesPaid: args.listingType === "nft" && listingData.origin?.data?.map?.royalties ? 
+									JSON.parse(listingData.origin.data.map.royalties) : undefined,
 							}),
 						},
 					],

package/tools/wallet/schemas.ts

@@ -291,7 +291,7 @@ export const purchaseListingArgsSchema = z.object({
 		.string()
 		.optional()
 		.describe("Optional description for the transaction"),
-});
+}).describe("Schema for the wallet_purchaseListing tool arguments (purchase NFTs or tokens), with detailed field descriptions.");
 
 // Export types
 export type SendToAddressArgs = z.infer<typeof sendToAddressArgsSchema>;

package/tools/wallet/sendOrdinals.ts

@@ -26,6 +26,7 @@ export type SendOrdinalsArgs = z.infer<typeof sendOrdinalsArgsSchema>;
 export function registerSendOrdinalsTool(server: McpServer, wallet: Wallet) {
   server.tool(
     "wallet_sendOrdinals",
+    "Transfers ordinals (NFTs) from your wallet to another address on the Bitcoin SV blockchain. This tool enables sending inscriptions you own to any valid BSV address. The transaction is created, signed, and broadcast automatically, with appropriate fee calculation and change handling.",
     { args: sendOrdinalsArgsSchema },
     async (
       { args }: { args: SendOrdinalsArgs },

package/tools/wallet/sendToAddress.ts

@@ -42,6 +42,7 @@ export type SendToAddressArgs = z.infer<typeof sendToAddressArgsSchema>;
 export function registerSendToAddressTool(server: McpServer, wallet: Wallet) {
 	server.tool(
 		"wallet_sendToAddress",
+		"Sends Bitcoin SV (BSV) to a specified address. This tool supports payments in both BSV and USD amounts (with automatic conversion using current exchange rates). Transaction fees are automatically calculated and a confirmation with transaction ID is returned upon success.",
 		{
 			args: sendToAddressArgsSchema,
 		},

package/tools/ordinals/getBsv20ById.ts

@@ -1,94 +0,0 @@
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
-import { z } from "zod";
-
-// Schema for get BSV20 by ID arguments
-export const getBsv20ByIdArgsSchema = z.object({
-	id: z.string().describe("BSV20 token ID in outpoint format (txid_vout)"),
-});
-
-export type GetBsv20ByIdArgs = z.infer<typeof getBsv20ByIdArgsSchema>;
-
-// BSV20 token response type
-interface Bsv20TokenResponse {
-	id: string;
-	tick?: string;
-	sym?: string;
-	max?: string;
-	lim?: string;
-	dec?: number;
-	supply?: string;
-	amt?: string;
-	status?: number;
-	icon?: string;
-	height?: number;
-	[key: string]: unknown;
-}
-
-/**
- * Register the BSV20 token lookup tool
- */
-export function registerGetBsv20ByIdTool(server: McpServer): void {
-	server.tool(
-		"ordinals_getBsv20ById",
-		{
-			args: getBsv20ByIdArgsSchema,
-		},
-		async (
-			{ args }: { args: GetBsv20ByIdArgs },
-			extra: RequestHandlerExtra,
-		) => {
-			try {
-				const { id } = args;
-
-				// Validate ID format (should be in outpoint format)
-				if (!/^[0-9a-f]{64}_\d+$/i.test(id)) {
-					throw new Error("Invalid BSV20 ID format. Expected 'txid_vout'");
-				}
-
-				// Fetch BSV20 token data from GorillaPool API
-				const response = await fetch(
-					`https://ordinals.gorillapool.io/api/bsv20/id/${id}`,
-				);
-
-				if (response.status === 404) {
-					return {
-						content: [
-							{
-								type: "text",
-								text: JSON.stringify({ error: "BSV20 token not found" }),
-							},
-						],
-					};
-				}
-
-				if (!response.ok) {
-					throw new Error(
-						`API error: ${response.status} ${response.statusText}`,
-					);
-				}
-
-				const data = (await response.json()) as Bsv20TokenResponse;
-
-				return {
-					content: [
-						{
-							type: "text",
-							text: JSON.stringify(data, null, 2),
-						},
-					],
-				};
-			} catch (error) {
-				return {
-					content: [
-						{
-							type: "text",
-							text: error instanceof Error ? error.message : String(error),
-						},
-					],
-					isError: true,
-				};
-			}
-		},
-	);
-}