salesforce-metadata-mcp 2.1.2 → 2.1.4

package/dist/schemas/index.js

@@ -858,37 +858,86 @@ export const CreateExperiencePageSchema = z.object({
 }).strict();
 // ─── AGENTFORCE ───────────────────────────────────────────────────────────────
 export const CreateAgentSchema = z.object({
-    agentName: z.string().min(1).max(80).regex(/^[A-Za-z][A-Za-z0-9_]*$/).describe("Agent API name, e.g. 'SupportAgent'"),
-    label: z.string().min(1).max(255).describe("Agent display name"),
-    description: z.string().max(1000).optional().describe("Agent description shown to users"),
-    type: z.enum(["Default", "EinsteinCopilot"]).default("EinsteinCopilot").describe("Agent type"),
-    company: z.string().max(255).optional().describe("Company name for the agent's context"),
-    persona: z.string().max(5000).optional().describe("Agent persona description, e.g. 'A helpful customer service representative'"),
-    tone: z.enum(["Formal", "Neutral", "Casual"]).default("Neutral").describe("Communication tone"),
-    instructions: z.string().max(10000).optional().describe("System-level instructions for the agent"),
+    agentName: z.string().min(1).max(80).regex(/^[A-Za-z][A-Za-z0-9_]*$/).describe("Agent API name, e.g. 'CRM_Record_Creator'. IMMUTABLE after creation."),
+    label: z.string().min(1).max(255).describe("Agent display label, e.g. 'CRM Record Creator'"),
+    description: z.string().max(1000).optional().describe("Agent description"),
+    type: z.enum(["EinsteinCopilot", "ExternalCopilot"]).default("EinsteinCopilot").describe("Bot type: 'EinsteinCopilot' for internal employee agents (shown in Lightning sidebar), 'ExternalCopilot' for customer-facing Agentforce Service Agents. CANNOT be changed after creation."),
+    systemPrompt: z.string().max(32000).optional().describe("Custom system prompt to override the agent's default behavior and persona. Injected into the agent's context before every conversation."),
+    openingMessage: z.string().max(2000).optional().describe("Welcome message shown to users when they first open the agent (set as welcomeMessage on the Bot)."),
 }).strict();
 export const CreateAgentTopicSchema = z.object({
-    agentName: z.string().min(1).max(80).describe("Parent agent API name"),
-    topicName: z.string().min(1).max(80).regex(/^[A-Za-z][A-Za-z0-9_]*$/).describe("Topic API name, e.g. 'OrderManagement'"),
-    label: z.string().min(1).max(255).describe("Topic label"),
-    description: z.string().min(1).max(5000).describe("What this topic covers"),
-    scope: z.string().min(1).max(5000).describe("Scope of this topic — what kind of requests it handles"),
-    instructions: z.string().max(10000).optional().describe("Step-by-step instructions for handling this topic"),
-    actions: z.array(z.string().max(80)).optional().describe("Action API names to associate with this topic"),
+    topicName: z.string().min(1).max(80).regex(/^[A-Za-z][A-Za-z0-9_]*$/).describe("Topic API name, e.g. 'Create_Account_Topic'. Used as the GenAiPlugin developer name."),
+    label: z.string().min(1).max(255).describe("Topic display label, e.g. 'Create Account Topic'"),
+    description: z.string().min(1).max(5000).describe("Routing description — the LLM uses this to decide which topic handles a user request. Be specific, e.g. 'Use this topic when the user wants to create, add, or make a new Account or company record'"),
+    scope: z.string().min(1).max(5000).describe("What this topic covers in detail, e.g. 'Create new Account records with company name, industry, phone, and website'"),
+    instructions: z.array(z.string().max(2000)).optional().describe("Ordered step-by-step instructions for the agent, e.g. ['Ask the user for the account name', 'Call the Create Account action', 'Confirm success to the user']"),
+    actions: z.array(z.string().max(80)).optional().describe("Action API names (GenAiFunction developer names) to associate, e.g. ['Create_Account']. Create actions first with sf_create_agent_action."),
+    escalationEnabled: z.boolean().optional().describe("Whether this topic can escalate to a human agent (sets canEscalate on GenAiPlugin). Default: false."),
+    fallbackTopic: z.string().max(80).optional().describe("API name of another GenAiPlugin topic to fall back to if this topic cannot handle the request."),
 }).strict();
+const AgentParamSchema = z.object({
+    name: z.string().max(80).describe("Parameter API name matching the flow variable name, e.g. 'AccountName'"),
+    label: z.string().max(255).describe("Human-readable label, e.g. 'Account Name'"),
+    description: z.string().max(1000).optional().describe("Description shown to the LLM, e.g. 'The name of the company or organization'"),
+    type: z.enum(["Text", "Number", "Currency", "Boolean", "Date", "DateTime", "TextArea"]).default("Text").describe("Data type — must match the flow variable type: 'Currency'/'Number' for numeric fields, 'Date' for date fields, 'Boolean' for checkboxes, 'Text' for everything else"),
+    required: z.boolean().default(true).describe("Whether this input is required"),
+});
 export const CreateAgentActionSchema = z.object({
-    agentName: z.string().min(1).max(80).describe("Parent agent API name"),
-    topicName: z.string().min(1).max(80).describe("Parent topic API name"),
-    actionName: z.string().min(1).max(80).regex(/^[A-Za-z][A-Za-z0-9_]*$/).describe("Action API name"),
-    label: z.string().min(1).max(255).describe("Action label"),
-    description: z.string().min(1).max(5000).describe("What this action does"),
-    type: z.enum(["Flow", "ApexClass", "PromptTemplate", "DataCategoryGroup", "ExternalService"])
-        .describe("Action type"),
-    reference: z.string().min(1).max(255).describe("API name of the Flow, Apex class, or Prompt Template to invoke"),
-    inputs: z.array(z.object({
-        name: z.string().max(255).describe("Input parameter name"),
-        value: z.string().max(1000).describe("Value or reference, e.g. '{!Agent.Topic.Entities.accountName}'"),
-    })).optional().describe("Input parameter mappings"),
+    actionName: z.string().min(1).max(80).regex(/^[A-Za-z][A-Za-z0-9_]*$/).describe("Action API name (GenAiFunction developer name), e.g. 'Create_Account'. Used to reference this action from topics."),
+    label: z.string().min(1).max(255).describe("Action display label, e.g. 'Create Account'"),
+    description: z.string().min(1).max(5000).describe("What this action does — the LLM uses this to decide when to invoke it. Be specific, e.g. 'Creates a new Account record in Salesforce with the given company name, industry, phone, and website'"),
+    invocationTargetType: z.enum(["Flow", "ApexClass"]).default("Flow").describe("Type of backend to invoke: 'Flow' for AutoLaunchedFlow (most common), 'ApexClass' for an Apex class implementing InvocableMethod."),
+    flowApiName: z.string().max(255).optional().describe("API name of the AutoLaunchedFlow to invoke (required when invocationTargetType is Flow). Must be Active with runInMode=SystemModeWithoutSharing."),
+    apexClassName: z.string().max(255).optional().describe("API name of the Apex class to invoke (required when invocationTargetType is ApexClass). Class must have an @InvocableMethod."),
+    inputs: z.array(AgentParamSchema).optional().describe("Input parameters. Each becomes a parameter the LLM collects from the user. Type MUST match the flow variable / Apex param type."),
+    outputs: z.array(AgentParamSchema.omit({ required: true })).optional().describe("Output parameters returned to the agent after execution, e.g. the created record ID"),
+}).strict();
+export const CreateAgentPlannerSchema = z.object({
+    plannerName: z.string().min(1).max(80).regex(/^[A-Za-z][A-Za-z0-9_]*$/).describe("Planner API name, e.g. 'CRM_Creator_Planner'. NOTE: Names are permanently reserved even after deletion — use a unique name."),
+    label: z.string().min(1).max(255).describe("Planner display label, e.g. 'CRM Creator Planner'"),
+    description: z.string().max(1000).optional().describe("Planner description"),
+    topicNames: z.array(z.string().min(1).max(80)).min(1).describe("Topic API names (GenAiPlugin developer names) to include, e.g. ['Create_Account_Topic', 'Create_Lead_Topic']. Topics must already exist."),
+    dataLibraryName: z.string().max(80).optional().describe("API name of a Data Library (Knowledge Base) to attach to this planner for Knowledge-grounded agents."),
+}).strict();
+export const GetAgentSchema = z.object({
+    agentApiName: z.string().min(1).max(80).describe("Agent API name, e.g. 'CRM_Record_Creator'"),
+}).strict();
+export const UpdateAgentTopicSchema = z.object({
+    agentApiName: z.string().min(1).max(80).describe("API name of the agent that owns this topic. The agent is automatically deactivated before the update and reactivated after."),
+    topicName: z.string().min(1).max(80).regex(/^[A-Za-z][A-Za-z0-9_]*$/).describe("Topic API name to update (GenAiPlugin developer name)"),
+    label: z.string().min(1).max(255).describe("Updated topic display label"),
+    description: z.string().min(1).max(5000).describe("Updated routing description"),
+    scope: z.string().min(1).max(5000).describe("Updated scope"),
+    instructions: z.array(z.string().max(2000)).optional().describe("Updated step-by-step instructions (replaces existing)"),
+    actions: z.array(z.string().max(80)).optional().describe("Updated action API names (replaces existing)"),
+    escalationEnabled: z.boolean().optional().describe("Whether this topic can escalate to a human agent"),
+    fallbackTopic: z.string().max(80).optional().describe("API name of fallback topic"),
+}).strict();
+export const UpdateAgentActionSchema = z.object({
+    actionName: z.string().min(1).max(80).regex(/^[A-Za-z][A-Za-z0-9_]*$/).describe("Action API name to update (GenAiFunction developer name)"),
+    label: z.string().min(1).max(255).describe("Updated action display label"),
+    description: z.string().min(1).max(5000).describe("Updated action description"),
+    invocationTargetType: z.enum(["Flow", "ApexClass"]).default("Flow").describe("Type of backend to invoke"),
+    flowApiName: z.string().max(255).optional().describe("API name of the AutoLaunchedFlow (required if invocationTargetType is Flow)"),
+    apexClassName: z.string().max(255).optional().describe("API name of the Apex class (required if invocationTargetType is ApexClass)"),
+    inputs: z.array(AgentParamSchema).optional().describe("Updated input parameters (replaces existing)"),
+    outputs: z.array(AgentParamSchema.omit({ required: true })).optional().describe("Updated output parameters (replaces existing)"),
+}).strict();
+export const DeleteAgentSchema = z.object({
+    agentApiName: z.string().min(1).max(80).describe("API name of the agent to delete, e.g. 'CRM_Record_Creator'"),
+    deleteTopics: z.boolean().default(false).describe("If true, also deletes the agent's GenAiPlugin topics (identified via its GenAiPlannerBundle)"),
+    deleteActions: z.boolean().default(false).describe("If true, also deletes the GenAiFunction actions referenced by the agent's topics"),
+}).strict();
+export const ListAgentsSchema = z.object({}).strict();
+export const TestAgentSchema = z.object({
+    agentApiName: z.string().min(1).max(80).describe("API name of the agent to test, e.g. 'CRM_Record_Creator'"),
+    message: z.string().min(1).max(5000).describe("Test message to send to the agent, e.g. 'Create an account called Acme Corp'"),
+    orgUrl: z.string().url().optional().describe("Override the Agentforce bootstrap URL (defaults to SF_INSTANCE_URL). Required only if your My Domain URL differs from the instance URL."),
+}).strict();
+export const GetAgentLogsSchema = z.object({
+    agentApiName: z.string().max(80).optional().describe("Filter logs by agent API name (optional — omit to see all agent activity in the org)"),
+    limit: z.number().int().min(1).max(200).default(20).describe("Maximum number of log entries to return (default: 20)"),
+    hoursBack: z.number().min(0.1).max(24).default(1).describe("How many hours back to look (default: 1 hour)"),
 }).strict();
 // ─── MCP SERVER MANAGEMENT ───────────────────────────────────────────────────
 export const CreateMcpServerSchema = z.object({

package/dist/services/deployment.js

@@ -64,6 +64,105 @@ export async function buildStaticResourceZip(resourceName, content, contentType,
     const buffer = await zip.generateAsync({ type: "nodebuffer" });
     return buffer.toString("base64");
 }
+export async function buildGenAiActionZip(params, apiVersion) {
+    const zip = new JSZip();
+    const functionName = params.actionName;
+    const packageXml = buildPackageXml([{ name: "GenAiFunction", members: [functionName] }], apiVersion);
+    zip.file("package.xml", packageXml);
+    // Build mappingAttributes XML
+    const inputsXml = (params.inputs ?? []).map(inp => `
+    <mappingAttributes>
+        <description>${escapeXml(inp.description ?? inp.label)}</description>
+        <label>${escapeXml(inp.label)}</label>
+        <name>${escapeXml(inp.name)}</name>
+        <parameterName>${escapeXml(inp.name)}</parameterName>
+        <parameterType>input</parameterType>
+    </mappingAttributes>`).join("\n");
+    const outputsXml = (params.outputs ?? []).map(out => `
+    <mappingAttributes>
+        <description>${escapeXml(out.description ?? out.label)}</description>
+        <label>${escapeXml(out.label)}</label>
+        <name>${escapeXml(out.name)}</name>
+        <parameterName>${escapeXml(out.name)}</parameterName>
+        <parameterType>output</parameterType>
+    </mappingAttributes>`).join("\n");
+    const isApex = params.invocationTargetType === "ApexClass";
+    const invocationTarget = isApex ? (params.apexClassName ?? "") : (params.flowApiName ?? "");
+    const invocationTargetType = isApex ? "apexClass" : "flow";
+    const functionXml = `<?xml version="1.0" encoding="UTF-8"?>
+<GenAiFunction xmlns="http://soap.sforce.com/2006/04/metadata">
+    <description>${escapeXml(params.description)}</description>
+    <invocationTarget>${escapeXml(invocationTarget)}</invocationTarget>
+    <invocationTargetType>${invocationTargetType}</invocationTargetType>
+    <isConfirmationRequired>false</isConfirmationRequired>
+    <masterLabel>${escapeXml(params.label)}</masterLabel>
+    ${inputsXml}
+    ${outputsXml}
+</GenAiFunction>`;
+    zip.file(`genAiFunctions/${functionName}/${functionName}.genAiFunction-meta.xml`, functionXml);
+    // Build input schema JSON
+    const inputSchemaProps = {};
+    const requiredInputs = [];
+    for (const inp of (params.inputs ?? [])) {
+        inputSchemaProps[inp.name] = {
+            "title": inp.label,
+            "description": inp.description ?? inp.label,
+            "lightning:type": lightningTypeFor(inp.type ?? "Text"),
+            "lightning:isPII": false,
+            "copilotAction:isUserInput": true
+        };
+        if (inp.required !== false) {
+            requiredInputs.push(inp.name);
+        }
+    }
+    const inputSchema = {
+        "required": requiredInputs.length > 0 ? requiredInputs : undefined,
+        "unevaluatedProperties": false,
+        "properties": inputSchemaProps,
+        "lightning:type": "lightning__objectType"
+    };
+    if (!inputSchema.required) {
+        delete inputSchema.required;
+    }
+    zip.file(`genAiFunctions/${functionName}/input/schema.json`, JSON.stringify(inputSchema, null, 2));
+    // Build output schema JSON
+    const outputSchemaProps = {};
+    for (const out of (params.outputs ?? [])) {
+        outputSchemaProps[out.name] = {
+            "title": out.label,
+            "description": out.description ?? out.label,
+            "lightning:type": lightningTypeFor(out.type ?? "Text"),
+            "lightning:isPII": false,
+            "copilotAction:isDisplayable": true,
+            "copilotAction:isUsedByPlanner": true
+        };
+    }
+    const outputSchema = {
+        "unevaluatedProperties": false,
+        "properties": outputSchemaProps,
+        "lightning:type": "lightning__objectType"
+    };
+    zip.file(`genAiFunctions/${functionName}/output/schema.json`, JSON.stringify(outputSchema, null, 2));
+    const buffer = await zip.generateAsync({ type: "nodebuffer" });
+    return buffer.toString("base64");
+}
+function escapeXml(s) {
+    return String(s ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+function lightningTypeFor(sfType) {
+    const t = sfType.toLowerCase();
+    if (t === "currency" || t === "number" || t === "double" || t === "integer" || t === "percent")
+        return "lightning__numberType";
+    if (t === "boolean" || t === "checkbox")
+        return "lightning__booleanType";
+    if (t === "date")
+        return "lightning__dateType";
+    if (t === "datetime")
+        return "lightning__dateTimeType";
+    if (t === "textarea" || t === "longtextarea" || t === "richtext")
+        return "lightning__textAreaType";
+    return "lightning__textType";
+}
 export async function buildGenericDeployZip(components, apiVersion) {
     const zip = new JSZip();
     const typeMap = new Map();