@opthr/mcp-server 0.2.0 → 0.2.3

package/README.md

@@ -1,42 +1,76 @@
 # @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.
+Model Context Protocol server for **OptHR** — exposes the OptHR product surfaces plus the Compensation, Pay-Equity, Skill Gap and Rapporto Biennale agents to MCP-aware clients (Claude Desktop, Cursor, etc.).
 
-This is a thin Node.js wrapper around the OptHR FastAPI backend (`http://localhost:8765` by default). All tools are real — no mocks.
+This is a thin Node.js wrapper around the OptHR FastAPI backend. All tools call the **same endpoints** the OptHR web app uses — there is no separate "MCP backend". The MCP cannot run analyses without a reachable hosted (or local) OptHR backend.
 
-## Tools exposed
+## Install
+
+```bash
+npx -y @opthr/mcp-server@latest
+```
+
+Requires Node 18+.
+
+## Tools
+
+The public MCP surface is deliberately small — 10 tools. Read-only browsing (job lists, samples, schemas, product URLs) is exposed as **resources**, not tools.
 
 | 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 |
+| `opthr_health` | Sanity-check connectivity and active LLM |
+| `opthr_run_skill_gap` | Skill gap vs a target role |
+| `opthr_run_compensation` | Compensation + pay-equity for a single employee |
+| `opthr_run_pay_equity` | Pay-equity from a payroll CSV |
+| `opthr_run_rapporto_biennale` | Legge 162/2021 workflow — full Modello XLSX (Sez B/C/E/F/H) |
+| `opthr_wait_for_job` | Poll until `completed` / `failed` or timeout |
+| `opthr_get_job_summary` | Compact merged summary (comp + pay-equity + skill-gap + recs) |
+| `opthr_export` | Download PDF / XLSX / DOCX / PPTX / JSON |
+| `opthr_answer` | Send a clarification to a paused job |
+| `opthr_review_step` | Approve / revise compensation, pay_equity, skills, recommendations, or manager_feedback |
+
+## Resources
+
+| URI | Mime | What it gives clients |
+|---|---|---|
+| `opthr://dashboard` | json | Current dashboard URL + API base |
+| `opthr://figma` | json | Configured Figma handoff URL |
+| `opthr://product-surfaces` | json | Dashboard / landing / API / Figma metadata |
+| `opthr://samples` | json | List of bundled sample documents |
+| `opthr://schemas` | json | JobState, JobModule, DocumentType, UserRole enums, review payloads, error codes |
+| `opthr://tool-guide` | md | When to use which tool |
+| `opthr://recent-jobs` | json | Live: last 20 analyses for the tenant |
+| `opthr://sample-payroll-csv` | csv | Minimal payroll CSV template |
+| `opthr://rapporto-biennale-template` | json | Legge 162/2021 column layout |
 
-## Install + run locally
+## Prompts
 
-Requires Node 18+.
+- `opthr-quick-comp` — one-shot compensation + pay-equity for a single employee
+- `opthr-explain-job` — pull a job and summarise what was computed
+- `opthr-rapporto-biennale` — Rapporto Biennale workflow including trasmissione
+- `opthr-calibrate-team` — loop comp analyses for a team
+
+## Local setup (against a backend on your laptop)
 
 ```bash
+# Start the OptHR FastAPI backend
+cd backend && uvicorn HR_Suite_Agents.api.app:app --reload --port 8765
+
+# Run the MCP (stdio)
 cd mcp-server
 npm install
-npm test          # smoke-tests the OptHR backend connection
-npm start         # boots the MCP server on stdio
+npm test      # smoke-tests the backend connection
+npm start
 ```
 
-## Wire it into Claude Desktop
-
-Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
 
 ```json
 {
   "mcpServers": {
     "opthr": {
-      "command": "node",
-      "args": ["/Users/YOU/Desktop/HR_startup/mcp-server/src/index.js"],
+      "command": "npx",
+      "args": ["-y", "@opthr/mcp-server@latest"],
       "env": {
         "OPTHR_API_BASE": "http://localhost:8765",
         "OPTHR_DEV_ROLE": "admin_hr",
@@ -47,32 +81,132 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 }
 ```
 
-After publishing to npm, replace `command/args` with:
+## Hosted setup (production / customer demos)
+
+For the current OptHR pilot backend, use:
+
+```text
+OPTHR_API_BASE=https://opthrr.onrender.com
+```
+
+Create the API key from the OptHR dashboard:
+
+1. Open `https://opthrr.onrender.com/prototype/OptHR%20Redesign.html`.
+2. Log in as a tenant admin.
+3. Go to `Integrate -> REST API`.
+4. Click `Generate key`.
+5. Use the generated `optkey_live_...` value as `OPTHR_API_KEY`.
 
 ```json
-"command": "npx",
-"args": ["-y", "@opthr/mcp-server@latest"]
+{
+  "mcpServers": {
+    "opthr": {
+      "command": "npx",
+      "args": ["-y", "@opthr/mcp-server@latest"],
+      "env": {
+        "OPTHR_API_BASE": "https://opthrr.onrender.com",
+        "OPTHR_API_KEY": "optkey_live_xxx",
+        "OPTHR_DOCUMENT_SEARCH_ROOT": "/Users/<you>/Documents/OptHR"
+      }
+    }
+  }
+}
 ```
 
-Then restart Claude Desktop and try:
+The hosted backend must:
+
+1. Be reachable at `OPTHR_API_BASE`.
+2. Accept `X-API-Key` — generate keys from the dashboard/API so they carry tenant scope and role.
+3. Enforce tenant scoping and rate limits on every endpoint the MCP touches.
+
+See [`docs/MCP_PLATFORM_READINESS.md`](../docs/MCP_PLATFORM_READINESS.md) for the production checklist.
 
-> "Run a skill gap analysis for a Senior Backend Engineer role using the OptHR sample data."
+## Document handling
 
-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.
+Analysis tools accept three ways to provide source documents:
+
+1. **`document_url`** — `http://`, `https://`, or `file://` URL.
+2. **`document_path`** — absolute local path, or a path relative to `OPTHR_DOCUMENT_SEARCH_ROOT`.
+3. **`use_sample_data: true`** — explicit opt-in to the backend's bundled demo files.
+
+Sample data is **never** attached implicitly. If neither `document_url`, `document_path`, nor `use_sample_data` is supplied, the tool returns `state: needs_document` and a dashboard URL for manual upload.
+
+If `OPTHR_DOCUMENT_SEARCH_ROOT` is set, any resolved `document_path` (and any `file://` URL) must live inside that directory after `realpath` resolution. Symlink escape attempts return `DOCUMENT_NOT_FOUND`.
 
 ## 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` |
+| `OPTHR_API_BASE` | `http://localhost:8765` | FastAPI backend base URL |
+| `OPTHR_API_KEY` | — | Sent as `X-API-Key` (hosted/production) |
+| `OPTHR_BEARER_TOKEN` | — | Sent as `Authorization: Bearer …` |
+| `OPTHR_DEV_ROLE` | `admin_hr` | Legacy fallback `X-Role` (local dev only) |
+| `OPTHR_DEV_TENANT_ID` | `tenant_demo` | Legacy fallback `X-Tenant-ID` (local dev only) |
+| `OPTHR_DOCUMENT_SEARCH_ROOT` | — | Restrict `document_path` to this directory |
+| `OPTHR_DASHBOARD_URL` | `${OPTHR_API_BASE}/OptHR%20Redesign.html#/app` | Dashboard URL exposed via resources |
+| `OPTHR_LANDING_URL` | `https://opthr-landing-site.vercel.app/` | Public landing URL |
+| `OPTHR_FIGMA_URL` | — | Optional Figma handoff URL |
+| `OPTHR_TELEMETRY_URL` | — | Optional HTTPS endpoint to POST one JSON line per tool call (fire-and-forget). |
+| `OPTHR_TELEMETRY_AUTH` | — | Optional `Authorization` header value sent with each telemetry POST (e.g. `Bearer abc`). |
+
+## Error codes
+
+The MCP returns structured errors with one of these codes (also surfaced via `opthr://schemas`):
+
+| Code | Meaning |
+|---|---|
+| `BACKEND_UNREACHABLE` | The MCP can't reach `OPTHR_API_BASE` at all. |
+| `AUTH_FAILED` | Backend returned 401/403 — API key, bearer, or role missing/invalid. |
+| `DOCUMENT_NOT_FOUND` | `document_url` / `document_path` resolution failed. |
+| `INVALID_DOCUMENT_TYPE` | A scheme or type check rejected the input. |
+| `JOB_TIMEOUT` | `opthr_wait_for_job` exhausted its deadline. |
+| `BACKEND_ERROR` | Any other non-2xx backend response. |
+
+See [`docs/MCP_ERROR_CATALOG.md`](../docs/MCP_ERROR_CATALOG.md) for symptoms, root-cause analysis, and runbook steps for each code (plus the `429` rate-limit response).
+
+## Observability
+
+The MCP logs one structured JSON line per tool call to **stderr** (stdout is reserved for the MCP transport):
+
+```json
+{"ts":"…","svc":"opthr-mcp-server","version":"0.2.2","tenant_id":"tenant_demo",
+ "backend_host":"api.opthr.io","event":"tool_call","tool":"opthr_run_compensation",
+ "outcome":"ok","latency_ms":1820}
+```
+
+PII, salaries, raw documents, and request/response bodies are **never** logged — by design, only the tool name, latency, outcome, and error code.
+
+### Telemetry sink
+
+Set `OPTHR_TELEMETRY_URL` to an HTTPS endpoint to also POST each line, fire-and-forget. The payload is exactly the JSON shown above. Telemetry failures (HTTP errors, DNS failures, timeouts) are swallowed — they never affect tool calls.
 
-## How it differs from the prototype `api.js`
+```jsonc
+// claude_desktop_config.json
+{
+  "mcpServers": {
+    "opthr": {
+      "command": "npx",
+      "args": ["-y", "@opthr/mcp-server@latest"],
+      "env": {
+        "OPTHR_API_BASE": "https://<hosted-api>",
+        "OPTHR_API_KEY": "optkey_live_xxx",
+        "OPTHR_TELEMETRY_URL": "https://telemetry.opthr.io/mcp",
+        "OPTHR_TELEMETRY_AUTH": "Bearer <ingest-token>"
+      }
+    }
+  }
+}
+```
+
+## Publishing
+
+```bash
+# from mcp-server/
+npm version patch        # → 0.2.x
+npm publish --access public
+```
 
-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).
+`files` in `package.json` already pins the npm tarball to `src/`, `assets/`, and `README.md`.
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.",
+  "version": "0.2.3",
+  "description": "Model Context Protocol server for OptHR — Compensation, Pay-Equity, Skill Gap and Rapporto Biennale agents for Claude Desktop, Cursor, and other MCP clients.",
   "type": "module",
   "bin": {
     "opthr-mcp-server": "src/index.js"
@@ -25,6 +25,8 @@
     "opthr",
     "compensation",
     "skill-gap",
+    "pay-equity",
+    "rapporto-biennale",
     "anthropic"
   ],
   "author": "OptHR",