Salesforce MCP Server

Instructions

Implementation Reference

• src/tools/reportXml.ts:88-216 (handler)

  Main execution logic for the salesforce_upload_report_xml tool. Handles validation, creation, and updating of Salesforce reports using Metadata API.
  export async function handleUploadReportXml(conn: any, args: UploadReportXmlArgs) { const { reportName, reportId, folderId, xmlContent, isDeveloperName = false } = args; try { // Validate input parameters if (!reportId && !reportName) { return { content: [{ type: "text", text: "Either reportName (for new reports) or reportId (for updates) must be provided" }], isError: true, }; } // Validate XML content const xmlValidation = validateReportXml(xmlContent); if (!xmlValidation.isValid) { return { content: [{ type: "text", text: xmlValidation.error! }], isError: true, }; } // For updating existing reports if (reportId) { // First verify the report exists try { await conn.sobject('Report').retrieve(reportId); } catch (error) { return { content: [{ type: "text", text: `Report with ID ${reportId} not found or you don't have access to it` }], isError: true, }; } // Use Salesforce Metadata API to update the report const result = await conn.metadata.update('Report', { fullName: reportId, content: Buffer.from(xmlContent).toString('base64') }); if (result.success) { return { content: [{ type: "text", text: `Report successfully updated with ID: ${reportId}` }], isError: false, }; } else { return { content: [{ type: "text", text: `Failed to update report: ${result.errors?.join(', ') || 'Unknown error'}` }], isError: true, }; } } // For creating new reports else { // Generate API name from display name if needed const developerName = isDeveloperName ? reportName : reportName!.replace(/[^a-zA-Z0-9]/g, '_'); // Prepare report metadata const reportMetadata = { fullName: developerName, content: Buffer.from(xmlContent).toString('base64') }; // Specify folder if provided if (folderId) { // @ts-ignore - JSForce types don't include this property but it's supported reportMetadata.folderId = folderId; } // Use Metadata API to create the report const result = await conn.metadata.create('Report', reportMetadata); if (result.success) { return { content: [{ type: "text", text: `Report "${reportName}" successfully created with ID: ${result.id}` }], isError: false, }; } else { return { content: [{ type: "text", text: `Failed to create report: ${result.errors?.join(', ') || 'Unknown error'}` }], isError: true, }; } } } catch (error) { // Enhanced error handling const errorMessage = error instanceof Error ? error.message : String(error); let enhancedError = errorMessage; // Customize error messages for common issues if (errorMessage.includes('INVALID_CROSS_REFERENCE_KEY')) { enhancedError = `Invalid folder ID or report folder access issue. Please check that the folder exists and you have proper permissions.`; } else if (errorMessage.includes('INSUFFICIENT_ACCESS')) { enhancedError = `Insufficient permissions to create or modify reports. Please check your Salesforce user permissions.`; } else if (errorMessage.includes('INVALID_TYPE')) { enhancedError = `Invalid report type in XML. Ensure the report type specified in the XML exists in your Salesforce org.`; } return { content: [{ type: "text", text: `Error uploading report XML: ${enhancedError}` }], isError: true, }; } }
• src/tools/reportXml.ts:3-50 (schema)

  Tool schema definition including name, description, and input schema for salesforce_upload_report_xml.
  export const UPLOAD_REPORT_XML: Tool = { name: "salesforce_upload_report_xml", description: `Upload XML to generate or update reports in Salesforce. Examples: 1. Create a new report: - reportName: "Monthly Sales Summary" - folderId: "00l5e000000XXXXX" (optional - uploads to user's private reports by default) - xmlContent: "<Report xmlns=..." - isDeveloperName: false 2. Update existing report: - reportId: "00O5e000000XXXXX" - xmlContent: "<Report xmlns=..." Note: XML must follow Salesforce report metadata format. For custom report types, ensure the report type exists in your org before uploading.`, inputSchema: { type: "object", properties: { reportName: { type: "string", description: "Name for the new report (required for new reports)", optional: true }, reportId: { type: "string", description: "Report ID to update an existing report", optional: true }, folderId: { type: "string", description: "Folder ID where the report should be saved (optional)", optional: true }, xmlContent: { type: "string", description: "XML content for the report in Salesforce report metadata format" }, isDeveloperName: { type: "boolean", description: "If true, reportName is treated as the API name instead of the display name", optional: true } }, required: ["xmlContent"] } };
• src/index.ts:36-47 (registration)

  Registration of the tool in the ListToolsRequestSchema handler, adding UPLOAD_REPORT_XML to the available tools list.
  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [ SEARCH_OBJECTS, DESCRIBE_OBJECT, QUERY_RECORDS, DML_RECORDS, MANAGE_OBJECT, MANAGE_FIELD, SEARCH_ALL, UPLOAD_REPORT_XML // Add new tool to the list ], }));
• src/index.ts:177-193 (registration)

  Dispatch handler in the main switch case for CallToolRequestSchema, routing 'salesforce_upload_report_xml' calls to handleUploadReportXml.
  case "salesforce_upload_report_xml": { const reportArgs = args as Record<string, unknown>; if (!reportArgs.xmlContent) { throw new Error('xmlContent is required for report XML upload'); } // Type check and conversion const validatedArgs: UploadReportXmlArgs = { reportName: reportArgs.reportName as string | undefined, reportId: reportArgs.reportId as string | undefined, folderId: reportArgs.folderId as string | undefined, xmlContent: reportArgs.xmlContent as string, isDeveloperName: reportArgs.isDeveloperName as boolean | undefined }; return await handleUploadReportXml(conn, validatedArgs); }
• src/tools/reportXml.ts:61-86 (helper)

  Helper function to validate the XML content before uploading to Salesforce.
  function validateReportXml(xmlContent: string): { isValid: boolean; error?: string } { try { // Check if content is valid XML if (!xmlContent.trim().startsWith('<')) { return { isValid: false, error: "Invalid XML format: Content must be XML starting with '<'" }; } // Check if it's a Salesforce report XML if (!xmlContent.includes('<Report xmlns') && !xmlContent.includes('<report>')) { return { isValid: false, error: "XML content doesn't appear to be a valid Salesforce report definition" }; } return { isValid: true }; } catch (error) { return { isValid: false, error: `XML validation error: ${error instanceof Error ? error.message : String(error)}` }; } }