MCP Three-Way Invoice Match

Compara localmente las cantidades y precios de SKU de las facturas de proveedores contra órdenes de compra, recibos y facturas anteriores.

GitHub

Documentación

Servidor MCP de conciliación de facturas de proveedores a tres bandas

Servidor MCP para conciliación a tres bandas: verificación de facturas de proveedores contra órdenes de compra y recepciones aceptadas por SKU. Verificación de factura de proveedor, orden de compra y recepción por SKU exacto.

Funciona con Claude Desktop, Claude Code, Cursor y cualquier cliente del Model Context Protocol. Se ejecuta en tu propia máquina: este no tiene un endpoint alojado, así que instálalo desde el paquete o desde el código fuente.

Página del producto: https://mcp.zovo.one/s/three-way-match — capacidades, límites gratuitos y rutas de instalación compatibles.

Prueba el ejemplo editable de conciliación en tu navegador antes de instalar. No se necesita cuenta; las comprobaciones del ejemplo se ejecutan en tu navegador sin subir valores de campos.

Instalar

Claude Desktop, un clic. Descarga three-way-match.mcpb del catálogo de paquetes y haz doble clic en él.

Desde el código fuente. El espejo es autocontenido: cada dependencia de @theluckystrike/* está incluida, por lo que un clon nuevo se compila sin configuración adicional.

git clone https://github.com/theluckystrike/mcp-three-way-match.git
cd mcp-three-way-match
npm install && npm run build

Luego apunta tu cliente al punto de entrada compilado:

{
  "mcpServers": {
    "three-way-match": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-three-way-match/dist/index.js"]
    }
  }
}

@theluckystrike/mcp-three-way-match aún no está publicado en npm, por lo que un comando npx -y @theluckystrike/mcp-three-way-match fallará. Las tres rutas anteriores son las que funcionan y cada una está probada por CI.

three-way-match demo

Espejo de solo lectura de mcp-servers/servers/three-way-match. Consulta MIRROR.md.

Verifica una factura de proveedor contra su orden de compra y recibos de entrega en Claude u otro cliente MCP. Este servidor local compara cada SKU exacto, precio unitario y cantidad facturada con la orden de compra, las entregas aceptadas acumuladas y las cantidades que indiques que ya fueron facturadas. Detecta errores de SKU compensados incluso cuando los totales generales de la factura y la orden de compra coinciden, y devuelve los valores de origen detrás de cada excepción. Proporciona documentos estructurados; este servidor no extrae PDFs, no realiza OCR, no se conecta a un ERP, no registra pagos ni aprueba una factura.

Creado por theluckystrike. MIT. Soporte: support@zovo.one.

Instalar

Claude Desktop: descarga three-way-match.mcpb v0.22.8 y ábrelo. SHA-256: 6397928ec44ea9d5c406a66f4eb7aa9a2f34f5731bf8ef9972fadfdac882f040. Otros clientes pueden usar las instrucciones de código fuente a continuación.

Requiere Node.js 18 o superior. Compila desde el checkout del código fuente; el paquete npm no está publicado. No se requiere clave API ni cuenta para ejecutar las herramientas gratuitas.

git clone https://github.com/theluckystrike/mcp-servers.git
cd mcp-servers
npm install
node scripts/bootstrap-timezone.mjs
npm run build --workspace @theluckystrike/mcp-license
npm run build --workspace @theluckystrike/mcp-three-way-match

Usa la ruta absoluta a servers/three-way-match/dist/index.js en tu checkout. El servidor habla stdio; tu cliente MCP lo inicia. No pongas una URL HTTP en su lugar.

Claude Desktop: fusiona esta entrada en mcpServers en ~/Library/Application Support/Claude/claude_desktop_config.json en macOS (o %APPDATA%\Claude\claude_desktop_config.json en Windows), reemplazando /absolute/path con la ubicación de tu checkout:

{
  "mcpServers": {
    "three-way-match": {
      "command": "node",
      "args": ["/absolute/path/mcp-servers/servers/three-way-match/dist/index.js"]
    }
  }
}

Claude Code:

claude mcp add three-way-match -- node /absolute/path/mcp-servers/servers/three-way-match/dist/index.js

Cursor: fusiona el mismo JSON en .cursor/mcp.json en tu proyecto o ~/.cursor/mcp.json. Reinicia tu cliente, llama a license_status y luego ejecuta el ejemplo a continuación. Un resultado tools/list por sí solo no verifica la conciliación.

Para Claude Desktop, descarga three-way-match.mcpb y ábrelo para instalar. SHA-256: 6397928ec44ea9d5c406a66f4eb7aa9a2f34f5731bf8ef9972fadfdac882f040. Este es un servidor stdio local; no hay endpoint alojado disponible.

Herramientas

Herramienta	Argumentos y resultado
`three_way_match`	PO, recibos, factura, `prior_invoiced` requerido, `save` opcional; devuelve informe completo y resultado del guardado.
`report_list`	`offset` opcional (0), `limit` (20, máximo 100); devuelve UUIDs guardados y resúmenes.
`report_get`	`id`; documentos de origen, todos los problemas y evidencia por SKU.
`report_page`	`id`, `section`, `offset`/`limit` opcionales, `receipt_index`/`sku`; páginas gratuitas de cada problema, evidencia de SKU y fila de origen.
`report_delete`	`id`; elimina ese informe guardado y libera un espacio de almacenamiento.
`report_export_csv`	`id`, `offset`/`limit` opcionales; texto CSV más moneda, estado y códigos de problema a nivel de documento; las exportaciones grandes se paginan.
`license_status`	Sin argumentos; estado gratuito/Pro sin conexión y enlace de checkout.
`license_activate`	`key`; verifica y almacena una clave Pro sin conexión.

Contrato de entrada

Una PO y una factura de proveedor actual por llamada. No hay coincidencia difusa: SKU, proveedor y referencias de PO son cadenas exactas, sensibles a mayúsculas y minúsculas, sin espacios circundantes ni caracteres de control. Las referencias de documentos y los SKU tienen de 1 a 120 caracteres. Las referencias de documentos de PO, factura y recibo deben ser distintas. Los SKU duplicados dentro de un documento o dentro de prior_invoiced, y las referencias de recibo duplicadas, producen invalid; las filas ambiguas se excluyen de la comparación. Los SKU repetidos en diferentes documentos de recibo son esperados y se acumulan.

Las cantidades son unidades enteras de 0 a 1,000,000,000; las cantidades de línea de PO y factura deben ser positivas. Las cantidades fraccionarias se rechazan. accepted_quantity y rejected_quantity son recuentos disjuntos, no un recuento bruto y su subconjunto. Las unidades rechazadas nunca aumentan la cantidad disponible para facturar. Los recibos deben llevar fechas YYYY-MM-DD válidas; incluye solo recibos relevantes para esta verificación. Las fechas son evidencia, no un corte automático de fecha de factura.

Cada entrada monetaria es un monto entero en unidades menores de 0 a Number.MAX_SAFE_INTEGER (9,007,199,254,740,991). Para USD, 100 significa $1.00; para una moneda de cero decimales usa sus propias unidades menores. Proporciona el código de moneda de tres letras en mayúsculas tanto en la PO como en la factura. No se realiza conversión de moneda ni búsqueda en catálogo de códigos de moneda. Los precios unitarios deben coincidir exactamente, sin tolerancia. Los productos monetarios y los totales usan aritmética de enteros; los resultados inseguros producen invalid con unsafe_money_arithmetic, nunca un monto redondeado.

invoice.total_minor es el total de las líneas de bienes suministradas. No hay ajustes implícitos de impuestos, flete, descuentos, redondeo o créditos. Representa los cargos acordados como SKUs de PO/factura con precio explícito y evidencia de recibo adecuada, o prepara un total de bienes excluyendo ajustes antes de llamar. No proporciones un total de factura todo incluido mientras omites sus ajustes.

prior_invoiced es requerido, incluso cuando está vacío. Proporciona las cantidades acumuladas completas facturadas previamente para cada SKU contra esta PO, excluyendo esta factura actual. [] afirma explícitamente que no hay ninguna. Las cantidades actuales más las anteriores deben caber tanto en los recibos aceptados como en la PO. Guardar informes no actualiza este historial ni detecta referencias de factura repetidas entre verificaciones; un historial incorrecto u omitido puede permitir que la facturación repetida pase desapercibida. Los informes son instantáneas de evidencia, no un libro contable.

Los límites se aplican por igual a gratuito y Pro: 1–500 líneas de PO, 1–500 líneas de factura, hasta 500 SKU anteriores y hasta 100 recibos de 1–500 líneas cada uno. Un arreglo de recibos vacío es válido y produce excepciones de recibo faltante para SKUs de PO facturados. Referencias vacías o mal formadas, SKUs en blanco/faltantes, decimales, números de entrada inseguros y fechas inválidas se rechazan como errores de entrada. Los SKU desconocidos son excepciones explícitas de unordered_sku.

Los totales iguales pueden ocultar errores de SKU

Llama a three_way_match con:

{
  "po": {
    "reference": "PO-1", "supplier": "Supply Co", "currency": "USD",
    "lines": [
      {"sku": "A", "quantity": 10, "unit_price_minor": 100},
      {"sku": "B", "quantity": 10, "unit_price_minor": 100}
    ]
  },
  "receipts": [{
    "reference": "GR-1", "po_reference": "PO-1", "supplier": "Supply Co", "date": "2026-10-16",
    "lines": [
      {"sku": "A", "accepted_quantity": 5, "rejected_quantity": 0},
      {"sku": "B", "accepted_quantity": 15, "rejected_quantity": 0}
    ]
  }],
  "invoice": {
    "reference": "INV-1", "po_reference": "PO-1", "supplier": "Supply Co", "currency": "USD",
    "lines": [
      {"sku": "A", "quantity": 10, "unit_price_minor": 100},
      {"sku": "B", "quantity": 10, "unit_price_minor": 100}
    ],
    "total_minor": 2000
  },
  "prior_invoiced": [],
  "save": false
}

El informe tiene status: "exceptions", a pesar de los totales de PO/factura iguales de 2,000 unidades menores y cantidades agregadas iguales. El SKU A tiene invoiced_above_accepted (10 facturados, 5 aceptados); el SKU B tiene accepted_above_order (15 aceptados, 10 ordenados). Cambiar los precios unitarios de la factura a 90 para A y 110 para B también preserva el total general pero produce dos problemas de unit_price_mismatch.

Las entregas parciales pueden coincidir

Usando la misma PO, proporciona un recibo que contenga solo A con accepted_quantity: 4, rejected_quantity: 2. Factura solo A con quantity: 4, unit_price_minor: 100, total_minor: 400, y mantén prior_invoiced: []. Esto devuelve matched. A tiene seis unidades aún no entregadas; B no necesita aparecer en esta factura parcial. Un segundo recibo coincidente agrega su cantidad aceptada; las cantidades rechazadas permanecen como evidencia separada. Después de facturar previamente dos unidades de A, proporciona prior_invoiced: [{"sku":"A","quantity":2}] y factura como máximo dos más contra esas cuatro unidades aceptadas.

Leyendo el informe

matched significa que la evidencia proporcionada pasa estas verificaciones exactas; no autoriza el pago. exceptions identifica discrepancias de documentos, SKU desconocidos, recibos faltantes, cantidades aceptadas/facturadas excesivas, diferencias de precio o un total de factura declarado inconsistente. invalid identifica ambigüedad o dinero calculado inseguro; resuélvelo antes de interpretar la comparación. Las referencias de PO/proveedor de recibos no coincidentes se marcan y esos recibos no respaldan la facturación.

Cada problema tiene code, severity, source, sku opcional y un mensaje concreto. Cada fila de SKU ordenada incluye números de línea de origen de PO/factura basados en uno; cantidades ordenadas, aceptadas, rechazadas, anteriores y de factura actual; ambos precios unitarios; cantidad facturada acumulada; cantidad disponible antes de esta factura; cantidad restante no entregada; referencias/números de línea de recibo y banderas de inclusión; y códigos de problema. El informe conserva los documentos completos proporcionados, por lo que una fila duplicada nunca desaparece de la evidencia de auditoría. Las escaseces parciales se muestran como cantidades restantes y no fallan por sí mismas una factura parcial compatible.

Los informes pequeños se devuelven en línea. Un informe cuya respuesta MCP escapada exceda 8 MiB devuelve una descripción general explícita de paginated: true con estado, totales, recuentos, encabezados de documentos de origen y report_id. Toda la evidencia permanece gratuita hasta report_page. Selecciona section de issues, lines, po_lines, invoice_lines, prior_invoiced, receipts, receipt_lines o line_receipts; usa offset (predeterminado 0) y limit (predeterminado 100, máximo 100), siguiendo next_offset hasta null. Las páginas de lines contienen evidencia escalar y receipt_count; obtén esas entradas de recibo con line_receipts y el sku exacto. receipt_lines requiere el receipt_index basado en cero del arreglo de recibos original. Las páginas de receipts contienen encabezados de documentos y recuentos de líneas. Juntas, estas secciones preservan cada fila de origen y cada problema calculado.

Los informes guardados usan su UUID persistente para las páginas, y report_get devuelve la misma descripción general limitada para informes guardados grandes. Los informes grandes no guardados, incluidos los límites de guardado y fallos de almacenamiento, usan IDs de preview:<UUID>: el proceso mantiene sus últimas dos vistas previas grandes durante 30 minutos. Reiniciar, expirar o una tercera vista previa puede desalojarlas; reenvía el diagnóstico original para recrear la vista previa gratuita. Los IDs de vista previa pertenecen al proceso del servidor actualmente en ejecución. El SDK subyacente también limita los mensajes stdio entrantes a 10 MiB; las solicitudes codificadas deben caber en ese límite de transporte incluso cuando los recuentos de filas individuales caben en el esquema.

El CSV incluye una fila por SKU, precios exactos en unidades menores, cantidades y códigos de problema de línea; los problemas de documento permanecen en el JSON adjunto y en el informe completo. El CSV se devuelve como texto, no se escribe en una ruta arbitraria proporcionada por el llamador. Los caracteres iniciales similares a fórmulas se escapan para uso en hojas de cálculo.

Las exportaciones CSV que caben en el mismo presupuesto de respuesta de 8 MiB permanecen en línea. Las exportaciones más grandes devuelven un primer fragmento de hasta 1,000 filas con paginated, offset, returned, total_rows y next_offset. Pasa ese next_offset como offset en otra llamada a report_export_csv; limit opcional es 1–1,000. Cada fragmento repite el encabezado; conserva un encabezado al combinar fragmentos.

Gratuito y Pro

Capacidad	Gratuito	Pro
Verificaciones de diagnóstico completas y evidencia de origen	Todas las verificaciones, hasta 500 líneas de PO/factura	Igual
Verificaciones de recibos y facturas anteriores	Mismos límites documentados	Igual
Informes guardados	3 a la vez	Sin límite de recuento de informes
Listar/obtener/eliminar y exportación CSV	Incluido	Incluido
Cuando `save: true` alcanza el límite gratuito, el informe completo se sigue devolviendo con `saved: false`, `save_error: "free_saved_report_cap"` y el enlace de pago. Un error de almacenamiento también conserva el informe de diagnóstico. Elimina un informe guardado antiguo para reutilizar un espacio gratuito. Un archivo de informe guardado está limitado a 64 MiB al guardarse y leerse; esto es una protección de integridad del almacenamiento, no un límite de Pro.

Obtén Pro: $19 por una sola vez. Todos los servidores: paquete de $39. Activa la clave con license_activate o establece MCP_LICENSE_KEY. Las claves se verifican sin conexión.

Todos los datos permanecen locales. La conciliación no realiza solicitudes de red. Los informes JSON guardados residen en ${XDG_DATA_HOME:-~/.local/share}/mcp-servers/three-way-match/; XDG_DATA_HOME debe ser absoluto y el árbol de directorios de almacenamiento no debe contener enlaces simbólicos. Los archivos usan renombrado atómico y las mutaciones comparten un bloqueo entre procesos. Los informes incluyen datos de documentos comerciales: gestiona el acceso local y las copias de seguridad en consecuencia. La activación de licencia escribe la configuración de licencia local compartida.

Desarrollo

npm run build --workspace @theluckystrike/mcp-three-way-match
npm test --workspace @theluckystrike/mcp-three-way-match

Las pruebas ejercitan errores de cantidad/precio compensados, recibos rechazados y múltiples, parciales, facturación previa explícita, SKUs/referencias desconocidas y duplicadas, discrepancias de moneda/PO/proveedor, fechas, límites de enteros, política de guardado gratuito/Pro, almacenamiento atómico y un recorrido de ida y vuelta de inicialización/herramientas/llamadas de MCP stdio. Las compilaciones de Docker se realizan desde la raíz del repositorio con docker build -f servers/three-way-match/Dockerfile ..