bsv-mcp 0.0.1

package/tools/ordinals/getBsv20ById.ts

@@ -0,0 +1,94 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import { z } from "zod";
+
+// Schema for get BSV20 by ID arguments
+export const getBsv20ByIdArgsSchema = z.object({
+	id: z.string().describe("BSV20 token ID in outpoint format (txid_vout)"),
+});
+
+export type GetBsv20ByIdArgs = z.infer<typeof getBsv20ByIdArgsSchema>;
+
+// BSV20 token response type
+interface Bsv20TokenResponse {
+	id: string;
+	tick?: string;
+	sym?: string;
+	max?: string;
+	lim?: string;
+	dec?: number;
+	supply?: string;
+	amt?: string;
+	status?: number;
+	icon?: string;
+	height?: number;
+	[key: string]: unknown;
+}
+
+/**
+ * Register the BSV20 token lookup tool
+ */
+export function registerGetBsv20ByIdTool(server: McpServer): void {
+	server.tool(
+		"ordinals_getBsv20ById",
+		{
+			args: getBsv20ByIdArgsSchema,
+		},
+		async (
+			{ args }: { args: GetBsv20ByIdArgs },
+			extra: RequestHandlerExtra,
+		) => {
+			try {
+				const { id } = args;
+
+				// Validate ID format (should be in outpoint format)
+				if (!/^[0-9a-f]{64}_\d+$/i.test(id)) {
+					throw new Error("Invalid BSV20 ID format. Expected 'txid_vout'");
+				}
+
+				// Fetch BSV20 token data from GorillaPool API
+				const response = await fetch(
+					`https://ordinals.gorillapool.io/api/bsv20/id/${id}`,
+				);
+
+				if (response.status === 404) {
+					return {
+						content: [
+							{
+								type: "text",
+								text: JSON.stringify({ error: "BSV20 token not found" }),
+							},
+						],
+					};
+				}
+
+				if (!response.ok) {
+					throw new Error(
+						`API error: ${response.status} ${response.statusText}`,
+					);
+				}
+
+				const data = (await response.json()) as Bsv20TokenResponse;
+
+				return {
+					content: [
+						{
+							type: "text",
+							text: JSON.stringify(data, null, 2),
+						},
+					],
+				};
+			} catch (error) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: error instanceof Error ? error.message : String(error),
+						},
+					],
+					isError: true,
+				};
+			}
+		},
+	);
+}

package/tools/ordinals/getInscription.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";
+
+// Schema for get inscription arguments
+export const getInscriptionArgsSchema = z.object({
+	outpoint: z.string().describe("Outpoint in format 'txid_vout'"),
+});
+
+export type GetInscriptionArgs = z.infer<typeof getInscriptionArgsSchema>;
+
+// Inscription API response type
+interface InscriptionResponse {
+	outpoint: string;
+	origin: {
+		outpoint: string;
+		data?: {
+			insc?: {
+				text?: string;
+				json?: unknown;
+				file?: {
+					hash?: string;
+					size?: number;
+					type?: string;
+				};
+			};
+		};
+	};
+	height?: number;
+	idx?: number;
+	satoshis?: number;
+	script?: string;
+	spend?: string;
+	[key: string]: unknown;
+}
+
+/**
+ * Register the Ordinals inscription lookup tool
+ */
+export function registerGetInscriptionTool(server: McpServer): void {
+	server.tool(
+		"ordinals_getInscription",
+		{
+			args: getInscriptionArgsSchema,
+		},
+		async (
+			{ args }: { args: GetInscriptionArgs },
+			extra: RequestHandlerExtra,
+		) => {
+			try {
+				const { outpoint } = args;
+
+				// Validate outpoint format
+				if (!/^[0-9a-f]{64}_\d+$/i.test(outpoint)) {
+					throw new Error("Invalid outpoint format. Expected 'txid_vout'");
+				}
+
+				// Fetch inscription data from GorillaPool API
+				const response = await fetch(
+					`https://ordinals.gorillapool.io/api/inscriptions/${outpoint}`,
+				);
+
+				if (response.status === 404) {
+					return {
+						content: [
+							{
+								type: "text",
+								text: JSON.stringify({ error: "Inscription not found" }),
+							},
+						],
+					};
+				}
+
+				if (!response.ok) {
+					throw new Error(
+						`API error: ${response.status} ${response.statusText}`,
+					);
+				}
+
+				const data = (await response.json()) as InscriptionResponse;
+
+				return {
+					content: [
+						{
+							type: "text",
+							text: JSON.stringify(data, null, 2),
+						},
+					],
+				};
+			} catch (error) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: error instanceof Error ? error.message : String(error),
+						},
+					],
+					isError: true,
+				};
+			}
+		},
+	);
+}

package/tools/ordinals/index.ts

@@ -0,0 +1,19 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerBsv20MarketSalesTool } from "./bsv20MarketSales";
+import { registerGetBsv20ByIdTool } from "./getBsv20ById";
+import { registerGetInscriptionTool } from "./getInscription";
+import { registerMarketListingsTool } from "./marketListings";
+import { registerSearchInscriptionsTool } from "./searchInscriptions";
+
+/**
+ * Register all Ordinals tools with the MCP server
+ * @param server The MCP server instance
+ */
+export function registerOrdinalsTools(server: McpServer): void {
+	// Register Ordinals-related tools
+	registerGetInscriptionTool(server);
+	registerSearchInscriptionsTool(server);
+	registerMarketListingsTool(server);
+	registerBsv20MarketSalesTool(server);
+	registerGetBsv20ByIdTool(server);
+}

package/tools/ordinals/marketListings.ts

@@ -0,0 +1,137 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import { z } from "zod";
+
+// Schema for market listings arguments
+export const marketListingsArgsSchema = z.object({
+	limit: z
+		.number()
+		.int()
+		.min(1)
+		.max(100)
+		.default(20)
+		.describe("Number of results (1-100, default 20)"),
+	offset: z.number().int().min(0).default(0).describe("Pagination offset"),
+	sort: z
+		.enum(["recent", "price", "num"])
+		.default("recent")
+		.describe("Sort method (recent, price, or num)"),
+	dir: z
+		.enum(["asc", "desc"])
+		.default("desc")
+		.describe("Sort direction (asc or desc)"),
+	address: z.string().optional().describe("Bitcoin address"),
+	origin: z.string().optional().describe("Origin outpoint"),
+	mime: z.string().optional().describe("MIME type filter"),
+	num: z.string().optional().describe("Inscription number"),
+	minPrice: z.number().optional().describe("Minimum price in satoshis"),
+	maxPrice: z.number().optional().describe("Maximum price in satoshis"),
+});
+
+export type MarketListingsArgs = z.infer<typeof marketListingsArgsSchema>;
+
+// Simplified market listing response type
+interface MarketListingResponse {
+	results: Array<{
+		outpoint: string;
+		origin: {
+			outpoint: string;
+			data?: {
+				insc?: {
+					text?: string;
+					file?: {
+						type?: string;
+						size?: number;
+					};
+				};
+			};
+		};
+		data?: {
+			list?: {
+				price?: number;
+				payout?: string;
+				sale?: boolean;
+			};
+		};
+		satoshis?: number;
+		[key: string]: unknown;
+	}>;
+	total: number;
+}
+
+/**
+ * Register the Ordinals market listings tool
+ */
+export function registerMarketListingsTool(server: McpServer): void {
+	server.tool(
+		"ordinals_marketListings",
+		{
+			args: marketListingsArgsSchema,
+		},
+		async (
+			{ args }: { args: MarketListingsArgs },
+			extra: RequestHandlerExtra,
+		) => {
+			try {
+				const {
+					limit,
+					offset,
+					sort,
+					dir,
+					address,
+					origin,
+					mime,
+					num,
+					minPrice,
+					maxPrice,
+				} = args;
+
+				// Build the URL with query parameters
+				const url = new URL("https://ordinals.gorillapool.io/api/market");
+				url.searchParams.append("limit", limit.toString());
+				url.searchParams.append("offset", offset.toString());
+				url.searchParams.append("sort", sort);
+				url.searchParams.append("dir", dir);
+
+				if (address) url.searchParams.append("address", address);
+				if (origin) url.searchParams.append("origin", origin);
+				if (mime) url.searchParams.append("mime", mime);
+				if (num) url.searchParams.append("num", num);
+				if (minPrice !== undefined)
+					url.searchParams.append("min", minPrice.toString());
+				if (maxPrice !== undefined)
+					url.searchParams.append("max", maxPrice.toString());
+
+				// Fetch market listings from GorillaPool API
+				const response = await fetch(url.toString());
+
+				if (!response.ok) {
+					throw new Error(
+						`API error: ${response.status} ${response.statusText}`,
+					);
+				}
+
+				const data = (await response.json()) as MarketListingResponse;
+
+				return {
+					content: [
+						{
+							type: "text",
+							text: JSON.stringify(data, null, 2),
+						},
+					],
+				};
+			} catch (error) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: error instanceof Error ? error.message : String(error),
+						},
+					],
+					isError: true,
+				};
+			}
+		},
+	);
+}

package/tools/ordinals/searchInscriptions.ts

@@ -0,0 +1,118 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import { z } from "zod";
+
+// Schema for search inscriptions arguments
+export const searchInscriptionsArgsSchema = z.object({
+	limit: z
+		.number()
+		.int()
+		.min(1)
+		.max(100)
+		.default(20)
+		.describe("Number of results (1-100, default 20)"),
+	offset: z.number().int().min(0).default(0).describe("Pagination offset"),
+	dir: z
+		.enum(["asc", "desc"])
+		.default("desc")
+		.describe("Sort direction (asc or desc)"),
+	num: z.string().optional().describe("Inscription number"),
+	origin: z.string().optional().describe("Origin outpoint"),
+	address: z.string().optional().describe("Bitcoin address"),
+	map: z.string().optional().describe("Map field"),
+	terms: z.string().optional().describe("Search terms"),
+	mime: z.string().optional().describe("MIME type filter"),
+});
+
+export type SearchInscriptionsArgs = z.infer<
+	typeof searchInscriptionsArgsSchema
+>;
+
+// Simplified inscription response type
+interface InscriptionSearchResponse {
+	results: Array<{
+		outpoint: string;
+		origin: {
+			outpoint: string;
+			data?: {
+				insc?: {
+					text?: string;
+					file?: {
+						type?: string;
+						size?: number;
+					};
+				};
+			};
+		};
+		height?: number;
+		satoshis?: number;
+		[key: string]: unknown;
+	}>;
+	total: number;
+}
+
+/**
+ * Register the Ordinals search inscriptions tool
+ */
+export function registerSearchInscriptionsTool(server: McpServer): void {
+	server.tool(
+		"ordinals_searchInscriptions",
+		{
+			args: searchInscriptionsArgsSchema,
+		},
+		async (
+			{ args }: { args: SearchInscriptionsArgs },
+			extra: RequestHandlerExtra,
+		) => {
+			try {
+				const { limit, offset, dir, num, origin, address, map, terms, mime } =
+					args;
+
+				// Build the URL with query parameters
+				const url = new URL(
+					"https://ordinals.gorillapool.io/api/inscriptions/search",
+				);
+				url.searchParams.append("limit", limit.toString());
+				url.searchParams.append("offset", offset.toString());
+				url.searchParams.append("dir", dir);
+
+				if (num) url.searchParams.append("num", num);
+				if (origin) url.searchParams.append("origin", origin);
+				if (address) url.searchParams.append("address", address);
+				if (map) url.searchParams.append("map", map);
+				if (terms) url.searchParams.append("terms", terms);
+				if (mime) url.searchParams.append("mime", mime);
+
+				// Fetch inscriptions data from GorillaPool API
+				const response = await fetch(url.toString());
+
+				if (!response.ok) {
+					throw new Error(
+						`API error: ${response.status} ${response.statusText}`,
+					);
+				}
+
+				const data = (await response.json()) as InscriptionSearchResponse;
+
+				return {
+					content: [
+						{
+							type: "text",
+							text: JSON.stringify(data, null, 2),
+						},
+					],
+				};
+			} catch (error) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: error instanceof Error ? error.message : String(error),
+						},
+					],
+					isError: true,
+				};
+			}
+		},
+	);
+}

package/tools/utils/conversion.ts

@@ -0,0 +1,58 @@
+import { Utils } from "@bsv/sdk";
+import { z } from "zod";
+const {
+	toArray: bsvToArray,
+	toBase64: bsvToBase64,
+	toHex: bsvToHex,
+	toUTF8: bsvToUTF8,
+} = Utils;
+
+const encodingSchema = z.enum(["utf8", "hex", "base64", "binary"]);
+
+/**
+ * Convert data between hex, base64, utf8, and binary (number array) formats.
+ * @param data - The input data as a string (hex, base64, utf8, or JSON array string for binary)
+ * @param from - The encoding of the input data
+ * @param to - The desired encoding of the output data
+ * @returns The converted data as a string (except for binary, which is a JSON array string)
+ */
+export function convertData({
+	data,
+	from,
+	to,
+}: {
+	data: string;
+	from: "hex" | "base64" | "utf8" | "binary";
+	to: "hex" | "base64" | "utf8" | "binary";
+}): string {
+	encodingSchema.parse(from);
+	encodingSchema.parse(to);
+
+	let arr: number[];
+	if (from === "binary") {
+		try {
+			arr = JSON.parse(data);
+			if (!Array.isArray(arr) || !arr.every((n) => typeof n === "number")) {
+				throw new Error();
+			}
+		} catch {
+			throw new Error("Invalid binary input: must be a JSON array of numbers");
+		}
+	} else {
+		arr = bsvToArray(data, from);
+	}
+
+	if (to === "binary") {
+		return JSON.stringify(arr);
+	}
+	if (to === "hex") {
+		return bsvToHex(arr);
+	}
+	if (to === "base64") {
+		return bsvToBase64(arr);
+	}
+	if (to === "utf8") {
+		return bsvToUTF8(arr);
+	}
+	throw new Error("Invalid 'to' encoding");
+}

package/tools/utils/index.ts

@@ -0,0 +1,50 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { convertData } from "./conversion";
+
+const encodingSchema = z.enum(["utf8", "hex", "base64", "binary"]);
+
+/**
+ * Register the unified conversion tool with the MCP server
+ * @param server The MCP server instance
+ */
+export function registerUtilsTools(server: McpServer): void {
+	server.tool(
+		"utils_convertData",
+		{
+			args: z.object({
+				data: z.string(),
+				from: encodingSchema,
+				to: encodingSchema,
+			}),
+		},
+		async ({ args }) => {
+			try {
+				const result = convertData({
+					data: args.data,
+					from: args.from,
+					to: args.to,
+				});
+				return {
+					content: [
+						{
+							type: "text",
+							text: result,
+						},
+					],
+				};
+			} catch (err: unknown) {
+				const msg = err instanceof Error ? err.message : String(err);
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Error: ${msg}`,
+						},
+					],
+					isError: true,
+				};
+			}
+		},
+	);
+}

package/tools/wallet/getAddress.ts

@@ -0,0 +1,38 @@
+import { PrivateKey } from "@bsv/sdk";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+/**
+ * Register the tool to get the wallet address
+ * @param server The MCP server instance
+ */
+export function registerGetAddressTool(server: McpServer): void {
+	server.tool(
+		"wallet_getAddress",
+		{
+			args: z.object({}).optional(),
+		},
+		async () => {
+			try {
+				const wif = process.env.PRIVATE_KEY_WIF;
+				if (!wif) throw new Error("PRIVATE_KEY_WIF env var not set");
+				const privKey = PrivateKey.fromWif(wif);
+				const address = privKey.toAddress();
+				return {
+					content: [
+						{
+							type: "text",
+							text: JSON.stringify({ address, status: "ok" }),
+						},
+					],
+				};
+			} catch (err: unknown) {
+				const msg = err instanceof Error ? err.message : String(err);
+				return {
+					content: [{ type: "text", text: msg }],
+					isError: true,
+				};
+			}
+		},
+	);
+}