diff --git a/CHANGELOG.md b/CHANGELOG.md index 3a72cc4e..3b3d4cdf 100644 --- a/CHANGELOG.md +++ b/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" diff --git a/docs/reference/vs-official-mcp.es.md b/docs/reference/vs-official-mcp.es.md index 41391ae0..b209131b 100644 --- a/docs/reference/vs-official-mcp.es.md +++ b/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: diff --git a/docs/reference/vs-official-mcp.md b/docs/reference/vs-official-mcp.md index b60185b5..67b0dcc0 100644 --- a/docs/reference/vs-official-mcp.md +++ b/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: