bsv-mcp 0.0.5 → 0.0.7

package/README.md

@@ -14,16 +14,6 @@ To install dependencies:
 bun install
 ```
 
-For global installation (recommended for MCP client integration):
-
-```bash
-# Install globally with bun
-bun install -g bsv-mcp
-
-# Or with npm
-npm install -g bsv-mcp
-```
-
 ## External Dependencies
 
 For full functionality of all tools, the following additional dependencies are installed:
@@ -38,11 +28,7 @@ js-1sat-ord
 Start the MCP server:
 
 ```bash
-# If installed locally
 bun run index.ts
-
-# If installed globally
-bunx bsv-mcp
 ```
 
 ## Connecting to MCP Clients
@@ -54,7 +40,7 @@ This server implements the [Model Context Protocol](https://modelcontextprotocol
 To use the BSV MCP server with [Cursor](https://cursor.sh/):
 
 1. Install Cursor if you haven't already
-2. Install this package globally: `bun install -g bsv-mcp`
+2. Clone this repository and run `bun install` in the project directory
 3. Open Cursor and navigate to Settings → Extensions → Model Context Protocol
 4. Click "Add a new global MCP server"
 5. Enter the following configuration in JSON format:
@@ -65,15 +51,17 @@ To use the BSV MCP server with [Cursor](https://cursor.sh/):
     "command": "env",
     "args": [
       "PRIVATE_KEY_WIF=<your_private_key_wif>",
-      "bunx",
-      "bsv-mcp"
+      "bun",
+      "run",
+      "<path_to_project>/index.ts"
     ]
   }
 }
 ```
 
 6. Replace `<your_private_key_wif>` with your actual private key WIF (keep this secure!)
-7. Click "Save"
+7. Replace `<path_to_project>` with the full path to where you cloned this repository
+8. Click "Save"
 
 The BSV tools will now be available to Cursor's AI assistant under the "Bitcoin SV" namespace.
 
@@ -82,7 +70,7 @@ The BSV tools will now be available to Cursor's AI assistant under the "Bitcoin
 To connect this server to Claude for Desktop:
 
 1. Ensure you have [Claude for Desktop](https://claude.ai/desktop) installed and updated to the latest version
-2. Install this package globally: `bun install -g bsv-mcp`
+2. Clone this repository and run `bun install` in the project directory
 3. Open your Claude for Desktop configuration file:
    ```bash
    # macOS/Linux
@@ -99,16 +87,18 @@ To connect this server to Claude for Desktop:
          "command": "env",
          "args": [
            "PRIVATE_KEY_WIF=<your_private_key_wif>",
-           "bunx",
-           "bsv-mcp"
+           "bun",
+           "run",
+           "<path_to_project>/index.ts"
          ]
        }
      }
    }
    ```
 5. Replace `<your_private_key_wif>` with your actual private key WIF
-6. Save the file and restart Claude for Desktop
-7. The BSV tools will appear when you click the tools icon (hammer) in Claude for Desktop
+6. Replace `<path_to_project>` with the full path to where you cloned this repository
+7. Save the file and restart Claude for Desktop
+8. The BSV tools will appear when you click the tools icon (hammer) in Claude for Desktop
 
 ### Generic MCP Client Integration
 
@@ -120,8 +110,9 @@ For other MCP clients that support JSON configuration:
     "command": "env",
     "args": [
       "PRIVATE_KEY_WIF=<your_private_key_wif>",
-      "bunx",
-      "bsv-mcp"
+      "bun",
+      "run",
+      "<path_to_project>/index.ts"
     ]
   }
 }
@@ -134,7 +125,7 @@ If running the server directly:
 export PRIVATE_KEY_WIF=<your_private_key_wif>
 
 # Then run the server
-bunx bsv-mcp
+bun run index.ts
 ```
 
 ## Available Tools
@@ -225,7 +216,7 @@ When you interact with an MCP-enabled AI assistant:
 
 If you're having issues connecting to the server:
 
-1. Ensure the package is properly installed: `bun install -g bsv-mcp`
+1. Ensure the package dependencies are properly installed: `bun install`
 2. Verify your WIF private key is correctly set in the environment
 3. Check that your client supports MCP and is properly configured
 4. Look for error messages in the client's console output
@@ -254,18 +245,7 @@ This project was created using `bun init` in bun v1.2.9. [Bun](https://bun.sh) i
 
 ### Package Configuration
 
-To ensure the package can be run with `bunx bsv-mcp`, make sure your `package.json` includes:
-
-```json
-{
-  "name": "bsv-mcp",
-  "bin": {
-    "bsv-mcp": "./index.ts"
-  },
-  "type": "module"
-  // ...other configuration
-}
-```
+The main entry point for this package is `index.ts`.
 
 ### Running Tests
 

package/package.json

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

package/smithery.yaml

@@ -0,0 +1,21 @@
+startCommand:
+  type: stdio
+  configSchema:
+    type: object
+    required:
+      - privateKeyWif
+    properties:
+      privateKeyWif:
+        type: string
+        description: "Your private key WIF (Wallet Import Format) for Bitcoin SV transactions. This key is used to sign transactions and is required for wallet operations."
+  commandFunction: |
+    (config) => ({
+      "command": "bun",
+      "args": [
+        "run",
+        "index.ts"
+      ],
+      "env": {
+        "PRIVATE_KEY_WIF": config.privateKeyWif
+      }
+    })

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,
 		},

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,
 		},

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

@@ -61,13 +61,17 @@ interface OrdUtxo {
 /**
  * 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
@@ -75,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> },
@@ -200,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({
@@ -229,6 +234,9 @@ Please fund this wallet address with enough BSV to cover the purchase price
 					};
 					
 					// 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 {

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,
-				};
-			}
-		},
-	);
-}