@jobtarget/profiles-api-mcp 1.0.0

package/dist/tools/GetProfile.js

@@ -0,0 +1,37 @@
+import { MCPTool } from "mcp-framework";
+import { z } from "zod";
+import { apiClient, ProfilesApiError } from "../client/ProfilesApiClient.js";
+export class GetProfile extends MCPTool {
+    name = "get_profile";
+    description = "Retrieve a single candidate profile by its ID. " +
+        "Profile IDs are prefixed by source: pdl_ (PeopleDataLabs), jbt_ (JobTarget), or rli_ (ResumeLibrary). " +
+        "Returns the full SourcerProfile object including contact details, experience, education, and skills.";
+    schema = z.object({
+        id: z
+            .string()
+            .min(1)
+            .describe("Profile ID including source prefix (e.g. 'pdl_abc123', 'jbt_456', 'rli_789')"),
+    });
+    async execute(input) {
+        try {
+            const profile = await apiClient.get(`/api/v1/profiles/${encodeURIComponent(input.id)}`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(profile, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            if (error instanceof ProfilesApiError) {
+                if (error.status === 404) {
+                    throw new Error(`Profile not found: ${input.id}`);
+                }
+                throw new Error(`Profiles API error (${error.status}): ${error.message}`);
+            }
+            throw error;
+        }
+    }
+}

package/dist/tools/GetProfileLinks.d.ts

@@ -0,0 +1,40 @@
+import { MCPTool } from "mcp-framework";
+import { z } from "zod";
+export declare class GetProfileLinks extends MCPTool {
+    name: string;
+    description: string;
+    schema: z.ZodObject<{
+        recruiterId: z.ZodNumber;
+        saved: z.ZodOptional<z.ZodBoolean>;
+        unlocked: z.ZodOptional<z.ZodBoolean>;
+        hidden: z.ZodOptional<z.ZodBoolean>;
+        page: z.ZodDefault<z.ZodNumber>;
+        count: z.ZodDefault<z.ZodNumber>;
+        includeInvites: z.ZodOptional<z.ZodBoolean>;
+        jobId: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        recruiterId: number;
+        page: number;
+        count: number;
+        saved?: boolean | undefined;
+        unlocked?: boolean | undefined;
+        hidden?: boolean | undefined;
+        includeInvites?: boolean | undefined;
+        jobId?: number | undefined;
+    }, {
+        recruiterId: number;
+        saved?: boolean | undefined;
+        unlocked?: boolean | undefined;
+        hidden?: boolean | undefined;
+        page?: number | undefined;
+        count?: number | undefined;
+        includeInvites?: boolean | undefined;
+        jobId?: number | undefined;
+    }>;
+    execute(input: z.infer<typeof this.schema>): Promise<{
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+    }>;
+}

package/dist/tools/GetProfileLinks.js

@@ -0,0 +1,89 @@
+import { MCPTool } from "mcp-framework";
+import { z } from "zod";
+import { apiClient, ProfilesApiError } from "../client/ProfilesApiClient.js";
+export class GetProfileLinks extends MCPTool {
+    name = "get_profile_links";
+    description = "Retrieve profile links (saved/unlocked candidates) associated with a recruiter. " +
+        "Supports filtering by saved, unlocked, and hidden status. " +
+        "Optionally fetches associated profile invites when includeInvites is true. " +
+        "Returns paginated ProfileLinks objects with presigned S3 URLs for unlocked profiles.";
+    schema = z.object({
+        recruiterId: z
+            .number()
+            .int()
+            .positive()
+            .describe("Recruiter ID to fetch profile links for"),
+        saved: z
+            .boolean()
+            .optional()
+            .describe("Filter: only return saved (true) or unsaved (false) links"),
+        unlocked: z
+            .boolean()
+            .optional()
+            .describe("Filter: only return unlocked (true) or locked (false) profiles"),
+        hidden: z
+            .boolean()
+            .optional()
+            .describe("Filter: only return hidden (true) or visible (false) profiles"),
+        page: z
+            .number()
+            .int()
+            .min(0)
+            .default(0)
+            .describe("Zero-based page number (default 0)"),
+        count: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .default(10)
+            .describe("Results per page (1–100, default 10)"),
+        includeInvites: z
+            .boolean()
+            .optional()
+            .describe("When true, include associated ProfileInvite records for each link"),
+        jobId: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Optional job ID to filter links. Implies includeInvites=true. Must be a valid job ID."),
+    });
+    async execute(input) {
+        const { recruiterId, saved, unlocked, hidden, page, count, includeInvites, jobId } = input;
+        const params = new URLSearchParams();
+        params.set("page", String(page ?? 0));
+        params.set("count", String(count ?? 10));
+        if (saved !== undefined)
+            params.set("saved", String(saved));
+        if (unlocked !== undefined)
+            params.set("unlocked", String(unlocked));
+        if (hidden !== undefined)
+            params.set("hidden", String(hidden));
+        if (includeInvites !== undefined)
+            params.set("includeInvites", String(includeInvites));
+        if (jobId !== undefined)
+            params.set("jobId", String(jobId));
+        const path = `/api/v1/recruiter/${encodeURIComponent(recruiterId)}/profilelink?${params.toString()}`;
+        try {
+            const links = await apiClient.get(path);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(links, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            if (error instanceof ProfilesApiError) {
+                if (error.status === 404) {
+                    throw new Error(`Recruiter not found: ${recruiterId}`);
+                }
+                throw new Error(`Profiles API error (${error.status}): ${error.message}`);
+            }
+            throw error;
+        }
+    }
+}

package/dist/tools/QueryProfiles.d.ts

@@ -0,0 +1,297 @@
+import { MCPTool } from "mcp-framework";
+import { z } from "zod";
+export declare class QueryProfiles extends MCPTool {
+    name: string;
+    description: string;
+    schema: z.ZodObject<{
+        query: z.ZodObject<{
+            must: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodObject<{
+                term: z.ZodRecord<z.ZodString, z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                term: Record<string, string>;
+            }, {
+                term: Record<string, string>;
+            }>, z.ZodObject<{
+                contains: z.ZodRecord<z.ZodString, z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                contains: Record<string, string>;
+            }, {
+                contains: Record<string, string>;
+            }>, z.ZodObject<{
+                match: z.ZodRecord<z.ZodString, z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                match: Record<string, string>;
+            }, {
+                match: Record<string, string>;
+            }>, z.ZodObject<{
+                fuzzy: z.ZodRecord<z.ZodString, z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                fuzzy: Record<string, string>;
+            }, {
+                fuzzy: Record<string, string>;
+            }>, z.ZodObject<{
+                startsWith: z.ZodRecord<z.ZodString, z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                startsWith: Record<string, string>;
+            }, {
+                startsWith: Record<string, string>;
+            }>, z.ZodObject<{
+                doesNotStartWith: z.ZodRecord<z.ZodString, z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                doesNotStartWith: Record<string, string>;
+            }, {
+                doesNotStartWith: Record<string, string>;
+            }>]>, "many">>;
+            not: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodObject<{
+                term: z.ZodRecord<z.ZodString, z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                term: Record<string, string>;
+            }, {
+                term: Record<string, string>;
+            }>, z.ZodObject<{
+                contains: z.ZodRecord<z.ZodString, z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                contains: Record<string, string>;
+            }, {
+                contains: Record<string, string>;
+            }>, z.ZodObject<{
+                match: z.ZodRecord<z.ZodString, z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                match: Record<string, string>;
+            }, {
+                match: Record<string, string>;
+            }>, z.ZodObject<{
+                fuzzy: z.ZodRecord<z.ZodString, z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                fuzzy: Record<string, string>;
+            }, {
+                fuzzy: Record<string, string>;
+            }>, z.ZodObject<{
+                startsWith: z.ZodRecord<z.ZodString, z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                startsWith: Record<string, string>;
+            }, {
+                startsWith: Record<string, string>;
+            }>, z.ZodObject<{
+                doesNotStartWith: z.ZodRecord<z.ZodString, z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                doesNotStartWith: Record<string, string>;
+            }, {
+                doesNotStartWith: Record<string, string>;
+            }>]>, "many">>;
+            should: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodObject<{
+                term: z.ZodRecord<z.ZodString, z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                term: Record<string, string>;
+            }, {
+                term: Record<string, string>;
+            }>, z.ZodObject<{
+                contains: z.ZodRecord<z.ZodString, z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                contains: Record<string, string>;
+            }, {
+                contains: Record<string, string>;
+            }>, z.ZodObject<{
+                match: z.ZodRecord<z.ZodString, z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                match: Record<string, string>;
+            }, {
+                match: Record<string, string>;
+            }>, z.ZodObject<{
+                fuzzy: z.ZodRecord<z.ZodString, z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                fuzzy: Record<string, string>;
+            }, {
+                fuzzy: Record<string, string>;
+            }>, z.ZodObject<{
+                startsWith: z.ZodRecord<z.ZodString, z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                startsWith: Record<string, string>;
+            }, {
+                startsWith: Record<string, string>;
+            }>, z.ZodObject<{
+                doesNotStartWith: z.ZodRecord<z.ZodString, z.ZodString>;
+            }, "strip", z.ZodTypeAny, {
+                doesNotStartWith: Record<string, string>;
+            }, {
+                doesNotStartWith: Record<string, string>;
+            }>]>, "many">>;
+        }, "strip", z.ZodTypeAny, {
+            must?: ({
+                term: Record<string, string>;
+            } | {
+                contains: Record<string, string>;
+            } | {
+                match: Record<string, string>;
+            } | {
+                fuzzy: Record<string, string>;
+            } | {
+                startsWith: Record<string, string>;
+            } | {
+                doesNotStartWith: Record<string, string>;
+            })[] | undefined;
+            not?: ({
+                term: Record<string, string>;
+            } | {
+                contains: Record<string, string>;
+            } | {
+                match: Record<string, string>;
+            } | {
+                fuzzy: Record<string, string>;
+            } | {
+                startsWith: Record<string, string>;
+            } | {
+                doesNotStartWith: Record<string, string>;
+            })[] | undefined;
+            should?: ({
+                term: Record<string, string>;
+            } | {
+                contains: Record<string, string>;
+            } | {
+                match: Record<string, string>;
+            } | {
+                fuzzy: Record<string, string>;
+            } | {
+                startsWith: Record<string, string>;
+            } | {
+                doesNotStartWith: Record<string, string>;
+            })[] | undefined;
+        }, {
+            must?: ({
+                term: Record<string, string>;
+            } | {
+                contains: Record<string, string>;
+            } | {
+                match: Record<string, string>;
+            } | {
+                fuzzy: Record<string, string>;
+            } | {
+                startsWith: Record<string, string>;
+            } | {
+                doesNotStartWith: Record<string, string>;
+            })[] | undefined;
+            not?: ({
+                term: Record<string, string>;
+            } | {
+                contains: Record<string, string>;
+            } | {
+                match: Record<string, string>;
+            } | {
+                fuzzy: Record<string, string>;
+            } | {
+                startsWith: Record<string, string>;
+            } | {
+                doesNotStartWith: Record<string, string>;
+            })[] | undefined;
+            should?: ({
+                term: Record<string, string>;
+            } | {
+                contains: Record<string, string>;
+            } | {
+                match: Record<string, string>;
+            } | {
+                fuzzy: Record<string, string>;
+            } | {
+                startsWith: Record<string, string>;
+            } | {
+                doesNotStartWith: Record<string, string>;
+            })[] | undefined;
+        }>;
+        page: z.ZodDefault<z.ZodNumber>;
+        count: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        page: number;
+        count: number;
+        query: {
+            must?: ({
+                term: Record<string, string>;
+            } | {
+                contains: Record<string, string>;
+            } | {
+                match: Record<string, string>;
+            } | {
+                fuzzy: Record<string, string>;
+            } | {
+                startsWith: Record<string, string>;
+            } | {
+                doesNotStartWith: Record<string, string>;
+            })[] | undefined;
+            not?: ({
+                term: Record<string, string>;
+            } | {
+                contains: Record<string, string>;
+            } | {
+                match: Record<string, string>;
+            } | {
+                fuzzy: Record<string, string>;
+            } | {
+                startsWith: Record<string, string>;
+            } | {
+                doesNotStartWith: Record<string, string>;
+            })[] | undefined;
+            should?: ({
+                term: Record<string, string>;
+            } | {
+                contains: Record<string, string>;
+            } | {
+                match: Record<string, string>;
+            } | {
+                fuzzy: Record<string, string>;
+            } | {
+                startsWith: Record<string, string>;
+            } | {
+                doesNotStartWith: Record<string, string>;
+            })[] | undefined;
+        };
+    }, {
+        query: {
+            must?: ({
+                term: Record<string, string>;
+            } | {
+                contains: Record<string, string>;
+            } | {
+                match: Record<string, string>;
+            } | {
+                fuzzy: Record<string, string>;
+            } | {
+                startsWith: Record<string, string>;
+            } | {
+                doesNotStartWith: Record<string, string>;
+            })[] | undefined;
+            not?: ({
+                term: Record<string, string>;
+            } | {
+                contains: Record<string, string>;
+            } | {
+                match: Record<string, string>;
+            } | {
+                fuzzy: Record<string, string>;
+            } | {
+                startsWith: Record<string, string>;
+            } | {
+                doesNotStartWith: Record<string, string>;
+            })[] | undefined;
+            should?: ({
+                term: Record<string, string>;
+            } | {
+                contains: Record<string, string>;
+            } | {
+                match: Record<string, string>;
+            } | {
+                fuzzy: Record<string, string>;
+            } | {
+                startsWith: Record<string, string>;
+            } | {
+                doesNotStartWith: Record<string, string>;
+            })[] | undefined;
+        };
+        page?: number | undefined;
+        count?: number | undefined;
+    }>;
+    execute(input: z.infer<typeof this.schema>): Promise<{
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+    }>;
+}

package/dist/tools/QueryProfiles.js

@@ -0,0 +1,82 @@
+import { MCPTool } from "mcp-framework";
+import { z } from "zod";
+import { apiClient, ProfilesApiError } from "../client/ProfilesApiClient.js";
+// A single query clause maps one field to one value.
+const QueryClauseSchema = z.record(z.string()).describe('Single field-value pair, e.g. {"currentTitle": "Software Engineer"}');
+// Supported query types.
+const QueryNodeSchema = z.union([
+    z.object({ term: QueryClauseSchema }).describe("Exact-match (case-sensitive)"),
+    z.object({ contains: QueryClauseSchema }).describe("Wildcard / partial match"),
+    z.object({ match: QueryClauseSchema }).describe("Full-text analyzed match"),
+    z.object({ fuzzy: QueryClauseSchema }).describe("Approximate match (typo-tolerant)"),
+    z.object({ startsWith: QueryClauseSchema }).describe("Prefix match"),
+    z.object({ doesNotStartWith: QueryClauseSchema }).describe("Negative prefix match"),
+]);
+const BooleanQuerySchema = z.object({
+    must: z
+        .array(QueryNodeSchema)
+        .optional()
+        .describe("Clauses that MUST match (AND logic)"),
+    not: z
+        .array(QueryNodeSchema)
+        .optional()
+        .describe("Clauses that MUST NOT match (NOT logic)"),
+    should: z
+        .array(QueryNodeSchema)
+        .optional()
+        .describe("Clauses that SHOULD match (OR logic)"),
+});
+export class QueryProfiles extends MCPTool {
+    name = "query_profiles";
+    description = "Execute an advanced boolean query against the profile index using Elasticsearch-style syntax. " +
+        "Supports must/not/should clauses with term, contains, match, fuzzy, startsWith, and doesNotStartWith operators. " +
+        "Use this for complex filtering scenarios not covered by search_profiles. " +
+        "Searchable fields include: fullName, firstName, lastName, currentTitle, normalizedTitle, " +
+        "currentEmployer, skills, experience.title.name, experience.company.name, education.school.name, " +
+        "location.name, location.region, emails.emailAddress, and many more.";
+    schema = z.object({
+        query: BooleanQuerySchema.describe("Boolean query with must, not, and/or should clauses. At least one clause list is required."),
+        page: z
+            .number()
+            .int()
+            .min(0)
+            .default(0)
+            .describe("Zero-based page number (default 0)"),
+        count: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .default(10)
+            .describe("Results per page (1–100, default 10)"),
+    });
+    async execute(input) {
+        const { query, page, count } = input;
+        if ((!query.must || query.must.length === 0) &&
+            (!query.not || query.not.length === 0) &&
+            (!query.should || query.should.length === 0)) {
+            throw new Error("query must contain at least one clause in must, not, or should");
+        }
+        try {
+            const results = await apiClient.post("/api/v1/profiles/query", {
+                query,
+                page,
+                count,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(results, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            if (error instanceof ProfilesApiError) {
+                throw new Error(`Profiles API error (${error.status}): ${error.message}`);
+            }
+            throw error;
+        }
+    }
+}

package/dist/tools/SearchProfiles.d.ts

@@ -0,0 +1,101 @@
+import { MCPTool } from "mcp-framework";
+import { z } from "zod";
+export declare class SearchProfiles extends MCPTool {
+    name: string;
+    description: string;
+    schema: z.ZodObject<{
+        source: z.ZodEnum<["PeopleDataLabs", "JobTarget", "ResumeLibrary"]>;
+        what: z.ZodString;
+        where: z.ZodOptional<z.ZodString>;
+        latitude: z.ZodOptional<z.ZodNumber>;
+        longitude: z.ZodOptional<z.ZodNumber>;
+        radius: z.ZodOptional<z.ZodNumber>;
+        page: z.ZodDefault<z.ZodNumber>;
+        count: z.ZodDefault<z.ZodNumber>;
+        companies: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        jobTitles: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        recentlyActive: z.ZodOptional<z.ZodBoolean>;
+        companyId: z.ZodOptional<z.ZodNumber>;
+        fuzziness: z.ZodOptional<z.ZodEnum<["Auto", "0", "1", "2"]>>;
+        type: z.ZodOptional<z.ZodEnum<["best_fields", "most_fields", "cross_fields"]>>;
+        weights: z.ZodOptional<z.ZodObject<{
+            w_text: z.ZodOptional<z.ZodNumber>;
+            w_recency: z.ZodOptional<z.ZodNumber>;
+            w_signal_data: z.ZodOptional<z.ZodNumber>;
+            w_contact: z.ZodOptional<z.ZodNumber>;
+            w_job_title: z.ZodOptional<z.ZodNumber>;
+            w_distance: z.ZodOptional<z.ZodNumber>;
+            w_phone: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            w_text?: number | undefined;
+            w_recency?: number | undefined;
+            w_signal_data?: number | undefined;
+            w_contact?: number | undefined;
+            w_job_title?: number | undefined;
+            w_distance?: number | undefined;
+            w_phone?: number | undefined;
+        }, {
+            w_text?: number | undefined;
+            w_recency?: number | undefined;
+            w_signal_data?: number | undefined;
+            w_contact?: number | undefined;
+            w_job_title?: number | undefined;
+            w_distance?: number | undefined;
+            w_phone?: number | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        page: number;
+        count: number;
+        source: "PeopleDataLabs" | "JobTarget" | "ResumeLibrary";
+        what: string;
+        type?: "best_fields" | "most_fields" | "cross_fields" | undefined;
+        where?: string | undefined;
+        latitude?: number | undefined;
+        longitude?: number | undefined;
+        radius?: number | undefined;
+        companies?: string[] | undefined;
+        jobTitles?: string[] | undefined;
+        recentlyActive?: boolean | undefined;
+        companyId?: number | undefined;
+        fuzziness?: "0" | "1" | "2" | "Auto" | undefined;
+        weights?: {
+            w_text?: number | undefined;
+            w_recency?: number | undefined;
+            w_signal_data?: number | undefined;
+            w_contact?: number | undefined;
+            w_job_title?: number | undefined;
+            w_distance?: number | undefined;
+            w_phone?: number | undefined;
+        } | undefined;
+    }, {
+        source: "PeopleDataLabs" | "JobTarget" | "ResumeLibrary";
+        what: string;
+        type?: "best_fields" | "most_fields" | "cross_fields" | undefined;
+        page?: number | undefined;
+        count?: number | undefined;
+        where?: string | undefined;
+        latitude?: number | undefined;
+        longitude?: number | undefined;
+        radius?: number | undefined;
+        companies?: string[] | undefined;
+        jobTitles?: string[] | undefined;
+        recentlyActive?: boolean | undefined;
+        companyId?: number | undefined;
+        fuzziness?: "0" | "1" | "2" | "Auto" | undefined;
+        weights?: {
+            w_text?: number | undefined;
+            w_recency?: number | undefined;
+            w_signal_data?: number | undefined;
+            w_contact?: number | undefined;
+            w_job_title?: number | undefined;
+            w_distance?: number | undefined;
+            w_phone?: number | undefined;
+        } | undefined;
+    }>;
+    execute(input: z.infer<typeof this.schema>): Promise<{
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+    }>;
+}