ordinals_searchInscriptions

Instructions

Implementation Reference

• tools/ordinals/searchInscriptions.ts:64-117 (handler)

  The main handler function that executes the tool logic: constructs API URL with search parameters, fetches data from GorillaPool ordinals API, and returns JSON response or error.

  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,
  		};
  	}
  },

• tools/ordinals/searchInscriptions.ts:6-25 (schema)

  Zod schema defining input parameters for the ordinals_searchInscriptions tool, including limits, filters, and pagination.

  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"),
  });

• tools/ordinals/searchInscriptions.ts:57-119 (registration)

  Function that registers the ordinals_searchInscriptions tool with the MCP server, providing name, description, schema, and handler.

  export function registerSearchInscriptionsTool(server: McpServer): void {
  	server.tool(
  		"ordinals_searchInscriptions",
  		"Searches for Bitcoin SV ordinal inscriptions using flexible criteria. This powerful search tool supports filtering by address, inscription content, MIME type, MAP fields, and other parameters. Results include detailed information about each matched inscription. Ideal for discovering NFTs and exploring the ordinals ecosystem.",
  		{
  			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,
  				};
  			}
  		},
  	);
  }