bsv-mcp 0.0.22 → 0.0.24

package/README.md

@@ -8,48 +8,94 @@
 
 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 and Setup
+
+### Prerequisites
+
+This project is built using [Bun](https://bun.sh/), a fast JavaScript runtime and package manager. While Bun is recommended for best performance, the server can also run with Node.js and npm.
+
+#### Installing Bun (Recommended)
+
+**macOS (using Homebrew):**
+```bash
+brew tap oven-sh/bun
+brew install bun
+```
+
+**macOS/Linux/WSL (using installer script):**
+```bash
+curl -fsSL https://bun.sh/install | bash
+```
+
+**Windows:**
+Windows users should use WSL (Windows Subsystem for Linux) or Docker to run Bun.
+
+Node.js and npm will also work but may not offer the same performance benefits.
+
 ## 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.
 
+![MCP Configuration Example](docs/images/mcp-config-example.png)
+
 ### Cursor
 
 To use the BSV MCP server with [Cursor](https://cursor.sh/):
 
 1. Install Cursor if you haven't already
-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:
+2. Open Cursor and navigate to Settings → Extensions → Model Context Protocol
+3. Click "Add a new global MCP server"
+4. Enter the following configuration in JSON format:
 
 ```json
-  {
-    "mcpServers": {
-      "Bitcoin SV": {
-        "command": "bunx",
-        "args": [
-          "bsv-mcp@latest"
-        ],
-        "env": {
-          "PRIVATE_KEY_WIF": "<your_private_key_wif>"
-        }
+{
+  "mcpServers": {
+    "Bitcoin SV": {
+      "command": "bunx",
+      "args": [
+        "bsv-mcp@latest"
+      ],
+      "env": {
+        "PRIVATE_KEY_WIF": "<your_private_key_wif>"
       }
     }
   }
+}
 ```
 
-6. Replace `<your_private_key_wif>` with your actual private key WIF (keep this secure!)
-7. Click "Save"
+5. Replace `<your_private_key_wif>` with your actual private key WIF (keep this secure!)
+6. Click "Save"
 
 The BSV tools will now be available to Cursor's AI assistant under the "Bitcoin SV" namespace.
 
+#### Alternative for npm users
+
+If you prefer to use npm instead of Bun:
+
+```json
+{
+  "mcpServers": {
+    "Bitcoin SV": {
+      "command": "npx",
+      "args": [
+        "bsv-mcp@latest"
+      ],
+      "env": {
+        "PRIVATE_KEY_WIF": "<your_private_key_wif>"
+      }
+    }
+  }
+}
+```
+
 ### 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. Clone this repository and run `bun install` in the project directory
-3. Open your Claude for Desktop configuration file:
+1. Open [Claude for Desktop](https://claude.ai/desktop) and go to Claude > Settings > Developer
+2. Click "Edit Config". 
+
+Open the Claude configuration json file in your favorite text editor. If you prefer to do it from the cli:
 
    ```bash
    # macOS/Linux
@@ -59,25 +105,29 @@ To connect this server to Claude for Desktop:
    code %APPDATA%\Claude\claude_desktop_config.json
    ```
 
-4. Add the BSV MCP server to your configuration (create the file if it doesn't exist):
+3. Add the BSV MCP server to your configuration:
    ```json
-    {
-      "mcpServers": {
-        "Bitcoin SV": {
-          "command": "bunx",
-          "args": [
-            "bsv-mcp@latest"
-          ],
-          "env": {
-            "PRIVATE_KEY_WIF": "<your_private_key_wif>"
-          }
-        }
-      }
-    }
+   {
+     "mcpServers": {
+       "Bitcoin SV": {
+         "command": "bunx",
+         "args": [
+           "bsv-mcp@latest"
+         ],
+         "env": {
+           "PRIVATE_KEY_WIF": "<your_private_key_wif>"
+         }
+       }
+     }
+   }
    ```
-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
+4. Replace `<your_private_key_wif>` with your actual private key WIF
+5. Save the file and restart Claude for Desktop
+6. The BSV tools will appear when you click the tools icon (hammer) in Claude for Desktop
+
+#### Alternative for npm users (Claude)
+
+If you prefer to use npm instead of Bun, replace the "command" field with "npx".
 
 ## Available Tools
 
@@ -177,6 +227,102 @@ Once connected, you can use natural language to interact with Bitcoin SV through
 
 - "Convert 'Hello World' from UTF-8 to hex format"
 
+## MCP Prompts and Resources
+
+The BSV MCP server exposes specialized prompts and resources that provide detailed information and context about Bitcoin SV technologies. These can be accessed by AI models to enhance their understanding and capabilities.
+
+### Available Prompts
+
+The server provides the following educational prompts that can be accessed directly via the MCP protocol:
+
+#### Ordinals Prompt
+- **Identifier**: `bitcoin_sv_ordinals`
+- **Description**: Comprehensive information about Bitcoin SV ordinals, including what they are, how they work, and how to use them.
+- **Usage**: Ask the assistant about "Bitcoin SV ordinals" or "1Sat Ordinals" to access this information.
+
+#### BSV SDK Prompts
+A collection of prompts providing detailed information about the Bitcoin SV SDK:
+
+- **Overview**
+  - **Identifier**: `bitcoin_sv_sdk_overview`
+  - **Description**: General overview of the Bitcoin SV SDK, including its purpose and main components.
+  - **Usage**: "Tell me about the BSV SDK" or "What is the Bitcoin SV SDK?"
+
+- **Wallet Operations**
+  - **Identifier**: `bitcoin_sv_sdk_wallet`
+  - **Description**: Information about wallet operations in the BSV SDK.
+  - **Usage**: "How do wallet operations work in the BSV SDK?"
+
+- **Transaction Building**
+  - **Identifier**: `bitcoin_sv_sdk_transaction`
+  - **Description**: Details about transaction creation and manipulation.
+  - **Usage**: "Explain BSV SDK transaction building" or "How do I create transactions with BSV SDK?"
+
+- **Authentication**
+  - **Identifier**: `bitcoin_sv_sdk_auth`
+  - **Description**: Authentication and identity protocols in BSV SDK.
+  - **Usage**: "How does authentication work with BSV SDK?"
+
+- **Cryptography**
+  - **Identifier**: `bitcoin_sv_sdk_cryptography`
+  - **Description**: Signing, encryption, and verification functionality.
+  - **Usage**: "Explain BSV SDK cryptography features"
+
+- **Scripting**
+  - **Identifier**: `bitcoin_sv_sdk_script`
+  - **Description**: Bitcoin scripting and contract capabilities.
+  - **Usage**: "How do I work with Bitcoin scripts using the BSV SDK?"
+
+- **Primitives**
+  - **Identifier**: `bitcoin_sv_sdk_primitives`
+  - **Description**: Core data types and structures in the BSV SDK.
+  - **Usage**: "What primitives are available in the BSV SDK?"
+
+### Available Resources
+
+The server also provides access to Bitcoin Request for Comments (BRC) specifications and documentation:
+
+#### BRC Resources
+- **BRCs Overview**
+  - **Identifier**: `brcs_readme`
+  - **Description**: Overview of all Bitcoin SV protocol specifications in the BRCs repository.
+  - **Usage**: "Show me the Bitcoin SV BRCs overview"
+
+- **BRCs Summary**
+  - **Identifier**: `brcs_summary`
+  - **Description**: Table of contents for all Bitcoin SV BRCs.
+  - **Usage**: "Give me a summary of Bitcoin SV BRCs"
+
+- **Specific BRC Specifications**
+  - **Identifier**: `brc_spec`
+  - **Description**: Access specific BRC specifications by category and number.
+  - **Usage**: "Show me BRC 8 on Transaction Envelopes" or "What does BRC 1 specify?"
+
+#### BRC Categories
+The BRC specifications are organized into the following categories:
+- Wallet
+- Transactions
+- Scripts
+- Tokens
+- Overlays
+- Payments
+- Peer-to-Peer
+- Key Derivation
+- Outpoints
+- Opinions
+- State Machines
+- Apps
+
+### Using Prompts and Resources
+
+AI models can use these prompts and resources to provide more accurate and detailed responses about Bitcoin SV technologies. As a user, you can:
+
+1. **Ask about a specific topic**: "Tell me about Bitcoin SV ordinals" or "Explain BSV SDK transaction building"
+2. **Request specific BRC details**: "What does BRC 8 specify?" or "Show me the BRC on Transaction Creation"
+3. **Get general overviews**: "What is the BSV SDK?" or "Show me a summary of all BRCs"
+
+These prompts and resources enhance the AI's knowledge base, enabling more technical and accurate responses even for complex Bitcoin SV topics.
+
 ## How MCP Works
 
 When you interact with an MCP-enabled AI assistant:
@@ -189,17 +335,39 @@ When you interact with an MCP-enabled AI assistant:
 
 ## Troubleshooting
 
-If you're having issues connecting to the server:
+If you're having issues with the BSV MCP server:
 
-1. Ensure the package dependencies are properly installed: `bun install`
+### Connection Issues
+
+1. Make sure Bun or Node.js is installed on your system
 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
 
+### Keeping Bun Up to Date
+
+It's important to keep Bun updated to the latest version to ensure compatibility:
+
+```bash
+# Update Bun to the latest version
+bun upgrade
+```
+
+To verify your current Bun version:
+```bash
+bun --version
+```
+
+### Logging and Debugging
+
 For Claude for Desktop, check the logs at:
 
 ```bash
+# macOS/Linux
 tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
+
+# Windows
+type %APPDATA%\Claude\Logs\mcp*.log
 ```
 
 For Cursor, check the Cursor MCP logs in Settings → Extensions → Model Context Protocol.
@@ -312,16 +480,37 @@ The tool supports both mainnet and testnet:
 
 # Development
 
+## Project Setup
+
+If you want to contribute to the project or run it locally:
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/b-open-io/bsv-mcp.git
+   cd bsv-mcp
+   ```
+
+2. Install dependencies:
+   ```bash
+   bun install
+   # or with npm
+   npm install
+   ```
+
 ## Running the Server
 
 ```bash
 bun run index.ts
+# or with npm
+npm run start
 ```
 
 ### Running Tests
 
 ```bash
 bun test
+# or with npm
+npm test
 ```
 
 ## License

package/index.ts

@@ -2,6 +2,8 @@
 import { PrivateKey } from "@bsv/sdk";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerAllPrompts } from "./prompts";
+import { registerResources } from "./resources/resources";
 import { registerAllTools } from "./tools";
 import { registerWalletTools } from "./tools/wallet/tools";
 import { Wallet } from "./tools/wallet/wallet";
@@ -11,42 +13,57 @@ import { Wallet } from "./tools/wallet/wallet";
  * Exits the process with an error message if validation fails
  */
 function validatePrivateKey(): PrivateKey {
-  const privateKeyWif = process.env.PRIVATE_KEY_WIF;
-
-  // Check if private key is set
-  if (!privateKeyWif) {
-    console.error(
-      "\x1b[31mError: PRIVATE_KEY_WIF environment variable is not set\x1b[0m"
-    );
-    console.error(
-      "Please set this variable with a valid Bitcoin SV private key in WIF format"
-    );
-    console.error(
-      "Example: PRIVATE_KEY_WIF=your_private_key_wif bun run index.ts"
-    );
-    process.exit(1);
-  }
-
-  // Validate the private key format
-  try {
-    return PrivateKey.fromWif(privateKeyWif);
-  } catch (error) {
-    console.error("\x1b[31mError: Invalid private key format\x1b[0m");
-    console.error(
-      "The PRIVATE_KEY_WIF provided is not a valid Bitcoin SV private key in WIF format"
-    );
-    console.error("Please check your key and try again");
-    process.exit(1);
-  }
+	const privateKeyWif = process.env.PRIVATE_KEY_WIF;
+
+	// Check if private key is set
+	if (!privateKeyWif) {
+		console.error(
+			"\x1b[31mError: PRIVATE_KEY_WIF environment variable is not set\x1b[0m",
+		);
+		console.error(
+			"Please set this variable with a valid Bitcoin SV private key in WIF format",
+		);
+		console.error(
+			"Example: PRIVATE_KEY_WIF=your_private_key_wif bun run index.ts",
+		);
+		process.exit(1);
+	}
+
+	// Validate the private key format
+	try {
+		return PrivateKey.fromWif(privateKeyWif);
+	} catch (error) {
+		console.error("\x1b[31mError: Invalid private key format\x1b[0m");
+		console.error(
+			"The PRIVATE_KEY_WIF provided is not a valid Bitcoin SV private key in WIF format",
+		);
+		console.error("Please check your key and try again");
+		process.exit(1);
+	}
 }
 
 // Validate private key early before starting the server
 const privKey = validatePrivateKey();
 
-const server = new McpServer({
-	name: "Bitcoin SV MCP Server",
-	version: "0.0.22",
-});
+const server = new McpServer(
+	{ name: "Bitcoin SV", version: "0.0.24" },
+	// {
+	// 	// Advertise only what you actually implement
+	// 	capabilities: {
+	// 		completions: {},
+	// 		experimental: {},
+	// 		logging: {},
+	// 		prompts: {},
+	// 		resources: {},
+	// 		tools: {},
+	// 	},
+	// 	// Optional instructions banner for clients
+	// 	instructions: `
+	// 		This server exposes Bitcoin SV helpers.
+	// 		Tools are idempotent unless marked destructive.
+	// 	`,
+	// },
+);
 
 // Initialize wallet with the validated private key
 const wallet = new Wallet(privKey);
@@ -57,6 +74,12 @@ registerWalletTools(server, wallet);
 // Register all other tools (BSV, Ordinals, Utils, etc.)
 registerAllTools(server);
 
+// Register resources
+registerResources(server);
+
+// Register prompts
+registerAllPrompts(server);
+
 // Connect to the transport
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/package.json

@@ -2,7 +2,7 @@
 	"name": "bsv-mcp",
 	"module": "index.ts",
 	"type": "module",
-	"version": "0.0.22",
+	"version": "0.0.24",
 	"license": "MIT",
 	"author": "satchmo",
 	"description": "A collection of Bitcoin SV (BSV) tools for the Model Context Protocol (MCP) framework",
@@ -41,8 +41,8 @@
 		"typescript": "^5.8.3"
 	},
 	"dependencies": {
-		"@bsv/sdk": "^1.4.19",
-		"@modelcontextprotocol/sdk": "^1.10.1",
+		"@bsv/sdk": "^1.4.20",
+		"@modelcontextprotocol/sdk": "^1.10.2",
 		"@types/node": "^22.14.1",
 		"js-1sat-ord": "^0.1.81",
 		"mnee": "^2.0.0",

package/tools/a2b/call.ts

@@ -0,0 +1,32 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import { z } from "zod";
+
+// Schema for invoking another agent via A2A protocol
+export const a2aCallArgsSchema = z.object({
+	url: z.string().url().describe("Full agent-to-agent endpoint URL"),
+	method: z.string().describe("A2A method name to invoke"),
+	params: z
+		.record(z.any())
+		.optional()
+		.describe("Payload parameters for the A2A call"),
+});
+export type A2aCallArgs = z.infer<typeof a2aCallArgsSchema>;
+
+/**
+ * Registers the a2a_call tool for agent-to-agent HTTP/SSE calls
+ */
+export function registerA2aCallTool(server: McpServer) {
+	server.tool(
+		"a2a_call",
+		"Invoke a remote agent's A2A endpoint via HTTP/SSE",
+		{ args: a2aCallArgsSchema },
+		async ({ args }: { args: A2aCallArgs }, extra: RequestHandlerExtra) => {
+			// TODO: implement HTTP request logic (e.g., fetch, SSE)
+			return {
+				content: [{ type: "text", text: "Not implemented" }],
+				isError: true,
+			};
+		},
+	);
+}

package/tools/a2b/discover.ts

@@ -0,0 +1,101 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import type {
+	ServerNotification,
+	ServerRequest,
+} from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+
+type OverlayRequest = {
+	type: "agent" | "tool";
+	query: string;
+	limit: number;
+	offset: number;
+	fromBlock?: number;
+	toBlock?: number;
+};
+
+type OverlayResponse = {
+	agents: {
+		name: string;
+		description: string;
+		capabilities: string[];
+	}[];
+	tools: {
+		name: string;
+		description: string;
+	}[];
+};
+
+// Schema for agent discovery parameters
+export const a2bDiscoverArgsSchema = z.object({
+	queryType: z.enum(["agent", "tool"]).describe("Type of discovery to perform"),
+	query: z.string().describe("Search agent or tool names, descriptions"),
+	limit: z.number().optional().describe("Limit the number of results"),
+	offset: z.number().optional().describe("Offset the results"),
+	fromBlock: z.number().optional().describe("From block"),
+	toBlock: z.number().optional().describe("To block"),
+});
+export type A2bDiscoverArgs = z.infer<typeof a2bDiscoverArgsSchema>;
+
+/**
+ * Registers the a2b_discover tool for on-chain agent discovery
+ */
+export function registerA2bDiscoverTool(server: McpServer) {
+	server.tool(
+		"a2b_discover",
+		"Search on-chain agent and MCP tool records. Use 'agent' to search for agents, 'tool' to search for MCP tools.",
+		{ args: a2bDiscoverArgsSchema },
+		async (
+			{ args }: { args: A2bDiscoverArgs },
+			extra: RequestHandlerExtra<ServerRequest, ServerNotification>,
+		) => {
+			if (args.queryType === "agent") {
+				return {
+					content: [
+						{ type: "text", text: "Agent discovery is not supported yet" },
+					],
+					isError: true,
+				};
+			}
+
+			if (args.queryType !== "tool") {
+				return {
+					content: [
+						{
+							type: "text",
+							text: "Only tool discovery is supported currently",
+						},
+					],
+					isError: true,
+				};
+			}
+
+			try {
+				const params = new URLSearchParams();
+				params.set("type", args.queryType);
+				params.set("query", args.query);
+				params.set("limit", args.limit?.toString() ?? "5");
+				params.set("offset", args.offset?.toString() ?? "0");
+				if (args.fromBlock) {
+					params.set("fromBlock", args.fromBlock.toString());
+				}
+				if (args.toBlock) {
+					params.set("toBlock", args.toBlock.toString());
+				}
+				const OVERLAY_URL = `https://overlay.a2b.network/v1/search?${params.toString()}`;
+				const response = await fetch(OVERLAY_URL);
+				const data = (await response.json()) as OverlayResponse;
+				return {
+					content: [{ type: "text", text: JSON.stringify(data) }],
+					isError: false,
+				};
+			} catch (error) {
+				return {
+					content: [{ type: "text", text: `Error querying overlay: ${error}` }],
+					isError: true,
+				};
+			}
+		},
+	);
+}