get-museum-object

Instructions

Implementation Reference

• src/tools/GetObjectTool.ts:9-110 (handler)

  The GetObjectTool class implements the 'get-museum-object' tool. The execute() method (line 25) fetches object data from the Met Museum API via apiClient.getObject(), formats the response as text content, optionally fetches and returns the image as base64, and returns structured content with the full object data.

  export class GetObjectTool {
    public readonly name: string = 'get-museum-object';
    public readonly description: string = 'Get a museum object by its ID, from the Metropolitan Museum of Art Collection. '
      + 'Use this when the user asks for deeper details on a specific object ID.';
  
    public readonly inputSchema = z.object({
      objectId: z.number().int().positive().describe('The positive integer ID of the museum object to retrieve'),
      returnImage: z.boolean().optional().default(true).describe('Whether to return the image (if available) of the object'),
    }).describe('Get a museum object by its ID');
  
    private readonly apiClient: MetMuseumApiClient;
  
    constructor(apiClient: MetMuseumApiClient) {
      this.apiClient = apiClient;
    }
  
    public async execute({ objectId, returnImage }: z.infer<typeof this.inputSchema>): Promise<CallToolResult> {
      try {
        const data = await this.apiClient.getObject(objectId);
        const tagsText = Array.isArray(data.tags)
          ? data.tags
              .map(tag => tag?.term?.trim())
              .filter((term): term is string => Boolean(term))
              .join(', ')
          : '';
  
        let text = `Object ID: ${data.objectID}\n`
          + `Title: ${data.title}\n`
          + `${data.artistDisplayName ? `Artist: ${data.artistDisplayName}\n` : ''}`
          + `${data.artistDisplayBio ? `Artist Bio: ${data.artistDisplayBio}\n` : ''}`
          + `${data.department ? `Department: ${data.department}\n` : ''}`
          + `${data.objectDate ? `Date: ${data.objectDate}\n` : ''}`
          + `${data.creditLine ? `Credit Line: ${data.creditLine}\n` : ''}`
          + `${data.medium ? `Medium: ${data.medium}\n` : ''}`
          + `${data.dimensions ? `Dimensions: ${data.dimensions}\n` : ''}`
          + `${data.primaryImage ? `Primary Image URL: ${data.primaryImage}\n` : ''}`
          + `${tagsText ? `Tags: ${tagsText}\n` : ''}`;
  
        let imageContent: ImageContent | null = null;
        let imageFetchFailed = false;
        const preferredImageUrl = data.primaryImageSmall || data.primaryImage;
  
        if (returnImage && preferredImageUrl) {
          try {
            const image = await this.apiClient.getImageAsBase64(preferredImageUrl);
            imageContent = {
              type: 'image',
              data: image.data,
              mimeType: image.mimeType,
            };
          }
          catch {
            // Note: Image fetch failed - we'll add a note to the text below.
            // This can happen due to network issues, timeouts, or invalid URLs.
            imageFetchFailed = true;
          }
        }
  
        if (imageFetchFailed) {
          const fallbackImageUrl = data.primaryImage || data.primaryImageSmall;
          text += fallbackImageUrl
            ? `\nNote: Image could not be loaded. You can try accessing it directly here: ${fallbackImageUrl}`
            : '\nNote: Image could not be loaded.';
        }
  
        const content: Array<TextContent | ImageContent> = [];
        content.push({
          type: 'text',
          text,
        });
        if (imageContent) {
          content.push(imageContent);
        }
  
        const structuredContent: GetMuseumObjectStructuredContent = {
          object: data,
        };
  
        return {
          content,
          structuredContent,
        };
      }
      catch (error) {
        if (error instanceof MetMuseumApiError) {
          const message = error.isUserFriendly
            ? error.message
            : `Error getting museum object id ${objectId}: ${error.message}`;
          return {
            content: [{ type: 'text', text: message }],
            isError: true,
          };
        }
        // Note: Error is already returned to user in the tool response.
        // No need to log to stderr as it would leak implementation details in stdio mode.
        return {
          content: [{ type: 'text', text: `Error getting museum object id ${objectId}: ${error}` }],
          isError: true,
        };
      }
    }
  }

• src/types/types.ts:130-132 (schema)

  The GetMuseumObjectStructuredContentSchema defines the output schema for the tool, containing the full object response data validated against ObjectResponseSchema (lines 55-120).

  export const GetMuseumObjectStructuredContentSchema = z.object({
    object: ObjectResponseSchema.describe('Detailed object data for the requested object ID'),
  });

• src/tools/GetObjectTool.ts:14-17 (schema)

  The input schema for the tool, accepting objectId (required positive integer) and returnImage (optional boolean, defaults to true).

  public readonly inputSchema = z.object({
    objectId: z.number().int().positive().describe('The positive integer ID of the museum object to retrieve'),
    returnImage: z.boolean().optional().default(true).describe('Whether to return the image (if available) of the object'),
  }).describe('Get a museum object by its ID');

• src/MetMuseumServer.ts:137-158 (registration)

  The tool is registered with registerAppTool() using the name 'get-museum-object' (via getMuseumObject.name), with annotations including title 'Get Met Museum Object', and is bound to getMuseumObject.execute.

  registerAppTool(
    server,
    getMuseumObject.name,
    {
      description: getMuseumObject.description,
      inputSchema: getMuseumObject.inputSchema.shape,
      outputSchema: GetMuseumObjectStructuredContentSchema.shape,
      annotations: {
        title: 'Get Met Museum Object',
        readOnlyHint: true,
        destructiveHint: false,
        idempotentHint: true,
        openWorldHint: true,
      },
      _meta: {
        ui: {
          resourceUri: getMuseumObjectAppResource.uri,
        },
      },
    },
    getMuseumObject.execute.bind(getMuseumObject),
  );

• src/api/MetMuseumApiClient.ts:235-245 (helper)

  The getObject() method on the API client fetches object data from the Met Museum API, normalizes nulls to undefined, and validates the response against ObjectResponseSchema.

  public async getObject(objectId: number): Promise<z.infer<typeof ObjectResponseSchema>> {
    const url = `${this.objectBaseUrl}${objectId}`;
    const rawData = await this.fetchJson(url);
    const normalizedData = normalizeNulls(rawData);
    const parseResult = ObjectResponseSchema.safeParse(normalizedData);
    if (!parseResult.success) {
      logSchemaValidationFailure('object', parseResult.error, { objectId, url });
      throw createUnexpectedResponseError('object');
    }
    return parseResult.data;
  }