mirlo-mcp 1.0.0

package/README.md

@@ -0,0 +1,171 @@
+# Mirlo para Claude
+
+Conectá tu CRM de Mirlo con Claude para consultar y gestionar oportunidades, contactos, tickets y tareas usando lenguaje natural.
+
+## ¿Qué puedo hacer?
+
+Preguntale a Claude cosas como:
+
+- *"¿Cuántos deals abiertos tengo arriba de $100k?"*
+- *"Creame un ticket de soporte con prioridad alta"*
+- *"¿Qué tareas tengo vencidas?"*
+- *"Dame los contactos de la empresa Farmacias del Ahorro"*
+- *"¿Cuáles oportunidades cierran esta semana?"*
+- *"Creá una tarea para llamar al cliente mañana"*
+
+---
+
+## Configuración paso a paso
+
+### Paso 1: Obtené tu API Key de Mirlo
+
+1. Ingresá a [app.mirlo.com](https://app.mirlo.com)
+2. Andá a **Mi Organización** → **API Keys**
+3. Hacé click en **+ Crear API Key**
+4. Copiá la key (empieza con `sk_live_`)
+
+### Paso 2: Instalá Node.js (si no lo tenés)
+
+Descargá e instalá Node.js desde [nodejs.org](https://nodejs.org). Elegí la versión LTS (recomendada).
+
+Para verificar que está instalado, abrí la Terminal y escribí:
+```
+node --version
+```
+Debería mostrar algo como `v22.x.x`.
+
+### Paso 3: Configurá Claude Desktop
+
+1. Abrí **Claude Desktop**
+2. Andá a **Settings** (Configuración) → **Developer** → **Edit Config**
+3. Se abre un archivo. Reemplazá el contenido con:
+
+```json
+{
+  "mcpServers": {
+    "mirlo": {
+      "command": "npx",
+      "args": ["-y", "@mirlo/mcp", "--api-key=TU_API_KEY_AQUI"]
+    }
+  }
+}
+```
+
+4. Reemplazá `TU_API_KEY_AQUI` con tu API key de Mirlo (la que copiaste en el Paso 1)
+5. Guardá el archivo y **reiniciá Claude Desktop**
+
+### Paso 4: ¡Listo!
+
+Abrí una nueva conversación en Claude y preguntá algo sobre tu CRM:
+
+> *"¿Cuántos tickets abiertos tengo?"*
+
+Claude va a usar las herramientas de Mirlo automáticamente para responder.
+
+---
+
+## Configuración con Claude Code (CLI)
+
+Si usás Claude Code en la terminal:
+
+```bash
+# Agregar el MCP server
+claude mcp add mirlo npx -y @mirlo/mcp --api-key=sk_live_xxx
+```
+
+---
+
+## ¿Qué puede hacer?
+
+### CRM — Oportunidades
+| Acción | Ejemplo |
+|--------|---------|
+| Listar deals | *"Dame las oportunidades abiertas ordenadas por monto"* |
+| Buscar deals | *"¿Hay deals que cierran esta semana?"* |
+| Crear deal | *"Creá una oportunidad para Acme Corp por $50,000"* |
+| Mover de etapa | *"Mové el deal de Acme a Negociación"* |
+| Filtrar por tiempo | *"¿Qué deals llevan más de 24 horas en Prospecto?"* |
+
+### CRM — Contactos y Cuentas
+| Acción | Ejemplo |
+|--------|---------|
+| Buscar contactos | *"Buscame los contactos de la empresa Café Digital"* |
+| Crear contacto | *"Creá un contacto: Ana García, ana@empresa.com"* |
+| Listar cuentas | *"¿Qué cuentas tenemos en la industria Tecnología?"* |
+
+### CRM — Tickets
+| Acción | Ejemplo |
+|--------|---------|
+| Ver tickets abiertos | *"¿Cuántos tickets abiertos hay?"* |
+| Crear ticket | *"Creá un ticket urgente: Error en la integración"* |
+| Filtrar por prioridad | *"Mostrá los tickets de prioridad alta"* |
+
+### CRM — Tareas
+| Acción | Ejemplo |
+|--------|---------|
+| Ver tareas pendientes | *"¿Qué tareas tengo para hoy?"* |
+| Tareas vencidas | *"¿Hay tareas vencidas?"* |
+| Crear tarea | *"Creá una tarea para llamar a Ana García mañana"* |
+| Completar tarea | *"Marcá como completada la tarea de llamar a Ana"* |
+
+### Messaging
+| Acción | Ejemplo |
+|--------|---------|
+| Enviar mensaje | *"Mandá un WhatsApp a +52 55 1234 5678 diciendo: Hola, te contacto de Mirlo"* |
+| Ver conversaciones | *"Mostrá las últimas conversaciones"* |
+
+### Voz
+| Acción | Ejemplo |
+|--------|---------|
+| Ver llamadas | *"¿Cuántas llamadas entrantes hubo hoy?"* |
+| Transcripción | *"Dame la transcripción de la última llamada"* |
+
+---
+
+## Solución de problemas
+
+### "Claude no encuentra las herramientas de Mirlo"
+- Verificá que reiniciaste Claude Desktop después de editar la configuración
+- Verificá que tu API Key es válida en [app.mirlo.com](https://app.mirlo.com) → API Keys
+
+### "Error de autenticación"
+- Tu API Key puede haber expirado. Generá una nueva en Mi Organización → API Keys
+
+### "npx no se encuentra"
+- Instalá Node.js desde [nodejs.org](https://nodejs.org)
+
+---
+
+## Soporte
+
+¿Necesitás ayuda? Contactanos en [mirlo.com](https://mirlo.com) o por WhatsApp.
+
+---
+
+## Para desarrolladores
+
+### Instalación manual
+
+```bash
+npm install -g @mirlo/mcp
+mirlo-mcp --api-key=sk_live_xxx
+```
+
+### Variables de entorno
+
+```bash
+MIRLO_API_KEY=sk_live_xxx    # API key (requerida)
+MIRLO_BASE_URL=https://...   # URL base (opcional, default: api.mirlo.com)
+```
+
+### Herramientas disponibles (21 tools)
+
+**CRM:** `mirlo_list_deals`, `mirlo_get_deal`, `mirlo_create_deal`, `mirlo_update_deal`, `mirlo_move_deal_stage`, `mirlo_list_contacts`, `mirlo_get_contact`, `mirlo_create_contact`, `mirlo_list_accounts`, `mirlo_create_account`, `mirlo_list_tickets`, `mirlo_create_ticket`, `mirlo_list_tasks`, `mirlo_create_task`, `mirlo_complete_task`, `mirlo_list_pipelines`
+
+**Messaging:** `mirlo_send_message`, `mirlo_send_template`, `mirlo_list_conversations`
+
+**Voice:** `mirlo_list_calls`, `mirlo_get_call_transcript`
+
+## Licencia
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Mirlo API Client — wraps the public API for CRM, Messaging, and Voice.
+ */
+export declare class MirloClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    constructor(apiKey: string, baseUrl?: string);
+    private request;
+    listDeals(filters?: Record<string, string | number | boolean>): Promise<any>;
+    getDeal(id: string): Promise<any>;
+    createDeal(data: Record<string, unknown>): Promise<any>;
+    updateDeal(id: string, data: Record<string, unknown>): Promise<any>;
+    moveDealStage(id: string, stageId: string): Promise<any>;
+    deleteDeal(id: string): Promise<any>;
+    listContacts(filters?: Record<string, string>): Promise<any>;
+    getContact(id: string): Promise<any>;
+    createContact(data: Record<string, unknown>): Promise<any>;
+    updateContact(id: string, data: Record<string, unknown>): Promise<any>;
+    listAccounts(filters?: Record<string, string>): Promise<any>;
+    getAccount(id: string): Promise<any>;
+    createAccount(data: Record<string, unknown>): Promise<any>;
+    updateAccount(id: string, data: Record<string, unknown>): Promise<any>;
+    listTickets(filters?: Record<string, string>): Promise<any>;
+    getTicket(id: string): Promise<any>;
+    createTicket(data: Record<string, unknown>): Promise<any>;
+    updateTicket(id: string, data: Record<string, unknown>): Promise<any>;
+    listTasks(filters?: Record<string, string>): Promise<any>;
+    createTask(data: Record<string, unknown>): Promise<any>;
+    completeTask(id: string): Promise<any>;
+    listPipelines(): Promise<any>;
+    sendMessage(to: string, body: string, channel?: string): Promise<any>;
+    sendTemplate(to: string, templateId: string, params?: Record<string, string>): Promise<any>;
+    listConversations(filters?: Record<string, string>): Promise<any>;
+    listMessages(conversationId: string, limit?: number): Promise<any>;
+    listCalls(filters?: Record<string, string>): Promise<any>;
+    getCallTranscript(callId: string): Promise<any>;
+}

package/dist/client.js

@@ -0,0 +1,126 @@
+/**
+ * Mirlo API Client — wraps the public API for CRM, Messaging, and Voice.
+ */
+export class MirloClient {
+    baseUrl;
+    apiKey;
+    constructor(apiKey, baseUrl = 'https://api.mirlo.com/v1') {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl;
+    }
+    async request(method, path, body) {
+        const url = `${this.baseUrl}${path}`;
+        const res = await fetch(url, {
+            method,
+            headers: {
+                'X-API-Key': this.apiKey,
+                'Content-Type': 'application/json',
+            },
+            ...(body ? { body: JSON.stringify(body) } : {}),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`Mirlo API ${method} ${path} → ${res.status}: ${text.slice(0, 200)}`);
+        }
+        return res.json();
+    }
+    // ── CRM: Deals ──
+    async listDeals(filters) {
+        const params = filters ? '?' + new URLSearchParams(Object.entries(filters).map(([k, v]) => [k, String(v)])).toString() : '';
+        return this.request('GET', `/crm/deals${params}`);
+    }
+    async getDeal(id) {
+        return this.request('GET', `/crm/deals/${id}`);
+    }
+    async createDeal(data) {
+        return this.request('POST', '/crm/deals', data);
+    }
+    async updateDeal(id, data) {
+        return this.request('PATCH', `/crm/deals/${id}`, data);
+    }
+    async moveDealStage(id, stageId) {
+        return this.request('PATCH', `/crm/deals/${id}/stage`, { stage_id: stageId });
+    }
+    async deleteDeal(id) {
+        return this.request('DELETE', `/crm/deals/${id}`);
+    }
+    // ── CRM: Contacts ──
+    async listContacts(filters) {
+        const params = filters ? '?' + new URLSearchParams(filters).toString() : '';
+        return this.request('GET', `/crm/contacts${params}`);
+    }
+    async getContact(id) {
+        return this.request('GET', `/crm/contacts/${id}`);
+    }
+    async createContact(data) {
+        return this.request('POST', '/crm/contacts', data);
+    }
+    async updateContact(id, data) {
+        return this.request('PATCH', `/crm/contacts/${id}`, data);
+    }
+    // ── CRM: Accounts ──
+    async listAccounts(filters) {
+        const params = filters ? '?' + new URLSearchParams(filters).toString() : '';
+        return this.request('GET', `/crm/accounts${params}`);
+    }
+    async getAccount(id) {
+        return this.request('GET', `/crm/accounts/${id}`);
+    }
+    async createAccount(data) {
+        return this.request('POST', '/crm/accounts', data);
+    }
+    async updateAccount(id, data) {
+        return this.request('PATCH', `/crm/accounts/${id}`, data);
+    }
+    // ── CRM: Tickets ──
+    async listTickets(filters) {
+        const params = filters ? '?' + new URLSearchParams(filters).toString() : '';
+        return this.request('GET', `/crm/tickets${params}`);
+    }
+    async getTicket(id) {
+        return this.request('GET', `/crm/tickets/${id}`);
+    }
+    async createTicket(data) {
+        return this.request('POST', '/crm/tickets', data);
+    }
+    async updateTicket(id, data) {
+        return this.request('PATCH', `/crm/tickets/${id}`, data);
+    }
+    // ── CRM: Tasks ──
+    async listTasks(filters) {
+        const params = filters ? '?' + new URLSearchParams(filters).toString() : '';
+        return this.request('GET', `/crm/tasks${params}`);
+    }
+    async createTask(data) {
+        return this.request('POST', '/crm/tasks', data);
+    }
+    async completeTask(id) {
+        return this.request('PATCH', `/crm/tasks/${id}/complete`);
+    }
+    // ── CRM: Pipelines ──
+    async listPipelines() {
+        return this.request('GET', '/crm/pipelines');
+    }
+    // ── Messaging ──
+    async sendMessage(to, body, channel = 'whatsapp') {
+        return this.request('POST', '/messages', { to, body, channel });
+    }
+    async sendTemplate(to, templateId, params) {
+        return this.request('POST', '/messages/templates', { to, template_id: templateId, params });
+    }
+    async listConversations(filters) {
+        const params = filters ? '?' + new URLSearchParams(filters).toString() : '';
+        return this.request('GET', `/conversations${params}`);
+    }
+    async listMessages(conversationId, limit = 20) {
+        return this.request('GET', `/conversations/${conversationId}/messages?limit=${limit}`);
+    }
+    // ── Voice ──
+    async listCalls(filters) {
+        const params = filters ? '?' + new URLSearchParams(filters).toString() : '';
+        return this.request('GET', `/calls${params}`);
+    }
+    async getCallTranscript(callId) {
+        return this.request('GET', `/calls/${callId}/transcript`);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * Mirlo MCP Server
+ *
+ * Exposes Mirlo CRM, Messaging, and Voice as MCP tools
+ * for use with Claude, GPT, and other LLM clients.
+ *
+ * Usage:
+ *   npx @mirlo/mcp --api-key=sk_live_xxx
+ *   MIRLO_API_KEY=sk_live_xxx npx @mirlo/mcp
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+/**
+ * Mirlo MCP Server
+ *
+ * Exposes Mirlo CRM, Messaging, and Voice as MCP tools
+ * for use with Claude, GPT, and other LLM clients.
+ *
+ * Usage:
+ *   npx @mirlo/mcp --api-key=sk_live_xxx
+ *   MIRLO_API_KEY=sk_live_xxx npx @mirlo/mcp
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { MirloClient } from './client.js';
+import { ALL_TOOLS } from './tools.js';
+// ── Parse API key ──
+function getApiKey() {
+    // From CLI arg: --api-key=xxx
+    const cliArg = process.argv.find(a => a.startsWith('--api-key='));
+    if (cliArg)
+        return cliArg.split('=')[1];
+    // From env
+    if (process.env.MIRLO_API_KEY)
+        return process.env.MIRLO_API_KEY;
+    console.error('Error: API key required. Use --api-key=sk_live_xxx or set MIRLO_API_KEY env var.');
+    console.error('Get your API key at: app.mirlo.com → Mi Organización → API Keys');
+    process.exit(1);
+    return ''; // unreachable, satisfies TS
+}
+function getBaseUrl() {
+    const cliArg = process.argv.find(a => a.startsWith('--base-url='));
+    if (cliArg)
+        return cliArg.split('=')[1];
+    return process.env.MIRLO_BASE_URL || 'https://api.mirlo.com/v1';
+}
+// ── Main ──
+async function main() {
+    const apiKey = getApiKey();
+    const baseUrl = getBaseUrl();
+    const client = new MirloClient(apiKey, baseUrl);
+    const server = new McpServer({
+        name: 'mirlo',
+        version: '1.0.0',
+        description: 'Mirlo CRM, Messaging & Voice — manage deals, contacts, tickets, tasks, send messages, and track calls.',
+    });
+    // Register all tools
+    for (const tool of ALL_TOOLS) {
+        server.tool(tool.name, tool.description, tool.schema.shape, async (args) => {
+            try {
+                const result = await tool.handler(client, args);
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2),
+                        }],
+                };
+            }
+            catch (error) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `Error: ${error.message}`,
+                        }],
+                    isError: true,
+                };
+            }
+        });
+    }
+    // Start stdio transport
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch(err => {
+    console.error('Fatal:', err);
+    process.exit(1);
+});

package/dist/tools.d.ts

@@ -0,0 +1,12 @@
+/**
+ * MCP Tool definitions for Mirlo CRM, Messaging, and Voice.
+ */
+import { z } from 'zod';
+import type { MirloClient } from './client.js';
+export interface ToolDef {
+    name: string;
+    description: string;
+    schema: z.ZodObject<any>;
+    handler: (client: MirloClient, args: any) => Promise<any>;
+}
+export declare const ALL_TOOLS: ToolDef[];

package/dist/tools.js

@@ -0,0 +1,286 @@
+/**
+ * MCP Tool definitions for Mirlo CRM, Messaging, and Voice.
+ */
+import { z } from 'zod';
+// ── CRM: Deals ──
+const listDeals = {
+    name: 'mirlo_list_deals',
+    description: 'List deals/opportunities with optional filters. Returns paginated results with total count.',
+    schema: z.object({
+        search: z.string().optional().describe('Search by deal name'),
+        pipeline_id: z.string().optional().describe('Filter by pipeline UUID'),
+        stage_id: z.string().optional().describe('Filter by stage UUID'),
+        status: z.enum(['open', 'won', 'lost']).optional().describe('Filter by status'),
+        owner_id: z.string().optional().describe('Filter by owner member UUID'),
+        account_id: z.string().optional().describe('Filter by account UUID'),
+        amount_min: z.number().optional().describe('Minimum deal amount'),
+        amount_max: z.number().optional().describe('Maximum deal amount'),
+        min_stage_hours: z.number().optional().describe('Minimum hours in current stage'),
+        max_stage_hours: z.number().optional().describe('Maximum hours in current stage'),
+        product_id: z.string().optional().describe('Filter by product UUID'),
+        currency: z.string().optional().describe('Filter by currency code (MXN, USD, etc.)'),
+        expected_close_before: z.string().optional().describe('Close date before (YYYY-MM-DD) — deals closing before this date'),
+        expected_close_after: z.string().optional().describe('Close date after (YYYY-MM-DD) — deals closing after this date'),
+        created_after: z.string().optional().describe('Created after (YYYY-MM-DD)'),
+        created_before: z.string().optional().describe('Created before (YYYY-MM-DD)'),
+        sort_by: z.string().optional().describe('Sort by field: amount, created_at, expected_close_date, name'),
+        sort_dir: z.enum(['asc', 'desc']).optional().describe('Sort direction'),
+        limit: z.number().optional().default(20).describe('Max results (default 20)'),
+        offset: z.number().optional().default(0).describe('Pagination offset'),
+    }),
+    handler: async (client, args) => client.listDeals(args),
+};
+const createDeal = {
+    name: 'mirlo_create_deal',
+    description: 'Create a new deal/opportunity in a pipeline.',
+    schema: z.object({
+        name: z.string().describe('Deal name'),
+        pipeline_id: z.string().describe('Pipeline UUID'),
+        stage_id: z.string().describe('Initial stage UUID'),
+        amount: z.number().optional().describe('Deal amount'),
+        currency: z.string().optional().default('MXN').describe('Currency code (default MXN)'),
+        owner_id: z.string().optional().describe('Owner member UUID'),
+        account_id: z.string().optional().describe('Account UUID'),
+        expected_close_date: z.string().optional().describe('Expected close date (YYYY-MM-DD)'),
+    }),
+    handler: async (client, args) => client.createDeal(args),
+};
+const updateDeal = {
+    name: 'mirlo_update_deal',
+    description: 'Update an existing deal. Only provided fields are updated.',
+    schema: z.object({
+        deal_id: z.string().describe('Deal UUID'),
+        name: z.string().optional(),
+        amount: z.number().optional(),
+        owner_id: z.string().optional(),
+        account_id: z.string().optional(),
+        status: z.enum(['open', 'won', 'lost']).optional(),
+        expected_close_date: z.string().optional(),
+    }),
+    handler: async (client, { deal_id, ...data }) => client.updateDeal(deal_id, data),
+};
+const moveDealStage = {
+    name: 'mirlo_move_deal_stage',
+    description: 'Move a deal to a different pipeline stage.',
+    schema: z.object({
+        deal_id: z.string().describe('Deal UUID'),
+        stage_id: z.string().describe('Target stage UUID'),
+    }),
+    handler: async (client, args) => client.moveDealStage(args.deal_id, args.stage_id),
+};
+const getDeal = {
+    name: 'mirlo_get_deal',
+    description: 'Get a deal by ID with full details including stage times, contacts, and conversations.',
+    schema: z.object({
+        deal_id: z.string().describe('Deal UUID'),
+    }),
+    handler: async (client, args) => client.getDeal(args.deal_id),
+};
+// ── CRM: Contacts ──
+const listContacts = {
+    name: 'mirlo_list_contacts',
+    description: 'List contacts with optional search and filters.',
+    schema: z.object({
+        search: z.string().optional().describe('Search by name, email, or phone'),
+        owner_id: z.string().optional().describe('Filter by owner'),
+        account_id: z.string().optional().describe('Filter by account'),
+        label_ids: z.string().optional().describe('Comma-separated label UUIDs'),
+        lifecycle_stage: z.string().optional().describe('lead, customer, partner, vendor, other'),
+        source_address: z.string().optional().describe('Filter by source phone/channel address'),
+        limit: z.number().optional().default(20),
+        offset: z.number().optional().default(0),
+    }),
+    handler: async (client, args) => client.listContacts(args),
+};
+const createContact = {
+    name: 'mirlo_create_contact',
+    description: 'Create a new contact.',
+    schema: z.object({
+        full_name: z.string().describe('Full name'),
+        first_name: z.string().optional(),
+        last_name: z.string().optional(),
+        primary_email: z.string().optional().describe('Email address'),
+        primary_phone: z.string().optional().describe('Phone number'),
+        account_id: z.string().optional().describe('Account UUID to link'),
+    }),
+    handler: async (client, args) => client.createContact(args),
+};
+const getContact = {
+    name: 'mirlo_get_contact',
+    description: 'Get a contact by ID.',
+    schema: z.object({ contact_id: z.string().describe('Contact UUID') }),
+    handler: async (client, args) => client.getContact(args.contact_id),
+};
+// ── CRM: Accounts ──
+const listAccounts = {
+    name: 'mirlo_list_accounts',
+    description: 'List accounts/companies with optional filters.',
+    schema: z.object({
+        search: z.string().optional().describe('Search by name or domain'),
+        industry: z.string().optional(),
+        lifecycle_stage: z.string().optional().describe('lead, customer, partner, vendor, other'),
+        owner_id: z.string().optional().describe('Filter by owner member UUID'),
+        source: z.string().optional().describe('manual, import, api, whatsapp, flow'),
+        city: z.string().optional(),
+        country: z.string().optional(),
+        limit: z.number().optional().default(20),
+        offset: z.number().optional().default(0),
+    }),
+    handler: async (client, args) => client.listAccounts(args),
+};
+const createAccount = {
+    name: 'mirlo_create_account',
+    description: 'Create a new account/company.',
+    schema: z.object({
+        name: z.string().describe('Company name'),
+        domain: z.string().optional().describe('Company domain'),
+        industry: z.string().optional(),
+        phone: z.string().optional(),
+        email: z.string().optional(),
+        city: z.string().optional(),
+        country: z.string().optional(),
+    }),
+    handler: async (client, args) => client.createAccount(args),
+};
+// ── CRM: Tickets ──
+const listTickets = {
+    name: 'mirlo_list_tickets',
+    description: 'List support tickets with filters.',
+    schema: z.object({
+        search: z.string().optional().describe('Search by title or reference'),
+        state: z.enum(['new', 'waiting_on_agent', 'waiting_on_customer', 'on_hold', 'closed']).optional().describe('Filter by specific state'),
+        exclude_closed: z.boolean().optional().describe('Set to true to get only open tickets (excludes closed)'),
+        priority: z.enum(['low', 'normal', 'high', 'urgent']).optional(),
+        owner_id: z.string().optional().describe('Filter by assignee'),
+        project_id: z.string().optional().describe('Filter by project UUID'),
+        source: z.enum(['channel', 'api', 'manual', 'form', 'automation']).optional(),
+        channel: z.string().optional().describe('whatsapp, voice, email, webchat, sms'),
+        account_id: z.string().optional().describe('Filter by account'),
+        limit: z.number().optional().default(20),
+        offset: z.number().optional().default(0),
+    }),
+    handler: async (client, args) => client.listTickets(args),
+};
+const createTicket = {
+    name: 'mirlo_create_ticket',
+    description: 'Create a support ticket.',
+    schema: z.object({
+        title: z.string().describe('Ticket title'),
+        body_html: z.string().optional().describe('Ticket description'),
+        priority: z.enum(['low', 'normal', 'high', 'urgent']).optional().default('normal'),
+        owner_id: z.string().optional().describe('Assignee member UUID'),
+    }),
+    handler: async (client, args) => client.createTicket({ ...args, source: 'api' }),
+};
+// ── CRM: Tasks ──
+const listTasks = {
+    name: 'mirlo_list_tasks',
+    description: 'List tasks with filters. Supports filtering by assignee, status, due date, and associated entities.',
+    schema: z.object({
+        owner_id: z.string().optional().describe('Filter by assignee'),
+        is_completed: z.boolean().optional().describe('true=completed, false=pending'),
+        type: z.enum(['to_do', 'call', 'email', 'meeting', 'follow_up']).optional(),
+        priority: z.enum(['low', 'normal', 'high', 'urgent']).optional(),
+        due_before: z.string().optional().describe('Due date before (YYYY-MM-DD) — tasks due before this date'),
+        due_after: z.string().optional().describe('Due date after (YYYY-MM-DD) — tasks due after this date'),
+        overdue: z.boolean().optional().describe('Only overdue tasks'),
+        deal_id: z.string().optional(),
+        ticket_id: z.string().optional(),
+        contact_id: z.string().optional(),
+        account_id: z.string().optional(),
+        search: z.string().optional().describe('Search by title'),
+        limit: z.number().optional().default(20),
+    }),
+    handler: async (client, args) => client.listTasks(args),
+};
+const createTask = {
+    name: 'mirlo_create_task',
+    description: 'Create a task, optionally associated to a deal, ticket, contact, or account.',
+    schema: z.object({
+        title: z.string().describe('Task title'),
+        type: z.enum(['to_do', 'call', 'email', 'meeting', 'follow_up']).optional().default('to_do'),
+        priority: z.enum(['low', 'normal', 'high', 'urgent']).optional().default('normal'),
+        due_date: z.string().optional().describe('Due date ISO 8601'),
+        owner_id: z.string().optional().describe('Assignee member UUID'),
+        deal_id: z.string().optional(),
+        ticket_id: z.string().optional(),
+        contact_id: z.string().optional(),
+        notes: z.string().optional(),
+    }),
+    handler: async (client, args) => client.createTask(args),
+};
+const completeTask = {
+    name: 'mirlo_complete_task',
+    description: 'Mark a task as completed.',
+    schema: z.object({ task_id: z.string().describe('Task UUID') }),
+    handler: async (client, args) => client.completeTask(args.task_id),
+};
+// ── CRM: Pipelines ──
+const listPipelines = {
+    name: 'mirlo_list_pipelines',
+    description: 'List all pipelines with their stages. Useful for getting pipeline/stage IDs before creating deals.',
+    schema: z.object({}),
+    handler: async (client) => client.listPipelines(),
+};
+// ── Messaging ──
+const sendMessage = {
+    name: 'mirlo_send_message',
+    description: 'Send a WhatsApp or SMS message to a phone number.',
+    schema: z.object({
+        to: z.string().describe('Recipient phone number (E.164 format)'),
+        body: z.string().describe('Message text'),
+        channel: z.enum(['whatsapp', 'sms']).optional().default('whatsapp'),
+    }),
+    handler: async (client, args) => client.sendMessage(args.to, args.body, args.channel),
+};
+const sendTemplate = {
+    name: 'mirlo_send_template',
+    description: 'Send a pre-approved WhatsApp template message.',
+    schema: z.object({
+        to: z.string().describe('Recipient phone number'),
+        template_id: z.string().describe('Template ID'),
+        params: z.record(z.string(), z.string()).optional().describe('Template parameters'),
+    }),
+    handler: async (client, args) => client.sendTemplate(args.to, args.template_id, args.params),
+};
+const listConversations = {
+    name: 'mirlo_list_conversations',
+    description: 'List recent conversations across channels.',
+    schema: z.object({
+        status: z.string().optional().describe('Filter by status'),
+        limit: z.number().optional().default(20),
+    }),
+    handler: async (client, args) => client.listConversations(args),
+};
+// ── Voice ──
+const listCalls = {
+    name: 'mirlo_list_calls',
+    description: 'List phone calls with filters.',
+    schema: z.object({
+        direction: z.enum(['inbound', 'outbound']).optional(),
+        limit: z.number().optional().default(20),
+    }),
+    handler: async (client, args) => client.listCalls(args),
+};
+const getCallTranscript = {
+    name: 'mirlo_get_call_transcript',
+    description: 'Get the AI-generated transcript of a phone call.',
+    schema: z.object({
+        call_id: z.string().describe('Call UUID'),
+    }),
+    handler: async (client, args) => client.getCallTranscript(args.call_id),
+};
+// ── Export all tools ──
+export const ALL_TOOLS = [
+    // CRM
+    listDeals, getDeal, createDeal, updateDeal, moveDealStage,
+    listContacts, getContact, createContact,
+    listAccounts, createAccount,
+    listTickets, createTicket,
+    listTasks, createTask, completeTask,
+    listPipelines,
+    // Messaging
+    sendMessage, sendTemplate, listConversations,
+    // Voice
+    listCalls, getCallTranscript,
+];

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "mirlo-mcp",
+  "version": "1.0.0",
+  "description": "Mirlo MCP Server — CRM, Messaging & Voice tools for Claude, GPT, and other LLMs",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "mirlo-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js"
+  },
+  "keywords": ["mirlo", "mcp", "crm", "whatsapp", "voice", "ai", "claude"],
+  "author": "Mirlo <dev@mirlo.mx>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MirloLLC/mirlo-mcp-server"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "tsx": "^4.23.1",
+    "typescript": "^7.0.2"
+  }
+}

package/src/client.ts

@@ -0,0 +1,167 @@
+/**
+ * Mirlo API Client — wraps the public API for CRM, Messaging, and Voice.
+ */
+
+export class MirloClient {
+  private readonly baseUrl: string;
+  private readonly apiKey: string;
+
+  constructor(apiKey: string, baseUrl = 'https://api.mirlo.com/v1') {
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl;
+  }
+
+  private async request<T>(method: string, path: string, body?: unknown): Promise<T> {
+    const url = `${this.baseUrl}${path}`;
+    const res = await fetch(url, {
+      method,
+      headers: {
+        'X-API-Key': this.apiKey,
+        'Content-Type': 'application/json',
+      },
+      ...(body ? { body: JSON.stringify(body) } : {}),
+    });
+
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`Mirlo API ${method} ${path} → ${res.status}: ${text.slice(0, 200)}`);
+    }
+
+    return res.json() as T;
+  }
+
+  // ── CRM: Deals ──
+
+  async listDeals(filters?: Record<string, string | number | boolean>) {
+    const params = filters ? '?' + new URLSearchParams(Object.entries(filters).map(([k, v]) => [k, String(v)])).toString() : '';
+    return this.request<any>('GET', `/crm/deals${params}`);
+  }
+
+  async getDeal(id: string) {
+    return this.request<any>('GET', `/crm/deals/${id}`);
+  }
+
+  async createDeal(data: Record<string, unknown>) {
+    return this.request<any>('POST', '/crm/deals', data);
+  }
+
+  async updateDeal(id: string, data: Record<string, unknown>) {
+    return this.request<any>('PATCH', `/crm/deals/${id}`, data);
+  }
+
+  async moveDealStage(id: string, stageId: string) {
+    return this.request<any>('PATCH', `/crm/deals/${id}/stage`, { stage_id: stageId });
+  }
+
+  async deleteDeal(id: string) {
+    return this.request<any>('DELETE', `/crm/deals/${id}`);
+  }
+
+  // ── CRM: Contacts ──
+
+  async listContacts(filters?: Record<string, string>) {
+    const params = filters ? '?' + new URLSearchParams(filters).toString() : '';
+    return this.request<any>('GET', `/crm/contacts${params}`);
+  }
+
+  async getContact(id: string) {
+    return this.request<any>('GET', `/crm/contacts/${id}`);
+  }
+
+  async createContact(data: Record<string, unknown>) {
+    return this.request<any>('POST', '/crm/contacts', data);
+  }
+
+  async updateContact(id: string, data: Record<string, unknown>) {
+    return this.request<any>('PATCH', `/crm/contacts/${id}`, data);
+  }
+
+  // ── CRM: Accounts ──
+
+  async listAccounts(filters?: Record<string, string>) {
+    const params = filters ? '?' + new URLSearchParams(filters).toString() : '';
+    return this.request<any>('GET', `/crm/accounts${params}`);
+  }
+
+  async getAccount(id: string) {
+    return this.request<any>('GET', `/crm/accounts/${id}`);
+  }
+
+  async createAccount(data: Record<string, unknown>) {
+    return this.request<any>('POST', '/crm/accounts', data);
+  }
+
+  async updateAccount(id: string, data: Record<string, unknown>) {
+    return this.request<any>('PATCH', `/crm/accounts/${id}`, data);
+  }
+
+  // ── CRM: Tickets ──
+
+  async listTickets(filters?: Record<string, string>) {
+    const params = filters ? '?' + new URLSearchParams(filters).toString() : '';
+    return this.request<any>('GET', `/crm/tickets${params}`);
+  }
+
+  async getTicket(id: string) {
+    return this.request<any>('GET', `/crm/tickets/${id}`);
+  }
+
+  async createTicket(data: Record<string, unknown>) {
+    return this.request<any>('POST', '/crm/tickets', data);
+  }
+
+  async updateTicket(id: string, data: Record<string, unknown>) {
+    return this.request<any>('PATCH', `/crm/tickets/${id}`, data);
+  }
+
+  // ── CRM: Tasks ──
+
+  async listTasks(filters?: Record<string, string>) {
+    const params = filters ? '?' + new URLSearchParams(filters).toString() : '';
+    return this.request<any>('GET', `/crm/tasks${params}`);
+  }
+
+  async createTask(data: Record<string, unknown>) {
+    return this.request<any>('POST', '/crm/tasks', data);
+  }
+
+  async completeTask(id: string) {
+    return this.request<any>('PATCH', `/crm/tasks/${id}/complete`);
+  }
+
+  // ── CRM: Pipelines ──
+
+  async listPipelines() {
+    return this.request<any>('GET', '/crm/pipelines');
+  }
+
+  // ── Messaging ──
+
+  async sendMessage(to: string, body: string, channel = 'whatsapp') {
+    return this.request<any>('POST', '/messages', { to, body, channel });
+  }
+
+  async sendTemplate(to: string, templateId: string, params?: Record<string, string>) {
+    return this.request<any>('POST', '/messages/templates', { to, template_id: templateId, params });
+  }
+
+  async listConversations(filters?: Record<string, string>) {
+    const params = filters ? '?' + new URLSearchParams(filters).toString() : '';
+    return this.request<any>('GET', `/conversations${params}`);
+  }
+
+  async listMessages(conversationId: string, limit = 20) {
+    return this.request<any>('GET', `/conversations/${conversationId}/messages?limit=${limit}`);
+  }
+
+  // ── Voice ──
+
+  async listCalls(filters?: Record<string, string>) {
+    const params = filters ? '?' + new URLSearchParams(filters).toString() : '';
+    return this.request<any>('GET', `/calls${params}`);
+  }
+
+  async getCallTranscript(callId: string) {
+    return this.request<any>('GET', `/calls/${callId}/transcript`);
+  }
+}

package/src/index.ts

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+
+/**
+ * Mirlo MCP Server
+ *
+ * Exposes Mirlo CRM, Messaging, and Voice as MCP tools
+ * for use with Claude, GPT, and other LLM clients.
+ *
+ * Usage:
+ *   npx @mirlo/mcp --api-key=sk_live_xxx
+ *   MIRLO_API_KEY=sk_live_xxx npx @mirlo/mcp
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { MirloClient } from './client.js';
+import { ALL_TOOLS } from './tools.js';
+
+// ── Parse API key ──
+
+function getApiKey(): string {
+  // From CLI arg: --api-key=xxx
+  const cliArg = process.argv.find(a => a.startsWith('--api-key='));
+  if (cliArg) return cliArg.split('=')[1];
+
+  // From env
+  if (process.env.MIRLO_API_KEY) return process.env.MIRLO_API_KEY;
+
+  console.error('Error: API key required. Use --api-key=sk_live_xxx or set MIRLO_API_KEY env var.');
+  console.error('Get your API key at: app.mirlo.com → Mi Organización → API Keys');
+  process.exit(1);
+  return ''; // unreachable, satisfies TS
+}
+
+function getBaseUrl(): string {
+  const cliArg = process.argv.find(a => a.startsWith('--base-url='));
+  if (cliArg) return cliArg.split('=')[1];
+  return process.env.MIRLO_BASE_URL || 'https://api.mirlo.com/v1';
+}
+
+// ── Main ──
+
+async function main() {
+  const apiKey = getApiKey();
+  const baseUrl = getBaseUrl();
+  const client = new MirloClient(apiKey, baseUrl);
+
+  const server = new McpServer({
+    name: 'mirlo',
+    version: '1.0.0',
+    description: 'Mirlo CRM, Messaging & Voice — manage deals, contacts, tickets, tasks, send messages, and track calls.',
+  });
+
+  // Register all tools
+  for (const tool of ALL_TOOLS) {
+    server.tool(
+      tool.name,
+      tool.description,
+      tool.schema.shape,
+      async (args: any) => {
+        try {
+          const result = await tool.handler(client, args);
+          return {
+            content: [{
+              type: 'text' as const,
+              text: JSON.stringify(result, null, 2),
+            }],
+          };
+        } catch (error: any) {
+          return {
+            content: [{
+              type: 'text' as const,
+              text: `Error: ${error.message}`,
+            }],
+            isError: true,
+          };
+        }
+      },
+    );
+  }
+
+  // Start stdio transport
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch(err => {
+  console.error('Fatal:', err);
+  process.exit(1);
+});

package/src/tools.ts

@@ -0,0 +1,328 @@
+/**
+ * MCP Tool definitions for Mirlo CRM, Messaging, and Voice.
+ */
+
+import { z } from 'zod';
+import type { MirloClient } from './client.js';
+
+// ── Tool definition type ──
+
+export interface ToolDef {
+  name: string;
+  description: string;
+  schema: z.ZodObject<any>;
+  handler: (client: MirloClient, args: any) => Promise<any>;
+}
+
+// ── CRM: Deals ──
+
+const listDeals: ToolDef = {
+  name: 'mirlo_list_deals',
+  description: 'List deals/opportunities with optional filters. Returns paginated results with total count.',
+  schema: z.object({
+    search: z.string().optional().describe('Search by deal name'),
+    pipeline_id: z.string().optional().describe('Filter by pipeline UUID'),
+    stage_id: z.string().optional().describe('Filter by stage UUID'),
+    status: z.enum(['open', 'won', 'lost']).optional().describe('Filter by status'),
+    owner_id: z.string().optional().describe('Filter by owner member UUID'),
+    account_id: z.string().optional().describe('Filter by account UUID'),
+    amount_min: z.number().optional().describe('Minimum deal amount'),
+    amount_max: z.number().optional().describe('Maximum deal amount'),
+    min_stage_hours: z.number().optional().describe('Minimum hours in current stage'),
+    max_stage_hours: z.number().optional().describe('Maximum hours in current stage'),
+    product_id: z.string().optional().describe('Filter by product UUID'),
+    currency: z.string().optional().describe('Filter by currency code (MXN, USD, etc.)'),
+    expected_close_before: z.string().optional().describe('Close date before (YYYY-MM-DD) — deals closing before this date'),
+    expected_close_after: z.string().optional().describe('Close date after (YYYY-MM-DD) — deals closing after this date'),
+    created_after: z.string().optional().describe('Created after (YYYY-MM-DD)'),
+    created_before: z.string().optional().describe('Created before (YYYY-MM-DD)'),
+    sort_by: z.string().optional().describe('Sort by field: amount, created_at, expected_close_date, name'),
+    sort_dir: z.enum(['asc', 'desc']).optional().describe('Sort direction'),
+    limit: z.number().optional().default(20).describe('Max results (default 20)'),
+    offset: z.number().optional().default(0).describe('Pagination offset'),
+  }),
+  handler: async (client, args) => client.listDeals(args),
+};
+
+const createDeal: ToolDef = {
+  name: 'mirlo_create_deal',
+  description: 'Create a new deal/opportunity in a pipeline.',
+  schema: z.object({
+    name: z.string().describe('Deal name'),
+    pipeline_id: z.string().describe('Pipeline UUID'),
+    stage_id: z.string().describe('Initial stage UUID'),
+    amount: z.number().optional().describe('Deal amount'),
+    currency: z.string().optional().default('MXN').describe('Currency code (default MXN)'),
+    owner_id: z.string().optional().describe('Owner member UUID'),
+    account_id: z.string().optional().describe('Account UUID'),
+    expected_close_date: z.string().optional().describe('Expected close date (YYYY-MM-DD)'),
+  }),
+  handler: async (client, args) => client.createDeal(args),
+};
+
+const updateDeal: ToolDef = {
+  name: 'mirlo_update_deal',
+  description: 'Update an existing deal. Only provided fields are updated.',
+  schema: z.object({
+    deal_id: z.string().describe('Deal UUID'),
+    name: z.string().optional(),
+    amount: z.number().optional(),
+    owner_id: z.string().optional(),
+    account_id: z.string().optional(),
+    status: z.enum(['open', 'won', 'lost']).optional(),
+    expected_close_date: z.string().optional(),
+  }),
+  handler: async (client, { deal_id, ...data }) => client.updateDeal(deal_id, data),
+};
+
+const moveDealStage: ToolDef = {
+  name: 'mirlo_move_deal_stage',
+  description: 'Move a deal to a different pipeline stage.',
+  schema: z.object({
+    deal_id: z.string().describe('Deal UUID'),
+    stage_id: z.string().describe('Target stage UUID'),
+  }),
+  handler: async (client, args) => client.moveDealStage(args.deal_id, args.stage_id),
+};
+
+const getDeal: ToolDef = {
+  name: 'mirlo_get_deal',
+  description: 'Get a deal by ID with full details including stage times, contacts, and conversations.',
+  schema: z.object({
+    deal_id: z.string().describe('Deal UUID'),
+  }),
+  handler: async (client, args) => client.getDeal(args.deal_id),
+};
+
+// ── CRM: Contacts ──
+
+const listContacts: ToolDef = {
+  name: 'mirlo_list_contacts',
+  description: 'List contacts with optional search and filters.',
+  schema: z.object({
+    search: z.string().optional().describe('Search by name, email, or phone'),
+    owner_id: z.string().optional().describe('Filter by owner'),
+    account_id: z.string().optional().describe('Filter by account'),
+    label_ids: z.string().optional().describe('Comma-separated label UUIDs'),
+    lifecycle_stage: z.string().optional().describe('lead, customer, partner, vendor, other'),
+    source_address: z.string().optional().describe('Filter by source phone/channel address'),
+    limit: z.number().optional().default(20),
+    offset: z.number().optional().default(0),
+  }),
+  handler: async (client, args) => client.listContacts(args),
+};
+
+const createContact: ToolDef = {
+  name: 'mirlo_create_contact',
+  description: 'Create a new contact.',
+  schema: z.object({
+    full_name: z.string().describe('Full name'),
+    first_name: z.string().optional(),
+    last_name: z.string().optional(),
+    primary_email: z.string().optional().describe('Email address'),
+    primary_phone: z.string().optional().describe('Phone number'),
+    account_id: z.string().optional().describe('Account UUID to link'),
+  }),
+  handler: async (client, args) => client.createContact(args),
+};
+
+const getContact: ToolDef = {
+  name: 'mirlo_get_contact',
+  description: 'Get a contact by ID.',
+  schema: z.object({ contact_id: z.string().describe('Contact UUID') }),
+  handler: async (client, args) => client.getContact(args.contact_id),
+};
+
+// ── CRM: Accounts ──
+
+const listAccounts: ToolDef = {
+  name: 'mirlo_list_accounts',
+  description: 'List accounts/companies with optional filters.',
+  schema: z.object({
+    search: z.string().optional().describe('Search by name or domain'),
+    industry: z.string().optional(),
+    lifecycle_stage: z.string().optional().describe('lead, customer, partner, vendor, other'),
+    owner_id: z.string().optional().describe('Filter by owner member UUID'),
+    source: z.string().optional().describe('manual, import, api, whatsapp, flow'),
+    city: z.string().optional(),
+    country: z.string().optional(),
+    limit: z.number().optional().default(20),
+    offset: z.number().optional().default(0),
+  }),
+  handler: async (client, args) => client.listAccounts(args),
+};
+
+const createAccount: ToolDef = {
+  name: 'mirlo_create_account',
+  description: 'Create a new account/company.',
+  schema: z.object({
+    name: z.string().describe('Company name'),
+    domain: z.string().optional().describe('Company domain'),
+    industry: z.string().optional(),
+    phone: z.string().optional(),
+    email: z.string().optional(),
+    city: z.string().optional(),
+    country: z.string().optional(),
+  }),
+  handler: async (client, args) => client.createAccount(args),
+};
+
+// ── CRM: Tickets ──
+
+const listTickets: ToolDef = {
+  name: 'mirlo_list_tickets',
+  description: 'List support tickets with filters.',
+  schema: z.object({
+    search: z.string().optional().describe('Search by title or reference'),
+    state: z.enum(['new', 'waiting_on_agent', 'waiting_on_customer', 'on_hold', 'closed']).optional().describe('Filter by specific state'),
+    exclude_closed: z.boolean().optional().describe('Set to true to get only open tickets (excludes closed)'),
+    priority: z.enum(['low', 'normal', 'high', 'urgent']).optional(),
+    owner_id: z.string().optional().describe('Filter by assignee'),
+    project_id: z.string().optional().describe('Filter by project UUID'),
+    source: z.enum(['channel', 'api', 'manual', 'form', 'automation']).optional(),
+    channel: z.string().optional().describe('whatsapp, voice, email, webchat, sms'),
+    account_id: z.string().optional().describe('Filter by account'),
+    limit: z.number().optional().default(20),
+    offset: z.number().optional().default(0),
+  }),
+  handler: async (client, args) => client.listTickets(args),
+};
+
+const createTicket: ToolDef = {
+  name: 'mirlo_create_ticket',
+  description: 'Create a support ticket.',
+  schema: z.object({
+    title: z.string().describe('Ticket title'),
+    body_html: z.string().optional().describe('Ticket description'),
+    priority: z.enum(['low', 'normal', 'high', 'urgent']).optional().default('normal'),
+    owner_id: z.string().optional().describe('Assignee member UUID'),
+  }),
+  handler: async (client, args) => client.createTicket({ ...args, source: 'api' }),
+};
+
+// ── CRM: Tasks ──
+
+const listTasks: ToolDef = {
+  name: 'mirlo_list_tasks',
+  description: 'List tasks with filters. Supports filtering by assignee, status, due date, and associated entities.',
+  schema: z.object({
+    owner_id: z.string().optional().describe('Filter by assignee'),
+    is_completed: z.boolean().optional().describe('true=completed, false=pending'),
+    type: z.enum(['to_do', 'call', 'email', 'meeting', 'follow_up']).optional(),
+    priority: z.enum(['low', 'normal', 'high', 'urgent']).optional(),
+    due_before: z.string().optional().describe('Due date before (YYYY-MM-DD) — tasks due before this date'),
+    due_after: z.string().optional().describe('Due date after (YYYY-MM-DD) — tasks due after this date'),
+    overdue: z.boolean().optional().describe('Only overdue tasks'),
+    deal_id: z.string().optional(),
+    ticket_id: z.string().optional(),
+    contact_id: z.string().optional(),
+    account_id: z.string().optional(),
+    search: z.string().optional().describe('Search by title'),
+    limit: z.number().optional().default(20),
+  }),
+  handler: async (client, args) => client.listTasks(args),
+};
+
+const createTask: ToolDef = {
+  name: 'mirlo_create_task',
+  description: 'Create a task, optionally associated to a deal, ticket, contact, or account.',
+  schema: z.object({
+    title: z.string().describe('Task title'),
+    type: z.enum(['to_do', 'call', 'email', 'meeting', 'follow_up']).optional().default('to_do'),
+    priority: z.enum(['low', 'normal', 'high', 'urgent']).optional().default('normal'),
+    due_date: z.string().optional().describe('Due date ISO 8601'),
+    owner_id: z.string().optional().describe('Assignee member UUID'),
+    deal_id: z.string().optional(),
+    ticket_id: z.string().optional(),
+    contact_id: z.string().optional(),
+    notes: z.string().optional(),
+  }),
+  handler: async (client, args) => client.createTask(args),
+};
+
+const completeTask: ToolDef = {
+  name: 'mirlo_complete_task',
+  description: 'Mark a task as completed.',
+  schema: z.object({ task_id: z.string().describe('Task UUID') }),
+  handler: async (client, args) => client.completeTask(args.task_id),
+};
+
+// ── CRM: Pipelines ──
+
+const listPipelines: ToolDef = {
+  name: 'mirlo_list_pipelines',
+  description: 'List all pipelines with their stages. Useful for getting pipeline/stage IDs before creating deals.',
+  schema: z.object({}),
+  handler: async (client) => client.listPipelines(),
+};
+
+// ── Messaging ──
+
+const sendMessage: ToolDef = {
+  name: 'mirlo_send_message',
+  description: 'Send a WhatsApp or SMS message to a phone number.',
+  schema: z.object({
+    to: z.string().describe('Recipient phone number (E.164 format)'),
+    body: z.string().describe('Message text'),
+    channel: z.enum(['whatsapp', 'sms']).optional().default('whatsapp'),
+  }),
+  handler: async (client, args) => client.sendMessage(args.to, args.body, args.channel),
+};
+
+const sendTemplate: ToolDef = {
+  name: 'mirlo_send_template',
+  description: 'Send a pre-approved WhatsApp template message.',
+  schema: z.object({
+    to: z.string().describe('Recipient phone number'),
+    template_id: z.string().describe('Template ID'),
+    params: z.record(z.string(), z.string()).optional().describe('Template parameters'),
+  }),
+  handler: async (client, args) => client.sendTemplate(args.to, args.template_id, args.params),
+};
+
+const listConversations: ToolDef = {
+  name: 'mirlo_list_conversations',
+  description: 'List recent conversations across channels.',
+  schema: z.object({
+    status: z.string().optional().describe('Filter by status'),
+    limit: z.number().optional().default(20),
+  }),
+  handler: async (client, args) => client.listConversations(args),
+};
+
+// ── Voice ──
+
+const listCalls: ToolDef = {
+  name: 'mirlo_list_calls',
+  description: 'List phone calls with filters.',
+  schema: z.object({
+    direction: z.enum(['inbound', 'outbound']).optional(),
+    limit: z.number().optional().default(20),
+  }),
+  handler: async (client, args) => client.listCalls(args as any),
+};
+
+const getCallTranscript: ToolDef = {
+  name: 'mirlo_get_call_transcript',
+  description: 'Get the AI-generated transcript of a phone call.',
+  schema: z.object({
+    call_id: z.string().describe('Call UUID'),
+  }),
+  handler: async (client, args) => client.getCallTranscript(args.call_id),
+};
+
+// ── Export all tools ──
+
+export const ALL_TOOLS: ToolDef[] = [
+  // CRM
+  listDeals, getDeal, createDeal, updateDeal, moveDealStage,
+  listContacts, getContact, createContact,
+  listAccounts, createAccount,
+  listTickets, createTicket,
+  listTasks, createTask, completeTask,
+  listPipelines,
+  // Messaging
+  sendMessage, sendTemplate, listConversations,
+  // Voice
+  listCalls, getCallTranscript,
+];

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*"]
+}