artic-mcp

Instructions

Implementation Reference

• src/tools/GetArtworkByIdTool.ts:12-105 (handler)

  The GetArtworkByIdTool class is the main handler for the 'get-artwork-by-id' tool. It fetches detailed artwork information from the Art Institute of Chicago API, formats it into text, and optionally retrieves and embeds the image.
  export class GetArtworkByIdTool extends BaseTool<typeof artworkByIdSchema, any> { public readonly name: string = 'get-artwork-by-id'; public readonly description: string = `Get additional information, including an image if available, about a specific artwork by its ID` + ` from the Art Institute of Chicago. ` + `Using the value of Artwork ID from the 'search-by-title' tool.`; public readonly inputSchema = artworkByIdSchema; public readonly imageByTitle = new Map<string, string>(); private readonly fields: string[] = Object.keys(artworkSchema._def.shape()); constructor(private server: McpServer) { super(); } public async executeCore(input: z.infer<typeof this.inputSchema>) { const { id, includeImage } = input; const url = new URL(`${this.apiBaseUrl}/artworks/${id}`); url.searchParams.set('fields', this.fields.join(',')); const parsedResponse = await this.safeApiRequest( url, { method: 'GET' }, artworkResponseSchema, ); const artwork = parsedResponse.data; const text = this.formatArtworkDetails(artwork, `${parsedResponse.config.iiif_url}`); const content = []; content.push({ type: 'text' as const, text }); if (includeImage) { const image = await this.getArtworkImage(artwork, `${parsedResponse.config.iiif_url}`); if (image) { content.push(image); } } return { content }; } private formatArtworkDetails(artwork: z.infer<typeof artworkSchema>, iiif_url: string) { return `Title: ${artwork.title}\n` + `${artwork.alt_titles ? `Alt Titles: ${artwork.alt_titles.join(', ')}\n` : ''}` + `Artist: ${artwork.artist_display}\n` + `Artist ID: ${artwork.artist_id}\n` + `Description: ${artwork.description ?? 'No description available'}\n` + `Image ID: ${artwork.image_id}\n` + `Place of Origin: ${artwork.place_of_origin}\n` + `Dimensions: ${artwork.dimensions}\n` + `Medium: ${artwork.medium_display}\n` + `Credit Line: ${artwork.credit_line}\n` + `Department: ${artwork.department_title}\n` + `Is On View: ${artwork.is_on_view ? 'Yes' : 'No'}\n` + `Main Reference Number: ${artwork.main_reference_number}\n` + `Has not been viewed much: ${artwork.has_not_been_viewed_much ? 'Yes' : 'No'}\n` + `Date Start: ${artwork.date_start ?? 'N/A'}\n` + `Date End: ${artwork.date_end ?? 'N/A'}\n` + `Date: ${artwork.date_display ?? 'N/A'}\n` + `Fiscal Year: ${artwork.fiscal_year ?? 'N/A'}\n` + `Is Public Domain: ${artwork.is_public_domain ? 'Yes' : 'No'}\n` + `Gallery: ${artwork.gallery_title ?? 'N/A'}\n` + `Artwork Type: ${artwork.artwork_type_title}\n` + `Artist Title: ${artwork.artist_title}\n` + `Artist Titles: ${artwork.artist_titles.join(', ')}\n` + `Style Title: ${artwork.style_title ?? 'N/A'}\n` + `Image URL: ${artwork.image_id ? `${iiif_url}/${artwork.image_id}/full/843,/0/default.jpg` : 'N/A'}\n`; } private async getArtworkImage(artwork: z.infer<typeof artworkSchema>, iiif_url: string) { if (artwork.image_id) { try { const imageURL = `${iiif_url}/${artwork.image_id}/full/843,/0/default.jpg`; const imageBase64 = await imageToBase64(imageURL); const title = `${artwork.title} (${artwork.artist_title})`; this.imageByTitle.set(title, imageBase64); this.server.server.notification({ method: 'notifications/resources/list_changed', }); return { type: 'image' as const, data: imageBase64, mimeType: 'image/jpeg', }; } catch (error) { console.error(`Error fetching image for artwork ${artwork.id}:`, error); return { type: 'text' as const, text: `Error fetching image for artwork ${artwork.id}: ${error}`, }; } } return null; } }
• src/tools/GetArtworkByIdTool.ts:7-10 (schema)

  Input schema for the get-artwork-by-id tool defining parameters id and optional includeImage.
  const artworkByIdSchema = z.object({ id: z.number().describe('The ID of the artwork to retrieve.'), includeImage: z.boolean().optional().default(true).describe('Whether to include the artwork image in the response.'), });
• src/schemas/schemas.ts:58-91 (schema)

  Zod schemas for single artwork data (artworkSchema) and API response (artworkResponseSchema) used for validation in the tool handler.
  export const artworkSchema = z.object({ id: z.number(), title: z.string(), alt_titles: z.array(z.string()).nullable(), thumbnail: thumbnailSchema, main_reference_number: z.string(), has_not_been_viewed_much: z.boolean(), date_start: z.number().nullable(), date_end: z.number().nullable(), date_display: z.string().nullable(), artist_display: z.string(), place_of_origin: z.string(), description: z.string().nullable(), dimensions: z.string(), medium_display: z.string(), credit_line: z.string(), fiscal_year: z.number().nullable(), is_public_domain: z.boolean(), gallery_title: z.string().nullable(), artwork_type_title: z.string(), is_on_view: z.boolean(), department_title: z.string(), artist_title: z.string(), artist_titles: z.array(z.string()), style_title: z.string().nullable(), artist_id: z.number(), image_id: z.string(), }); export const artworkResponseSchema = z.object({ data: artworkSchema, info: apiInfoSchema, config: apiConfigSchema, });
• src/index.ts:64-68 (registration)

  Registration of the 'get-artwork-by-id' tool with the MCP server using server.tool().
  this.getArtworkByIdTool.name, this.getArtworkByIdTool.description, this.getArtworkByIdTool.inputSchema.shape, this.getArtworkByIdTool.execute.bind(this.getArtworkByIdTool), );
• src/tools/BaseTool.ts:37-62 (helper)

  safeApiRequest method from BaseTool, used by the handler for safe API calls with Zod validation.
  protected async safeApiRequest<S extends z.ZodType>( url: URL | string, options: RequestInit, schema: S, ): Promise<z.infer<S>> { const response = await articRateLimiter.fetch(url.toString(), { ...options, headers: { ...this.getDefaultHeaders(), ...(options.headers || {}), }, }); if (!response.ok) { throw new Error(`HTTP error! status: ${response.status}`); } const jsonResponse = await response.json(); const parsedResponse = schema.safeParse(jsonResponse); if (!parsedResponse.success) { throw new Error(`Invalid response shape: ${JSON.stringify(parsedResponse.error.issues, null, 2)}`); } return parsedResponse.data; }