hirelayer-mcp 1.1.1 → 2.1.0

package/README.md

@@ -4,9 +4,9 @@
 
 # HireLayer MCP Server
 
-**Resume parsing, candidate matching and candidate ranking for AI agents.**
+**Resume parsing, resume scoring and talent pool search for AI agents.**
 
-The official [Model Context Protocol](https://modelcontextprotocol.io) server for [HireLayer](https://hirelayer.co). Parse resumes and CVs, turn job descriptions into criteria, then score and rank candidates from Claude, ChatGPT, Cursor, VS Code, Codex or any MCP client.
+The official [Model Context Protocol](https://modelcontextprotocol.io) server for [HireLayer](https://hirelayer.co). Parse resumes and CVs, turn job descriptions into criteria, score and rank resumes against a job, and search the candidates and jobs you already have, from Claude, ChatGPT, Cursor, VS Code, Codex or any MCP client.
 
 **Server URL: `https://hirelayer.co/mcp`** · sign in with your HireLayer account, no API key to copy.
 
@@ -24,7 +24,7 @@ The official [Model Context Protocol](https://modelcontextprotocol.io) server fo
 
 > "Screen these 3 resumes against the Senior React job and tell me who to interview."
 >
-> Your assistant parses each CV, extracts the job criteria, scores every candidate criterion by criterion and explains the shortlist.
+> Your assistant parses each CV, scores every candidate against the job criterion by criterion and explains the shortlist.
 
 ## Contents
 
@@ -40,11 +40,12 @@ The official [Model Context Protocol](https://modelcontextprotocol.io) server fo
 
 ## What you can do
 
-- **Parse resumes and CVs.** Turn PDF, Word, image and other files into structured JSON: contact details, work experience, education, languages, skills and the full text. Scanned resumes go through OCR, and the resume language is detected.
-- **Turn a job description into criteria.** Get weighted, explained matching criteria, with mandatory requirements flagged.
-- **Match candidates to jobs.** Score a resume against a job from 0 to 1, with an explanation for each criterion.
-- **Rank candidates.** Order up to 10 candidates for the same job in one call, with a score and a rationale for each.
-- **Normalize skills.** Map free-text skills in French or English to a skills taxonomy with stable IDs.
+- **Parse resumes and CVs** (Resume Parser). Turn PDF, Word, image and other files into structured JSON: contact details, work experience, education, languages, skills and the full text. Scanned resumes go through OCR, and the resume language is detected.
+- **Turn a job description into criteria** (Job Criteria Extractor). Get the typed, weighted criteria the posting states, each marked required, preferred or bonus, in English, French, German, Spanish or Portuguese. Free.
+- **Score and rank resumes** (Resume Scorer). Score up to 50 resumes against a job in one call, from 0 to 1, with a verdict, a summary and the evidence for each criterion, best first. Ask for a precise ranking to re-rank the 10 best with a reason each.
+- **Search your talent pool** (Talent Pool Search). Find the resumes already in your HireLayer database closest to a job, around a city if you like.
+- **Recommend jobs** (Job Recommendations). Find your open jobs closest to a candidate.
+- **Normalize skills** (Skills Normalizer). Map free-text skills to a skills taxonomy with stable IDs, named in French or English.
 
 Use it to screen applicants in a chat, build a recruiting agent, enrich an ATS, or prototype HR tech features without writing integration code.
 
@@ -208,27 +209,32 @@ docker build -t hirelayer-mcp .
 docker run -i --rm -e HIRELAYER_API_KEY=your-api-key hirelayer-mcp
 ```
 
-In Docker, `parse_resume` only reads files that you mount into the container. Otherwise, pass `file_url`.
+In Docker, `parse_resume` only reads files that you mount into the container. Otherwise, pass `file_url` or `resume_text`.
 
 </details>
 
 ## Tools
 
-| Tool | What it does | Typical input |
-|---|---|---|
-| `parse_resume` | Parses a resume or CV file into structured JSON: contact details, experience, education, languages, skills and the full text | A local `file_path` or a public `file_url`. Accepts PDF, DOC, DOCX, ODT, RTF, TXT, PPT, PPTX, ODP, XLS, JPG, PNG or BMP files under 4.5 MB. |
-| `extract_job_criteria` | Turns a job description into weighted criteria: a weight from 1 to 3, a mandatory flag and a rationale for each | Job description text |
-| `match_candidate` | Scores one candidate against a job from 0 to 1, with a summary and a status and explanation for each criterion | Job text, resume text and criteria |
-| `rank_candidates` | Ranks up to 10 candidates for one job, with a score and a rationale for each | Job text and up to 10 resume texts |
-| `resolve_skills` | Maps free-text skills in French or English to taxonomy skills, with their families and domains | Free text, from one skill to a whole skills section |
+| Tool | Product | What it does | Typical input |
+|---|---|---|---|
+| `parse_resume` | Resume Parser | Parses a resume or CV into structured JSON: contact details, experience, education, languages, skills and the full text, stored under an `application_id` | A local `file_path`, a public `file_url` or the `resume_text`. Accepts PDF, DOC, DOCX, ODT, RTF, TXT, HTML, Markdown, PPT, PPTX, ODP, XLS, JPG, PNG or BMP files under 4.5 MB. |
+| `extract_job_criteria` | Job Criteria Extractor | Turns a job description into the typed criteria it states, each with a requirement (required, preferred or bonus) and a weight from 0 to 3, and stores the job under a `job_id` | Job description text, at least 30 characters |
+| `score_resumes` | Resume Scorer | Scores 1 to 50 resumes against one job, best first: a score from 0 to 1, a verdict, a summary, the required criteria missing and the evidence for each criterion. `precise_ranking` re-ranks the 10 best with a reason each | The job as `job_text` (optionally with your own `criteria`) or a `job_id`, and each resume as `text` or an `application_id`; at least one resume of 30 characters or more |
+| `search_resumes` | Talent Pool Search | Finds the stored resumes closest to a job, with optional city, radius and date filters. Proximity only: score the ones worth it with `score_resumes` | A `job_id` or `job_text` |
+| `search_jobs` | Job Recommendations | Finds the stored open jobs closest to a resume. Proximity only | An `application_id` or `resume_text` |
+| `normalize_skills` | Skills Normalizer | Maps free-text skills to taxonomy skills, with their families and domains, named in French or English | Free text, from one skill to a whole skills section |
+
+HireLayer keeps the resumes, jobs and scores in your HireLayer account, as the REST API does, so a resume or a job-resume pair already processed costs nothing the second time and the two searches have something to search. `normalize_skills` stores nothing. No tool deletes anything or changes your other systems.
+
+**Several client companies?** Every tool except `normalize_skills` takes an optional `workspace` (for example `acme-corp`), sent as the `HireLayer-Workspace` header: each client's jobs, resumes and scores stay apart. A new id creates a new workspace; without one, calls use your default workspace.
 
-All tools only read and analyse data. They never change anything in your systems.
+Upgrading from 1.x: `match_candidate` and `rank_candidates` became `score_resumes`, and `resolve_skills` became `normalize_skills`. See the [changelog](CHANGELOG.md).
 
 The server also ships **prompts** that clients show as ready-made commands:
 
 | Prompt | What it does |
 |---|---|
-| `screen_candidates` | Runs the full screening workflow (criteria, parsing, matching) and writes a shortlist |
+| `screen_candidates` | Parses the resume files, scores every resume against the job in one call with a precise ranking, and writes a shortlist |
 | `summarize_resume` | Parses one resume and writes a recruiter summary |
 | `normalize_skills` | Normalizes a skills section and groups it by domain |
 
@@ -236,37 +242,61 @@ The server also ships **prompts** that clients show as ready-made commands:
 
 ```mermaid
 flowchart LR
-    J[Job description] --> C[extract_job_criteria]
+    J[Job description] --> S[score_resumes]
     R[Resume files] --> P[parse_resume]
-    C --> M[match_candidate]
-    P --> M
-    P --> K[rank_candidates]
-    J --> K
-    M --> S[Shortlist with explanations]
-    K --> S
+    P -- application_id --> S
+    T[Resume texts] --> S
+    J -. review criteria first .-> C[extract_job_criteria]
+    C -. job_id .-> S
+    D[(Your talent pool)] --> Q[search_resumes]
+    Q -- application_ids --> S
+    S --> L[Shortlist with evidence]
 ```
 
 <details>
-<summary><b>Example output from <code>match_candidate</code></b></summary>
+<summary><b>Example output from <code>score_resumes</code></b></summary>
+
+Trimmed to one resume and one criterion:
 
 ```json
 {
-  "score": 0.89,
-  "summary": "Profil très aligné : React, TypeScript et l’expérience demandée sont démontrés. Le niveau d’anglais reste à confirmer.",
-  "evaluated_criteria": [
+  "job": {
+    "job_id": "job_8f14e45fceea167a5a36dedd4bea2543",
+    "title": "Senior React Developer",
+    "language": "en"
+  },
+  "precise_ranking": true,
+  "scores": [
     {
-      "id": "crit_1",
-      "label": "Maîtrise de React",
-      "weight": 3,
-      "is_mandatory": true,
-      "match_status": "ideal",
-      "match_explanation": "Le CV décrit une équipe React dirigée depuis 2022 sur une plateforme en production."
+      "rank": 1,
+      "application_id": "text_c4ca4238a0b923820dcc509a6f75849b",
+      "reference": "alex-morgan",
+      "evaluation_status": "completed",
+      "score": 0.91,
+      "verdict": "highly_relevant",
+      "summary": "Strong fit: 8 years of React and TypeScript, team lead, automated testing with Jest and Playwright. Health tech experience to confirm.",
+      "ranking_reason": "The only candidate who has led a React and TypeScript team in production.",
+      "required_missing": [],
+      "to_verify": [],
+      "criteria": [
+        {
+          "criterion_id": "crit_2",
+          "label": "React experience",
+          "requirement": "required",
+          "weight": 3,
+          "status": "met",
+          "score": 1,
+          "evidence": "Lead Front-End Engineer, Medisoft: 'Lead a team of 4 developers on a React 18 + TypeScript appointment platform'",
+          "explanation": "Over 3 years of React, the last ones leading a team on a production platform."
+        }
+      ]
     }
-  ]
+  ],
+  "credits_used": 3
 }
 ```
 
-Criteria labels, rationales, summaries and explanations are written in French. Your assistant translates them when it answers you in another language.
+Criteria, summaries and explanations are written in the job's language (English, French, German, Spanish or Portuguese; English for any other) unless you pass `language`; evidence quotes the resume in its own language.
 
 </details>
 
@@ -275,10 +305,13 @@ Criteria labels, rationales, summaries and explanations are written in French. Y
 **Recruiters and hiring managers**
 
 - "Parse `~/Downloads/jane-doe.pdf` and summarize her experience in five bullet points."
-- "Here is our job description for a Senior Data Engineer. Extract the criteria, then tell me which ones are must-haves."
+- "Here is our job description for a Senior Data Engineer. Extract the criteria, then tell me which ones are required."
 - "Score the resumes in `~/candidates/` against this job and give me a shortlist table with scores and main gaps."
-- "Rank these 8 candidates for the Account Executive role and explain why the top 3 stand out."
-- "Does this candidate meet every mandatory criterion? If not, which ones are missing?"
+- "Rank these 8 candidates for the Account Executive role with a precise ranking and explain why the top 3 stand out."
+- "Does this candidate meet every required criterion? If not, which ones are missing?"
+- "Which candidates already in my HireLayer database fit this job? Keep those within 50 km of Lyon."
+- "Which of our open jobs suit this candidate?"
+- "For our client Acme Corp (workspace `acme-corp`), score these resumes against their Product Manager job."
 
 **Developers and HR tech teams**
 
@@ -292,18 +325,27 @@ Criteria labels, rationales, summaries and explanations are written in French. Y
 
 ## Pricing and credits
 
-Each successful tool call costs **1 HireLayer credit**. A `rank_candidates` call costs 1 credit whatever the number of candidates. Failed calls are not charged.
+| Tool | Credits |
+|---|---|
+| `parse_resume` | 1 per resume, 0 for a file already stored |
+| `extract_job_criteria` | Free (a new text for a job already scored evaluates its scores again, 1 credit each) |
+| `score_resumes` | 1 per resume evaluated, 0 for a job-resume pair already scored; 1 more per call with `precise_ranking` |
+| `search_resumes`, `search_jobs` | 1 per search |
+| `normalize_skills` | 1 |
+
+Failed calls and resumes that fail are not charged, and a call refused for lack of credits processes nothing.
 
 | Plan | Credits | Price |
 |---|---|---|
 | Free | 50 a month | Free, no card required |
-| Paid plans | More credits and higher limits | See [hirelayer.co/#pricing](https://hirelayer.co/#pricing) |
+| Paid plans | More credits and higher limits | See [hirelayer.co/pricing](https://hirelayer.co/pricing) |
 
 ## Data and privacy
 
 - The hosted server receives only what your assistant sends to HireLayer tools. Each app gets access only after you sign in and allow it, and you can disconnect it at any time.
 - The local server runs **on your machine** and calls the HireLayer API over HTTPS with your API key. It has no telemetry.
-- `parse_resume` reads only the file you name. By default HireLayer stores the original file and returns a link to it in `info_resume.url`. Set `do_not_store_data: true` in a call so the file is not stored.
+- `parse_resume` reads only the file you name. HireLayer stores the resume in your account under its `application_id`, keeps the original file and returns a link to it in `resume.info_resume.url`. On the Enterprise plan, set `do_not_store_data: true` in a call so nothing of the parse is kept.
+- The jobs, resumes and scores the tools process stay in your HireLayer account, in the workspace of the call, so you can score and search them again later.
 - See the [privacy policy](https://hirelayer.co/privacy-policy) and the [security policy](SECURITY.md).
 
 Resumes contain personal data. Use the tools in line with your hiring process and the rules that apply to you, such as GDPR. Scores support human decisions; they don't replace them.
@@ -321,8 +363,10 @@ Resumes contain personal data. Use the tools in line with your hiring process an
 |---|---|
 | `HIRELAYER_API_KEY is not set` | Add the `env` block with your key to the client config, then restart the client. |
 | `HireLayer API returned 401` | The key is wrong or revoked. Copy it again from **Dashboard → API keys**. |
-| `HireLayer API returned 403` | You have used your monthly credits. Wait for the reset or upgrade your plan. |
-| Parsing seems slow | Parsing usually takes about 35 seconds, and longer for scans that need OCR. The server sends progress updates so clients don't time out. |
+| `HireLayer API returned 403 (insufficient_credits)` | You have used your monthly credits. Wait for the reset or upgrade your plan. |
+| `HireLayer API returned 403 (enterprise_plan_required)` | `do_not_store_data` needs the Enterprise plan. Call again without it if storing the resume is fine. |
+| `HireLayer API returned 410` | You run a 1.x version, which calls retired endpoints. Update to the latest version with `npx -y hirelayer-mcp@latest`. |
+| Parsing or scoring seems slow | Parsing usually takes about 30 seconds, and longer for scans that need OCR; scoring 50 resumes takes about a minute. The server sends progress updates so clients don't time out. |
 | `npx` not found or an old Node.js | Install Node.js 20 or later from [nodejs.org](https://nodejs.org). |
 | The file is not found | Use an absolute path, for example `/Users/me/Downloads/cv.pdf` rather than `~/Downloads/cv.pdf`. |
 
@@ -335,13 +379,13 @@ HIRELAYER_API_KEY=your-api-key npx @modelcontextprotocol/inspector npx -y hirela
 ## FAQ
 
 **Is HireLayer an ATS?**
-No. HireLayer provides the AI building blocks of recruiting software: resume parsing, matching, ranking and skills. Use them on their own through MCP, or plug them into your ATS or HR tech product through the [REST API](https://hirelayer.co/api-docs).
+No. HireLayer provides the AI building blocks of recruiting software: resume parsing, scoring and ranking, talent pool search and skills. Use them on their own through MCP, or plug them into your ATS or HR tech product through the [REST API](https://hirelayer.co/api-docs).
 
 **Which language are the results in?**
-The text that HireLayer writes (criteria labels and rationales, match summaries and explanations, ranking rationales) is in French; your assistant translates it when it answers in another language. Skills resolution returns French or English labels.
+The text that HireLayer writes (criteria, summaries, explanations and ranking reasons) is in the job's language: English, French, German, Spanish or Portuguese, and English for a job written in another language. Choose it with `language` (`en`, `fr`, `de`, `es` or `pt`). Evidence quotes the resume in its own language. Skills normalization returns French or English labels.
 
 **Which resume languages are supported?**
-The parser detects the main language of each resume and returns it in `info_resume.language`.
+The parser detects the main language of each resume and returns it in `resume.info_resume.language`.
 
 **Can I use the REST API directly?**
 Yes. See the [API reference](https://hirelayer.co/api-docs), the [OpenAPI spec](https://hirelayer.co/openapi.json) and [`llms.txt`](https://hirelayer.co/llms.txt) for agents.

package/dist/client.js

@@ -3,74 +3,124 @@ import { createRequire } from 'node:module';
 import { basename } from 'node:path';
 export const VERSION = createRequire(import.meta.url)('../package.json').version;
 const DEFAULT_BASE_URL = 'https://hirelayer.co';
+const API_PREFIX = '/api/v4';
+/** Keeps one client company's jobs, resumes and scores apart from another's. */
+export const WORKSPACE_HEADER = 'HireLayer-Workspace';
 // The API rejects resumes above 4.5 MB.
 export const MAX_RESUME_BYTES = 4.5 * 1024 * 1024;
 // 502 and 503 are transient and never charged, so one retry is safe.
 const RETRYABLE_STATUSES = new Set([502, 503]);
 const MAX_RETRY_DELAY_MS = 10_000;
+// A scoring call whose evaluations outlast about 100 seconds answers 202 with a results_url,
+// read until no score is pending, for this long at most.
+const MAX_SCORING_WAIT_MS = 10 * 60_000;
 export class HireLayerError extends Error {
     status;
-    constructor(message, status) {
+    code;
+    param;
+    requestId;
+    constructor(message, status, 
+    /** The code of the API error, such as insufficient_credits; undefined when the API sent none. */
+    code, 
+    /** The input at fault, such as job.criteria, when the API names one. */
+    param, 
+    /** The id of the failed call, to quote to HireLayer support. */
+    requestId) {
         super(message);
         this.status = status;
+        this.code = code;
+        this.param = param;
+        this.requestId = requestId;
         this.name = 'HireLayerError';
     }
 }
+/** The languages a job's criteria, summaries and explanations are written in. */
+export const JOB_LANGUAGES = ['en', 'fr', 'de', 'es', 'pt'];
 export class HireLayerClient {
     apiKey;
     baseUrl;
     fetch;
     retryDelayMs;
-    constructor({ apiKey, baseUrl, fetch: fetchImpl, retryDelayMs }) {
+    pollIntervalMs;
+    constructor({ apiKey, baseUrl, fetch: fetchImpl, retryDelayMs, pollIntervalMs }) {
         this.apiKey = apiKey;
         this.baseUrl = (baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, '');
         this.fetch = fetchImpl ?? globalThis.fetch;
         this.retryDelayMs = retryDelayMs ?? 2_000;
+        this.pollIntervalMs = pollIntervalMs ?? 5_000;
     }
+    /** Resume Parser: POST /resumes/parse. */
     async parseResume(source, options = {}) {
-        const { bytes, filename } = await this.loadResume(source, options.signal);
+        const { bytes, filename, type } = await this.loadResume(source, options.signal);
         const form = new FormData();
-        form.append('file', new Blob([bytes]), filename);
+        form.append('file', new Blob([bytes], type ? { type } : {}), filename);
         if (options.applicationId)
             form.append('application_id', options.applicationId);
         if (options.doNotStoreData !== undefined) {
             form.append('do_not_store_data', String(options.doNotStoreData));
         }
-        return this.request('/api/v3/parser', { method: 'POST', body: form, signal: options.signal });
+        return this.request('/resumes/parse', { method: 'POST', body: form, signal: options.signal }, options.workspace);
     }
-    extractJobCriteria(jobText, options = {}) {
-        return this.postJson('/api/v1/jobs/extract-criteria', { job_text: jobText }, options);
+    /** Job Criteria Extractor: POST /jobs/extract-criteria. */
+    extractJobCriteria(body, options = {}) {
+        return this.postJson('/jobs/extract-criteria', body, options);
     }
-    matchCandidate(body, options = {}) {
-        return this.postJson('/api/v1/matching/job-candidate', body, options);
+    /**
+     * Resume Scorer: POST /resumes/score. When the evaluations outlast the API's wait (202),
+     * reads results_url until no score is pending and returns that read: the call's resumes, best first.
+     */
+    async scoreResumes(body, options = {}) {
+        const answer = await this.postJson('/resumes/score', body, options);
+        const resultsPath = pendingResultsPath(answer);
+        if (!resultsPath)
+            return answer;
+        const deadline = Date.now() + MAX_SCORING_WAIT_MS;
+        while (Date.now() < deadline) {
+            await sleep(this.pollIntervalMs, options.signal);
+            const read = await this.request(resultsPath, { method: 'GET', signal: options.signal }, options.workspace);
+            if (!hasPendingScores(read))
+                return read;
+        }
+        return {
+            ...answer,
+            next_step: 'HireLayer is still scoring these resumes. Call score_resumes again later with the same job and resumes: the resumes already scored come back at no extra cost.',
+        };
+    }
+    /** Talent Pool Search: POST /resumes/search. */
+    searchResumes(body, options = {}) {
+        return this.postJson('/resumes/search', body, options);
     }
-    rankCandidates(body, options = {}) {
-        return this.postJson('/api/v1/matching/job-candidates/rank', body, options);
+    /** Job Recommendations: POST /jobs/search. */
+    searchJobs(body, options = {}) {
+        return this.postJson('/jobs/search', body, options);
     }
-    resolveSkills(text, language, options = {}) {
-        return this.postJson('/api/v1/skills/resolve', language ? { text, language } : { text }, options);
+    /** Skills Normalizer: POST /skills/normalize. Nothing is stored, so it takes no workspace. */
+    normalizeSkills(text, language, options = {}) {
+        return this.postJson('/skills/normalize', language ? { text, language } : { text }, options);
     }
-    postJson(path, body, { signal }) {
+    // JSON.stringify leaves out the fields left undefined, so the API sees only what was given.
+    postJson(path, body, { signal, workspace }) {
         return this.request(path, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify(body),
             signal,
-        });
+        }, workspace);
     }
-    async request(path, init, attempt = 1) {
-        const response = await this.fetch(`${this.baseUrl}${path}`, {
+    async request(path, init, workspace, attempt = 1) {
+        const response = await this.fetch(`${this.baseUrl}${API_PREFIX}${path}`, {
             ...init,
             headers: {
                 ...init.headers,
                 'X-API-Key': this.apiKey,
                 'User-Agent': `hirelayer-mcp/${VERSION}`,
+                ...(workspace ? { [WORKSPACE_HEADER]: workspace } : {}),
             },
         });
         if (attempt === 1 && RETRYABLE_STATUSES.has(response.status) && !init.signal?.aborted) {
             await response.body?.cancel();
             await sleep(this.retryDelay(response.headers.get('retry-after')), init.signal);
-            return this.request(path, init, attempt + 1);
+            return this.request(path, init, workspace, attempt + 1);
         }
         const text = await response.text();
         let payload = text;
@@ -80,10 +130,8 @@ export class HireLayerClient {
         catch {
             // Keep the raw text: gateways can answer with HTML or plain text.
         }
-        if (!response.ok) {
-            const detail = typeof payload === 'string' ? payload.slice(0, 500) : JSON.stringify(payload);
-            throw new HireLayerError(`HireLayer API returned ${response.status}: ${detail}${errorHint(response.status, detail)}`, response.status);
-        }
+        if (!response.ok)
+            throw apiError(response.status, payload, response.headers.get('hirelayer-request-id'));
         return payload;
     }
     retryDelay(retryAfter) {
@@ -93,17 +141,19 @@ export class HireLayerClient {
         }
         return this.retryDelayMs;
     }
-    async loadResume({ filePath, fileUrl }, signal) {
-        if (Boolean(filePath) === Boolean(fileUrl)) {
-            throw new HireLayerError('Provide exactly one of file_path or file_url.');
+    async loadResume({ filePath, fileUrl, text }, signal) {
+        const given = [filePath, fileUrl, text].filter((value) => value !== undefined && value !== '');
+        if (given.length !== 1) {
+            throw new HireLayerError('Provide exactly one of file_path, file_url or resume_text.');
         }
         let bytes;
         let filename;
+        let type;
         if (filePath) {
             bytes = new Uint8Array(await readFile(filePath));
             filename = basename(filePath);
         }
-        else {
+        else if (fileUrl) {
             const response = await this.fetch(fileUrl, { signal });
             if (!response.ok) {
                 throw new HireLayerError(`Could not download ${fileUrl}: HTTP ${response.status}`);
@@ -111,18 +161,63 @@ export class HireLayerClient {
             bytes = new Uint8Array(await response.arrayBuffer());
             filename = basename(new URL(fileUrl).pathname) || 'resume';
         }
+        else {
+            bytes = new TextEncoder().encode(text);
+            filename = 'resume.txt';
+            type = 'text/plain';
+        }
         if (bytes.byteLength > MAX_RESUME_BYTES) {
             throw new HireLayerError(`The resume is ${(bytes.byteLength / 1024 / 1024).toFixed(1)} MB; HireLayer accepts files under 4.5 MB.`);
         }
-        return { bytes, filename };
+        return { bytes, filename, type };
+    }
+}
+/**
+ * The API answers errors as {"error": {"code", "message", "param", "doc_url"}, "request_id"}; gateways
+ * in front of it can still answer with HTML or plain text, kept as they come.
+ */
+function apiError(status, payload, headerRequestId) {
+    const body = payload && typeof payload === 'object' ? payload : null;
+    const error = body?.error;
+    const requestId = typeof body?.request_id === 'string' ? body.request_id : headerRequestId || undefined;
+    const support = requestId ? ` (request_id ${requestId})` : '';
+    if (error && typeof error === 'object') {
+        const { code, message, param } = error;
+        const errorCode = typeof code === 'string' ? code : undefined;
+        const errorParam = typeof param === 'string' ? param : undefined;
+        const label = [errorCode, errorParam && `param ${errorParam}`].filter(Boolean).join(', ');
+        const text = typeof message === 'string' ? message : JSON.stringify(error);
+        return new HireLayerError(`HireLayer API returned ${status}${label ? ` (${label})` : ''}: ${text}${errorHint(status, errorCode, text)}${support}`, status, errorCode, errorParam, requestId);
     }
+    const detail = typeof payload === 'string' ? payload.slice(0, 500) : JSON.stringify(payload);
+    return new HireLayerError(`HireLayer API returned ${status}: ${detail}${errorHint(status, undefined, detail)}${support}`, status, undefined, undefined, requestId);
 }
-function errorHint(status, detail) {
+/** The path of results_url under /api/v4 when a scoring call answered 202 without a webhook, else null. */
+function pendingResultsPath(answer) {
+    if (!answer || typeof answer !== 'object')
+        return null;
+    const { status, results_url: resultsUrl, webhook_url: webhookUrl } = answer;
+    if (status !== 'pending' || typeof resultsUrl !== 'string' || webhookUrl)
+        return null;
+    // Read through the client's own base URL: results_url names the production host.
+    const url = new URL(resultsUrl);
+    if (!url.pathname.startsWith(`${API_PREFIX}/`))
+        return null;
+    return `${url.pathname.slice(API_PREFIX.length)}${url.search}`;
+}
+function hasPendingScores(read) {
+    const data = read && typeof read === 'object' ? read.data : undefined;
+    return Array.isArray(data) && data.some((score) => score?.evaluation_status === 'pending');
+}
+function errorHint(status, code, detail) {
     if (status === 401) {
         return ' Check HIRELAYER_API_KEY: copy your key from https://hirelayer.co/dashboard/api-keys.';
     }
-    if (status === 403 && /credit/i.test(detail)) {
-        return ' Credits reset every month; see https://hirelayer.co/#pricing for more.';
+    if (code === 'insufficient_credits' || (status === 403 && !code && /credit/i.test(detail))) {
+        return ' Credits reset every month; more at https://hirelayer.co/pricing.';
+    }
+    if (code === 'enterprise_plan_required') {
+        return ' do_not_store_data needs the Enterprise plan. Without it HireLayer stores the resume: check with the user before parsing again without the option.';
     }
     return '';
 }

package/dist/server.js

@@ -1,33 +1,87 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import { VERSION } from './client.js';
+import { HireLayerError, JOB_LANGUAGES, VERSION } from './client.js';
 // Clients drop calls that stay silent too long (often after 60 s); parsing takes about
-// 35 s and scans needing OCR take longer, so long calls report progress at this interval.
+// 30 s, scans needing OCR and scoring 50 resumes longer, so long calls report progress at this interval.
 const PROGRESS_INTERVAL_MS = 10_000;
-const INSTRUCTIONS = `HireLayer gives you recruiting tools: resume (CV) parsing, job criteria extraction, candidate matching, candidate ranking and skills normalization.
+const INSTRUCTIONS = `HireLayer gives you recruiting tools, one per product: Resume Parser (parse_resume), Job Criteria Extractor (extract_job_criteria), Resume Scorer (score_resumes), Talent Pool Search (search_resumes), Job Recommendations (search_jobs) and Skills Normalizer (normalize_skills).
 
 Typical workflows:
-- Screen candidates for a job: extract_job_criteria on the job description, parse_resume on each resume, then match_candidate for each one (pass the criteria and info_resume.text). Use rank_candidates to order up to 10 candidates in one call.
-- Read a resume: parse_resume returns contact details, experience, education, languages, skills and the full text.
-- Normalize skills: resolve_skills maps free text in French or English to taxonomy skills.
+- Screen candidates for a job: score_resumes with the job description (job_text) and the resumes (their text, or the application_id of resumes already parsed). It extracts the job's criteria on the way and returns every resume scored, best first. Set precise_ranking to re-rank the 10 best against each other, with a one-sentence reason each.
+- Review or edit the criteria first: extract_job_criteria, then score_resumes with the job_id it returned, or with job_text and your edited criteria.
+- Read a resume: parse_resume returns contact details, experience, education, languages, skills and the full text in resume.info_resume.text, stored under application_id.
+- Find candidates already in the user's resume database for a job: search_resumes, then score_resumes on the application_ids it returns.
+- Find stored open jobs for a candidate: search_jobs.
+- Normalize skills: normalize_skills maps free-text skills to taxonomy skills, named in French or English.
+
+Resume input:
+- parse_resume reads a local file (file_path, an absolute path), downloads a public file_url, or takes the resume text as resume_text.
+- score_resumes and search_jobs take resume text directly: when you can already read the resume, pass its text instead of parsing it first. For a resume file, parse it with parse_resume and pass the application_id it returns.
 
 Notes:
-- The text HireLayer writes (criteria labels and rationales, match summaries and explanations, ranking rationales) is in French: translate it when you answer the user in another language.
-- info_resume.text can reach 100,000 characters; match_candidate and rank_candidates accept 50,000 characters per resume, so truncate longer texts.
-- Pass do_not_store_data: true to parse_resume when the user does not want HireLayer to keep the file.
-- Every successful tool call costs 1 HireLayer credit. Resume parsing usually takes about 35 seconds.`;
+- Criteria, summaries and explanations are written in the job's language (English, French, German, Spanish or Portuguese; English for any other) unless language says otherwise; evidence quotes the resume in its own language.
+- A job text holds at least 30 characters, and score_resumes needs at least one resume of 30 characters or more.
+- Job and resume texts are accepted up to 50,000 characters each: truncate longer ones. score_resumes takes up to 50 resumes per call.
+- HireLayer keeps the jobs, resumes and scores in the user's account, as the REST API does, unless the workspace runs without storage. A pair already scored is not evaluated again and costs nothing.
+- Pass do_not_store_data: true to parse_resume when the user does not want HireLayer to keep the resume (Enterprise plan). Such a resume gets no application_id: score it by its text.
+- When the user recruits for several client companies, pass the client's workspace id so each client's jobs and candidates stay apart. Reuse the exact id the user gives: a new id creates a new workspace.
+- Credits: parse_resume 1 (0 for a file already stored), extract_job_criteria free (a new text under a job_id already scored re-evaluates its scores, 1 credit each), score_resumes 1 per resume evaluated and 1 more with precise_ranking, search_resumes and search_jobs 1 per search, normalize_skills 1. A parse takes about 30 seconds; scoring 50 resumes about a minute.
+- Scores support human hiring decisions; they never replace them.`;
+// The ids HireLayer accepts for resumes, jobs and workspaces.
+const CLIENT_ID_PATTERN = /^[A-Za-z0-9._:~-]{1,200}$/;
+const CLIENT_ID_RULE = 'letters, digits and . _ : ~ -, up to 200 characters';
+const isClientId = (value) => CLIENT_ID_PATTERN.test(value) && !/^\.\.?$/.test(value);
+const APPLICATION_ID_MESSAGE = `application_id must contain ${CLIENT_ID_RULE}`;
+const WORKSPACE_MESSAGE = `workspace must contain ${CLIENT_ID_RULE}`;
+const JOB_ID_MESSAGE = `job_id must contain ${CLIENT_ID_RULE}`;
+const APPLICATION_ID_RULE = z
+    .string()
+    .regex(CLIENT_ID_PATTERN, APPLICATION_ID_MESSAGE)
+    .refine(isClientId, APPLICATION_ID_MESSAGE);
+const JOB_ID_RULE = z.string().regex(CLIENT_ID_PATTERN, JOB_ID_MESSAGE).refine(isClientId, JOB_ID_MESSAGE);
+// The rule of the HireLayer-Workspace header, which the API also checks before any work.
+const workspaceArg = z
+    .string()
+    .regex(CLIENT_ID_PATTERN, WORKSPACE_MESSAGE)
+    .optional()
+    .describe(`The client company this call belongs to, when the user recruits for several companies: its HireLayer workspace id (${CLIENT_ID_RULE}), e.g. acme-corp. Jobs, resumes and scores stay apart from other clients'. A new id creates a new workspace, so reuse the exact id. Omit it for the user's default workspace.`);
+const languageArg = z
+    .enum(JOB_LANGUAGES)
+    .optional()
+    .describe("Language of the criteria, summaries and explanations: en, fr, de, es or pt. Defaults to the language of the job's text (English when it is another).");
+// The API refuses a job text under 30 characters.
+const jobText = z
+    .string()
+    .trim()
+    .min(30, 'A job text holds at least 30 characters: send the full job description.')
+    .max(50000);
+const resumeText = z.string().min(1).max(50000);
+// The format extract_job_criteria returns; criterion_id and source, sent back, are ignored by the API.
 const criterion = z.object({
-    id: z.string().min(1).describe('Criterion ID, e.g. crit_1 from extract_job_criteria.'),
-    label: z.string().min(1).describe('What is evaluated, in a short phrase.'),
-    weight: z.number().int().min(1).max(3).describe('3 essential, 2 important, 1 nice to have.'),
-    is_mandatory: z.boolean().describe('Whether the job states it as a hard requirement.'),
-    rationale: z.string().min(1).describe('Why the criterion matters for the job.'),
+    label: z.string().min(1).max(300).describe('What is evaluated.'),
+    type: z
+        .enum(['skill', 'experience', 'education', 'language', 'certification', 'location', 'soft_skill', 'other'])
+        .optional(),
+    requirement: z
+        .enum(['required', 'preferred', 'bonus'])
+        .optional()
+        .describe('required: a resume that clearly lacks it loses 25 % of its score. preferred and bonus count through their weight only.'),
+    weight: z.number().int().min(0).max(3).optional().describe('3 essential, 2 important, 1 nice to have, 0 off.'),
+    threshold: z
+        .string()
+        .max(100)
+        .nullable()
+        .optional()
+        .describe('Minimum level in short text, such as 3 years or B2.'),
 });
-// The tools only read and analyse data; they never change anything in the user's systems.
-const readOnly = { readOnlyHint: true, destructiveHint: false, openWorldHint: true };
+// The tools read and analyse the data they receive and call the HireLayer API (open world).
+// Every product but normalize_skills stores what it processes in the user's HireLayer account,
+// as the REST API does, unless the workspace runs without storage: they are not read-only.
+// No tool deletes anything.
+const hints = { destructiveHint: false, idempotentHint: false, openWorldHint: true };
 // Directories (Claude, ChatGPT) read the human-readable name from annotations.title.
-function annotations(title) {
-    return { title, ...readOnly };
+function annotations(title, options = {}) {
+    return { title, readOnlyHint: !options.writes, ...hints };
 }
 export function createServer(client) {
     const server = new McpServer({
@@ -52,77 +106,168 @@ export function createServer(client) {
         }
     };
     server.registerTool('parse_resume', {
-        title: 'Parse a resume',
-        description: 'Parse a resume / CV (PDF, DOC, DOCX, ODT, PPT, PPTX, ODP, XLS, RTF, TXT, JPG, PNG or BMP, under 4.5 MB) into structured JSON: contact details, work experience, education, languages, skills and the full resume text in info_resume.text. Pass a local file_path or a public file_url. Takes about 35 seconds. Costs 1 HireLayer credit.',
+        title: 'Resume Parser',
+        description: "Parse a resume / CV (PDF, DOC, DOCX, ODT, PPT, PPTX, ODP, XLS, RTF, TXT, HTML, Markdown, JPG, PNG or BMP, under 4.5 MB) into structured JSON, in resume: contact details, work experience, education, languages, skills and the full resume text in resume.info_resume.text. Give exactly one input: file_path (a local file), file_url (a public URL) or resume_text. HireLayer keeps the resume in the user's resume database under application_id, unless do_not_store_data is set. Takes about 30 seconds. Costs 1 HireLayer credit, 0 for a file already stored.",
         inputSchema: {
             file_path: z.string().optional().describe('Absolute path of a local resume file.'),
             file_url: z.string().url().optional().describe('Public URL of a resume file to download.'),
-            application_id: z.string().optional().describe('Your own reference, echoed back in the result.'),
+            resume_text: z
+                .string()
+                .min(1)
+                .max(100000)
+                .optional()
+                .describe('Resume as plain text, when no file is available.'),
+            application_id: APPLICATION_ID_RULE.optional().describe(`Your id for this resume, such as the application or candidate id of your ATS (${CLIENT_ID_RULE}). The resume is stored under it, replacing a resume stored under the same id. Omit it when you have no such id: the resume is stored under an id drawn from the file.`),
             do_not_store_data: z
                 .boolean()
                 .optional()
-                .describe('true: HireLayer does not keep the file after parsing.'),
+                .describe('true: HireLayer keeps nothing of this parse and application_id comes back null. Enterprise plan only.'),
+            workspace: workspaceArg,
         },
-        annotations: annotations('Parse a resume'),
-    }, ({ file_path, file_url, application_id, do_not_store_data }, extra) => run(extra, (signal) => client.parseResume({ filePath: file_path, fileUrl: file_url }, { applicationId: application_id, doNotStoreData: do_not_store_data, signal })));
+        annotations: annotations('Resume Parser', { writes: true }),
+    }, ({ file_path, file_url, resume_text, application_id, do_not_store_data, workspace }, extra) => run(extra, (signal) => client.parseResume({ filePath: file_path, fileUrl: file_url, text: resume_text }, { applicationId: application_id, doNotStoreData: do_not_store_data, workspace, signal })));
     server.registerTool('extract_job_criteria', {
-        title: 'Extract job criteria',
-        description: 'Turn a job description (any language) into weighted matching criteria (matching_criteria[]), each with a weight from 1 to 3, a mandatory flag and a rationale (labels and rationales are written in French). Feed the result to match_candidate. Costs 1 HireLayer credit.',
+        title: 'Job Criteria Extractor',
+        description: "Turn a job description (any language, at least 30 characters) into the typed criteria it states (usually 4 to 10, fewer for a short posting), in the posting's order, each with a criterion_id, a label, a type, a requirement (required, preferred or bonus), a weight from 0 to 3 and an optional threshold. They are written in the job's language (English, French, German, Spanish or Portuguese; English for any other) unless language says otherwise. The job is stored under job_id, so score_resumes can reuse it. Free, except a new text sent under the job_id of a job already scored: its scores are evaluated again, 1 credit each.",
         inputSchema: {
-            job_text: z.string().min(1).max(50000).describe('Full job description.'),
+            job_text: jobText.describe('Full job description, as published: at least 30 characters.'),
+            title: z.string().max(300).optional().describe('Job title.'),
+            location: z.string().max(300).optional().describe('Where the job is based.'),
+            language: languageArg,
+            job_id: JOB_ID_RULE.optional().describe(`Your id for this job (${CLIENT_ID_RULE}). Omit it: the job is stored under an id drawn from its text.`),
+            workspace: workspaceArg,
         },
-        annotations: annotations('Extract job criteria'),
-    }, ({ job_text }, extra) => run(extra, (signal) => client.extractJobCriteria(job_text, { signal })));
-    server.registerTool('match_candidate', {
-        title: 'Match a candidate to a job',
-        description: 'Score one candidate against a job: returns a score between 0 and 1, a summary and an explained evaluation of each criterion (written in French). Use the criteria from extract_job_criteria and the resume text from parse_resume (info_resume.text). Costs 1 HireLayer credit.',
+        annotations: annotations('Job Criteria Extractor', { writes: true }),
+    }, ({ job_text, title, location, language, job_id, workspace }, extra) => run(extra, (signal) => client.extractJobCriteria({ text: job_text, title, location, language, job_id }, { workspace, signal })));
+    server.registerTool('score_resumes', {
+        title: 'Resume Scorer',
+        description: "Evaluate 1 to 50 resumes against a job, criterion by criterion, and return them best first: for each, a score between 0 and 1, a verdict (highly_relevant, relevant, marginally_relevant or not_relevant), a summary, the required criteria missing or to verify, and the evidence for each criterion. Give the job as job_text (its criteria are extracted on the way, or pass your own criteria) or as the job_id of a stored job. Give each resume as text or as the application_id of a stored resume; at least one resume of the call holds 30 characters or more. Summaries and explanations are written in the job's language. With precise_ranking, the 10 best are re-ranked against each other, each with a ranking_reason. The result is decision support for a human recruiter, not an automated hiring decision. Costs 1 HireLayer credit per resume evaluated, and 1 more with precise_ranking; a pair already scored costs 0.",
         inputSchema: {
-            job_text: z.string().min(1).max(50000).describe('Job description.'),
-            candidate_text: z.string().min(1).max(50000).describe('Resume as plain text.'),
-            matching_criteria: z
+            job_text: jobText.optional().describe('The job description, at least 30 characters. Give job_text or job_id.'),
+            job_id: JOB_ID_RULE.optional().describe('Alone: a job already stored, such as the job_id extract_job_criteria returned. With job_text: store the job under your own id; a new text or new criteria for a job already scored evaluate its stored scores again, 1 credit each.'),
+            criteria: z
                 .array(criterion)
-                .default([])
-                .describe('Criteria to evaluate, usually from extract_job_criteria.'),
-        },
-        annotations: annotations('Match a candidate to a job'),
-    }, (args, extra) => run(extra, (signal) => client.matchCandidate(args, { signal })));
-    server.registerTool('rank_candidates', {
-        title: 'Rank candidates for a job',
-        description: 'Rank up to 10 candidates against the same job description, from their resume texts: returns each candidate with a rank, a score between 0 and 1 and a rationale (written in French). Costs 1 HireLayer credit per call, whatever the number of candidates.',
-        inputSchema: {
-            job_text: z.string().min(1).max(50000).describe('Job description.'),
-            candidates: z
+                .min(1)
+                .max(20)
+                .optional()
+                .describe("The job's own criteria, in the format extract_job_criteria returns; they replace the extraction. Only with job_text."),
+            language: languageArg.describe("Language of the criteria, summaries and explanations: en, fr, de, es or pt. Only with job_text; defaults to the language of the job's text (English when it is another)."),
+            resumes: z
                 .array(z.object({
-                id: z.string().min(1).describe('Your candidate ID, unique in the request.'),
-                candidate_text: z.string().min(1).max(50000).describe('Resume as plain text.'),
+                text: resumeText.optional().describe('The resume as plain text.'),
+                application_id: APPLICATION_ID_RULE.optional().describe('Alone: a resume already stored, such as the application_id parse_resume returned. With text: store the resume under your own id.'),
+                reference: z.string().max(200).optional().describe('Your label for this resume, returned as is.'),
             }))
                 .min(1)
-                .max(10),
+                .max(50)
+                .describe('The resumes to score. Each needs text or application_id.'),
+            precise_ranking: z
+                .boolean()
+                .optional()
+                .describe('Re-rank the 10 best against each other and explain each place in ranking_reason. 1 credit more for the call.'),
+            workspace: workspaceArg,
         },
-        annotations: annotations('Rank candidates for a job'),
-    }, (args, extra) => run(extra, (signal) => client.rankCandidates(args, { signal })));
-    server.registerTool('resolve_skills', {
-        title: 'Resolve skills',
-        description: 'Map free-text skills in French or English (one skill, a compound string or a whole skills section) to skills of the HireLayer taxonomy, with their IDs, families and domains. Unmatched parts are listed in unresolved. Costs 1 HireLayer credit.',
+        annotations: annotations('Resume Scorer', { writes: true }),
+    }, (args, extra) => run(extra, async (signal) => {
+        const job = scoreJob(args);
+        const resumes = args.resumes.map((resume, index) => {
+            if (resume.text !== undefined) {
+                return { text: resume.text, application_id: resume.application_id, reference: resume.reference };
+            }
+            if (resume.application_id !== undefined) {
+                return { application_id: resume.application_id, reference: resume.reference };
+            }
+            throw new HireLayerError(`resumes[${index}] needs text or application_id.`);
+        });
+        return client.scoreResumes({ job, resumes, precise_ranking: args.precise_ranking }, { workspace: args.workspace, signal });
+    }));
+    server.registerTool('search_resumes', {
+        title: 'Talent Pool Search',
+        description: "Find the resumes of the user's resume database closest to a job, by proximity only: application_ids with a similarity between 0 and 1, best first, and whether each is already scored for the job. No evaluation: pass the ones worth it to score_resumes. Give the job as the job_id of a stored job or as job_text (at least 30 characters; the job is then stored). Costs 1 HireLayer credit per search.",
+        inputSchema: {
+            job_id: JOB_ID_RULE.optional().describe('A stored job. Give job_id or job_text.'),
+            job_text: jobText.optional().describe('A job description not stored yet, at least 30 characters.'),
+            limit: z.number().int().min(1).max(500).optional().describe('How many resumes to return, 50 by default.'),
+            city: z
+                .string()
+                .min(1)
+                .optional()
+                .describe('Keep the resumes located around this city. Resumes without a known location are left out.'),
+            country_code: z
+                .string()
+                .regex(/^[A-Z]{2}$/)
+                .optional()
+                .describe("The city's country, ISO 3166-1 alpha-2 such as FR."),
+            radius_km: z.number().int().min(1).max(500).optional().describe('Around the city, 30 km by default.'),
+            added_after: z
+                .string()
+                .datetime({ offset: true })
+                .optional()
+                .describe('Keep the resumes added after this date (ISO 8601).'),
+            workspace: workspaceArg,
+        },
+        annotations: annotations('Talent Pool Search', { writes: true }),
+    }, (args, extra) => run(extra, async (signal) => {
+        if ((args.job_id === undefined) === (args.job_text === undefined)) {
+            throw new HireLayerError('Give exactly one of job_id or job_text.');
+        }
+        if (args.city === undefined && args.radius_km !== undefined) {
+            throw new HireLayerError('radius_km needs city.');
+        }
+        const location = args.city === undefined
+            ? undefined
+            : { city: args.city, country_code: args.country_code, radius_km: args.radius_km };
+        const filters = location || args.added_after ? { location, added_after: args.added_after } : undefined;
+        return client.searchResumes({
+            job_id: args.job_id,
+            job: args.job_text === undefined ? undefined : { text: args.job_text },
+            limit: args.limit,
+            filters,
+        }, { workspace: args.workspace, signal });
+    }));
+    server.registerTool('search_jobs', {
+        title: 'Job Recommendations',
+        description: "Find the user's stored open jobs closest to a resume, by proximity only: job_ids with their title and a similarity between 0 and 1, best first, and whether the resume is already scored for each. No evaluation: score the ones worth it with score_resumes. Give the resume as the application_id of a stored resume or as resume_text (the resume is then stored). Costs 1 HireLayer credit per search.",
+        inputSchema: {
+            application_id: APPLICATION_ID_RULE.optional().describe('A stored resume. Give application_id or resume_text.'),
+            resume_text: resumeText.optional().describe('A resume not stored yet, as plain text.'),
+            limit: z.number().int().min(1).max(100).optional().describe('How many jobs to return, 10 by default.'),
+            workspace: workspaceArg,
+        },
+        annotations: annotations('Job Recommendations', { writes: true }),
+    }, (args, extra) => run(extra, async (signal) => {
+        if ((args.application_id === undefined) === (args.resume_text === undefined)) {
+            throw new HireLayerError('Give exactly one of application_id or resume_text.');
+        }
+        return client.searchJobs({
+            application_id: args.application_id,
+            resume: args.resume_text === undefined ? undefined : { text: args.resume_text },
+            limit: args.limit,
+        }, { workspace: args.workspace, signal });
+    }));
+    server.registerTool('normalize_skills', {
+        title: 'Skills Normalizer',
+        description: 'Map free-text skills (one skill, a compound string or a whole skills section) to skills of the HireLayer taxonomy, with their IDs, families and domains, named in French or English. Unmatched parts are listed in unresolved. Costs 1 HireLayer credit.',
         inputSchema: {
             text: z.string().min(1).max(5000).describe('Free text containing one or more skills.'),
             language: z.enum(['fr', 'en']).optional().describe('Language of the labels returned: fr (default) or en.'),
         },
-        annotations: annotations('Resolve skills'),
-    }, ({ text, language }, extra) => run(extra, (signal) => client.resolveSkills(text, language, { signal })));
+        annotations: annotations('Skills Normalizer'),
+    }, ({ text, language }, extra) => run(extra, (signal) => client.normalizeSkills(text, language, { signal })));
     server.registerPrompt('screen_candidates', {
         title: 'Screen candidates for a job',
-        description: 'Parse resumes, score each candidate against a job description and build a shortlist.',
+        description: 'Score each candidate against a job description and build a shortlist.',
         argsSchema: {
             job_description: z.string().describe('The job description, or the path of a file that contains it.'),
-            resumes: z.string().describe('Resume file paths or URLs, one per line, or a folder that holds them.'),
+            resumes: z
+                .string()
+                .describe('Resume file paths or URLs, one per line, a folder that holds them, or resume texts separated by ---.'),
         },
     }, ({ job_description, resumes }) => userPrompt(`Screen these candidates for the job below with the HireLayer tools.
 
-1. Call extract_job_criteria on the job description.
-2. Call parse_resume on each resume.
-3. Call match_candidate for each candidate with the criteria and info_resume.text.
-4. Present a shortlist table sorted by score: candidate, score, mandatory criteria met, main gaps. Then recommend who to interview and why.
+1. For each resume given as a file path or URL, call parse_resume and keep its application_id; use resume texts as they are.
+2. Call score_resumes once, with the job description as job_text, every resume (text or application_id) and precise_ranking set to true.
+3. Present a shortlist table in the order returned: candidate, score, verdict, required criteria missing, main gaps. Then recommend who to interview and why.
 
 Job description:
 ${job_description}
@@ -133,22 +278,39 @@ ${resumes}`));
         title: 'Summarize a resume',
         description: 'Parse one resume and write a short recruiter-style candidate summary.',
         argsSchema: {
-            resume: z.string().describe('Path or URL of the resume file.'),
+            resume: z.string().describe('Path or URL of the resume file, or the resume text.'),
         },
-    }, ({ resume }) => userPrompt(`Parse this resume with parse_resume, then write a recruiter summary: current role, years of experience, key skills, education, languages, location and availability. Flag missing contact details.
+    }, ({ resume }) => userPrompt(`Parse this resume with parse_resume (file_path for a local file, file_url for a URL, resume_text for text), then write a recruiter summary: current role, years of experience, key skills, education, languages, location and availability. Flag missing contact details.
 
 Resume: ${resume}`));
-    server.registerPrompt('normalize_skills', {
+    server.registerPrompt('normalize_skills_list', {
         title: 'Normalize a skills list',
         description: 'Map a free-text skills section to standard taxonomy skills.',
         argsSchema: {
             skills: z.string().describe('Free-text skills, e.g. a resume skills section.'),
         },
-    }, ({ skills }) => userPrompt(`Call resolve_skills on the text below (language en), then list the normalized skills grouped by domain and the parts that could not be resolved.
+    }, ({ skills }) => userPrompt(`Call normalize_skills on the text below (language en), then list the normalized skills grouped by domain and the parts that could not be resolved.
 
 ${skills}`));
     return server;
 }
+/** The job of score_resumes: its text (with criteria) or a stored job_id. */
+function scoreJob(args) {
+    if (args.job_text !== undefined) {
+        return { text: args.job_text, job_id: args.job_id, criteria: args.criteria, language: args.language };
+    }
+    if (args.criteria !== undefined) {
+        throw new HireLayerError('criteria go with job_text, never alone.');
+    }
+    // The API refuses it next to a job_id alone: a stored job keeps its language.
+    if (args.language !== undefined) {
+        throw new HireLayerError('language goes with job_text: a stored job keeps its own language.');
+    }
+    if (args.job_id === undefined) {
+        throw new HireLayerError('Give job_text or job_id.');
+    }
+    return { job_id: args.job_id };
+}
 function userPrompt(text) {
     return { messages: [{ role: 'user', content: { type: 'text', text } }] };
 }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "hirelayer-mcp",
-  "version": "1.1.1",
+  "version": "2.1.0",
   "mcpName": "co.hirelayer/hirelayer",
-  "description": "Official HireLayer MCP server: resume and CV parsing, job criteria extraction, candidate matching and ranking, and skills normalization for AI agents in Claude, Cursor, VS Code and other MCP clients.",
+  "description": "Official HireLayer MCP server: resume and CV parsing, job criteria extraction, resume scoring and ranking, talent pool search, job recommendations and skills normalization for AI agents in Claude, Cursor, VS Code and other MCP clients.",
   "type": "module",
   "bin": {
     "hirelayer-mcp": "dist/index.js"
@@ -28,6 +28,9 @@
     "resume-parsing",
     "candidate-matching",
     "candidate-ranking",
+    "resume-scoring",
+    "talent-search",
+    "job-recommendations",
     "job-matching",
     "resume-screening",
     "recruiting",