bsv-mcp 0.0.2 → 0.0.3

package/README.md

@@ -154,7 +154,8 @@ Wallet tools provide core BSV wallet functionality:
 | `wallet_decrypt` | Decrypts data using a specified protocol and key |
 | `wallet_getAddress` | Returns a BSV address for the current wallet or a derived path |
 | `wallet_sendToAddress` | Sends BSV to a specified address (supports BSV or USD amounts) |
-| `wallet_purchaseListing` | Purchases an NFT from a marketplace listing |
+| `wallet_purchaseListing` | Purchases NFTs or BSV-20/BSV-21 tokens from marketplace listings |
+| `wallet_createOrdinals` | Creates and inscribes ordinals on the BSV blockchain |
 
 ### BSV Tools
 
@@ -173,8 +174,8 @@ Tools for working with ordinals (NFTs) on BSV:
 |-----------|-------------|
 | `ordinals_getInscription` | Retrieves detailed information about a specific inscription |
 | `ordinals_searchInscriptions` | Searches for inscriptions based on various criteria |
-| `ordinals_marketListings` | Retrieves current marketplace listings for inscriptions |
-| `ordinals_bsv20MarketSales` | Gets information about BSV20 token market sales |
+| `ordinals_marketListings` | Retrieves market listings for NFTs, BSV-20, and BSV-21 tokens with unified interface |
+| `ordinals_marketSales` | Gets information about BSV-20 and BSV-21 token market sales |
 | `ordinals_getBsv20ById` | Retrieves details about a specific BSV20 token by ID |
 
 ### Utility Tools
@@ -193,11 +194,15 @@ Once connected, you can use natural language to interact with Bitcoin SV through
 - "Get my Bitcoin SV address"
 - "Send 0.01 BSV to 1ExampleBsvAddressXXXXXXXXXXXXXXXXX"
 - "Send $5 USD worth of BSV to 1ExampleBsvAddressXXXXXXXXXXXXXXXXX"
+- "Purchase this NFT listing: txid_vout"
+- "Purchase this BSV-20 token listing: txid_vout"
 
 ### Ordinals (NFTs)
 - "Show me information about the NFT with outpoint 6a89047af2cfac96da17d51ae8eb62c5f1d982be2bc4ba0d0cd2084b7ffed325_0"
 - "Search for Pixel Zoide NFTs"
 - "Show me the current marketplace listings for BSV NFTs"
+- "Show me BSV-20 token listings for ticker PEPE"
+- "Get recent BSV-20 token sales"
 
 ### Blockchain Operations
 - "What is the current BSV price?"
@@ -232,6 +237,17 @@ tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
 
 For Cursor, check the Cursor MCP logs in Settings → Extensions → Model Context Protocol.
 
+## Recent Updates
+
+### Enhanced Marketplace Tools
+- **Unified Market Listings**: The `ordinals_marketListings` tool now supports NFTs, BSV-20, and BSV-21 tokens through a single interface with appropriate filtering.
+- **Improved Market Sales**: The `ordinals_marketSales` tool (renamed from `ordinals_bsv20MarketSales`) now supports both BSV-20 and BSV-21 token sales.
+- **Token Purchases**: The `wallet_purchaseListing` tool has been enhanced to support purchasing both NFTs and BSV-20/BSV-21 tokens.
+
+### API Refinements
+- Standardized endpoint structure for interactions with the GorillaPool API.
+- Improved parameter handling for different token types and marketplace actions.
+
 ## Development
 
 This project was created using `bun init` in bun v1.2.9. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.

package/package.json

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

package/tools/ordinals/index.ts

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

package/tools/ordinals/marketListings.ts

@@ -2,8 +2,9 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
 import { z } from "zod";
 
-// Schema for market listings arguments
+// Enhanced schema for unified market listings arguments
 export const marketListingsArgsSchema = z.object({
+	// Common parameters
 	limit: z
 		.number()
 		.int()
@@ -12,29 +13,47 @@ export const marketListingsArgsSchema = z.object({
 		.default(20)
 		.describe("Number of results (1-100, default 20)"),
 	offset: z.number().int().min(0).default(0).describe("Pagination offset"),
-	sort: z
-		.enum(["recent", "price", "num"])
-		.default("recent")
-		.describe("Sort method (recent, price, or num)"),
 	dir: z
 		.enum(["asc", "desc"])
 		.default("desc")
 		.describe("Sort direction (asc or desc)"),
 	address: z.string().optional().describe("Bitcoin address"),
+	
+	// NFT-specific parameters
 	origin: z.string().optional().describe("Origin outpoint"),
 	mime: z.string().optional().describe("MIME type filter"),
 	num: z.string().optional().describe("Inscription number"),
+	
+	// General market parameters
 	minPrice: z.number().optional().describe("Minimum price in satoshis"),
 	maxPrice: z.number().optional().describe("Maximum price in satoshis"),
+	
+	// Token-specific parameters
+	tokenType: z
+		.enum(["nft", "bsv20", "bsv21", "all"])
+		.default("all")
+		.describe("Type of token to search for (nft, bsv20, bsv21, or all)"),
+	sort: z
+		.enum(["recent", "price", "num", "height", "price_per_token"])
+		.default("recent")
+		.describe("Sort method (recent, price, num, height, price_per_token)"),
+	bsv20Type: z
+		.enum(["v1", "v2", "all"])
+		.default("all")
+		.optional()
+		.describe("BSV20 token type (v1, v2, or all)"),
+	id: z.string().optional().describe("Token ID in outpoint format"),
+	tick: z.string().optional().describe("Token ticker symbol"),
+	pending: z.boolean().default(false).optional().describe("Include pending sales"),
 });
 
 export type MarketListingsArgs = z.infer<typeof marketListingsArgsSchema>;
 
-// Simplified market listing response type
+// Unified response type that covers all token types
 interface MarketListingResponse {
 	results: Array<{
 		outpoint: string;
-		origin: {
+		origin?: {
 			outpoint: string;
 			data?: {
 				insc?: {
@@ -51,16 +70,26 @@ interface MarketListingResponse {
 				price?: number;
 				payout?: string;
 				sale?: boolean;
+				price_per_token?: number;
+			};
+			bsv20?: {
+				id?: string;
+				tick?: string;
+				sym?: string;
+				amt?: string;
+				op?: string;
 			};
 		};
 		satoshis?: number;
+		height?: number;
 		[key: string]: unknown;
 	}>;
 	total: number;
 }
 
 /**
- * Register the Ordinals market listings tool
+ * Register the unified Ordinals market listings tool
+ * Handles NFTs, BSV20, and BSV21 tokens
  */
 export function registerMarketListingsTool(server: McpServer): void {
 	server.tool(
@@ -84,25 +113,68 @@ export function registerMarketListingsTool(server: McpServer): void {
 					num,
 					minPrice,
 					maxPrice,
+					tokenType,
+					bsv20Type,
+					id,
+					tick,
+					pending,
 				} = args;
 
+				// Determine the API endpoint based on tokenType
+				let baseUrl = "https://ordinals.gorillapool.io/api";
+				let useTokenParams = false;
+				
+				if (tokenType === "bsv20") {
+					baseUrl += "/bsv20/market";
+					useTokenParams = true;
+				} else if (tokenType === "bsv21") {
+					baseUrl += "/bsv21/market"; // Assuming BSV21 endpoint follows similar pattern
+					useTokenParams = true;
+				} else if (tokenType === "nft" || tokenType === "all") {
+					baseUrl += "/market";
+				}
+
 				// Build the URL with query parameters
-				const url = new URL("https://ordinals.gorillapool.io/api/market");
+				const url = new URL(baseUrl);
 				url.searchParams.append("limit", limit.toString());
 				url.searchParams.append("offset", offset.toString());
-				url.searchParams.append("sort", sort);
 				url.searchParams.append("dir", dir);
-
+				
+				// Add sort parameter based on token type
+				if (useTokenParams) {
+					// BSV20/BSV21 specific sort options
+					if (sort === "height" || sort === "price" || sort === "price_per_token") {
+						url.searchParams.append("sort", sort);
+					}
+					// Add token-specific parameters
+					if (bsv20Type && bsv20Type !== "all") {
+						url.searchParams.append("type", bsv20Type);
+					}
+					if (id) url.searchParams.append("id", id);
+					if (tick) url.searchParams.append("tick", tick);
+					if (pending !== undefined) url.searchParams.append("pending", pending.toString());
+					// For BSV20/21, min/max price parameters have slightly different names
+					if (minPrice !== undefined) url.searchParams.append("min_price", minPrice.toString());
+					if (maxPrice !== undefined) url.searchParams.append("max_price", maxPrice.toString());
+				} else {
+					// NFT specific sort options
+					if (sort === "recent" || sort === "price" || sort === "num") {
+						url.searchParams.append("sort", sort);
+					}
+					// Add NFT-specific parameters
+					if (origin) url.searchParams.append("origin", origin);
+					if (mime) url.searchParams.append("mime", mime);
+					if (num) url.searchParams.append("num", num);
+					// For NFTs, min/max price parameters use short names
+					if (minPrice !== undefined) url.searchParams.append("min", minPrice.toString());
+					if (maxPrice !== undefined) url.searchParams.append("max", maxPrice.toString());
+				}
+				
+				// Add common parameters
 				if (address) url.searchParams.append("address", address);
-				if (origin) url.searchParams.append("origin", origin);
-				if (mime) url.searchParams.append("mime", mime);
-				if (num) url.searchParams.append("num", num);
-				if (minPrice !== undefined)
-					url.searchParams.append("min", minPrice.toString());
-				if (maxPrice !== undefined)
-					url.searchParams.append("max", maxPrice.toString());
 
-				// Fetch market listings from GorillaPool API
+				// Make the fetch request
+				console.log(`Fetching market listings from: ${url.toString()}`);
 				const response = await fetch(url.toString());
 
 				if (!response.ok) {

package/tools/ordinals/{bsv20MarketSales.ts → marketSales.ts}

@@ -2,8 +2,9 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
 import { z } from "zod";
 
-// Schema for BSV20 market sales arguments
-export const bsv20MarketSalesArgsSchema = z.object({
+// Schema for unified market sales arguments
+export const marketSalesArgsSchema = z.object({
+	// Common parameters
 	limit: z
 		.number()
 		.int()
@@ -16,20 +17,27 @@ export const bsv20MarketSalesArgsSchema = z.object({
 		.enum(["asc", "desc"])
 		.default("desc")
 		.describe("Sort direction (asc or desc)"),
-	type: z
+	address: z.string().optional().describe("Bitcoin address"),
+
+	// Token-specific parameters
+	tokenType: z
+		.enum(["bsv20", "bsv21", "all"])
+		.default("bsv20")
+		.describe("Type of token to search for (bsv20, bsv21, or all)"),
+	bsv20Type: z
 		.enum(["v1", "v2", "all"])
 		.default("all")
-		.describe("Token type (v1, v2, or all)"),
+		.optional()
+		.describe("BSV20 token type (v1, v2, or all)"),
 	id: z.string().optional().describe("Token ID in outpoint format"),
 	tick: z.string().optional().describe("Token ticker symbol"),
-	pending: z.boolean().default(false).describe("Include pending sales"),
-	address: z.string().optional().describe("Bitcoin address"),
+	pending: z.boolean().default(false).optional().describe("Include pending sales"),
 });
 
-export type Bsv20MarketSalesArgs = z.infer<typeof bsv20MarketSalesArgsSchema>;
+export type MarketSalesArgs = z.infer<typeof marketSalesArgsSchema>;
 
-// Simplified BSV20 sale response type
-interface Bsv20SaleResponse {
+// Unified response type for token sales
+interface MarketSaleResponse {
 	results: Array<{
 		outpoint: string;
 		data?: {
@@ -48,42 +56,70 @@ interface Bsv20SaleResponse {
 		};
 		satoshis?: number;
 		height?: number;
+		owner?: string;
+		spend?: string;
+		spendHeight?: number;
+		spendIdx?: string;
 		[key: string]: unknown;
 	}>;
 	total: number;
 }
 
 /**
- * Register the BSV20 market sales tool
+ * Register the unified market sales tool
+ * Handles BSV20 and BSV21 token sales
  */
-export function registerBsv20MarketSalesTool(server: McpServer): void {
+export function registerMarketSalesTool(server: McpServer): void {
 	server.tool(
-		"ordinals_bsv20MarketSales",
+		"ordinals_marketSales",
 		{
-			args: bsv20MarketSalesArgsSchema,
+			args: marketSalesArgsSchema,
 		},
 		async (
-			{ args }: { args: Bsv20MarketSalesArgs },
+			{ args }: { args: MarketSalesArgs },
 			extra: RequestHandlerExtra,
 		) => {
 			try {
-				const { limit, offset, dir, type, id, tick, pending, address } = args;
+				const { 
+					limit, 
+					offset, 
+					dir, 
+					tokenType, 
+					bsv20Type, 
+					id, 
+					tick, 
+					pending, 
+					address 
+				} = args;
+
+				// Determine the API endpoint based on tokenType
+				let baseUrl = "https://ordinals.gorillapool.io/api";
+				
+				if (tokenType === "bsv21") {
+					baseUrl += "/bsv21/market/sales";
+				} else {
+					// Default to BSV20 for "bsv20" or "all"
+					baseUrl += "/bsv20/market/sales";
+				}
 
 				// Build the URL with query parameters
-				const url = new URL(
-					"https://ordinals.gorillapool.io/api/bsv20/market/sales",
-				);
+				const url = new URL(baseUrl);
 				url.searchParams.append("limit", limit.toString());
 				url.searchParams.append("offset", offset.toString());
 				url.searchParams.append("dir", dir);
-				url.searchParams.append("type", type);
-				url.searchParams.append("pending", pending.toString());
+				
+				// Add type parameter for bsv20 only if specified
+				if (bsv20Type && bsv20Type !== "all") {
+					url.searchParams.append("type", bsv20Type);
+				}
 
 				if (id) url.searchParams.append("id", id);
 				if (tick) url.searchParams.append("tick", tick);
+				if (pending !== undefined) url.searchParams.append("pending", pending.toString());
 				if (address) url.searchParams.append("address", address);
 
-				// Fetch BSV20 market sales from GorillaPool API
+				// Fetch market sales from GorillaPool API
+				console.log(`Fetching market sales from: ${url.toString()}`);
 				const response = await fetch(url.toString());
 
 				if (!response.ok) {
@@ -92,7 +128,7 @@ export function registerBsv20MarketSalesTool(server: McpServer): void {
 					);
 				}
 
-				const data = (await response.json()) as Bsv20SaleResponse;
+				const data = (await response.json()) as MarketSaleResponse;
 
 				return {
 					content: [

package/tools/wallet/purchaseListing.ts

@@ -3,11 +3,15 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import {
+	type ChangeResult,
 	type ExistingListing,
 	type Payment,
+	type TokenUtxo,
 	type Utxo,
+	TokenType,
 	oneSatBroadcaster,
 	purchaseOrdListing,
+	purchaseOrdTokenListing,
 } from "js-1sat-ord";
 import type { z } from "zod";
 import {
@@ -29,6 +33,11 @@ interface ListingResponse {
 			price: number;
 			payout: string;
 		};
+		bsv20?: {
+			amt?: string;
+			tick?: string;
+			id?: string;
+		};
 	};
 }
 
@@ -39,7 +48,7 @@ interface ListingResponse {
  * 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 with market fee
+ * 4. Uses purchaseOrdListing or purchaseOrdTokenListing based on the listing type
  * 5. Broadcasts the transaction
  * 6. Returns the transaction details
  */
@@ -56,6 +65,7 @@ export function registerPurchaseListingTool(server: McpServer, wallet: Wallet) {
 		): Promise<CallToolResult> => {
 			try {
 				console.log(`Attempting to purchase listing: ${args.listingOutpoint}`);
+				console.log(`Listing type: ${args.listingType}`);
 				console.log("Using wallet instance:", wallet);
 				console.log("Wallet has UTXOs:", await wallet.getUtxos());
 
@@ -102,20 +112,6 @@ export function registerPurchaseListingTool(server: McpServer, wallet: Wallet) {
 				}
 				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) {
@@ -152,15 +148,77 @@ Please fund this wallet address with enough BSV to cover the purchase price
 					op: "purchase",
 				};
 
-				// Create the purchase transaction using the library's config type
-				const transaction = await purchaseOrdListing({
-					utxos: paymentUtxos,
-					paymentPk,
-					ordAddress: args.ordAddress,
-					listing,
-					additionalPayments,
-					metaData,
-				});
+				// Create the purchase transaction based on listing type
+				let transaction: ChangeResult;
+				
+				if (args.listingType === "token") {
+					if (!args.tokenProtocol) {
+						throw new Error("tokenProtocol is required for token listings");
+					}
+					
+					if (!args.tokenID) {
+						throw new Error("tokenID is required for token listings");
+					}
+					
+					// Validate token data from the listing
+					if (!listingData.data.bsv20) {
+						throw new Error("This is not a valid BSV-20 token listing");
+					}
+					
+					// For BSV-20, the amount should be included in the listing data
+					if (!listingData.data.bsv20.amt) {
+						throw new Error("Token listing doesn't have an amount specified");
+					}
+					
+					// Convert the token protocol to the enum type expected by js-1sat-ord
+					const protocol = args.tokenProtocol === "bsv-20" 
+						? TokenType.BSV20
+						: TokenType.BSV21;
+					
+					// Create a TokenUtxo with the required fields
+					const listingUtxo: TokenUtxo = {
+						txid,
+						vout,
+						script: listingData.script,
+						satoshis: 1, // TokenUtxo's satoshis must be exactly 1
+						amt: listingData.data.bsv20.amt,
+						id: args.tokenID,
+					};
+					
+					transaction = await purchaseOrdTokenListing({
+						protocol,
+						tokenID: args.tokenID,
+						utxos: paymentUtxos,
+						paymentPk,
+						listingUtxo,
+						ordAddress: args.ordAddress,
+						additionalPayments,
+						metaData,
+					});
+				} else {
+					// Create a regular Utxo for NFT listing
+					const listingUtxo: Utxo = {
+						txid,
+						vout,
+						script: listingData.script,
+						satoshis: listingData.satoshis,
+					};
+					
+					// Create the ExistingListing object for NFT listings
+					const listing: ExistingListing = {
+						payout: listingData.data.list.payout,
+						listingUtxo,
+					};
+					
+					transaction = await purchaseOrdListing({
+						utxos: paymentUtxos,
+						paymentPk,
+						ordAddress: args.ordAddress,
+						listing,
+						additionalPayments,
+						metaData,
+					});
+				}
 
 				// After successful transaction creation, refresh the wallet's UTXOs
 				// This ensures the wallet doesn't try to reuse spent UTXOs
@@ -199,6 +257,9 @@ Please fund this wallet address with enough BSV to cover the purchase price
 								txid: transaction.tx.id("hex"),
 								listingOutpoint: args.listingOutpoint,
 								destinationAddress: args.ordAddress,
+								listingType: args.listingType,
+								tokenProtocol: args.tokenID ? args.tokenProtocol : undefined,
+								tokenID: args.tokenID,
 								price: listingData.data.list.price,
 								marketFee,
 								marketFeeAddress: MARKET_WALLET_ADDRESS,

package/tools/wallet/schemas.ts

@@ -279,6 +279,18 @@ export const purchaseListingArgsSchema = z.object({
 		.string()
 		.optional()
 		.describe("Optional description for the transaction"),
+	listingType: z
+		.enum(["nft", "token"])
+		.default("nft")
+		.describe("Type of listing: 'nft' for ordinal NFTs, 'token' for BSV-20 tokens"),
+	tokenProtocol: z
+		.enum(["bsv-20", "bsv-21"])
+		.optional()
+		.describe("Token protocol for token listings (required when listingType is 'token')"),
+	tokenID: z
+		.string()
+		.optional()
+		.describe("Token ID for BSV-21 tokens or ticker for BSV-20 tokens (required when listingType is 'token')"),
 });
 
 export type PurchaseListingArgs = z.infer<typeof purchaseListingArgsSchema>;

package/tools/wallet/tools.ts

@@ -40,8 +40,6 @@ import type { createOrdinalsArgsSchema } from "./createOrdinals";
 import { registerGetAddressTool } from "./getAddress";
 import { registerPurchaseListingTool } from "./purchaseListing";
 import { registerSendToAddressTool } from "./sendToAddress";
-import { registerSendOrdinalsTool } from "./sendOrdinals";
-import type { sendOrdinalsArgsSchema } from "./sendOrdinals";
 
 // Define mapping from tool names to argument schemas
 type ToolArgSchemas = {
@@ -74,7 +72,6 @@ type ToolArgSchemas = {
 	wallet_sendToAddress: typeof sendToAddressArgsSchema;
 	wallet_purchaseListing: typeof purchaseListingArgsSchema;
 	wallet_createOrdinals: typeof createOrdinalsArgsSchema;
-	wallet_sendOrdinals: typeof sendOrdinalsArgsSchema;
 };
 
 // Define a type for the handler function with proper argument types
@@ -210,8 +207,6 @@ export function registerWalletTools(
 	// Register ordinals extension tools
 	// Register the wallet_createOrdinals tool
 	registerCreateOrdinalsTool(server, wallet);
-	// Register the wallet_sendOrdinals tool
-	registerSendOrdinalsTool(server, wallet);
 
 	return handlers;
 }