@frihet/mcp-server 2.0.0 → 2.0.2

package/README.md

@@ -18,13 +18,9 @@
 <p align="center">
   <a href="https://www.npmjs.com/package/@frihet/mcp-server"><img src="https://img.shields.io/npm/v/@frihet/mcp-server?style=flat&color=18181b&labelColor=09090b" alt="npm version"></a>
   <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>
+  <img src="https://img.shields.io/badge/catalogue-158_operations-18181b?style=flat&labelColor=09090b" alt="158 canonical catalogue operations">
   <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-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>
 
 <p align="center">
@@ -33,161 +29,95 @@
 
 ---
 
-## Distribution
-
-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.
-
----
-
 ## What is this
 
-An MCP server that connects your AI assistant to [Frihet](https://frihet.io/?utm_source=github_readme&utm_medium=mcp_readme&utm_campaign=mcp_landgrab). Create invoices by talking. Query expenses in natural language. Manage your entire business from your IDE.
+An MCP server that connects your AI assistant to [Frihet](https://frihet.io/?utm_source=github_readme&utm_medium=mcp_readme&utm_campaign=mcp_landgrab), the AI-native ERP for businesses of any size. Ask for invoices, expenses, clients, quotes, banking and tax figures in plain language, from the tools you already use.
 
 ```
 You:     "Create an invoice for TechStart SL, 40 hours of consulting at 75 EUR/hour, due March 1st"
 Claude:  Done. Invoice INV-2026-089 created. Total: 3,000.00 EUR + 21% IVA = 3,630.00 EUR.
 ```
 
-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), 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.) -->
+158 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.
 
 ---
 
-## Try it instantly (no signup)
+## Quick start
+
+**Remote, one step.** Add `https://mcp.frihet.io/mcp` as a remote MCP server in any client that supports OAuth. You sign in with your browser; there is nothing to install and no key to copy.
 
-Kick the tires with zero setup — no account, no API key:
+**Local, with your API key** (create one in [app.frihet.io](https://app.frihet.io) under Settings > API):
 
 ```bash
-FRIHET_DEMO=1 npx -y @frihet/mcp-server
+claude mcp add frihet -s user -e FRIHET_API_KEY=fri_your_key_here -- npx -y @frihet/mcp-server
 ```
 
-In demo mode the server answers from realistic **example fixtures** (Spanish invoices with IVA/IGIC, expenses, clients, products, a bank account, and more) — every record uses `demo_`-prefixed IDs and the server prints a `DEMO MODE` banner on startup. **Nothing is persisted** and no network call is ever made. Writes are simulated and fiscal actions (e-invoice, VeriFactu, TicketBAI, FACe, payroll) return a clearly-labeled simulation — never a real submission to any tax authority.
+**No account yet?** Try demo mode. It answers from example data, persists nothing and makes no network calls:
 
-When you're ready for your real data, drop the flag and add your key ([app.frihet.io](https://app.frihet.io) → Settings → API keys). See [Install](#install) below.
+```bash
+FRIHET_DEMO=1 npx -y @frihet/mcp-server
+```
 
----
+Local installs need Node 22.23.4+, 24.22.1+ or 26.12.1+. Other clients are covered under [Client setup](#client-setup).
 
-## 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.
+## Distribution
 
-| 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 |
+### Where to get it
 
-Three rules the contract encodes, in short:
+| Channel | Status | Entry point |
+|---|---|---|
+| npm | Published | [`@frihet/mcp-server`](https://www.npmjs.com/package/@frihet/mcp-server) · `npx -y @frihet/mcp-server` |
+| Remote MCP | Live, OAuth or API key | `https://mcp.frihet.io/mcp` (running version at [`/health`](https://mcp.frihet.io/health)) |
+| ChatGPT app | Live | [Frihet in ChatGPT](https://chatgpt.com/plugins/plugin_asdk_app_6ac6b51bd7648191a0696bd1e725bfe6) |
+| Raycast | Coming to the Raycast Store | [Submission](https://github.com/raycast/extensions/pull/33017) |
+| Official MCP Registry | Listed | [`io.frihet/erp`](https://registry.modelcontextprotocol.io/?q=io.frihet) |
+| GitHub MCP Registry | Listed | [Frihet ERP](https://github.com/mcp/io.frihet/erp) |
 
-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.
+Also listed on [Glama](https://glama.ai/mcp/servers/Frihet-io/frihet-mcp), [Cursor Directory](https://cursor.directory/plugins/mcp-frihet), [mcp.so](https://mcp.so/servers/frihet-mcp), [mcpservers.org](https://mcpservers.org/servers/frihet-io/frihet-mcp) and the [ToolSDK registry](https://github.com/toolsdk-ai/toolsdk-mcp-registry/blob/main/packages/finance-fintech/frihet-mcp.json).
 
-`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.
+> **Surface truth:** the catalogue contains 158 canonical operations. The local full profile serves 163 tool names, 11 resources, and 10 prompts (158 canonical operations plus 5 fiscal aliases). The hosted grouped profile serves 166 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. These counts describe the current source release; the hosted server reports the version it is running at `/health`. Catalogue membership is not a promise that a backing API is enabled for every workspace.
 
 ---
 
-## 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
-npx skills add Frihet-io/frihet-mcp
-```
-
-### Claude Code plugin (skill + MCP server in one install)
+## What you can do
 
-This repository is also a Claude Code plugin (`frihet-erp`): installing it wires up both the business-management skill and the MCP server.
+Real prompts, grouped by area.
 
-```bash
-# Try it locally
-claude --plugin-dir /path/to/frihet-mcp
-```
+| Area | Try asking |
+|------|------------|
+| Invoicing | "Show me all unpaid invoices" · "Create an invoice for Acme SL with 10h of consulting at 95/hour" · "Mark invoice abc123 as paid" |
+| Expenses | "Log a 59.99 EUR expense for Adobe Creative Cloud, category: software, tax-deductible" · "What did I spend on travel last quarter?" |
+| Clients and CRM | "Add a new client: TechStart SL, NIF B12345678" · "Log a call with TechStart: discussed Q2 proposal" · "Show all activities for Acme SL" |
+| Quotes | "Create a quote for Design Studio: logo design (2000 EUR) + brand guidelines (3500 EUR)" |
+| Tax and reporting | "Prepare my quarterly tax summary" · "Give me this month's profit and loss" |
+| Webhooks | "Set up a webhook to notify https://my-app.com/hook when invoices are paid" |
 
-Marketplace availability is pending. Use the local plugin command above or the Claude Code MCP command below to connect today.
+Beyond these, the catalogue covers banking, e-invoicing, time tracking, recurring invoices, HR and payroll, POS and more. See the [full catalogue](#full-catalogue).
 
-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.
+## Client setup
 
-### Claude Code — one command
+### Claude Code
 
 ```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
 ```
 
-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`.)
+Or use the hosted server: `claude mcp add --transport http frihet https://mcp.frihet.io/mcp`.
 
-### Codex CLI — one command
+### Codex CLI
 
 ```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"
-```
+Codex reads TOML, not JSON. Pasting a JSON `mcpServers` block into `~/.codex/config.toml` is a parse error that breaks the whole file, so use the command above.
 
-> 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 Desktop, Cursor, Windsurf, Cline — JSON config
+### Claude Desktop, Cursor, Windsurf, Cline
 
 ```json
 {
@@ -203,20 +133,14 @@ FRIHET_API_KEY = "fri_your_key_here"
 }
 ```
 
-| Tool | Config file |
+| Client | Config file |
 |------|------------|
 | 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` |
 
-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)
-
-Use the hosted endpoint at `mcp.frihet.io` -- zero local dependencies, runs on Cloudflare Workers.
-
-**With API key:**
+### Remote server with an API key
 
 ```json
 {
@@ -232,103 +156,57 @@ Use the hosted endpoint at `mcp.frihet.io` -- zero local dependencies, runs on C
 }
 ```
 
-**With OAuth 2.0 + PKCE** (browser-based login, no API key needed):
+Clients that support OAuth 2.1 with PKCE can connect to the same URL and sign in through the browser instead.
 
-Clients that support OAuth (Claude Desktop, Smithery, etc.) can connect directly to `https://mcp.frihet.io/mcp` and authenticate via browser. The server implements the full OAuth 2.1 authorization code flow with PKCE.
+### ChatGPT
 
-### Get your API key
+Open [Frihet in ChatGPT](https://chatgpt.com/plugins/plugin_asdk_app_6ac6b51bd7648191a0696bd1e725bfe6) and connect your account.
 
-1. Log into [app.frihet.io](https://app.frihet.io)
-2. Go to **Settings > API**
-3. Click **Create API key**
-4. Copy the key (starts with `fri_`) -- it's only shown once
-
----
+### Skill for coding agents
 
-## What you can do
-
-Talk to your ERP. These are real prompts, not marketing copy.
-
-### Invoicing
-
-```
-"Show me all unpaid invoices"
-"Create an invoice for Acme SL with 10h of consulting at 95/hour"
-"Mark invoice abc123 as paid"
-"How much has ClientName been invoiced this year?"
-```
-
-### Expenses
-
-```
-"Log a 59.99 EUR expense for Adobe Creative Cloud, category: software, tax-deductible"
-"List all expenses from January"
-"What did I spend on travel last quarter?"
+```bash
+npx skills add Frihet-io/frihet-mcp
 ```
 
-### Clients
+Installs the Frihet skill for Claude Code, Cursor, Codex, Windsurf, Gemini CLI and others. It routes requests to the MCP tools and asks for confirmation before writes. Tax figures come from your Frihet data, not from the skill. [Skill docs](https://docs.frihet.io/desarrolladores/skill-claude-code).
 
-```
-"Add a new client: TechStart SL, NIF B12345678, email admin@techstart.es"
-"Show me all my clients"
-"Update ClientName's address to Calle Mayor 1, Madrid 28001"
-```
+### Get your API key
 
-### CRM
+1. Log into [app.frihet.io](https://app.frihet.io)
+2. Go to **Settings > API**
+3. Click **Create API key**
+4. Copy the key (starts with `fri_`). It is only shown once.
 
-```
-"Add a contact to Acme SL: Ana Garcia, CTO, ana@acme.es"
-"Log a call with TechStart: discussed Q2 proposal, they're interested in upgrade"
-"Add a note to ClientName: prefers invoices in English, payment NET 30"
-"Show me all activities for Acme SL"
-```
+---
 
-### Quotes
+## For AI agents
 
-```
-"Create a quote for Design Studio: logo design (2000 EUR) + brand guidelines (3500 EUR)"
-"Show me all pending quotes"
-```
+If you are an agent reading this repository, the contract is machine-readable and generated from the running server.
 
-### Webhooks
+| 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 in 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` |
 
-```
-"Set up a webhook to notify https://my-app.com/hook when invoices are paid"
-"List all my active webhooks"
-```
+1. **Orient before acting.** `get_business_context` and the `frihet://tax/rates` resource decide the correct fiscal treatment. Do not recall a tax rate from memory.
+2. **Draft, show, stop.** `create_invoice`, `create_quote` and `create_credit_note` default to `status=draft`: no fiscal number, no hash, nothing sent to a tax authority.
+3. **Human authority is not yours to assume.** Any tool with a non-empty `externalSideEffects` reaches a client's inbox, a webhook, money, or a tax authority. Several also take `confirm=true`; that flag records a human decision.
 
 ---
 
 ## 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 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.
+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 158 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:**
-
-```
-"Create an invoice for TechStart SL, 40h consulting at 75 EUR/h"   --> creates the invoice
-"Show unpaid invoices over 1,000 EUR"                               --> queries and filters
-"Log a 120 EUR expense for the Madrid train, category: travel"      --> records the expense
-"Update client Acme's email to billing@acme.es"                     --> modifies the record
-```
-
-**Does not do:**
-
-- OCR or PDF scanning -- you cannot upload an invoice image and have it read
-- File upload or attachment handling
-- Image processing of any kind
-
-If you need to digitize paper invoices or receipts, extract the data first (e.g., Claude Vision API, a dedicated OCR service, or manual entry), then use the MCP to create the record:
-
-```
-1. Scan/photograph the invoice
-2. Use Claude Vision: "Read this invoice image and extract the vendor, items, amounts, and dates"
-3. Then: "Create an expense in Frihet for [extracted data]"
-```
+It does not do OCR, PDF scanning, file upload or image processing. To digitize a paper invoice, extract the data first (a vision model, an OCR service, or manual entry), then ask the assistant to create the record. One API key maps to one Frihet workspace, and you need a Frihet account at [app.frihet.io](https://app.frihet.io).
 
 ---
 
-## Catalogue operations (156)
+## Full catalogue
+
+<details>
+<summary><strong>All 158 canonical operations, resources and prompts</strong></summary>
 
 ### Invoices (12)
 
@@ -436,7 +314,7 @@ If you need to digitize paper invoices or receipts, extract the data first (e.g.
 | Tool | What it does |
 |------|-------------|
 | `send_einvoice` | Dispatch an invoice in 11 formats (XRechnung, Factur-X, FatturaPA, PEPPOL, Facturae, UBL, CII) via email / Chorus Pro / SDI / PEPPOL / download |
-| `get_einvoice_status` | Poll Hatchet workflow run status until succeeded/failed — returns ackId, XML URL, PDF/A-3 URL |
+| `get_einvoice_status` | Poll an e-invoice dispatch until it succeeds or fails; returns ackId, XML URL and PDF/A-3 URL |
 | `validate_einvoice_xml` | Validate raw XML against format schema + schematron rules (KOSIT / Mustang / XSD / Schematron) |
 | `export_datev` | Export accounting data as DATEV EXTF (Buchungsstapel / Debitoren / Kreditoren) in CP1252 encoding |
 | `einvoice_export` | Export e-invoice data in machine-readable formats (JSON/XML) for archival or integration |
@@ -444,7 +322,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` | **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* |
+| `ksef_submit` | **NOT_DEPLOYED**: submit an invoice to KSeF (Poland). Returns a labeled "unavailable" error until activated |
 
 ### Time Tracking (6)
 
@@ -493,8 +371,8 @@ If you need to digitize paper invoices or receipts, extract the data first (e.g.
 
 | Tool | What it does |
 |------|-------------|
-| `frihet_gl_entry_approve` | Approve a GL journal entry (gestor/admin only — TRUST AREA) |
-| `frihet_gl_entry_reject` | Reject a GL entry with a mandatory reason (TRUST AREA) |
+| `frihet_gl_entry_approve` | Approve a GL journal entry (gestor/admin only, restricted) |
+| `frihet_gl_entry_reject` | Reject a GL entry with a mandatory reason (restricted) |
 | `frihet_gl_entry_audit_log` | Retrieve full audit trail for a GL entry |
 
 ### White-label Portal Domain (3)
@@ -578,7 +456,6 @@ If you need to digitize paper invoices or receipts, extract the data first (e.g.
 | `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 |
-| `ticketbai_status` | Poll TicketBAI submission status — *cross-reference from E-Invoicing (10); NOT counted toward this section's 7* |
 
 ### Vacation Rentals / Stay (5)
 
@@ -631,11 +508,6 @@ 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 — withdrawn via #124
-
-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)
 
@@ -649,8 +521,8 @@ If a future Frihet-ERP release ships the family, restore `src/tools/onboarding.t
 | Tool | What it does |
 |------|-------------|
 | `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) |
+| `period_close` | Close an accounting period (gestor/admin only, restricted) |
+| `period_reopen` | Reopen a closed period with a mandatory reason (restricted) |
 
 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.
 
@@ -663,11 +535,9 @@ On the full MCP surfaces, every `tools/list` entry includes `_meta["io.frihet/ca
 - `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.
-
----
+The ChatGPT app uses a separately reviewed profile of 33 business operations, with no discovery meta-tools, prompts or resources. Its 17 reads and 16 writes are deliberately narrow, and every write requires literal `confirm=true`. Do not infer it from the full catalogue.
 
-## Resources
+### Resources
 
 Context the AI can read to make smarter decisions.
 
@@ -694,9 +564,7 @@ The local package serves 11 resources: 7 static references plus 4 API-backed wor
 | Overdue Invoices | `frihet://overdue-invoices` | All invoices past due date (up to 100) |
 | Plan Limits | `frihet://status/plan-limits` | Live plan tier, usage counters, invoices/month, API rate limits |
 
----
-
-## Prompts (10)
+### Prompts (10)
 
 Pre-built workflows the AI can execute as guided multi-step operations.
 
@@ -713,167 +581,47 @@ Pre-built workflows the AI can execute as guided multi-step operations.
 | `invoice-aging-review` | AR aging analysis: group unpaid invoices by bucket (0-30/31-60/61-90/90+ days), top debtors, collection actions | -- |
 | `expense-batch` | Process expenses in bulk: categorize, apply tax rates, flag missing receipts | `fiscalZone?` |
 
----
+</details>
 
-## How it works
-
-```mermaid
-graph LR
-    AI["Your AI assistant"]
-    MCP["frihet-mcp"]
-    API["api.frihet.io"]
-    DB["Frihet ERP"]
-
-    AI -- "create_invoice()" --> MCP
-    MCP -- "POST /v1/invoices" --> API
-    API --> DB
-    DB -- "201 + invoice data" --> API
-    API -- "structured JSON" --> MCP
-    MCP -- "typed response + suggestions" --> AI
-
-    style AI fill:#09090b,stroke:#4ade80,color:#fafafa
-    style MCP fill:#09090b,stroke:#fafafa,color:#fafafa
-    style API fill:#09090b,stroke:#3f3f46,color:#a1a1aa
-    style DB fill:#09090b,stroke:#3f3f46,color:#a1a1aa
-```
-
-The server translates tool calls into REST API requests. It handles authentication, rate limiting (automatic retry with backoff on 429), pagination, and error mapping.
-
-Two transports:
-- **stdio** (local) -- `npx @frihet/mcp-server` with `FRIHET_API_KEY`
-- **Streamable HTTP** (remote) -- `https://mcp.frihet.io/mcp` with Bearer token or OAuth 2.0+PKCE
+---
 
-### Environment variables
+## Configuration
 
 | Variable | Required | Default |
 |----------|----------|---------|
 | `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.
-
----
-
-## Tool exposure: depth served on demand
-
-Frihet's differentiator is **depth** — full ES/EU fiscal coverage plus native compliance (VeriFactu, TicketBAI, Facturae/FACe; KSeF Poland infra-ready, activation pending), banking, CRM, HR/payroll, stay/PMS and POS. But a flat list of every tool, loaded into an agent's context up front, is the 2026 context-rot problem: it crowds out the task and degrades tool selection before any work begins.
-
-`FRIHET_TOOL_MODE` lets you choose how that depth is exposed.
-
-| Mode | Behavior |
-|------|----------|
-| `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 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:
+`FRIHET_TOOL_MODE=grouped` is progressive disclosure: each tool description collapses to one line and three discovery tools (`list_tool_groups`, `search_tools`, `describe_tool`) are added, so an agent loads full schemas only for the tools it needs. Operation names, input schemas and handlers do not change. The hosted server runs in grouped mode.
 
-- **`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`.
-- **`describe_tool(name)`** — the full original description and input fields for one tool, on demand, before you call it.
-
-```jsonc
-// claude_desktop_config.json — opt in to grouped mode
+```json
 {
   "mcpServers": {
     "frihet": {
       "command": "npx",
       "args": ["@frihet/mcp-server"],
-      "env": {
-        "FRIHET_API_KEY": "fri_...",
-        "FRIHET_TOOL_MODE": "grouped"
-      }
+      "env": { "FRIHET_API_KEY": "fri_...", "FRIHET_TOOL_MODE": "grouped" }
     }
   }
 }
 ```
 
-> Grouped exposure changes description density, not operation behavior. The versioned OpenAI-reviewed profile is composed separately and remains independently gated.
-
----
-
-## API limits
-
-| Limit | Value |
-|-------|-------|
-| Requests per minute | 100 per API key |
-| Results per page | 100 max (50 default) |
-| Request body | 1 MB max |
-| Webhook payload | 100 KB max |
-| Webhooks per account | 20 max |
-
-Rate limiting is handled automatically with exponential backoff.
-
----
-
-## Claude Code Skill
-
-Beyond raw MCP tools, this repo includes a **Claude Code skill** that adds business context: Spanish tax rules, workflow recipes, financial reports, and natural language commands.
-
-### Install the skill
-
-```bash
-git clone https://github.com/Frihet-io/frihet-mcp.git
-ln -s "$(pwd)/frihet-mcp/skills/frihet-mcp" ~/.claude/skills/frihet-mcp
-```
-
-Or with the universal installer:
-
-```bash
-npx skills add Frihet-io/frihet-mcp
-```
-
-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)
+Rate limits depend on your plan; the server retries with exponential backoff on 429. See the [API reference](https://docs.frihet.io/desarrolladores/api-rest).
 
 ---
 
-## Development
-
-```bash
-git clone https://github.com/Frihet-io/frihet-mcp.git
-cd frihet-mcp
-npm install
-npm run build
-```
-
-Run locally:
-
-```bash
-FRIHET_API_KEY=fri_xxx node dist/index.js
-```
-
-Test with the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector):
-
-```bash
-npx @modelcontextprotocol/inspector node dist/index.js
-```
-
----
-
-## Contributing
-
-Contributions are welcome. Please open an issue first to discuss what you'd like to change.
+## Development and contributing
 
 ```bash
 git clone https://github.com/Frihet-io/frihet-mcp.git
 cd frihet-mcp
 npm install
 npm run build   # must pass before submitting
+FRIHET_API_KEY=fri_xxx node dist/index.js
 ```
 
----
-
-## Current limitations
-
-- **No OCR or file upload** -- the MCP works with structured data, not images or PDFs.
-- **Single company** -- one API key maps to one Frihet workspace.
-- **Frihet account required** -- you need an active account at [app.frihet.io](https://app.frihet.io) and an API key (starts with `fri_`).
+Test with the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector): `npx @modelcontextprotocol/inspector node dist/index.js`. Open an issue before large changes. Report vulnerabilities as described in [SECURITY.md](./SECURITY.md).
 
 ---
 
@@ -881,29 +629,14 @@ 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 (156 canonical operations + 5 alias names; 11 local resources; 10 prompts) |
+| [`@frihet/mcp-server`](https://www.npmjs.com/package/@frihet/mcp-server) | This MCP server (158 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 |
 | [REST API](https://docs.frihet.io/desarrolladores/api-rest) | OpenAPI 3.1 at `api.frihet.io/v1` |
-| [Remote MCP](https://mcp.frihet.io) | Hosted endpoint on Cloudflare Workers (zero install) |
 | [Webhooks](https://docs.frihet.io/desarrolladores/webhooks) | Real-time events with HMAC-SHA256 |
 
-## Links
-
-- [Frihet](https://frihet.io) -- The product
-- [Documentation](https://docs.frihet.io) -- Full docs
-- [API reference](https://docs.frihet.io/desarrolladores/api-rest) -- REST API
-- [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) -- 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
-
----
+[Frihet](https://frihet.io) · [Documentation](https://docs.frihet.io) · [MCP server docs](https://docs.frihet.io/desarrolladores/mcp-server) · [OpenAPI spec](https://api.frihet.io/openapi.json)
 
 ## License