@jobtarget/profiles-api-mcp 1.0.0

package/README.md

@@ -0,0 +1,331 @@
+# profiles-api-mcp
+
+MCP server that exposes JobTarget Profiles API endpoints as MCP tools. Built with [mcp-framework](https://github.com/QuantGeekDev/mcp-framework), TypeScript, and Zod.
+
+---
+
+## Tools
+
+| Tool | Method | Endpoint |
+|------|--------|----------|
+| `search_profiles` | POST | `/api/v1/profiles/search` |
+| `get_profile` | GET | `/api/v1/profiles/{id}` |
+| `query_profiles` | POST | `/api/v1/profiles/query` |
+| `get_profile_links` | GET | `/api/v1/recruiter/{id}/profilelink` |
+| `create_profile_link` | POST | `/api/v1/recruiter/{id}/profilelink` |
+| `get_invite` | GET | `/api/v1/profileinvite/{publicId}` |
+
+---
+
+## Setup
+
+### 1. Install dependencies
+
+```bash
+npm install
+```
+
+### 2. Configure environment
+
+Copy `.env.example` to `.env` and fill in your values:
+
+```bash
+cp .env.example .env
+```
+
+```env
+# Required: Profiles API base URL (no trailing slash)
+PROFILES_API_BASE_URL=https://your-profiles-api-host.example.com
+
+# Required: use one of API key or Bearer token
+PROFILES_API_API_KEY=your-api-key-here
+# PROFILES_API_TOKEN=your-bearer-token-here
+```
+
+The API key is sent as the `X-API-Key` header. If `PROFILES_API_TOKEN` is set instead, it is sent as `Authorization: Bearer <token>`.
+
+### 3. Build
+
+```bash
+npm run build
+```
+
+### 4. Run
+
+```bash
+npm start
+```
+
+For development (no build step):
+
+```bash
+npm run dev
+```
+
+---
+
+## Claude Desktop / Claude Code configuration
+
+Add to your MCP settings (e.g. `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "profiles-api": {
+      "command": "node",
+      "args": ["/absolute/path/to/profiles-api-mcp/dist/index.js"],
+      "env": {
+        "PROFILES_API_BASE_URL": "https://your-profiles-api-host.example.com",
+        "PROFILES_API_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Production access via the public gateway (SRC-2936)
+
+For hosted / non-local use, the MCP server talks to the **public API Gateway
+façade** (`packages/lambdas/`) instead of the private Profiles API directly. The
+gateway exposes only the 6 tool endpoints, is protected by AWS WAF, and
+authenticates each request with a **per-user Personal Access Token (PAT)**.
+
+Point the server at the gateway for the target environment and use the user's PAT
+as the bearer token:
+
+```json
+{
+  "mcpServers": {
+    "profiles-api": {
+      "command": "npx",
+      "args": ["-y", "@jobtarget/profiles-api-mcp"],
+      "env": {
+        "PROFILES_API_BASE_URL": "https://<gateway-id>.execute-api.us-east-1.amazonaws.com/qa",
+        "PROFILES_API_TOKEN": "pat_… (issued via packages/lambdas/scripts/token-admin.mjs)"
+      }
+    }
+  }
+}
+```
+
+`PROFILES_API_TOKEN` is sent as `Authorization: Bearer <token>` — exactly what the
+gateway's authorizer expects. Get the gateway URL from the stack output
+`GatewayUrl`, and mint/revoke tokens with the token-admin CLI. See
+[`packages/lambdas/README.md`](packages/lambdas/README.md) and
+[`packages/lambdas/RUNBOOK.md`](packages/lambdas/RUNBOOK.md).
+
+---
+
+## Tool Reference
+
+### `search_profiles`
+
+Full-text keyword search across profile data sources.
+
+**Required inputs:**
+- `source` — `"PeopleDataLabs"` | `"JobTarget"` | `"ResumeLibrary"`
+- `what` — Search keywords (e.g. `"software engineer react"`)
+
+**Optional inputs:**
+- `where` — Location string (e.g. `"Austin, TX"`)
+- `latitude` / `longitude` — Geo coordinates (must be paired)
+- `radius` — Search radius in miles (10–200, requires `where` + coordinates)
+- `page` — Page number (1-based, default `1`)
+- `count` — Results per page (1–100, default `10`)
+- `companies` — Array of company name filters
+- `jobTitles` — Array of job title filters
+- `recentlyActive` — Boolean; filter to recently active profiles
+- `companyId` — Required when `source` is `ResumeLibrary`
+- `fuzziness` — `"Auto"` | `"0"` | `"1"` | `"2"`
+- `type` — `"best_fields"` | `"most_fields"` | `"cross_fields"`
+- `weights` — Object with `w_text`, `w_recency`, `w_signal_data`, `w_contact`, `w_job_title`, `w_distance`, `w_phone`
+
+**Example:**
+```json
+{
+  "source": "PeopleDataLabs",
+  "what": "senior software engineer typescript",
+  "where": "San Francisco, CA",
+  "radius": 25,
+  "latitude": 37.7749,
+  "longitude": -122.4194,
+  "count": 5
+}
+```
+
+---
+
+### `get_profile`
+
+Fetch a single profile by ID.
+
+**Required inputs:**
+- `id` — Profile ID with source prefix (e.g. `"pdl_abc123"`, `"jbt_456"`, `"rli_789"`)
+
+**Example:**
+```json
+{ "id": "pdl_abc123def456" }
+```
+
+---
+
+### `query_profiles`
+
+Execute an advanced boolean query against the profile index.
+
+**Required inputs:**
+- `query` — Object with `must`, `not`, and/or `should` arrays. At least one array must be non-empty.
+
+**Optional inputs:**
+- `page` — Zero-based page number (default `0`)
+- `count` — Results per page (1–100, default `10`)
+
+**Supported query operators:**
+
+| Operator | Description |
+|----------|-------------|
+| `term` | Exact case-sensitive match |
+| `contains` | Wildcard / partial match |
+| `match` | Full-text analyzed match |
+| `fuzzy` | Typo-tolerant approximate match |
+| `startsWith` | Prefix match |
+| `doesNotStartWith` | Negative prefix match |
+
+**Example:**
+```json
+{
+  "query": {
+    "must": [
+      { "match": { "skills": "Python" } },
+      { "match": { "skills": "machine learning" } }
+    ],
+    "not": [
+      { "term": { "currentEmployer": "Acme Corp" } }
+    ]
+  },
+  "count": 20
+}
+```
+
+**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`, `industry`, and many more.
+
+---
+
+### `get_profile_links`
+
+List profile links (saved/unlocked candidates) for a recruiter.
+
+**Required inputs:**
+- `recruiterId` — Recruiter ID (integer)
+
+**Optional inputs:**
+- `saved` — Filter by saved status
+- `unlocked` — Filter by unlocked status
+- `hidden` — Filter by hidden status
+- `page` — Zero-based page (default `0`)
+- `count` — Results per page (1–100, default `10`)
+- `includeInvites` — Include associated ProfileInvite records
+- `jobId` — Filter by job ID (implies `includeInvites=true`)
+
+**Example:**
+```json
+{
+  "recruiterId": 1234,
+  "saved": true,
+  "unlocked": true,
+  "count": 25
+}
+```
+
+---
+
+### `create_profile_link`
+
+Save or unlock a candidate profile for a recruiter.
+
+**Required inputs:**
+- `recruiterId` — Recruiter ID (integer)
+- `profileId` — Profile ID with source prefix (`pdl_*`, `jbt_*`, or `rli_*`)
+
+**Optional inputs:**
+- `saved` — Mark as saved (default `false`)
+- `unlocked` — Fetch full profile data and return presigned S3 URL (default `false`)
+- `hidden` — Hide from recruiter's list (default `false`)
+- `notes` — Recruiter notes (max 4092 characters)
+
+**Example:**
+```json
+{
+  "recruiterId": 1234,
+  "profileId": "pdl_abc123",
+  "saved": true,
+  "unlocked": true,
+  "notes": "Strong Python background, open to relocation"
+}
+```
+
+---
+
+### `get_invite`
+
+Retrieve a profile invite by its public ID.
+
+**Required inputs:**
+- `publicId` — Public invite ID (MongoDB ObjectId or UUID slug)
+
+**Example:**
+```json
+{ "publicId": "507f1f77bcf86cd799439011" }
+```
+
+---
+
+## Project Structure
+
+```
+profiles-api-mcp/
+├── src/
+│   ├── index.ts                   # Server entry point
+│   ├── config.ts                  # Environment config + validation
+│   ├── client/
+│   │   └── ProfilesApiClient.ts   # HTTP client with auth + error handling
+│   └── tools/
+│       ├── SearchProfiles.ts      # search_profiles tool
+│       ├── GetProfile.ts          # get_profile tool
+│       ├── QueryProfiles.ts       # query_profiles tool
+│       ├── GetProfileLinks.ts     # get_profile_links tool
+│       ├── CreateProfileLink.ts   # create_profile_link tool
+│       └── GetInvite.ts           # get_invite tool
+├── dist/                          # Compiled output (git-ignored)
+├── .env.example                   # Environment variable template
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+---
+
+## Error Handling
+
+All tools surface API errors with the HTTP status code and message:
+
+| Status | Meaning |
+|--------|---------|
+| 400 | Validation failure — check your inputs |
+| 401 | Authentication failure — check your API key |
+| 404 | Resource not found |
+| 409 | Conflict — resource already exists |
+| 503 | S3 upload failure (create_profile_link with unlocked=true) |
+| 5xx | Server error |
+
+---
+
+## Assumptions & Limitations
+
+- **Authentication:** The Profiles API uses `X-API-Key` header auth. Bearer token support is provided as a fallback via `PROFILES_API_TOKEN`.
+- **No pagination cursor:** All pagination uses page+count offsets. Max page for `query_profiles` is 100 (API-enforced).
+- **ResumeLibrary source:** Requires `companyId` in `search_profiles`. The API returns a 401-shaped 400 error if missing.
+- **Presigned URLs:** The `profileUrl` field in `create_profile_link` responses is valid for 15 minutes.
+- **Profile invites:** `get_invite` retrieves by `publicId` (not the MongoDB `_id`).

package/dist/client/ProfilesApiClient.d.ts

@@ -0,0 +1,19 @@
+export interface ApiResponse<T> {
+    data: T;
+    status: number;
+}
+export declare class ProfilesApiError extends Error {
+    readonly status: number;
+    readonly body?: unknown | undefined;
+    constructor(status: number, message: string, body?: unknown | undefined);
+}
+export declare class ProfilesApiClient {
+    private readonly baseUrl;
+    private readonly headers;
+    constructor();
+    get<T>(path: string): Promise<T>;
+    post<T>(path: string, body: unknown): Promise<T>;
+    private handleResponse;
+    private extractErrorMessage;
+}
+export declare const apiClient: ProfilesApiClient;

package/dist/client/ProfilesApiClient.js

@@ -0,0 +1,73 @@
+import { config } from "../config.js";
+export class ProfilesApiError extends Error {
+    status;
+    body;
+    constructor(status, message, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = "ProfilesApiError";
+    }
+}
+export class ProfilesApiClient {
+    baseUrl;
+    headers;
+    constructor() {
+        this.baseUrl = config.api.baseUrl.replace(/\/$/, "");
+        this.headers = {
+            "Content-Type": "application/json",
+            Accept: "application/json",
+        };
+        if (config.api.apiKey) {
+            this.headers["X-API-Key"] = config.api.apiKey;
+        }
+        if (config.api.token) {
+            this.headers["Authorization"] = `Bearer ${config.api.token}`;
+        }
+    }
+    async get(path) {
+        const response = await fetch(`${this.baseUrl}${path}`, {
+            method: "GET",
+            headers: this.headers,
+        });
+        return this.handleResponse(response);
+    }
+    async post(path, body) {
+        const response = await fetch(`${this.baseUrl}${path}`, {
+            method: "POST",
+            headers: this.headers,
+            body: JSON.stringify(body),
+        });
+        return this.handleResponse(response);
+    }
+    async handleResponse(response) {
+        let body;
+        const contentType = response.headers.get("content-type") ?? "";
+        if (contentType.includes("application/json")) {
+            body = await response.json();
+        }
+        else {
+            body = await response.text();
+        }
+        if (!response.ok) {
+            const message = this.extractErrorMessage(body, response);
+            throw new ProfilesApiError(response.status, message, body);
+        }
+        return body;
+    }
+    extractErrorMessage(body, response) {
+        if (typeof body === "object" && body !== null) {
+            const b = body;
+            if (typeof b["title"] === "string")
+                return b["title"];
+            if (typeof b["message"] === "string")
+                return b["message"];
+            if (typeof b["error"] === "string")
+                return b["error"];
+        }
+        if (typeof body === "string" && body.length > 0)
+            return body;
+        return `HTTP ${response.status} ${response.statusText}`;
+    }
+}
+export const apiClient = new ProfilesApiClient();

package/dist/config.d.ts

@@ -0,0 +1,12 @@
+export declare const config: {
+    api: {
+        baseUrl: string;
+        apiKey: string;
+        token: string;
+    };
+    server: {
+        name: string;
+        version: string;
+    };
+};
+export declare function validateConfig(): void;

package/dist/config.js

@@ -0,0 +1,19 @@
+export const config = {
+    api: {
+        baseUrl: process.env.PROFILES_API_BASE_URL ?? "",
+        apiKey: process.env.PROFILES_API_API_KEY ?? "",
+        token: process.env.PROFILES_API_TOKEN ?? "",
+    },
+    server: {
+        name: "profiles-api-mcp",
+        version: "1.0.0",
+    },
+};
+export function validateConfig() {
+    if (!config.api.baseUrl) {
+        throw new Error("PROFILES_API_BASE_URL environment variable is required");
+    }
+    if (!config.api.apiKey && !config.api.token) {
+        throw new Error("Either PROFILES_API_API_KEY or PROFILES_API_TOKEN environment variable is required");
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "dotenv/config";

package/dist/index.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import "dotenv/config";
+import { MCPServer } from "mcp-framework";
+import { config, validateConfig } from "./config.js";
+validateConfig();
+const server = new MCPServer({
+    name: config.server.name,
+    version: config.server.version,
+});
+server.start();

package/dist/tools/CreateProfileLink.d.ts

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

package/dist/tools/CreateProfileLink.js

@@ -0,0 +1,82 @@
+import { MCPTool } from "mcp-framework";
+import { z } from "zod";
+import { apiClient, ProfilesApiError } from "../client/ProfilesApiClient.js";
+export class CreateProfileLink extends MCPTool {
+    name = "create_profile_link";
+    description = "Save or unlock a candidate profile for a recruiter, creating a ProfileLink record. " +
+        "The profileId must include the source prefix (pdl_, jbt_, or rli_). " +
+        "Setting unlocked=true triggers a profile data fetch and S3 upload, " +
+        "and returns a 15-minute presigned URL to the full profile. " +
+        "Returns 409 Conflict if the recruiter already has a link for this profile.";
+    schema = z.object({
+        recruiterId: z
+            .number()
+            .int()
+            .positive()
+            .describe("Recruiter ID that is saving/unlocking the profile"),
+        profileId: z
+            .string()
+            .min(1)
+            .describe("Profile ID including source prefix: pdl_<id>, jbt_<id>, or rli_<id>"),
+        saved: z
+            .boolean()
+            .optional()
+            .describe("Mark the profile as saved (default false)"),
+        unlocked: z
+            .boolean()
+            .optional()
+            .describe("Unlock the full profile data. Triggers S3 fetch and returns a presigned URL (default false)"),
+        hidden: z
+            .boolean()
+            .optional()
+            .describe("Hide the profile from the recruiter's list (default false)"),
+        notes: z
+            .string()
+            .max(4092)
+            .optional()
+            .describe("Recruiter notes about this candidate (max 4092 characters)"),
+    });
+    async execute(input) {
+        const { recruiterId, profileId, saved, unlocked, hidden, notes } = input;
+        if (!profileId.startsWith("pdl_") &&
+            !profileId.startsWith("jbt_") &&
+            !profileId.startsWith("rli_")) {
+            throw new Error("profileId must start with pdl_, jbt_, or rli_ (e.g. 'pdl_abc123')");
+        }
+        const body = { profileId };
+        if (saved !== undefined)
+            body["saved"] = saved;
+        if (unlocked !== undefined)
+            body["unlocked"] = unlocked;
+        if (hidden !== undefined)
+            body["hidden"] = hidden;
+        if (notes !== undefined)
+            body["notes"] = notes;
+        try {
+            const link = await apiClient.post(`/api/v1/recruiter/${encodeURIComponent(recruiterId)}/profilelink`, body);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(link, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            if (error instanceof ProfilesApiError) {
+                if (error.status === 404) {
+                    throw new Error(`Recruiter not found: ${recruiterId}`);
+                }
+                if (error.status === 409) {
+                    throw new Error(`Profile link already exists for recruiter ${recruiterId} and profile ${profileId}`);
+                }
+                if (error.status === 503) {
+                    throw new Error("Failed to upload profile to storage. The profile link may have been created without an unlocked URL.");
+                }
+                throw new Error(`Profiles API error (${error.status}): ${error.message}`);
+            }
+            throw error;
+        }
+    }
+}

package/dist/tools/GetInvite.d.ts

@@ -0,0 +1,19 @@
+import { MCPTool } from "mcp-framework";
+import { z } from "zod";
+export declare class GetInvite extends MCPTool {
+    name: string;
+    description: string;
+    schema: z.ZodObject<{
+        publicId: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        publicId: string;
+    }, {
+        publicId: string;
+    }>;
+    execute(input: z.infer<typeof this.schema>): Promise<{
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+    }>;
+}

package/dist/tools/GetInvite.js

@@ -0,0 +1,39 @@
+import { MCPTool } from "mcp-framework";
+import { z } from "zod";
+import { apiClient, ProfilesApiError } from "../client/ProfilesApiClient.js";
+export class GetInvite extends MCPTool {
+    name = "get_invite";
+    description = "Retrieve a profile invite by its public ID. " +
+        "Profile invites are sent to candidates via email or SMS and track " +
+        "whether the candidate applied or connected. " +
+        "Returns the full ProfileInvite object including invite type, success status, " +
+        "job ID, and all associated events (opens, clicks, replies, etc.).";
+    schema = z.object({
+        publicId: z
+            .string()
+            .min(1)
+            .describe("The public invite ID (MongoDB ObjectId or UUID slug) from the invite URL or profile link"),
+    });
+    async execute(input) {
+        try {
+            const invite = await apiClient.get(`/api/v1/profileinvite/${encodeURIComponent(input.publicId)}`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(invite, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            if (error instanceof ProfilesApiError) {
+                if (error.status === 404) {
+                    throw new Error(`Profile invite not found: ${input.publicId}`);
+                }
+                throw new Error(`Profiles API error (${error.status}): ${error.message}`);
+            }
+            throw error;
+        }
+    }
+}

package/dist/tools/GetProfile.d.ts

@@ -0,0 +1,19 @@
+import { MCPTool } from "mcp-framework";
+import { z } from "zod";
+export declare class GetProfile extends MCPTool {
+    name: string;
+    description: string;
+    schema: z.ZodObject<{
+        id: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+    }, {
+        id: string;
+    }>;
+    execute(input: z.infer<typeof this.schema>): Promise<{
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+    }>;
+}