@app-connect/core 1.7.10 → 1.7.12

package/mcp/tools/findContactByPhone.js

@@ -0,0 +1,101 @@
+const jwt = require('../../lib/jwt');
+const connectorRegistry = require('../../connector/registry');
+const contactCore = require('../../handlers/contact');
+
+/**
+ * MCP Tool: Find Contact
+ * 
+ * This tool searches for a contact in the CRM platform by phone number.
+ * It uses the platform-specific connector to find matching contacts.
+ */
+
+const toolDefinition = {
+    name: 'findContactByPhone',
+    description: '⚠️ REQUIRES AUTHENTICATION: User must first authenticate using the "auth" tool to obtain a JWT token before using this tool. | Search for a contact in the CRM platform by phone number. Returns contact details if found.',
+    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.'
+            },
+            phoneNumber: {
+                type: 'string',
+                description: 'Phone number to search for, if not in E.164 format, convert it to E.164 format'
+            },
+            overridingFormat: {
+                type: 'string',
+                description: 'Overriding format to search for'
+            },
+            isExtension: {
+                type: 'boolean',
+                description: 'Whether the request is from an extension'
+            }
+        },
+        required: ['jwtToken', 'phoneNumber']
+    },
+    annotations: {
+        readOnlyHint: true,
+        openWorldHint: true,
+        destructiveHint: false
+    }
+};
+
+/**
+ * Execute the findContactByPhone tool
+ * @param {Object} args - The tool arguments
+ * @param {string} args.jwtToken - JWT token with user and platform info
+ * @param {string} [args.phoneNumber] - Phone number to search for
+ * @param {string} [args.overridingFormat] - Overriding format to search for
+ * @param {string} [args.isExtension] - Whether the request is from an extension
+ * @returns {Object} Result object with contact information
+ */
+async function execute(args) {
+    try {
+        const { jwtToken, phoneNumber, overridingFormat, isExtension } = args;
+
+        // 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 findContactByPhone is implemented
+        if (!platformModule.findContact) {
+            throw new Error(`findContactByPhone is not implemented for platform: ${platform}`);
+        }
+
+        // Call the findContactByPhone method
+        const { successful, returnMessage, contact } = await contactCore.findContact({ platform, userId, phoneNumber, overridingFormat: overridingFormat ?? '', isExtension: isExtension ?? false });
+        if (successful) {
+            return {
+                success: true,
+                data: contact,
+            };
+        }
+        else {
+            return {
+                success: false,
+                error: returnMessage.message,
+            };
+        }
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error.message || 'Unknown error occurred',
+            errorDetails: error.stack
+        };
+    }
+}
+
+exports.definition = toolDefinition;
+exports.execute = execute;

package/mcp/tools/getCallLog.js

@@ -0,0 +1,98 @@
+const jwt = require('../../lib/jwt');
+const connectorRegistry = require('../../connector/registry');
+const logCore = require('../../handlers/log');
+
+/**
+ * MCP Tool: Get Call Log
+ * 
+ * This tool retrieves call logs from the CRM platform by session IDs.
+ */
+
+const toolDefinition = {
+    name: 'getCallLog',
+    description: '⚠️ REQUIRES AUTHENTICATION: User must first authenticate using the "auth" tool to obtain a JWT token before using this tool. | Get call logs from the CRM platform by session IDs. Returns log details if found.',
+    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.'
+            },
+            sessionIds: {
+                type: 'string',
+                description: 'Session IDs to retrieve, seprated by commas'
+            },
+            requireDetails: {
+                type: 'boolean',
+                description: 'Whether to require detailed log information. If true, will call CRM API. Otherwise will just query in our own database',
+                default: false
+            }
+        },
+        required: ['jwtToken', 'sessionIds']
+    }
+};
+
+/**
+ * Execute the getCallLog tool
+ * @param {Object} args - The tool arguments
+ * @param {string} args.jwtToken - JWT token with user and platform info
+ * @param {string} args.sessionIds - Session IDs to retrieve, seprated by commas
+ * @param {boolean} [args.requireDetails] - Whether to require detailed log information. If true, will call CRM API. Otherwise will just query in our own database.
+ * @returns {Object} Result object with call log information
+ */
+async function execute(args) {
+    try {
+        const { jwtToken, sessionIds, requireDetails = false } = args;
+
+        // 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 getCallLog is implemented
+        if (!platformModule.getCallLog) {
+            throw new Error(`getCallLog is not implemented for platform: ${platform}`);
+        }
+
+        // Call the getCallLog method
+        const { successful, logs, returnMessage } = await logCore.getCallLog({ 
+            userId, 
+            sessionIds, 
+            platform, 
+            requireDetails 
+        });
+        
+        if (successful) {
+            return {
+                success: true,
+                data: logs,
+            };
+        }
+        else {
+            return {
+                success: false,
+                error: returnMessage.message,
+            };
+        }
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error.message || 'Unknown error occurred',
+            errorDetails: error.stack
+        };
+    }
+}
+
+exports.definition = toolDefinition;
+exports.execute = execute;
+

package/mcp/tools/getGoogleFilePicker.js

@@ -0,0 +1,103 @@
+const jwt = require('../../lib/jwt');
+const { UserModel } = require('../../models/userModel');
+const axios = require('axios');
+
+/**
+ * MCP Tool: Get Google File Picker
+ * 
+ * Returns the URL for the Google Sheets file picker.
+ * The user must visit this URL in a browser to select a Google Sheet.
+ */
+
+const toolDefinition = {
+    name: 'getGoogleFilePicker',
+    description: '⚠️ REQUIRES AUTHENTICATION: User must first authenticate with googleSheets platform. | Returns a URL for the Google Sheets file picker (1st preference) OR create a new sheet with input sheet name (2nd preference). The user should open this URL in their browser to select a Google Sheet for logging.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            jwtToken: {
+                type: 'string',
+                description: 'JWT token obtained from authentication. If user does not have this, direct them to use the "doAuth" tool first with googleSheets platform.'
+            },
+            sheetName: {
+                type: 'string',
+                description: 'OPTIONAL. Name of the new sheet to create.'
+            }
+        },
+        required: ['jwtToken']
+    },
+    annotations: {
+        readOnlyHint: false,
+        openWorldHint: true,
+        destructiveHint: false
+    }
+};
+
+/**
+ * Execute the getGoogleFilePicker tool
+ * @param {Object} args - The tool arguments
+ * @param {string} args.jwtToken - JWT token containing userId
+ * @param {string} args.sheetName - Name of the new sheet to create
+ * @returns {Object} Result object with file picker URL
+ */
+async function execute(args) {
+    try {
+        const { jwtToken, sheetName } = args;
+
+        if (!jwtToken) {
+            return {
+                success: false,
+                error: 'JWT token is required. Please authenticate with googleSheets platform first using the doAuth tool.'
+            };
+        }
+
+        // Decode JWT to get userId
+        const unAuthData = jwt.decodeJwt(jwtToken);
+
+        if (!unAuthData?.id) {
+            return {
+                success: false,
+                error: 'Invalid JWT token: userId not found'
+            };
+        }
+
+        // Find the user
+        const user = await UserModel.findByPk(unAuthData.id);
+
+        if (!user) {
+            return {
+                success: false,
+                error: 'User not found. Please authenticate with googleSheets platform first.'
+            };
+        }
+
+
+        if (sheetName) {
+            const createSheetResponse = await axios.post(`${process.env.APP_SERVER}/googleSheets/sheet?jwtToken=${jwtToken}`, { name: sheetName });
+            return createSheetResponse.data;
+        }
+        else {
+            // Generate the file picker URL
+            const filePickerUrl = `${process.env.APP_SERVER}/googleSheets/filePicker?token=${jwtToken}}`;
+
+            return {
+                success: true,
+                data: {
+                    filePickerUrl,
+                    message: 'Please open this URL in a browser to select a Google Sheet. After selecting a sheet, it will be configured for logging your calls and messages.'
+                }
+            };
+        }
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error.message || 'Unknown error occurred',
+            errorDetails: error.stack
+        };
+    }
+}
+
+exports.definition = toolDefinition;
+exports.execute = execute;
+

package/mcp/tools/getHelp.js

@@ -0,0 +1,44 @@
+/**
+ * MCP Tool: Get Help
+ * 
+ * This tool provides users with a friendly guide to available capabilities
+ * and how to get started with the RingCentral CRM integration.
+ */
+
+const toolDefinition = {
+    name: 'getHelp',
+    description: 'Get a quick guide on what this integration can do and how to get started.',
+    inputSchema: {
+        type: 'object',
+        properties: {},
+        required: []
+    },
+    annotations: {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false
+    }
+};
+
+/**
+ * Execute the getHelp tool
+ * @returns {Object} Result object with help information
+ */
+async function execute() {
+    return {
+        success: true,
+        data: {
+            overview: "I help you connect RingCentral with your CRM to log calls.",
+            steps:[
+                '1. Tell me to show all connectors and let me connect you to your CRM',
+                '2. Follow authorization flow to authorize your CRM',
+                '3. Once authorized, I can help find contacts and log your calls'
+            ],
+            supportedCRMs: ["Clio", "Google Sheets"],
+        }
+    };
+}
+
+exports.definition = toolDefinition;
+exports.execute = execute;
+

package/mcp/tools/getPublicConnectors.js

@@ -0,0 +1,53 @@
+const developerPortal = require('../../connector/developerPortal');
+
+/**
+ * MCP Tool: Get Public Connectors
+ * 
+ * This tool retrieves a list of public connectors from the developer portal.
+ */
+
+const toolDefinition = {
+    name: 'getPublicConnectors',
+    description: 'Auth flow step.1. Get a list of all available connectors from the developer portal. Returns a list of connector names for users to choose. Next step is calling step.2 "setConnector" tool.',
+    inputSchema: {
+        type: 'object',
+        properties: {},
+        required: []
+    },
+    annotations: {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false
+    }
+};
+
+const supportedPlatforms = ['googleSheets','clio'];
+
+/**
+ * Execute the getPublicConnectors tool
+ * @returns {Object} Result object with connector names
+ */
+async function execute() {
+    try {
+        const { connectors: publicConnectorList } = await developerPortal.getPublicConnectorList();
+        const connectorList = publicConnectorList;
+        if(process.env.RC_ACCOUNT_ID) {
+            const { privateConnectors } = await developerPortal.getPrivateConnectorList();
+            connectorList.push(...privateConnectors);
+        }
+        return {
+            success: true,
+            data: connectorList.filter(c => supportedPlatforms.includes(c.name)).map(c => c.displayName)
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error.message || 'Unknown error occurred',
+            errorDetails: error.stack
+        };
+    }
+}
+
+exports.definition = toolDefinition;
+exports.execute = execute;

package/mcp/tools/index.js

@@ -0,0 +1,64 @@
+/**
+ * MCP Tools Index
+ * 
+ * This file exports all available MCP tools for the RC Unified CRM Extension.
+ */
+
+// const auth = require('./auth');
+const getHelp = require('./getHelp');
+const getPublicConnectors = require('./getPublicConnectors');
+const setConnector = require('./setConnector');
+const collectAuthInfo = require('./collectAuthInfo');
+const doAuth = require('./doAuth');
+const checkAuthStatus = require('./checkAuthStatus');
+const logout = require('./logout');
+const findContact = require('./findContactByPhone');
+const findContactWithName = require('./findContactByName');
+const getCallLog = require('./getCallLog');
+const createCallLog = require('./createCallLog');
+const updateCallLog = require('./updateCallLog');
+const createMessageLog = require('./createMessageLog');
+const rcGetCallLogs = require('./rcGetCallLogs');
+const getGoogleFilePicker = require('./getGoogleFilePicker');
+const createContact = require('./createContact');
+
+// Export all tools
+module.exports = {
+    getHelp,
+    getPublicConnectors,
+    setConnector,
+    collectAuthInfo,
+    doAuth,
+    checkAuthStatus,
+    logout,
+    findContact,
+    findContactWithName,
+    //getCallLog,
+    createCallLog,
+    //updateCallLog,
+    //createMessageLog,
+    rcGetCallLogs,
+    getGoogleFilePicker,
+    createContact
+};
+
+// Export tools as an array for easy iteration
+module.exports.tools = [
+    getHelp,
+    getPublicConnectors,
+    setConnector,
+    collectAuthInfo,
+    doAuth,
+    checkAuthStatus,
+    logout,
+    findContact,
+    findContactWithName,
+    //getCallLog,
+    createCallLog,
+    //updateCallLog,
+    //createMessageLog,
+    rcGetCallLogs,
+    getGoogleFilePicker,
+    createContact
+];
+

package/mcp/tools/logout.js

@@ -0,0 +1,68 @@
+const jwt = require('../../lib/jwt');
+const { UserModel } = require('../../models/userModel');
+const connectorRegistry = require('../../connector/registry');
+
+/**
+ * MCP Tool: Logout
+ * 
+ * This tool logs out the user from the CRM platform.
+ */
+
+const toolDefinition = {
+    name: 'logout',
+    description: 'Logout the user from the CRM platform.',
+    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.'
+            }
+        }
+    },
+    annotations: {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: true
+    }
+};
+
+/**
+ * Execute the logout tool
+ * @param {Object} args - The tool arguments
+ * @param {string} args.jwtToken - JWT token containing userId and platform information. If user does not have this, direct them to use the "auth" tool first.
+ * @returns {Object} Result object with logout information
+ */
+async function execute(args) {
+    try {
+        const { jwtToken } = args;
+        const { platform, id } = jwt.decodeJwt(jwtToken);
+        
+        const userToLogout = await UserModel.findByPk(id);
+            if (!userToLogout) {
+            return {
+                success: false,
+                error: "User not found",
+                errorDetails: "User not found",
+            };
+        }
+        const platformModule = connectorRegistry.getConnector(platform);
+        await platformModule.unAuthorize({ user: userToLogout });
+        return {
+            success: true,
+            data: {
+                message: "IMPORTANT: Logout successful. Clear jwtToken, connectorManifest, connectorDisplayName, hostname and connectorName in memory. User is logged out from the CRM platform.",
+            }
+        }
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error.message || 'Unknown error occurred',
+            errorDetails: error.stack
+        };
+    }
+}
+
+exports.definition = toolDefinition;
+exports.execute = execute;

package/mcp/tools/rcGetCallLogs.js

@@ -0,0 +1,78 @@
+const { RingCentral } = require('../../lib/ringcentral');
+const jwt = require('../../lib/jwt');
+const { CallLogModel } = require('../../models/callLogModel');
+
+const toolDefinition = {
+    name: 'rcGetCallLogs',
+    description: '⚠️ REQUIRES AUTHENTICATION: User must first authenticate using the "auth" tool to obtain a JWT token before using this tool. | Get call logs from RingCentral',
+    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.'
+            },
+            timeFrom: {
+                type: 'string',
+                description: 'MUST be ISO string. Default is 24 hours ago.'
+            },
+            timeTo: {
+                type: 'string',
+                description: 'MUST be ISO string. Default is now.'
+            }
+        },
+        required: ['jwtToken', 'timeFrom', 'timeTo']
+    },
+    annotations: {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false
+    }
+}
+
+async function execute(args) {
+    try {
+        const { jwtToken, rcAccessToken, timeFrom, timeTo } = args;
+        if (!rcAccessToken) {
+            throw new Error('RingCentral access token not found');
+        }
+        const { id: userId } = jwt.decodeJwt(jwtToken);
+        if (!userId) {
+            throw new Error('Invalid JWT token: userId not found');
+        }
+        const rcSDK = new RingCentral({
+            server: process.env.RINGCENTRAL_SERVER,
+            clientId: process.env.RINGCENTRAL_CLIENT_ID,
+            clientSecret: process.env.RINGCENTRAL_CLIENT_SECRET,
+            redirectUri: `${process.env.APP_SERVER}/ringcentral/oauth/callback`
+        });
+        const callLogData = await rcSDK.getCallLogData({
+            token: { access_token: rcAccessToken, token_type: 'Bearer' },
+            timeFrom: timeFrom ?? new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString(),
+            timeTo: timeTo ?? new Date().toISOString(),
+        });
+        // hack: remove already logged calls
+        const existingCalls = [];
+        for (const call of callLogData.records) {
+            const existingCallLog = await CallLogModel.findOne({
+                where: {
+                    sessionId: call.sessionId
+                }
+            });
+            if (existingCallLog) {
+                existingCalls.push(existingCallLog.sessionId);
+            }
+        }
+        callLogData.records = callLogData.records.filter(call => !existingCalls.includes(call.sessionId));
+        return callLogData;
+    }
+    catch (e) {
+        return {
+            success: false,
+            error: e.message
+        }
+    }
+}
+
+exports.definition = toolDefinition;
+exports.execute = execute;

package/mcp/tools/setConnector.js

@@ -0,0 +1,69 @@
+const developerPortal = require('../../connector/developerPortal');
+
+/**
+ * MCP Tool: Set Connector
+ * 
+ * This tool helps the user set the connector.
+ */
+
+const toolDefinition = {
+    name: 'setConnector',
+    description: 'Auth flow step.2. Save connectorManifest to memory if successful.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            connectorDisplayName: {
+                type: 'string',
+                description: 'Connector displayname to set'
+            }
+        },
+        required: ['connectorDisplayName']
+    },
+    annotations: {
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false
+    }
+};
+
+/**
+ * Execute the setConnector tool
+ * @param {Object} args - The tool arguments
+ * @param {string} args.connectorDisplayName - Connector display name to set
+ * @returns {Object} Result object with connector information
+ */
+async function execute(args) {
+    try {
+        const { connectorDisplayName } = args;
+        const { connectors: publicConnectorList } = await developerPortal.getPublicConnectorList();
+        const { privateConnectors } = await developerPortal.getPrivateConnectorList();
+        const connectorList = [...publicConnectorList, ...privateConnectors];
+        const connector = connectorList.find(c => c.displayName === connectorDisplayName);
+        const connectorName = connector.name;
+        const connectorManifest = await developerPortal.getConnectorManifest({ connectorId: connector.id, isPrivate: connector.status === 'private' });
+        if (!connectorManifest) {
+            throw new Error(`Connector manifest not found: ${connectorDisplayName}`);
+        }
+        return {
+            success: true,
+            data: {
+                connectorManifest,
+                connectorDisplayName,
+                connectorName,
+                // Add explicit instruction
+                message: "IMPORTANT: Use connectorManifest, connectorDisplayName, and connectorName in the next few authentication steps. Call 'collectAuthInfo' tool if the connector is oauth, unless connectorManifest.platform[0].environment.type == 'fixed'.",
+                
+            }
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error.message || 'Unknown error occurred',
+            errorDetails: error.stack
+        };
+    }
+}
+
+exports.definition = toolDefinition;
+exports.execute = execute;