Funnel Calibrator

Un servidor MCP que recalibra las decisiones publicitarias según lo que un embudo de ventas realmente hace, no lo que se supone que hace.

⚠️ Estado: trabajo en curso. El andamiaje y el diseño están avanzados; la implementación del servidor MCP llega el 24 de agosto de 2026. Defensa: 25 de agosto de 2026.

KSE AI Agentic Lab — Trabajo individual de laboratorio (Semana 7, Integración MCP).

El problema que resuelve

El proyecto se desarrolla sobre un negocio real de comercio electrónico ucraniano con pago contra reembolso (COD, por sus siglas en inglés) que vende ropa de mujer mediante anuncios de Meta. Su embudo tiene cinco etapas:

Meta ads ──► Lead ──► Call-centre approval ──► Shipment ──► Buyout at post office ──► Profit

Como el pago se produce en el momento de la entrega, el resultado de una campaña publicitaria no se conoce cuando se gasta el dinero. Se conoce dos a cuatro semanas después, cuando el cliente recoge el paquete o no lo recoge. El negocio cubre esta brecha con dos constantes globales de cartera — una tasa de aprobación del 65% y una tasa de compra del 52,5% — y las utiliza para calcular, para cada producto, el coste máximo por lead en el que ese producto sigue punto de equilibrio (Stop CPL) y el objetivo hacia el que debería optimizarse (Goal CPL).

Esas constantes son promedios de cartera aplicados a productos individuales, y los productos individuales se alejan claramente de ellas. Ejemplos medidos en el negocio: los productos de un fabricante se compran al 37% frente al 52,5% asumido; la tasa de aprobación de un producto se midió en el 53% frente al 65% asumido; la tasa de compra se correlaciona fuertemente con la franja de precios, desde aproximadamente el 93% en 690–790 ₴ hasta aproximadamente el 55% por encima de 1290 ₴.

Cuando las tasas reales de un producto son peores de lo manejadas, su CPL real de equilibrio es inferior al número por el que el negocio se está guiando, de modo que el objetivo publicitario puede situarse por encima del punto de equilibrio real. El tráfico parece saludable en el análisis de los anuncios mientras cada lead pierde dinero, y la pérdida solo se hace visible en el cierre financiero mensual, semanas después.

Esto es un sistema de control en lazo abierto: la medición no regresa nunca a la decisión. Funnel Calibrator cierra el lazo.

Related MCP server: KrystalView MCP Server

Qué hace

El servidor mide las tasas de embudo propias de cada producto a partir de los datos históricos de pedidos, recalcula los límites de CPL reales de ese producto y audita las decisiones publicitarias propuestas contra las cifras —corregidas, devolviendo evidencia estructurada en lugar de un veredicto que deba aceptarse sin más.

Dos problemas hacen que esto sea más difícil de lo habitual, and realize both are handled explicitly in the tool contracts:

• Censura. Los pedidos recientes aún no se han resuelto: un paquete en tránsito no es ni una compra ni una devolución. Contarlos de forma directa reduce la tasa medida. El servidor excluye las cohortes menores que una ventana de madurez configurable e informa de cuántos pedidos ha movido a un lado.

• Muestras pequeñas. Entre productos, tanto, tallas y colores, los conteos se vuelven kaduc por el número de integrantes. Cada medición incorpora su tamaño de muestra y un indicador de fiabilidad, y el servidor se niega a sacar conclusiones por debajo de un umbral configurable en lugar de comunicar ruido confiable.

Arquitectura

┌─────────────────────────────────────────────────────────────┐
│  Agent  (Claude Agent SDK)                                  │
│                                                             │
│    ├── MCP ──► Obsidian Local REST API      [existing]      │
│    │           decision journal: reads the day's objective  │
│    │           and prior conclusions, writes calibrated      │
│    │           verdicts back as a durable record            │
│    │                                                         │
│    └── MCP ──► Funnel Calibrator            [custom]        │
│                measure → recalibrate → recommend → audit    │
│                        │                                     │
│                        ▼                                     │
│                 local snapshot dataset                       │
│                 (anonymised order cohorts + unit economics)  │
└─────────────────────────────────────────────────────────────┘

El servidor personalizado se ejecuta como proceso separado y se comunica a través de stdio, y es startable de forma independiente del agente.

Flujo del agente

1. Leer el objetivo publicitario del día y las conclusiones de ayer de la bóveda de Obsidian.

2. Medir las tasas de embudo observadas de cada producto desde la instantánea (sensibilidad sobre censura y muestra).

3. Recalcular los límites Stop/Goal CPL reales y la desviación frente a la base asumida.

4. Diagnosticar por qué un producto tiene bajo rendimiento — la cura según causa distinta — y recompartir una acción siguiente.

5. Auditar las decisiones propuestas del día (no queda correctiva).

6. Escribir el veredicto calibrado, con su cadena de evidencia, en la bóveda.

Cada paso he uses output of the previous step: el contenido de la bóveda determina what to measure, la medición determina los límites corrigidos, y los límites déterminan si una decisión propuesta se sostiene o se destuye.

Herramientas personalizadas

Esquemas de entrada/salida completos, condiciones de error, efectos secundarios y ejemplos orientativos: docs/tool-contracts.md.

Por qué estas cuatro, por qué están en el límite MCP y qué renuncia el diseño a cambio: docs/design-rationale.md.

Fuente de datos

Un conjunto de datos sinks anonimizado de cohortes históricas de pedidos, exportado desde el CRM del negocio mediante scripts/export_snapshot.py. No se necesita autenticación ni acceso por red en el tiempo de ejecución, lo que hace que la demostración es determinista y reproducible.

Toda la información personalmente identificable (nombres de clientes, números de teléfono, lugares y direcciones, números de albarán) se elimina en la exportación. La instantánea conserva solo lo que la calibración necesita: código de producto, estado del pedido, marcas de tiempo, importes y economía unitaria. Consulte data/README.md para las políticas and protocol de anonimización.

Inicio rápido

Las condiciones previas: Python ≥ 3.11 y uv. Obsidian no plugin Local REST API only is required for agent flow, not to execute the server.

git clone https://github.com/denkor1015-debug/funnel-calibrator.git
cd funnel-calibrator
uv sync

Ejecuta el servidor MCP en modo standalone (habla MCP sobre stdio y esperará a un cliente):

uv run funnel-calibrator

Inspecta las herramientas expuestas de forma interactiva con MCP Inspector:

npx @modelcontextprotocol/inspector uv run funnel-calibrator

La configuración se lee a través de variables bibliotecarias; copie la plantilla y edítela:

cp .env.example .env

Configuración del agente para ambas connexiones MCP: agent/mcp_config.example.json.

Estructura del repositorio

src/funnel_calibrator/   MCP server: tool definitions, calibration math, policy engine
scripts/                 snapshot exporter (CRM ──► anonymised local dataset)
data/                    snapshot dataset + anonymisation policy
docs/                    tool contracts, design rationale, defence checklist
agent/                   MCP client configuration for both connections
tests/                   unit tests for calibration and policy logic

Plan de desarrollo

• Scaffolding, arquitectura y justificación de diseño

• Malecón: exportador de instantáneas con eliminación de PII

• measure_sku_funnel: censura y límite de muestra

• recalibrate_cpl_bounds: recálculo de la economía unitaria

• recommend_next_action: diagnóstico del modo de fallo

• audit_ad_verdict: auditoría de decisiones

• Integración con Obsidian MCP y flujo de agente completo (de extremo a extremo)

• Manejo de rutas de fallo y demonstrates

• Documentación de tool-contracts y replay de defensa

Mapa de requisitos de la asignación

Licencia

MIT — ver LICENSE.