get-artwork-by-artist

Instructions

Implementation Reference

• src/tools/GetArtworkByArtistTool.ts:11-50 (handler)

  The GetArtworkByArtistTool class implements the core execution logic for the 'get-artwork-by-artist' tool, handling input parsing, API request construction to the Art Institute of Chicago search endpoint, response validation, and formatting.

  export class GetArtworkByArtistTool extends BaseTool<typeof artworkByArtistSchema, any> {
    public readonly name: string = 'get-artwork-by-artist';
    public readonly description: string = 'Get artworks by artist id in the Art Institute of Chicago collection. Pagination is supported with the page parameter.';
    public readonly inputSchema = artworkByArtistSchema;
  
    constructor() {
      super();
    }
  
    public async executeCore(input: z.infer<typeof this.inputSchema>) {
      const { id, limit, page } = input;
  
      const query = {
        query: {
          term: {
            artist_id: id,
          },
        },
      };
  
      const url = new URL(`${this.apiBaseUrl}/artworks/search`);
      url.searchParams.set('page', `${page}`);
      url.searchParams.set('limit', `${limit}`);
      url.searchParams.set('query', `artist_id:${id}`);
  
      const parsedData = await this.safeApiRequest(
        url,
        {
          method: 'POST',
          body: JSON.stringify(query),
        },
        artworkSearchResponseSchema,
      );
      // Attach pagination info to each artwork for formatting
      parsedData.data.forEach((artwork) => {
        (artwork as any)._pagination = parsedData.pagination;
      });
      return this.formatArtworkList(parsedData.data, `Artworks by artist ID ${id}`);
    }
  }

• src/tools/GetArtworkByArtistTool.ts:5-9 (schema)

  Input schema (Zod) defining parameters for the tool: artist ID (required), optional limit and page for pagination.

  const artworkByArtistSchema = z.object({
    id: z.number().describe('The id of the artist to search for artworks. Should be the Artist ID of the `search-for-artist` tool.'),
    limit: z.number().optional().default(10).describe('The number of resources to return per page.'),
    page: z.number().optional().default(1).describe('The page of results to return. Used for pagination.'),
  });

• src/schemas/schemas.ts:36-51 (schema)

  Output schema (Zod) for validating the artwork search API response, used in the tool's safeApiRequest method.

  export const artworkSearchResponseSchema = z.object({
    preference: z.string().nullable(),
    pagination: paginationSchema,
    data: z.array(z.object({
      _score: z.number(),
      id: z.number(),
      api_model: z.string(),
      api_link: z.string(),
      is_boosted: z.boolean(),
      title: z.string(),
      thumbnail: thumbnailSchema.nullable(),
      timestamp: z.string(),
    })),
    info: apiInfoSchema,
    config: apiConfigSchema,
  });

• src/index.ts:81-86 (registration)

  Registers the 'get-artwork-by-artist' tool with the MCP server by calling server.tool() with the tool's name, description, input schema, and execute method.

  this.server.tool(
    this.getArtworkByArtistTool.name,
    this.getArtworkByArtistTool.description,
    this.getArtworkByArtistTool.inputSchema.shape,
    this.getArtworkByArtistTool.execute.bind(this.getArtworkByArtistTool),
  );

• src/tools/BaseTool.ts:64-89 (helper)

  formatArtworkList helper method used by the tool to format the list of artworks into a readable text response with pagination info.

  protected formatArtworkList(artworks: any[], query: string) {
    if (artworks.length === 0) {
      return {
        content: [{ type: 'text' as const, text: `No artworks found for "${query}".` }],
        isError: false,
      };
    }
  
    const artText = artworks.map((artwork) => {
      return `Title: ${artwork.title}\n`
        + `Artwork ID: ${artwork.id}\n`
        + `Thumbnail alt text: ${artwork.thumbnail?.alt_text ?? 'No thumbnail available'}\n`
        + `Score: ${artwork._score}\n`;
    }).join('\n-----\n');
  
    const paginationText = artworks.length > 0
      ? `\nPagination Info\n`
      + `Total: ${artworks[0]._pagination?.total || 'Unknown'}\n`
      + `Total Pages: ${artworks[0]._pagination?.total_pages || 'Unknown'}\n`
      + `Current Page: ${artworks[0]._pagination?.current_page || 'Unknown'}`
      : '';
  
    return {
      content: [{ type: 'text' as const, text: artText + paginationText }],
    };
  }