ashby-mcp 1.3.2 → 1.4.0

package/README.md

@@ -22,7 +22,13 @@ This server exposes Ashby's recruiting data through the [Model Context Protocol]
 
 Just add the config below and it works immediately.
 
-#### Option B: From source
+#### Option B: Docker
+
+```bash
+docker build -t ashby-mcp .
+```
+
+#### Option C: From source
 
 ```bash
 git clone https://github.com/dewierwan/ashby-mcp.git && cd ashby-mcp
@@ -68,36 +74,219 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 }
 ```
 
+#### Docker
+
+```json
+{
+  "mcpServers": {
+    "ashby": {
+      "command": "docker",
+      "args": ["run", "--rm", "-i", "-e", "ASHBY_API_KEY", "ashby-mcp"],
+      "env": {
+        "ASHBY_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
 ## Tools
 
-### Read tools
-
-| Tool | Description |
-|------|-------------|
-| `ashby_list_jobs` | List open jobs with IDs, titles, department, location, status |
-| `ashby_get_job_details` | Full job details including interview plan stages |
-| `ashby_list_candidates_for_job` | List candidates/applications for a job with stage and status |
-| `ashby_get_candidate` | Comprehensive candidate profile with all applications |
-| `ashby_get_application_details` | Full application with stage history, feedback, evaluations |
-| `ashby_get_candidate_notes` | All notes on a candidate |
-| `ashby_search_candidates` | Search candidates by name or email |
-| `ashby_list_interview_stages` | List all interview stages (pipeline reference) |
-| `ashby_get_feedback` | Submitted feedback/scorecards for an application |
-| `ashby_get_resume` | Download and extract text from a candidate's resume (PDF, text) |
-| `ashby_list_applications` | List applications across all jobs with date, status, stage, and source filters |
-| `ashby_get_pipeline_summary` | Pipeline overview with candidate counts per stage, per job |
-| `ashby_list_archive_reasons` | List available archive/rejection reasons |
-| `ashby_list_email_templates` | List email templates for rejection emails |
-
-### Write tools
-
-| Tool | Description |
-|------|-------------|
-| `ashby_add_candidate_note` | Add an evaluation note to a candidate |
-| `ashby_move_application_stage` | Move an application to a different interview stage |
-| `ashby_add_candidate_tag` | Tag a candidate (e.g. "Strong Hire") |
-| `ashby_archive_application` | Archive an application with reason and optional rejection email |
-| `ashby_bulk_archive` | Archive multiple applications at once (max 25) |
+All tools return dual-format responses: a human-readable summary followed by structured JSON.
+
+### Jobs
+
+#### `ashby_list_jobs`
+
+List open jobs with IDs, titles, department, location, and status.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `status` | `"Open" \| "Closed" \| "Archived" \| "Draft" \| "All"` | `"Open"` | Filter by job status |
+| `limit` | `number` (1-100) | `25` | Max results per page |
+| `cursor` | `string` | — | Pagination cursor from previous response |
+
+#### `ashby_get_job_details`
+
+Full job details including description and interview plan stages.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `job_id` | `string` | Yes | Job ID (UUID) |
+
+#### `ashby_get_pipeline_summary`
+
+Pipeline overview with candidate counts per stage, per job.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `job_id` | `string` | — | Summary for one job. Omit for all jobs. |
+| `status` | `"Open" \| "Closed" \| "All"` | `"Open"` | Which jobs to include |
+
+### Candidates
+
+#### `ashby_get_candidate`
+
+Comprehensive candidate profile with all applications resolved.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `candidate_id` | `string` | Yes | Candidate ID (UUID) |
+
+#### `ashby_get_candidate_notes`
+
+All notes on a candidate.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `candidate_id` | `string` | Yes | Candidate ID (UUID) |
+
+#### `ashby_search_candidates`
+
+Search candidates by name or email.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `query` | `string` | — | Candidate name to search for (required) |
+| `email` | `string` | — | Optional email (AND logic with name) |
+| `limit` | `number` (1-100) | `25` | Max results |
+
+#### `ashby_add_candidate_note`
+
+Add an evaluation note to a candidate. Visible to the hiring team.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `candidate_id` | `string` | Yes | Candidate ID (UUID) |
+| `note` | `string` | Yes | Note content (plain text) |
+
+#### `ashby_add_candidate_tag`
+
+Tag a candidate (e.g. "Strong Hire", "Needs Review").
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `candidate_id` | `string` | Yes | Candidate ID (UUID) |
+| `tag_id` | `string` | Yes | Tag ID (UUID) from Ashby admin settings |
+
+#### `ashby_get_resume`
+
+Download and extract text from a candidate's resume (PDF, text).
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `file_handle` | `string` | Yes | File handle from candidate's `fileHandles` array |
+| `file_name` | `string` | No | Original filename (helps determine format) |
+
+### Applications
+
+#### `ashby_list_candidates_for_job`
+
+List candidates/applications for a specific job with stage and status.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `job_id` | `string` | — | Job ID (UUID) (required) |
+| `limit` | `number` (1-100) | `25` | Max results per page |
+| `cursor` | `string` | — | Pagination cursor |
+
+#### `ashby_get_application_details`
+
+Full application with stage history, feedback, and criteria evaluations.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `application_id` | `string` | Yes | Application ID (UUID) |
+
+#### `ashby_get_application_form_submission`
+
+Candidate's submitted application form responses (screening questions, cover letter, etc).
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `application_id` | `string` | Yes | Application ID (UUID) |
+
+#### `ashby_list_applications`
+
+List applications across all jobs with date, status, stage, and source filters.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `created_after` | `string` (ISO datetime) | — | Only applications after this time |
+| `created_before` | `string` (ISO datetime) | — | Only applications before this time |
+| `job_id` | `string` | — | Filter to a specific job |
+| `status` | `"Active" \| "Archived" \| "Hired" \| "Lead" \| "All"` | `"All"` | Filter by status |
+| `stage_type` | `"Lead" \| "PreInterviewScreen" \| "Interview" \| "Offer" \| "All"` | — | Filter by stage type |
+| `stage_name` | `string` | — | Filter by exact stage name |
+| `source` | `string` | — | Filter by source (case-insensitive substring) |
+| `limit` | `number` (1-100) | `25` | Max results |
+| `cursor` | `string` | — | Pagination cursor |
+
+#### `ashby_archive_application`
+
+Archive an application with reason and optional rejection email.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `application_id` | `string` | — | Application ID (UUID) (required) |
+| `archive_reason_id` | `string` | — | Reason ID from `ashby_list_archive_reasons` |
+| `send_email` | `boolean` | `false` | Send rejection email (requires `email_template_id`) |
+| `email_template_id` | `string` | — | Template ID from `ashby_list_email_templates` |
+
+#### `ashby_bulk_archive`
+
+Archive multiple applications at once (max 25).
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `application_ids` | `string[]` (1-25) | — | Application IDs (required) |
+| `archive_reason_id` | `string` | — | Reason ID, applied to all |
+| `send_email` | `boolean` | `false` | Send rejection emails |
+| `email_template_id` | `string` | — | Template ID for rejection emails |
+
+### Interviews
+
+#### `ashby_list_interview_stages`
+
+List all interview stages across all interview plans. No parameters.
+
+#### `ashby_list_upcoming_interviews`
+
+List upcoming and pending interview schedules.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `start_after` | `string` (ISO datetime) | now | Only interviews after this time |
+| `start_before` | `string` (ISO datetime) | — | Only interviews before this time |
+| `status` | `"Scheduled" \| "NeedsScheduling" \| "Complete" \| "Cancelled" \| "All"` | `"All"` | Filter by status |
+| `limit` | `number` (1-100) | `25` | Max results |
+
+### Workflow
+
+#### `ashby_move_application_stage`
+
+Move an application to a different interview stage.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `application_id` | `string` | Yes | Application ID (UUID) |
+| `stage_id` | `string` | Yes | Target stage ID from `ashby_list_interview_stages` |
+
+#### `ashby_get_feedback`
+
+Submitted feedback/scorecards for an application.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `application_id` | `string` | Yes | Application ID (UUID) |
+
+#### `ashby_list_archive_reasons`
+
+List available archive/rejection reasons. No parameters.
+
+#### `ashby_list_email_templates`
+
+List email templates for rejection emails. No parameters.
 
 ## Example Prompts
 

package/dist/ashby-client.js

@@ -1,4 +1,5 @@
 import { logger } from "./logger.js";
+import { validateApiKeyFormat } from "./enhance-error.js";
 const BASE_URL = "https://api.ashbyhq.com";
 const API_TIMEOUT_MS = 30_000;
 const MAX_RETRIES = 3;
@@ -9,7 +10,11 @@ export class AshbyClient {
         const apiKey = process.env.ASHBY_API_KEY;
         if (!apiKey) {
             throw new Error("ASHBY_API_KEY environment variable is required. " +
-                "Get an API key from your Ashby admin settings.");
+                "Get an API key from your Ashby admin settings → Integrations → API Keys.");
+        }
+        const validation = validateApiKeyFormat(apiKey);
+        if (!validation.valid) {
+            logger.warn("api key validation", { reason: validation.reason });
         }
         this.authHeader = `Basic ${Buffer.from(`${apiKey}:`).toString("base64")}`;
     }

package/dist/ashby-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"ashby-client.js","sourceRoot":"","sources":["../src/ashby-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ashby-client.js","sourceRoot":"","sources":["../src/ashby-client.ts"],"names":[],"mappings":"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"}

package/dist/enhance-error.d.ts

@@ -0,0 +1,18 @@
+import { AshbyApiError } from "./ashby-client.js";
+/**
+ * Transform an AshbyApiError into an actionable message with guidance
+ * on how to fix the issue.
+ */
+export declare function enhanceError(err: AshbyApiError): string;
+/**
+ * Look up the required Ashby permission for a given API endpoint.
+ */
+export declare function getRequiredPermission(endpoint: string): string | undefined;
+/**
+ * Validate that an Ashby API key looks reasonable.
+ * Ashby keys are typically 40+ character alphanumeric strings.
+ */
+export declare function validateApiKeyFormat(key: string): {
+    valid: boolean;
+    reason?: string;
+};

package/dist/enhance-error.js

@@ -0,0 +1,83 @@
+const PERMISSION_MAP = {
+    "job.list": "jobsRead",
+    "job.info": "jobsRead",
+    "jobPosting.info": "jobsRead",
+    "candidate.info": "candidatesRead",
+    "candidate.search": "candidatesRead",
+    "candidate.listNotes": "candidatesRead",
+    "candidate.createNote": "candidatesWrite",
+    "candidate.addTag": "candidatesWrite",
+    "application.info": "candidatesRead",
+    "application.list": "candidatesRead",
+    "application.listHistory": "candidatesRead",
+    "application.listCriteriaEvaluations": "candidatesRead",
+    "application.changeStage": "candidatesWrite",
+    "applicationFeedback.list": "candidatesRead",
+    "interviewPlan.list": "interviewsRead",
+    "interviewStage.list": "interviewsRead",
+    "interviewSchedule.list": "interviewsRead",
+    "archiveReason.list": "hiringProcessMetadataRead",
+    "communicationTemplate.list": "hiringProcessMetadataRead",
+    "file.info": "candidatesRead",
+};
+/**
+ * Transform an AshbyApiError into an actionable message with guidance
+ * on how to fix the issue.
+ */
+export function enhanceError(err) {
+    const base = `Ashby API error: ${err.message}${err.code ? ` (code: ${err.code})` : ""}`;
+    if (err.httpStatus === 401) {
+        return (`${base}\n\n` +
+            `Your API key appears to be invalid or expired.\n` +
+            `- Check that ASHBY_API_KEY is set correctly\n` +
+            `- Ashby API keys use Basic auth (the key is base64-encoded automatically)\n` +
+            `- Create or rotate your key at: Ashby Admin > Integrations > API Keys`);
+    }
+    if (err.httpStatus === 403) {
+        return (`${base}\n\n` +
+            `Your API key lacks the required permission.\n` +
+            `Required permissions for common operations:\n` +
+            `- candidatesRead: read candidate profiles, applications, notes, feedback\n` +
+            `- candidatesWrite: add notes, tags, move stages, archive\n` +
+            `- jobsRead: read jobs and job postings\n` +
+            `- interviewsRead: read interview stages, plans, and schedules\n` +
+            `- hiringProcessMetadataRead: list archive reasons and email templates\n` +
+            `Update your key at: Ashby Admin > Integrations > API Keys`);
+    }
+    if (err.httpStatus === 404) {
+        return (`${base}\n\n` +
+            `The requested resource was not found. Possible causes:\n` +
+            `- The ID may be incorrect (Ashby uses UUIDs like "a1b2c3d4-...")\n` +
+            `- The resource may have been deleted or archived\n` +
+            `- The API endpoint may not exist in your Ashby plan`);
+    }
+    if (err.httpStatus === 422) {
+        return (`${base}\n\n` +
+            `The request was invalid. Check that all required parameters are provided ` +
+            `and IDs are valid UUIDs.`);
+    }
+    return base;
+}
+/**
+ * Look up the required Ashby permission for a given API endpoint.
+ */
+export function getRequiredPermission(endpoint) {
+    return PERMISSION_MAP[endpoint];
+}
+/**
+ * Validate that an Ashby API key looks reasonable.
+ * Ashby keys are typically 40+ character alphanumeric strings.
+ */
+export function validateApiKeyFormat(key) {
+    if (!key || key.trim().length === 0) {
+        return { valid: false, reason: "API key is empty" };
+    }
+    if (key.length < 20) {
+        return { valid: false, reason: `API key seems too short (${key.length} chars). Ashby keys are typically 40+ characters.` };
+    }
+    if (key.startsWith("Bearer ") || key.startsWith("Basic ")) {
+        return { valid: false, reason: "API key should be the raw key, not prefixed with 'Bearer' or 'Basic'. The server handles encoding." };
+    }
+    return { valid: true };
+}
+//# sourceMappingURL=enhance-error.js.map

package/dist/enhance-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enhance-error.js","sourceRoot":"","sources":["../src/enhance-error.ts"],"names":[],"mappings":"AAEA,MAAM,cAAc,GAA2B;IAC7C,UAAU,EAAE,UAAU;IACtB,UAAU,EAAE,UAAU;IACtB,iBAAiB,EAAE,UAAU;IAC7B,gBAAgB,EAAE,gBAAgB;IAClC,kBAAkB,EAAE,gBAAgB;IACpC,qBAAqB,EAAE,gBAAgB;IACvC,sBAAsB,EAAE,iBAAiB;IACzC,kBAAkB,EAAE,iBAAiB;IACrC,kBAAkB,EAAE,gBAAgB;IACpC,kBAAkB,EAAE,gBAAgB;IACpC,yBAAyB,EAAE,gBAAgB;IAC3C,qCAAqC,EAAE,gBAAgB;IACvD,yBAAyB,EAAE,iBAAiB;IAC5C,0BAA0B,EAAE,gBAAgB;IAC5C,oBAAoB,EAAE,gBAAgB;IACtC,qBAAqB,EAAE,gBAAgB;IACvC,wBAAwB,EAAE,gBAAgB;IAC1C,oBAAoB,EAAE,2BAA2B;IACjD,4BAA4B,EAAE,2BAA2B;IACzD,WAAW,EAAE,gBAAgB;CAC9B,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,GAAkB;IAC7C,MAAM,IAAI,GAAG,oBAAoB,GAAG,CAAC,OAAO,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IAExF,IAAI,GAAG,CAAC,UAAU,KAAK,GAAG,EAAE,CAAC;QAC3B,OAAO,CACL,GAAG,IAAI,MAAM;YACb,kDAAkD;YAClD,+CAA+C;YAC/C,6EAA6E;YAC7E,uEAAuE,CACxE,CAAC;IACJ,CAAC;IAED,IAAI,GAAG,CAAC,UAAU,KAAK,GAAG,EAAE,CAAC;QAC3B,OAAO,CACL,GAAG,IAAI,MAAM;YACb,+CAA+C;YAC/C,+CAA+C;YAC/C,4EAA4E;YAC5E,4DAA4D;YAC5D,0CAA0C;YAC1C,iEAAiE;YACjE,yEAAyE;YACzE,2DAA2D,CAC5D,CAAC;IACJ,CAAC;IAED,IAAI,GAAG,CAAC,UAAU,KAAK,GAAG,EAAE,CAAC;QAC3B,OAAO,CACL,GAAG,IAAI,MAAM;YACb,0DAA0D;YAC1D,oEAAoE;YACpE,oDAAoD;YACpD,qDAAqD,CACtD,CAAC;IACJ,CAAC;IAED,IAAI,GAAG,CAAC,UAAU,KAAK,GAAG,EAAE,CAAC;QAC3B,OAAO,CACL,GAAG,IAAI,MAAM;YACb,2EAA2E;YAC3E,0BAA0B,CAC3B,CAAC;IACJ,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAAgB;IACpD,OAAO,cAAc,CAAC,QAAQ,CAAC,CAAC;AAClC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAW;IAC9C,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpC,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC;IACtD,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC;QACpB,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,4BAA4B,GAAG,CAAC,MAAM,mDAAmD,EAAE,CAAC;IAC7H,CAAC;IACD,IAAI,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1D,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,oGAAoG,EAAE,CAAC;IACxI,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACzB,CAAC"}