phone_make_call

Instructions

Implementation Reference

• operations/realtime-assistant.ts:45-106 (handler)

  Core handler function that executes the phone call logic: logs the initiation, calls the PhoneClient to make the call, manages active calls state, and handles errors.

  export async function makePhoneCall(request: PhoneCallRequest): Promise<{
    success: boolean;
    callId: string;
    message: string;
    estimatedDuration?: number;
  }> {
    const client = getPhoneClient();
    
    try {
      // Log de la invocación
      const log: SystemLog = {
        id: generateId(),
        timestamp: new Date().toISOString(),
        level: 'info',
        component: 'phone',
        action: 'initiate_call',
        details: {
          usuario: request.usuario,
          telefono: request.telefono,
          proposito: request.proposito,
          timeout: request.timeout,
          herramientasCount: request.herramientas.length
        }
      };
      systemLogs.push(log);
  
      // Invocar asistente telefónico
      const response = await client.makePhoneCall(request);
      
      // Registrar llamada activa
      const callStatus: CallStatus = {
        callId: response.callId,
        status: 'pending',
        startTime: new Date().toISOString(),
        lastUpdate: new Date().toISOString(),
        usuario: request.usuario,
        telefono: request.telefono,
        proposito: request.proposito
      };
      
      activeCalls.set(response.callId, callStatus);
      
      return response;
    } catch (error) {
      // Log del error
      const errorLog: SystemLog = {
        id: generateId(),
        timestamp: new Date().toISOString(),
        level: 'error',
        component: 'phone',
        action: 'initiate_call_failed',
        details: {
          error: error instanceof Error ? error.message : 'Unknown error',
          usuario: request.usuario,
          proposito: request.proposito
        }
      };
      systemLogs.push(errorLog);
      
      throw error;
    }
  }

• index.ts:22-49 (registration)

  MCP server tool registration for 'phone_make_call', including input schema with Zod and thin handler delegating to phoneTools.makePhoneCall.

    "phone_make_call",
    "Realizar una llamada telefónica conversacional automatizada",
    {
      usuario: z.string().describe("Nombre del usuario a llamar"),
      telefono: z.string().describe("Número de teléfono del usuario"),
      proposito: z.string().describe("Propósito específico de la llamada"),
      contexto: z.string().optional().describe("Contexto adicional sobre el tema a tratar"),
      timeout: z.number().optional().default(40).describe("Timeout de la llamada en segundos"),
      herramientas_personalizadas: z.string().optional().describe("Herramientas HTTP personalizadas en formato JSON")
    },
    async (args) => {
      const result = await phoneTools.makePhoneCall({
        usuario: args.usuario,
        telefono: args.telefono,
        proposito: args.proposito,
        contexto: args.contexto,
        timeout: args.timeout || 40,
        herramientas_personalizadas: args.herramientas_personalizadas
      });
  
      return {
        content: [{ 
          type: "text", 
          text: `📞 Llamada iniciada con ${args.usuario}\n\n**ID de llamada:** ${result.callId}\n**Mensaje:** ${result.message}\n**Duración estimada:** ${result.estimatedDuration || 'No estimada'} segundos`
        }],
      };
    }
  );

• types/realtime-assistant.ts:32-39 (schema)

  TypeScript interface defining the input schema for phone call requests (PhoneCallRequest).

  export interface PhoneCallRequest {
    usuario: string;
    telefono: string;
    timeout: number;
    proposito: string; // Para qué es la llamada
    contexto?: string; // Contexto adicional sobre el tema
    herramientas: HttpTool[]; // Tools que puede usar el asistente telefónico
  }

• tools/realtime-assistant.ts:13-96 (helper)

  Wrapper helper function that processes input arguments, adds default tools, parses custom tools, and delegates to phoneOps.makePhoneCall.

  export async function makePhoneCall(args: {
    usuario: string;
    telefono: string;
    proposito: string;
    contexto?: string;
    timeout?: number;
    herramientas_personalizadas?: string; // JSON string de herramientas adicionales
  }): Promise<{
    success: boolean;
    callId: string;
    message: string;
    estimatedDuration?: number;
  }> {
    const { usuario, telefono, proposito, contexto, herramientas_personalizadas } = args;
    const timeout = args.timeout || 40;
  
    // Parsear herramientas personalizadas si se proporcionan
    let herramientasPersonalizadas: HttpTool[] = [];
    if (herramientas_personalizadas) {
      try {
        herramientasPersonalizadas = JSON.parse(herramientas_personalizadas);
      } catch (error) {
        throw new Error(`Error al parsear herramientas personalizadas: ${error instanceof Error ? error.message : 'JSON inválido'}`);
      }
    }
  
    // Herramientas básicas conversacionales (mínimas)
    const herramientasBasicas: HttpTool[] = [
      // Herramienta para confirmar información obtenida
      {
        name: 'confirmar_informacion',
        description: 'Confirma información importante obtenida durante la conversación',
        endpoint: `${process.env.MCP_CALLBACK_URL || 'http://localhost:3000'}/api/phone/confirm-info`,
        method: 'POST',
        parameters: [
          {
            name: 'callId',
            type: 'string',
            description: 'ID de la llamada',
            required: true
          },
          {
            name: 'tipo_informacion',
            type: 'string',
            description: 'Tipo de información (contacto, cita, preferencia, etc.)',
            required: true
          },
          {
            name: 'datos',
            type: 'string',
            description: 'Datos confirmados en formato JSON',
            required: true
          },
          {
            name: 'usuario_confirmo',
            type: 'boolean',
            description: 'Si el usuario confirmó explícitamente',
            required: true
          }
        ],
        authentication: {
          type: 'api_key',
          header: 'X-MCP-API-Key',
          key: process.env.MCP_CALLBACK_API_KEY || 'mcp-default-key'
        }
      }
    ];
  
    // Combinar herramientas básicas con personalizadas
    const todasLasHerramientas = [...herramientasBasicas, ...herramientasPersonalizadas];
  
    // Construir request para el asistente telefónico
    const request: PhoneCallRequest = {
      usuario,
      telefono,
      timeout,
      proposito,
      contexto,
      herramientas: todasLasHerramientas
    };
  
    // Realizar llamada telefónica
    return await phoneOps.makePhoneCall(request);
  }