MCP Teamtailor

Instructions

Implementation Reference

• src/server.ts:52-63 (handler)

  MCP tool handler function that retrieves the candidate via TeamtailorClient and returns it as JSON text content.

  async ({ candidateId }) => {
    const candidate = await client.getCandidate(candidateId);
  
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(candidate),
        }
      ]
    }
  }

• src/server.ts:49-51 (schema)

  Input validation schema using Zod for the candidateId parameter.

  {
    candidateId: z.number(),
  },

• src/server.ts:46-64 (registration)

  Registration of the 'teamtailor_get_candidate' tool with the MCP server, including description, schema, and handler.

  server.tool(
    "teamtailor_get_candidate",
    "Get a single candidate by their id.",
    {
      candidateId: z.number(),
    },
    async ({ candidateId }) => {
      const candidate = await client.getCandidate(candidateId);
  
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(candidate),
          }
        ]
      }
    }
  );

• src/teamtailor.ts:97-104 (helper)

  TeamtailorClient method that performs the API request to fetch a single candidate by ID.

  async getCandidate(
    id: number,
  ): Promise<Candidate> {
    const url = new URL(`${this.baseUrl}/candidates/${id}`);
  
    const body = await this.request<{ data: Candidate }>(url);
    return body.data;
  }

• src/teamtailor.ts:4-37 (schema)

  Type definition for the Candidate object returned by the Teamtailor API.

  export interface Candidate {
    id: string;
    type: 'candidates';
    attributes: {
      createdAt?: string; // date
      updatedAt?: string; // date
      email?: string;
      connected?: boolean;
      'consent-future-jobs-at'?: string; // date, read only
      'consent-given-future-jobs'?: boolean; // write only
      'facebook-id'?: string;
      'facebook-profile'?: string; // read only, html version
      'first-name'?: string;
      internal?: boolean;
      'last-name'?: string;
      'linkedin-profile'?: string; // read only, html version
      'linkedin-uid'?: string;
      'linkedin-url'?: string;
      merge?: boolean; // write only
      'original-resume'?: string; // read only, signed URL
      phone?: string;
      picture?: string;
      pitch?: string;
      'referring-site'?: string; // read only
      'referring-url'?: string;
      referred: boolean; // read only
      resume?: string;
      sourced?: boolean;
      'setConsent-expiration'?: boolean; // write only
      tags?: string[];
      unsubscribed?: boolean;
      'send-welcome-message'?: boolean; // create only
    };
  }