@app-connect/core 1.7.10 → 1.7.12

package/mcp/tools/createContact.js

@@ -0,0 +1,117 @@
+const jwt = require('../../lib/jwt');
+const connectorRegistry = require('../../connector/registry');
+const contactCore = require('../../handlers/contact');
+
+/**
+ * MCP Tool: Create Contact
+ * 
+ * This tool creates a new contact in the CRM platform.
+ */
+
+const toolDefinition = {
+    name: 'createContact',
+    description: '⚠️ REQUIRES AUTHENTICATION: User must first authenticate using the "auth" tool to obtain a JWT token before using this tool. | Create a new contact in the CRM platform. Returns the created contact information 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.'
+            },
+            phoneNumber: {
+                type: 'string',
+                description: 'Phone number of the new contact (MUST BE in E.164 format, e.g., +14155551234)'
+            },
+            newContactName: {
+                type: 'string',
+                description: 'Full name of the new contact. If not provided, use phone number as the name'
+            }
+        },
+        required: ['jwtToken', 'phoneNumber']
+    },
+    annotations: {
+        readOnlyHint: false,
+        openWorldHint: true,
+        destructiveHint: false
+    }
+};
+
+/**
+ * Execute the createContact tool
+ * @param {Object} args - The tool arguments
+ * @param {string} args.jwtToken - JWT token with user and platform info
+ * @param {string} args.phoneNumber - Phone number of the new contact
+ * @param {string} args.newContactName - Name of the new contact
+ * @returns {Object} Result object with created contact information
+ */
+async function execute(args) {
+    try {
+        const { jwtToken, phoneNumber, newContactName } = args;
+
+        if (!jwtToken) {
+            throw new Error('Please go to Settings and authorize CRM platform');
+        }
+
+        if (!phoneNumber) {
+            throw new Error('Phone number is required');
+        }
+
+        if (!newContactName) {
+            throw new Error('Contact name is required');
+        }
+
+        // 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 createContact is implemented
+        if (!platformModule.createContact) {
+            throw new Error(`createContact is not implemented for platform: ${platform}`);
+        }
+
+        // Call the createContact method
+        const { successful, returnMessage, contact } = await contactCore.createContact({
+            platform,
+            userId,
+            phoneNumber,
+            newContactName
+        });
+
+        if (successful) {
+            return {
+                success: true,
+                data: {
+                    contact,
+                    message: returnMessage?.message || 'Contact created successfully'
+                }
+            };
+        }
+        else {
+            return {
+                success: false,
+                error: returnMessage?.message || 'Failed to create contact'
+            };
+        }
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error.message || 'Unknown error occurred',
+            errorDetails: error.stack
+        };
+    }
+}
+
+exports.definition = toolDefinition;
+exports.execute = execute;
+

package/mcp/tools/createMessageLog.js

@@ -0,0 +1,283 @@
+const jwt = require('../../lib/jwt');
+const connectorRegistry = require('../../connector/registry');
+const logCore = require('../../handlers/log');
+
+/**
+ * MCP Tool: Create Message Log
+ * 
+ * This tool creates message logs in the CRM platform.
+ */
+
+const toolDefinition = {
+    name: 'createMessageLog',
+    description: '⚠️ REQUIRES AUTHENTICATION: User must first authenticate using the "auth" tool to obtain a JWT token before using this tool. | Create message logs in the CRM platform. Returns the created log IDs 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: 'Message log data including messages array with conversation info',
+                properties: {
+                    conversation: {
+                        type: 'object',
+                        description: 'Log info object. Sometimes it is named logInfo',
+                        properties: {
+                            messages: {
+                                type: 'array',
+                                description: 'Array of message objects to log',
+                                minItems: 1,
+                                items: {
+                                    type: 'object',
+                                    properties: {
+                                        id: {
+                                            type: 'string',
+                                            description: 'Message ID'
+                                        },
+                                        creationTime: {
+                                            type: 'number',
+                                            description: 'Message creation time'
+                                        },
+                                        subject: {
+                                            type: 'string',
+                                            description: 'Message subject'
+                                        },
+                                        conversationId: {
+                                            type: 'string',
+                                            description: 'Conversation/session ID'
+                                        },
+                                        phoneNumber: {
+                                            type: 'string',
+                                            description: 'Phone number associated with the message'
+                                        },
+                                        direction: {
+                                            type: 'string',
+                                            description: 'Message direction (inbound/outbound)'
+                                        },
+                                        from: {
+                                            type: 'object',
+                                            description: 'From object',
+                                            properties: {
+                                                phoneNumber: {
+                                                    type: 'string',
+                                                    description: 'Phone number associated with the from'
+                                                },
+                                                location: {
+                                                    type: 'string',
+                                                    description: 'Location associated with the from'
+                                                },
+                                                name: {
+                                                    type: 'string',
+                                                    description: 'Name associated with the from'
+                                                }
+                                            }
+                                        },
+                                        to: {
+                                            type: 'array',
+                                            description: 'Array of to objects',
+                                            items: {
+                                                type: 'object',
+                                                properties: {
+                                                    phoneNumber: {
+                                                        type: 'string',
+                                                        description: 'Phone number associated with the to'
+                                                    },
+                                                    location: {
+                                                        type: 'string',
+                                                        description: 'Location associated with the to'
+                                                    },
+                                                    name: {
+                                                        type: 'string',
+                                                        description: 'Name associated with the to'
+                                                    }
+                                                }
+                                            }
+                                        },
+                                        messageStatus: {
+                                            type: 'string',
+                                            description: 'Message status, just for fax document'
+                                        },
+                                        faxPageCount: {
+                                            type: 'number',
+                                            description: 'Fax page count, just for fax document'
+                                        },
+                                        attachments: {
+                                            type: 'array',
+                                            description: 'Array of attachment objects',
+                                            items: {
+                                                type: 'object',
+                                                properties: {
+                                                    type: {
+                                                        type: 'string',
+                                                        description: 'Attachment type'
+                                                    },
+                                                    link: {
+                                                        type: 'string',
+                                                        description: 'Attachment link'
+                                                    },
+                                                    uri: {
+                                                        type: 'string',
+                                                        description: 'Attachment URI'
+                                                    },
+                                                    contentType: {
+                                                        type: 'string',
+                                                        description: 'Attachment content type'
+                                                    }
+                                                }
+                                            }
+                                        }
+                                    }
+                                },
+                                required: ['id', 'conversationId', 'phoneNumber', 'direction']
+                            },
+                            correspondents: {
+                                type: 'array',
+                                description: 'Array of correspondent objects',
+                                minItems: 1,
+                                items: {
+                                    type: 'object',
+                                    properties: {
+                                        phoneNumber: {
+                                            type: 'string',
+                                            description: 'Phone number associated with the correspondent'
+                                        }
+                                    }
+                                }
+                            },
+                            conversationId:{
+                                type: 'string',
+                                description: 'Conversation ID'
+                            },
+                            conversationLogId: {
+                                type: 'string',
+                                description: 'Conversation log ID, conversationId + date. The same conversation happen during the same day will have the same conversationLogId'
+                            },
+                            rcAccessToken: {
+                                type: 'string',
+                                description: 'RingCentral access token'
+                            },
+                            type: {
+                                type: 'string',
+                                description: 'Conversation type'
+                            },
+                            date: {
+                                type: 'string',
+                                description: 'Conversation date'
+                            },
+                            creationTime:{
+                                type: 'number',
+                                description: 'Conversation creation time'
+                            }
+                        },
+                        required: ['messages', 'correspondents', 'conversationLogId']
+                    },
+                    contactId: {
+                        type: 'string',
+                        description: 'Contact ID'
+                    },
+                    contactName: {
+                        type: 'string',
+                        description: 'Contact name'
+                    },
+                    contactType: {
+                        type: 'string',
+                        description: 'Contact type'
+                    },
+                    additionalSubmission: {
+                        type: 'object',
+                        description: 'Additional submission object',
+                        properties: {
+                            isAssignedToUser: {
+                                type: 'boolean',
+                                description: 'Whether to assign to a specific user'
+                            }
+                        }
+                    }
+                },
+                required: ['conversation', 'contactId', 'contactName']
+            }
+        },
+        required: ['jwtToken', 'incomingData']
+    }
+};
+
+/**
+ * Execute the createMessageLog tool
+ * @param {Object} args - The tool arguments
+ * @param {string} args.jwtToken - JWT token with user and platform info
+ * @param {Object} args.incomingData - Message log data
+ * @returns {Object} Result object with created log IDs
+ */
+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');
+        }
+
+        if(incomingData.conversation && !incomingData.logInfo) {
+            incomingData.logInfo = incomingData.conversation;
+        }
+
+        // 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 createMessageLog is implemented
+        if (!platformModule.createMessageLog) {
+            throw new Error(`createMessageLog is not implemented for platform: ${platform}`);
+        }
+
+        // Call the createMessageLog method
+        const { successful, returnMessage, logIds } = await logCore.createMessageLog({ 
+            platform, 
+            userId, 
+            incomingData
+        });
+        
+        if (successful) {
+            return {
+                success: true,
+                data: {
+                    logIds,
+                    message: returnMessage?.message || 'Message logs created successfully'
+                }
+            };
+        }
+        else {
+            return {
+                success: false,
+                error: returnMessage?.message || 'Failed to create message logs',
+            };
+        }
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error.message || 'Unknown error occurred',
+            errorDetails: error.stack
+        };
+    }
+}
+
+exports.definition = toolDefinition;
+exports.execute = execute;
+

package/mcp/tools/doAuth.js

@@ -0,0 +1,190 @@
+const authCore = require('../../handlers/auth');
+const jwt = require('../../lib/jwt');
+const crypto = require('crypto');
+const { createAuthSession } = require('../../lib/authSession');
+const { isManifestValid } = require('../lib/validator');
+/**
+ * MCP Tool: Do Authentication
+ * 
+ * This tool does the authentication.
+ */
+
+const toolDefinition = {
+    name: 'doAuth',
+    description: 'Auth flow step.4. Do the authentication. Next step is calling step.5 "checkAuthStatus" tool.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            connectorManifest: {
+                type: 'object',
+                description: 'connectorManifest variable from above conversation. Must be the full manifest object, not just serverUrl'
+            },
+            connectorName: {
+                type: 'string',
+                description: 'connectorName variable from above conversation.'
+            },
+            hostname: {
+                type: 'string',
+                description: 'Hostname to authenticate to.'
+            },
+            apiKey: {
+                type: 'string',
+                description: 'API key to authenticate to.'
+            },
+            additionalInfo: {
+                type: 'object',
+                description: 'Additional information to authenticate to.',
+                properties: {
+                    username: {
+                        type: 'string',
+                        description: 'Username to authenticate to.'
+                    },
+                    password: {
+                        type: 'string',
+                        description: 'Password to authenticate to.'
+                    },
+                    apiUrl: {
+                        type: 'string',
+                        description: 'API URL to authenticate to.'
+                    }
+                }
+            },
+            callbackUri: {
+                type: 'string',
+                description: 'Callback URI to authenticate to.'
+            }
+        },
+        required: ['connectorManifest', 'connectorName', 'hostname']
+    },
+    annotations: {
+        readOnlyHint: false,
+        openWorldHint: true,
+        destructiveHint: true
+    }
+};
+
+/**
+ * Execute the doAuth tool
+ * @param {Object} args - The tool arguments
+ * @param {string} args.connectorManifest - Connector manifest from conversation or memory.
+ * @param {string} args.connectorName - Connector name from conversation or memory.
+ * @param {string} args.hostname - Hostname to authenticate to.
+ * @param {string} args.apiKey - API key to authenticate to.
+ * @param {Object} args.additionalInfo - Additional information to authenticate to.
+ * @param {string} args.callbackUri - Callback URI to authenticate to.
+ * @returns {Object} Result object with authentication information
+ */
+async function execute(args) {
+    try {
+        const { connectorManifest, connectorName, hostname, apiKey, additionalInfo, callbackUri } = args;
+        const { isValid, errors } = isManifestValid({ connectorManifest, connectorName });
+        if (!isValid) {
+            return {
+                success: false,
+                error: "Invalid connector manifest",
+                errorDetails: errors.join(', '),
+            }
+        }
+        const platform = connectorManifest.platforms[connectorName];
+        switch (platform.auth.type) {
+            case 'apiKey':
+                const { userInfo } = await authCore.onApiKeyLogin({ platform: platform.name, hostname, apiKey, additionalInfo });
+                if (userInfo) {
+                    const jwtToken = jwt.generateJwt({
+                        id: userInfo.id.toString(),
+                        platform: platform.name
+                    });
+                    return {
+                        success: true,
+                        data: {
+                            jwtToken,
+                            message: "IMPORTANT: Authentication successful. Keep jwtToken in memory for future use. DO NOT directly show it to user.",
+                        }
+                    }
+                }
+                else {
+                    return {
+                        success: false,
+                        error: "Authentication failed",
+                        errorDetails: "User info not found",
+                    }
+                }
+            case 'oauth':
+                const hasValidCallbackUri = callbackUri && callbackUri.includes('code=') && callbackUri.includes('state=');
+                if (hasValidCallbackUri) {
+                    const query = Object.fromEntries(new URL(callbackUri).searchParams);
+                    query.hostname = hostname;
+                    const { userInfo } = await authCore.onOAuthCallback({ platform: platform.name, hostname, callbackUri, query });
+                    if (userInfo) {
+                        const jwtToken = jwt.generateJwt({
+                            id: userInfo.id.toString(),
+                            platform: platform.name
+                        });
+                        return {
+                            success: true,
+                            data: {
+                                jwtToken,
+                                message: "IMPORTANT: Authentication successful. Keep jwtToken in memory for future use. DO NOT directly show it to user.",
+                            }
+                        }
+                    }
+                    else {
+                        return {
+                            success: false,
+                            error: "Authentication failed",
+                            errorDetails: "User info not found",
+                        }
+                    }
+                }
+                else {
+                    // Generate unique session ID
+                    const sessionId = crypto.randomUUID();
+                    
+                    // Store session
+                    await createAuthSession(sessionId, {
+                        platform: platform.name,
+                        hostname,
+                    });
+                    
+                    const authUri = composeAuthUri({ platform, sessionId, hostname });
+                    return {
+                        success: true,
+                        data: {
+                            authUri,
+                            sessionId,
+                            message: "IMPORTANT: Show this uri as a clickable link for user to authorize. After user authorizes, use checkAuthStatus tool with this sessionId to get the jwtToken.",
+                        }
+                    }
+                }
+        }
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error.message || 'Unknown error occurred',
+            errorDetails: error.stack
+        };
+    }
+}
+
+function composeAuthUri({ platform, sessionId, hostname }) {
+    // Build base state param
+    let stateParam = sessionId ? 
+        `sessionId=${sessionId}&platform=${platform.name}&hostname=${hostname}` : 
+        `platform=${platform.name}&hostname=${hostname}`;
+    
+    // Merge customState if provided
+    if (platform.auth.oauth.customState) {
+        stateParam += `&${platform.auth.oauth.customState}`;
+    }
+    
+    return `${platform.auth.oauth.authUrl}?` +
+        `response_type=code` +
+        `&client_id=${platform.auth.oauth.clientId}` +
+        `${!!platform.auth.oauth.scope && platform.auth.oauth.scope != '' ? `&${platform.auth.oauth.scope}` : ''}` +
+        `&state=${encodeURIComponent(stateParam)}` +
+        `&redirect_uri=${process.env.APP_SERVER}/oauth-callback`;
+}
+
+exports.definition = toolDefinition;
+exports.execute = execute;

package/mcp/tools/findContactByName.js

@@ -0,0 +1,92 @@
+const jwt = require('../../lib/jwt');
+const connectorRegistry = require('../../connector/registry');
+const contactCore = require('../../handlers/contact');
+
+/**
+ * MCP Tool: Find Contact With Name
+ * 
+ * This tool searches for a contact in the CRM platform by name.
+ * It uses the platform-specific connector to find matching contacts.
+ */
+
+const toolDefinition = {
+    name: 'findContactByName',
+    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 name. 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.'
+            },
+            name: {
+                type: 'string',
+                description: 'Name to search for'
+            }
+        },
+        required: ['jwtToken', 'name']
+    },
+    annotations: {
+        readOnlyHint: true,
+        openWorldHint: true,
+        destructiveHint: false
+    }
+};
+
+/**
+ * Execute the findContactByName tool
+ * @param {Object} args - The tool arguments
+ * @param {string} args.jwtToken - JWT token with user and platform info
+ * @param {string} args.name - Name to search for
+ * @returns {Object} Result object with contact information
+ */
+async function execute(args) {
+    try {
+        const { jwtToken, name } = 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 findContactByName is implemented
+        if (!platformModule.findContactWithName) {
+            throw new Error(`findContactByName is not implemented for platform: ${platform}`);
+        }
+
+        // Call the findContactByName method
+        const { successful, returnMessage, contact } = await contactCore.findContactWithName({ platform, userId, name });
+        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;
+