ordinals_searchInscriptions
Search Bitcoin SV ordinals inscriptions by address, content, MIME type, or MAP fields. Filter and retrieve detailed NFT data to explore the ordinals ecosystem efficiently.
Instructions
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.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| args | Yes |
Implementation Reference
- 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, }; } },
- 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, }; } }, ); }