@app-connect/core 1.7.10 → 1.7.12

package/mcp/mcpHandler.js

@@ -0,0 +1,166 @@
+/**
+ * MCP Server for RC Unified CRM Extension
+ * 
+ * This module provides MCP (Model Context Protocol) interface for the CRM extension.
+ * It exposes tools that can be called by AI assistants or other MCP clients.
+ */
+
+const tools = require('./tools');
+const logger = require('../lib/logger');
+
+const JSON_RPC_INTERNAL_ERROR = -32603;
+const JSON_RPC_METHOD_NOT_FOUND = -32601;
+
+async function handleMcpRequest(req, res) {
+    try {
+        const { method, params, id } = req.body;
+        logger.info('Received MCP request:', { method });
+
+        let response;
+
+        switch (method) {
+            case 'initialize':
+                response = {
+                    jsonrpc: '2.0',
+                    id,
+                    result: {
+                        protocolVersion: '2024-11-05',
+                        capabilities: {
+                            tools: {},
+                            prompts: {}
+                        },
+                        serverInfo: {
+                            name: 'rc-unified-crm-extension',
+                            version: '1.0.0'
+                        }
+                    }
+                };
+                break;
+            case 'tools/list':
+                response = {
+                    jsonrpc: '2.0',
+                    id,
+                    result: {
+                        tools: getTools()
+                    }
+                };
+                break;
+            case 'tools/call':
+                const { name: toolName, arguments: args } = params;
+                const rcAccessToken = req.headers['authorization']?.split('Bearer ')?.[1];
+                if (args && rcAccessToken) {
+                    args.rcAccessToken = rcAccessToken;
+                }
+                try {
+                    const result = await executeTool(toolName, args || {});
+                    response = {
+                        jsonrpc: '2.0',
+                        id,
+                        result: {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: JSON.stringify(result, null, 2)
+                                }
+                            ]
+                        }
+                    };
+                } catch (toolError) {
+                    response = {
+                        jsonrpc: '2.0',
+                        id,
+                        error: {
+                            code: JSON_RPC_INTERNAL_ERROR,
+                            message: `Tool execution failed: ${toolError.message}`,
+                            data: {
+                                error: toolError.message,
+                                stack: process.env.NODE_ENV !== 'production' ? toolError.stack : undefined
+                            }
+                        }
+                    };
+                }
+                break;
+            case 'ping':
+                response = {
+                    jsonrpc: '2.0',
+                    id,
+                    result: {}
+                };
+                break;
+            default:
+                response = {
+                    jsonrpc: '2.0',
+                    id,
+                    error: {
+                        code: JSON_RPC_METHOD_NOT_FOUND,
+                        message: `Method not found: ${method}`
+                    }
+                };
+        }
+
+        res.status(200).json(response);
+    } catch (error) {
+        logger.error('Error handling MCP request:', { stack: error.stack });
+        const errorResponse = {
+            jsonrpc: '2.0',
+            id: req.body?.id || null,
+            error: {
+                code: JSON_RPC_INTERNAL_ERROR,
+                message: 'Internal server error',
+                data: {
+                    error: error.message,
+                    stack: process.env.NODE_ENV !== 'production' ? error.stack : undefined
+                }
+            }
+        };
+        res.status(200).json(errorResponse);
+    }
+}
+
+
+/**
+ * Get all registered MCP tools
+ * @returns {Array} Array of tool definitions
+ */
+function getTools() {
+    return tools.tools.map(tool => tool.definition);
+}
+
+/**
+ * Execute a specific MCP tool
+ * @param {string} toolName - Name of the tool to execute
+ * @param {Object} args - Arguments to pass to the tool
+ * @returns {Promise<Object>} Tool execution result
+ */
+async function executeTool(toolName, args) {
+    // Find the tool by name
+    const tool = tools.tools.find(t => t.definition.name === toolName);
+
+    if (!tool) {
+        throw new Error(`Tool not found: ${toolName}`);
+    }
+
+    // Execute the tool
+    return await tool.execute(args);
+}
+
+/**
+ * Get a specific tool definition
+ * @param {string} toolName - Name of the tool
+ * @returns {Object} Tool definition
+ */
+function getToolDefinition(toolName) {
+    const tool = tools.tools.find(t => t.definition.name === toolName);
+
+    if (!tool) {
+        throw new Error(`Tool not found: ${toolName}`);
+    }
+
+    return tool.definition;
+}
+
+exports.handleMcpRequest = handleMcpRequest;
+exports.getTools = getTools;
+exports.executeTool = executeTool;
+exports.getToolDefinition = getToolDefinition;
+exports.tools = tools.tools;

package/mcp/tools/checkAuthStatus.js

@@ -0,0 +1,110 @@
+const { getAuthSession } = require('../../lib/authSession');
+
+/**
+ * MCP Tool: Check Auth Status
+ * 
+ * Polls the status of an ongoing OAuth authentication session
+ */
+
+const toolDefinition = {
+    name: 'checkAuthStatus',
+    description: 'Auth flow step.5. Check the status of an ongoing OAuth authentication session. Poll this after user clicks the auth link.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            sessionId: {
+                type: 'string',
+                description: 'The session ID returned from doAuth tool'
+            },
+            platform: {
+                type: 'string',
+                description: 'The platform to check the status of'
+            }
+        },
+        required: ['sessionId']
+    },
+    annotations: {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false
+    }
+};
+
+/**
+ * Execute the checkAuthStatus tool
+ * @param {Object} args - The tool arguments
+ * @param {string} args.sessionId - The session ID to check
+ * @returns {Object} Result object with authentication status
+ */
+async function execute(args) {
+    try {
+        const { sessionId, platform } = args;
+        
+        const session = await getAuthSession(sessionId);
+        
+        if (!session) {
+            return {
+                success: false,
+                error: 'Session not found or expired',
+                data: {
+                    status: 'expired'
+                }
+            };
+        }
+        
+        switch (session.status) {
+            case 'completed':
+                if(platform === 'googleSheets') {
+                    return {
+                        success: true,
+                        data: {
+                            status: 'completed',
+                            jwtToken: session.jwtToken,
+                            userInfo: session.userInfo,
+                            message: 'IMPORTANT: Authentication successful! Keep jwtToken in memory for future use. DO NOT directly show it to user. Next step is to call getGoogleFilePicker tool.'
+                        }
+                    };
+                }
+                return {
+                    success: true,
+                    data: {
+                        status: 'completed',
+                        jwtToken: session.jwtToken,
+                        userInfo: session.userInfo,
+                        message: 'IMPORTANT: Authentication successful! Keep jwtToken in memory for future use. DO NOT directly show it to user.'
+                    }
+                };
+            
+            case 'failed':
+                return {
+                    success: false,
+                    error: 'Authentication failed',
+                    data: {
+                        status: 'failed',
+                        errorMessage: session.errorMessage
+                    }
+                };
+            
+            case 'pending':
+            default:
+                return {
+                    success: true,
+                    data: {
+                        status: 'pending',
+                        message: 'Waiting for user to complete authorization. Poll again in a few seconds.'
+                    }
+                };
+        }
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error.message || 'Unknown error occurred',
+            errorDetails: error.stack
+        };
+    }
+}
+
+exports.definition = toolDefinition;
+exports.execute = execute;
+

package/mcp/tools/collectAuthInfo.js

@@ -0,0 +1,91 @@
+/**
+ * MCP Tool: User Authentication
+ * 
+ * This tool authenticates the user with the CRM platform.
+ * It uses the platform-specific connector to authenticate the user.
+ */
+
+const { isManifestValid } = require('../lib/validator');
+
+const toolDefinition = {
+    name: 'collectAuthInfo',
+    description: '(This step is skipped if auth type is "apiKey" or environment type is "fixed", this is a MUST if environment type is "dynamic" or "selectable") Auth flow step.3. Get information that is required for authentication. Next step is calling step.4 "doAuth" tool.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            connectorManifest: {
+                type: 'object',
+                description: 'connectorManifest variable from above conversation. Must be the full manifest object, not just serverUrl'
+            },
+            hostname: {
+                type: 'string',
+                description: 'For "dynamic" type environment. User is to login to CRM account then copy and paste the hostname over here.'
+            },
+            selection: {
+                type: 'string',
+                description: 'For "selectable" type environment. User is to select a name (NOT value) of the options from the selectable list'
+            },
+            connectorName: {
+                type: 'string',
+                description: 'connectorName variable from above conversation.'
+            }
+        },
+        required: ['connectorManifest', 'connectorName']
+    },
+    annotations: {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false
+    }
+};
+
+/**
+ * Execute the collectAuthInfo tool
+ * @param {Object} args - The tool arguments
+ * @param {string} args.connectorManifest - Connector manifest from conversation or memory.
+ * @param {string} args.hostname - For "dynamic" type environment. User is to login to CRM account then copy and paste the hostname over here.
+ * @param {string} args.selection - For "selectable" type environment. User is to select a name (NOT value) of the options from the selectable list
+ * @param {string} args.connectorName - Connector name from conversation or memory.
+ * @returns {Object} Result object with hostname or selection
+ */
+async function execute(args) {
+    try {
+        const { connectorManifest, hostname, selection, connectorName } = args;
+        const { isValid, errors } = isManifestValid({ connectorManifest, connectorName });
+        if (!isValid) {
+            return {
+                success: false,
+                error: "Invalid connector manifest",
+                errorDetails: errors.join(', '),
+            }
+        }
+        let result = '';
+        switch (connectorManifest.platforms[connectorName].environment.type) {
+            case 'selectable':
+                result = connectorManifest.platforms[connectorName].environment.selections.find(s => s.name === selection).const;
+                break;
+            case 'dynamic':
+                result = hostname;
+                break;
+        }
+        const url = new URL(result);
+        return {
+            success: true,
+            data: {
+                hostname: url.hostname,
+                // Add explicit instruction
+                message: "IMPORTANT: Use hostname in the next few authentication steps.",
+            }
+        }
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error.message || 'Unknown error occurred',
+            errorDetails: error.stack
+        };
+    }
+}
+
+exports.definition = toolDefinition;
+exports.execute = execute;

package/mcp/tools/createCallLog.js

@@ -0,0 +1,308 @@
+const jwt = require('../../lib/jwt');
+const connectorRegistry = require('../../connector/registry');
+const logCore = require('../../handlers/log');
+const contactCore = require('../../handlers/contact');
+const util = require('../../lib/util');
+const { CallLogModel } = require('../../models/callLogModel');
+/**
+ * MCP Tool: Create Call Log
+ * 
+ * This tool creates a call log in the CRM platform.
+ */
+
+const toolDefinition = {
+    name: 'createCallLog',
+    description: '⚠️ REQUIRES AUTHENTICATION: User must first authenticate using the "auth" tool to obtain a JWT token before using this tool. | Create only one call log in the CRM platform. Returns the created log ID if successful.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            jwtToken: {
+                type: 'string',
+                description: 'JWT token containing userId and platform information. If user does not have this, direct them to use the "auth" tool first.'
+            },
+            incomingData: {
+                type: 'object',
+                description: 'Call log data to create',
+                properties: {
+                    logInfo: {
+                        type: 'object',
+                        description: 'RingCentral call log information (follows RingCentral Call Log schema)',
+                        properties: {
+                            id: {
+                                type: 'string',
+                                description: 'Call log ID from RingCentral'
+                            },
+                            sessionId: {
+                                type: 'string',
+                                description: 'Unique session identifier for the call'
+                            },
+                            telephonySessionId: {
+                                type: 'string',
+                                description: 'Telephony session ID'
+                            },
+                            startTime: {
+                                type: 'string',
+                                description: 'Call start time in ISO 8601 format'
+                            },
+                            duration: {
+                                type: 'number',
+                                description: 'Call duration in seconds'
+                            },
+                            type: {
+                                type: 'string',
+                                description: 'Call type (e.g., Voice)'
+                            },
+                            direction: {
+                                type: 'string',
+                                description: 'Call direction: "Inbound" or "Outbound"'
+                            },
+                            action: {
+                                type: 'string',
+                                description: 'Call action (e.g., Phone Call)'
+                            },
+                            result: {
+                                type: 'string',
+                                description: 'Call result (e.g., Accepted, Missed, Voicemail)'
+                            },
+                            to: {
+                                type: 'object',
+                                description: 'Recipient information',
+                                properties: {
+                                    phoneNumber: {
+                                        type: 'string',
+                                        description: 'Recipient phone number in E.164 format'
+                                    },
+                                    name: {
+                                        type: 'string',
+                                        description: 'Recipient name'
+                                    }
+                                }
+                            },
+                            from: {
+                                type: 'object',
+                                description: 'Caller information',
+                                properties: {
+                                    phoneNumber: {
+                                        type: 'string',
+                                        description: 'Caller phone number in E.164 format'
+                                    },
+                                    name: {
+                                        type: 'string',
+                                        description: 'Caller name'
+                                    },
+                                    location: {
+                                        type: 'string',
+                                        description: 'Caller location'
+                                    }
+                                }
+                            },
+                            recording: {
+                                type: 'object',
+                                description: 'Recording information',
+                                properties: {
+                                    link: {
+                                        type: 'string',
+                                        description: 'Recording link URL'
+                                    }
+                                }
+                            },
+                            customSubject: {
+                                type: 'string',
+                                description: 'Custom subject for the call log'
+                            },
+                            legs: {
+                                type: 'array',
+                                description: 'Call legs information (for multi-party calls)',
+                                items: {
+                                    type: 'object'
+                                }
+                            },
+                            accountId: {
+                                type: 'string',
+                                description: 'RingCentral account ID'
+                            }
+                        },
+                        required: ['id', 'sessionId', 'direction', 'startTime', 'duration', 'to', 'from']
+                    },
+                    note: {
+                        type: 'string',
+                        description: 'User-entered call note/description'
+                    },
+                    aiNote: {
+                        type: 'string',
+                        description: 'AI-generated summary of the phone call'
+                    },
+                    transcript: {
+                        type: 'string',
+                        description: 'Call transcript text'
+                    },
+                    additionalSubmission: {
+                        type: 'object',
+                        description: 'Additional platform-specific custom fields (e.g., deals, matters, nonBillable flags, assigned users)',
+                        properties: {
+                            isAssignedToUser: {
+                                type: 'boolean',
+                                description: 'Whether to assign to a specific user'
+                            },
+                            adminAssignedUserToken: {
+                                type: 'string',
+                                description: 'JWT token of the assigned user'
+                            },
+                            adminAssignedUserRcId: {
+                                type: 'string',
+                                description: 'RingCentral extension ID of the assigned user'
+                            }
+                        }
+                    }
+                },
+                required: ['logInfo']
+            },
+            contactId: {
+                type: 'string',
+                description: 'OPTIONAL: CRM contact ID to associate with the call.'
+            }
+        },
+        required: ['jwtToken', 'incomingData']
+    },
+    annotations: {
+        readOnlyHint: false,
+        openWorldHint: true,
+        destructiveHint: false
+    }
+};
+
+/**
+ * Execute the createCallLog tool
+ * @param {Object} args - The tool arguments
+ * @param {string} args.jwtToken - JWT token with user and platform info
+ * @param {Object} args.incomingData - Call log data including logInfo (RingCentral call log schema), contactName, contactType, note, aiNote, transcript, and additionalSubmission
+ * @param {Object} args.incomingData.logInfo - RingCentral call log information with sessionId, direction, startTime, duration, from, to, result, recording, customSubject, etc.
+ * @param {string} [args.incomingData.contactName] - Contact name
+ * @param {string} [args.incomingData.contactType] - Contact type in CRM
+ * @param {string} [args.incomingData.note] - User-entered call note
+ * @param {string} [args.incomingData.aiNote] - AI-generated call summary
+ * @param {string} [args.incomingData.transcript] - Call transcript
+ * @param {Object} [args.incomingData.additionalSubmission] - Platform-specific custom fields
+ * @param {string} args.contactId - OPTIONAL: CRM contact ID to associate with the call
+ * @returns {Object} Result object with created log ID
+ */
+async function execute(args) {
+    try {
+        const { jwtToken, incomingData } = args;
+
+        if (!jwtToken) {
+            throw new Error('Please go to Settings and authorize CRM platform');
+        }
+
+        if (!incomingData) {
+            throw new Error('Incoming data must be provided');
+        }
+
+        // Validate logInfo exists
+        if (!incomingData.logInfo) {
+            throw new Error('incomingData.logInfo is required');
+        }
+
+        const { logInfo } = incomingData;
+
+        // Check in DB if the call log already exists
+        const existingCallLog = await CallLogModel.findOne({
+            where: {
+                sessionId: logInfo.sessionId
+            }
+        });
+        if (existingCallLog) {
+            throw new Error(`Call log already exists for session ${logInfo.sessionId}`);
+        }
+
+        // Decode JWT to get userId and platform
+        const { id: userId, platform } = jwt.decodeJwt(jwtToken);
+
+        if (!userId) {
+            throw new Error('Invalid JWT token: userId not found');
+        }
+
+        // Get the platform connector module
+        const platformModule = connectorRegistry.getConnector(platform);
+
+        if (!platformModule) {
+            throw new Error(`Platform connector not found for: ${platform}`);
+        }
+
+        // Check if createCallLog is implemented
+        if (!platformModule.createCallLog) {
+            throw new Error(`createCallLog is not implemented for platform: ${platform}`);
+        }
+
+        // Calculate hashed account ID
+        const hashedAccountId = incomingData.logInfo?.accountId
+            ? util.getHashValue(incomingData.logInfo.accountId, process.env.HASH_KEY)
+            : undefined;
+
+        // Get contact Id from conversation
+        let contactId = args.contactId ?? null;
+        // Get contact Id from conversation if not provided
+        if (!contactId) {
+            const callDirection = logInfo.direction;
+            const contactNumber = callDirection === 'Inbound' ? logInfo.from.phoneNumber : logInfo.to.phoneNumber;
+            const contactInfo = await contactCore.findContact({
+                platform,
+                userId,
+                phoneNumber: contactNumber,
+                overridingFormat: '',
+                isExtension: 'false'
+            });
+            const filteredContact = contactInfo.contact?.filter(c => !c.isNewContact);
+            if (contactInfo.successful && filteredContact?.length > 0) {
+                contactId = filteredContact[0].id;
+                incomingData.contactId = contactId;
+            }
+            else {
+                return {
+                    success: false,
+                    message: 'Cannot find the contact. Please create the contact first.',
+                    error: 'Failed to get contact with number ' + contactNumber
+                }
+            }
+        }
+        else {
+            incomingData.contactId = contactId;
+        }
+
+        // Call the createCallLog method
+        const { successful, logId, returnMessage } = await logCore.createCallLog({
+            platform,
+            userId,
+            incomingData,
+            hashedAccountId,
+            isFromSSCL: false
+        });
+
+        if (successful) {
+            return {
+                success: true,
+                data: {
+                    logId,
+                    message: returnMessage?.message || 'Call log created successfully'
+                }
+            };
+        }
+        else {
+            return {
+                success: false,
+                error: returnMessage?.message || 'Failed to create call log',
+            };
+        }
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error.message || 'Unknown error occurred',
+            errorDetails: error.stack
+        };
+    }
+}
+
+exports.definition = toolDefinition;
+exports.execute = execute;
+