hirelayer-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Louis Desclous
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,354 @@
+<div align="center">
+
+<a href="https://hirelayer.co"><img src="assets/logo.svg" alt="HireLayer logo" width="72" height="72"></a>
+
+# HireLayer MCP Server
+
+**Resume parsing, candidate matching and candidate ranking 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, Cursor, VS Code, Codex or any MCP client.
+
+[![npm version](https://img.shields.io/npm/v/hirelayer-mcp?color=4f46e5)](https://www.npmjs.com/package/hirelayer-mcp)
+[![CI](https://github.com/hirelayer/hirelayer-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/hirelayer/hirelayer-mcp/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![MCP](https://img.shields.io/badge/MCP-compatible-4f46e5)](https://modelcontextprotocol.io)
+
+[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=hirelayer&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImhpcmVsYXllci1tY3AiXSwiZW52Ijp7IkhJUkVMQVlFUl9BUElfS0VZIjoieW91ci1hcGkta2V5In19)
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_server-0098FF?logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=hirelayer&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22hirelayer_api_key%22%2C%22description%22%3A%22HireLayer%20API%20key%20%28free%20at%20hirelayer.co%29%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22hirelayer-mcp%22%5D%2C%22env%22%3A%7B%22HIRELAYER_API_KEY%22%3A%22%24%7Binput%3Ahirelayer_api_key%7D%22%7D%7D)
+[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_server-24bfa5?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=hirelayer&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22hirelayer_api_key%22%2C%22description%22%3A%22HireLayer%20API%20key%20%28free%20at%20hirelayer.co%29%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22hirelayer-mcp%22%5D%2C%22env%22%3A%7B%22HIRELAYER_API_KEY%22%3A%22%24%7Binput%3Ahirelayer_api_key%7D%22%7D%7D&quality=insiders)
+[![Add to LM Studio](https://files.lmstudio.ai/deeplink/mcp-install-light.svg)](https://lmstudio.ai/install-mcp?name=hirelayer&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImhpcmVsYXllci1tY3AiXSwiZW52Ijp7IkhJUkVMQVlFUl9BUElfS0VZIjoieW91ci1hcGkta2V5In19)
+
+</div>
+
+> "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.
+
+## Contents
+
+- [What you can do](#what-you-can-do)
+- [Quick start](#quick-start)
+- [Install in your MCP client](#install-in-your-mcp-client)
+- [Tools](#tools)
+- [Example prompts](#example-prompts)
+- [Pricing and credits](#pricing-and-credits)
+- [Data and privacy](#data-and-privacy)
+- [Troubleshooting](#troubleshooting)
+- [FAQ](#faq)
+
+## 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.
+
+Use it to screen applicants in a chat, build a recruiting agent, enrich an ATS, or prototype HR tech features without writing integration code.
+
+## Quick start
+
+1. **Get a free API key.** [Sign up at hirelayer.co](https://hirelayer.co/auth/signup), with no card required, and copy your key from **Dashboard → API keys**. The free plan includes 50 credits a month.
+2. **Add the server to your client.** Click a one-click install button above, or copy a config from [the next section](#install-in-your-mcp-client).
+3. **Ask your assistant.** For example: *"Parse ~/Downloads/resume.pdf and summarize the candidate."*
+
+To try it without your own data, use the sample job and resumes in [`examples/`](examples).
+
+Requires Node.js 20 or later, because the server runs with `npx`.
+
+## Install in your MCP client
+
+Replace `your-api-key` with your HireLayer API key in each config below.
+
+<details open>
+<summary><b>Claude Code</b></summary>
+
+```bash
+claude mcp add hirelayer --env HIRELAYER_API_KEY=your-api-key -- npx -y hirelayer-mcp
+```
+
+</details>
+
+<details>
+<summary><b>Claude Desktop</b></summary>
+
+Open **Settings → Developer → Edit Config** and add the server to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "hirelayer": {
+      "command": "npx",
+      "args": ["-y", "hirelayer-mcp"],
+      "env": { "HIRELAYER_API_KEY": "your-api-key" }
+    }
+  }
+}
+```
+
+Restart Claude Desktop.
+
+</details>
+
+<details>
+<summary><b>Cursor</b></summary>
+
+Click **Install in Cursor** above, or add this to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):
+
+```json
+{
+  "mcpServers": {
+    "hirelayer": {
+      "command": "npx",
+      "args": ["-y", "hirelayer-mcp"],
+      "env": { "HIRELAYER_API_KEY": "your-api-key" }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>VS Code (GitHub Copilot)</b></summary>
+
+Click **Install in VS Code** above. VS Code asks for your API key and stores it securely. To configure it by hand, add this to `.vscode/mcp.json`:
+
+```json
+{
+  "inputs": [
+    { "type": "promptString", "id": "hirelayer_api_key", "description": "HireLayer API key", "password": true }
+  ],
+  "servers": {
+    "hirelayer": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "hirelayer-mcp"],
+      "env": { "HIRELAYER_API_KEY": "${input:hirelayer_api_key}" }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>Windsurf</b></summary>
+
+Add this to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "hirelayer": {
+      "command": "npx",
+      "args": ["-y", "hirelayer-mcp"],
+      "env": { "HIRELAYER_API_KEY": "your-api-key" }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>OpenAI Codex CLI</b></summary>
+
+```bash
+codex mcp add hirelayer --env HIRELAYER_API_KEY=your-api-key -- npx -y hirelayer-mcp
+```
+
+</details>
+
+<details>
+<summary><b>Gemini CLI</b></summary>
+
+```bash
+gemini mcp add -e HIRELAYER_API_KEY=your-api-key hirelayer npx -y hirelayer-mcp
+```
+
+</details>
+
+<details>
+<summary><b>Cline, Roo Code, Zed, LM Studio and other clients</b></summary>
+
+Any client that runs stdio MCP servers works with this command and environment variable:
+
+- Command: `npx -y hirelayer-mcp`
+- Environment: `HIRELAYER_API_KEY=your-api-key`
+
+Cline users can also ask Cline to install the server: [`llms-install.md`](llms-install.md) has the steps.
+
+</details>
+
+<details>
+<summary><b>Docker</b></summary>
+
+```bash
+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`.
+
+</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 |
+
+All tools only read and analyse data. They never change anything in your systems.
+
+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 |
+| `summarize_resume` | Parses one resume and writes a recruiter summary |
+| `normalize_skills` | Normalizes a skills section and groups it by domain |
+
+### How screening works
+
+```mermaid
+flowchart LR
+    J[Job description] --> C[extract_job_criteria]
+    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
+```
+
+<details>
+<summary><b>Example output from <code>match_candidate</code></b></summary>
+
+```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": [
+    {
+      "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."
+    }
+  ]
+}
+```
+
+Criteria labels, rationales, summaries and explanations are written in French. Your assistant translates them when it answers you in another language.
+
+</details>
+
+## Example prompts
+
+**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."
+- "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?"
+
+**Developers and HR tech teams**
+
+- "Parse this resume and map the result to our ATS candidate schema: `{ name, email, current_title, skills[] }`."
+- "Normalize this skills section: Pack Office (Word, Excel), React.js, anglais courant, gestion de projet."
+- "Write a TypeScript function that sends a resume to the HireLayer API, using the JSON this tool returned as the expected type."
+
+**Try it now with the sample files**
+
+- "Screen the resumes in `examples/` against `examples/job-senior-react-developer.md`."
+
+## 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.
+
+| 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) |
+
+## Data and privacy
+
+- The 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.
+- 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.
+
+## Configuration
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `HIRELAYER_API_KEY` | Yes | | Your HireLayer API key |
+| `HIRELAYER_BASE_URL` | No | `https://hirelayer.co` | API base URL, for testing |
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `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. |
+| `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`. |
+
+To debug, run the server in the MCP Inspector:
+
+```bash
+HIRELAYER_API_KEY=your-api-key npx @modelcontextprotocol/inspector npx -y hirelayer-mcp
+```
+
+## 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).
+
+**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.
+
+**Which resume languages are supported?**
+The parser detects the main language of each resume and returns it in `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.
+
+**Is there a hosted remote server?**
+A hosted server with one-click sign-in (OAuth) is on the way. For now, the server runs locally with `npx`.
+
+## Development
+
+```bash
+git clone https://github.com/hirelayer/hirelayer-mcp.git
+cd hirelayer-mcp
+npm install
+npm test
+HIRELAYER_API_KEY=your-api-key npx @modelcontextprotocol/inspector node dist/index.js
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Report bugs in [GitHub issues](https://github.com/hirelayer/hirelayer-mcp/issues) and vulnerabilities as described in [SECURITY.md](SECURITY.md).
+
+## Links
+
+- Website: [hirelayer.co](https://hirelayer.co)
+- API reference: [hirelayer.co/api-docs](https://hirelayer.co/api-docs)
+- OpenAPI: [hirelayer.co/openapi.json](https://hirelayer.co/openapi.json)
+- Docs for agents: [hirelayer.co/llms.txt](https://hirelayer.co/llms.txt)
+- Contact: [contact@hirelayer.co](mailto:contact@hirelayer.co)
+
+## License
+
+[MIT](LICENSE)

package/dist/client.js

@@ -0,0 +1,139 @@
+import { readFile } from 'node:fs/promises';
+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';
+// 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;
+export class HireLayerError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = 'HireLayerError';
+    }
+}
+export class HireLayerClient {
+    apiKey;
+    baseUrl;
+    fetch;
+    retryDelayMs;
+    constructor({ apiKey, baseUrl, fetch: fetchImpl, retryDelayMs }) {
+        this.apiKey = apiKey;
+        this.baseUrl = (baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, '');
+        this.fetch = fetchImpl ?? globalThis.fetch;
+        this.retryDelayMs = retryDelayMs ?? 2_000;
+    }
+    async parseResume(source, options = {}) {
+        const { bytes, filename } = await this.loadResume(source, options.signal);
+        const form = new FormData();
+        form.append('file', new Blob([bytes]), 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 });
+    }
+    extractJobCriteria(jobText, options = {}) {
+        return this.postJson('/api/v1/jobs/extract-criteria', { job_text: jobText }, options);
+    }
+    matchCandidate(body, options = {}) {
+        return this.postJson('/api/v1/matching/job-candidate', body, options);
+    }
+    rankCandidates(body, options = {}) {
+        return this.postJson('/api/v1/matching/job-candidates/rank', body, options);
+    }
+    resolveSkills(text, language, options = {}) {
+        return this.postJson('/api/v1/skills/resolve', language ? { text, language } : { text }, options);
+    }
+    postJson(path, body, { signal }) {
+        return this.request(path, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+            signal,
+        });
+    }
+    async request(path, init, attempt = 1) {
+        const response = await this.fetch(`${this.baseUrl}${path}`, {
+            ...init,
+            headers: {
+                ...init.headers,
+                'X-API-Key': this.apiKey,
+                'User-Agent': `hirelayer-mcp/${VERSION}`,
+            },
+        });
+        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);
+        }
+        const text = await response.text();
+        let payload = text;
+        try {
+            payload = JSON.parse(text);
+        }
+        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);
+        }
+        return payload;
+    }
+    retryDelay(retryAfter) {
+        const seconds = Number(retryAfter);
+        if (retryAfter && Number.isFinite(seconds) && seconds >= 0) {
+            return Math.min(seconds * 1000, MAX_RETRY_DELAY_MS);
+        }
+        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.');
+        }
+        let bytes;
+        let filename;
+        if (filePath) {
+            bytes = new Uint8Array(await readFile(filePath));
+            filename = basename(filePath);
+        }
+        else {
+            const response = await this.fetch(fileUrl, { signal });
+            if (!response.ok) {
+                throw new HireLayerError(`Could not download ${fileUrl}: HTTP ${response.status}`);
+            }
+            bytes = new Uint8Array(await response.arrayBuffer());
+            filename = basename(new URL(fileUrl).pathname) || 'resume';
+        }
+        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 };
+    }
+}
+function errorHint(status, 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.';
+    }
+    return '';
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(signal.reason);
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener('abort', () => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        }, { once: true });
+    });
+}

package/dist/index.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { HireLayerClient, VERSION } from './client.js';
+import { createServer } from './server.js';
+if (process.argv.includes('--version')) {
+    console.log(VERSION);
+    process.exit(0);
+}
+const apiKey = process.env.HIRELAYER_API_KEY;
+if (!apiKey) {
+    console.error('HIRELAYER_API_KEY is not set. Create a free key (50 credits a month) at https://hirelayer.co and pass it in the server env.');
+    process.exit(1);
+}
+const server = createServer(new HireLayerClient({ apiKey, baseUrl: process.env.HIRELAYER_BASE_URL }));
+await server.connect(new StdioServerTransport());

package/dist/server.js

@@ -0,0 +1,166 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { 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.
+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.
+
+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.
+
+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.`;
+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.'),
+});
+// The tools only read and analyse data; they never change anything in the user's systems.
+const annotations = { readOnlyHint: true, destructiveHint: false, openWorldHint: true };
+export function createServer(client) {
+    const server = new McpServer({
+        name: 'hirelayer',
+        title: 'HireLayer',
+        version: VERSION,
+        websiteUrl: 'https://hirelayer.co',
+        icons: [{ src: 'https://hirelayer.co/favicon/android-chrome-512x512.png', mimeType: 'image/png', sizes: ['512x512'] }],
+    }, { instructions: INSTRUCTIONS });
+    const run = async (extra, call) => {
+        const stopProgress = reportProgress(extra);
+        try {
+            const result = await call(extra.signal);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: message }], isError: true };
+        }
+        finally {
+            stopProgress();
+        }
+    };
+    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.',
+        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.'),
+            do_not_store_data: z
+                .boolean()
+                .optional()
+                .describe('true: HireLayer does not keep the file after parsing.'),
+        },
+        annotations,
+    }, ({ 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 })));
+    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.',
+        inputSchema: {
+            job_text: z.string().min(1).max(50000).describe('Full job description.'),
+        },
+        annotations,
+    }, ({ 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.',
+        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
+                .array(criterion)
+                .default([])
+                .describe('Criteria to evaluate, usually from extract_job_criteria.'),
+        },
+        annotations,
+    }, (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
+                .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.'),
+            }))
+                .min(1)
+                .max(10),
+        },
+        annotations,
+    }, (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.',
+        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,
+    }, ({ text, language }, extra) => run(extra, (signal) => client.resolveSkills(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.',
+        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.'),
+        },
+    }, ({ 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.
+
+Job description:
+${job_description}
+
+Resumes:
+${resumes}`));
+    server.registerPrompt('summarize_resume', {
+        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 }) => 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: ${resume}`));
+    server.registerPrompt('normalize_skills', {
+        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}`));
+    return server;
+}
+function userPrompt(text) {
+    return { messages: [{ role: 'user', content: { type: 'text', text } }] };
+}
+function reportProgress(extra) {
+    const progressToken = extra._meta?.progressToken;
+    if (progressToken === undefined)
+        return () => { };
+    let progress = 0;
+    const timer = setInterval(() => {
+        progress += 1;
+        extra
+            .sendNotification({
+            method: 'notifications/progress',
+            params: { progressToken, progress, message: 'Waiting for HireLayer…' },
+        })
+            .catch(() => { });
+    }, PROGRESS_INTERVAL_MS);
+    return () => clearInterval(timer);
+}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "hirelayer-mcp",
+  "version": "1.0.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.",
+  "type": "module",
+  "bin": {
+    "hirelayer-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "inspect": "npm run build && npx @modelcontextprotocol/inspector node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "hirelayer",
+    "resume-parser",
+    "cv-parser",
+    "resume-parsing",
+    "candidate-matching",
+    "candidate-ranking",
+    "job-matching",
+    "resume-screening",
+    "recruiting",
+    "recruitment",
+    "ats",
+    "hr-tech",
+    "hiring",
+    "talent-acquisition",
+    "ai-agents",
+    "claude",
+    "cursor"
+  ],
+  "homepage": "https://github.com/hirelayer/hirelayer-mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hirelayer/hirelayer-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/hirelayer/hirelayer-mcp/issues"
+  },
+  "author": "HireLayer <contact@hirelayer.co> (https://hirelayer.co)",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "typescript": "^5.9.3"
+  }
+}