bsv-mcp 0.0.19 → 0.0.20

package/README.md

@@ -48,22 +48,23 @@ To use the BSV MCP server with [Cursor](https://cursor.sh/):
 5. Enter the following configuration in JSON format:
 
 ```json
-{
-  "Bitcoin SV": {
-    "command": "env",
-    "args": [
-      "PRIVATE_KEY_WIF=<your_private_key_wif>",
-      "bun",
-      "run",
-      "<path_to_project>/index.ts"
-    ]
+  {
+    "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. Replace `<path_to_project>` with the full path to where you cloned this repository
-8. Click "Save"
+7. Click "Save"
 
 The BSV tools will now be available to Cursor's AI assistant under the "Bitcoin SV" namespace.
 
@@ -76,59 +77,30 @@ To connect this server to Claude for Desktop:
 3. Open your Claude for Desktop configuration file:
    ```bash
    # macOS/Linux
-   code ~/Library/Application\ Support/Claude/claude_desktop_config.json
+   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>",
-           "bun",
-           "run",
-           "<path_to_project>/index.ts"
-         ]
-       }
-     }
-   }
+  {
+    "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. 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
-
-For other MCP clients that support JSON configuration:
-
-```json
-{
-  "Bitcoin SV": {
-    "command": "env",
-    "args": [
-      "PRIVATE_KEY_WIF=<your_private_key_wif>",
-      "bun",
-      "run",
-      "<path_to_project>/index.ts"
-    ]
-  }
-}
-```
-
-If running the server directly:
-
-```bash
-# Set environment variable first
-export PRIVATE_KEY_WIF=<your_private_key_wif>
-
-# Then run the server
-bun run index.ts
-```
+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
 
 ## Available Tools
 

package/index.ts

@@ -37,7 +37,7 @@ const privKey = validatePrivateKey();
 
 const server = new McpServer({
 	name: "Bitcoin SV MCP Server",
-	version: "0.0.19",
+	version: "0.0.20",
 });
 
 // Initialize wallet with the validated private key

package/package.json

@@ -2,7 +2,7 @@
 	"name": "bsv-mcp",
 	"module": "index.ts",
 	"type": "module",
-	"version": "0.0.19",
+	"version": "0.0.20",
 	"license": "MIT",
 	"author": "satchmo",
 	"description": "A collection of Bitcoin SV (BSV) tools for the Model Context Protocol (MCP) framework",

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,30 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import { z } from "zod";
+
+// Schema for agent discovery parameters
+export const a2bDiscoverArgsSchema = z.object({
+  query: z.string().describe("Agent name or capability to search for"),
+});
+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 records by name or capability",
+    { args: a2bDiscoverArgsSchema },
+    async (
+      { args }: { args: A2bDiscoverArgs },
+      extra: RequestHandlerExtra
+    ) => {
+      // TODO: implement on-chain lookup logic
+      return {
+        content: [{ type: "text", text: "Not implemented" }],
+        isError: true,
+      };
+    }
+  );
+} 

package/tools/index.ts

@@ -2,6 +2,8 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { registerBsvTools } from "./bsv";
 import { registerOrdinalsTools } from "./ordinals";
 import { registerUtilsTools } from "./utils";
+import { registerA2bDiscoverTool } from "./a2b/discover";
+import { registerA2aCallTool } from "./a2b/call";
 
 /**
  * Register all tools with the MCP server
@@ -17,5 +19,11 @@ export function registerAllTools(server: McpServer): void {
 	// Register utility tools
 	registerUtilsTools(server);
 
+	// Register agent-to-blockchain discovery tool
+	registerA2bDiscoverTool(server);
+
+	// Register agent-to-agent call tool
+	registerA2aCallTool(server);
+
 	// Add more tool categories as needed
 }

package/tools/wallet/a2bPublish.ts

@@ -0,0 +1,150 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import { z } from "zod";
+import type { Wallet } from "./wallet";
+import { createOrdinals } from "js-1sat-ord";
+import type { Inscription, Destination, ChangeResult, PreMAP } from "js-1sat-ord";
+import { Utils } from "@bsv/sdk";
+const { toArray, toBase64 } = Utils;
+
+// https://raw.githubusercontent.com/google/A2A/refs/heads/main/specification/json/a2a.json
+
+// A2A AgentCard schema (per A2A spec)
+const AgentCapabilitiesSchema = z.object({
+  streaming: z.boolean().default(false),
+  pushNotifications: z.boolean().default(false),
+  stateTransitionHistory: z.boolean().default(false),
+});
+const AgentSkillSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  description: z.string().nullable(),
+  tags: z.array(z.string()).nullable(),
+  examples: z.array(z.string()).nullable(),
+  inputModes: z.array(z.string()).nullable(),
+  outputModes: z.array(z.string()).nullable(),
+});
+
+// Provider per A2A spec
+const AgentProviderSchema = z.object({
+  organization: z.string(),
+  url: z.string().url().nullable().default(null),
+}).nullable().default(null);
+
+// Authentication per A2A spec
+const AgentAuthenticationSchema = z.object({
+  schemes: z.array(z.string()),
+  credentials: z.string().nullable().default(null),
+}).nullable().default(null);
+
+export const AgentCardSchema = z.object({
+  name: z.string(),
+  description: z.string().nullable().default(null),
+  url: z.string().url(),
+  provider: AgentProviderSchema,
+  version: z.string(),
+  documentationUrl: z.string().url().nullable().default(null),
+  capabilities: AgentCapabilitiesSchema,
+  authentication: AgentAuthenticationSchema,
+  defaultInputModes: z.array(z.string()).default(["text"]),
+  defaultOutputModes: z.array(z.string()).default(["text"]),
+  skills: z.array(AgentSkillSchema),
+});
+
+// Schema for on-chain agent publish parameters
+export const a2bPublishArgsSchema = z.object({
+  agentUrl: z.string().url().describe("Agent base URL (e.g. https://example.com)"),
+  agentName: z.string().describe("Human-friendly agent name"),
+  description: z.string().nullable().optional().describe("Optional agent description"),
+  providerOrganization: z.string().optional().describe("Optional provider organization name"),
+  providerUrl: z.string().url().optional().describe("Optional provider URL"),
+  version: z.string().optional().describe("Optional agent version"),
+  documentationUrl: z.string().url().nullable().optional().describe("Optional documentation URL"),
+  streaming: z.boolean().default(false).describe("Supports SSE (tasks/sendSubscribe)"),
+  pushNotifications: z.boolean().default(false).describe("Supports push notifications"),
+  stateTransitionHistory: z.boolean().default(false).describe("Supports state transition history"),
+  defaultInputModes: z.array(z.string()).default(["text"]).describe("Default input modes"),
+  defaultOutputModes: z.array(z.string()).default(["text"]).describe("Default output modes"),
+  skills: z.array(AgentSkillSchema).optional().default([]).describe("List of agent skills"),
+  destinationAddress: z.string().optional().describe("Optional target address for inscription"),
+});
+export type A2bPublishArgs = z.infer<typeof a2bPublishArgsSchema>;
+
+/**
+ * Registers the wallet_a2bPublish tool for publishing an agent record on-chain
+ */
+export function registerA2bPublishTool(server: McpServer, wallet: Wallet) {
+  server.tool(
+    "wallet_a2bPublish",
+    "Publish an agent.json record on-chain via Ordinal inscription",
+    { args: a2bPublishArgsSchema },
+    async (
+      { args }: { args: A2bPublishArgs },
+      extra: RequestHandlerExtra
+    ) => {
+      try {
+        const paymentPk = wallet.getPrivateKey();
+        if (!paymentPk) throw new Error("No private key available");
+        const { paymentUtxos } = await wallet.getUtxos();
+        if (!paymentUtxos?.length) throw new Error("No payment UTXOs available to fund inscription");
+
+        // Assemble AgentCard with defaults and user overrides
+        const agentCard = {
+          name: args.agentName,
+          description: args.description ?? null,
+          url: args.agentUrl,
+          provider:
+            args.providerOrganization && args.providerUrl
+              ? { organization: args.providerOrganization, url: args.providerUrl }
+              : null,
+          version: args.version ?? "1.0.0",
+          documentationUrl: args.documentationUrl ?? null,
+          capabilities: {
+            streaming: args.streaming,
+            pushNotifications: args.pushNotifications,
+            stateTransitionHistory: args.stateTransitionHistory,
+          },
+          authentication: null,
+          defaultInputModes: args.defaultInputModes,
+          defaultOutputModes: args.defaultOutputModes,
+          skills: args.skills,
+        };
+        // Validate compliance
+        AgentCardSchema.parse(agentCard);
+        const fileContent = JSON.stringify(agentCard, null, 2);
+        // Base64 payload for inscription
+        const dataB64 = toBase64(toArray(fileContent));
+        const inscription: Inscription = { dataB64, contentType: "application/json" };
+        // Destination for the ordinal
+        const walletAddress = paymentPk.toAddress().toString();
+        const targetAddress = args.destinationAddress ?? walletAddress;
+        const destinations: Destination[] = [{ address: targetAddress, inscription }];
+        // Default MAP metadata: file path, content type, encoding
+        const metaData: PreMAP = { app: 'bsv-mcp', type: 'agent' };
+
+        // Inscribe the ordinal on-chain via js-1sat-ord
+        const result = await createOrdinals({ utxos: paymentUtxos, destinations, paymentPk, changeAddress: walletAddress, metaData });
+        const changeResult = result as ChangeResult;
+        await changeResult.tx.broadcast();
+        // Refresh UTXOs
+        try { await wallet.refreshUtxos(); } catch {}
+        // Return transaction details
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              txid: changeResult.tx.id("hex"),
+              spentOutpoints: changeResult.spentOutpoints,
+              payChange: changeResult.payChange,
+              inscriptionAddress: targetAddress,
+              agentCard,
+            }),
+          }],
+        };
+      } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: msg }], isError: true };
+      }
+    }
+  );
+} 

package/tools/wallet/tools.ts

@@ -39,6 +39,10 @@ import type { createOrdinalsArgsSchema } from "./createOrdinals";
 import { registerGetAddressTool } from "./getAddress";
 import { registerPurchaseListingTool } from "./purchaseListing";
 import { registerSendToAddressTool } from "./sendToAddress";
+import { registerTransferOrdTokenTool } from "./transferOrdToken";
+import { registerA2bPublishTool } from "./a2bPublish";
+import type { transferOrdTokenArgsSchema } from "./transferOrdToken";
+import type { a2bPublishArgsSchema } from "./a2bPublish";
 import { Utils, type WalletProtocol } from "@bsv/sdk";
 
 // Define mapping from tool names to argument schemas
@@ -70,6 +74,8 @@ type ToolArgSchemas = {
 	wallet_getAddress: typeof getAddressArgsSchema;
 	wallet_sendToAddress: typeof sendToAddressArgsSchema;
 	wallet_purchaseListing: typeof purchaseListingArgsSchema;
+	wallet_transferOrdToken: typeof transferOrdTokenArgsSchema;
+	wallet_a2bPublish: typeof a2bPublishArgsSchema;
 	wallet_createOrdinals: typeof createOrdinalsArgsSchema;
 };
 
@@ -111,6 +117,12 @@ export function registerWalletTools(
 	// Register the wallet_purchaseListing tool
 	registerPurchaseListingTool(server, wallet);
 
+	// Register the wallet_transferOrdToken tool
+	registerTransferOrdTokenTool(server, wallet);
+
+	// Register the wallet_a2bPublish tool
+	registerA2bPublishTool(server, wallet);
+
 	// Register only the minimal public-facing tools
 	// wallet_createAction, wallet_signAction and wallet_getHeight have been removed
 

package/tools/wallet/transferOrdToken/index.ts

@@ -0,0 +1,103 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import { z } from "zod";
+import {
+  transferOrdTokens,
+  TokenType,
+  TokenInputMode,
+  TokenSelectionStrategy,
+  selectTokenUtxos,
+  type TransferOrdTokensConfig,
+  type Utxo,
+  type TokenUtxo,
+  type Payment,
+  type Distribution,
+  type TokenChangeResult,
+} from "js-1sat-ord";
+import type { Wallet } from "../wallet";
+
+// Schema for BSV-20/BSV-21 token transfer arguments
+export const transferOrdTokenArgsSchema = z.object({
+  protocol: z.enum(["bsv-20", "bsv-21"]),
+  tokenID: z.string(),
+  sendAmount: z.number(),
+  paymentUtxos: z.array(
+    z.object({ txid: z.string(), vout: z.number(), satoshis: z.number(), script: z.string() })
+  ),
+  tokenUtxos: z.array(
+    z.object({ txid: z.string(), vout: z.number(), satoshis: z.literal(1), script: z.string(), amt: z.string(), id: z.string() })
+  ),
+  distributions: z.array(z.object({ address: z.string(), tokens: z.number() })),
+  decimals: z.number(),
+  additionalPayments: z.array(z.object({ to: z.string(), amount: z.number() })).optional(),
+});
+export type TransferOrdTokenArgs = z.infer<typeof transferOrdTokenArgsSchema>;
+
+/**
+ * Register the wallet_transferOrdToken tool for transferring BSV tokens.
+ */
+export function registerTransferOrdTokenTool(server: McpServer, wallet: Wallet) {
+  server.tool(
+    "wallet_transferOrdToken",
+    "Transfers BSV-20 or BSV-21 tokens from your wallet via js-1sat-ord transferOrdTokens.",
+    { args: transferOrdTokenArgsSchema },
+    async (
+      { args }: { args: TransferOrdTokenArgs },
+      extra: RequestHandlerExtra
+    ) => {
+      try {
+        // fetch keys
+        const paymentPk = wallet.getPrivateKey();
+        if (!paymentPk) throw new Error("No private key available");
+        const ordPk = paymentPk;
+        const changeAddress = paymentPk.toAddress().toString();
+        const ordAddress = changeAddress;
+
+        // select token UTXOs
+        const { selectedUtxos: inputTokens } = selectTokenUtxos(
+          args.tokenUtxos as TokenUtxo[],
+          args.sendAmount,
+          args.decimals,
+          { inputStrategy: TokenSelectionStrategy.SmallestFirst, outputStrategy: TokenSelectionStrategy.LargestFirst }
+        );
+
+        // build config
+        const config: TransferOrdTokensConfig = {
+          protocol: args.protocol === "bsv-20" ? TokenType.BSV20 : TokenType.BSV21,
+          tokenID: args.tokenID,
+          utxos: args.paymentUtxos as Utxo[],
+          inputTokens,
+          distributions: args.distributions as Distribution[],
+          tokenChangeAddress: ordAddress,
+          changeAddress,
+          paymentPk,
+          ordPk,
+          additionalPayments: args.additionalPayments as Payment[] || [],
+          decimals: args.decimals,
+          inputMode: TokenInputMode.Needed,
+          splitConfig: { outputs: inputTokens.length === 1 ? 2 : 1, threshold: args.sendAmount },
+        };
+
+        // execute transfer
+        const result: TokenChangeResult = await transferOrdTokens(config);
+        await result.tx.broadcast();
+
+        // refresh UTXOs
+        try { await wallet.refreshUtxos(); } catch {}
+
+        // respond
+        return {
+          content: [{ type: "text", text: JSON.stringify({
+            txid: result.tx.id("hex"),
+            spentOutpoints: result.spentOutpoints,
+            payChange: result.payChange,
+            tokenChange: result.tokenChange,
+          }) }]
+        };
+      } catch (err: unknown) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: msg }], isError: true };
+      }
+    }
+  );
+}