recruitcrm-mcp-server 0.1.0

package/README.md

@@ -0,0 +1,104 @@
+# Recruit CRM MCP Server
+
+Local `stdio` MCP server for Recruit CRM's Public API.
+
+Repository: `https://github.com/saurav-rcrm/mcp-recruitcrm`
+
+## What It Does
+
+This server exposes compact Recruit CRM search and lookup tools for MCP clients.
+
+## Tools
+
+| Tool | Description |
+| --- | --- |
+| `search_candidates` | Search candidates and return compact summaries for large result sets. Returns `slug`, which can be used for candidate detail lookup or Recruit CRM app links. |
+| `search_jobs` | Search jobs and return compact summaries for large result sets. Returns job, company, and contact slugs for Recruit CRM app links. |
+| `search_companies` | Search companies and return compact summaries for large result sets. Returns company slug and related contact slugs for Recruit CRM app links. |
+| `search_tasks` | Search tasks and return compact task summaries with related entity context. Returns `related_to` and `related_to_type` for related entity links. |
+| `search_meetings` | Search meetings and return compact meeting summaries with scheduling metadata. Returns `related_to` and `related_to_type` for related entity links. |
+| `search_notes` | Search notes and return compact note summaries with related entity context. Returns `related_to` and `related_to_type` for related entity links. |
+| `search_call_logs` | Search call logs and return compact call summaries with related entity context. Returns `related_to` and `related_to_type` for related entity links. |
+| `get_candidate_details` | Fetch one candidate by slug and return the raw Recruit CRM payload, which may include `resource_url`. |
+| `get_job_details` | Fetch one job by slug and return the raw Recruit CRM payload, which may include `resource_url` and `application_form_url`. |
+| `get_candidate_job_assignment_hiring_stage_history` | Fetch one candidate's job assignment hiring stage history by slug and return compact entries with job, company, stage, remark, and update metadata. |
+| `list_candidate_custom_fields` | List curated searchable candidate custom field metadata. |
+| `get_candidate_custom_field_details` | Fetch curated details for one candidate custom field, including full option values when relevant. |
+
+## Open In Recruit CRM
+
+Current live Recruit CRM `resource_url` values use the app path pattern `https://app.recruitcrm.io/<entity>/<slug>`.
+
+| Entity | App Link Pattern | Source Field In MCP Output |
+| --- | --- | --- |
+| Candidate | `https://app.recruitcrm.io/candidate/{slug}` | `search_candidates.slug` or `get_candidate_details.slug` |
+| Company | `https://app.recruitcrm.io/company/{slug}` | `search_companies.slug`, `search_jobs.company_slug`, activity search `related_to` when `related_to_type` is `company`, or `get_candidate_job_assignment_hiring_stage_history.history[].company_slug` |
+| Contact | `https://app.recruitcrm.io/contact/{slug}` | `search_companies.contact_slugs[]`, `search_jobs.contact_slug`, or activity search `related_to` when `related_to_type` is `contact` |
+| Job | `https://app.recruitcrm.io/job/{slug}` | `search_jobs.slug`, `get_job_details.slug`, activity search `related_to` when `related_to_type` is `job`, or `get_candidate_job_assignment_hiring_stage_history.history[].job_slug` |
+| Deal | `https://app.recruitcrm.io/deal/{slug}` | activity search `related_to` when `related_to_type` is `deal` |
+
+## Required Environment Variable
+
+`RECRUITCRM_API_TOKEN`
+
+Optional:
+
+- `RECRUITCRM_BASE_URL` default: `https://api.recruitcrm.io/v1`
+- `RECRUITCRM_TIMEOUT_MS` default: `10000`
+- `RECRUITCRM_DEBUG_SCHEMA_ERRORS` default: `false`
+
+## Install And Run
+
+Run directly from GitHub with `npx`:
+
+```bash
+npx -y github:saurav-rcrm/mcp-recruitcrm
+```
+
+## MCP Config Example
+
+```json
+{
+  "mcpServers": {
+    "recruitcrm": {
+      "command": "npx",
+      "args": ["-y", "github:saurav-rcrm/mcp-recruitcrm"],
+      "env": {
+        "RECRUITCRM_API_TOKEN": "<your-api-token>"
+      }
+    }
+  }
+}
+```
+
+## Local Development
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+## Privacy And Security
+
+- Runs locally on the user's machine over `stdio`
+- No live deployment required
+- Search results exclude email and phone by default
+- `search_companies` excludes custom fields, social links, logos, `resource_url`, last-meeting metadata, and other large raw fields not needed for compact search output
+- `search_jobs` excludes contact emails, phone numbers, and large nested arrays or objects such as job questions, custom fields, collaborator payloads, and feed metadata
+- `search_tasks` exposes only a compact `related` identity object from the nested `related` payload and excludes the rest of that payload plus associated entity and collaborator arrays
+- `search_meetings` exposes only a compact `related` identity object from the nested `related` payload and excludes the rest of that payload plus attendee, associated entity, and collaborator arrays
+- `search_notes` exposes only a compact `related` identity object from the nested `related` payload and excludes the rest of that payload plus associated entity and collaborator arrays
+- `search_call_logs` exposes only a compact `related` identity object from the nested `related` payload and excludes the rest of that payload plus associated entity and collaborator arrays
+- `search_tasks` treats `created_*` as task created-on range filters, `starting_*` as task due-date range filters, and `updated_*` as task updated-on range filters
+- `search_meetings` treats `created_*` as meeting created-on range filters, `starting_*` as meeting start date/time range filters, and `updated_*` as meeting updated-on range filters
+- `search_notes` treats `added_*` as note added-on range filters and `updated_*` as note updated-on range filters
+- `search_call_logs` treats `starting_*` as call started-on range filters and `updated_*` as call log updated-on range filters
+- `search_call_logs` does not support `related_to_type=job` or `related_to_type=deal`; Recruit CRM rejects those filters upstream
+- API tokens are read from environment variables only
+
+## Custom Field Flow
+
+Ask the client to resolve a custom field first, then search with its `field_id`. Example: find `Tech Stack`, get `field_id: 34`, then call `search_candidates` with `custom_fields`.
+
+`supported_filter_types` and `filter_value_required_for` are guidance for the model. The MCP server no longer blocks valid-looking searches locally based on the hardcoded field-type matrix, except when a referenced `field_id` does not exist.

package/dist/config.d.ts

@@ -0,0 +1,7 @@
+export type AppConfig = {
+    apiToken: string;
+    baseUrl: string;
+    timeoutMs: number;
+    debugSchemaErrors: boolean;
+};
+export declare function loadConfig(env?: NodeJS.ProcessEnv): AppConfig;

package/dist/config.js

@@ -0,0 +1,41 @@
+import * as z from "zod/v4";
+const DEFAULT_BASE_URL = "https://api.recruitcrm.io/v1";
+const DEFAULT_TIMEOUT_MS = 10_000;
+const envBooleanSchema = z
+    .preprocess((value) => (typeof value === "string" ? value.trim().toLowerCase() : value), z.union([z.literal("true"), z.literal("false"), z.literal("1"), z.literal("0")]).optional())
+    .transform((value) => value === "true" || value === "1");
+const envSchema = z.object({
+    RECRUITCRM_API_TOKEN: z.string().trim().min(1, "RECRUITCRM_API_TOKEN is required."),
+    RECRUITCRM_BASE_URL: z.string().trim().url().optional(),
+    RECRUITCRM_TIMEOUT_MS: z
+        .string()
+        .trim()
+        .optional()
+        .transform((value) => {
+        if (value === undefined || value === "") {
+            return DEFAULT_TIMEOUT_MS;
+        }
+        const parsed = Number(value);
+        if (!Number.isFinite(parsed) || parsed <= 0) {
+            throw new Error("RECRUITCRM_TIMEOUT_MS must be a positive integer.");
+        }
+        return Math.floor(parsed);
+    }),
+    RECRUITCRM_DEBUG_SCHEMA_ERRORS: envBooleanSchema,
+});
+export function loadConfig(env = process.env) {
+    const parsed = envSchema.safeParse(env);
+    if (!parsed.success) {
+        throw new Error(parsed.error.issues[0]?.message ?? "Invalid environment configuration.");
+    }
+    return {
+        apiToken: parsed.data.RECRUITCRM_API_TOKEN,
+        baseUrl: stripTrailingSlash(parsed.data.RECRUITCRM_BASE_URL ?? DEFAULT_BASE_URL),
+        timeoutMs: parsed.data.RECRUITCRM_TIMEOUT_MS,
+        debugSchemaErrors: parsed.data.RECRUITCRM_DEBUG_SCHEMA_ERRORS,
+    };
+}
+function stripTrailingSlash(value) {
+    return value.replace(/\/+$/, "");
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAE5B,MAAM,gBAAgB,GAAG,8BAA8B,CAAC;AACxD,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAClC,MAAM,gBAAgB,GAAG,CAAC;KACvB,UAAU,CACT,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,EAC3E,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAC5F;KACA,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,MAAM,IAAI,KAAK,KAAK,GAAG,CAAC,CAAC;AAE3D,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC;IACzB,oBAAoB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,mCAAmC,CAAC;IACnF,mBAAmB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IACvD,qBAAqB,EAAE,CAAC;SACrB,MAAM,EAAE;SACR,IAAI,EAAE;SACN,QAAQ,EAAE;SACV,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE;QACnB,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;YACxC,OAAO,kBAAkB,CAAC;QAC5B,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAE7B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;YAC5C,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;QACvE,CAAC;QAED,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC5B,CAAC,CAAC;IACJ,8BAA8B,EAAE,gBAAgB;CACjD,CAAC,CAAC;AASH,MAAM,UAAU,UAAU,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC7D,MAAM,MAAM,GAAG,SAAS,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IAExC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,IAAI,oCAAoC,CAAC,CAAC;IAC3F,CAAC;IAED,OAAO;QACL,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,oBAAoB;QAC1C,OAAO,EAAE,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC,mBAAmB,IAAI,gBAAgB,CAAC;QAChF,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,qBAAqB;QAC5C,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,8BAA8B;KAC9D,CAAC;AACJ,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAa;IACvC,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACnC,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,8 @@
+export declare class RecruitCrmApiError extends Error {
+    readonly statusCode?: number | undefined;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, statusCode?: number | undefined, cause?: unknown | undefined);
+}
+export declare function mapFetchError(error: unknown): RecruitCrmApiError;
+export declare function mapHttpError(statusCode: number): RecruitCrmApiError;
+export declare function invalidApiResponse(message?: string): RecruitCrmApiError;

package/dist/errors.js

@@ -0,0 +1,38 @@
+export class RecruitCrmApiError extends Error {
+    statusCode;
+    cause;
+    constructor(message, statusCode, cause) {
+        super(message);
+        this.statusCode = statusCode;
+        this.cause = cause;
+        this.name = "RecruitCrmApiError";
+    }
+}
+export function mapFetchError(error) {
+    if (error instanceof RecruitCrmApiError) {
+        return error;
+    }
+    if (error instanceof Error && error.name === "AbortError") {
+        return new RecruitCrmApiError("Recruit CRM API request timed out.", undefined, error);
+    }
+    return new RecruitCrmApiError("Unable to reach the Recruit CRM API.", undefined, error);
+}
+export function mapHttpError(statusCode) {
+    if (statusCode === 401 || statusCode === 403) {
+        return new RecruitCrmApiError("Recruit CRM API authentication failed.", statusCode);
+    }
+    if (statusCode === 404) {
+        return new RecruitCrmApiError("Candidate not found.", statusCode);
+    }
+    if (statusCode === 429) {
+        return new RecruitCrmApiError("Recruit CRM API rate limit exceeded.", statusCode);
+    }
+    if (statusCode >= 500) {
+        return new RecruitCrmApiError("Recruit CRM API is unavailable right now.", statusCode);
+    }
+    return new RecruitCrmApiError("Recruit CRM API request failed.", statusCode);
+}
+export function invalidApiResponse(message = "Recruit CRM API returned an invalid response.") {
+    return new RecruitCrmApiError(message);
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAGhC;IACA;IAHX,YACE,OAAe,EACN,UAAmB,EACnB,KAAe;QAExB,KAAK,CAAC,OAAO,CAAC,CAAC;QAHN,eAAU,GAAV,UAAU,CAAS;QACnB,UAAK,GAAL,KAAK,CAAU;QAGxB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,KAAK,YAAY,kBAAkB,EAAE,CAAC;QACxC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;QAC1D,OAAO,IAAI,kBAAkB,CAAC,oCAAoC,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;IACxF,CAAC;IAED,OAAO,IAAI,kBAAkB,CAAC,sCAAsC,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;AAC1F,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,UAAkB;IAC7C,IAAI,UAAU,KAAK,GAAG,IAAI,UAAU,KAAK,GAAG,EAAE,CAAC;QAC7C,OAAO,IAAI,kBAAkB,CAAC,wCAAwC,EAAE,UAAU,CAAC,CAAC;IACtF,CAAC;IAED,IAAI,UAAU,KAAK,GAAG,EAAE,CAAC;QACvB,OAAO,IAAI,kBAAkB,CAAC,sBAAsB,EAAE,UAAU,CAAC,CAAC;IACpE,CAAC;IAED,IAAI,UAAU,KAAK,GAAG,EAAE,CAAC;QACvB,OAAO,IAAI,kBAAkB,CAAC,sCAAsC,EAAE,UAAU,CAAC,CAAC;IACpF,CAAC;IAED,IAAI,UAAU,IAAI,GAAG,EAAE,CAAC;QACtB,OAAO,IAAI,kBAAkB,CAAC,2CAA2C,EAAE,UAAU,CAAC,CAAC;IACzF,CAAC;IAED,OAAO,IAAI,kBAAkB,CAAC,iCAAiC,EAAE,UAAU,CAAC,CAAC;AAC/E,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,OAAO,GAAG,+CAA+C;IAC1F,OAAO,IAAI,kBAAkB,CAAC,OAAO,CAAC,CAAC;AACzC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createRecruitCrmServer } from "./server.js";
+async function main() {
+    const server = createRecruitCrmServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Recruit CRM MCP Server running on stdio");
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : "Unknown startup error.";
+    console.error(`Recruit CRM MCP Server failed to start: ${message}`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAErD,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,sBAAsB,EAAE,CAAC;IACxC,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAE7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,yCAAyC,CAAC,CAAC;AAC3D,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC9B,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,wBAAwB,CAAC;IAClF,OAAO,CAAC,KAAK,CAAC,2CAA2C,OAAO,EAAE,CAAC,CAAC;IACpE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/recruitcrm/client.d.ts

@@ -0,0 +1,37 @@
+import type { AppConfig } from "../config.js";
+import { type HttpTransport } from "./http.js";
+import type { RecruitCrmCandidateCustomField, RecruitCrmCandidateJobAssignmentHiringStageHistoryResponse, RecruitCrmCallLogSearchResponse, CandidateDetail, JobDetail, RecruitCrmCompanySearchResponse, RecruitCrmJobSearchResponse, RecruitCrmMeetingSearchResponse, RecruitCrmNoteSearchResponse, RecruitCrmSearchResponse, RecruitCrmTaskSearchResponse, SearchCandidatesInput, SearchCallLogsInput, SearchCompaniesInput, SearchJobsInput, SearchMeetingsInput, SearchNotesInput, SearchTasksInput } from "./types.js";
+export declare class RecruitCrmClient {
+    #private;
+    constructor(config: AppConfig, transport?: HttpTransport);
+    searchCandidates(filters: SearchCandidatesInput): Promise<RecruitCrmSearchResponse>;
+    searchJobs(filters: SearchJobsInput): Promise<RecruitCrmJobSearchResponse>;
+    searchCompanies(filters: SearchCompaniesInput): Promise<RecruitCrmCompanySearchResponse>;
+    searchTasks(filters: SearchTasksInput): Promise<RecruitCrmTaskSearchResponse>;
+    searchMeetings(filters: SearchMeetingsInput): Promise<RecruitCrmMeetingSearchResponse>;
+    searchNotes(filters: SearchNotesInput): Promise<RecruitCrmNoteSearchResponse>;
+    searchCallLogs(filters: SearchCallLogsInput): Promise<RecruitCrmCallLogSearchResponse>;
+    getCandidateJobAssignmentHiringStageHistory(candidateSlug: string): Promise<RecruitCrmCandidateJobAssignmentHiringStageHistoryResponse>;
+    getCandidateDetails(candidateSlug: string): Promise<CandidateDetail>;
+    getJobDetails(jobSlug: string): Promise<JobDetail>;
+    getCandidateCustomFields(): Promise<RecruitCrmCandidateCustomField[]>;
+}
+export type GetRequestOptions = {
+    query?: URLSearchParams;
+    jsonBody?: {
+        custom_fields: SearchCandidatesCustomFieldsBody;
+    };
+};
+type SearchCandidatesCustomFieldsBody = Array<{
+    field_id: number;
+    filter_type: string;
+    filter_value?: string | number;
+}>;
+export declare function buildSearchCandidatesRequest(filters: SearchCandidatesInput): GetRequestOptions;
+export declare function buildSearchJobsRequest(filters: SearchJobsInput): GetRequestOptions;
+export declare function buildSearchCompaniesRequest(filters: SearchCompaniesInput): GetRequestOptions;
+export declare function buildSearchTasksRequest(filters: SearchTasksInput): GetRequestOptions;
+export declare function buildSearchMeetingsRequest(filters: SearchMeetingsInput): GetRequestOptions;
+export declare function buildSearchNotesRequest(filters: SearchNotesInput): GetRequestOptions;
+export declare function buildSearchCallLogsRequest(filters: SearchCallLogsInput): GetRequestOptions;
+export {};