@opthr/mcp-server 0.2.0 → 0.2.3

package/src/index.js

@@ -2,64 +2,56 @@
 /**
  * @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.
+ * Thin Node.js wrapper around the OptHR FastAPI backend (OPTHR_API_BASE).
+ * Same endpoints the web prototype uses — no separate "MCP backend".
  *
- * 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)
+ * Environment:
+ *   OPTHR_API_BASE              FastAPI base URL (default http://localhost:8765)
+ *   OPTHR_API_KEY               sent as X-API-Key (production / hosted)
+ *   OPTHR_BEARER_TOKEN          sent as Authorization: Bearer …
+ *   OPTHR_DEV_ROLE              fallback X-Role            (default admin_hr)
+ *   OPTHR_DEV_TENANT_ID         fallback X-Tenant-ID       (default tenant_demo)
+ *   OPTHR_DOCUMENT_SEARCH_ROOT  if set, restrict `document_path` to this dir
+ *   OPTHR_DASHBOARD_URL         dashboard / app URL exposed via resources
+ *   OPTHR_LANDING_URL           landing-site URL
+ *   OPTHR_FIGMA_URL             optional Figma handoff URL
  *
- * 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"
- *         }
- *       }
- *     }
- *   }
+ * No personal/local paths are baked in. Source documents must be supplied
+ * by the caller via `document_url` (http/https/file://), `document_path`
+ * (absolute or under OPTHR_DOCUMENT_SEARCH_ROOT), or `use_sample_data=true`.
  */
 
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
   CallToolRequestSchema,
+  GetPromptRequestSchema,
+  ListPromptsRequestSchema,
+  ListResourcesRequestSchema,
   ListToolsRequestSchema,
+  ReadResourceRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
-import { readFileSync } from "node:fs";
+import { readFileSync, existsSync, statSync, realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { dirname, join } from "node:path";
+import { dirname, isAbsolute, join, resolve, basename } from "node:path";
+
+/* ----------------------------------------------------------------- */
+/* Environment                                                        */
+/* ----------------------------------------------------------------- */
 
+const PKG_VERSION = "0.2.2";
 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";
+const DOC_SEARCH_ROOT = (process.env.OPTHR_DOCUMENT_SEARCH_ROOT || "").trim();
+const DASHBOARD_URL = process.env.OPTHR_DASHBOARD_URL || `${BASE}/OptHR%20Redesign.html#/app`;
+const LANDING_URL = process.env.OPTHR_LANDING_URL || "https://opthr-landing-site.vercel.app/";
+const FIGMA_URL = process.env.OPTHR_FIGMA_URL || "";
 
 /* ----------------------------------------------------------------- */
-/* 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.                 */
+/* Branding — OptHR icon for clients on MCP spec 2025-06-18+          */
 /* ----------------------------------------------------------------- */
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -74,8 +66,83 @@ function loadOptHRIcon() {
     return undefined;
   }
 }
-
 const OPTHR_ICONS = loadOptHRIcon();
+const ICON_FIELDS = OPTHR_ICONS ? { icons: OPTHR_ICONS } : {};
+
+/* ----------------------------------------------------------------- */
+/* Structured observability                                           */
+/* ----------------------------------------------------------------- */
+
+const ERROR_CODES = {
+  BACKEND_UNREACHABLE: "BACKEND_UNREACHABLE",
+  AUTH_FAILED: "AUTH_FAILED",
+  DOCUMENT_NOT_FOUND: "DOCUMENT_NOT_FOUND",
+  INVALID_DOCUMENT_TYPE: "INVALID_DOCUMENT_TYPE",
+  JOB_TIMEOUT: "JOB_TIMEOUT",
+  BACKEND_ERROR: "BACKEND_ERROR",
+};
+
+// Telemetry sink: stderr always, plus optional fire-and-forget HTTP POST when
+// OPTHR_TELEMETRY_URL is set. Payload is intentionally narrow — no PII, no
+// salaries, no documents, no request/response bodies.
+const TELEMETRY_URL = (process.env.OPTHR_TELEMETRY_URL || "").trim();
+const TELEMETRY_AUTH = (process.env.OPTHR_TELEMETRY_AUTH || "").trim();
+
+function postTelemetry(entry) {
+  if (!TELEMETRY_URL) return;
+  const headers = { "Content-Type": "application/json" };
+  if (TELEMETRY_AUTH) headers["Authorization"] = TELEMETRY_AUTH;
+  // Fire-and-forget; never await, never throw into the caller.
+  fetch(TELEMETRY_URL, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(entry),
+  }).catch(() => {
+    /* swallow — telemetry must never affect tool calls */
+  });
+}
+
+function logEvent(event) {
+  // stderr only — stdout is reserved for the MCP transport.
+  try {
+    const entry = {
+      ts: new Date().toISOString(),
+      svc: "opthr-mcp-server",
+      version: PKG_VERSION,
+      tenant_id: DEV_TENANT || null,
+      backend_host: safeHost(BASE),
+      ...event,
+    };
+    console.error(JSON.stringify(entry));
+    postTelemetry(entry);
+  } catch {
+    // never let logging fail the call
+  }
+}
+
+function safeHost(url) {
+  try {
+    return new URL(url).host || null;
+  } catch {
+    return null;
+  }
+}
+
+class OptHRError extends Error {
+  constructor(message, { code = ERROR_CODES.BACKEND_ERROR, status: httpStatus, details } = {}) {
+    super(message);
+    this.code = code;
+    this.status = httpStatus;
+    this.details = details;
+  }
+}
+
+function classifyStatus(status) {
+  if (status === 401 || status === 403) return ERROR_CODES.AUTH_FAILED;
+  if (status === 404) return ERROR_CODES.DOCUMENT_NOT_FOUND;
+  if (status === 422) return ERROR_CODES.INVALID_DOCUMENT_TYPE;
+  return ERROR_CODES.BACKEND_ERROR;
+}
 
 /* ----------------------------------------------------------------- */
 /* HTTP helpers                                                       */
@@ -101,7 +168,6 @@ async function request(path, opts = {}) {
   } 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 {
@@ -110,11 +176,19 @@ async function request(path, opts = {}) {
   }
   if (API_KEY) headers["X-API-Key"] = API_KEY;
 
-  const res = await fetch(url, {
-    method: opts.method || "GET",
-    headers,
-    body,
-  });
+  let res;
+  try {
+    res = await fetch(url, {
+      method: opts.method || "GET",
+      headers,
+      body,
+    });
+  } catch (networkErr) {
+    throw new OptHRError(
+      `Cannot reach OptHR backend at ${BASE} — ${networkErr.message || networkErr}`,
+      { code: ERROR_CODES.BACKEND_UNREACHABLE },
+    );
+  }
 
   const ct = res.headers.get("content-type") || "";
   let resBody = null;
@@ -122,18 +196,36 @@ async function request(path, opts = {}) {
   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;
+    const detail =
+      (resBody && (resBody.detail || resBody.message)) || res.statusText || "request failed";
+    throw new OptHRError(`OptHR API ${res.status}: ${detail}`, {
+      code: classifyStatus(res.status),
+      status: res.status,
+      details: resBody,
+    });
   }
   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 });
+const ok = (s) => ({ content: [text(s)] });
+
+function fail(err) {
+  const code = err && err.code ? err.code : ERROR_CODES.BACKEND_ERROR;
+  const status = err && err.status;
+  return {
+    content: [
+      text({
+        error: {
+          code,
+          message: err && err.message ? err.message : String(err),
+          status: status || null,
+        },
+      }),
+    ],
+    isError: true,
+  };
+}
 
 function filenameFromDisposition(value, fallback) {
   const raw = value || "";
@@ -143,113 +235,778 @@ function filenameFromDisposition(value, fallback) {
   return ascii ? ascii[1] : fallback;
 }
 
+/* ----------------------------------------------------------------- */
+/* Document resolution — file://, document_path, document_url         */
+/* ----------------------------------------------------------------- */
+
+function resolveLocalPath(rawPath) {
+  if (!rawPath || typeof rawPath !== "string") {
+    throw new OptHRError("document_path must be a non-empty string", {
+      code: ERROR_CODES.DOCUMENT_NOT_FOUND,
+    });
+  }
+
+  let candidate = rawPath.trim();
+  if (candidate.startsWith("file://")) {
+    candidate = fileURLToPath(candidate);
+  }
+
+  if (!isAbsolute(candidate)) {
+    if (!DOC_SEARCH_ROOT) {
+      throw new OptHRError(
+        `Relative document_path '${rawPath}' is not allowed unless OPTHR_DOCUMENT_SEARCH_ROOT is configured.`,
+        { code: ERROR_CODES.DOCUMENT_NOT_FOUND },
+      );
+    }
+    candidate = resolve(DOC_SEARCH_ROOT, candidate);
+  }
+
+  let realPath;
+  try {
+    realPath = realpathSync(candidate);
+  } catch {
+    throw new OptHRError(`Document not found: ${rawPath}`, {
+      code: ERROR_CODES.DOCUMENT_NOT_FOUND,
+    });
+  }
+
+  if (DOC_SEARCH_ROOT) {
+    const rootReal = realpathSync(resolve(DOC_SEARCH_ROOT));
+    if (!realPath.startsWith(rootReal + "/") && realPath !== rootReal) {
+      throw new OptHRError(
+        `document_path '${rawPath}' resolves outside OPTHR_DOCUMENT_SEARCH_ROOT`,
+        { code: ERROR_CODES.DOCUMENT_NOT_FOUND },
+      );
+    }
+  }
+
+  let stats;
+  try {
+    stats = statSync(realPath);
+  } catch {
+    throw new OptHRError(`Document not found: ${rawPath}`, {
+      code: ERROR_CODES.DOCUMENT_NOT_FOUND,
+    });
+  }
+  if (!stats.isFile()) {
+    throw new OptHRError(`document_path '${rawPath}' is not a regular file`, {
+      code: ERROR_CODES.DOCUMENT_NOT_FOUND,
+    });
+  }
+  return realPath;
+}
+
+function guessMimeType(filename) {
+  const f = (filename || "").toLowerCase();
+  if (f.endsWith(".pdf")) return "application/pdf";
+  if (f.endsWith(".csv")) return "text/csv";
+  if (f.endsWith(".xlsx")) return "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+  if (f.endsWith(".json")) return "application/json";
+  if (f.endsWith(".docx")) return "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+  return "application/octet-stream";
+}
+
+/**
+ * Returns a { blob, filename } pair given:
+ *   - document_url: http(s)://… or file://…
+ *   - document_path: absolute local path or relative under OPTHR_DOCUMENT_SEARCH_ROOT
+ * Throws an OptHRError with a DOCUMENT_NOT_FOUND / INVALID_DOCUMENT_TYPE code on failure.
+ */
+async function resolveDocument({ document_url, document_path, fallbackName = "document.bin" }) {
+  if (document_path) {
+    const path = resolveLocalPath(document_path);
+    const bytes = readFileSync(path);
+    const blob = new Blob([bytes], { type: guessMimeType(path) });
+    return { blob, filename: basename(path) };
+  }
+  if (document_url) {
+    const url = document_url.trim();
+    if (url.startsWith("file://")) {
+      const path = resolveLocalPath(url);
+      const bytes = readFileSync(path);
+      const blob = new Blob([bytes], { type: guessMimeType(path) });
+      return { blob, filename: basename(path) };
+    }
+    if (!/^https?:\/\//i.test(url)) {
+      throw new OptHRError(
+        `document_url must start with http://, https://, or file://. Got: ${url}`,
+        { code: ERROR_CODES.INVALID_DOCUMENT_TYPE },
+      );
+    }
+    let r;
+    try {
+      r = await fetch(url);
+    } catch (e) {
+      throw new OptHRError(`Cannot fetch document_url: ${e.message || e}`, {
+        code: ERROR_CODES.DOCUMENT_NOT_FOUND,
+      });
+    }
+    if (!r.ok) {
+      throw new OptHRError(`document_url returned ${r.status} ${r.statusText}`, {
+        code: ERROR_CODES.DOCUMENT_NOT_FOUND,
+        status: r.status,
+      });
+    }
+    const blob = await r.blob();
+    const name = url.split("/").pop() || fallbackName;
+    return { blob, filename: name };
+  }
+  throw new OptHRError("Provide either document_path or document_url.", {
+    code: ERROR_CODES.DOCUMENT_NOT_FOUND,
+  });
+}
+
+async function uploadJobDocument(jobId, blob, filename, documentType, { autoRun = false } = {}) {
+  const fd = new FormData();
+  fd.append("document_type", documentType);
+  fd.append("file", blob, filename || `${documentType}.bin`);
+  return request(
+    `/jobs/${encodeURIComponent(jobId)}/documents?auto_run=${autoRun ? "true" : "false"}`,
+    { method: "POST", body: fd },
+  );
+}
+
+/* ----------------------------------------------------------------- */
+/* Product surfaces & static resources                                */
+/* ----------------------------------------------------------------- */
+
+function productSurfaces() {
+  return {
+    dashboard_url: DASHBOARD_URL,
+    landing_url: LANDING_URL,
+    api_base: BASE,
+    figma_url: FIGMA_URL || null,
+    figma_status: FIGMA_URL ? "configured" : "not_configured",
+    notes: [
+      "Use the dashboard URL for the current product UI and job workspace.",
+      "Set OPTHR_FIGMA_URL to expose the canonical Figma handoff link through MCP.",
+      "MCP analysis tools never attach bundled sample PDFs unless use_sample_data=true.",
+    ],
+  };
+}
+
+const TOOL_GUIDE_MARKDOWN = `# OptHR MCP — Tool guide
+
+This MCP bridges Claude clients to the OptHR FastAPI backend. The backend is the source of truth; this server is a thin RPC layer plus a few document-resolution helpers.
+
+## Picking the right tool
+
+- **opthr_health** — sanity check connectivity and active LLM. Call first when nothing else works.
+- **opthr_run_compensation** — start a compensation + pay-equity job. Needs employee_name, job_title, ral_actual.
+- **opthr_run_pay_equity** — pay-equity-only run from a payroll-style CSV.
+- **opthr_run_skill_gap** — skill gap vs a target role from a competence-profile document.
+- **opthr_run_rapporto_biennale** — Legge 162/2021 Rapporto Biennale workflow (preview).
+- **opthr_wait_for_job** — poll a running job until it completes/fails or a timeout fires.
+- **opthr_get_job_summary** — compact merged summary across compensation / pay equity / skill gap / recommendations. Best for "what did this job find?".
+- **opthr_answer** — send a clarification when a job is paused waiting on the user.
+- **opthr_export** — download a PDF / XLSX / DOCX / PPTX / JSON export of a completed job.
+- **opthr_review_step** — generic reviewer action over compensation / pay_equity / skills / recommendations / manager_feedback.
+
+## Read-only browsing — use resources, not tools
+
+- \`opthr://recent-jobs\` — latest 20 analyses for the tenant. Use to discover a \`job_id\` without spending a tool slot.
+- \`opthr://dashboard\` and \`opthr://product-surfaces\` — dashboard, landing, Figma, API URLs.
+- \`opthr://samples\` and \`opthr://sample-payroll-csv\` — bundled demo inputs.
+- \`opthr://schemas\` — JobModule, DocumentType, error-code enums.
+- \`opthr://rapporto-biennale-template\` — Legge 162/2021 column layout.
+
+## When NOT to use these tools
+
+- Don't call any tool other than \`opthr_health\` if the backend is unreachable — surface the error to the user instead.
+- Don't auto-attach sample data unless the user explicitly asks for "demo" / "sample" data.
+- Don't call \`opthr_run_compensation\` if you only have a payroll CSV — use \`opthr_run_pay_equity\` or \`opthr_run_rapporto_biennale\`.
+- Don't poll for job state with \`opthr_get_job_summary\` — use \`opthr_wait_for_job\`, then \`opthr_get_job_summary\` once.
+- Don't approve a review step on the user's behalf without confirmation.
+`;
+
+const RESOURCES = [
+  {
+    uri: "opthr://dashboard",
+    name: "OptHR dashboard",
+    title: "OptHR Dashboard",
+    description: "Current dashboard/app URL for running analyses and inspecting jobs.",
+    mimeType: "application/json",
+  },
+  {
+    uri: "opthr://figma",
+    name: "OptHR Figma handoff",
+    title: "OptHR Figma",
+    description: "Configured Figma design handoff URL. Set OPTHR_FIGMA_URL if missing.",
+    mimeType: "application/json",
+  },
+  {
+    uri: "opthr://product-surfaces",
+    name: "OptHR product surfaces",
+    title: "OptHR Product Surfaces",
+    description: "Dashboard, landing, API base, and Figma handoff metadata.",
+    mimeType: "application/json",
+  },
+  {
+    uri: "opthr://samples",
+    name: "OptHR sample files",
+    title: "OptHR sample documents",
+    description: "List of bundled sample documents (skills profiles, performance reviews, payroll CSV).",
+    mimeType: "application/json",
+  },
+  {
+    uri: "opthr://schemas",
+    name: "OptHR schema reference",
+    title: "OptHR job & document schemas",
+    description: "Canonical JobState, JobModule, DocumentType, UserRole enums and review payload shapes.",
+    mimeType: "application/json",
+  },
+  {
+    uri: "opthr://tool-guide",
+    name: "OptHR MCP tool guide",
+    title: "OptHR MCP — when to use which tool",
+    description: "Guidance for picking the right OptHR tool and avoiding common mistakes.",
+    mimeType: "text/markdown",
+  },
+  {
+    uri: "opthr://recent-jobs",
+    name: "Recent OptHR jobs",
+    title: "OptHR recent jobs (live)",
+    description: "Live list of the last 20 analyses for the connected tenant.",
+    mimeType: "application/json",
+  },
+  {
+    uri: "opthr://sample-payroll-csv",
+    name: "Sample payroll CSV",
+    title: "Sample payroll CSV (pay equity / Rapporto Biennale)",
+    description: "Minimal CSV template used to seed a payroll/pay-equity dataset.",
+    mimeType: "text/csv",
+  },
+  {
+    uri: "opthr://rapporto-biennale-template",
+    name: "Rapporto Biennale template",
+    title: "Rapporto Biennale (Legge 162/2021) — column template",
+    description: "Header layout the backend equity_report agent expects from a payroll CSV.",
+    mimeType: "application/json",
+  },
+];
+
+const SCHEMA_REFERENCE = {
+  job_states: [
+    "uploaded",
+    "queued",
+    "parsing",
+    "extracting",
+    "matching",
+    "analyzing",
+    "recommending",
+    "review_required",
+    "completed",
+    "failed",
+  ],
+  job_modules: ["compensation", "pay_equity", "skillgap", "equity_report"],
+  job_steps: ["parsing", "extracting", "matching", "analyzing", "recommending", "reporting"],
+  document_types: [
+    "jd_pdf",
+    "performance_pdf",
+    "pay_equity_csv",
+    "scheda_competenze_pdf",
+    "catalog_skilla",
+    "catalog_cegos",
+    "payroll_csv",
+  ],
+  user_roles: ["admin_hr", "manager", "reviewer"],
+  review_payloads: {
+    compensation: { acknowledged: "boolean", note: "string?" },
+    pay_equity: { acknowledged: "boolean", note: "string?" },
+    skills: { hard_skills: "ReviewSkillItem[]", soft_skills: "ReviewSkillItem[]" },
+    recommendations: { recommendations_by_skill: "Record<string, ReviewRecommendationItem[]>" },
+    manager_feedback: {
+      markdown: "string",
+      rating_bucket: "string?",
+      comp_recommendation: "string?",
+      hr_actions: "string[]",
+      sign: "boolean",
+      signer_name: "string?",
+    },
+  },
+  error_codes: Object.values(ERROR_CODES),
+};
+
+const SAMPLE_PAYROLL_CSV = `employee_id,nome,genere,job_title,area,esperienza,ral_attuale,bonus_anno,data_assunzione
+EMP-0001,Anna Bianchi,F,Senior Controller,nord_est,5_10_anni,52000,4000,2019-04-01
+EMP-0002,Marco Verdi,M,Senior Controller,nord_est,5_10_anni,58000,5000,2018-09-15
+EMP-0003,Giulia Neri,F,Junior Controller,centro,0_3_anni,32000,1500,2023-01-10
+EMP-0004,Luca Rossi,M,Junior Controller,centro,0_3_anni,34000,1500,2022-07-01
+EMP-0005,Sara Conti,F,Plant Manager,sud,10_plus_anni,72000,8000,2014-03-12
+EMP-0006,Andrea Russo,M,Plant Manager,sud,10_plus_anni,82000,9000,2013-11-04
+`;
+
+const RAPPORTO_TEMPLATE_INFO = {
+  required_columns: [
+    "employee_id",
+    "nome",
+    "genere",
+    "job_title",
+    "area",
+    "esperienza",
+    "ral_attuale",
+  ],
+  optional_columns: ["bonus_anno", "data_assunzione", "contract_type", "part_time_pct"],
+  gender_values: ["F", "M"],
+  notes: [
+    "Legge 162/2021 requires gender-coded rows; 'U' / blank values will not be counted in the Rapporto Biennale aggregation.",
+    "The backend `equity_report` agent (backend/agents/equity_report.py) builds the XLSX and Markdown summary; wiring this module into the workflow orchestrator is in progress.",
+    "Until that wiring lands, opthr_run_rapporto_biennale will create a job with modules=['equity_report'] and upload the payroll CSV, but the run will not produce a finished report.",
+  ],
+};
+
+async function readResource(uri) {
+  const surfaces = productSurfaces();
+  switch (uri) {
+    case "opthr://dashboard":
+      return {
+        uri,
+        mimeType: "application/json",
+        text: JSON.stringify(
+          {
+            dashboard_url: surfaces.dashboard_url,
+            api_base: surfaces.api_base,
+            description: "Open this URL for the current OptHR dashboard and job workspace.",
+          },
+          null,
+          2,
+        ),
+      };
+    case "opthr://figma":
+      return {
+        uri,
+        mimeType: "application/json",
+        text: JSON.stringify(
+          {
+            figma_url: surfaces.figma_url,
+            status: surfaces.figma_status,
+            description: FIGMA_URL
+              ? "Open this URL for the current Figma design handoff."
+              : "No Figma URL is configured. Set OPTHR_FIGMA_URL in the MCP server environment.",
+          },
+          null,
+          2,
+        ),
+      };
+    case "opthr://product-surfaces":
+      return { uri, mimeType: "application/json", text: JSON.stringify(surfaces, null, 2) };
+    case "opthr://schemas":
+      return { uri, mimeType: "application/json", text: JSON.stringify(SCHEMA_REFERENCE, null, 2) };
+    case "opthr://tool-guide":
+      return { uri, mimeType: "text/markdown", text: TOOL_GUIDE_MARKDOWN };
+    case "opthr://sample-payroll-csv":
+      return { uri, mimeType: "text/csv", text: SAMPLE_PAYROLL_CSV };
+    case "opthr://rapporto-biennale-template":
+      return {
+        uri,
+        mimeType: "application/json",
+        text: JSON.stringify(RAPPORTO_TEMPLATE_INFO, null, 2),
+      };
+    case "opthr://samples": {
+      const r = await request("/samples");
+      return { uri, mimeType: "application/json", text: JSON.stringify(r, null, 2) };
+    }
+    case "opthr://recent-jobs": {
+      const r = await request("/jobs?limit=20&offset=0");
+      const items = (r.items || []).map((j) => ({
+        job_id: j.job_id,
+        state: j.state,
+        modules: j.requested_modules || [],
+        employee_name: j.employee_name || null,
+        job_title: j.job_title || null,
+        updated_at: j.updated_at,
+      }));
+      return {
+        uri,
+        mimeType: "application/json",
+        text: JSON.stringify({ count: items.length, items }, null, 2),
+      };
+    }
+    default:
+      throw new OptHRError(`Unknown resource: ${uri}`, { code: ERROR_CODES.DOCUMENT_NOT_FOUND });
+  }
+}
+
+/* ----------------------------------------------------------------- */
+/* Prompts                                                            */
+/* ----------------------------------------------------------------- */
+
+const PROMPTS = [
+  {
+    name: "opthr-quick-comp",
+    title: "OptHR · Quick compensation check",
+    description: "Run a one-shot compensation + pay-equity analysis for a single employee.",
+    arguments: [
+      { name: "employee_name", description: "Full name", required: true },
+      { name: "job_title", description: "Target role, e.g. 'Senior Controller'", required: true },
+      { name: "ral_actual", description: "Current annual gross salary (EUR)", required: true },
+      { name: "area", description: "Geo cluster (nord_ovest / nord_est / centro / sud)", required: false },
+    ],
+  },
+  {
+    name: "opthr-explain-job",
+    title: "OptHR · Explain a job",
+    description: "Pull a job's full state and outputs, then explain what was computed and what the next action is.",
+    arguments: [{ name: "job_id", description: "Job UUID", required: true }],
+  },
+  {
+    name: "opthr-rapporto-biennale",
+    title: "OptHR · Rapporto Biennale (Legge 162/2021)",
+    description: "Kick off a Rapporto Biennale run from a payroll CSV and walk the user through trasmissione.",
+    arguments: [
+      { name: "company_name", description: "Ragione sociale dichiarante", required: true },
+      { name: "payroll_path", description: "Absolute path or file:// URL to the payroll CSV", required: true },
+    ],
+  },
+  {
+    name: "opthr-calibrate-team",
+    title: "OptHR · Calibrate team comp",
+    description: "Loop through a list of employees and run compensation analyses, ready for calibration.",
+    arguments: [
+      { name: "team_name", description: "Team label, e.g. 'Controlling Italia'", required: true },
+      { name: "employees", description: "Comma-separated list of 'Name | Role | RAL'", required: true },
+    ],
+  },
+];
+
+function getPrompt(name, args = {}) {
+  switch (name) {
+    case "opthr-quick-comp": {
+      const { employee_name, job_title, ral_actual, area } = args;
+      const message = [
+        `Run a compensation + pay-equity analysis for **${employee_name || "<employee>"}** in role **${job_title || "<role>"}**`,
+        `with RAL **${ral_actual || "<ral>"} EUR**${area ? ` (${area})` : ""}.`,
+        "",
+        "Steps:",
+        "1. Call `opthr_run_compensation` with the fields above.",
+        "2. Call `opthr_wait_for_job` to wait for completion.",
+        "3. Summarise the percentile band, gender-gap signal, and the top remediation action.",
+      ].join("\n");
+      return {
+        description: "Quick compensation + pay-equity workflow",
+        messages: [{ role: "user", content: { type: "text", text: message } }],
+      };
+    }
+    case "opthr-explain-job": {
+      const message = [
+        `Explain OptHR job \`${args.job_id || "<job_id>"}\`.`,
+        "",
+        "Steps:",
+        "1. Call `opthr_get_job_summary` for a compact view.",
+        "2. If state != completed, surface the last event and what's blocking.",
+        "3. If state == completed, summarise: percentile band, EU Pay Directive gap, top recommendations.",
+      ].join("\n");
+      return {
+        description: "Explain an existing OptHR job",
+        messages: [{ role: "user", content: { type: "text", text: message } }],
+      };
+    }
+    case "opthr-rapporto-biennale": {
+      const message = [
+        `Kick off a Rapporto Biennale (Legge 162/2021) for **${args.company_name || "<company>"}**.`,
+        "",
+        "Steps:",
+        `1. Call \`opthr_run_rapporto_biennale\` with company_name and document_path=\`${args.payroll_path || "<absolute payroll csv path>"}\`.`,
+        "2. Call `opthr_wait_for_job` to wait for completion.",
+        "3. Call `opthr_export` with format='xlsx' to download the Modello.",
+        "4. Walk the user through trasmissione alla Consigliera di parità.",
+      ].join("\n");
+      return {
+        description: "Rapporto Biennale workflow",
+        messages: [{ role: "user", content: { type: "text", text: message } }],
+      };
+    }
+    case "opthr-calibrate-team": {
+      const message = [
+        `Calibrate compensation for team **${args.team_name || "<team>"}**.`,
+        "",
+        `Employees (Name | Role | RAL): ${args.employees || "<list>"}`,
+        "",
+        "Steps:",
+        "1. For each row, call `opthr_run_compensation`.",
+        "2. Use `opthr_wait_for_job` and `opthr_get_job_summary` to collect results.",
+        "3. Produce a calibration table (employee, current RAL, percentile band, recommended action).",
+      ].join("\n");
+      return {
+        description: "Team calibration",
+        messages: [{ role: "user", content: { type: "text", text: message } }],
+      };
+    }
+    default:
+      throw new OptHRError(`Unknown prompt: ${name}`, { code: ERROR_CODES.BACKEND_ERROR });
+  }
+}
+
 /* ----------------------------------------------------------------- */
 /* Tool definitions                                                   */
 /* ----------------------------------------------------------------- */
 
+const GENDER_VALUES = ["male", "female", "unspecified", "F", "M"];
+
 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.",
+    description:
+      "Sanity-check that the OptHR backend is reachable and report which LLM model it's wired to. " +
+      "Use this first when other tools fail. " +
+      "**Do NOT use this** to inspect job state or read outputs.",
     inputSchema: { type: "object", properties: {}, additionalProperties: false },
-    ...(OPTHR_ICONS ? { icons: OPTHR_ICONS } : {}),
+    outputSchema: {
+      type: "object",
+      properties: {
+        ok: { type: "boolean" },
+        version: { type: "string" },
+        api_base: { type: "string" },
+      },
+      required: ["ok"],
+    },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+    ...ICON_FIELDS,
   },
   {
-    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.",
+    name: "opthr_get_job_summary",
+    title: "OptHR · Get job summary",
+    description:
+      "Compact merged summary across compensation, pay-equity, skill-gap, performance and recommendations. " +
+      "Best for 'what did this job find?' questions. " +
+      "**Do NOT use this** to poll — wait via `opthr_wait_for_job` first, then call this once.",
     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 },
-      },
+      properties: { job_id: { type: "string" } },
+      required: ["job_id"],
       additionalProperties: false,
     },
+    annotations: { readOnlyHint: true },
+    ...ICON_FIELDS,
   },
   {
-    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.",
+    name: "opthr_wait_for_job",
+    title: "OptHR · Wait for job",
+    description:
+      "Poll a running job until it reaches `completed` or `failed`, or the timeout fires. " +
+      "Cheaper than polling `opthr_get_job_summary`. " +
+      "**Do NOT call** with a timeout longer than a few minutes — surface partial progress instead.",
     inputSchema: {
       type: "object",
       properties: {
-        job_id: { type: "string", description: "Job UUID, e.g. from opthr_list_jobs" },
+        job_id: { type: "string" },
+        timeout_seconds: { type: "integer", minimum: 5, maximum: 600, default: 120 },
+        poll_interval_seconds: { type: "number", minimum: 0.5, maximum: 30, default: 3 },
       },
       required: ["job_id"],
       additionalProperties: false,
     },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+    ...ICON_FIELDS,
   },
   {
     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.",
+    description:
+      "Start a Skill Gap analysis from a competence-profile document. " +
+      "Pass `document_url` (http/https/file://), `document_path` (absolute or under OPTHR_DOCUMENT_SEARCH_ROOT), " +
+      "or `use_sample_data=true` for the bundled demo PDF. " +
+      "**Do NOT use this** if you only have payroll data — that's `opthr_run_pay_equity` / `opthr_run_rapporto_biennale`.",
     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" },
+        job_title: { type: "string" },
+        natural_language: { type: "string" },
+        document_url: { type: "string", description: "http(s):// or file:// URL" },
+        document_path: { type: "string", description: "Absolute path or under OPTHR_DOCUMENT_SEARCH_ROOT" },
+        use_sample_data: { type: "boolean", default: false },
       },
       required: ["job_title"],
       additionalProperties: false,
     },
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    ...ICON_FIELDS,
   },
   {
     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.",
+    description:
+      "Start a new Compensation + Pay-Equity analysis. Compares the employee's salary against EU market " +
+      "percentile bands (P25/P50/P75/P90), explains the delta, and proposes EU Pay Directive remediation. " +
+      "**Do NOT use this** for org-wide pay-equity from a payroll CSV — use `opthr_run_pay_equity`.",
     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'" },
+        employee_gender: {
+          type: "string",
+          enum: GENDER_VALUES,
+          default: "unspecified",
+          description:
+            "Optional. Accepted values: male / female / unspecified / F / M. " +
+            "Required only for the EU Pay Directive single-employee gap calculation.",
+        },
+        job_title: { type: "string" },
         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" },
+        natural_language: { type: "string" },
+        document_url: { type: "string", description: "Optional performance PDF (http/https/file://)" },
+        document_path: { type: "string", description: "Optional performance PDF path" },
+        use_sample_data: { type: "boolean", default: false },
       },
       required: ["employee_name", "job_title", "ral_actual"],
       additionalProperties: false,
     },
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    ...ICON_FIELDS,
+  },
+  {
+    name: "opthr_run_pay_equity",
+    title: "OptHR · Run Pay-Equity analysis",
+    description:
+      "Run a pay-equity analysis over a payroll-style CSV (one row per employee, gendered). " +
+      "Pass `document_path` or `document_url` (CSV). Set `payroll_source` to hint the column " +
+      "layout (zucchetti, teamsystem, or generic) — the backend tolerates either way, but the " +
+      "hint helps when columns are ambiguous. " +
+      "**Do NOT use this** for a single employee — use `opthr_run_compensation`.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        document_path: { type: "string" },
+        document_url: { type: "string" },
+        threshold_pct: { type: "number", minimum: 0, maximum: 100, default: 5 },
+        payroll_source: {
+          type: "string",
+          enum: ["zucchetti", "teamsystem", "generic"],
+          default: "generic",
+          description: "Optional column-mapping hint matching the customer's payroll export tool.",
+        },
+        natural_language: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: false, openWorldHint: true },
+    ...ICON_FIELDS,
+  },
+  {
+    name: "opthr_run_rapporto_biennale",
+    title: "OptHR · Rapporto Biennale (Legge 162/2021)",
+    description:
+      "Start a Rapporto Biennale workflow for the supplied payroll CSV. Creates a job with " +
+      "`modules=['equity_report']`, attaches the payroll, runs the equity-report orchestrator " +
+      "node, and produces a Modello workbook downloadable via `opthr_export` with `format=xlsx`. " +
+      "Set `payroll_source` to hint the column layout. Pass `section_h` to populate the " +
+      "qualitative \"politiche di conciliazione\" sheet — anything omitted renders as " +
+      "\"(da compilare)\". " +
+      "**Do NOT use this** to compare a single employee's salary — use `opthr_run_compensation`.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        company_name: { type: "string" },
+        document_path: { type: "string" },
+        document_url: { type: "string" },
+        payroll_source: {
+          type: "string",
+          enum: ["zucchetti", "teamsystem", "generic"],
+          default: "generic",
+          description: "Optional column-mapping hint matching the customer's payroll export tool.",
+        },
+        section_h: {
+          type: "object",
+          description:
+            "Sezione H — politiche di conciliazione vita-lavoro. Optional but recommended " +
+            "for companies with ≥50 employees (Legge 162/2021 art. 46).",
+          properties: {
+            smart_working: { type: "string" },
+            part_time_policy: { type: "string" },
+            parental_leave: { type: "string" },
+            childcare_support: { type: "string" },
+            flexible_hours: { type: "string" },
+            equal_opportunity_actions: { type: "string" },
+            training_on_diversity: { type: "string" },
+            career_progression_review: { type: "string" },
+            pay_review_process: { type: "string" },
+            notes: { type: "string" },
+          },
+          additionalProperties: false,
+        },
+        natural_language: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: false, openWorldHint: true },
+    ...ICON_FIELDS,
   },
   {
     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.",
+    title: "OptHR · Send follow-up",
+    description:
+      "Send a clarification answer or follow-up instruction to a job that's paused waiting on the user. " +
+      "The agent re-runs the affected step and continues. " +
+      "**Do NOT use this** to re-run a step on a failed job — re-create the job instead.",
     inputSchema: {
       type: "object",
       properties: {
         job_id: { type: "string" },
-        answer: { type: "string", description: "Plain-English answer or follow-up instruction" },
+        answer: { type: "string" },
       },
       required: ["job_id", "answer"],
       additionalProperties: false,
     },
+    annotations: { readOnlyHint: false, destructiveHint: false },
+    ...ICON_FIELDS,
   },
   {
     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.",
+    description:
+      "Download an export of a completed job. " +
+      "`format=pdf` returns the page-rendered report; `format=xlsx/docx/pptx/json` returns the matching structured export. " +
+      "**Do NOT use this** before the job is in state=completed — call `opthr_wait_for_job` first.",
     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)" },
+        format: { type: "string", enum: ["pdf", "xlsx", "json", "docx", "pptx"], default: "pdf" },
+        kind: { type: "string", enum: ["skillgap", "compensation"] },
       },
       required: ["job_id"],
       additionalProperties: false,
     },
+    annotations: { readOnlyHint: true },
+    ...ICON_FIELDS,
+  },
+  {
+    name: "opthr_review_step",
+    title: "OptHR · Review a workflow step",
+    description:
+      "Generic reviewer action for an OptHR job. Approve or request a revision of a single step. " +
+      "Steps: `compensation`, `pay_equity`, `skills`, `recommendations`, `manager_feedback`. " +
+      "For `skills` / `recommendations` overrides, pass the full payload under `payload` " +
+      "(e.g. `{ \"hard_skills\": [...], \"soft_skills\": [...] }`). " +
+      "**Do NOT use this** on the user's behalf without explicit confirmation, and never sign " +
+      "manager feedback (decision=approve + step=manager_feedback) without a named human signer.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        job_id: { type: "string" },
+        step: {
+          type: "string",
+          enum: ["compensation", "pay_equity", "skills", "recommendations", "manager_feedback"],
+        },
+        decision: { type: "string", enum: ["approve", "revise"], default: "approve" },
+        notes: { type: "string" },
+        payload: {
+          type: "object",
+          description:
+            "Step-specific extras. For `skills`: { hard_skills, soft_skills }. " +
+            "For `recommendations`: { recommendations_by_skill }. " +
+            "For `manager_feedback`: { markdown, rating_bucket?, comp_recommendation?, hr_actions?, signer_name? }.",
+        },
+      },
+      required: ["job_id", "step"],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false },
+    ...ICON_FIELDS,
   },
 ];
 
@@ -257,51 +1014,65 @@ const TOOLS = [
 /* Tool implementations                                               */
 /* ----------------------------------------------------------------- */
 
+const PUBLIC_TOOL_NAMES = new Set(TOOLS.map((t) => t.name));
+
 async function handle(name, args = {}) {
+  if (!PUBLIC_TOOL_NAMES.has(name)) {
+    throw new OptHRError(`Unknown tool: ${name}`, { code: ERROR_CODES.BACKEND_ERROR });
+  }
   switch (name) {
     case "opthr_health": {
       const h = await request("/health");
-      return ok({
-        ok: h.ok,
-        version: h.version,
-        llm: h.llm,
-        api_base: BASE,
-      });
+      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_summary": {
+      const jobId = encodeURIComponent(args.job_id);
+      const [job, comp, payEq, skill, rec, perf] = await Promise.all([
+        request(`/jobs/${jobId}`).catch(() => null),
+        request(`/jobs/${jobId}/compensation-summary`).catch(() => null),
+        request(`/jobs/${jobId}/pay-equity-summary`).catch(() => null),
+        request(`/jobs/${jobId}/skill-gap-summary`).catch(() => null),
+        request(`/jobs/${jobId}/recommendations`).catch(() => null),
+        request(`/jobs/${jobId}/performance-summary`).catch(() => null),
+      ]);
+      return ok({
+        job_id: args.job_id,
+        state: job ? job.state : null,
+        requested_modules: job ? job.requested_modules : null,
+        compensation: comp || null,
+        pay_equity: payEq || null,
+        skill_gap: skill || null,
+        recommendations: rec || null,
+        performance: perf || null,
+      });
     }
 
-    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_wait_for_job": {
+      const jobId = encodeURIComponent(args.job_id);
+      const timeoutMs = (args.timeout_seconds ?? 120) * 1000;
+      const intervalMs = Math.max(500, (args.poll_interval_seconds ?? 3) * 1000);
+      const deadline = Date.now() + timeoutMs;
+      let job = await request(`/jobs/${jobId}`);
+      while (Date.now() < deadline) {
+        if (job && (job.state === "completed" || job.state === "failed")) break;
+        await new Promise((r) => setTimeout(r, intervalMs));
+        job = await request(`/jobs/${jobId}`);
+      }
+      if (!job || (job.state !== "completed" && job.state !== "failed")) {
+        throw new OptHRError(`Job ${args.job_id} did not finish within ${args.timeout_seconds ?? 120}s`, {
+          code: ERROR_CODES.JOB_TIMEOUT,
+        });
+      }
+      return ok({
+        job_id: args.job_id,
+        state: job.state,
+        last_event: (job.events || []).slice(-1)[0] || null,
+        requested_modules: job.requested_modules || [],
+      });
     }
 
     case "opthr_run_skill_gap": {
-      // 1) create the job
       const created = await request("/jobs", {
         method: "POST",
         body: {
@@ -313,43 +1084,38 @@ async function handle(name, args = {}) {
       });
       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,
+      if (args.document_url || args.document_path) {
+        const { blob, filename } = await resolveDocument({
+          document_url: args.document_url,
+          document_path: args.document_path,
+          fallbackName: "skills.pdf",
         });
-      } else {
-        // Use sample
+        await uploadJobDocument(jobId, blob, filename, "scheda_competenze_pdf");
+      } else if (args.use_sample_data === true) {
         const samples = await request("/samples");
-        const sample = (samples.items || []).find(s => s.mode === "skill_learn");
+        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,
-          });
+          await uploadJobDocument(jobId, blob, sample.name, sample.document_type);
         }
+      } else {
+        return ok({
+          job_id: jobId,
+          state: "needs_document",
+          message:
+            "Skill-gap job created, but no document was attached. Pass document_path / document_url, " +
+            "set use_sample_data=true for the bundled demo, or open the dashboard to upload manually.",
+          required_document_type: "scheda_competenze_pdf",
+          dashboard_url: DASHBOARD_URL,
+        });
       }
 
-      // 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.`,
+        message: `Skill-gap analysis started against role "${args.job_title}". Call opthr_wait_for_job to await completion.`,
       });
     }
 
@@ -359,7 +1125,7 @@ async function handle(name, args = {}) {
         body: {
           modules: ["compensation", "pay_equity"],
           employee_name: args.employee_name,
-          employee_gender: args.employee_gender || "female",
+          employee_gender: args.employee_gender || "unspecified",
           job_title: args.job_title,
           area: args.area || "nord_est",
           experience: args.experience || "3_5_anni",
@@ -372,27 +1138,116 @@ async function handle(name, args = {}) {
       });
       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,
+      if (args.document_url || args.document_path) {
+        const { blob, filename } = await resolveDocument({
+          document_url: args.document_url,
+          document_path: args.document_path,
+          fallbackName: "performance.pdf",
         });
+        await uploadJobDocument(jobId, blob, filename, "performance_pdf");
+      } else if (args.use_sample_data === true) {
+        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();
+          await uploadJobDocument(jobId, blob, perf.name, perf.document_type);
+        }
       }
 
       await request(`/jobs/${encodeURIComponent(jobId)}/start`, { method: "POST" });
+      return ok({
+        job_id: jobId,
+        state: "running",
+        message: `Compensation analysis started for ${args.employee_name}. Call opthr_wait_for_job to await completion.`,
+      });
+    }
+
+    case "opthr_run_pay_equity": {
+      const payrollSource = (args.payroll_source || "generic").toLowerCase();
+      const created = await request("/jobs", {
+        method: "POST",
+        body: {
+          modules: ["pay_equity"],
+          pay_equity_threshold_pct: args.threshold_pct ?? 5,
+          natural_language: args.natural_language || "Pay equity analysis",
+          metadata: {
+            natural_language: args.natural_language || "",
+            payroll_source: payrollSource,
+          },
+        },
+      });
+      const jobId = created.job_id;
+      if (!args.document_url && !args.document_path) {
+        return ok({
+          job_id: jobId,
+          state: "needs_document",
+          message:
+            "Pay-equity job created. Attach a pay_equity_csv via document_path / document_url or upload via the dashboard.",
+          required_document_type: "pay_equity_csv",
+          dashboard_url: DASHBOARD_URL,
+        });
+      }
+      const { blob, filename } = await resolveDocument({
+        document_url: args.document_url,
+        document_path: args.document_path,
+        fallbackName: "pay_equity.csv",
+      });
+      await uploadJobDocument(jobId, blob, filename, "pay_equity_csv");
+      await request(`/jobs/${encodeURIComponent(jobId)}/start`, { method: "POST" });
+      return ok({
+        job_id: jobId,
+        state: "running",
+        message: "Pay-equity analysis started. Call opthr_wait_for_job to await completion.",
+      });
+    }
 
+    case "opthr_run_rapporto_biennale": {
+      const payrollSource = (args.payroll_source || "generic").toLowerCase();
+      const sectionH =
+        args.section_h && typeof args.section_h === "object" ? args.section_h : undefined;
+      const created = await request("/jobs", {
+        method: "POST",
+        body: {
+          modules: ["equity_report"],
+          company_name: args.company_name || "",
+          section_h: sectionH,
+          natural_language: args.natural_language || `Rapporto Biennale per ${args.company_name || "azienda"}`,
+          metadata: {
+            natural_language: args.natural_language || "",
+            company_name: args.company_name || "",
+            workflow_kind: "rapporto_biennale",
+            payroll_source: payrollSource,
+          },
+        },
+      });
+      const jobId = created.job_id;
+      if (!args.document_url && !args.document_path) {
+        return ok({
+          job_id: jobId,
+          state: "needs_document",
+          message:
+            "Rapporto Biennale job created. Attach a payroll_csv via document_path / document_url. " +
+            "See resource opthr://rapporto-biennale-template for the column layout.",
+          required_document_type: "payroll_csv",
+          dashboard_url: DASHBOARD_URL,
+        });
+      }
+      const { blob, filename } = await resolveDocument({
+        document_url: args.document_url,
+        document_path: args.document_path,
+        fallbackName: "payroll.csv",
+      });
+      await uploadJobDocument(jobId, blob, filename, "payroll_csv");
+      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.`,
+        message:
+          `Rapporto Biennale started for ${args.company_name || "azienda"}. ` +
+          "Call opthr_wait_for_job, then opthr_export with format='xlsx' to download the Modello workbook.",
       });
     }
 
@@ -404,32 +1259,94 @@ async function handle(name, args = {}) {
       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.`,
-      });
-    }
+    case "opthr_export":
+      return ok(await downloadExport(args.job_id, args.format || "pdf", args.kind));
+
+    case "opthr_review_step":
+      return ok(await dispatchReviewStep(args));
 
     default:
-      throw new Error(`Unknown tool: ${name}`);
+      throw new OptHRError(`Unknown tool: ${name}`, { code: ERROR_CODES.BACKEND_ERROR });
   }
 }
 
+async function dispatchReviewStep({ job_id, step, decision = "approve", notes, payload = {} }) {
+  if (!job_id || !step) {
+    throw new OptHRError("opthr_review_step requires job_id and step.", {
+      code: ERROR_CODES.BACKEND_ERROR,
+    });
+  }
+  const jobId = encodeURIComponent(job_id);
+  const acknowledged = decision === "approve";
+
+  let path;
+  let body;
+  switch (step) {
+    case "compensation":
+      path = `/jobs/${jobId}/review/compensation`;
+      body = { acknowledged, note: notes || null };
+      break;
+    case "pay_equity":
+      path = `/jobs/${jobId}/review/pay-equity`;
+      body = { acknowledged, note: notes || null };
+      break;
+    case "skills":
+      path = `/jobs/${jobId}/review/skills`;
+      body = {
+        hard_skills: Array.isArray(payload.hard_skills) ? payload.hard_skills : [],
+        soft_skills: Array.isArray(payload.soft_skills) ? payload.soft_skills : [],
+      };
+      break;
+    case "recommendations":
+      path = `/jobs/${jobId}/review/recommendations`;
+      body = { recommendations_by_skill: payload.recommendations_by_skill || {} };
+      break;
+    case "manager_feedback":
+      if (!payload.markdown) {
+        throw new OptHRError("manager_feedback review requires payload.markdown.", {
+          code: ERROR_CODES.BACKEND_ERROR,
+        });
+      }
+      path = `/jobs/${jobId}/review/manager-feedback`;
+      body = {
+        markdown: payload.markdown,
+        rating_bucket: payload.rating_bucket || null,
+        comp_recommendation: payload.comp_recommendation || null,
+        hr_actions: payload.hr_actions || [],
+        sign: acknowledged && !!payload.signer_name,
+        signer_name: payload.signer_name || null,
+      };
+      break;
+    default:
+      throw new OptHRError(`Unknown review step: ${step}`, { code: ERROR_CODES.BACKEND_ERROR });
+  }
+
+  const r = await request(path, { method: "POST", body });
+  return { job_id: r.job_id, state: r.state, step, decision };
+}
+
+async function downloadExport(jobId, fmt, kind) {
+  const path =
+    fmt === "pdf"
+      ? `/jobs/${encodeURIComponent(jobId)}/report?engine=page${kind ? `&kind=${kind}` : ""}`
+      : `/jobs/${encodeURIComponent(jobId)}/export?format=${fmt}`;
+  const res = await request(path, { raw: true });
+  const buf = Buffer.from(await res.arrayBuffer());
+  return {
+    job_id: jobId,
+    format: fmt,
+    pdf_engine: fmt === "pdf" ? res.headers.get("x-opthr-pdf-engine") || "page" : undefined,
+    filename: filenameFromDisposition(
+      res.headers.get("content-disposition"),
+      `OptHR-${jobId}.${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.`,
+  };
+}
+
 /* ----------------------------------------------------------------- */
 /* MCP server bootstrap                                               */
 /* ----------------------------------------------------------------- */
@@ -437,27 +1354,58 @@ async function handle(name, args = {}) {
 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.",
+    title: "OptHR — Compensation, Pay-Equity & Skill Gap agents",
+    version: PKG_VERSION,
+    description:
+      "Run OptHR's Compensation, Pay-Equity, Skill Gap and Rapporto Biennale agents directly from chat. " +
+      "Audit-ready reasoning, EU Pay Directive coverage, exportable reports.",
     websiteUrl: "https://github.com/Dunic15/OptHRr",
-    ...(OPTHR_ICONS ? { icons: OPTHR_ICONS } : {}),
+    ...ICON_FIELDS,
   },
-  { capabilities: { tools: {} } },
+  { capabilities: { tools: {}, resources: {}, prompts: {} } },
 );
 
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
 
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-  const { name, arguments: args = {} } = request.params;
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({ resources: RESOURCES }));
+
+server.setRequestHandler(ReadResourceRequestSchema, async (req) => ({
+  contents: [await readResource(req.params.uri)],
+}));
+
+server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: PROMPTS }));
+
+server.setRequestHandler(GetPromptRequestSchema, async (req) =>
+  getPrompt(req.params.name, req.params.arguments || {}),
+);
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const { name, arguments: args = {} } = req.params;
+  const started = Date.now();
   try {
-    return await handle(name, args);
+    const result = await handle(name, args);
+    logEvent({
+      event: "tool_call",
+      tool: name,
+      outcome: "ok",
+      latency_ms: Date.now() - started,
+    });
+    return result;
   } catch (err) {
+    const code = err && err.code ? err.code : ERROR_CODES.BACKEND_ERROR;
+    logEvent({
+      event: "tool_call",
+      tool: name,
+      outcome: "error",
+      error_code: code,
+      status: err && err.status,
+      latency_ms: Date.now() - started,
+    });
     return fail(err);
   }
 });
 
 const transport = new StdioServerTransport();
 server.connect(transport).then(() => {
-  console.error(`[opthr-mcp-server] connected on stdio · API base = ${BASE}`);
+  logEvent({ event: "connected", api_base: BASE });
 });