bsv-mcp 0.0.35 → 0.2.0

package/tools/bap/getId.ts

@@ -0,0 +1,169 @@
+import { PrivateKey } from "@bsv/sdk";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import type {
+	CallToolResult,
+	ServerNotification,
+	ServerRequest,
+} from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { BSOCIAL_API_URL } from "../constants";
+import type { IdentityData, SigmaIdentityProfile } from "./types";
+
+// Schema for bap_getId arguments
+export const bapGetIdArgsSchema = z.object({
+	idKey: z
+		.string()
+		.optional()
+		.describe(
+			"Optional Identity Key (Paymail or public key). If not provided, attempts to use the server's configured identity key.",
+		),
+});
+export type BapGetIdArgs = z.infer<typeof bapGetIdArgsSchema>;
+
+/**
+ * Fetches the identity profile from Sigma API.
+ * @param idKey The identity key (Paymail or public key) to fetch the profile for.
+ * @returns The identity data, or null if not found.
+ */
+export const fetchProfile = async (
+	idKey: string,
+): Promise<IdentityData | null> => {
+	const response = await fetch(`${BSOCIAL_API_URL}/identity/get`, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+		},
+		body: JSON.stringify({ idKey }),
+	});
+
+	if (!response.ok) {
+		// For 404, Sigma API might return a specific body, but generally, we treat it as profile not found.
+		if (response.status === 404) {
+			return null; // Explicitly return null for 404
+		}
+		const errorBody = await response.text();
+		throw new Error(
+			`Sigma API request failed with status ${response.status}: ${errorBody}`,
+		);
+	}
+
+	try {
+		const profileData = (await response.json()) as SigmaIdentityProfile;
+		// Ensure result exists, even if it's null (which means not found)
+		if (typeof profileData.result === "undefined") {
+			throw new Error("Sigma API response is missing the 'result' field.");
+		}
+		return profileData.result; // This can be IdentityData or null
+	} catch (jsonError) {
+		// Handle cases where response is not JSON or structure is unexpected
+		throw new Error(
+			`Failed to parse Sigma API response: ${jsonError instanceof Error ? jsonError.message : String(jsonError)}`,
+		);
+	}
+};
+
+/**
+ * Registers the bap_getId tool for fetching a BAP identity.
+ */
+export function registerBapGetIdTool(
+	server: McpServer,
+	identityPk?: PrivateKey, // Accept the global identityPk
+) {
+	server.tool(
+		"bap_getId",
+		"Retrieves a Bitcoin Attestation Protocol (BAP) identity profile using an idKey (Paymail or public key). If no idKey is provided, it attempts to use the server's configured identity key.",
+		{ args: bapGetIdArgsSchema },
+		async (
+			{ args }: { args: BapGetIdArgs },
+			extra: RequestHandlerExtra<ServerRequest, ServerNotification>,
+		): Promise<CallToolResult> => {
+			let targetIdKey = args.idKey;
+
+			if (!targetIdKey) {
+				// First priority: Use authenticated user's BAP ID from OAuth session
+				const authInfo = (extra as any).authInfo;
+				if (authInfo?.metadata?.bapId) {
+					targetIdKey = authInfo.metadata.bapId;
+					console.error(`Using authenticated user's BAP ID: ${targetIdKey}`);
+				}
+				// Second priority: Use authenticated user's pubkey
+				else if (authInfo?.metadata?.pubkey) {
+					targetIdKey = authInfo.metadata.pubkey;
+					console.error(`Using authenticated user's pubkey: ${targetIdKey}`);
+				}
+				// Fallback: Attempt to get idKey from the passed identityPk or environment variable
+				else {
+					let pkToUse = identityPk;
+
+					if (!pkToUse) {
+						const identityKeyWifEnv = process.env.IDENTITY_KEY_WIF;
+						if (identityKeyWifEnv) {
+							try {
+								pkToUse = PrivateKey.fromWif(identityKeyWifEnv);
+							} catch (e) {
+								// Don't error here, let it be handled by the final check
+							}
+						}
+					}
+
+					if (pkToUse) {
+						// Sigma typically uses the public key string as the idKey
+						targetIdKey = pkToUse.toPublicKey().toString();
+					} else {
+						return {
+							content: [
+								{
+									type: "text",
+									text: "idKey not provided and could not be derived from authenticated session or server configuration.",
+								},
+							],
+							isError: true,
+						};
+					}
+				}
+			}
+
+			if (!targetIdKey) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: "Critical error: targetIdKey is unexpectedly undefined after derivation attempts.",
+						},
+					],
+					isError: true,
+				};
+			}
+
+			try {
+				const identityDataResult = await fetchProfile(targetIdKey);
+				if (identityDataResult === null) {
+					return {
+						content: [
+							{
+								type: "text",
+								text: `No BAP identity found for idKey: ${targetIdKey}`,
+							},
+						],
+						isError: false, // Not an error, just no data found for the given key
+					};
+				}
+				return {
+					content: [
+						{ type: "text", text: JSON.stringify(identityDataResult, null, 2) },
+					],
+				};
+			} catch (error) {
+				const errorMessage =
+					error instanceof Error ? error.message : String(error);
+				return {
+					content: [
+						{ type: "text", text: `Error fetching BAP ID: ${errorMessage}` },
+					],
+					isError: true,
+				};
+			}
+		},
+	);
+}

package/tools/bap/index.ts

@@ -0,0 +1,111 @@
+import type { PrivateKey } from "@bsv/sdk";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Wallet } from "../wallet/wallet";
+import { registerBapFriendTool } from "./friend";
+import { registerBapGenerateTool } from "./generate";
+import { registerBapGetCurrentAddressTool } from "./getCurrentAddress";
+import { registerBapGetIdTool } from "./getId";
+
+const logFunc = console.error;
+
+/**
+ * Configuration for BAP tools registration.
+ */
+export interface BapToolsConfig {
+	disableBroadcasting?: boolean;
+	identityPk?: PrivateKey;
+	masterXprv?: string;
+	wallet?: Wallet;
+}
+
+/**
+ * Register all BAP tools with the MCP server
+ * @param server The MCP server instance
+ * @param identityPk The optional identity private key for operations requiring it
+ * @param masterXprv The BAP HD Master Key (xprv string) if available.
+ * @param config Configuration options for BAP tools.
+ */
+export function registerBapTools(
+	server: McpServer,
+	config?: BapToolsConfig,
+): void {
+	const {
+		identityPk, // Server's main configured identity (from keys.json or IDENTITY_KEY_WIF)
+		masterXprv, // Server's master BAP key (from keys.json)
+		wallet,
+		disableBroadcasting = false,
+	} = config || {};
+
+	const envIdentityKeyWif = process.env.IDENTITY_KEY_WIF;
+
+	// --- Register bap_generate ONLY if no identity exists ---
+	const canGenerateBapIdentity = !envIdentityKeyWif && !masterXprv;
+	if (canGenerateBapIdentity) {
+		logFunc(
+			"INFO: Registering bap_generate tool. No master identity (xprv) or direct identity WIF found.",
+		);
+		registerBapGenerateTool(server, { disableBroadcasting });
+	} else {
+		logFunc(
+			"INFO: bap_generate tool not registered. Master identity (xprv) or direct identity WIF already exists.",
+		);
+	}
+
+	// --- Register tools requiring an established identity ---
+	// Established identity means either an identityPk was loaded/configured, OR an env var was set.
+	const hasEstablishedIdentity = !!identityPk || !!envIdentityKeyWif;
+
+	if (hasEstablishedIdentity) {
+		logFunc(
+			"INFO: Registering BAP tools that require an established identity (bap_getId, bap_getCurrentAddress).",
+		);
+		// registerBapGetIdTool can use server's identityPk if available
+
+		// registerBapGetCurrentAddressTool strictly requires the server's identityPk (not just env var)
+		if (identityPk) {
+			registerBapGetCurrentAddressTool(server, identityPk);
+		} else {
+			logFunc(
+				"WARN: bap_getCurrentAddress tool not registered. Server identityPk not available (might be using env var directly).",
+			);
+		}
+	} else {
+		logFunc(
+			"INFO: BAP tools requiring established identity not registered (no identityPk or IDENTITY_KEY_WIF).",
+		);
+		// We might still want bap_getId available even without server identity,
+		// as it can take an idKey argument. Let's register it outside the check.
+		// Moved registerBapGetIdTool outside this block - see below.
+	}
+
+	// Always register bap_getId as it can operate on user-provided idKey too.
+	// If server identityPk is available, it can use it as default.
+	registerBapGetIdTool(server, identityPk);
+
+	// --- Register tools requiring the master HD key (xprv) ---
+	if (masterXprv) {
+		try {
+			// No need to parse HD key here if tools don't need the HD object itself
+			// const masterHdKey = HD.fromString(masterXprv);
+
+			// Register bap_friend if wallet is also available
+			if (wallet) {
+				logFunc(
+					"INFO: Registering bap_friend tool (requires wallet & masterXprv).",
+				);
+				registerBapFriendTool(server, wallet, masterXprv, {
+					disableBroadcasting,
+				});
+			} else {
+				logFunc("WARN: Wallet not available, bap_friend tool not registered.");
+			}
+
+			// Add other tools that specifically require masterXprv here...
+		} catch (e) {
+			// Catch potential HD.fromString errors if parsing is done here
+			console.error(
+				`ERROR: Failed during masterXprv tool registration: ${e instanceof Error ? e.message : String(e)}`,
+			);
+		}
+	}
+}

package/tools/bap/types.ts

@@ -0,0 +1,66 @@
+import type { Place, PostalAddress } from "schema-dts";
+
+export interface BapPublicKey {
+	id: string;
+	controller: string;
+	type: "EcdsaSecp256k1VerificationKey2019";
+	bitcoinAddress: string;
+}
+
+export enum SchemaType {
+	Person = "Person",
+	Organization = "Organization",
+}
+
+// Define our base Identity interface including common fields + custom ones
+export interface Identity {
+	// Common Schema.org fields we use
+	"@context"?: string;
+	"@type": SchemaType;
+	alternateName?: string;
+	description?: string;
+	image?: string; // Used for Person
+	logo?: string; // Used for Organization
+	address?: string | PostalAddress;
+	location?: Place; // Use Place from schema-dts
+	homeLocation?: Place; // Use Place from schema-dts
+	url?: string;
+	email?: string;
+
+	// Person specific (optional)
+	givenName?: string;
+	familyName?: string;
+
+	// Organization specific (optional)
+	legalName?: string;
+
+	// Custom properties
+	_id?: string;
+	paymail?: string;
+	bitcoinAddress?: string;
+	banner?: string;
+}
+
+// Address related to BAP/blockchain context, not Schema.org PostalAddress
+export type BapAddress = {
+	address: string;
+	txId: string;
+	block: number;
+};
+
+export type IdentityData = {
+	addresses?: BapAddress[]; // Use BapAddress type
+	block: number;
+	currentAddress: string;
+	firstSeen: number;
+	idKey: string; // BAP ID format
+	identity: Identity;
+	rootAddress: string;
+	timestamp: number;
+	valid: boolean;
+};
+
+// The API response structure for fetching a profile
+export interface SigmaIdentityProfile {
+	result: IdentityData;
+}

package/tools/bap/utils.ts

@@ -0,0 +1,33 @@
+import type { Identity, IdentityData, SchemaType } from "./types";
+
+type AllFields = {
+	schemaType: SchemaType;
+	alternateName: string;
+	description: string;
+	bitcoinAddress: string;
+};
+
+export const buildIdentity = ({
+	schemaType,
+	alternateName,
+	description,
+	bitcoinAddress,
+}: AllFields): string => {
+	const identity: Identity = {
+		"@context": "https://schema.org",
+		"@type": schemaType as SchemaType,
+		alternateName,
+		description,
+		bitcoinAddress,
+	};
+
+	if (description) {
+		identity.description = description;
+	}
+
+	if (bitcoinAddress) {
+		identity.bitcoinAddress = bitcoinAddress;
+	}
+
+	return JSON.stringify(identity);
+};

package/tools/bigblocks/components.ts

@@ -0,0 +1,304 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+// TypeScript interfaces for BigBlocks registry
+interface BigBlocksComponent {
+	name: string;
+	type: string;
+	description: string;
+	files?: string[];
+	dependencies?: string[];
+	registryDependencies?: string[];
+}
+
+interface BigBlocksRegistry {
+	components: BigBlocksComponent[];
+	version?: string;
+}
+
+interface OrganizedComponents {
+	[category: string]: {
+		[subcategory: string]: BigBlocksComponent[];
+	};
+}
+
+// Load BigBlocks registry data
+function loadBigBlocksRegistry(): BigBlocksRegistry | null {
+	try {
+		const registryPath = path.resolve(
+			"node_modules/bigblocks/registry/registry.json",
+		);
+		const registryData = JSON.parse(fs.readFileSync(registryPath, "utf-8"));
+		return registryData as BigBlocksRegistry;
+	} catch (error) {
+		console.error("Failed to load BigBlocks registry:", error);
+		return null;
+	}
+}
+
+// Organize components by type for easier browsing
+function organizeComponentsByType(
+	registry: BigBlocksRegistry,
+): OrganizedComponents {
+	const organized: OrganizedComponents = {};
+
+	if (!registry?.components) return organized;
+
+	for (const component of registry.components) {
+		const [category, subcategory] = component.type.split(":");
+
+		if (!organized[category]) {
+			organized[category] = {};
+		}
+
+		if (!organized[category][subcategory]) {
+			organized[category][subcategory] = [];
+		}
+
+		organized[category][subcategory].push(component);
+	}
+
+	return organized;
+}
+
+const componentSearchSchema = z.object({
+	category: z
+		.string()
+		.optional()
+		.describe("Component category to search in (component, hook)"),
+	type: z
+		.string()
+		.optional()
+		.describe(
+			"Component type to filter by (auth, social, wallet, market, profile, backup, ui, bap, provider, layout)",
+		),
+	component: z
+		.string()
+		.optional()
+		.describe("Specific component name to get details for"),
+	search: z
+		.string()
+		.optional()
+		.describe("Search term to find components by name or description"),
+	showAll: z.boolean().optional().describe("Show all available components"),
+});
+
+/**
+ * Register the BigBlocks component discovery tool
+ */
+export function registerBigBlocksComponentTool(server: McpServer): void {
+	server.tool(
+		"bigblocks_components",
+		"Discover and learn about BigBlocks React components from the official registry. BigBlocks provides 96+ production-ready components for Bitcoin applications.\n\n" +
+			"Usage examples:\n" +
+			'- List all components: {"showAll": true}\n' +
+			'- Browse by category: {"category": "component"}\n' +
+			'- Filter by type: {"type": "social"}\n' +
+			'- Get component details: {"component": "auth-flow"}\n' +
+			'- Search components: {"search": "authentication"}\n\n' +
+			"Categories:\n" +
+			"- component: React components (auth, social, wallet, market, profile, backup, ui, bap, provider, layout)\n" +
+			"- hook: React hooks for various functionalities\n\n" +
+			"Types:\n" +
+			"- auth: Authentication and login components\n" +
+			"- social: Social media and networking\n" +
+			"- wallet: Bitcoin wallet operations\n" +
+			"- market: NFT and token marketplace\n" +
+			"- profile: User profile management\n" +
+			"- backup: Key backup and recovery\n" +
+			"- ui: General UI components\n" +
+			"- bap: Bitcoin Application Protocol\n" +
+			"- provider: Context providers\n" +
+			"- layout: Layout components",
+		{ args: componentSearchSchema },
+		async ({ args }) => {
+			try {
+				const registry = loadBigBlocksRegistry();
+				if (!registry) {
+					return {
+						content: [
+							{
+								type: "text",
+								text: "Error: Could not load BigBlocks registry data",
+							},
+						],
+						isError: true,
+					};
+				}
+
+				const { category, type, component, search, showAll } = args;
+				const organized = organizeComponentsByType(registry);
+
+				// Show specific component details
+				if (component) {
+					const comp = registry.components.find((c) => c.name === component);
+					if (!comp) {
+						const available = registry.components.map((c) => c.name).join(", ");
+						return {
+							content: [
+								{
+									type: "text",
+									text: `Component "${component}" not found. Available components: ${available}`,
+								},
+							],
+							isError: true,
+						};
+					}
+
+					let result = `# ${comp.name}\n\n`;
+					result += `**Type:** ${comp.type}\n`;
+					result += `**Description:** ${comp.description}\n\n`;
+
+					if (comp.files?.length) {
+						result += `**Files:**\n${comp.files.map((f) => `- ${f}`).join("\n")}\n\n`;
+					}
+
+					if (comp.dependencies?.length) {
+						result += `**Dependencies:** ${comp.dependencies.join(", ")}\n\n`;
+					}
+
+					if (comp.registryDependencies?.length) {
+						result += `**Registry Dependencies:** ${comp.registryDependencies.join(", ")}\n\n`;
+					}
+
+					// Determine the actual component/hook name from files
+					const mainFile = comp.files?.[0];
+					if (mainFile) {
+						const fileName = path.basename(mainFile, path.extname(mainFile));
+						result += `**Import:**\n\`\`\`tsx\nimport { ${fileName} } from 'bigblocks';\n\`\`\`\n\n`;
+					}
+
+					return { content: [{ type: "text", text: result }] };
+				}
+
+				// Search components
+				if (search) {
+					const searchTerm = search.toLowerCase();
+					const matchingComponents = registry.components.filter(
+						(comp) =>
+							comp.name.toLowerCase().includes(searchTerm) ||
+							comp.description.toLowerCase().includes(searchTerm) ||
+							comp.type.toLowerCase().includes(searchTerm),
+					);
+
+					let result = `# BigBlocks Components Search: "${search}"\n\n`;
+					if (matchingComponents.length === 0) {
+						result += "No components found matching your search.";
+					} else {
+						result += `Found ${matchingComponents.length} component(s):\n\n`;
+						for (const comp of matchingComponents) {
+							result += `## ${comp.name} (${comp.type})\n`;
+							result += `${comp.description}\n\n`;
+						}
+					}
+
+					return { content: [{ type: "text", text: result }] };
+				}
+
+				// Filter by category and/or type
+				if (category || type) {
+					let filtered = registry.components;
+
+					if (category) {
+						filtered = filtered.filter((comp) =>
+							comp.type.startsWith(`${category}:`),
+						);
+					}
+
+					if (type) {
+						filtered = filtered.filter((comp) =>
+							comp.type.includes(`:${type}`),
+						);
+					}
+
+					let result = `# BigBlocks Components${category ? ` - ${category}` : ""}${type ? ` - ${type}` : ""}\n\n`;
+
+					if (filtered.length === 0) {
+						result += "No components found matching your criteria.";
+					} else {
+						result += `Found ${filtered.length} component(s):\n\n`;
+						for (const comp of filtered) {
+							result += `## ${comp.name}\n**Type:** ${comp.type}\n**Description:** ${comp.description}\n\n`;
+						}
+					}
+
+					return { content: [{ type: "text", text: result }] };
+				}
+
+				// Show all components organized
+				if (showAll) {
+					let result = "# BigBlocks Component Registry\n\n";
+					result += `**Version:** ${registry.version}\n`;
+					result += `**Total Components:** ${registry.components.length}\n\n`;
+
+					for (const [cat, subcats] of Object.entries(organized)) {
+						result += `## ${cat.charAt(0).toUpperCase() + cat.slice(1)}s\n\n`;
+
+						for (const [subcat, components] of Object.entries(subcats)) {
+							result += `### ${subcat.charAt(0).toUpperCase() + subcat.slice(1)} (${components.length})\n`;
+
+							for (const comp of components) {
+								result += `- **${comp.name}**: ${comp.description}\n`;
+							}
+							result += "\n";
+						}
+					}
+
+					result +=
+						'\n**Get details:** Use {"component": "component-name"} for specific information\n';
+					result +=
+						'**Filter:** Use {"category": "component", "type": "social"} to filter by type';
+
+					return { content: [{ type: "text", text: result }] };
+				}
+
+				// Default: show overview
+				const componentCount = Object.values(organized.component || {}).reduce(
+					(sum, comps) => sum + comps.length,
+					0,
+				);
+				const hookCount = Object.values(organized.hook || {}).reduce(
+					(sum, hooks) => sum + hooks.length,
+					0,
+				);
+
+				return {
+					content: [
+						{
+							type: "text",
+							text: `# BigBlocks Component Registry
+
+**Version:** ${registry.version}
+**Total:** ${registry.components.length} items
+
+**Categories:**
+- **Components:** ${componentCount} React components
+- **Hooks:** ${hookCount} React hooks
+
+**Component Types:**
+${Object.keys(organized.component || {})
+	.map(
+		(type) => `- **${type}**: ${organized.component[type].length} components`,
+	)
+	.join("\n")}
+
+Use {"showAll": true} to see all components, {"category": "component"} to browse components, or {"component": "name"} for details.`,
+						},
+					],
+				};
+			} catch (error) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+						},
+					],
+					isError: true,
+				};
+			}
+		},
+	);
+}