@frihet/mcp-server 1.17.0 → 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/catalogue-157_operations-18181b?style=flat&labelColor=09090b" alt="157 canonical catalogue operations">
-  <img src="https://img.shields.io/badge/node-%3E%3D20-18181b?style=flat&labelColor=09090b" alt="node >=20">
+  <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) |
-
-> **Surface truth:** the catalogue contains 157 canonical operations. The local full profile serves those plus 5 fiscal alias names (162 names). The hosted grouped profile also adds 3 local discovery names (165 names). Catalogue membership is not a promise that a backing API is enabled for every workspace.
+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 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.
+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.) -->
 
 ---
 
@@ -102,6 +128,10 @@ Three rules the contract encodes, in short:
 
 ## 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
@@ -117,15 +147,17 @@ 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:
-
-```text
-/plugin marketplace add anthropics/claude-plugins-community
-/plugin install frihet-erp@claude-community
-```
+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
 
 ```bash
@@ -269,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 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.
+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:**
 
@@ -296,7 +328,7 @@ If you need to digitize paper invoices or receipts, extract the data first (e.g.
 
 ---
 
-## Catalogue operations (157)
+## Catalogue operations (156)
 
 ### Invoices (12)
 
@@ -412,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)
 
@@ -436,7 +468,7 @@ 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)
 
@@ -484,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)
 
@@ -513,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)
 
@@ -542,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 |
@@ -599,12 +631,11 @@ If you need to digitize paper invoices or receipts, extract the data first (e.g.
 | `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)
 
@@ -652,7 +683,7 @@ The local package serves 11 resources: 7 static references plus 4 API-backed wor
 | 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):
 
@@ -719,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.
 
 ---
 
@@ -781,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:
@@ -790,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)
 
@@ -857,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 canonical operations + 5 alias names; 11 local 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 |
@@ -873,7 +897,8 @@ 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

@@ -30,7 +30,7 @@ export declare const AGENT_ONBOARDING_CONTRACT_VERSION = 1;
  *  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 frihet://tax/rates and frihet://tax/calendar carry the Spanish rate table (IVA / IGIC / IPSI) and the filing deadlines. Read them instead of recalling a rate.\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. That flag records the human's decision. 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 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: {

package/dist/agent-onboarding.js

@@ -47,7 +47,7 @@ AUTH
 
 ORIENT BEFORE ACTING (read-only)
 - get_business_context — fiscal zone, currency, IRPF/IVA defaults, plan limits. Call this first; the correct tax treatment depends on it.
-- Resources frihet://tax/rates and frihet://tax/calendar carry the Spanish rate table (IVA / IGIC / IPSI) and the filing deadlines. Read them instead of recalling a rate.
+- 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.
 
 CAPABILITY DISCOVERY
 - Every tool in tools/list carries _meta["${CAPABILITY_META_KEY}"] = {callability, writesFrihet, externalInteraction, externalSideEffects}. Read it before you call.
@@ -60,7 +60,7 @@ THE SAFE WORKFLOW — draft, show, stop
 
 HUMAN AUTHORITY — do not call unprompted
 - Any tool whose capability shows a non-empty externalSideEffects reaches outside Frihet — email to a client, webhook delivery, money movement, or a submission to AEAT / VeriFactu / TicketBAI / FACe. You cannot undo those.
-- Several also take confirm=true. That flag records the human's decision. Never set it to satisfy your own plan; ask, then pass what you were told.
+- 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.
 - delete_invoice does not always delete: an issued invoice is CANCELLED (status=cancelled) because VeriFactu forbids breaking the hash chain. Same for quotes.
 
 WHEN A CALL FAILS
@@ -214,7 +214,7 @@ export async function captureAgentOnboardingDescriptor() {
                 {
                     call: "resources/read frihet://tax/rates",
                     kind: "read",
-                    note: "Authoritative IVA / IGIC / IPSI table. Do not recall a rate from memory.",
+                    note: "Spanish statutory IVA / IGIC / IPSI reference schedule. Do not recall a rate from memory; server validates transaction math.",
                 },
                 {
                     call: "list_clients",

package/dist/canary/mcp-harness.d.ts

@@ -15,7 +15,7 @@
  */
 export declare const HARNESS_CONTRACT_VERSION = 1;
 export declare const INSPECTOR_PINNED_VERSION = "2.3.0";
-export declare const CANONICAL_OPERATIONS_COUNT = 157;
+export declare const CANONICAL_OPERATIONS_COUNT = 156;
 export declare const FISCAL_ALIASES_COUNT: number;
 export type CheckStatus = "PASS" | "FAIL" | "UNSUPPORTED" | "NOT_EXERCISED";
 export type OverallStatus = "PASS" | "PASS_WITH_GAPS" | "FAIL";

package/dist/canary/mcp-harness.js

@@ -22,7 +22,10 @@ import { CAPABILITY_META_KEY } from "../capability-truth.js";
 import { FISCAL_MODELO_ALIASES } from "../fiscal-aliases.js";
 export const HARNESS_CONTRACT_VERSION = 1;
 export const INSPECTOR_PINNED_VERSION = "2.3.0";
-export const CANONICAL_OPERATIONS_COUNT = 157;
+// Updated 2026-10-10 by issue #124 (IGIC-pattern withdraw of dead onboarding_status /
+// onboarding_persona_set — the Frihet-ERP /v1/onboarding/* family is absent, so the
+// MCP catalogue now declares 156 canonical operations, down from 158).
+export const CANONICAL_OPERATIONS_COUNT = 156;
 export const FISCAL_ALIASES_COUNT = Object.keys(FISCAL_MODELO_ALIASES).length;
 /**
  * Executes the complete compatibility harness in-process and returns

package/dist/capability-truth.js

@@ -14,17 +14,11 @@ const RUNTIME_CHECKED = new Set([
     "anomaly_list",
     "attendance_clock_in",
     "attendance_clock_out",
-    "frihet_aiem_calculate",
     "frihet_bank_rule_create",
     "frihet_bank_rules_list",
     "frihet_gl_entry_approve",
     "frihet_gl_entry_audit_log",
     "frihet_gl_entry_reject",
-    "frihet_modelo_200_summary",
-    "frihet_modelo_202_summary",
-    "frihet_modelo_415_summary",
-    "frihet_modelo_418_summary",
-    "frihet_modelo_425_summary",
     "frihet_portal_domain_add",
     "frihet_portal_domain_remove",
     "frihet_portal_domain_verify",
@@ -32,7 +26,6 @@ const RUNTIME_CHECKED = new Set([
     "frihet_tax_id_vies_lookup",
     "gestoria_template_create",
     "get_modelo_130_summary",
-    "get_modelo_180_summary",
     "get_modelo_303_summary",
     "get_modelo_347_summary",
     "get_modelo_390_summary",
@@ -41,8 +34,6 @@ const RUNTIME_CHECKED = new Set([
     "leave_list",
     "leave_reject",
     "leave_request_create",
-    "onboarding_persona_set",
-    "onboarding_status",
     "overtime_report",
     "payroll_checklist",
     "payroll_export",
@@ -71,7 +62,19 @@ const DEFERRED = new Set([
     "create_reservation",
     "sync_channel",
 ]);
-const UNAVAILABLE = new Set(["ksef_submit"]);
+// No Frihet-ERP route exists: publicApi.ts serves /fiscal/modelo/{303,130,390,347}
+// only, and has no /igic/* (modelo or AIEM) and no /is/modelo/* route. These
+// handlers return NOT_DEPLOYED without a call (ksef_submit: labelled unavailable).
+const UNAVAILABLE = new Set([
+    "ksef_submit",
+    "get_modelo_180_summary",
+    "frihet_modelo_415_summary",
+    "frihet_modelo_418_summary",
+    "frihet_modelo_425_summary",
+    "frihet_aiem_calculate",
+    "frihet_modelo_200_summary",
+    "frihet_modelo_202_summary",
+]);
 const DESTRUCTIVE_UPDATES = new Set([
     // These writes can synchronously enqueue delivery to workspace webhooks.
     // Once an external endpoint receives the event, that disclosure cannot be
@@ -101,7 +104,6 @@ const DESTRUCTIVE_UPDATES = new Set([
     "send_invoice",
     "mark_invoice_paid",
     "update_kitchen_ticket",
-    "onboarding_persona_set",
     "update_product",
     "update_quote",
     "send_quote",
@@ -147,11 +149,17 @@ const NON_IDEMPOTENT = new Set([
     "pause_recurring_invoice",
     "resume_recurring_invoice",
 ]);
-const WRITE_OVERRIDES = new Set(["frihet_portal_domain_verify"]);
+const WRITE_OVERRIDES = new Set([
+    "frihet_portal_domain_verify",
+    // signed=true exercises a workspace certificate. MCP annotations are
+    // static, so classify the whole export tool conservatively.
+    "einvoice_export",
+]);
 const EXTERNAL_SIDE_EFFECTS = {
     create_invoice: ["webhook_delivery_or_configuration", "fiscal_or_einvoice_submission"],
     duplicate_invoice: ["webhook_delivery_or_configuration"],
     create_credit_note: ["webhook_delivery_or_configuration"],
+    run_recurring_now: ["webhook_delivery_or_configuration", "fiscal_or_einvoice_submission"],
     update_invoice: ["webhook_delivery_or_configuration", "fiscal_or_einvoice_submission"],
     mark_invoice_paid: ["webhook_delivery_or_configuration", "fiscal_or_einvoice_submission"],
     delete_invoice: ["webhook_delivery_or_configuration", "fiscal_or_einvoice_submission"],