MergeOn MCP Server

MCP (Model Context Protocol) server que expone tu cuenta de MergeOn Seller como herramientas y skills para clientes Claude (Claude Desktop, Claude Code, Cursor, Continue, Zed, etc.).

Una vez instalado, puedes pedirle a Claude cosas como:

"Lista mis 10 últimos pedidos sin enviar" "Crea un flow que mande un follow-up 24 h después de un lead nuevo de Instagram" "Actualiza el prompt del agente de ventas para que sugiera el producto X cuando alguien pregunte por talla" "Importa estos 200 contactos de CSV al CRM"

Y Claude usa el MCP para hacerlo directamente contra tu backend de MergeOn.

Tabla de contenidos

1. ¿Qué expone el MCP?
2. Setup en Claude Desktop / Claude Code
3. Tools disponibles (106)
4. Skills incluidos
5. Variables de entorno
6. Desarrollo local
7. Mantenimiento — añadir o modificar tools
8. Publicación a npm

¿Qué expone el MCP?

El MCP ofrece dos tipos de capacidades a Claude:

A. Tools (herramientas ejecutables)

Cada tool es una función que Claude puede invocar. Internamente, el MCP autentica con tu API key (mk_xxx), llama al endpoint correcto del backend de MergeOn (https://api.mergeon.dev por defecto) inyectando tu ecommerce_id, y devuelve el JSON de respuesta a Claude. Claude decide cuándo usar cada tool según el contexto de la conversación.

Superadmin (key de ecommerce 1): todas las tools aceptan un parámetro opcional ecommerce_id para operar sobre cualquier tenant (ej. agent_prompts_update({ wpp_prompt_text: "...", ecommerce_id: "57" })). Con una key normal el override se rechaza: el backend (enforce_ecommerce_access) solo lo permite para la key de ecommerce 1 y devuelve 403 al resto.

Las 115 tools cubren los principales dominios de MergeOn: CRM, pedidos, productos, conversaciones, flujos de automatización (con catálogo de triggers/conditions/actions descubrible y filtros por reel específico via media_ids), calendario, marketing masivo, analytics legacy, analítica de ventas (revenue, top productos, comparativas y filtros por canal), eventos a Meta CAPI (auditoría + reenvío), nurturing/hidratación de leads, formularios dinámicos con tracking codes + UTMs, videos sociales con auto-tracking y funnel de conversión, webhooks entrantes, workers, admin, configuración del agente IA (prompts + tools), business context (conocimiento dinámico para el agente), plantillas de WhatsApp avanzadas y configuración general del ecommerce.

B. Skills (guías de experto instalables en CLAUDE.md)

Los skills son documentos .md con conocimiento experto que se inyectan en tu CLAUDE.md local vía npx mergeon-mcp skills add <nombre>. A diferencia de las tools, un skill no es ejecutable: es contexto que mejora la calidad de las respuestas de Claude para tareas específicas (escribir prompts del agente, diseñar flows, etc.).

Hoy hay nueve skills:

• prompt-creation — experto en redactar el prompt del agente de ventas para WhatsApp/Instagram.
• flows-creation — experto en diseñar flows de automatización (post-venta, pautas, notificaciones, chatbots, flows por reel específico).
• nurturing-creation — experto en hidratación de leads (secuencias multi-touch por stage del CRM).
• templates-creation — experto en plantillas oficiales (HSM) avanzadas con headers media, botones, manual_placeholders.
• webhooks-usage — experto en integrar sistemas externos (forms, pasarelas, CRMs) con webhooks entrantes.
• sales-analysis — analista de ventas: cómo combinar sales_* para responder bien a "cómo voy".
• meta-events-debug — auditoría de Meta CAPI: por qué no aparece tal venta como Purchase en Events Manager.
• social-tracking — tracking por reel/post: auto-discovery, funnel comments→DM→leads→órdenes, atribución de revenue por video.
• forms-creation — forms dinámicos en mergeon.dev/form/{code}: schema, tracking codes con UTMs, atribución a videos, auto-upsert CRM.

Setup

1. Genera una API key

En tu dashboard de MergeOn Seller: Admin → API Keys → "Generar API Key". Copia la clave (mk_xxxxxxxx). Solo se muestra una vez.

2. Configura tu cliente Claude

Claude Desktop

Edita claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mergeon": {
      "command": "npx",
      "args": ["-y", "mergeon-mcp"],
      "env": {
        "MERGEON_API_KEY": "mk_tu_api_key_aqui"
      }
    }
  }
}

Reinicia Claude Desktop. Las herramientas de MergeOn aparecen en el menú de tools (icono de martillo).

Claude Code

Añade el server con el comando:

claude mcp add mergeon -- npx -y mergeon-mcp -e MERGEON_API_KEY=mk_tu_api_key

Otros clientes (Cursor, Continue, Zed)

Cualquier cliente compatible con MCP-stdio funciona. Apunta al binario npx -y mergeon-mcp y pasa MERGEON_API_KEY como variable de entorno.

3. (Opcional) Instala los skills

cd /ruta/a/tu/proyecto
npx mergeon-mcp skills add prompt-creation
npx mergeon-mcp skills add flows-creation

Esto añade el contenido del skill a tu CLAUDE.md local, dentro de marcadores <!-- mergeon-skill:nombre --> para futura desinstalación o re-aplicación.

Listar los skills disponibles:

npx mergeon-mcp skills list

Tools disponibles

106 tools organizadas en 20 dominios. Cada nombre corresponde a la cadena exacta que verás en Claude Desktop.

💡 Los dominios marcados con (catálogo descubrible) exponen un tool <dominio>_get_catalog que devuelve los enums, shapes y reglas válidas. Llámalo SIEMPRE antes de crear/modificar para no inventar campos.

CRM (6 tools)

| Tool | Qué hace | |---|---| | crm_list | Lista contactos con filtros: status (lead/warm/hot/cold/sold), city, country, name, source (whatsapp/instagram/web), cellphone, ig_user, attended_by, paginación. | | crm_get | Detalle completo de un contacto por id (intereses, calificación, resumen de conversación). | | crm_interests_aggregate | Nuevo en 1.9.0: devuelve todos los valores únicos de interested_in agrupados por categoría (keywords, products, brand_affinity, etc.) en el ecommerce. Ideal antes de añadir tags para evitar duplicados. | | crm_create | Crea contacto. Mínimo: name o cellphone. Opcionales: email, ciudad, país, source, status, ig_user, notes. | | crm_update | Actualiza campos de un contacto (PATCH parcial). Útil para cambiar status o reasignar attended_by. | | crm_delete | Elimina contacto permanentemente. | | crm_bulk_import | Importa varios contactos desde CSV (string con cabecera) en una sola llamada. Columnas que se guardan: name, cellphone, ig_id, ig_user, source, city, country. Deduplica por teléfono (o ig_id): los que ya existen se omiten, no se duplican. trigger_flows (default false) dispara el flow crm_created (ej. bienvenida) por cada contacto nuevo. Devuelve {created, skipped, errors, created_ids, error_details}. |

Pedidos (7 tools)

| Tool | Qué hace | |---|---| | orders_list | Pedidos recientes ordenados por fecha. Filtro last_order (ISO datetime — solo pedidos posteriores). | | orders_get | Detalle completo del pedido por order_id (productos, cliente, pago, tracking). | | orders_create | Crea pedido. Requiere user_name, user_cellphone, amount y products: [{product_id, quantity}]. Opcionales: dirección, email, status, payment_status, notes. | | orders_update | PATCH parcial de status, payment_status, dirección, monto, notas. | | orders_create_shipment | Crea envío y marca pedido como ready_to_ship. Acepta tracking_number, tracking_url, courier, label_url. | | orders_export_config_get | Devuelve el mapeo de columnas de exportación CSV (orden, encabezados, separador, fila de encabezados) + available_fields (catálogo de campos del pedido mapeables). Mismo config que usa el botón "Exportar CSV" del dashboard. | | orders_export_config_update | Define cómo se exportan los pedidos a CSV: columns: [{field, header}] (orden = orden de columnas), delimiter (',' ';' o '\t') e include_header. field debe ser una key de available_fields. Persiste por tenant. |

Productos (5 tools)

| Tool | Qué hace | |---|---| | products_list | Catálogo paginado, búsqueda por search (nombre/descripción), sort, limit, offset. | | products_get | Detalle por identificator (ID o slug), incluye variantes, imágenes, inventario. | | products_create | Crea producto. Requiere name y price. Opcionales: description, available (pásalo true para publicarlo), brand, category (string o lista — se envía como lista), discount_price/has_discount, slug, variants. Las imágenes y el stock viven en variants (no hay columna photo_url a nivel producto): cada variante lleva su photo_url y stock. No funciona en fuentes read-only (Shopify). | | products_update | PUT parcial de campos del producto: name, price, description, available, brand, category, discount_price/has_discount, stock/manage_stock, slug, variants. Pasar variants reemplaza el array completo; es la vía para fijar fotos por variante. | | products_bulk_update | Aplica los mismos cambios a varios productos a la vez. Útil para subir/bajar precios en masa o (des)activar lotes. |

Conversaciones (4 tools)

| Tool | Qué hace | |---|---| | conversations_list | Lista sesiones (hilos WhatsApp/Instagram) con paginación. | | conversations_get | Mensajes completos de una sesión por session_id. | | conversations_search | Busca texto en mensajes de todas las conversaciones. Filtros: from_user, from_agent. | | conversations_range | Trae todos los mensajes creados entre since y until (ISO 8601), orden cronológico. Para sincronización incremental por ventana de tiempo (ej. cron cada 30 min). |

Flujos / Flows (6 tools)

| Tool | Qué hace | |---|---| | flows_list | Lista todos los flows con id, name, trigger_type, conditions, actions[], is_active, continue_agent, scheduled_at. | | flows_create | Crea flow. Campos: name, trigger_type (enum), actions[] (array de {action_type: payload}), conditions, is_active, continue_agent, is_exclusive, scheduled_at. La descripción de la tool enumera triggers y condiciones válidas por trigger. Nuevo en 1.5.1: ig_comment acepta conditions.media_ids[] y conditions.media_product_type para flows por reel/post específico. Nuevo en 1.8.0: is_exclusive en trigger sold → solo el flow exclusivo más específico corre; los no-exclusivos siempre corren. | | flows_update | PATCH parcial. Re-valida constraints de story_reply/decision_tree/scheduled_send. | | flows_delete | Elimina flow por flow_id y limpia cache de flows. | | flows_execute | Ejecuta flow manualmente con crm/message/order, opcional template_placeholders (overrides de campos manuales para send_template) y opcional template_file_url (override del header image/video/documento del template, ej. guía de envío específica del pedido). Opcional session_id + source para fijar la conversación destino exacta (evita que el canal se re-derive del contacto). Permite ejecutar flows inactivos manualmente. | | flows_get_catalog | Catálogo descubrible: devuelve todos los trigger_types con sus condiciones válidas, todos los action_types con sus payloads, los order_statuses válidos y los {{placeholders}} disponibles (order/crm/message/time + aritmética). Llamar antes de diseñar un flow para no inventar triggers/actions. |

Para escribir flows con recetas y buenas prácticas, instala el skill flows-creation (npx mergeon-mcp skills add flows-creation). El skill ya cubre los 10 triggers y las 14 actions del backend.

Calendario (8 tools)

| Tool | Qué hace | |---|---| | calendar_list | Lista eventos con filtros opcionales: start_date, end_date, event_type (appointment/task/reminder/followup), status, priority. | | calendar_today | Eventos del día. | | calendar_upcoming | Próximos eventos N días (1-90, default 7). | | calendar_get | Detalle de evento por event_id. | | calendar_create | Crea evento. Requiere title y date. Opcionales: time, event_type, priority, contact_id, contact_name, description. | | calendar_update | PATCH parcial. | | calendar_complete | Marca evento como completado. | | calendar_delete | Elimina evento. |

Marketing (3 tools)

| Tool | Qué hace | |---|---| | marketing_rate_limit | Devuelve el tier actual de mensajería WhatsApp y mensajes enviados hoy. Llamar antes de envíos masivos. | | marketing_campaigns | Lista campañas pasadas con stats de delivery. | | marketing_send_bulk | Envía mensaje masivo por WhatsApp/Instagram. Acepta template_name (HSM aprobada, llega a cualquiera) o message_text (texto libre, solo WhatsApp, solo a contactos dentro de la ventana de 24h). Combina con filters (status/city/source/interested_in/attended_by) o users (lista explícita de strings: teléfonos o IG user IDs). |

Analytics legacy (1 tool)

| Tool | Qué hace | |---|---| | analytics_orders | Pedidos en rango first_month–last_month (formato YYYY-MM). Útil para revenue y tendencias. Deprecado en favor de sales_* — mantiene compatibilidad. |

Analítica de ventas (5 tools + catálogo descubrible)

Combinaciones agregadas para responder rápido "cómo van las ventas". El MCP calcula los breakdowns (status / provider / canal / ciudad / día) en memoria a partir de /analytics/orders/. Para guías de uso, instala el skill sales-analysis.

| Tool | Qué hace | |---|---| | sales_get_catalog | Catálogo descubrible: statuses válidos, métricas calculables (revenue, avg_ticket, from_ads_share_count, breakdowns…), workflow recomendado. Llamar antes de cualquier análisis. | | sales_summary | Reporte agregado del rango (last_days o first_month/last_month): revenue, count, avg_ticket, breakdowns por status/provider/ciudad/canal y serie diaria. Acepta filtros only_paid, statuses, only_from_ads. | | sales_top_products | Top productos por unidades / revenue / órdenes distintas. | | sales_compare_periods | Compara dos periodos (current vs previous). Si no se pasa el previo, se infiere "mismo tamaño hacia atrás". Devuelve delta_pct. | | sales_orders_in_range | Órdenes crudas en rango (sin agregar). Útil para exportar o revisar casos puntuales. | | sales_recent_orders | Últimas órdenes (/orders/recent) sin agregar. Ideal para "¿llegó la orden de Juan?". |

Eventos a Meta CAPI (9 tools + catálogo descubrible)

Auditoría y backfill de eventos de Conversions API for Business Messaging. Para diagnóstico end-to-end, instala el skill meta-events-debug.

| Tool | Qué hace | |---|---| | meta_events_get_catalog | Catálogo descubrible: tipos de evento (sold/lead_submitted/whatsapp_referral), source CAPI vs DIRECT, señales de verificación (meta_sent, event_created, fbtrace_id), workflow de debugging. | | meta_events_health_check | Composite: verifica config Meta (waba, ads_token, dataset, pixel), cuenta eventos vs órdenes recientes, devuelve next_step. Punto de entrada del diagnóstico. | | meta_events_advertisement_list | Lista eventos advertisement_events con filtros: advertisement_id, event_type, date_from/date_to, paginación. Cada item incluye source, details.fbtrace_id y order_id. | | meta_events_advertisement_get | Detalle completo de un evento por event_id. | | meta_events_advertisements_list | Lista anuncios (/advertisement/) registrados. Mapea advertisement_id → metadata del ad. | | meta_events_order_capi_status | Devuelve TODOS los eventos CAPI de una orden: has_sold_event, sold_event y timeline. Úsalo para "¿Meta recibió la venta X?". | | meta_events_order_capi_preview | Dry-run antes de enviar: busca el whatsapp_referral vinculado al teléfono de la orden (normaliza +/sin-+) y devuelve would_be_source (CAPI vs DIRECT), ad_id, ctwa_clid y referral_event_id. Úsalo cuando una orden de anuncio cae como DIRECT. | | meta_events_orders_pending_capi | Lista órdenes pagadas SIN evento sold registrado. Útil para backfills. | | meta_events_send_order_capi | Reenvía evento Purchase para una orden. Idempotente: si ya existe devuelve already_exists: true. | | meta_events_send_bulk_capi | Reenvía Purchase para muchas órdenes (recibe la lista que devuelve meta_events_orders_pending_capi). |

Nurturing / Hidratación de leads (6 tools + catálogo descubrible)

Secuencias multi-touch por etapa del CRM (cold/warm/hot/sold/...). Internamente endpoint /hydration/. Para diseñar secuencias, instala el skill nurturing-creation. v1.13.0: los flows aceptan interest_keywords para segmentar por interés; la IA de WhatsApp etiqueta leads con la tool de bot add_lead_keyword (aparece en agent_tools_get).

| Tool | Qué hace | |---|---| | nurturing_get_catalog | Catálogo descubrible: stages típicos, shapes de las 3 acciones (send_message, send_template, run_agent), best practices de hours_trigger y guardrails (max_activations, ventana de 24h de WhatsApp). | | nurturing_flows_list | Lista todos los flows de hidratación. | | nurturing_flow_create | Crea flow: name, lead_stage, hours_trigger, action, is_active, max_activations, max_activations_window_days, interest_keywords (v1.13.0: filtra el flow a leads con esas keywords en interested_in). | | nurturing_flow_update | PATCH parcial. | | nurturing_flow_delete | Elimina permanentemente. | | nurturing_logs | Log de ejecuciones con lead_name/phone, sent_at, action_text. Útil para auditar disparos reales. | | nurturing_create_sequence | Crea de un solo golpe una secuencia completa (varios flows con misma lead_stage y distintos hours_trigger). Útil para "arma una hidratación 4h/24h/72h/7d". |

Formularios / Forms (10 tools — schema dinámico + tracking codes + UTMs)

Forms que se renderizan en mergeon.dev/form/{tracking_code}. 1 form → N tracking codes (uno por reel/canal). Submissions auto-crean CRM y atribuyen al video. Skill: forms-creation.

| Tool | Qué hace | |---|---| | forms_get_catalog | Field types válidos, destination_modes, after_submit shapes, ejemplos. Llamar primero. | | forms_list | Lista forms con métricas (total_submissions, total_codes, last_submission_at). | | forms_get | Uno con full schema. | | forms_create | Nuevo form. Field types: text, textarea, email, phone, url, number, yes_no, select, multi_select, checkbox, date. Soporta condicionales (show_if). | | forms_update | PATCH parcial. | | forms_delete | Cascade — borra codes + submissions. | | forms_tracking_codes_list | Codes (los slugs en la URL). Filtra por form_id. | | forms_tracking_codes_create | Bind form → reel/canal con UTMs propias. Code autogenerado si se omite. | | forms_tracking_codes_update | Edita UTMs/label/is_active. | | forms_tracking_codes_delete | Borra code (submissions sobreviven con el code como texto). | | forms_submissions_list | Filtra por form_id, tracking_code o tracked_media_id. |

Pipeline: forms_create → forms_tracking_codes_create({ form_id, tracked_media_id }) → comparte mergeon.dev/form/{code}. El submit auto-upsertea CRM contact (si hay phone), registra magnet_submitted/lead_captured en el video, dispara webhook saliente (firmado HMAC), y aplica after_submit (mensaje o redirect a Calendly/lo que sea).

Videos / Tracked Media (10 tools — auto-tracking de reels/posts IG)

Videos auto-descubiertos al recibir comentarios. Cada uno acumula métricas (comments, dms_sent, leads, orders, revenue) y eventos de funnel. Para guía completa instala el skill social-tracking.

| Tool | Qué hace | |---|---| | tracked_media_list | Lista videos con métricas agregadas. Sort por last_comment_at (default), total_revenue, total_orders, total_leads, etc. | | tracked_media_top | Top-N por una métrica. Útil para "qué reel vendió más este mes". | | tracked_media_get | Uno solo con métricas. Toma el tracked_media_id interno (no el media_id de Meta). | | tracked_media_funnel | Funnel completo: comments → dms → leads → opens → submissions → orders + tasas de conversión + revenue. | | tracked_media_events | Timeline raw de eventos. Filtrable por event_type. | | tracked_media_label | Pone etiqueta humana ("Reel oferta enero") para que el análisis posterior sea legible. | | tracked_media_update | PATCH parcial: label, permalink, caption, thumbnail_url, media_product_type. | | tracked_media_hydrate | Fuerza re-fetch a Meta Graph para llenar permalink/caption/thumbnail si la hidratación inicial falló. | | tracked_media_delete | Destructivo — cascade a todos los eventos. Solo si el usuario lo pide. | | tracked_media_get_catalog | Métricas válidas, event_types canónicos y hint para encadenar con flows_create. |

Pipeline: el webhook entrante de IG crea automáticamente la fila al primer comentario. Para crear un flow específico por reel, usa tracked_media_list → toma el media_id (string numérico de Meta) → pásalo a flows_create({ conditions: { media_ids: [...], media_product_type: "REELS" } }). Flows con media_ids ganan prioridad sobre los ig_comment generales.

Webhooks entrantes (8 tools + catálogo descubrible)

Endpoints HTTP que MergeOn expone para que sistemas externos creen contactos, ventas, citas, tickets, reseñas o actualicen leads. Para integrar y debuggear, instala el skill webhooks-usage.

| Tool | Qué hace | |---|---| | webhooks_get_catalog | Catálogo descubrible: 7 event_type válidos con available_fields, reglas de field_mapping y workflow. | | webhooks_list_event_types | Versión raw del catálogo (sin contexto extra). | | webhooks_list | Lista endpoints configurados (con api_key_preview, no la key completa). | | webhooks_get | Detalle de un webhook. | | webhooks_create | Crea endpoint. Devuelve api_key completa solo esta vez. | | webhooks_update | PATCH parcial. event_type no es modificable (delete + recreate). | | webhooks_rotate_key | Rota la api_key (la anterior deja de funcionar inmediatamente). | | webhooks_delete | Elimina endpoint y su api_key. | | webhooks_logs | Logs de deliveries: raw_payload, mapped_payload, status, error_message, created_record_id. Punto de entrada del debugging. |

Workers (3 tools)

| Tool | Qué hace | |---|---| | workers_list | Lista miembros del equipo con rol, contacto y settings de notificación. Admin/adev. | | workers_create | Crea worker (username, password, role: admin/manager/waiter, opcional full_name, email, phone, notification_enabled). | | workers_delete | Elimina worker por username. No permite borrarte a ti mismo ni a usuarios adev. |

Admin (4 tools — solo ecommerce_id=1)

| Tool | Qué hace | |---|---| | admin_ecommerces_list | Lista todos los ecommerces (tenants). | | admin_subscriptions_list | Suscripciones con filtros status y plan. | | admin_prompts_get | Prompts del agente IA de un ecommerce concreto. | | admin_prompts_update | Actualiza prompts del agente IA de un ecommerce. |

Agente IA — Configuración (8 tools)

| Tool | Qué hace | |---|---| | agent_plan_get | Plan del usuario, flag B2B, paid, can_access_agents (edición completa: rol + plan), can_manage_tools (gestión de capacidades; gating mínimo: paid), available_tool_names (cae al catálogo completo si el plan no restringe) y selected_tool_names. Útil antes de editar agente para saber qué se puede tocar. | | agent_prompts_get | Prompts del agente: wpp_prompt_text, image_prompt, ig_prompt_text, ig_comment_prompt_text, remarketing_prompt_text y prompts por etapa (cold/warm/hot/sold_prompt). | | agent_prompts_update | Crea o actualiza prompts. Manda solo los campos a cambiar. Channel-specific: wpp_prompt_text, ig_prompt_text, ig_comment_prompt_text. | | agent_prompts_generate | Genera prompts optimizados con IA a partir de un cuestionario estructurado (business_name, business_description, faq, hours, shipping/return policies, payment_methods, catalog, tone). Devuelve borrador para guardar luego con agent_prompts_update. | | agent_prompts_delete | Borra la configuración de prompts. El agente cae a defaults hasta recrearla. | | agent_tools_get | Tools del bot disponibles por plan, tools seleccionadas y si hay selección custom guardada. | | agent_tools_update | Actualiza la lista de tools habilitadas. Recibe selected_tool_names: string[] (debe ser subset de available_tool_names). | | agent_password_verify | Verifica la contraseña del worker autenticado. Útil como gate antes de operaciones sensibles del agente. |

Para escribir prompts con la calidad y estructura recomendada, instala el skill prompt-creation.

Business Context — Conocimiento dinámico del agente (4 tools)

Entradas (title, content) que el agente lee como conocimiento adicional cuando responde. Ideales para promos activas, horarios especiales, políticas estacionales, info de stock crítica, etc.

Galerías de fotos auto-sincronizadas: al crear/actualizar una entrada con photos (array de URLs), el backend genera y mantiene en sync un flow llamado Galeria: <title> cuya única acción es send_images con esas fotos. El agente recibe la marca 📷 Galería disponible en su contexto y puede invocar ese flow con execute_flow_by_name. Editar las fotos actualiza el flow; vaciarlas lo borra; renombrar el title lo renombra; desactivar el contexto lo desactiva.

| Tool | Qué hace | |---|---| | business_context_list | Lista todas las entradas (activas e inactivas). | | business_context_create | Crea entrada (title, content, is_active default true, opcional photos[]). Markdown soportado en content. Si photos no vacío → auto-crea flow Galeria: <title>. | | business_context_update | PATCH parcial. Cambios en title/photos/is_active se reflejan automáticamente en el flow asociado. | | business_context_delete | Borra entrada permanentemente y su flow asociado. Prefiere update con is_active:false si pudieras reusarla. |

Plantillas WhatsApp (5 tools + catálogo descubrible)

Plantillas oficiales (HSM) y libres internas. Para creación avanzada (headers media, botones, manual_placeholders), instala el skill templates-creation.

| Tool | Qué hace | |---|---| | templates_get_catalog | Catálogo descubrible: component_types, header_formats, button_types, language_codes, reglas de NAMED placeholders, ejemplos por tipo de bloque. | | templates_list | Lista plantillas con status, language, content y components. | | templates_get | Plantilla por identifier (ID o name con by_name: true). | | templates_create | Crea plantilla. Schema real: name (snake_case), content (BODY con {{nombre}} NAMED), language, placeholders (Dict[str, str] con samples), manual_placeholders ([{key, type, label?}]), components (HEADER/FOOTER/BUTTONS), file_url + mime_type para header media, official (true → submit a Meta). | | templates_update | PATCH parcial. ⚠️ Plantillas APPROVED no se reaprueban: crea otra con name_v2. | | templates_delete | Borra plantilla en MergeOn (no en Meta). |

Ecommerce (6 tools)

| Tool | Qué hace | |---|---| | ecommerce_get | Configuración del ecommerce, incluido el bloque config (country, currency, store_address). Default: el tuyo. | | ecommerce_update | PATCH del registro principal (name, active, paid, source, shop, billing_provider). No acepta country/currency/store_address (esos van en ecommerce_config_update). | | ecommerce_config_update | PATCH del bloque escalable: country (ISO-3166 alpha-2, default para normalizar teléfonos), currency (ISO-4217, se inyecta en órdenes nuevas) y store_address. | | ecommerce_whatsapp_catalog_sync | Vincula el catálogo del negocio a WhatsApp (Meta Commerce): conecta al WABA, lo hace visible y sube los productos (pueden venir de Shopify). Crear/subir productos requiere el permiso catalog_management de Meta (App Review). | | ecommerce_whatsapp_catalog_status | Estado del catálogo de WhatsApp: si hay catálogo creado/vinculado (catalog_id) y si está visible en el perfil. | | ecommerce_whatsapp_catalog_disconnect | Desvincula/oculta el catálogo de WhatsApp (oculta del perfil + desconecta del WABA). No borra el catálogo ni los productos. |

Reseñas / Reviews (3 tools)

Reseñas y testimonios de clientes. Endpoint público /reviews/. Skill: reviews-usage. | Tool | Qué hace | |---|---| | reviews_create | Crea una reseña/testimonio. Todos los campos opcionales: rating (1-5), comment, user_name, product_id (omítelo para un testimonio a nivel tienda, ej. tarjeta "Cliente feliz"), image_url (foto de la reseña — súbela antes con media_upload). | | reviews_list | Lista reseñas. Filtra por product_id opcional; sin filtro devuelve todas (incluye testimonios a nivel tienda). | | reviews_delete | Borra una reseña por review_id. |

Media / Uploads (1 tool)

| Tool | Qué hace | |---|---| | media_upload | Sube un archivo local (ruta absoluta en la máquina que corre el MCP) a Cloudflare R2 y devuelve una URL pública permanente en cdn.mergeon.dev. Imágenes auto-optimizadas a JPEG (máx 2048px); soporta video y documentos. Úsala para fotos de productos (variants[].photo_url), imágenes de reseñas (reviews_create image_url), flows, etc. |

Skills incluidos

Los skills viven en mcp-server/skills/ y se distribuyen con el paquete npm.

| Skill | Para qué sirve | Instalación | |---|---|---| | prompt-creation | Plantilla y heurísticas para redactar el prompt del agente de ventas (tono, estructura, manejo de objeciones, ejemplos few-shot). | npx mergeon-mcp skills add prompt-creation | | flows-creation | Patrones de diseño de flows: post-venta, recuperación de carrito, follow-up de leads, anuncios, notificaciones, chatbots. Incluye sintaxis de actions, triggers válidos y ejemplos. | npx mergeon-mcp skills add flows-creation | | nurturing-creation | Secuencias de hidratación de leads (cold/warm/hot/sold) con send_message/send_template/run_agent. Incluye guardrails de la ventana de 24h y max_activations. | npx mergeon-mcp skills add nurturing-creation | | templates-creation | Plantillas HSM avanzadas: headers media, botones URL/QUICK_REPLY/PHONE, NAMED placeholders, manual_placeholders, idiomas. | npx mergeon-mcp skills add templates-creation | | webhooks-usage | Integrar sistemas externos (forms, pasarelas, CRMs) con webhooks entrantes. Patrones, mapping de campos y debugging vía logs. | npx mergeon-mcp skills add webhooks-usage | | sales-analysis | Analista comercial: cómo combinar sales_* para "cómo voy hoy/este mes", detección de caídas, atribución a pauta. | npx mergeon-mcp skills add sales-analysis | | meta-events-debug | Diagnóstico end-to-end de eventos a Meta CAPI: por qué no aparece una venta, cómo backfillear pendientes, cómo leer fbtrace_id. | npx mergeon-mcp skills add meta-events-debug | | reviews-usage | Subir reseñas/testimonios reales (incluidas tarjetas "Cliente feliz" con foto) vía media_upload + reviews_create. A nivel tienda o por producto. | npx mergeon-mcp skills add reviews-usage |

Al instalarse, el contenido se inserta en tu CLAUDE.md local entre marcadores <!-- mergeon-skill:nombre --> y <!-- mergeon-skill:nombre -->:end.

Variables de entorno

| Variable | Requerida | Default | Descripción | |---|---|---|---| | MERGEON_API_KEY | Sí | — | API key generada en el dashboard (formato mk_xxx). | | MERGEON_API_URL | No | https://api.mergeon.dev | URL base del backend. Cámbialo si corres el backend local o tienes un staging. | | MERGEON_ECOMMERCE_ID | No | (resuelto vía /api-keys/me) | Solo para testing local: fuerza el ecommerce_id sin consultar el backend. |

Desarrollo local

cd mcp-server
npm install
npm run build      # compila TS → dist/
npm run dev        # tsc --watch

# Probar contra backend local
MERGEON_API_KEY=mk_xxx \
MERGEON_API_URL=http://localhost:8000 \
node dist/index.js

El MCP habla por stdio: stdin/stdout son el transporte. Para probarlo manualmente, lo más cómodo es engancharlo a Claude Desktop apuntando command a node y args a ["/ruta/a/mcp-server/dist/index.js"] en lugar de npx.

Estructura del proyecto

mcp-server/
├── src/
│   ├── index.ts            # Entry point — crea McpServer y registra tools
│   ├── client.ts           # MergeOnClient — auth con API key, fetch helpers
│   └── tools/
│       ├── index.ts        # Registra todos los dominios
│       ├── crm.ts
│       ├── orders.ts
│       ├── products.ts
│       ├── conversations.ts
│       ├── flows.ts
│       ├── calendar.ts
│       ├── marketing.ts
│       ├── analytics.ts
│       ├── workers.ts
│       ├── admin.ts
│       ├── agent-config.ts
│       ├── business-context.ts
│       ├── templates.ts
│       ├── ecommerce.ts
│       ├── sales-analytics.ts   # ← v1.4
│       ├── meta-events.ts       # ← v1.4
│       ├── nurturing.ts         # ← v1.4
│       └── webhooks.ts          # ← v1.4
├── skills/
│   ├── prompt-creation.md
│   ├── flows-creation.md
│   ├── nurturing-creation.md    # ← v1.4
│   ├── templates-creation.md    # ← v1.4
│   ├── webhooks-usage.md        # ← v1.4
│   ├── sales-analysis.md        # ← v1.4
│   └── meta-events-debug.md     # ← v1.4
├── scripts/
│   └── install-skills.js   # CLI para `npx mergeon-mcp skills add ...`
├── dist/                   # Output de tsc (no editar)
├── package.json
├── tsconfig.json
└── README.md

Mantenimiento

Si trabajas en este repo, lee también la sección 6 de /CLAUDE.md — define cuándo es obligatorio actualizar el MCP al cambiar el backend.

Añadir una tool nueva

1. Identifica el dominio y abre el archivo en src/tools/<dominio>.ts. Si es un dominio nuevo, créalo:

   // src/tools/nurturing.ts
   import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
   import { z } from "zod";
   import { MergeOnClient } from "../client.js";
   
   function text(data: any) {
     return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] };
   }
   
   export function registerNurturingTools(server: McpServer, client: MergeOnClient) {
     server.tool(
       "nurturing_status",
       "Get nurturing status for a CRM contact: which sequences are active, last touch, next scheduled message.",
       { contact_id: z.string().describe("CRM contact ID") },
       async ({ contact_id }) => text(await client.get(`/nurturing/${contact_id}`))
     );
   }

2. Regístralo en src/tools/index.ts:

   import { registerNurturingTools } from "./nurturing.js";
   // ...
   registerNurturingTools(server, client);

3. Reglas de naming:

   • <dominio>_<accion> en snake_case (flows_create, nurturing_pause, crm_bulk_import).
   • Las descripciones se escriben en inglés (consistencia con el resto del MCP) y van orientadas al modelo: di qué devuelve, cuándo usarla y cualquier precaución (rate-limits, permisos).

4. Schema con Zod:

   • Marca todos los campos opcionales con .optional() salvo los estrictamente requeridos por el endpoint.
   • Usa .describe(...) siempre — Claude lee esas descripciones para decidir qué mandar.
   • Para diccionarios genéricos: z.record(z.any()). Para listas: z.array(...).

5. Compila y arregla TS antes de declarar terminado:

   npm run build

6. Sube versión en package.json siguiendo SemVer:

   • patch (1.1.1) → fix interno o doc.
   • minor (1.2.0) → tools nuevas, no rompen nada.
   • major (2.0.0) → breaking en tools existentes (rename, cambio de schema incompatible).

7. Actualiza este README: añade la tool a la tabla del dominio correspondiente y, si cambia, el conteo total de "Tools disponibles (N)".

Modificar una tool existente

• Si cambias el shape de respuesta del backend, repasa el handler — normalmente no hace falta tocar nada porque devolvemos el JSON tal cual, pero la description puede quedar obsoleta y confundir al modelo. Actualízala.
• Si cambias el schema de entrada (renombras o eliminas un parámetro), es breaking → bump major.
• Si añades parámetros opcionales, es minor.

Skills (skills/*.md)

Los skills se inyectan en el CLAUDE.md del usuario. Tratarlos como contratos:

• No los reformatees por gusto: usuarios pueden tener versiones viejas instaladas.
• Si añades una sección nueva, hazlo aditivamente.
• Si renombras un skill, actualiza scripts/install-skills.js.

Publicación a npm

cd mcp-server
npm run build       # compila a dist/
npm version <patch|minor|major>
npm publish --access public

prepublishOnly corre npm run build automáticamente. El archivo files en package.json controla qué se incluye en el tarball: dist/, skills/, scripts/.

No publiques sin que el usuario lo pida explícitamente. Cambios en el repo no requieren publicación inmediata; pueden quedar en main y publicarse en lote.

Licencia

MIT.