list-departments

Instructions

Implementation Reference

• src/tools/ListDepartmentsTool.ts:9-47 (handler)

  The ListDepartmentsTool class that implements the 'list-departments' tool. Its execute() method calls the API client, formats results as text, and returns structured content.

  export class ListDepartmentsTool {
    public readonly name: string = 'list-departments';
    public readonly description: string = 'List all departments in the Metropolitan Museum of Art (Met Museum)';
    public readonly inputSchema = z.object({}).describe('No input required');
  
    private readonly apiClient: MetMuseumApiClient;
  
    constructor(apiClient: MetMuseumApiClient) {
      this.apiClient = apiClient;
    }
  
    public async execute(): Promise<CallToolResult> {
      try {
        const departments = await this.apiClient.listDepartments();
        const structuredContent: ListDepartmentsStructuredContent = {
          departments,
        };
        const text = departments.map((department) => {
          return `Department ID: ${department.departmentId}, Display Name: ${department.displayName}`;
        }).join('\n');
        return {
          content: [{ type: 'text', text }],
          structuredContent,
          isError: false,
        };
      }
      catch (error) {
        // Note: Error is returned to user in the tool response below.
        // No need to log to stderr as it would leak implementation details in stdio mode.
        const message = error instanceof MetMuseumApiError && error.isUserFriendly
          ? error.message
          : `Error listing departments: ${error}`;
        return {
          content: [{ type: 'text', text: message }],
          isError: true,
        };
      }
    }
  }

• src/MetMuseumServer.ts:93-114 (registration)

  Registration of the 'list-departments' tool via registerAppTool(). Wires the tool name, description, input/output schemas, annotations, and execute handler.

  registerAppTool(
    server,
    listDepartments.name,
    {
      description: listDepartments.description,
      inputSchema: listDepartments.inputSchema.shape,
      outputSchema: DepartmentsSchema.shape,
      annotations: {
        title: 'List Met Departments',
        readOnlyHint: true,
        destructiveHint: false,
        idempotentHint: true,
        openWorldHint: true,
      },
      _meta: {
        ui: {
          visibility: ['model', 'app'],
        },
      },
    },
    listDepartments.execute.bind(listDepartments),
  );

• src/types/types.ts:12-18 (schema)

  DepartmentSchema and DepartmentsSchema Zod schemas defining the shape of each department object (departmentId, displayName) and the overall response array.

  export const DepartmentSchema = z.object({
    departmentId: z.number().describe(
      'Department ID as an integer. The departmentId is to be used as a query '
      + 'parameter on the `/objects` endpoint',
    ),
    displayName: z.string().describe('Display name for a department'),
  });

• src/api/MetMuseumApiClient.ts:141-160 (helper)

  The listDepartments() method on MetMuseumApiClient that fetches departments from the Met Museum API with caching and request deduplication.

  public async listDepartments(): Promise<z.infer<typeof DepartmentsSchema>['departments']> {
    const now = Date.now();
    if (this.departmentsCache && now < this.departmentsCacheExpiresAt) {
      return this.departmentsCache;
    }
  
    if (!this.departmentsRequestInFlight) {
      this.departmentsRequestInFlight = this.fetchAndParse(this.departmentsUrl, DepartmentsSchema, 'departments')
        .then((data) => {
          this.departmentsCache = data.departments;
          this.departmentsCacheExpiresAt = Date.now() + this.departmentsCacheTtlMs;
          return data.departments;
        })
        .finally(() => {
          this.departmentsRequestInFlight = undefined;
        });
    }
  
    return await this.departmentsRequestInFlight;
  }

• src/MetMuseumServer.ts:56-60 (registration)

  Instantiation of the ListDepartmentsTool with the API client dependency, and passing it into setupTools().

  const metMuseumApiClient = new MetMuseumApiClient();
  const listDepartments = new ListDepartmentsTool(metMuseumApiClient);
  const search = new SearchMuseumObjectsTool(metMuseumApiClient);
  const getMuseumObject = new GetObjectTool(metMuseumApiClient);
  const openMetExplorer = new OpenMetExplorerTool();