bsv-mcp 0.3.2 → 0.3.4

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # BSV MCP Server Changelog
 
+## [0.3.4] - 2026-09-06
+
+### Added
+- Discover owner-listed Droplit sponsors without a wallet or preselected faucet.
+- Validate public responses and pagination; discovery never authorizes access or payment.
+
+
+## [0.3.3] - 2026-09-06
+
+### Fixed
+- Honor `DROPLIT_SITE_URL` for sponsor approval links so staging requests reach the correct owner UI.
+- Build approval links from the configured sponsor and verified wallet identity; reject unsafe site origins.
+
 ## [0.3.2] - 2026-09-06
 
 ### Added

package/README.md

@@ -884,17 +884,36 @@ BRC100_WALLET_URL=http://127.0.0.1:3321
 BRC100_WALLET_ORIGINATOR=bsv-mcp.local
 DROPLIT_API_URL=https://api.droplit.dev/droplit
 DROPLIT_FAUCET_NAME=your-sponsor-slug
+# Optional: set explicitly when the owner approval UI is hosted elsewhere.
+DROPLIT_SITE_URL=https://droplit.dev
 ```
 
-Set both sponsor values explicitly. The URL includes the server's configured
+Set both sponsor values explicitly for wallet operations. The URL includes the server's configured
 base path. Leave `USE_DROPLIT_API` unset: these sponsor tools appear alongside
 normal wallet tools and use the same connected signer identity. Existing local
 BRC-100 wallet contexts also support this sponsor pair. `1sat serve` exposes a
 wallet stack service; it is not itself a BRC-100 signer RPC endpoint.
 
+For public sponsor discovery, set only `DROPLIT_API_URL` and call
+`droplit_discover` with optional `limit` (1–50, default 20) and `after`
+(the previous `next_cursor`). This unsigned read needs no selected sponsor or
+wallet and returns only names, slugs, and `approval_required: true`. It neither
+creates a wallet nor grants sponsor access. Normal MCP startup retains its
+existing wallet initialization behavior; this tool itself makes no wallet calls.
+An empty catalog means no owners have opted in. Select a listed slug, configure
+`DROPLIT_FAUCET_NAME`, and use the existing wallet access/owner approval flow.
+Listing does not promise funding or quota availability.
+
 Call `droplit_getAccess` to inspect your own authorization and quotas. An
-`approval_required` response includes a `https://droplit.dev` link for manual
+`approval_required` response includes a link to `DROPLIT_SITE_URL` (default
+`https://droplit.dev`) for manual
 owner review. Do not automatically open, approve, or register to obtain access.
+The site URL must be an HTTPS origin (HTTP is allowed only for loopback),
+without credentials, a path, query, or fragment. For staging, set it to the
+trusted staging frontend origin independently of `DROPLIT_API_URL`. Approval
+links use the configured sponsor and authenticated wallet identity; a server
+response cannot redirect them to another site.
+
 Public status and public-key registration do not prove sponsor approval, and
 creating your own faucet requires funding rather than providing free credit.
 Missing quota kinds are unrestricted for authorized users; a configured zero

package/dist/index.js

@@ -256042,7 +256042,7 @@ var package_default = {
   name: "bsv-mcp",
   module: "dist/index.js",
   type: "module",
-  version: "0.3.2",
+  version: "0.3.4",
   license: "MIT",
   author: "satchmo",
   description: "A collection of Bitcoin SV (BSV) tools for the Model Context Protocol (MCP) framework",
@@ -284877,6 +284877,23 @@ function registerUtilsTools(server) {
 
 // utils/droplit.ts
 init_mod2();
+function droplitApiBaseUrl(apiUrl) {
+  const url3 = new URL(apiUrl);
+  const loopback = url3.hostname === "localhost" || url3.hostname === "127.0.0.1" || url3.hostname === "[::1]";
+  if (url3.username || url3.password || url3.search || url3.hash || !(url3.protocol === "https:" || url3.protocol === "http:" && loopback)) {
+    throw new Error("Droplit API requires HTTPS or HTTP loopback without credentials, query or fragment");
+  }
+  return url3.href.replace(/\/$/, "");
+}
+function approvalSiteOrigin(value2 = "https://droplit.dev") {
+  const url3 = new URL(value2);
+  const loopback = ["localhost", "127.0.0.1", "[::1]"].includes(url3.hostname);
+  if (url3.username || url3.password || url3.pathname !== "/" || url3.href.includes("?") || url3.href.includes("#") || value2.includes("\\") || !(url3.protocol === "https:" || url3.protocol === "http:" && loopback)) {
+    throw new Error("DROPLIT_SITE_URL requires an HTTPS or HTTP loopback origin without credentials, path, query or fragment");
+  }
+  return url3.origin;
+}
+
 class DroplitError extends Error {
   code;
   status;
@@ -284926,16 +284943,14 @@ function httpFailure(status, details = {}) {
 class DroplitClient {
   config;
   authFetch;
+  siteOrigin;
   wallet;
   constructor(config2) {
     this.config = config2;
+    this.siteOrigin = approvalSiteOrigin(config2.siteUrl);
     if (config2.wallet && config2.authKey)
       throw new Error("Configure Droplit wallet or authKey, not both");
-    const url3 = new URL(config2.apiUrl);
-    const loopback = url3.hostname === "localhost" || url3.hostname === "127.0.0.1" || url3.hostname === "[::1]";
-    if (url3.username || url3.password || url3.search || url3.hash || !(url3.protocol === "https:" || url3.protocol === "http:" && loopback)) {
-      throw new Error("Droplit API requires HTTPS or HTTP loopback without credentials, query or fragment");
-    }
+    droplitApiBaseUrl(config2.apiUrl);
     if (!config2.faucetName.trim())
       throw new Error("Droplit faucet name is required");
     this.wallet = config2.wallet ?? (config2.authKey ? new ProtoWallet_default(config2.authKey) : undefined);
@@ -285023,6 +285038,7 @@ class DroplitClient {
       throw new DroplitError("invalid_response", "Sponsor access response did not match the authenticated wallet.");
     }
     access.approval_path = `/droplit/${encodeURIComponent(this.config.faucetName)}?tab=api&request_key=${encodeURIComponent(identity6)}`;
+    access.approval_url = new URL(access.approval_path, this.siteOrigin).href;
     return access;
   }
   async fund(rawtx) {
@@ -285059,6 +285075,74 @@ class DroplitClient {
     return this.authed(path3, init);
   }
 }
+var publicSponsorsSchema = exports_external.object({
+  sponsors: exports_external.array(exports_external.object({
+    name: exports_external.string(),
+    slug: exports_external.string().min(1),
+    approval_required: exports_external.literal(true)
+  })).max(50),
+  next_cursor: exports_external.string().min(1).nullable()
+});
+async function discoverDroplitSponsors(apiUrl, options = {}) {
+  const limit = options.limit ?? 20;
+  if (!Number.isInteger(limit) || limit < 1 || limit > 50)
+    throw new Error("limit must be an integer from 1 to 50");
+  const url3 = new URL(`${droplitApiBaseUrl(apiUrl)}/sponsors`);
+  url3.searchParams.set("limit", String(limit));
+  if (options.after !== undefined)
+    url3.searchParams.set("after", options.after);
+  let response;
+  try {
+    response = await fetch(url3, {
+      method: "GET",
+      redirect: "error",
+      credentials: "omit",
+      signal: AbortSignal.timeout(15000)
+    });
+  } catch {
+    throw new DroplitError("request_failed", "Could not read public sponsors. Check the configured API origin.");
+  }
+  if (!response.ok)
+    throw new DroplitError("request_failed", "Could not read public sponsors.", response.status);
+  try {
+    return publicSponsorsSchema.parse(await response.json());
+  } catch {
+    throw new DroplitError("invalid_response", "Public sponsor response was invalid.");
+  }
+}
+
+// tools/wallet/droplitDiscovery.ts
+function registerDroplitDiscoveryTool(server, apiUrl) {
+  const baseUrl = droplitApiBaseUrl(apiUrl);
+  server.registerTool("droplit_discover", {
+    description: "List publicly opted-in sponsors. No wallet or sponsor selection is required. Listing grants no access or funding; choose a slug, then request the sponsor owner's approval separately.",
+    inputSchema: {
+      limit: exports_external.number().int().min(1).max(50).optional(),
+      after: exports_external.string().optional()
+    },
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    }
+  }, async (options) => {
+    try {
+      const data = await discoverDroplitSponsors(baseUrl, options);
+      return { ...createSuccessResponse(data), structuredContent: data };
+    } catch (error52) {
+      const data = {
+        error: error52 instanceof DroplitError ? error52.code : "invalid_request",
+        message: error52 instanceof DroplitError ? error52.message : "Invalid sponsor discovery request."
+      };
+      return {
+        ...createSuccessResponse(data),
+        structuredContent: data,
+        isError: true
+      };
+    }
+  });
+}
 
 // tools/wallet/droplit.ts
 function errorResult(error52) {
@@ -285093,7 +285177,7 @@ function registerDroplitTools(server, client, disableBroadcasting = false) {
         ...!access.authorized ? {
           error: "approval_required",
           message: "Ask the sponsor owner to approve this wallet. Copy the approval URL for manual review; do not auto-open or submit approval.",
-          approval_url: `https://droplit.dev${access.approval_path}`
+          approval_url: access.approval_url
         } : {}
       };
       return {
@@ -295163,7 +295247,7 @@ var package_default2 = {
   name: "bsv-mcp",
   module: "dist/index.js",
   type: "module",
-  version: "0.3.2",
+  version: "0.3.4",
   license: "MIT",
   author: "satchmo",
   description: "A collection of Bitcoin SV (BSV) tools for the Model Context Protocol (MCP) framework",
@@ -297896,6 +297980,9 @@ function registerAllTools(server, config2 = {}) {
   }
   if (enableUtilsTools) {
     registerUtilsTools(server);
+    const apiUrl = config2.droplitApiUrl ?? process.env.DROPLIT_API_URL ?? config2.droplitClient?.getConfig().apiUrl;
+    if (apiUrl)
+      registerDroplitDiscoveryTool(server, apiUrl);
   }
   if (enableA2bTools) {
     registerA2bDiscoverTool(server);
@@ -298351,12 +298438,39 @@ init_mod2();
 function readDroplitSponsorConfig(env = process.env) {
   const apiUrl = env.DROPLIT_API_URL;
   const faucetName = env.DROPLIT_FAUCET_NAME;
-  if (apiUrl === undefined && faucetName === undefined)
+  const siteUrl = env.DROPLIT_SITE_URL;
+  if (apiUrl === undefined && faucetName === undefined && siteUrl === undefined)
+    return;
+  if (apiUrl?.trim() && faucetName === undefined) {
+    droplitApiBaseUrl2(apiUrl);
+    if (siteUrl !== undefined)
+      approvalSiteOrigin2(siteUrl);
     return;
+  }
   if (!apiUrl?.trim() || !faucetName?.trim()) {
     throw new Error("DROPLIT_API_URL and DROPLIT_FAUCET_NAME must both be explicitly configured");
   }
-  return { apiUrl, faucetName };
+  return {
+    apiUrl,
+    faucetName,
+    ...siteUrl === undefined ? {} : { siteUrl: approvalSiteOrigin2(siteUrl) }
+  };
+}
+function droplitApiBaseUrl2(apiUrl) {
+  const url3 = new URL(apiUrl);
+  const loopback = url3.hostname === "localhost" || url3.hostname === "127.0.0.1" || url3.hostname === "[::1]";
+  if (url3.username || url3.password || url3.search || url3.hash || !(url3.protocol === "https:" || url3.protocol === "http:" && loopback)) {
+    throw new Error("Droplit API requires HTTPS or HTTP loopback without credentials, query or fragment");
+  }
+  return url3.href.replace(/\/$/, "");
+}
+function approvalSiteOrigin2(value2 = "https://droplit.dev") {
+  const url3 = new URL(value2);
+  const loopback = ["localhost", "127.0.0.1", "[::1]"].includes(url3.hostname);
+  if (url3.username || url3.password || url3.pathname !== "/" || url3.href.includes("?") || url3.href.includes("#") || value2.includes("\\") || !(url3.protocol === "https:" || url3.protocol === "http:" && loopback)) {
+    throw new Error("DROPLIT_SITE_URL requires an HTTPS or HTTP loopback origin without credentials, path, query or fragment");
+  }
+  return url3.origin;
 }
 
 class DroplitError2 extends Error {
@@ -298408,16 +298522,14 @@ function httpFailure2(status, details = {}) {
 class DroplitClient2 {
   config;
   authFetch;
+  siteOrigin;
   wallet;
   constructor(config2) {
     this.config = config2;
+    this.siteOrigin = approvalSiteOrigin2(config2.siteUrl);
     if (config2.wallet && config2.authKey)
       throw new Error("Configure Droplit wallet or authKey, not both");
-    const url3 = new URL(config2.apiUrl);
-    const loopback = url3.hostname === "localhost" || url3.hostname === "127.0.0.1" || url3.hostname === "[::1]";
-    if (url3.username || url3.password || url3.search || url3.hash || !(url3.protocol === "https:" || url3.protocol === "http:" && loopback)) {
-      throw new Error("Droplit API requires HTTPS or HTTP loopback without credentials, query or fragment");
-    }
+    droplitApiBaseUrl2(config2.apiUrl);
     if (!config2.faucetName.trim())
       throw new Error("Droplit faucet name is required");
     this.wallet = config2.wallet ?? (config2.authKey ? new ProtoWallet_default(config2.authKey) : undefined);
@@ -298505,6 +298617,7 @@ class DroplitClient2 {
       throw new DroplitError2("invalid_response", "Sponsor access response did not match the authenticated wallet.");
     }
     access.approval_path = `/droplit/${encodeURIComponent(this.config.faucetName)}?tab=api&request_key=${encodeURIComponent(identity6)}`;
+    access.approval_url = new URL(access.approval_path, this.siteOrigin).href;
     return access;
   }
   async fund(rawtx) {
@@ -298541,6 +298654,14 @@ class DroplitClient2 {
     return this.authed(path5, init);
   }
 }
+var publicSponsorsSchema2 = exports_external.object({
+  sponsors: exports_external.array(exports_external.object({
+    name: exports_external.string(),
+    slug: exports_external.string().min(1),
+    approval_required: exports_external.literal(true)
+  })).max(50),
+  next_cursor: exports_external.string().min(1).nullable()
+});
 
 // utils/externalWalletConfig.ts
 function readExternalWalletConfig(env = process.env) {

package/package.json

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

package/tools/index.ts

@@ -10,6 +10,7 @@ import { registerBsvTools } from "./bsv";
 import { registerMneeTools } from "./mnee";
 import { registerOrdinalsTools } from "./ordinals";
 import { registerUtilsTools } from "./utils";
+import { registerDroplitDiscoveryTool } from "./wallet/droplitDiscovery";
 import { registerDroplitTools } from "./wallet/droplit";
 import { registerWalletGetBalanceDroplitTool } from "./wallet/getBalanceDroplit";
 import type { IntegratedWallet } from "./wallet/integratedWallet";
@@ -48,6 +49,7 @@ export interface ToolsConfig {
 	ctx?: OneSatContext;
 	services?: OneSatServices;
 	droplitClient?: DroplitClient;
+	droplitApiUrl?: string;
 }
 
 /**
@@ -94,6 +96,11 @@ export function registerAllTools(
 	// Register utility tools
 	if (enableUtilsTools) {
 		registerUtilsTools(server);
+		const apiUrl =
+			config.droplitApiUrl ??
+			process.env.DROPLIT_API_URL ??
+			config.droplitClient?.getConfig().apiUrl;
+		if (apiUrl) registerDroplitDiscoveryTool(server, apiUrl);
 	}
 
 	// Register agent-to-blockchain tools

package/tools/wallet/droplit.ts

@@ -53,7 +53,7 @@ export function registerDroplitTools(
 								error: "approval_required",
 								message:
 									"Ask the sponsor owner to approve this wallet. Copy the approval URL for manual review; do not auto-open or submit approval.",
-								approval_url: `https://droplit.dev${access.approval_path}`,
+								approval_url: access.approval_url,
 							}
 						: {}),
 				};

package/tools/wallet/droplitDiscovery.ts

@@ -0,0 +1,51 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import {
+	discoverDroplitSponsors,
+	droplitApiBaseUrl,
+	DroplitError,
+} from "../../utils/droplit";
+import { createSuccessResponse } from "../utils/errorHandler";
+
+export function registerDroplitDiscoveryTool(
+	server: McpServer,
+	apiUrl: string,
+) {
+	const baseUrl = droplitApiBaseUrl(apiUrl);
+	server.registerTool(
+		"droplit_discover",
+		{
+			description:
+				"List publicly opted-in sponsors. No wallet or sponsor selection is required. Listing grants no access or funding; choose a slug, then request the sponsor owner's approval separately.",
+			inputSchema: {
+				limit: z.number().int().min(1).max(50).optional(),
+				after: z.string().optional(),
+			},
+			annotations: {
+				readOnlyHint: true,
+				destructiveHint: false,
+				idempotentHint: true,
+				openWorldHint: true,
+			},
+		},
+		async (options) => {
+			try {
+				const data = await discoverDroplitSponsors(baseUrl, options);
+				return { ...createSuccessResponse(data), structuredContent: data };
+			} catch (error) {
+				const data = {
+					error: error instanceof DroplitError ? error.code : "invalid_request",
+					message:
+						error instanceof DroplitError
+							? error.message
+							: "Invalid sponsor discovery request.",
+				};
+				return {
+					...createSuccessResponse(data),
+					structuredContent: data,
+					isError: true,
+				};
+			}
+		},
+	);
+}