bsv-mcp 0.0.1

package/README.md

@@ -0,0 +1,258 @@
+# Bitcoin SV MCP Server
+
+A collection of Bitcoin SV (BSV) tools for the Model Context Protocol (MCP) framework. This library provides wallet, ordinals, and utility functions for BSV blockchain interaction.
+
+## Installation
+
+To install dependencies:
+
+```bash
+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:
+
+```bash
+# For ordinal listing purchase functionality
+js-1sat-ord
+```
+
+## Running the Server
+
+Start the MCP server:
+
+```bash
+# If installed locally
+bun run index.ts
+
+# If installed globally
+bunx bsv-mcp
+```
+
+## Connecting to MCP Clients
+
+This server implements the [Model Context Protocol](https://modelcontextprotocol.io/) (MCP), allowing AI assistants to utilize Bitcoin SV functionalities. You can connect this server to various MCP-compatible clients.
+
+### Cursor
+
+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`
+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:
+
+```json
+{
+  "Bitcoin SV": {
+    "command": "env",
+    "args": [
+      "PRIVATE_KEY_WIF=<your_private_key_wif>",
+      "bunx",
+      "bsv-mcp"
+    ]
+  }
+}
+```
+
+6. Replace `<your_private_key_wif>` with your actual private key WIF (keep this secure!)
+7. Click "Save"
+
+The BSV tools will now be available to Cursor's AI assistant under the "Bitcoin SV" namespace.
+
+### Claude for Desktop
+
+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`
+3. Open your Claude for Desktop configuration file:
+   ```bash
+   # macOS/Linux
+   code ~/Library/Application\ Support/Claude/claude_desktop_config.json
+   
+   # Windows
+   code %APPDATA%\Claude\claude_desktop_config.json
+   ```
+4. Add the BSV MCP server to your configuration (create the file if it doesn't exist):
+   ```json
+   {
+     "mcpServers": {
+       "Bitcoin SV": {
+         "command": "env",
+         "args": [
+           "PRIVATE_KEY_WIF=<your_private_key_wif>",
+           "bunx",
+           "bsv-mcp"
+         ]
+       }
+     }
+   }
+   ```
+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
+
+### Generic MCP Client Integration
+
+For other MCP clients that support JSON configuration:
+
+```json
+{
+  "Bitcoin SV": {
+    "command": "env",
+    "args": [
+      "PRIVATE_KEY_WIF=<your_private_key_wif>",
+      "bunx",
+      "bsv-mcp"
+    ]
+  }
+}
+```
+
+If running the server directly:
+
+```bash
+# Set environment variable first
+export PRIVATE_KEY_WIF=<your_private_key_wif>
+
+# Then run the server
+bunx bsv-mcp
+```
+
+## Available Tools
+
+The toolkit is organized into several categories:
+
+### Wallet Tools
+
+Wallet tools provide core BSV wallet functionality:
+
+| Tool Name | Description |
+|-----------|-------------|
+| `wallet_getPublicKey` | Retrieves a public key for a specified protocol and key ID |
+| `wallet_createSignature` | Creates a cryptographic signature for the provided data |
+| `wallet_verifySignature` | Verifies a cryptographic signature against the provided data |
+| `wallet_encrypt` | Encrypts data using a specified protocol and key |
+| `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 |
+
+### BSV Tools
+
+Tools for interacting with the BSV blockchain and network:
+
+| Tool Name | Description |
+|-----------|-------------|
+| `bsv_getPrice` | Gets the current BSV price from an exchange API |
+| `bsv_decodeTransaction` | Decodes a BSV transaction and returns detailed information |
+
+### Ordinals Tools
+
+Tools for working with ordinals (NFTs) on BSV:
+
+| Tool Name | Description |
+|-----------|-------------|
+| `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_getBsv20ById` | Retrieves details about a specific BSV20 token by ID |
+
+### Utility Tools
+
+General-purpose utility functions:
+
+| Tool Name | Description |
+|-----------|-------------|
+| `utils_convertData` | Converts data between different encodings (utf8, hex, base64, binary) |
+
+## Using the Tools with MCP
+
+Once connected, you can use natural language to interact with Bitcoin SV through your AI assistant. Here are some example prompts:
+
+### Wallet Operations
+- "Get my Bitcoin SV address"
+- "Send 0.01 BSV to 1ExampleBsvAddressXXXXXXXXXXXXXXXXX"
+- "Send $5 USD worth of BSV to 1ExampleBsvAddressXXXXXXXXXXXXXXXXX"
+
+### 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"
+
+### Blockchain Operations
+- "What is the current BSV price?"
+- "Decode this BSV transaction: (transaction hex or ID)"
+
+### Data Conversion
+- "Convert 'Hello World' from UTF-8 to hex format"
+
+## How MCP Works
+
+When you interact with an MCP-enabled AI assistant:
+
+1. The AI analyzes your request and decides which tools to use
+2. With your approval, it calls the appropriate BSV MCP tool
+3. The server executes the requested operation on the Bitcoin SV blockchain
+4. The results are returned to the AI assistant
+5. The assistant presents the information in a natural, conversational way
+
+## Troubleshooting
+
+If you're having issues connecting to the server:
+
+1. Ensure the package is properly installed: `bun install -g bsv-mcp`
+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
+
+For Claude for Desktop, check the logs at:
+```bash
+tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
+```
+
+For Cursor, check the Cursor MCP logs in Settings → Extensions → Model Context Protocol.
+
+## 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 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
+}
+```
+
+### Running Tests
+
+```bash
+bun test
+```
+
+## License
+
+[Include your license information here]

package/biome.json

@@ -0,0 +1,30 @@
+{
+	"$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
+	"vcs": {
+		"enabled": false,
+		"clientKind": "git",
+		"useIgnoreFile": false
+	},
+	"files": {
+		"ignoreUnknown": false,
+		"ignore": []
+	},
+	"formatter": {
+		"enabled": true,
+		"indentStyle": "tab"
+	},
+	"organizeImports": {
+		"enabled": true
+	},
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"recommended": true
+		}
+	},
+	"javascript": {
+		"formatter": {
+			"quoteStyle": "double"
+		}
+	}
+}

package/index.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env bun
+import {
+	PrivateKey,
+} from "@bsv/sdk";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerAllTools } from "./tools";
+import { registerWalletTools } from "./tools/wallet/tools";
+import { Wallet } from "./tools/wallet/wallet";
+
+const server = new McpServer({
+	name: "Bitcoin SV MCP",
+	version: "1.0.0",
+});
+
+// Singleton wallet instance (for demo, could be replaced with real key management)
+// If PRIVATE_KEY_WIF is set in the environment, use it to instantiate the Wallet
+const privateKeyWif = process.env.PRIVATE_KEY_WIF;
+const privKey = privateKeyWif ? PrivateKey.fromWif(privateKeyWif) : undefined;
+const wallet = privKey ? new Wallet(privKey) : new Wallet();
+
+// Register wallet tools separately (needs wallet instance)
+registerWalletTools(server, wallet);
+
+// Register all other tools (BSV, Ordinals, Utils, etc.)
+registerAllTools(server);
+
+// Debug: Log all registered tools
+console.log("Registered tools:", Object.keys(server));
+console.log("MCP Server:", server);
+
+// Connect to the transport
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,31 @@
+{
+	"name": "bsv-mcp",
+	"module": "index.ts",
+	"type": "module",
+	"version": "0.0.1",
+	"bin": {
+		"bsv-mcp": "./index.ts"
+	},
+	"private": false,
+	"devDependencies": {
+		"@biomejs/biome": "^1.9.4",
+		"@types/bun": "latest"
+	},
+	"peerDependencies": {
+		"typescript": "^5.8.3"
+	},
+	"dependencies": {
+		"@bsv/sdk": "^1.4.19",
+		"@modelcontextprotocol/sdk": "^1.9.0",
+		"@types/node": "^22.14.1",
+		"js-1sat-ord": "^0.1.80",
+		"satoshi-token": "^0.0.4",
+		"tsx": "^4.19.3",
+		"zod": "^3.24.2"
+	},
+	"scripts": {
+		"lint": "biome check .",
+		"lint:fix": "biome check . --write",
+		"prepare": "chmod +x ./index.ts"
+	}
+}

package/tests/integration/wallet-server.test.ts

@@ -0,0 +1,216 @@
+import { expect, test } from "bun:test";
+import { PrivateKey } from "@bsv/sdk";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { registerWalletTools } from "../../tools/wallet/tools";
+import { Wallet } from "../../tools/wallet/wallet";
+
+// List of expected wallet tool names
+const EXPECTED_WALLET_TOOLS = [
+	"wallet_getPublicKey",
+	"wallet_createSignature",
+	"wallet_verifySignature",
+	"wallet_encrypt",
+	"wallet_decrypt",
+	"wallet_createAction",
+	"wallet_signAction",
+	"wallet_listActions",
+	"wallet_listOutputs",
+	"wallet_getNetwork",
+	"wallet_getVersion",
+	"wallet_revealCounterpartyKeyLinkage",
+	"wallet_revealSpecificKeyLinkage",
+	"wallet_createHmac",
+	"wallet_verifyHmac",
+	"wallet_abortAction",
+	"wallet_internalizeAction",
+	"wallet_relinquishOutput",
+	"wallet_acquireCertificate",
+	"wallet_listCertificates",
+	"wallet_proveCertificate",
+	"wallet_relinquishCertificate",
+	"wallet_discoverByIdentityKey",
+	"wallet_discoverByAttributes",
+	"wallet_isAuthenticated",
+	"wallet_waitForAuthentication",
+	"wallet_getHeaderForHeight",
+];
+
+// Mock wallet with test responses
+class TestWallet extends Wallet {
+	constructor() {
+		super(PrivateKey.fromRandom());
+	}
+
+	// Override with test implementations that actually return something
+	async getPublicKey() {
+		return { publicKey: "mockPublicKey123" };
+	}
+
+	// Note: other methods will still return 'not implemented' errors
+}
+
+test("MCP server registers all expected wallet tools", async () => {
+	// Create an MCP server
+	const server = new McpServer({
+		name: "Wallet Server Test",
+		version: "0.0.1",
+	});
+
+	// Create test wallet and register tools
+	const wallet = new TestWallet();
+	const handlers = registerWalletTools(server, wallet);
+
+	// Check that we have all expected tool handlers
+	for (const toolName of EXPECTED_WALLET_TOOLS) {
+		expect(handlers[toolName as keyof typeof handlers]).toBeDefined();
+		expect(typeof handlers[toolName as keyof typeof handlers]).toBe("function");
+	}
+
+	// Check that we don't have any unexpected handlers
+	const actualToolNames = Object.keys(handlers);
+	expect(actualToolNames.length).toBe(EXPECTED_WALLET_TOOLS.length);
+
+	for (const toolName of actualToolNames) {
+		expect(EXPECTED_WALLET_TOOLS).toContain(toolName);
+	}
+});
+
+test("MCP server with wallet tools", async () => {
+	// Create an MCP server
+	const server = new McpServer({
+		name: "Wallet Server Test",
+		version: "0.0.1",
+	});
+
+	// Create test wallet and register tools
+	const wallet = new TestWallet();
+	const handlers = registerWalletTools(server, wallet);
+
+	// Mock the request handler extra
+	const mockExtra = {
+		signal: new AbortController().signal,
+	};
+
+	// Test the overridden getPublicKey handler which should return data
+	const getPublicKeyHandler = handlers.wallet_getPublicKey;
+	const getPublicKeyResult = await getPublicKeyHandler({ args: {} }, mockExtra);
+
+	// Check the success result based on the actual structure
+	expect(getPublicKeyResult.content).toBeDefined();
+	expect(getPublicKeyResult.content?.[0]?.type).toBe("text");
+
+	const publicKeyContent = getPublicKeyResult.content?.[0]?.text;
+	if (typeof publicKeyContent === "string") {
+		expect(JSON.parse(publicKeyContent)).toEqual({
+			publicKey: "mockPublicKey123",
+		});
+	}
+});
+
+// For a more complete integration test, we could create a real HTTP server
+// and use fetch to make requests to it
+test.skip("MCP server with HTTP requests", async () => {
+	// Create MCP server
+	const server = new McpServer({
+		name: "Wallet Server Test",
+		version: "0.0.1",
+	});
+
+	// Register wallet tools
+	const wallet = new TestWallet();
+	const handlers = registerWalletTools(server, wallet);
+
+	// Define expected request type
+	type ToolCallRequest = {
+		type: string;
+		name: string;
+		args?: Record<string, unknown>;
+	};
+
+	// Create a simple HTTP server
+	const httpServer = Bun.serve({
+		port: 0, // Use random available port
+		async fetch(req) {
+			if (req.method === "POST") {
+				const bodyText = await req.text();
+				let body: unknown;
+
+				try {
+					body = JSON.parse(bodyText);
+				} catch (err) {
+					return new Response("Invalid JSON", { status: 400 });
+				}
+
+				// Type guard for the request body
+				const isToolCallRequest = (obj: unknown): obj is ToolCallRequest => {
+					return (
+						typeof obj === "object" &&
+						obj !== null &&
+						"type" in obj &&
+						"name" in obj &&
+						typeof (obj as ToolCallRequest).type === "string" &&
+						typeof (obj as ToolCallRequest).name === "string"
+					);
+				};
+
+				// Handle MCP requests by calling the appropriate tool
+				if (
+					isToolCallRequest(body) &&
+					body.type === "tool_call" &&
+					body.name.startsWith("wallet_")
+				) {
+					// Get handler from our handlers object
+					const toolName = body.name as keyof typeof handlers;
+					const handler = handlers[toolName];
+					if (handler) {
+						const result = await handler(
+							{ args: body.args || {} },
+							{
+								signal: new AbortController().signal,
+							},
+						);
+
+						return new Response(JSON.stringify(result), {
+							headers: { "Content-Type": "application/json" },
+						});
+					}
+				}
+			}
+
+			return new Response("Not found", { status: 404 });
+		},
+	});
+
+	try {
+		const port = httpServer.port;
+		const baseUrl = `http://localhost:${port}`;
+
+		// Test calling the getPublicKey tool
+		const response = await fetch(`${baseUrl}`, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({
+				type: "tool_call",
+				name: "wallet_getPublicKey",
+				args: {},
+			}),
+		});
+
+		const resultData = (await response.json()) as {
+			isError?: boolean;
+			content?: Array<{ type: string; text: string }>;
+		};
+
+		expect(resultData.content).toBeDefined();
+		expect(resultData.content?.[0]?.type).toBe("text");
+
+		if (resultData.content?.[0]?.text) {
+			const parsedContent = JSON.parse(resultData.content[0].text);
+			expect(parsedContent).toEqual({ publicKey: "mockPublicKey123" });
+		}
+	} finally {
+		// Shutdown the server
+		httpServer.stop();
+	}
+});