io.github.ar-agents/mcp

Cancelar un envío que aún no salió a reparto. Returns { canceled: bool, reason? }. Si canceled=false, surface reason verbatim al usuario (típicamente 'ya está en reparto' o 'el carrier no soporta cancelación post-pickup'). Para envíos ya entregados, NO se puede cancelar — el usuario tiene que coordinar una devolución manual.

Consultar los detalles completos de una factura ya emitida (CAE, fecha, importes, doc receptor). USE WHEN: necesitás verificar que un CAE es válido y matchea con tu base de datos, o estás migrando de otro sistema y querés re-cargar facturas históricas. PURE READ: no side effects.

Consultar el último número de comprobante autorizado para un (PtoVta, CbteTipo) — i.e. cuál fue el número del último Factura C emitido desde el punto de venta 1. USE BEFORE emitir_factura para obtener el próximo número (último + 1). Returns 0 si nunca se emitió un comprobante de ese tipo desde ese PtoVta — entonces el próximo es 1. PURE READ: no side effects.

Cotizar el costo de un envío vía un carrier específico (Andreani, OCA, o Correo Argentino). Pasá origen + destino + paquetes (peso + dimensiones + valor declarado) y servicio (standard, express, same_day). Returns { carrier, costArs, estimatedDaysMin, estimatedDaysMax, productId }. USE WHEN el usuario quiere el precio de UN carrier conocido. Para comparar entre carriers, usá cotizar_envio_todos.

Cotizar un envío en TODOS los carriers configurados en paralelo. Returns { quotes: QuoteOption[] } ordenado por costo (más barato primero). USE WHEN el usuario dice 'cuál es el envío más barato' o 'compará Andreani vs OCA vs Correo'. Si un carrier falla individualmente, los otros igual responden — el campo error en cada quote indica si falló.

Crear un envío real con un carrier. RETURNS un trackingNumber + labelUrl + costo. SIDE EFFECT: el envío queda registrado en el sistema del carrier — confirma con el usuario antes si el monto es alto (>$10k declared value). Para Andreani, requiere productId del cotizador previo si querés bloquear el precio. Usá `externalReference` para reconciliar con tu order id.

Emitir una factura electrónica vía AFIP/ARCA WSFE. Solicita el CAE (Código de Autorización Electrónico) que valida la factura ante AFIP. RETURNS: el CAE (14 dígitos), su fecha de vencimiento, y el número de comprobante asignado, o errors/observaciones si AFIP rechazó. SIDE EFFECT: el CAE queda registrado en AFIP — NO se puede deshacer; para anular, emitir Nota de Crédito. PRE-FLIGHT: validate_cuit (del receptor) + consultar_ultimo_comprobante para obtener el próximo número. CONSTRAINTS: ImpTotal = ImpNeto + ImpIVA + ImpOpEx + ImpTrib + ImpTotConc (AFIP error 10048 si no). Para Factura C (monotributista), ImpIVA debe ser 0 y no incluir filas iva. Para Servicios, fchServDesde/Hasta/VtoPago obligatorios. Para Notas de Crédito/Débito, cbtesAsoc obligatorio referenciando el comprobante original. The lib pre-valida estas reglas localmente antes del round-trip a AFIP.

Health check de AFIP WSFE — devuelve el status de los servidores app, db, y auth. Use as a /health endpoint o como pre-flight rápido antes de emitir muchas facturas. PURE READ, latencia < 200ms.

Return the full list of known Argentine banks with their BCRA codes. USE THIS WHEN: you need to render a dropdown of banks for the user to pick from, or need to enumerate available entities for a workflow. Sorted by BCRA code. Returns array of `{ code, name, shortName, kind }`.

Return the full list of known Argentine PSPs (fintechs / digital wallets / virtual account issuers — Mercado Pago, Ualá, Naranja X, Personal Pay, etc.) with their CVU prefixes. USE THIS WHEN: you need to render a dropdown of fintech wallets for the user to pick from, or need to enumerate PSPs for a workflow. Returns array of `{ code, name, shortName, kind }` where `code` is the 7-digit CVU prefix.

Listar las sucursales / centros de despacho de un carrier cerca de un Código Postal Argentino (CPA). Returns array con id, name, address, openingHours, distanceKm cuando disponible. USE WHEN el usuario quiere despachar el envío en sucursal en lugar de retiro a domicilio, o cuando necesita un punto Pickup para que el destinatario retire.

Look up the Argentine bank or PSP (payment service provider) by its 3-digit BCRA-assigned entity code. PURE FUNCTION: in-memory lookup, free, sub-millisecond. Returns the entity's full legal name, short brand name, and kind (cbu = traditional bank, cvu = fintech). USE THIS WHEN: you have a bank code (e.g., from a CBU you've already parsed, from a user's input dropdown, from a transaction record) and need its human-readable name. For CVU prefixes (0000031 etc.), pass the 7-digit prefix; for traditional banks pass the 3-digit code. Returns null when the code isn't in the lookup table — the table is BCRA-published but updated periodically, so newer fintechs may be missing.

Look up the BCRA Central de Deudores credit situation for an Argentine CUIT. Returns the worst situation code (1=normal, 2=low risk <90 days, 3=medium risk 90-180 days, 4=high risk 180-365 days, 5=irrecoverable, 6=irrecoverable by admin disposition), total outstanding debt across all entities, and per-entity breakdown. USE THIS WHEN: the user is assessing counterparty risk before extending credit, factoring invoices, or onboarding a B2B supplier. DO NOT USE for routine billing decisions — Mercado Pago handles credit risk on the SaaS's behalf for normal subscription flows. REQUIRES: a `BcraDeudaAdapter` configured at app boot. The default `BcraPublicApiAdapter` hits BCRA's public REST API (no auth required). When NOT configured, returns `{ available: false, error: <setup instructions> }` instead of crashing — surface the error verbatim. ALWAYS call `validate_cuit` (from @ar-agents/identity) first to confirm format before hitting BCRA.

Look up an Argentine CUIT/CUIL against AFIP's padron webservice. Returns taxpayer name, tax condition (Monotributo / Responsable Inscripto / etc.), monotributo category if applicable, and registered address. REQUIRES an `AfipPadronAdapter` configured at app boot — typically wired to AFIP's WSAA + WSCDC SOAP integration which itself requires an X.509 cert registered with AFIP. WHEN NOT CONFIGURED: this tool returns `{ available: false, error: <setup instructions> }` instead of crashing. SURFACE the error message verbatim to the user — it contains the actionable steps to enable the lookup. DO NOT make up taxpayer info if available is false. USE THIS WHEN: the user asks for the taxpayer's name, tax condition, monotributo category, registered address, or activities. ALWAYS call `validate_cuit` first to confirm the format is sound — there's no point hitting AFIP for a malformed CUIT.

Listar las alícuotas de IVA disponibles según AFIP (21%=5, 10.5%=4, 27%=6, 0%=3, etc.). USE WHEN: el usuario necesita ver las opciones para construir una factura B o A. HEAVY: round-trip a AFIP. Preferí `AlicuotaIva` constants para flujos comunes.

Obtener la cotización oficial AFIP de una moneda extranjera vs ARS. REQUIRED antes de emitir cualquier factura no-PES (AFIP rechaza si la cotización está desactualizada). Devuelve el monCotiz a usar en `emitir_factura`. PURE READ.

Listar los tipos de comprobante disponibles según AFIP (Factura A=1, B=6, C=11, Nota Crédito A=3, etc.). USE WHEN: necesitás mostrar al usuario la lista actualizada (puede haber tipos nuevos que no están en los catalogs hard-coded del lib). HEAVY: hace network round-trip a AFIP — para flujos comunes preferí los constants de `CbteTipo` en `@ar-agents/facturacion`.

Listar los tipos de concepto: Productos (1), Servicios (2), Productos y Servicios (3). HEAVY: round-trip a AFIP. Preferí `Concepto` constants.

Listar los tipos de documento que AFIP acepta (CUIT=80, DNI=96, Pasaporte=94, Consumidor Final=99, etc.). HEAVY: round-trip a AFIP. Preferí los constants de `DocTipo` para flujos comunes.

Listar las monedas que WSFE acepta para emitir facturas (PES = Pesos, DOL = Dólar, 060 = Euro, 012 = Real, etc.). USE WHEN: el usuario quiere emitir Factura E (exportación) o multi-moneda. HEAVY: round-trip a AFIP.

Consultar el estado actual de un envío vía su trackingNumber. Returns { currentStatus, events[], deliveredAt? }. currentStatus normalizado a uno de: label_created, in_transit, out_for_delivery, delivered, delivery_failed, returned, canceled, exception, unknown. SURFACE los `events` al usuario en orden cronológico — muestran el detalle del recorrido.

Validate an Argentine CBU (Clave Bancaria Uniforme, traditional bank account) or CVU (Clave Virtual Uniforme, fintech wallet account) via the BCRA dual mod-10 check-digit algorithm. PURE FUNCTION: no API call, no environment dependencies, sub-millisecond latency, free. Returns whether the input is mathematically valid PLUS the bank/PSP identification (e.g., '007 → Banco Galicia', '0000031 → Mercado Pago'), the branch code, and the account number. USE THIS WHEN: the user pastes a CBU/CVU and you need to detect typos, identify the issuing bank/wallet, or extract the account components before submitting a transfer or alias setup. Always call this BEFORE any transfer-related action — invalid CBUs cause hard failures downstream and chargebacks. Distinguishes CBU vs CVU automatically via the entity-code prefix.

Validate an Argentine CUIT/CUIL via the AFIP modulo-11 check digit algorithm. PURE FUNCTION: no API call, no environment dependencies, sub-millisecond latency, free. Returns whether the input is mathematically valid plus the inferred person type (persona física vs jurídica). USE THIS WHEN: the user pastes a CUIT/CUIL and you need to detect typos, infer person type from the prefix, or normalize formatting before downstream operations. DO NOT USE WHEN: the user wants the taxpayer's name, tax condition, or monotributo category — call `lookup_cuit_afip` for that. Always call `validate_cuit` first; if it returns invalid, do NOT call `lookup_cuit_afip` (you already know the answer is no, and you'd waste an AFIP request).