@frihet/mcp-server 1.16.5 → 1.17.0

package/README.md

@@ -21,8 +21,8 @@
   <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/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-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">
   <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-18181b?style=flat&labelColor=09090b" alt="TypeScript"></a>
 </p>
 
@@ -47,7 +47,7 @@
 | **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.5) ships all 157 tools, same as the remote endpoint (`mcp.frihet.io`).
+> **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.
 
 ---
 
@@ -60,7 +60,7 @@ 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.
+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.
 
 <!-- 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 -->
 
@@ -80,6 +80,26 @@ 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
 
 ### One-line (Claude Code, Cursor, Copilot, Codex, Windsurf, Gemini CLI, and more)
@@ -106,7 +126,36 @@ Once available in the community marketplace:
 
 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).
 
-### Claude Code / Claude Desktop
+### Claude Code — one command
+
+```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`.)
+
+### 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 Desktop, Cursor, Windsurf, Cline — JSON config
 
 ```json
 {
@@ -124,14 +173,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 +269,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 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.
 
 **Works great:**
 
@@ -249,7 +296,7 @@ If you need to digitize paper invoices or receipts, extract the data first (e.g.
 
 ---
 
-## Tools (157)
+## Catalogue operations (157)
 
 ### Invoices (12)
 
@@ -259,12 +306,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 +376,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)
@@ -395,9 +442,9 @@ If you need to digitize paper invoices or receipts, extract the data first (e.g.
 
 | 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)
@@ -542,15 +589,15 @@ 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)
 
@@ -563,32 +610,45 @@ If you need to digitize paper invoices or receipts, extract the data first (e.g.
 
 | 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 |
@@ -670,10 +730,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 +755,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.
 
 ---
 
@@ -797,7 +857,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 (157 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 |
@@ -816,6 +876,7 @@ npm run build   # must pass before submitting
 - [MCP Registry](https://registry.modelcontextprotocol.io/?q=io.frihet) -- Anthropic official registry
 - [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 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 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

package/dist/agent-onboarding.js

@@ -0,0 +1,275 @@
+/**
+ * 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.
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CAPABILITY_META_KEY } from "./capability-truth.js";
+import { localMcpSurfaceComposition, registerMcpSurface, } from "./server-composition.js";
+export 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 const API_KEY_LOCATION = "https://app.frihet.io/settings/api";
+/* ------------------------------------------------------------------ */
+/*  1. initialize.instructions                                         */
+/* ------------------------------------------------------------------ */
+export const AGENT_SERVER_INSTRUCTIONS = `Frihet ERP — real business and fiscal records. Read freely, propose before you mutate.
+
+AUTH
+- Local (stdio): FRIHET_API_KEY=fri_... — create one at ${API_KEY_LOCATION}.
+- No key yet: FRIHET_DEMO=1 serves example fixtures. No network call, nothing persisted, demo_-prefixed IDs, fiscal actions simulated.
+- Hosted: https://mcp.frihet.io/mcp — OAuth 2.1 + PKCE, or Authorization: Bearer fri_...
+
+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.
+
+CAPABILITY DISCOVERY
+- Every tool in tools/list carries _meta["${CAPABILITY_META_KEY}"] = {callability, writesFrihet, externalInteraction, externalSideEffects}. Read it before you call.
+- 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.
+- Large surface: set FRIHET_TOOL_MODE=grouped for progressive disclosure (list_tool_groups, search_tools, describe_tool) instead of loading every schema.
+
+THE SAFE WORKFLOW — draft, show, stop
+- 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.
+- Build the draft, read it back, present it to the human, and stop there. Issuing is a separate, human-authorised step.
+
+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.
+- 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
+- Errors carry sanitized remediation text — read it, do not guess. 401 = key; 403 = scope or plan; 429 = wait Retry-After seconds.
+- 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.
+
+Machine-readable version of this contract: https://github.com/Frihet-io/frihet-mcp/blob/main/docs/agent-onboarding.json`;
+function makeRegistrationClient() {
+    return new Proxy({}, { get: () => async () => ({ data: [], total: 0, limit: 0, offset: 0 }) });
+}
+/** True when the tool's JSON Schema declares a top-level `confirm` property.
+ *  Derived, never hand-listed — a new confirm guard shows up in the descriptor
+ *  on the next generate, and the gate fails until it is committed. */
+function declaresConfirm(inputSchema) {
+    if (typeof inputSchema !== "object" || inputSchema === null)
+        return false;
+    const properties = inputSchema.properties;
+    if (typeof properties !== "object" || properties === null)
+        return false;
+    return Object.hasOwn(properties, "confirm");
+}
+async function captureLocalFullSurface() {
+    const server = new McpServer({
+        name: "agent-onboarding-capture",
+        version: "1.0.0",
+    });
+    registerMcpSurface(server, makeRegistrationClient(), localMcpSurfaceComposition(false, false));
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    const client = new Client({ name: "agent-onboarding-capture-client", version: "1.0.0" }, { capabilities: {} });
+    try {
+        await Promise.all([
+            server.connect(serverTransport),
+            client.connect(clientTransport),
+        ]);
+        const listed = await client.listTools();
+        const tools = listed.tools
+            .map((tool) => {
+            const meta = tool._meta;
+            const capability = meta?.[CAPABILITY_META_KEY];
+            return {
+                name: tool.name,
+                annotations: (tool.annotations ?? {}),
+                ...(capability ? { capability } : {}),
+                hasConfirm: declaresConfirm(tool.inputSchema),
+            };
+        })
+            .sort((left, right) => left.name.localeCompare(right.name));
+        const [resources, prompts] = await Promise.all([
+            client.listResources(),
+            client.listPrompts(),
+        ]);
+        return {
+            tools,
+            resources: resources.resources.length,
+            prompts: prompts.prompts.length,
+        };
+    }
+    finally {
+        await Promise.allSettled([client.close(), server.close()]);
+    }
+}
+export async function captureAgentOnboardingDescriptor() {
+    const { tools, resources, prompts } = await captureLocalFullSurface();
+    const confirmRequired = tools
+        .filter((tool) => tool.hasConfirm)
+        .map((tool) => tool.name);
+    const externalSideEffects = tools
+        .filter((tool) => (tool.capability?.externalSideEffects.length ?? 0) > 0)
+        .map((tool) => ({
+        tool: tool.name,
+        effects: [...(tool.capability?.externalSideEffects ?? [])],
+    }));
+    return {
+        onboardingContractVersion: AGENT_ONBOARDING_CONTRACT_VERSION,
+        server: {
+            mcpName: "io.frihet/erp",
+            npmPackage: "@frihet/mcp-server",
+            remoteEndpoint: "https://mcp.frihet.io/mcp",
+            transport: ["stdio", "streamable-http"],
+        },
+        auth: {
+            envVar: "FRIHET_API_KEY",
+            keyFormat: "fri_<key>",
+            obtainAt: API_KEY_LOCATION,
+            remoteMethods: ["oauth2.1-pkce", "bearer"],
+            noAuthTrial: {
+                env: { FRIHET_DEMO: "1" },
+                persists: false,
+                network: false,
+            },
+        },
+        quickstart: {
+            "claude-code": {
+                steps: [
+                    "claude mcp add frihet -s user -e FRIHET_API_KEY=fri_... -- npx -y @frihet/mcp-server",
+                ],
+                configFormat: "managed by the CLI (user scope writes ~/.claude.json)",
+                verify: "claude mcp list",
+            },
+            codex: {
+                steps: [
+                    "codex mcp add frihet --env FRIHET_API_KEY=fri_... -- npx -y @frihet/mcp-server",
+                ],
+                configFormat: "toml (~/.codex/config.toml — JSON in this file is a parse error)",
+                verify: "codex mcp list",
+            },
+            "generic-mcp-client-stdio": {
+                steps: [
+                    'mcpServers.frihet = { "command": "npx", "args": ["-y", "@frihet/mcp-server"], "env": { "FRIHET_API_KEY": "fri_..." } }',
+                ],
+                configFormat: "json",
+                verify: "initialize → tools/list returns a non-empty catalogue",
+            },
+            "generic-mcp-client-http": {
+                steps: [
+                    'mcpServers.frihet = { "type": "streamable-http", "url": "https://mcp.frihet.io/mcp", "headers": { "Authorization": "Bearer fri_..." } }',
+                ],
+                configFormat: "json",
+                verify: "initialize → tools/list returns a non-empty catalogue",
+            },
+        },
+        capabilityDiscovery: {
+            metaKey: CAPABILITY_META_KEY,
+            callabilityValues: [
+                "api_dependent",
+                "runtime_checked",
+                "deferred",
+                "unavailable",
+                "local",
+            ],
+            groupedModeEnv: { FRIHET_TOOL_MODE: "grouped" },
+            counts: {
+                toolNames: tools.length,
+                readOnly: tools.filter((tool) => tool.annotations.readOnlyHint === true)
+                    .length,
+                writesFrihet: tools.filter((tool) => tool.capability?.writesFrihet === true).length,
+                externalInteraction: externalSideEffects.length,
+                destructive: tools.filter((tool) => tool.annotations.destructiveHint === true).length,
+                resources,
+                prompts,
+            },
+        },
+        safeWorkflow: {
+            description: "Discover → orient → retrieve → propose → hand back. No step mutates data or reaches a third party.",
+            steps: [
+                {
+                    call: "get_business_context",
+                    kind: "read",
+                    note: "Fiscal zone, currency and defaults. Everything downstream depends on it.",
+                },
+                {
+                    call: "resources/read frihet://tax/rates",
+                    kind: "read",
+                    note: "Authoritative IVA / IGIC / IPSI table. Do not recall a rate from memory.",
+                },
+                {
+                    call: "list_clients",
+                    kind: "read",
+                    note: "Resolve the client by name before referencing an id.",
+                },
+                {
+                    call: "STOP",
+                    kind: "handoff",
+                    note: "Present the proposed draft inputs and all disclosed effects. Creating, issuing, sending, or submitting is a separate human decision.",
+                },
+            ],
+        },
+        humanAuthority: {
+            rule: "Do not call a tool with non-empty externalSideEffects, and do not set confirm=true, without an explicit human instruction for that specific action.",
+            confirmRequired,
+            externalSideEffects,
+        },
+        errors: [
+            {
+                condition: "startup exits 1 with code FRIHET_API_KEY_MISSING",
+                meaning: "No credential in the environment.",
+                agentAction: "Ask the human for a key from " +
+                    API_KEY_LOCATION +
+                    ", or re-launch with FRIHET_DEMO=1 to explore without one.",
+            },
+            {
+                condition: "HTTP 401",
+                meaning: "Key missing, malformed or revoked.",
+                agentAction: "Stop and ask for a new key. Do not retry.",
+            },
+            {
+                condition: "HTTP 403",
+                meaning: "The key is valid but lacks the scope, or the plan excludes it.",
+                agentAction: "Report which operation was refused. Do not try a different tool to route around it.",
+            },
+            {
+                condition: "HTTP 429",
+                meaning: "Rate limited.",
+                agentAction: "Wait the Retry-After seconds, then retry once.",
+            },
+            {
+                condition: "HTTP 409 IDEMPOTENCY_REQUEST_IN_PROGRESS",
+                meaning: "The first attempt's outcome could not be recorded; the server refuses to execute twice.",
+                agentAction: "Read the resource back and reconcile from its actual state. Never retry with a fresh Idempotency-Key.",
+            },
+            {
+                condition: "capability.callability is deferred or unavailable",
+                meaning: "The tool is registered but the backing API is not serving it.",
+                agentAction: "Do not call it. Tell the human the capability is not live for this workspace.",
+            },
+        ],
+    };
+}
+export function serializeAgentOnboardingDescriptor(descriptor) {
+    return JSON.stringify(descriptor, null, 2) + "\n";
+}
+//# sourceMappingURL=agent-onboarding.js.map