docs: correct MCP comparison with the actual 66 read-only tools

CHANGELOG.md

@@ -6,7 +6,17 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
-## [0.9.2] - 2026-06-11
+## [0.9.3] - 2026-06-11
+
+### Changed
+- Docs: corrected the "vs. the official MCP" comparison against the official
+  server's **actual** tool surface, captured by connecting it through claude.ai
+  and inspecting every tool. It exposes **66 read-only tools** (not 49 as a
+  partial earlier list suggested) covering almost the whole API — including
+  accounting, currencies, sellers, incoming payments, retentions, taxes, ledger
+  categories, and resolutions, which the page had wrongly listed as
+  alegra-cli-only. The read surface is broad; the difference remains that the
+  MCP writes nothing while alegra-cli reads and writes (plus emission). EN + ES.
 
 ### Changed
 - Docs: clearer Spanish in the Agent Safety guide — replaced the "gatear"

docs/reference/vs-official-mcp.es.md

@@ -8,11 +8,11 @@ servidor MCP (`alegra mcp`) y funciona para personas en una terminal. Esta pági
 ambos para que elijas el que mejor te encaje.
 
 !!! note "Foto del momento"
-    Refleja el **conjunto de herramientas desplegado en vivo del servidor MCP oficial (49
-    herramientas de solo lectura)** y `alegra-cli` **v0.8.1**, verificado el **2026-06-11**
-    conectándose a `mcp.alegra.com`. Ambos envuelven la misma API v1 de Alegra y ambos
-    requieren acceso de red a ella. Alegra puede cambiar su MCP con el tiempo — trátalo como
-    una foto de un momento puntual.
+    Refleja el **conjunto de herramientas en vivo del MCP oficial (66 herramientas de solo
+    lectura)** y `alegra-cli` **v0.9.2**, verificado el **2026-06-11** conectando el MCP
+    oficial vía claude.ai e inspeccionando cada tool. Ambos envuelven la misma API v1 de
+    Alegra y ambos requieren acceso de red a ella. Alegra puede cambiar su MCP con el
+    tiempo — trátalo como una foto de un momento puntual.
 
 ## De un vistazo
 
@@ -26,7 +26,7 @@ ambos para que elijas el que mejor te encaje.
 | Salida | Resultados de herramienta en JSON estructurado | tabla / JSON / YAML / CSV — combinable con `jq` y pipes (menos tokens para un agente) |
 | Controles de seguridad para agentes | Depende del host | `--dry-run` en cualquier comando, confirmación interactiva en `delete`, restringible con hooks del shell |
 | Uso humano (terminal) | — | De primera clase |
-| Cobertura de recursos | 17 áreas (49 herramientas) | 45+ recursos |
+| Cobertura de recursos | ~25 áreas (66 herramientas), todas de lectura | 45+ recursos |
 | Escrituras (create / update / delete) | No expuestas — solo lectura | Sí |
 | Emisión de facturas (stamp / void / email) | No expuesta | Sí |
 
@@ -69,25 +69,26 @@ persona escribiendo comandos. El razonamiento está expuesto en el post
 ## Cobertura de recursos
 
 Ambos envuelven la misma API v1 de Alegra pero exponen porciones distintas de ella. La
-diferencia clave: las 49 herramientas del MCP oficial son todas de **solo lectura**
+diferencia clave: las 66 herramientas del MCP oficial son **todas de solo lectura**
 (`get…`/`list…`), mientras que `alegra-cli` lee *y* escribe.
 
 ### Leídos por ambos, escritos solo por alegra-cli
-Contactos; ítems (con stock por bodega vía `items stock`) y la familia de inventario
-(categorías de ítems, atributos de variantes, bodegas, transferencias, listas de precios,
-ajustes y numeraciones, campos personalizados); cuentas bancarias y conciliaciones;
-facturas; la familia de gastos (facturas de compra, notas débito de proveedor, órdenes de
-compra, pagos salientes); reportes de ventas; y los catálogos de referencia de unidades /
-claves de producto del SAT. El MCP oficial los expone en **solo lectura**; `alegra-cli`
-además los crea, actualiza y elimina.
+El MCP oficial lee casi toda la API: contactos; ítems (con stock por bodega) y la familia
+de inventario (categorías de ítems, atributos de variantes, bodegas, transferencias, listas
+de precios, ajustes y numeraciones, campos personalizados); cuentas bancarias y
+conciliaciones; contabilidad (libros diarios, centros de costo, categorías del libro mayor);
+facturas; pagos entrantes y salientes; la familia de gastos (facturas de compra, notas
+débito de proveedor, órdenes de compra); impuestos; retenciones; monedas; vendedores;
+resoluciones/numeraciones; reportes de ventas; y los catálogos de referencia de unidades /
+claves de producto del SAT. Todos los expone en **solo lectura**; `alegra-cli` además los
+crea, actualiza y elimina.
 
 ### Solo en alegra-cli
-Recursos que el MCP oficial no expone en absoluto: libros diarios, centros de costo,
-impuestos, retenciones, monedas, vendedores, cotizaciones, notas crédito, notas débito de
-cliente (ingresos), remisiones, recibos de transporte, facturas globales (CFDI), facturas y
-pagos recurrentes, numeraciones de documentos, términos de pago, cargos adicionales, pagos
-entrantes y suscripciones a webhooks. Además de toda operación de escritura y la emisión de
-facturas electrónicas (ver más abajo).
+Recursos que el MCP oficial no expone en absoluto: cotizaciones, notas crédito, notas débito
+de cliente (ingresos), remisiones, recibos de transporte, facturas globales (CFDI), facturas
+y pagos recurrentes, términos de pago, cargos adicionales y suscripciones a webhooks. Además
+de **toda operación de escritura** en todos los recursos y la emisión de facturas
+electrónicas (ver más abajo).
 
 **Claves de producto del SAT** (`claveProdServ`, ~52k entradas específicas de México): el
 MCP oficial expone una herramienta de solo lectura `config_getProductKeys`. `alegra-cli`
@@ -108,9 +109,9 @@ factura electrónica a la DIAN/SAT, anularla o enviarla por correo se hace con `
 (`alegra invoices stamp|void|email …`) o con la API REST directamente. Si la emisión
 electrónica es parte de tu flujo de trabajo, la CLI cubre el ciclo completo.
 
-**Pagos.** El MCP oficial expone únicamente pagos **salientes**, en solo lectura, dentro de
-sus herramientas de gastos. `alegra-cli` tiene un único recurso `payments` que cubre tanto
-entrantes como salientes, con lectura, escritura y `stamp`/`void`/`open`.
+**Pagos.** El MCP oficial lee pagos entrantes (`incomePayments`) y salientes (pagos de la
+familia de gastos). `alegra-cli` los unifica en un único recurso `payments` y agrega
+escritura, `stamp`, `void` y `open`.
 
 **Reportes.** Los dos conjuntos de reportes son complementarios:
 

docs/reference/vs-official-mcp.md

@@ -7,10 +7,11 @@ is built **agent-first** as a command-line tool that AI agents drive directly 
 page compares the two so you can pick the right fit.
 
 !!! note "Snapshot"
-    Reflects the official MCP server's **live deployed tool set (49 read-only tools)** and
-    `alegra-cli` **v0.8.1**, verified **2026-06-11** by connecting to `mcp.alegra.com`.
-    Both wrap the same Alegra v1 API and both require network access to it. Alegra may
-    change its MCP over time — treat this as a point-in-time snapshot.
+    Reflects the official MCP server's **live tool set (66 read-only tools)** and
+    `alegra-cli` **v0.9.2**, verified **2026-06-11** by connecting the official MCP through
+    claude.ai and inspecting every tool. Both wrap the same Alegra v1 API and both require
+    network access to it. Alegra may change its MCP over time — treat this as a
+    point-in-time snapshot.
 
 ## At a glance
 
@@ -24,7 +25,7 @@ page compares the two so you can pick the right fit.
 | Output | Structured JSON tool results | table / JSON / YAML / CSV — composable with `jq` and pipes (fewer tokens for an agent) |
 | Agent safety controls | Host-dependent | `--dry-run` on any command, interactive confirm on `delete`, restrictable via shell hooks |
 | Human (terminal) use | — | First-class |
-| Resource coverage | 17 areas (49 tools) | 45+ resources |
+| Resource coverage | ~25 areas (66 tools), all reads | 45+ resources |
 | Writes (create / update / delete) | Not exposed — read-only | Yes |
 | Invoice emission (stamp / void / email) | Not exposed | Yes |
 
@@ -65,24 +66,25 @@ typing commands. The rationale is laid out in the post
 ## Resource coverage
 
 Both wrap the same Alegra v1 API but expose different slices of it. The key difference:
-the official MCP's 49 tools are all **read-only** (`get…`/`list…`), while `alegra-cli`
+the official MCP's 66 tools are **all read-only** (`get…`/`list…`), while `alegra-cli`
 reads *and* writes.
 
 ### Read by both, written only by alegra-cli
-Contacts; items (with per-warehouse stock via `items stock`) and the inventory family
-(item categories, variant attributes, warehouses, transfers, price lists, adjustments and
-numerations, custom fields); bank accounts and reconciliations; invoices; the expenses
-family (bills, supplier debit notes, purchase orders, outgoing payments); sales reports;
-and the units / SAT product-key reference catalogs. The official MCP exposes these
-**read-only**; `alegra-cli` also creates, updates, and deletes them.
+The official MCP reads almost the whole API: contacts; items (with per-warehouse stock)
+and the inventory family (item categories, variant attributes, warehouses, transfers,
+price lists, adjustments and numerations, custom fields); bank accounts and
+reconciliations; accounting (journals, cost centers, ledger categories); invoices;
+incoming and outgoing payments; the expenses family (bills, supplier debit notes, purchase
+orders); taxes; retentions; currencies; sellers; resolutions/numberings; sales reports;
+and the units / SAT product-key reference catalogs. It exposes all of these **read-only**;
+`alegra-cli` also creates, updates, and deletes them.
 
 ### Only in alegra-cli
-Resources the official MCP does not expose at all: journals, cost centers, taxes,
-retentions, currencies, sellers, estimates, credit notes, customer (income) debit notes,
-remissions, transportation receipts, global invoices (CFDI), recurring invoices and
-payments, document numberings, payment terms, additional charges, incoming payments, and
-webhook subscriptions. Plus every write operation and electronic invoice emission (see
-below).
+Resources the official MCP does not expose at all: estimates, credit notes, customer
+(income) debit notes, remissions, transportation receipts, global invoices (CFDI),
+recurring invoices and payments, payment terms, additional charges, and webhook
+subscriptions. Plus **every write operation** across all resources and electronic invoice
+emission (see below).
 
 **SAT product keys** (`claveProdServ`, ~52k Mexico-specific entries): the official MCP
 exposes a read-only `config_getProductKeys` tool. `alegra-cli` syncs the SAT's published
@@ -103,9 +105,9 @@ invoice to DIAN/SAT, voiding, or emailing it is done with `alegra-cli`
 (`alegra invoices stamp|void|email …`) or the REST API directly. If electronic emission
 is part of your workflow, the CLI covers the full cycle.
 
-**Payments.** The official MCP exposes only **outgoing** payments, read-only, under its
-expenses tools. `alegra-cli` has a single `payments` resource covering both incoming and
-outgoing, with read, write, and `stamp`/`void`/`open`.
+**Payments.** The official MCP reads both incoming (`incomePayments`) and outgoing
+(`expenses` outgoing-payments) payments. `alegra-cli` unifies them under one `payments`
+resource and adds write, `stamp`, `void`, and `open`.
 
 **Reports.** The two report sets are complementary: