MCP
Referencia · tools

Tools de crm

El dominio crm es el embudo comercial de un tenant: cuentas, oportunidades y su máquina de estados por etapas. Cada tool es una cáscara fina sobre una RPC — la autorización, la máquina de estados y las validaciones viven en la base (crm.*), nunca acá. Corre con tu propia sesión, nunca con una clave de servicio: ctx.db solo expone asUser, así que ninguna tool puede saltear la RLS de pg-dynamo-<env>.

gateway remoto 9 lectura 8 escritura

El embudo (etapas y transiciones) es DATO del tenant, no del producto. Dos clientes con procesos comerciales distintos son dos sets de filas distintos. Antes de crm_move_opportunity, consultá crm_pipeline_config para ver los code de etapa que ese tenant eligió — no hay un set universal. Antes de crm_initialize_tenant, la app crm tiene que estar habilitada en el proyecto y el usuario tener acceso — eso es auth_set_project_app y auth_set_app_access (ver tools de auth), los pasos 1-2 del alta de un cliente.

Un id ajeno devuelve el mismo error que "no existe". Mover una oportunidad sin la capacidad pipeline.escribir_todo da el mismo resultado que un id inventado — es deliberado, para no confirmar que el id existe. crm_configure_stages y crm_configure_transitions no llevan gate propio: la autorización vive en las policies de crm.etapas/ crm.etapa_transiciones (capacidad etapas.administrar) — sin ella, la base responde 42501, nunca una lista vacía.

Lectura (9)

Tool Qué hace Inputs Qué permiso hace falta Ejemplo de prompt
crm_tenant_status Dice qué le falta a un tenant para ser usable: si está inicializado, si tiene roles, usuarios con rol, etapas y transiciones. Que falten etapas y transiciones recién dado de alta NO es un error — es el trabajo de configuración del admin del tenant. Devuelve ["sin acceso"] sin revelar si el tenant existe cuando el que llama no tiene entitlement. tenant_project_id (uuid) Sesión autenticada con acceso al proyecto. "¿Qué le falta al tenant Acme para poder operar?"
crm_search_accounts Busca cuentas del tenant por razón social, nombre comercial, NIT o alias, y dice por cuál de los cuatro coincidió. El NIT se compara normalizado (sin separadores ni dígito de verificación). El nombre nunca es llave: para operar sobre una cuenta usá el cuenta_id que devuelve. tenant_project_id (uuid) · q (texto) · limit (entero, opcional) Sesión autenticada con acceso al proyecto. "Buscá la cuenta 'FIC 48' en el CRM de Acme."
crm_my_pending Las próximas acciones comprometidas DEL QUE LLAMA, vencidas o por vencer dentro de N días (7 por defecto). Sale de la bitácora, no de una columna que alguien tiene que acordarse de actualizar. Solo la vista propia, no la del equipo. tenant_project_id (uuid) · dias (entero, opcional) Sesión autenticada con acceso al proyecto. "¿Qué tengo pendiente esta semana en el CRM?"
crm_pipeline_summary Resumen del embudo por etapa: cantidad, valor total y valor ponderado (calculado en vivo con la probabilidad de la etapa del tenant). Con la capacidad pipeline.leer_todo es el embudo del tenant entero; sin ella, solo el propio — RLS decide, la tool no distingue. tenant_project_id (uuid) Sesión autenticada con acceso al proyecto. "Dame el resumen del embudo del tenant Acme."
crm_list_opportunities Las oportunidades del embudo, fila por fila, con la cuenta, el sector, el contacto principal y la próxima acción comprometida ya resueltos. Filtros: etapas para una columna del kanban, responsable_user_id para la vista de una persona, incluir_terminales: false para esconder ganadas/perdidas, q para buscar por cuenta/código/número/descripción. Un filtro ausente significa "no filtres", nunca "no devuelvas nada". Paginado: cada fila trae cursor_siguiente, opaco — no lo construyas ni lo interpretes. tenant_project_id (uuid) · q/etapas/responsable_user_id/incluir_terminales/limit/cursor (todos opcionales) Sesión autenticada con acceso al proyecto. "Mostrame las oportunidades del tenant Acme en la etapa 'negociación'."
crm_pipeline_config La configuración del embudo de un tenant: etapas, transiciones y lo que todavía le falta para ser usable. Consultala ANTES de mover una oportunidad en vez de adivinar los code de etapa. tenant_project_id (uuid) Sesión autenticada con acceso al proyecto. "¿Qué etapas tiene configuradas el embudo de Acme?"
crm_list_catalog Los valores ACTIVOS de un catálogo del tenant (por ejemplo sectores, soluciones, propuestas — el tipo es texto libre, no hay un set fijo). Un valor eliminado deja de aparecer acá pero no se borra de la base (ver crm_manage_catalog). tenant_project_id (uuid) · tipo (texto) Sesión autenticada con acceso al proyecto. "Dame el catálogo de sectores del tenant Acme."
crm_get_handoff El handoff de UNA oportunidad ganada: objetivo, compromisos, riesgos, checklist, responsable y los documentos de soporte ya adjuntados (contrato/ans/cámara de comercio/rut/propuesta). Devuelve null si la oportunidad todavía no ganó o si no hay acceso — nunca distingue los dos casos. tenant_project_id (uuid) · oportunidad_id (uuid) Visibilidad = la de la oportunidad (RLS de la policy, no un gate propio de la tool). "Mostrame el handoff de la oportunidad X."

Escritura (8)

Confirmá el ambiente con dynamo_session_status (ver tools de ops) antes de cualquiera de estas.

Tool Qué hace Inputs Qué permiso hace falta Ejemplo de prompt
crm_initialize_tenant Da de alta un tenant del CRM: crea su configuración y un rol administrador. Paso 3 del alta de un cliente (1-2 son de auth) — exige que ese entitlement YA exista, no lo otorga. Hace lo MÍNIMO a propósito: no crea etapas ni catálogos, eso lo decide el cliente. NO es idempotente: si el tenant ya está inicializado, falla. El project_id es distinto en QA y en prod para el mismo cliente: nunca reuses uno. tenant_project_id (uuid) · nombre (texto) · admin_user_id (uuid) Solo global-admin. "Dá de alta el tenant CRM para el proyecto Acme."
crm_move_opportunity Mueve una oportunidad de etapa por la máquina de estados DEL TENANT. La transición tiene que estar declarada por ese tenant y la etapa destino puede exigir requisitos. Escribe el evento en la bitácora en la misma transacción. Mover a la etapa en la que ya está es idempotente y no hace nada. opportunity_id (uuid) · etapa (texto, el code del tenant) · nota (texto, opcional) Capacidad pipeline.escribir_todo (o ser el responsable de la oportunidad). "Movéme la oportunidad X a la etapa 'negociación'."
crm_register_event Registra un evento en la bitácora de una oportunidad — típicamente la próxima acción comprometida (llamada, visita, propuesta) y su fecha, SIN mover de etapa. Es la mitad simétrica de crm_move_opportunity, que ya escribe un evento pero solo al transicionar. proxima_accion y fecha son obligatorias: sin ellas crm_my_pending no tiene de dónde sacar el próximo compromiso. tenant_project_id (uuid) · opportunity_id (uuid) · proxima_accion (texto) · fecha (texto) · tipo/nota (opcionales) Capacidad pipeline.escribir (propia) o pipeline.escribir_todo (ajena). "Registrá que voy a llamar al cliente de la oportunidad X el viernes."
crm_create_opportunity Crea una oportunidad en el embudo de un tenant. Nace en la ETAPA INICIAL que definió ese tenant (la de menor orden que no sea terminal), no en un code universal — no existe tal cosa. El responsable es SIEMPRE quien llama, sin parámetro para crear a nombre de otro. Si el tenant todavía no definió etapas, falla pidiendo crm_configure_stages primero, en vez de un error de integridad. tenant_project_id (uuid) · descripcion (texto) · cuenta_id/etapa_code/valor_antes_iva/periodicidad_dias/numero_visible (opcionales) Capacidad pipeline.escribir. "Creá una oportunidad para la cuenta FIC 48 por $5.000.000 mensuales."
crm_configure_stages Define (crea o actualiza) las etapas del embudo de un tenant. NO borra: retirar una etapa con oportunidades ya cargadas es otra operación. Un array vacío falla en vez de no hacer nada en silencio. tenant_project_id (uuid) · etapas (array de {code, nombre, probabilidad?, orden?, es_terminal?}, mínimo 1) Capacidad etapas.administrar. "Configurá las etapas del embudo de Acme: Prospecto, Calificado, Propuesta, Cerrado."
crm_configure_transitions Define qué movimientos son legales entre etapas. Sin transiciones ninguna oportunidad puede moverse — esta tool y crm_configure_stages son lo que vuelve usable un tenant recién dado de alta. Las dos etapas tienen que existir: un desde inventado da un error de integridad, nunca una transición fantasma. tenant_project_id (uuid) · transiciones (array de {desde, hasta}, mínimo 1) Capacidad etapas.administrar. "Permití pasar de 'Prospecto' a 'Calificado' y de 'Calificado' a 'Propuesta'."
crm_manage_catalog Agrega o retira UN valor de un catálogo del tenant y devuelve el catálogo completo ya actualizado. accion: "agregar" requiere valor; accion: "eliminar" requiere id (el que devuelve crm_list_catalog). Eliminar es SIEMPRE SOFT (activo = false): un valor ya usado por una cuenta u oportunidad no se destruye, solo deja de ofrecerse para elegir de nuevo. Reagregar un valor retirado lo reactiva en vez de duplicarlo. tenant_project_id (uuid) · tipo (texto) · accion (enum: agregar | eliminar) · valor/id (según la acción) Capacidad catalogo.administrar. "Agregá 'Retail' al catálogo de sectores del tenant Acme."
crm_update_handoff Actualiza uno o varios campos de un handoff ya creado (objetivo/compromisos/riesgos/checklist/responsable) y devuelve la fila completa. Un campo omitido conserva su valor actual — no hace falta reenviar los que no cambian. tenant_project_id (uuid) · oportunidad_id (uuid) · objetivo/compromisos/riesgos/checklist/responsable_user_id (todos opcionales) Capacidad handoff.escribir (rol "operaciones", o el que el tenant le haya dado esa capacidad). Un comercial sin ella recibe 42501, no un cambio parcial. "Actualizá el objetivo del handoff de la oportunidad X."
crm_attach_handoff_document Adjunta (o reemplaza) UN documento manual de soporte de un handoff: tipo es contrato, ans (Acuerdo de Nivel de Servicio), camara_comercio o rut — un enlace simple, sin subida de archivo. propuesta NO se acepta acá: esa la adjunta automático el Constructor. Reagregar el mismo tipo reemplaza el enlace, no duplica la fila. tenant_project_id (uuid) · oportunidad_id (uuid) · tipo (enum) · url (texto) · nombre (opcional) Capacidad handoff.escribir. "Adjuntá el contrato de la oportunidad X: [url]."

Para errores concretos de estas tools: Troubleshooting. Para correr los MCPs en stdio localmente en vez del gateway: Para desarrolladores.