teamtailor_list_candidates

Instructions

Implementation Reference

• src/server.ts:19-44 (registration)

  The tool 'teamtailor_list_candidates' is registered with the MCP server using server.tool(). It defines the schema (pageSize, page, filter) and handler callback.

  server.tool(
    "teamtailor_list_candidates",
    "List and filter candidates.",
    {
      pageSize: z.number().default(10),
      page: z.number().default(1),
      filter: z.object({
        createdAfter: z.string().optional(),
        createdBefore: z.string().optional(),
        updatedAfter: z.string().optional(),
        updatedBefore: z.string().optional(),
      }).optional(),
    },
    async ({ pageSize, page, filter}) => {
      const candidates = await client.listCandidates({ page, perPage: pageSize, filter });
  
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(candidates),
          }
        ]
      }
    }
  );

• src/server.ts:32-43 (handler)

  The handler function for teamtailor_list_candidates. It calls client.listCandidates() with pagination/filter params and returns the JSON-stringified result.

  async ({ pageSize, page, filter}) => {
    const candidates = await client.listCandidates({ page, perPage: pageSize, filter });
  
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(candidates),
        }
      ]
    }
  }

• src/server.ts:22-31 (schema)

  Input schema for the tool: pageSize (number, default 10), page (number, default 1), and an optional filter object with createdAfter, createdBefore, updatedAfter, updatedBefore strings.

  {
    pageSize: z.number().default(10),
    page: z.number().default(1),
    filter: z.object({
      createdAfter: z.string().optional(),
      createdBefore: z.string().optional(),
      updatedAfter: z.string().optional(),
      updatedBefore: z.string().optional(),
    }).optional(),
  },

• src/teamtailor.ts:69-92 (helper)

  The client.listCandidates() method that builds the /candidates URL with pagination and filter query params, then makes a GET request and returns the data.

  async listCandidates(params: ListCandidatesParams = {}): Promise<Candidate[]> {
    const url = new URL(`${this.baseUrl}/candidates`);
  
    this.addPaginationQueryParams(url, params);
  
    if (params?.filter?.createdAfter) {
      url.searchParams.append('filter[created-at][from]', params.filter.createdAfter);
    }
  
    if (params?.filter?.createdBefore) {
      url.searchParams.append('filter[created-at][to]', params.filter.createdBefore);
    }
  
    if (params?.filter?.updatedAfter) {
      url.searchParams.append('filter[updated-at][from]', params.filter.updatedAfter);
    }
  
    if (params?.filter?.updatedBefore) {
      url.searchParams.append('filter[updated-at][to]', params.filter.updatedBefore);
    }
  
    const body = await this.request<{ data: Candidate[] }>(url);
    return body.data;
  }

• src/teamtailor.ts:39-48 (schema)

  ListCandidatesParams interface defining the params shape used by the client.listCandidates() helper.

  export interface ListCandidatesParams {
    page?: number;
    perPage?: number;
    filter?: {
      createdAfter?: string;
      createdBefore?: string;
      updatedAfter?: string;
      updatedBefore?: string;
    }
  }