@frihet/mcp-server 1.16.6 → 2.0.0

package/README.md

@@ -20,9 +20,10 @@
   <a href="https://www.npmjs.com/package/@frihet/mcp-server"><img src="https://img.shields.io/npm/dm/@frihet/mcp-server?style=flat&color=18181b&labelColor=09090b&label=downloads" alt="npm downloads"></a>
   <a href="https://smithery.ai/servers/frihet/frihet-mcp"><img src="https://smithery.ai/badge/frihet/frihet-mcp" alt="Smithery installs"></a>
   <a href="https://registry.modelcontextprotocol.io/?q=io.frihet"><img src="https://img.shields.io/badge/MCP_Registry-io.frihet%2Ferp-4A90D9?style=flat&logo=anthropic&logoColor=white" alt="MCP Registry"></a>
+  <a href="https://github.com/mcp/io.frihet/erp"><img src="https://img.shields.io/badge/GitHub_MCP_Registry-Listed-18181b?style=flat&labelColor=09090b&logo=github" alt="Listed in GitHub MCP Registry"></a>
   <a href="https://github.com/Frihet-io/frihet-mcp/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-18181b?style=flat&labelColor=09090b" alt="license"></a>
-  <img src="https://img.shields.io/badge/tools-157-18181b?style=flat&labelColor=09090b" alt="157 tools">
-  <img src="https://img.shields.io/badge/node-%3E%3D18-18181b?style=flat&labelColor=09090b" alt="node >=18">
+  <img src="https://img.shields.io/badge/catalogue-156_operations-18181b?style=flat&labelColor=09090b" alt="156 canonical catalogue operations">
+  <img src="https://img.shields.io/badge/node-22.23.4%2B%20%7C%2024.22.1%2B%20%7C%2026.12.1%2B-18181b?style=flat&labelColor=09090b" alt="Node 22.23.4+ (22.x), 24.22.1+ (24.x), or 26.12.1+ (26.x)">
   <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-18181b?style=flat&labelColor=09090b" alt="TypeScript"></a>
 </p>
 
@@ -34,20 +35,41 @@
 
 ## Distribution
 
-| Channel | Status | Install |
-|---------|--------|---------|
-| **npm** | Live | `npx @frihet/mcp-server` |
-| **Remote endpoint** | Live | `https://mcp.frihet.io/mcp` (zero install, OAuth or API key) |
-| **Smithery** | Live | [smithery.ai/servers/frihet/frihet-mcp](https://smithery.ai/servers/frihet/frihet-mcp) |
-| **MCP Registry** | Live | [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io/?q=io.frihet) |
-| **Glama** | Live | [glama.ai/mcp/servers/Frihet-io/frihet-mcp](https://glama.ai/mcp/servers/Frihet-io/frihet-mcp) |
-| **mcp.so** | Auto-index (unverified) | [mcp.so](https://mcp.so) — indexes from npm + GitHub |
-| **PulseMCP** | Auto-index (unverified) | [pulsemcp.com](https://pulsemcp.com) — indexes from npm + GitHub |
-| **Cursor Marketplace** | Coming soon | [cursor.com/marketplace](https://cursor.com/marketplace) |
-| **ChatGPT Apps** | Coming soon | [chatgpt.com](https://chatgpt.com) |
-| **Anthropic Claude Directory** | Coming soon | [claude.ai/settings/connectors](https://claude.ai/settings/connectors) |
-
-> **Tool count:** the package (1.16.6) ships all 157 tools, same as the remote endpoint (`mcp.frihet.io`).
+Reviewed 2026-10-31. A directory entry is not proof of a working installation, vendor endorsement, or adoption. Package releases, hosted deployments and reviewed app versions are independent.
+
+### Use Frihet
+
+| Channel | Availability | Entry point |
+|---|---|---|
+| npm | Published package; see its own release version | [npm](https://www.npmjs.com/package/@frihet/mcp-server) · `npx @frihet/mcp-server` |
+| Remote MCP | Hosted connection route; OAuth or API key | `https://mcp.frihet.io/mcp` |
+| ChatGPT app | Published 1.0.2, confirmed by the maintainer; not the separate 1.0.3 candidate | [Frihet in ChatGPT](https://chatgpt.com/plugins/plugin_asdk_app_6ac6b51bd7648191a0696bd1e725bfe6) |
+
+### Find Frihet
+
+These are discovery links, not a count of independent integrations. Some third-party descriptions and cached copies are outdated.
+
+| Surface | Evidence at review | Entry |
+|---|---|---|
+| Official MCP Registry | Specific registry entry indexed | [io.frihet/erp](https://registry.modelcontextprotocol.io/?q=io.frihet) |
+| GitHub MCP Registry | Listing content retrieved; not a GitHub-verified connector claim | [Frihet ERP](https://github.com/mcp/io.frihet/erp) |
+| ToolSDK MCP Registry | Entry read in upstream repository | [Registry entry](https://github.com/toolsdk-ai/toolsdk-mcp-registry/blob/main/packages/finance-fintech/frihet-mcp.json) |
+| Glama | Specific listing indexed; summary needs refresh | [Listing](https://glama.ai/mcp/servers/Frihet-io/frihet-mcp) |
+| Smithery | Specific listing indexed; live recheck blocked | [Listing](https://smithery.ai/servers/%40frihet/frihet-mcp) |
+| mcpservers.org | Listing content retrieved; description outdated | [Listing](https://mcpservers.org/servers/frihet-io/frihet-mcp) |
+| Cursor Directory | Community listing retrieved; separate from the official Cursor Marketplace | [Listing](https://cursor.directory/plugins/mcp-frihet) |
+| mcp.so | Specific listing indexed; current installation not verified | [Listing](https://mcp.so/servers/frihet-mcp) |
+
+Frihet also appears in **[punkpeye/awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers)**, **[TensorBlock/awesome-mcp-servers](https://github.com/TensorBlock/awesome-mcp-servers/blob/main/docs/finance--crypto.md)** and **[ever-works/awesome-mcp-servers](https://github.com/ever-works/awesome-mcp-servers/blob/master/details/frihetmcp-server.md)**. Their retrieved descriptions still use an old tool count; the ever-works entry also links to a non-canonical repository URL. Use this repository's install instructions rather than copying those descriptions.
+
+### Pending or not reverified
+
+- **Docker:** [submission PR #1711](https://github.com/docker/mcp-registry/pull/1711) remains open; do not describe it as published in Docker's catalog.
+- **Cline:** [submission #2053](https://github.com/cline/mcp-marketplace/issues/2053) remains open; client compatibility is not marketplace approval.
+- **PulseMCP:** historically reported; a current primary listing was not retrieved in this review.
+- **Official Cursor Marketplace and Claude Directory:** public approval was not reverified here. This does not change existing submissions or manual MCP installation support.
+
+> **Surface truth:** the catalogue contains 156 canonical operations. The local full profile serves 161 tool names, 11 resources, and 10 prompts (156 canonical operations plus 5 fiscal aliases). The hosted grouped profile serves 164 tool names, 7 resources, and 10 prompts (the same names plus 3 discovery tools, with API-backed resources kept local-only). The separately reviewed OpenAI profile serves 33 tool names, 0 resources, and 0 prompts. Catalogue membership is not a promise that a backing API is enabled for every workspace.
 
 ---
 
@@ -60,9 +82,13 @@ You:     "Create an invoice for TechStart SL, 40 hours of consulting at 75 EUR/h
 Claude:  Done. Invoice INV-2026-089 created. Total: 3,000.00 EUR + 21% IVA = 3,630.00 EUR.
 ```
 
-157 tools. 11 resources. 10 prompts. Structured output on every tool. Zero boilerplate.
+156 canonical operations. Five fiscal aliases. Ten prompts. The local package serves 11 resources; the hosted Worker deliberately serves the 7 static resources, while API-backed workspace resources remain local-profile only.
 
-<!-- v1.12.0-beta.1 — D4-B megasprint: HR (9), payroll (2), onboarding (2), permissions (2), period close (3), webhook test (1) = +19 = 157 tools total -->
+<!-- v1.12.0-beta.1 — D4-B megasprint: HR (9), payroll (2), permissions (2), period close (3), webhook test (1) = +17 = 156 tools total
+     (Onboarding's two tools were withdrawn via #124 because the Frihet-ERP
+      /v1/onboarding/* family does not exist; the original +19 = 158 count
+      dropped to +17 = 156. The withdrawal is permanent until Frihet-ERP
+      ships the family.) -->
 
 ---
 
@@ -80,8 +106,32 @@ When you're ready for your real data, drop the flag and add your key ([app.frihe
 
 ---
 
+## For AI agents
+
+If you are an agent reading this repository rather than a person reading a page, everything you need is machine-readable and generated from the running server — you do not have to parse this README.
+
+| What | Where |
+|------|-------|
+| Onboarding contract: quickstart per client, auth, safe workflow, human-authority tool lists, error recovery | [`docs/agent-onboarding.json`](./docs/agent-onboarding.json) — also shipped inside the npm package |
+| Per-tool capability truth: `callability`, `writesFrihet`, `externalInteraction`, `externalSideEffects` | `_meta["io.frihet/capability"]` on every entry of `tools/list` |
+| How to behave once connected | the `instructions` string returned by `initialize` — your client hands it to you automatically |
+
+Three rules the contract encodes, in short:
+
+1. **Orient before acting.** `get_business_context` and the `frihet://tax/rates` resource decide the correct fiscal treatment. Do not recall a Spanish tax rate from memory.
+2. **Draft, show, stop.** `create_invoice`, `create_quote` and `create_credit_note` all default to `status=draft` — no fiscal number, no hash, nothing sent to a tax authority. Present the draft and hand back.
+3. **Human authority is not yours to assume.** Any tool with a non-empty `externalSideEffects` reaches a client's inbox, a webhook, money, or AEAT / VeriFactu / TicketBAI / FACe. Several also take `confirm=true`; that flag records a human decision — never set it to satisfy your own plan.
+
+`docs/agent-onboarding.json` is regenerated from the live surface by `npm run generate:agent-onboarding` and gated in CI by `npm run gate:agent-onboarding`, so its tool lists and counts cannot drift from the server.
+
+---
+
 ## Install
 
+Local npm/stdio installs require Node **22.23.4+ (22.x), 24.22.1+ (24.x), or 26.12.1+ (26.x)**, covering the [October 2026 Node security fixes](https://nodejs.org/en/blog/vulnerability/october-2026-security-releases). Node 20 is end-of-life: upgrade the Node runtime used by your MCP client before starting the server. CI uses Node 22.23.4.
+
+This source change does not update previously published npm package metadata or users' installed Node runtimes. Updated package metadata requires a separate npm release; users can upgrade their runtime now. The remote Cloudflare Worker has a separate runtime and release process.
+
 ### One-line (Claude Code, Cursor, Copilot, Codex, Windsurf, Gemini CLI, and more)
 
 ```bash
@@ -97,16 +147,47 @@ This repository is also a Claude Code plugin (`frihet-erp`): installing it wires
 claude --plugin-dir /path/to/frihet-mcp
 ```
 
-Once available in the community marketplace:
+Marketplace availability is pending. Use the local plugin command above or the Claude Code MCP command below to connect today.
+
+Skill invocation: `/frihet-erp:frihet-mcp`. The bundled `.mcp.json` launches `@frihet/mcp-server` via `npx` — set `FRIHET_API_KEY` in your environment (get one at [app.frihet.io](https://app.frihet.io) → Settings → API keys).
+
+The [portable Claude plugin preview](plugins/claude/frihet-erp/README.md) bundles
+real receivables, document-drafting and monthly-review skills with the existing
+public remote MCP. Load `plugins/claude/frihet-erp` in Claude Code or upload a ZIP
+of that folder in chat/Cowork. Its skills guide behavior; they do not filter the
+hosted catalogue or establish Directory approval. The root local MCP setup above
+keeps its existing API-key configuration.
+
+### Claude Code — one command
 
-```text
-/plugin marketplace add anthropics/claude-plugins-community
-/plugin install frihet-erp@claude-community
+```bash
+claude mcp add frihet -s user -e FRIHET_API_KEY=fri_your_key_here -- npx -y @frihet/mcp-server
+claude mcp list          # verify: frihet ✓ Connected
 ```
 
-Skill invocation: `/frihet-erp:frihet-mcp`. The bundled `.mcp.json` launches `@frihet/mcp-server` via `npx` — set `FRIHET_API_KEY` in your environment (get one at [app.frihet.io](https://app.frihet.io) → Settings → API keys).
+The CLI owns the config file, so there is nothing to hand-edit and no path to get wrong. (User scope writes `~/.claude.json`, not `~/.claude/mcp.json`.)
+
+### Codex CLI — one command
+
+```bash
+codex mcp add frihet --env FRIHET_API_KEY=fri_your_key_here -- npx -y @frihet/mcp-server
+codex mcp list           # verify
+```
+
+Codex config is **TOML**, not JSON. `codex mcp add` writes:
+
+```toml
+[mcp_servers.frihet]
+command = "npx"
+args = ["-y", "@frihet/mcp-server"]
+
+[mcp_servers.frihet.env]
+FRIHET_API_KEY = "fri_your_key_here"
+```
+
+> Pasting a JSON `mcpServers` block into `~/.codex/config.toml` is a TOML parse error that takes down your **whole** Codex config, not just this server. Use the command above.
 
-### Claude Code / Claude Desktop
+### Claude Desktop, Cursor, Windsurf, Cline — JSON config
 
 ```json
 {
@@ -124,14 +205,12 @@ Skill invocation: `/frihet-erp:frihet-mcp`. The bundled `.mcp.json` launches `@f
 
 | Tool | Config file |
 |------|------------|
-| Claude Code | `~/.claude/mcp.json` |
 | Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` |
 | Cursor | `.cursor/mcp.json` or `~/.cursor/mcp.json` |
 | Windsurf | `~/.windsurf/mcp.json` |
 | Cline | VS Code settings or `.cline/mcp.json` |
-| Codex CLI | `~/.codex/config.toml` (MCP section) |
 
-The JSON config is identical for all tools. Only the file path changes.
+The JSON above is identical for these four clients; only the file path changes. Claude Code and Codex are **not** in this table — they manage their own config through the CLI commands shown above.
 
 ### Remote (no install)
 
@@ -222,7 +301,7 @@ Talk to your ERP. These are real prompts, not marketing copy.
 
 ## What to expect
 
-This MCP is a **structured data interface** -- you describe what you want in natural language, and the AI creates, queries, or modifies business records in Frihet. Most of the 157 tools are CRUD operations over the REST API; the rest are read-only summaries and fiscal/e-invoice actions.
+This MCP is a **structured data interface** -- you describe what you want in natural language, and the AI creates, queries, or modifies business records in Frihet. Most of the 156 canonical operations are CRUD operations over the REST API; the rest are read-only summaries and fiscal/e-invoice actions. Alias and discovery names are counted separately.
 
 **Works great:**
 
@@ -249,7 +328,7 @@ If you need to digitize paper invoices or receipts, extract the data first (e.g.
 
 ---
 
-## Tools (157)
+## Catalogue operations (156)
 
 ### Invoices (12)
 
@@ -259,12 +338,12 @@ If you need to digitize paper invoices or receipts, extract the data first (e.g.
 | `get_invoice` | Get full invoice details by ID |
 | `create_invoice` | Create a new invoice with line items |
 | `update_invoice` | Update any invoice field |
-| `delete_invoice` | Permanently delete an invoice |
+| `delete_invoice` | Delete a draft invoice; a sent/paid one is cancelled, not destroyed (`confirm=true` required) |
 | `search_invoices` | Find invoices by client name, date, or status |
-| `send_invoice` | Email invoice to client (PDF attachment) |
+| `send_invoice` | Email invoice to client (PDF attachment) — reaches a third party, `confirm=true` required |
 | `mark_invoice_paid` | Mark an invoice as paid with optional payment date |
-| `get_invoice_pdf` | Get a download URL for the invoice PDF |
-| `get_invoice_einvoice` | Get the e-invoice XML for a given invoice ID |
+| `get_invoice_pdf` | Get bounded invoice PDF bytes as base64 |
+| `get_invoice_einvoice` | Get bounded XML or Factur-X PDF bytes for an invoice |
 | `create_credit_note` | Create a credit note linked to an existing invoice |
 | `apply_late_fee` | Apply a late payment fee to an overdue invoice |
 
@@ -329,7 +408,7 @@ If you need to digitize paper invoices or receipts, extract the data first (e.g.
 | `get_quote` | Get quote details |
 | `create_quote` | Draft a new quote |
 | `update_quote` | Modify a quote |
-| `delete_quote` | Delete a quote |
+| `delete_quote` | Delete only a clean draft with no delivery, response, attachment, or conversion evidence; refuse protected drafts; cancel non-drafts (`confirm=true` required) |
 | `send_quote` | Email quote to client for acceptance |
 
 ### Webhooks (6)
@@ -365,7 +444,7 @@ If you need to digitize paper invoices or receipts, extract the data first (e.g.
 | `face_status` | Poll submission status from FACe for a submitted invoice |
 | `ticketbai_submit` | Submit TicketBAI fiscal record to Basque Country tax authority (Hacienda) |
 | `ticketbai_status` | Poll TicketBAI submission status from the Basque tax authority |
-| `ksef_submit` | Submit invoice to KSeF (Poland) — *stub: transport is infra-ready in Frihet-ERP but not yet exposed as a live endpoint (production gated on KSeF cert); returns a labeled "unavailable" error until activated* |
+| `ksef_submit` | **NOT_DEPLOYED** — Submit invoice to KSeF (Poland) — *stub: transport is infra-ready in Frihet-ERP but not yet exposed as a live endpoint (production gated on KSeF cert); returns a labeled "unavailable" error until activated* |
 
 ### Time Tracking (6)
 
@@ -389,15 +468,15 @@ If you need to digitize paper invoices or receipts, extract the data first (e.g.
 | `pause_recurring_invoice` | Pause an active template — no invoices generated while paused |
 | `resume_recurring_invoice` | Resume a paused template — next invoice on next scheduled cycle |
 | `delete_recurring_invoice` | Permanently delete a template (confirm=true required) |
-| `run_recurring_now` | Manually trigger immediate generation of the next invoice instance |
+| `run_recurring_now` | Generate the next recurring invoice with explicit `confirm=true` in full and grouped modes; workspace settings may trigger fiscal issuance, submission and webhooks |
 
 ### Team Management (4)
 
 | Tool | What it does |
 |------|-------------|
-| `list_team_members` | List all workspace members with role and invite status |
-| `invite_team_member` | Invite a new member by email with role (admin/member/viewer) |
-| `update_team_member_role` | Change an existing member's role |
+| `list_team_members` | List active members + pending invites (owner excluded) |
+| `invite_team_member` | Invite a new member by email with role (admin/editor/accountant/viewer) |
+| `update_team_member_role` | Change an existing member's role (admin/editor/accountant/viewer) |
 | `remove_team_member` | Remove a member from the workspace (confirm=true required) |
 
 ### Gestoria — Accountants (5)
@@ -437,17 +516,17 @@ If you need to digitize paper invoices or receipts, extract the data first (e.g.
 
 | Tool | What it does |
 |------|-------------|
-| `frihet_modelo_415_summary` | M415 annual operations >€3,005 (Canarias equivalent of M347) |
-| `frihet_modelo_425_summary` | M425 annual IGIC recap for Canary Islands businesses |
-| `frihet_modelo_418_summary` | M418 monthly IGIC return for large enterprises (grandes empresas) |
-| `frihet_aiem_calculate` | Calculate AIEM (Arbitrio Importación) for imported/produced goods in Canarias |
+| `frihet_modelo_415_summary` | M415 annual operations >€3,005 (Canarias equivalent of M347) — not deployed, returns `NOT_DEPLOYED` |
+| `frihet_modelo_425_summary` | M425 annual IGIC recap for Canary Islands businesses — not deployed, returns `NOT_DEPLOYED` |
+| `frihet_modelo_418_summary` | M418 monthly individual IGIC return, régimen especial del grupo de entidades — not deployed, returns `NOT_DEPLOYED` |
+| `frihet_aiem_calculate` | AIEM (Arbitrio Importación) calculation for Canarias — not deployed, returns `NOT_DEPLOYED` |
 
 ### Impuesto sobre Sociedades — Corporate Tax (2)
 
 | Tool | What it does |
 |------|-------------|
-| `frihet_modelo_200_summary` | Modelo 200 annual IS return (taxable base, deductions, net payable) |
-| `frihet_modelo_202_summary` | Modelo 202 installment payments (1P April, 2P October, 3P December) |
+| `frihet_modelo_200_summary` | Modelo 200 annual IS return — not deployed, returns `NOT_DEPLOYED` |
+| `frihet_modelo_202_summary` | Modelo 202 installment payments (1P/2P/3P) — not deployed, returns `NOT_DEPLOYED` |
 
 ### Bank Categorization Rules (2)
 
@@ -466,7 +545,7 @@ If you need to digitize paper invoices or receipts, extract the data first (e.g.
 | `update_deposit` | Update deposit fields |
 | `delete_deposit` | Delete a deposit (confirm=true required) |
 | `apply_deposit` | Apply a deposit balance against an invoice |
-| `refund_deposit` | Issue a refund for a deposit |
+| `refund_deposit` | Record a deposit refund in Frihet bookkeeping with `confirm=true`; optional `amount` records that portion, omission records the remaining refundable balance. Does not transfer money |
 
 ### Vendors (5)
 
@@ -495,7 +574,7 @@ If you need to digitize paper invoices or receipts, extract the data first (e.g.
 | `get_modelo_303_summary` | Quarterly IVA return (Modelo 303) — collected vs deductible, net payable |
 | `get_modelo_130_summary` | Quarterly IRPF installment for self-employed (Modelo 130) |
 | `get_modelo_390_summary` | Annual IVA summary (Modelo 390) |
-| `get_modelo_180_summary` | Annual withholding summary for rentals (Modelo 180) |
+| `get_modelo_180_summary` | Annual withholding summary for rentals (Modelo 180) — not deployed, returns `NOT_DEPLOYED` |
 | `get_modelo_347_summary` | Annual third-party transactions >€3,005 (Modelo 347) |
 | `verifactu_status` | Get VeriFactu submission status for a fiscal record |
 | `verifactu_resubmit` | Resubmit a rejected VeriFactu fiscal record |
@@ -542,57 +621,69 @@ If you need to digitize paper invoices or receipts, extract the data first (e.g.
 | `leave_list` | List leave requests with filters (user, status, date range) |
 | `attendance_clock_in` | Record clock-in for an employee |
 | `attendance_clock_out` | Record clock-out for an employee |
-| `overtime_report` | Generate overtime report for a period |
+| `overtime_report` | Read daily/weekly overtime, aggregate minutes/hours, and compliance alerts computed over the selected YYYY or YYYY-MM records |
 | `anomaly_list` | List attendance anomalies (missing punches, excessive overtime) |
 
 ### Payroll (2)
 
 | Tool | What it does |
 |------|-------------|
-| `payroll_export` | Export payroll data for a period (CSV/PDF for gestoría) |
-| `payroll_checklist` | Generate pre-payroll checklist: pending leaves, anomalies, overtime |
+| `payroll_export` | Read normalized payroll-ready employee data; the format value is an echoed destination label, not a generated file |
+| `payroll_checklist` | List payable employees with payroll-profile readiness, missing fields, and monthly review state |
 
-### Onboarding (2)
+### Onboarding — withdrawn via #124
 
-| Tool | What it does |
-|------|-------------|
-| `onboarding_status` | Get onboarding completion status for the current workspace |
-| `onboarding_persona_set` | Set or update the business persona (freelancer, SME, gestoría, etc.) |
+The `onboarding_status` and `onboarding_persona_set` tools were withdrawn because the Frihet-ERP `/v1/onboarding/*` family does not exist as of this release. See [issue #124](https://github.com/Frihet-io/frihet-mcp/issues/124) for the audit and the precedent (`src/tools/igic.ts` shows the inline `NOT_DEPLOYED` stub pattern used for families whose backing API is not yet shipped; onboarding chose full withdrawal instead, because the catalogue should not over-promise tools that have no live handler).
+
+If a future Frihet-ERP release ships the family, restore `src/tools/onboarding.ts`, the `onboardingStatusOutput` / `onboardingPersonaResultOutput` schemas in `src/tools/shared.ts`, the `getOnboardingStatus` / `setOnboardingPersona` methods on `IFrihetClient`, and the registration in `src/tools/register-all.ts` (the `Onboarding tools — withdrawn via #124` test in `src/__tests__/d4b-hr-payroll-onboarding-tools.test.ts` is the gate that will fail and remind the next maintainer what was here).
 
 ### Permissions (2)
 
 | Tool | What it does |
 |------|-------------|
-| `permissions_matrix` | Get the full permissions matrix for all roles in the workspace |
-| `permissions_me` | Get the current API key's effective permissions |
+| `permissions_matrix` | Get the documented RBAC-model snapshot (not a runtime authorization guarantee) |
+| `permissions_me` | Compare RBAC-model fields with actual API-key scopes and known scope denials (non-exhaustive) |
 
 ### Period Close (3)
 
 | Tool | What it does |
 |------|-------------|
-| `period_close_status` | Get the close status for an accounting period |
+| `period_close_status` | Get the current or selected YYYY fiscal-year range, open/closed state, and nullable closing details |
 | `period_close` | Close an accounting period (gestor/admin only — TRUST AREA) |
 | `period_reopen` | Reopen a closed period with a mandatory reason (TRUST AREA) |
 
-All 157 tools return **structured output** via `outputSchema` -- typed JSON, not raw text. List tools return paginated results (`{ data, total, limit, offset }`).
+All canonical operations (and their aliases) return **structured output** via `outputSchema` -- typed JSON, not raw text. List response shapes follow their API family; not every list endpoint is paginated.
+
+### Capability and side-effect truth
+
+On the full MCP surfaces, every `tools/list` entry includes `_meta["io.frihet/capability"]`:
+
+- `registered` means the name and handler exist in this server build;
+- `callability` is `api_dependent` (the handler calls the API; deployment, workspace enablement, and authorization still decide), `runtime_checked` (the handler explicitly distinguishes an absent backend from empty data), `deferred`, `unavailable`, or `local`—never an unconditional “available” claim;
+- `writesFrihet`, `externalInteraction`, and `externalSideEffects` distinguish state changes and calls to external entities/providers;
+- MCP action annotations remain the standard source for read-only, destructive, idempotent, and open-world hints.
+
+The ChatGPT/OpenAI host is a separately reviewed surface: exactly 33 business operations with complete descriptions, 0 discovery meta-tools, 0 prompts, and 0 resources. Its 17 reads and 16 writes are deliberately narrow, and all writes require literal `confirm=true`. Ten writes may deliver full business events to active endpoints previously configured by the workspace owner; webhook administration itself remains excluded. Direct email delivery, the legacy monthly summary, raw invoice PDFs, invoice lifecycle transitions, updating an existing quote, regulated filing, deleting client parent records, deleting expenses with their linked files, deleting products, and deleting vendors are also excluded. This surface must not be inferred from the full catalogue.
 
 ---
 
-## Resources (11)
+## Resources
 
 Context the AI can read to make smarter decisions.
 
+The local package serves 11 resources: 7 static references plus 4 API-backed workspace resources. The hosted Worker serves the 7 static resources. The OpenAI-reviewed host serves 0 resources.
+
 **Static** (reference data, no API calls):
 
 | Resource | URI | What it provides |
 |----------|-----|-----------------|
 | API Schema | `frihet://api/schema` | OpenAPI summary: endpoints, auth, rate limits, pagination, error codes |
 | Tax Rates | `frihet://tax/rates` | Tax rates by Spanish fiscal zone: IVA, IGIC, IPSI, EU reverse charge, IRPF |
-| Tax Calendar | `frihet://tax/calendar` | Quarterly filing deadlines: Modelo 303, 130, 390, 420, VeriFactu timeline |
+| Tax Calendar | `frihet://tax/calendar` | Quarterly and annual filing deadlines for the listed Spanish tax models |
 | Expense Categories | `frihet://config/expense-categories` | 8 categories with deductibility rules, IVA treatment, amortization |
 | Invoice Statuses | `frihet://config/invoice-statuses` | Status flow (draft > sent > paid/overdue > cancelled), transition rules, webhook events |
 | Currencies | `frihet://config/currencies` | 40 supported currencies with ISO codes, symbols, decimal places, locale formatting |
-| Countries | `frihet://config/countries` | 61 supported countries with fiscal zones, default tax rates, currencies, invoice prefixes |
+| Countries | `frihet://config/countries` | Supported countries with fiscal zones, default tax rates, currencies, invoice prefixes |
 
 **Dynamic** (live data from your account):
 
@@ -659,6 +750,12 @@ Two transports:
 | `FRIHET_API_KEY` | Yes (stdio) | -- |
 | `FRIHET_API_URL` | No | `https://api.frihet.io/v1` |
 | `FRIHET_TOOL_MODE` | No | `full` |
+| `FRIHET_CLAUDE_MODE` | No (unreleased local candidate) | `false` |
+
+The source-only Claude candidate requires building this checkout and running
+`dist/index.js`; existing npm releases are not claimed to support the flag.
+See [candidate scope, exclusions and checks](marketplace/anthropic/SUBMISSION.md).
+It cannot be combined with `FRIHET_OPENAI_MODE=true` and is not enabled in the deployed Worker.
 
 ---
 
@@ -670,10 +767,10 @@ Frihet's differentiator is **depth** — full ES/EU fiscal coverage plus native
 
 | Mode | Behavior |
 |------|----------|
-| `full` (default) | All tools are exposed with their full descriptions and schemas. **Unchanged from previous releases** — existing setups are unaffected. |
+| `full` (default) | Canonical tools and fiscal aliases are exposed with full descriptions and schemas. Public descriptors add conservative callability and side-effect truth; operation names, schemas and handlers are unchanged. |
 | `grouped` | **Progressive disclosure.** Each tool's description collapses to a one-line `[group] summary — full schema via describe_tool('name')`, and three lightweight discovery tools are added. The agent loads depth only for the tools it actually needs. |
 
-In `grouped` mode the tools are unchanged — same names, same input schemas, same behavior. Only the *up-front context cost* changes. Discovery flows through three meta-tools:
+In `grouped` mode operation names, input schemas and handlers are unchanged. Descriptors also expose the same conservative capability and action truth as the full profile. Discovery flows through three meta-tools:
 
 - **`list_tool_groups()`** — the domain map (invoicing, expenses, fiscal/compliance, banking, CRM, HR/payroll, stay/PMS, POS, intelligence, products, platform) with a one-line blurb and tool count for each.
 - **`search_tools(query)`** — free-text search across tool name, title, summary and group; returns matching tools with their group, summary, read-only flag and input fields. Optional `group` filter and `limit`.
@@ -695,7 +792,7 @@ In `grouped` mode the tools are unchanged — same names, same input schemas, sa
 }
 ```
 
-> This is an opt-in exposure layer only — it never changes a tool's logic, name or behavior, and `full` mode is byte-identical to before. The same interceptor pattern powers the OpenAI-safe profile (`FRIHET_OPENAI_MODE`).
+> Grouped exposure changes description density, not operation behavior. The versioned OpenAI-reviewed profile is composed separately and remains independently gated.
 
 ---
 
@@ -721,7 +818,7 @@ Beyond raw MCP tools, this repo includes a **Claude Code skill** that adds busin
 
 ```bash
 git clone https://github.com/Frihet-io/frihet-mcp.git
-ln -s "$(pwd)/frihet-mcp/skill" ~/.claude/skills/frihet
+ln -s "$(pwd)/frihet-mcp/skills/frihet-mcp" ~/.claude/skills/frihet-mcp
 ```
 
 Or with the universal installer:
@@ -730,20 +827,7 @@ Or with the universal installer:
 npx skills add Frihet-io/frihet-mcp
 ```
 
-### Commands
-
-| Command | What it does |
-|---------|-------------|
-| `/frihet status` | Account overview, recent activity, pending payments |
-| `/frihet invoice` | Create, list, search invoices |
-| `/frihet expense` | Log and query expenses |
-| `/frihet clients` | Manage client database |
-| `/frihet quote` | Create and manage quotes |
-| `/frihet report` | Financial summaries (P&L, quarterly, overdue) |
-| `/frihet webhooks` | Configure automation triggers |
-| `/frihet setup` | Guided setup and connection test |
-
-The skill knows about IVA rates, IRPF retention, Modelo 303 prep, expense deductibility rules, and VeriFactu compliance.
+The skill routes requests to the Frihet MCP tools (invoices, quotes, expenses, clients, monthly review) and tells the agent when to ask for confirmation before writes. It does not add standalone `/frihet` subcommands, and it does not ship VAT rates or deductibility rules: tax figures come from your Frihet data, not from the skill.
 
 Full documentation: [docs.frihet.io/desarrolladores/skill-claude-code](https://docs.frihet.io/desarrolladores/skill-claude-code)
 
@@ -797,7 +881,7 @@ npm run build   # must pass before submitting
 
 | Package | What it is |
 |---------|-----------|
-| [`@frihet/mcp-server`](https://www.npmjs.com/package/@frihet/mcp-server) | This MCP server (157 tools, 11 resources, 10 prompts) |
+| [`@frihet/mcp-server`](https://www.npmjs.com/package/@frihet/mcp-server) | This MCP server (156 canonical operations + 5 alias names; 11 local resources; 10 prompts) |
 | [`@frihet/sdk`](https://github.com/Frihet-io/frihet-sdk) | TypeScript SDK (`frihet.invoices.create()`) |
 | [`frihet`](https://www.npmjs.com/package/frihet) | CLI (`frihet invoices list --status overdue`) |
 | [`n8n-nodes-frihet`](https://www.npmjs.com/package/n8n-nodes-frihet) | n8n community node for workflow automation |
@@ -813,9 +897,11 @@ npm run build   # must pass before submitting
 - [MCP server docs](https://docs.frihet.io/desarrolladores/mcp-server) -- Setup guides, troubleshooting
 - [npm](https://www.npmjs.com/package/@frihet/mcp-server) -- Package registry
 - [Smithery](https://smithery.ai/servers/frihet/frihet-mcp) -- Smithery marketplace
-- [MCP Registry](https://registry.modelcontextprotocol.io/?q=io.frihet) -- Anthropic official registry
+- [MCP Registry](https://registry.modelcontextprotocol.io/?q=io.frihet) -- Official Model Context Protocol registry
+- [GitHub MCP Registry](https://github.com/mcp/io.frihet/erp) -- Frihet listing on GitHub
 - [Remote endpoint](https://mcp.frihet.io) -- Hosted MCP server (Cloudflare Workers)
 - [OpenAPI spec](https://api.frihet.io/openapi.json) -- Machine-readable API definition
+- [Security policy](./SECURITY.md) -- Private vulnerability reporting guidance
 
 ---
 

package/dist/agent-onboarding.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Agent-native onboarding contract.
+ *
+ * Two artefacts, one source:
+ *
+ *   1. `AGENT_SERVER_INSTRUCTIONS` — the MCP `instructions` string returned by
+ *      `initialize`. Every MCP client hands this to the model before the first
+ *      tool call, so it is the only onboarding channel that costs the human
+ *      zero configuration. It deliberately contains NO counts: a number in a
+ *      per-session prompt is a number that drifts. It teaches the *mechanism*
+ *      for finding the current numbers instead.
+ *
+ *   2. `captureAgentOnboardingDescriptor()` — the machine-readable descriptor
+ *      written to `docs/agent-onboarding.json` by
+ *      `scripts/generate-agent-onboarding.mjs`. It is captured through the real
+ *      MCP SDK against the real registration path, so the tool lists in it
+ *      cannot drift from the server: `npm run gate:agent-onboarding` re-captures
+ *      and byte-compares.
+ *
+ * Nothing here registers a tool, a resource or a prompt. The surface counts the
+ * conformance baseline and the public capability contract already pin are
+ * unchanged by this module, on purpose.
+ */
+export declare const AGENT_ONBOARDING_CONTRACT_VERSION = 1;
+/** Where an API key actually comes from — a deep link, not a navigation
+ *  instruction, so the human has one click instead of a hunt.
+ *
+ *  Verified against the ERP: `settingsSectionToPath` renders `/settings/<id>`
+ *  and `api` is in `ALL_SETTINGS_SECTIONS`, so this URL resolves to the
+ *  ApiKeysSettings panel. The old index.ts wording ("Settings > Developers >
+ *  API Keys") pointed at a section that does not exist. */
+export declare const API_KEY_LOCATION = "https://app.frihet.io/settings/api";
+export declare const AGENT_SERVER_INSTRUCTIONS = "Frihet ERP \u2014 real business and fiscal records. Read freely, propose before you mutate.\n\nAUTH\n- Local (stdio): FRIHET_API_KEY=fri_... \u2014 create one at https://app.frihet.io/settings/api.\n- No key yet: FRIHET_DEMO=1 serves example fixtures. No network call, nothing persisted, demo_-prefixed IDs, fiscal actions simulated.\n- Hosted: https://mcp.frihet.io/mcp \u2014 OAuth 2.1 + PKCE, or Authorization: Bearer fri_...\n\nORIENT BEFORE ACTING (read-only)\n- get_business_context \u2014 fiscal zone, currency, IRPF/IVA defaults, plan limits. Call this first; the correct tax treatment depends on it.\n- Resources carry informational reference data with declared provenance: frihet://tax/rates and frihet://tax/calendar (Spanish statutory schedules and deadlines), frihet://config/expense-categories (LIRPF/LIVA deductibility guidelines), frihet://config/countries and currencies (defaults and ISO codes), frihet://api/schema (endpoint snapshot; canonical at https://api.frihet.io/v1/openapi.json). Read them instead of guessing, but treat as informational: writing tools and server endpoints enforce business and fiscal invariants server-side.\n\nCAPABILITY DISCOVERY\n- Every tool in tools/list carries _meta[\"io.frihet/capability\"] = {callability, writesFrihet, externalInteraction, externalSideEffects}. Read it before you call.\n- callability is a conservative fact, not a promise: api_dependent | runtime_checked | deferred | unavailable | local. Registration does NOT mean the backing API is enabled for this workspace; deferred and unavailable tools will refuse.\n- Large surface: set FRIHET_TOOL_MODE=grouped for progressive disclosure (list_tool_groups, search_tools, describe_tool) instead of loading every schema.\n\nTHE SAFE WORKFLOW \u2014 draft, show, stop\n- create_invoice defaults to status=draft: no fiscal number, no hash, nothing submitted to a tax authority. create_quote and create_credit_note are drafts too.\n- Build the draft, read it back, present it to the human, and stop there. Issuing is a separate, human-authorised step.\n\nHUMAN AUTHORITY \u2014 do not call unprompted\n- Any tool whose capability shows a non-empty externalSideEffects reaches outside Frihet \u2014 email to a client, webhook delivery, money movement, or a submission to AEAT / VeriFactu / TicketBAI / FACe. You cannot undo those.\n- Several also take confirm=true. It is a local client/agent interlock, not server-verifiable human attestation and not actor/resource/payload/expiry-bound. Never set it to satisfy your own plan; ask, then pass what you were told.\n- delete_invoice does not always delete: an issued invoice is CANCELLED (status=cancelled) because VeriFactu forbids breaking the hash chain. Same for quotes.\n\nWHEN A CALL FAILS\n- Errors carry sanitized remediation text \u2014 read it, do not guess. 401 = key; 403 = scope or plan; 429 = wait Retry-After seconds.\n- After 409 IDEMPOTENCY_REQUEST_IN_PROGRESS, do NOT retry with a fresh Idempotency-Key. Read the resource back and decide from its actual state; a new key would create a second fiscal document.\n\nMachine-readable version of this contract: https://github.com/Frihet-io/frihet-mcp/blob/main/docs/agent-onboarding.json";
+export interface AgentOnboardingDescriptor {
+    onboardingContractVersion: number;
+    server: {
+        mcpName: string;
+        npmPackage: string;
+        remoteEndpoint: string;
+        transport: readonly string[];
+    };
+    auth: {
+        envVar: string;
+        keyFormat: string;
+        obtainAt: string;
+        remoteMethods: readonly string[];
+        noAuthTrial: {
+            env: Record<string, string>;
+            persists: false;
+            network: false;
+        };
+    };
+    /** One verified command per client. Every `command` here was executed against
+     *  the real binary in an isolated HOME before being written down. */
+    quickstart: Record<string, {
+        steps: readonly string[];
+        configFormat: string;
+        verify: string;
+    }>;
+    capabilityDiscovery: {
+        metaKey: string;
+        callabilityValues: readonly string[];
+        groupedModeEnv: Record<string, string>;
+        counts: {
+            toolNames: number;
+            readOnly: number;
+            writesFrihet: number;
+            externalInteraction: number;
+            destructive: number;
+            resources: number;
+            prompts: number;
+        };
+    };
+    safeWorkflow: {
+        description: string;
+        steps: readonly {
+            call: string;
+            kind: string;
+            note: string;
+        }[];
+    };
+    humanAuthority: {
+        rule: string;
+        confirmRequired: readonly string[];
+        externalSideEffects: readonly {
+            tool: string;
+            effects: readonly string[];
+        }[];
+    };
+    errors: readonly {
+        condition: string;
+        meaning: string;
+        agentAction: string;
+    }[];
+}
+export declare function captureAgentOnboardingDescriptor(): Promise<AgentOnboardingDescriptor>;
+export declare function serializeAgentOnboardingDescriptor(descriptor: AgentOnboardingDescriptor): string;
+//# sourceMappingURL=agent-onboarding.d.ts.map