@opthr/mcp-server 0.2.0

package/README.md

@@ -0,0 +1,79 @@
+# @opthr/mcp-server
+
+Model Context Protocol server for **OptHR** — exposes the Skill Gap and Compensation agents to MCP-aware clients (Claude Desktop, Cursor, etc.) so you can run HR analyses directly from a chat.
+
+This is a thin Node.js wrapper around the OptHR FastAPI backend (`http://localhost:8765` by default). All tools are real — no mocks.
+
+## Tools exposed
+
+| Tool | What it does |
+|---|---|
+| `opthr_health` | Check the backend is reachable, see which Claude model is wired |
+| `opthr_list_jobs` | Recent analyses for the tenant |
+| `opthr_get_job` | Full job record — state, outputs, last event |
+| `opthr_run_skill_gap` | Start a new Skill Gap analysis (auto-attaches the sample profile) |
+| `opthr_run_compensation` | Start a new Compensation analysis vs P25/P50/P75/P90 |
+| `opthr_answer` | Reply to a paused job (clarification or follow-up) |
+| `opthr_export` | Download report (PDF) or data (XLSX/JSON) as base64 |
+
+## Install + run locally
+
+Requires Node 18+.
+
+```bash
+cd mcp-server
+npm install
+npm test          # smoke-tests the OptHR backend connection
+npm start         # boots the MCP server on stdio
+```
+
+## Wire it into Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "opthr": {
+      "command": "node",
+      "args": ["/Users/YOU/Desktop/HR_startup/mcp-server/src/index.js"],
+      "env": {
+        "OPTHR_API_BASE": "http://localhost:8765",
+        "OPTHR_DEV_ROLE": "admin_hr",
+        "OPTHR_DEV_TENANT_ID": "tenant_demo"
+      }
+    }
+  }
+}
+```
+
+After publishing to npm, replace `command/args` with:
+
+```json
+"command": "npx",
+"args": ["-y", "@opthr/mcp-server@latest"]
+```
+
+Then restart Claude Desktop and try:
+
+> "Run a skill gap analysis for a Senior Backend Engineer role using the OptHR sample data."
+
+Claude will call `opthr_run_skill_gap`, poll `opthr_get_job` until the state is `review_required`, and summarise the matrix + recommended courses for you.
+
+## Environment variables
+
+| Var | Default | What |
+|---|---|---|
+| `OPTHR_API_BASE` | `http://localhost:8765` | Where the FastAPI backend lives |
+| `OPTHR_API_KEY` | — | Sent as `X-API-Key` if set |
+| `OPTHR_BEARER_TOKEN` | — | Sent as `Authorization: Bearer …` if set |
+| `OPTHR_DEV_ROLE` | `admin_hr` | Dev fallback `X-Role` header (used when no Bearer token) |
+| `OPTHR_DEV_TENANT_ID` | `tenant_demo` | Dev fallback `X-Tenant-ID` |
+
+## How it differs from the prototype `api.js`
+
+The browser prototype's `api.js` and this MCP server hit the **exact same endpoints** — there is no separate "MCP backend". The prototype uses cookies/dev headers; this server uses env-supplied auth. Adding new tools is a 10-line patch in `src/index.js` (definition + handler).
+
+## License
+
+MIT

package/assets/opthr-logo.svg

@@ -0,0 +1,29 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="512" height="512" viewBox="0 0 80 80" role="img" aria-label="optHR">
+  <title>optHR</title>
+  <desc>Figure surfing through the middle of an ascending bar chart on a coral-to-teal arrow.</desc>
+  <defs>
+    <linearGradient id="bars" x1="0" y1="1" x2="0" y2="0">
+      <stop offset="0" stop-color="#FF8A5B"/>
+      <stop offset="1" stop-color="#FF6B6B"/>
+    </linearGradient>
+    <linearGradient id="wave" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#FF6B6B"/>
+      <stop offset="1" stop-color="#1A535C"/>
+    </linearGradient>
+  </defs>
+  <rect x="6"  y="56" width="12" height="18" rx="2.5" fill="url(#bars)" opacity="0.55"/>
+  <rect x="22" y="46" width="12" height="28" rx="2.5" fill="url(#bars)" opacity="0.7"/>
+  <rect x="38" y="32" width="12" height="42" rx="2.5" fill="url(#bars)" opacity="0.85"/>
+  <rect x="54" y="18" width="12" height="56" rx="2.5" fill="url(#bars)"/>
+  <path d="M4 64 Q 22 50, 38 38 T 76 8" stroke="url(#wave)" stroke-width="6" stroke-linecap="round" fill="none"/>
+  <path d="M76 8 L66 8 M76 8 L76 18" stroke="#1A535C" stroke-width="5" stroke-linecap="round" fill="none"/>
+  <g transform="translate(34 30) rotate(-32)">
+    <ellipse cx="0" cy="14" rx="16" ry="2.2" fill="#1A535C"/>
+    <path d="M-3 13 L -5 8" stroke="#1A535C" stroke-width="2.6" stroke-linecap="round"/>
+    <path d="M3 13 L 5 7" stroke="#1A535C" stroke-width="2.6" stroke-linecap="round"/>
+    <path d="M-3 7 C -4 4, -2 0, 1 -1 L4 1 C 5 5, 3 8, 0 8 Z" fill="#1A535C"/>
+    <path d="M-2 3 L -9 5" stroke="#1A535C" stroke-width="2.4" stroke-linecap="round"/>
+    <path d="M3 1 L 10 -2" stroke="#1A535C" stroke-width="2.4" stroke-linecap="round"/>
+    <circle cx="3" cy="-4" r="3.8" fill="#1A535C"/>
+  </g>
+</svg>

package/assets/opthr-wordmark.svg

@@ -0,0 +1,33 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="480" height="180" viewBox="0 0 240 90" role="img" aria-label="optHR">
+  <title>optHR</title>
+  <desc>Figure surfing through the middle of an ascending bar chart on a coral-to-teal arrow, with optHR wordmark.</desc>
+  <defs>
+    <linearGradient id="bars" x1="0" y1="1" x2="0" y2="0">
+      <stop offset="0" stop-color="#FF8A5B"/>
+      <stop offset="1" stop-color="#FF6B6B"/>
+    </linearGradient>
+    <linearGradient id="wave" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#FF6B6B"/>
+      <stop offset="1" stop-color="#1A535C"/>
+    </linearGradient>
+  </defs>
+  <rect x="6"  y="60" width="11" height="20" rx="2.5" fill="url(#bars)" opacity="0.55"/>
+  <rect x="20" y="50" width="11" height="30" rx="2.5" fill="url(#bars)" opacity="0.7"/>
+  <rect x="34" y="38" width="11" height="42" rx="2.5" fill="url(#bars)" opacity="0.85"/>
+  <rect x="48" y="24" width="11" height="56" rx="2.5" fill="url(#bars)"/>
+  <path d="M4 70 Q 18 56, 32 44 T 70 14" stroke="url(#wave)" stroke-width="5" stroke-linecap="round" fill="none"/>
+  <path d="M70 14 L60 14 M70 14 L70 24" stroke="#1A535C" stroke-width="4" stroke-linecap="round" fill="none"/>
+  <g transform="translate(28 32) rotate(-32)">
+    <ellipse cx="0" cy="13" rx="14" ry="2" fill="#1A535C"/>
+    <path d="M-3 12 L -5 8" stroke="#1A535C" stroke-width="2.4" stroke-linecap="round"/>
+    <path d="M3 12 L 5 7" stroke="#1A535C" stroke-width="2.4" stroke-linecap="round"/>
+    <path d="M-3 7 C -4 4, -2 0, 1 -1 L4 1 C 5 5, 3 8, 0 8 Z" fill="#1A535C"/>
+    <path d="M-2 3 L -8 5" stroke="#1A535C" stroke-width="2.2" stroke-linecap="round"/>
+    <path d="M3 1 L 9 -2" stroke="#1A535C" stroke-width="2.2" stroke-linecap="round"/>
+    <circle cx="3" cy="-4" r="3.4" fill="#1A535C"/>
+  </g>
+  <g font-family="Inter Tight, Inter, system-ui, sans-serif" font-weight="800" font-size="44" letter-spacing="-1.5">
+    <text x="86" y="60" fill="#1A535C">opt</text>
+    <text x="158" y="60" fill="#FF6B6B">HR</text>
+  </g>
+</svg>

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@opthr/mcp-server",
+  "version": "0.2.0",
+  "description": "Model Context Protocol server for OptHR — exposes Skill Gap and Compensation agents to Claude Desktop, Cursor, and other MCP clients.",
+  "type": "module",
+  "bin": {
+    "opthr-mcp-server": "src/index.js"
+  },
+  "icon": "assets/opthr-logo.svg",
+  "files": [
+    "src",
+    "assets",
+    "README.md"
+  ],
+  "main": "src/index.js",
+  "scripts": {
+    "start": "node src/index.js",
+    "dev": "node src/index.js",
+    "test": "node test/smoke.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "hr",
+    "opthr",
+    "compensation",
+    "skill-gap",
+    "anthropic"
+  ],
+  "author": "OptHR",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/index.js

@@ -0,0 +1,463 @@
+#!/usr/bin/env node
+/**
+ * @opthr/mcp-server — Model Context Protocol bridge for OptHR.
+ *
+ * This is the SAME OptHR backend (FastAPI at OPTHR_API_BASE) that the
+ * web prototype talks to, exposed as MCP tools so Claude Desktop, Cursor
+ * and other MCP clients can run skill-gap and compensation analyses
+ * without leaving the chat.
+ *
+ * Tools exposed:
+ *   - opthr_health             → check the backend is reachable
+ *   - opthr_list_jobs          → recent analyses for the tenant
+ *   - opthr_get_job            → fetch one job (state, outputs, events)
+ *   - opthr_run_skill_gap      → start a new skill-gap analysis
+ *   - opthr_run_compensation   → start a new compensation analysis
+ *   - opthr_answer             → respond to a paused-clarification
+ *   - opthr_export             → download report (PDF) / data (XLSX|JSON)
+ *
+ * Auth comes from environment:
+ *   OPTHR_API_BASE      — FastAPI base URL (default http://localhost:8765)
+ *   OPTHR_API_KEY       — optional X-API-Key
+ *   OPTHR_BEARER_TOKEN  — optional Bearer token
+ *   OPTHR_DEV_ROLE      — fallback X-Role header   (default admin_hr)
+ *   OPTHR_DEV_TENANT_ID — fallback X-Tenant-ID     (default tenant_demo)
+ *
+ * Usage in Claude Desktop's claude_desktop_config.json:
+ *
+ *   {
+ *     "mcpServers": {
+ *       "opthr": {
+ *         "command": "npx",
+ *         "args": ["-y", "@opthr/mcp-server"],
+ *         "env": {
+ *           "OPTHR_API_BASE": "http://localhost:8765",
+ *           "OPTHR_DEV_ROLE": "admin_hr",
+ *           "OPTHR_DEV_TENANT_ID": "tenant_demo"
+ *         }
+ *       }
+ *     }
+ *   }
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const BASE = (process.env.OPTHR_API_BASE || "http://localhost:8765").replace(/\/$/, "");
+const API_KEY = process.env.OPTHR_API_KEY || "";
+const BEARER = process.env.OPTHR_BEARER_TOKEN || "";
+const DEV_ROLE = process.env.OPTHR_DEV_ROLE || "admin_hr";
+const DEV_TENANT = process.env.OPTHR_DEV_TENANT_ID || "tenant_demo";
+
+/* ----------------------------------------------------------------- */
+/* Branding — load OptHR logo and expose it via the MCP icons field  */
+/* (supported by clients on MCP spec 2025-06-18+, e.g. Claude Desktop */
+/* 1.x). Falls back silently if the asset is missing.                 */
+/* ----------------------------------------------------------------- */
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const LOGO_PATH = join(__dirname, "..", "assets", "opthr-logo.svg");
+
+function loadOptHRIcon() {
+  try {
+    const svg = readFileSync(LOGO_PATH, "utf8");
+    const dataUri = "data:image/svg+xml;base64," + Buffer.from(svg, "utf8").toString("base64");
+    return [{ src: dataUri, mimeType: "image/svg+xml", sizes: ["any"] }];
+  } catch {
+    return undefined;
+  }
+}
+
+const OPTHR_ICONS = loadOptHRIcon();
+
+/* ----------------------------------------------------------------- */
+/* HTTP helpers                                                       */
+/* ----------------------------------------------------------------- */
+
+async function request(path, opts = {}) {
+  const url = path.startsWith("http") ? path : BASE + path;
+  const headers = { ...(opts.headers || {}) };
+
+  // Body handling: pass FormData/Blob/Buffer through untouched (fetch sets the
+  // correct multipart boundary). Stringify plain objects as JSON. Leave string
+  // bodies alone.
+  let body = opts.body;
+  const isFormData = typeof FormData !== "undefined" && body instanceof FormData;
+  const isBinary =
+    body instanceof ArrayBuffer ||
+    ArrayBuffer.isView(body) ||
+    (typeof Blob !== "undefined" && body instanceof Blob) ||
+    (typeof ReadableStream !== "undefined" && body instanceof ReadableStream);
+  if (body && !isFormData && !isBinary && typeof body !== "string") {
+    body = JSON.stringify(body);
+    if (!headers["Content-Type"]) headers["Content-Type"] = "application/json";
+  } else if (typeof body === "string" && !headers["Content-Type"]) {
+    headers["Content-Type"] = "application/json";
+  }
+  // For FormData, do NOT set Content-Type — fetch must set it with the boundary.
+
+  if (BEARER) headers["Authorization"] = "Bearer " + BEARER;
+  else {
+    headers["X-Role"] = DEV_ROLE;
+    headers["X-Tenant-ID"] = DEV_TENANT;
+  }
+  if (API_KEY) headers["X-API-Key"] = API_KEY;
+
+  const res = await fetch(url, {
+    method: opts.method || "GET",
+    headers,
+    body,
+  });
+
+  const ct = res.headers.get("content-type") || "";
+  let resBody = null;
+  if (ct.includes("application/json")) resBody = await res.json().catch(() => null);
+  else if (!opts.raw) resBody = await res.text().catch(() => null);
+
+  if (!res.ok) {
+    const detail = (resBody && (resBody.detail || resBody.message)) || res.statusText || "request failed";
+    const err = new Error(`OptHR API ${res.status}: ${detail}`);
+    err.status = res.status;
+    err.body = resBody;
+    throw err;
+  }
+  return opts.raw ? res : resBody;
+}
+
+const text = (s) => ({ type: "text", text: typeof s === "string" ? s : JSON.stringify(s, null, 2) });
+const ok   = (s) => ({ content: [text(s)] });
+const fail = (e) => ({ content: [text(`Error: ${e.message || e}`)], isError: true });
+
+function filenameFromDisposition(value, fallback) {
+  const raw = value || "";
+  const utf = raw.match(/filename\*=UTF-8''([^;]+)/i);
+  if (utf) return decodeURIComponent(utf[1]);
+  const ascii = raw.match(/filename="?([^";]+)"?/i);
+  return ascii ? ascii[1] : fallback;
+}
+
+/* ----------------------------------------------------------------- */
+/* Tool definitions                                                   */
+/* ----------------------------------------------------------------- */
+
+const TOOLS = [
+  {
+    name: "opthr_health",
+    title: "OptHR · Health check",
+    description: "Check that the OptHR backend is reachable and report which LLM model it's using. Use this first if other tools fail.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    ...(OPTHR_ICONS ? { icons: OPTHR_ICONS } : {}),
+  },
+  {
+    name: "opthr_list_jobs",
+    title: "OptHR · List recent jobs",
+    ...(OPTHR_ICONS ? { icons: OPTHR_ICONS } : {}),
+    description: "List recent analyses (compensation + skill-gap) for the current tenant. Returns id, state, type and last-update time.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: { type: "integer", minimum: 1, maximum: 100, default: 20, description: "Max number of jobs to return" },
+        offset: { type: "integer", minimum: 0, default: 0 },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "opthr_get_job",
+    title: "OptHR · Get job result",
+    ...(OPTHR_ICONS ? { icons: OPTHR_ICONS } : {}),
+    description: "Fetch the full record of one job: state, uploaded documents, agent outputs, event log. Use this after running an analysis to read the result.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        job_id: { type: "string", description: "Job UUID, e.g. from opthr_list_jobs" },
+      },
+      required: ["job_id"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "opthr_run_skill_gap",
+    title: "OptHR · Run Skill Gap analysis",
+    ...(OPTHR_ICONS ? { icons: OPTHR_ICONS } : {}),
+    description: "Start a new Skill Gap analysis. Compares an employee's skill profile against a target role and returns ranked course recommendations. Auto-attaches the OptHR sample profile (Senior Controller scheda_competenze_pdf) unless you pass document_url.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        job_title: { type: "string", description: "Target role to compare against, e.g. 'Senior Backend Engineer'" },
+        natural_language: { type: "string", description: "What you want the agent to do, in plain English" },
+        document_url: { type: "string", description: "Optional URL to a CV/skills profile (PDF/CSV) to use INSTEAD of the sample" },
+      },
+      required: ["job_title"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "opthr_run_compensation",
+    title: "OptHR · Run Compensation analysis",
+    ...(OPTHR_ICONS ? { icons: OPTHR_ICONS } : {}),
+    description: "Start a new Compensation analysis. Compares an employee's salary against EU market percentile bands (P25/P50/P75/P90), explains the delta, and proposes EU Pay Directive remediation.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        employee_name: { type: "string" },
+        employee_gender: { type: "string", enum: ["male", "female"], description: "Required for the EU Pay Directive gender-gap calculation" },
+        job_title: { type: "string", description: "e.g. 'Senior Controller'" },
+        area: { type: "string", description: "Geo cluster, e.g. 'nord_est'" },
+        experience: { type: "string", description: "e.g. '3_5_anni'" },
+        ral_actual: { type: "number", description: "Annual gross salary EUR" },
+        review_period: { type: "string", description: "e.g. 'Q2 2026'" },
+        natural_language: { type: "string", description: "What you want the agent to do, in plain English" },
+      },
+      required: ["employee_name", "job_title", "ral_actual"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "opthr_answer",
+    title: "OptHR · Answer paused job",
+    ...(OPTHR_ICONS ? { icons: OPTHR_ICONS } : {}),
+    description: "Send a clarification answer / follow-up question to a paused job. The agent re-runs the affected step and continues.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        job_id: { type: "string" },
+        answer: { type: "string", description: "Plain-English answer or follow-up instruction" },
+      },
+      required: ["job_id", "answer"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "opthr_export",
+    title: "OptHR · Export report",
+    ...(OPTHR_ICONS ? { icons: OPTHR_ICONS } : {}),
+    description: "Download an export of a completed job. format=pdf returns the audit-ready PDF report; format=xlsx returns the Excel; format=json returns the raw outputs. Returns a base64-encoded file.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        job_id: { type: "string" },
+        format: { type: "string", enum: ["pdf", "xlsx", "json"], default: "pdf" },
+        kind: { type: "string", enum: ["skillgap", "compensation"], description: "PDF report kind (only for format=pdf)" },
+      },
+      required: ["job_id"],
+      additionalProperties: false,
+    },
+  },
+];
+
+/* ----------------------------------------------------------------- */
+/* Tool implementations                                               */
+/* ----------------------------------------------------------------- */
+
+async function handle(name, args = {}) {
+  switch (name) {
+    case "opthr_health": {
+      const h = await request("/health");
+      return ok({
+        ok: h.ok,
+        version: h.version,
+        llm: h.llm,
+        api_base: BASE,
+      });
+    }
+
+    case "opthr_list_jobs": {
+      const limit = args.limit ?? 20;
+      const offset = args.offset ?? 0;
+      const r = await request(`/jobs?limit=${limit}&offset=${offset}`);
+      const items = (r.items || []).map((j) => ({
+        job_id: j.job_id,
+        state: j.state,
+        type: (j.requested_modules || []).includes("skillgap") ? "skill-gap" : "compensation",
+        employee_name: j.employee_name || null,
+        job_title: j.job_title || null,
+        updated_at: j.updated_at,
+      }));
+      return ok({ count: items.length, items });
+    }
+
+    case "opthr_get_job": {
+      const r = await request(`/jobs/${encodeURIComponent(args.job_id)}`);
+      // Trim noisy fields the model doesn't need.
+      const trimmed = {
+        job_id: r.job_id,
+        state: r.state,
+        requested_modules: r.requested_modules,
+        created_at: r.created_at,
+        updated_at: r.updated_at,
+        documents: Object.fromEntries(Object.entries(r.documents || {}).map(([k, v]) => [k, { filename: v.filename, uploaded_at: v.uploaded_at }])),
+        outputs: r.outputs,
+        last_event: (r.events || []).slice(-1)[0] || null,
+      };
+      return ok(trimmed);
+    }
+
+    case "opthr_run_skill_gap": {
+      // 1) create the job
+      const created = await request("/jobs", {
+        method: "POST",
+        body: {
+          modules: ["skillgap"],
+          job_title: args.job_title,
+          natural_language: args.natural_language || `Skill gap for ${args.job_title}`,
+          metadata: { natural_language: args.natural_language || "" },
+        },
+      });
+      const jobId = created.job_id;
+
+      // 2) attach a document (sample if not provided)
+      if (args.document_url) {
+        // Fetch user-supplied URL and upload
+        const fileRes = await fetch(args.document_url);
+        if (!fileRes.ok) throw new Error(`Cannot fetch ${args.document_url}: ${fileRes.status}`);
+        const blob = await fileRes.blob();
+        const fd = new FormData();
+        fd.append("document_type", "scheda_competenze_pdf");
+        fd.append("file", blob, args.document_url.split("/").pop() || "skills.pdf");
+        await request(`/jobs/${encodeURIComponent(jobId)}/documents?auto_run=false`, {
+          method: "POST",
+          body: fd,
+        });
+      } else {
+        // Use sample
+        const samples = await request("/samples");
+        const sample = (samples.items || []).find(s => s.mode === "skill_learn");
+        if (sample) {
+          const sres = await request(`/samples/${encodeURIComponent(sample.name)}`, { raw: true });
+          const blob = await sres.blob();
+          const fd = new FormData();
+          fd.append("document_type", sample.document_type);
+          fd.append("file", blob, sample.name);
+          await request(`/jobs/${encodeURIComponent(jobId)}/documents?auto_run=false`, {
+            method: "POST",
+            body: fd,
+          });
+        }
+      }
+
+      // 3) start
+      await request(`/jobs/${encodeURIComponent(jobId)}/start`, { method: "POST" });
+
+      return ok({
+        job_id: jobId,
+        state: "running",
+        message: `Skill-gap analysis started against role "${args.job_title}". Use opthr_get_job to read results once state=review_required or completed.`,
+      });
+    }
+
+    case "opthr_run_compensation": {
+      const created = await request("/jobs", {
+        method: "POST",
+        body: {
+          modules: ["compensation", "pay_equity"],
+          employee_name: args.employee_name,
+          employee_gender: args.employee_gender || "female",
+          job_title: args.job_title,
+          area: args.area || "nord_est",
+          experience: args.experience || "3_5_anni",
+          ral_actual: Number(args.ral_actual),
+          pay_equity_threshold_pct: 5,
+          review_period: args.review_period || "current",
+          natural_language: args.natural_language || `Compensation for ${args.employee_name} (${args.job_title})`,
+          metadata: { natural_language: args.natural_language || "" },
+        },
+      });
+      const jobId = created.job_id;
+
+      // Sample performance PDF
+      const samples = await request("/samples");
+      const perf = (samples.items || []).find(s => s.document_type === "performance_pdf" && s.mode === "comp_pe");
+      if (perf) {
+        const sres = await request(`/samples/${encodeURIComponent(perf.name)}`, { raw: true });
+        const blob = await sres.blob();
+        const fd = new FormData();
+        fd.append("document_type", perf.document_type);
+        fd.append("file", blob, perf.name);
+        await request(`/jobs/${encodeURIComponent(jobId)}/documents?auto_run=false`, {
+          method: "POST",
+          body: fd,
+        });
+      }
+
+      await request(`/jobs/${encodeURIComponent(jobId)}/start`, { method: "POST" });
+
+      return ok({
+        job_id: jobId,
+        state: "running",
+        message: `Compensation analysis started for ${args.employee_name}. Use opthr_get_job to read results once state=review_required or completed.`,
+      });
+    }
+
+    case "opthr_answer": {
+      const r = await request(`/jobs/${encodeURIComponent(args.job_id)}/answer`, {
+        method: "POST",
+        body: { answer: args.answer, fields: {} },
+      });
+      return ok(r);
+    }
+
+    case "opthr_export": {
+      const fmt = args.format || "pdf";
+      const path = fmt === "pdf"
+        ? `/jobs/${encodeURIComponent(args.job_id)}/report${args.kind ? `?kind=${args.kind}` : ""}`
+        : `/jobs/${encodeURIComponent(args.job_id)}/export?format=${fmt}`;
+      const res = await request(path, { raw: true });
+      const buf = Buffer.from(await res.arrayBuffer());
+      return ok({
+        job_id: args.job_id,
+        format: fmt,
+        filename: filenameFromDisposition(
+          res.headers.get("content-disposition"),
+          `OptHR-${args.job_id}.${fmt === "pdf" ? "pdf" : fmt}`,
+        ),
+        size_bytes: buf.length,
+        content_type: res.headers.get("content-type") || "application/octet-stream",
+        base64: buf.toString("base64"),
+        message: `Downloaded ${buf.length} bytes. Decode the base64 field and save it using the filename above.`,
+      });
+    }
+
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+
+/* ----------------------------------------------------------------- */
+/* MCP server bootstrap                                               */
+/* ----------------------------------------------------------------- */
+
+const server = new Server(
+  {
+    name: "opthr-mcp-server",
+    title: "OptHR — Compensation & Skill Gap agents",
+    version: "0.2.0",
+    description: "Run OptHR's Compensation and Skill Gap agents directly from chat. Audit-ready reasoning, EU Pay Directive coverage, exportable reports.",
+    websiteUrl: "https://github.com/Dunic15/OptHRr",
+    ...(OPTHR_ICONS ? { icons: OPTHR_ICONS } : {}),
+  },
+  { capabilities: { tools: {} } },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args = {} } = request.params;
+  try {
+    return await handle(name, args);
+  } catch (err) {
+    return fail(err);
+  }
+});
+
+const transport = new StdioServerTransport();
+server.connect(transport).then(() => {
+  console.error(`[opthr-mcp-server] connected on stdio · API base = ${BASE}`);
+});