salesforce-metadata-mcp 2.1.2 → 2.1.4

package/dist/tools/agentforce.js

@@ -1,73 +1,285 @@
-import { CreateAgentSchema, CreateAgentTopicSchema, CreateAgentActionSchema } from "../schemas/index.js";
-import { getAuth, createAgent, createAgentTopic } from "../services/salesforce.js";
+import {
+    CreateAgentSchema, CreateAgentTopicSchema, CreateAgentActionSchema, CreateAgentPlannerSchema,
+    GetAgentSchema, UpdateAgentTopicSchema, UpdateAgentActionSchema, DeleteAgentSchema,
+    ListAgentsSchema, TestAgentSchema, GetAgentLogsSchema,
+} from "../schemas/index.js";
+import {
+    getAuth, createAgent, createAgentTopic, createAgentPlanner,
+    activateAgent, deactivateAgent, getAgent, listAgents,
+    updateAgentTopic, deleteAgent, testAgent, getAgentLogs, API_VERSION,
+} from "../services/salesforce.js";
+import { buildGenAiActionZip, deployZip, pollDeployStatus } from "../services/deployment.js";
 import { resultContent } from "./utils.js";
+
 export function registerAgentforceTools(server) {
+    // ─── CREATE ──────────────────────────────────────────────────────────────
     server.registerTool("sf_create_agent", {
         title: "Create Agentforce Agent",
-        description: `Creates an Agentforce Agent (Einstein Copilot) in Salesforce using the Bot metadata type. An agent is an AI assistant that can understand natural language, reason about user intent, and take actions using topics and linked flows/actions. Specify the agent's persona, tone, and system-level instructions to shape its behavior and communication style.`,
+        description: `Creates an Agentforce Agent (Einstein Copilot / Service Agent) in Salesforce using the Bot metadata type.
+
+IMPORTANT: Follow this exact creation order for a fully working agent:
+1. Create flows (sf_create_flow) — AutoLaunchedFlows that perform actions, must be Active with runInMode=SystemModeWithoutSharing
+2. Create agent actions (sf_create_agent_action) — link each flow as a GenAiFunction with LLM-facing schemas
+3. Create agent topics (sf_create_agent_topic) — create GenAiPlugin topics referencing the actions
+4. Create agent planner (sf_create_agent_planner) — create GenAiPlannerBundle linking all topics (CRITICAL link)
+5. Create agent (sf_create_agent) — create the Bot referencing the planner
+6. Activate the agent (sf_activate_agent)
+
+The agent type is IMMUTABLE after creation — choose carefully:
+- EinsteinCopilot: internal employee-facing (Lightning sidebar)
+- ExternalCopilot: customer-facing Agentforce Service Agent`,
         inputSchema: CreateAgentSchema,
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     }, async (params) => {
         const auth = await getAuth();
-        const result = await createAgent(auth, {
-            agentName: params.agentName,
-            label: params.label,
-            description: params.description,
-            type: params.type,
-            company: params.company,
-            persona: params.persona,
-            tone: params.tone,
-            instructions: params.instructions,
-        });
+        const result = await createAgent(auth, params);
         return resultContent(result);
     });
+
     server.registerTool("sf_create_agent_topic", {
-        title: "Create Agentforce Topic",
-        description: `Creates a Topic for an Agentforce Agent. Topics define areas of expertise — what types of user requests the agent can handle. Each topic has a description (what it covers), scope (what kinds of questions it answers), and optional step-by-step instructions for how the agent should respond. Topics are linked to Actions that the agent can execute.`,
+        title: "Create Agentforce Topic (GenAiPlugin)",
+        description: `Creates a Topic (GenAiPlugin) for an Agentforce Agent. Topics define the agent's areas of expertise — what types of user requests it handles. Each topic has a routing description, scope, step-by-step instructions, and references to agent actions.
+
+Create topics AFTER creating agent actions (sf_create_agent_action) since topics reference actions by API name.
+Then create the planner bundle (sf_create_agent_planner) to link all topics to the agent.
+
+Set escalationEnabled: true to allow this topic to escalate to a human agent.
+Set fallbackTopic to route to another topic when this one cannot handle the request.`,
         inputSchema: CreateAgentTopicSchema,
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     }, async (params) => {
         const auth = await getAuth();
-        const result = await createAgentTopic(auth, {
-            agentName: params.agentName,
-            topicName: params.topicName,
-            label: params.label,
-            description: params.description,
-            scope: params.scope,
-            instructions: params.instructions,
-            actions: params.actions,
-        });
+        const result = await createAgentTopic(auth, params);
         return resultContent(result);
     });
+
     server.registerTool("sf_create_agent_action", {
-        title: "Create Agentforce Action",
-        description: `Creates an Agentforce Action linked to a Flow, Apex class, or Prompt Template. Actions are the concrete steps an agent takes when handling a topic. The agent decides which action to invoke based on the user's request and the topic's instructions. Flow actions are the most common — create a Flow first, then link it as an agent action.`,
+        title: "Create Agentforce Action (GenAiFunction)",
+        description: `Creates an Agentforce Action (GenAiFunction) linked to a Flow or Apex class. Actions are the concrete steps an agent takes when handling a topic.
+
+IMPORTANT: Deploys a complete GenAiFunction bundle including:
+- The GenAiFunction metadata (invocationTarget, invocationTargetType, mappingAttributes)
+- input/schema.json — the LLM-facing JSON schema for input parameters (REQUIRED for invocation)
+- output/schema.json — the LLM-facing JSON schema for output parameters
+
+Without schema files the LLM cannot invoke the action. This tool generates all three files automatically.
+
+Set invocationTargetType to "ApexClass" for Apex-backed actions (provide apexClassName instead of flowApiName).
+For Flow actions (default): the flow must be Active with runInMode=SystemModeWithoutSharing.
+
+Type matching: inputs/outputs type MUST match the flow variable type — use "Currency" for Currency fields, "Date" for Date fields, etc. Using "Text" for a Currency field causes "incorrect format" errors.
+
+Create actions BEFORE topics (topics reference actions by API name).`,
         inputSchema: CreateAgentActionSchema,
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     }, async (params) => {
         const auth = await getAuth();
         try {
-            // Agent actions are created via the GenAiPlanner/GenAiFunctionDef metadata
-            const { upsertMetadata, x } = await import("../services/salesforce.js");
-            const inputsXml = (params.inputs ?? []).map((inp) => `
-          <met:inputs>
-            <met:name>${x(inp.name)}</met:name>
-            <met:value>${x(inp.value)}</met:value>
-          </met:inputs>`).join("\n");
-            const xml = `<met:metadata xsi:type="met:GenAiFunction" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
-          <met:fullName>${x(params.agentName)}.${x(params.topicName)}.${x(params.actionName)}</met:fullName>
-          <met:masterLabel>${x(params.label)}</met:masterLabel>
-          <met:description>${x(params.description)}</met:description>
-          <met:type>${x(params.type)}</met:type>
-          <met:functionRef>${x(params.reference)}</met:functionRef>
-          ${inputsXml}
-        </met:metadata>`;
-            const result = await upsertMetadata(auth, xml);
+            const base64Zip = await buildGenAiActionZip({
+                actionName: params.actionName,
+                label: params.label,
+                description: params.description,
+                invocationTargetType: params.invocationTargetType,
+                flowApiName: params.flowApiName,
+                apexClassName: params.apexClassName,
+                inputs: params.inputs ?? [],
+                outputs: params.outputs ?? [],
+            }, API_VERSION);
+            const deployId = await deployZip(auth, base64Zip);
+            const result = await pollDeployStatus(auth, deployId, 120_000);
             return resultContent(result);
         }
         catch (err) {
             return resultContent({ success: false, message: err instanceof Error ? err.message : String(err) });
         }
     });
+
+    server.registerTool("sf_create_agent_planner", {
+        title: "Create Agentforce Planner Bundle (GenAiPlannerBundle)",
+        description: `Creates a GenAiPlannerBundle that connects topics to the agent's planning engine.
+
+The planner bundle is the CRITICAL link between the Bot and its topics (GenAiPlugins). Without it, the agent will have 0 topics visible and cannot route requests or invoke actions.
+
+Create the planner bundle AFTER creating all topics (sf_create_agent_topic) and BEFORE creating the agent (sf_create_agent).
+Then reference this planner's API name when calling sf_create_agent.
+
+For Knowledge-grounded agents, set dataLibraryName to the API name of a Data Library (Knowledge Base).`,
+        inputSchema: CreateAgentPlannerSchema,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (params) => {
+        const auth = await getAuth();
+        const result = await createAgentPlanner(auth, params);
+        return resultContent(result);
+    });
+
+    server.registerTool("sf_activate_agent", {
+        title: "Activate Agentforce Agent",
+        description: `Activates an Agentforce Agent so it is available to users. After making configuration changes (adding/removing topics or actions), re-activate with this tool.`,
+        inputSchema: { type: "object", properties: { agentApiName: { type: "string", description: "API name of the agent to activate, e.g. 'CRM_Record_Creator'" } }, required: ["agentApiName"] },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (params) => {
+        const auth = await getAuth();
+        const result = await activateAgent(auth, params.agentApiName);
+        return resultContent(result);
+    });
+
+    server.registerTool("sf_deactivate_agent", {
+        title: "Deactivate Agentforce Agent",
+        description: `Deactivates an Agentforce Agent so configuration changes can be made. You must deactivate an agent before modifying its topics, actions, or planner configuration. After making changes, re-activate with sf_activate_agent.`,
+        inputSchema: { type: "object", properties: { agentApiName: { type: "string", description: "API name of the agent to deactivate, e.g. 'CRM_Record_Creator'" } }, required: ["agentApiName"] },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (params) => {
+        const auth = await getAuth();
+        const result = await deactivateAgent(auth, params.agentApiName);
+        return resultContent(result);
+    });
+
+    // ─── READ ────────────────────────────────────────────────────────────────
+    server.registerTool("sf_get_agent", {
+        title: "Get Agentforce Agent Configuration",
+        description: `Retrieves the full configuration of an Agentforce Agent including activation status, all GenAiPlugin topics, GenAiFunction actions, and GenAiPlannerBundle planners in the org.
+
+Returns:
+- agent.status: Active / Inactive / Unknown
+- topics[]: all GenAiPlugin topics (name, label, lastModified)
+- actions[]: all GenAiFunction actions (name, label, lastModified)
+- planners[]: all GenAiPlannerBundle planners (name, label, lastModified)
+
+Note: topics/actions/planners list all components in the org (not filtered to this agent). Use sf_get_agent_logs to see which are actively routing.`,
+        inputSchema: GetAgentSchema,
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (params) => {
+        const auth = await getAuth();
+        const result = await getAgent(auth, params.agentApiName);
+        return resultContent(result);
+    });
+
+    server.registerTool("sf_list_agents", {
+        title: "List All Agentforce Agents",
+        description: `Lists all Agentforce Agents (Bots) in the org with their API name, label, activation status, and last modified date.
+
+Use this to discover agents before updating, testing, or deleting them.`,
+        inputSchema: ListAgentsSchema,
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (_params) => {
+        const auth = await getAuth();
+        const result = await listAgents(auth);
+        return resultContent(result);
+    });
+
+    // ─── UPDATE ──────────────────────────────────────────────────────────────
+    server.registerTool("sf_update_agent_topic", {
+        title: "Update Agentforce Topic (GenAiPlugin)",
+        description: `Updates an existing GenAiPlugin topic in-place without deleting and recreating it. Automatically deactivates the agent before the update and reactivates it after.
+
+Use this to change a topic's routing description, scope, instructions, or linked actions.
+All fields provided replace the existing values (instructions and actions arrays are replaced entirely).
+
+The agent must exist and be accessible — provide agentApiName for automatic deactivate/reactivate.`,
+        inputSchema: UpdateAgentTopicSchema,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (params) => {
+        const auth = await getAuth();
+        const { agentApiName, ...topicParams } = params;
+        const result = await updateAgentTopic(auth, topicParams, agentApiName);
+        return resultContent(result);
+    });
+
+    server.registerTool("sf_update_agent_action", {
+        title: "Update Agentforce Action (GenAiFunction)",
+        description: `Updates an existing GenAiFunction action and regenerates its LLM-facing input/output schema files. Uses zip-based metadata deploy (same as sf_create_agent_action) since GenAiFunction bundles require schema files.
+
+Use this to change an action's description, input/output parameters, or switch from one flow to another.
+All fields provided replace the existing values.
+
+After updating an action, the topics that reference it will automatically use the new schema on the next agent invocation.`,
+        inputSchema: UpdateAgentActionSchema,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (params) => {
+        const auth = await getAuth();
+        try {
+            const base64Zip = await buildGenAiActionZip({
+                actionName: params.actionName,
+                label: params.label,
+                description: params.description,
+                invocationTargetType: params.invocationTargetType,
+                flowApiName: params.flowApiName,
+                apexClassName: params.apexClassName,
+                inputs: params.inputs ?? [],
+                outputs: params.outputs ?? [],
+            }, API_VERSION);
+            const deployId = await deployZip(auth, base64Zip);
+            const result = await pollDeployStatus(auth, deployId, 120_000);
+            return resultContent(result);
+        }
+        catch (err) {
+            return resultContent({ success: false, message: err instanceof Error ? err.message : String(err) });
+        }
+    });
+
+    // ─── DELETE ──────────────────────────────────────────────────────────────
+    server.registerTool("sf_delete_agent", {
+        title: "Delete Agentforce Agent",
+        description: `Cleanly deletes an Agentforce Agent (Bot) and optionally its related GenAiPlugin topics and GenAiFunction actions.
+
+Deletion order (to avoid dependency errors):
+1. Deactivates the agent
+2. Reads the Bot → finds GenAiPlannerBundle name
+3. Reads the GenAiPlannerBundle → finds GenAiPlugin topic names (if deleteTopics: true)
+4. Reads each GenAiPlugin → finds GenAiFunction action names (if deleteActions: true)
+5. Deletes GenAiFunctions → GenAiPlugins → GenAiPlannerBundle → Bot
+
+Set deleteTopics: true to also delete the agent's topics.
+Set deleteActions: true to also delete the actions (requires deleteTopics: true since action names are discovered via topics).
+
+WARNING: Deleting actions/topics affects all agents that reference them.`,
+        inputSchema: DeleteAgentSchema,
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+    }, async (params) => {
+        const auth = await getAuth();
+        const result = await deleteAgent(auth, params);
+        return resultContent(result);
+    });
+
+    // ─── TEST & DEBUG ─────────────────────────────────────────────────────────
+    server.registerTool("sf_test_agent", {
+        title: "Send Test Message to Agentforce Agent",
+        description: `Sends a test message to an Agentforce Agent via the Einstein Agent API and returns the agent's response. Useful for end-to-end testing without opening the Salesforce UI.
+
+Flow:
+1. Bootstraps an Agentforce session (POST /agentforce/bootstrap/nameduser)
+2. Creates a session (POST /einstein/ai-agent/v1/agents/{id}/sessions)
+3. Sends the message and returns the agent's reply text
+
+The agent must be Active. Set orgUrl if your My Domain URL differs from SF_INSTANCE_URL.
+
+Returns: response text, sessionId, and success status.`,
+        inputSchema: TestAgentSchema,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, async (params) => {
+        const auth = await getAuth();
+        const result = await testAgent(auth, params);
+        return resultContent(result);
+    });
+
+    server.registerTool("sf_get_agent_logs", {
+        title: "Get Agentforce Debug Logs",
+        description: `Queries ConversationDefinitionEventLog for Agentforce agent debug information. Shows topic routing decisions, action executions, and errors.
+
+Key event types to look for:
+- TopicClassificationSuccess — agent routed to a topic (routing is working)
+- ActionExecuted — agent invoked an action (full pipeline working)
+- TopicClassificationFail / Error — routing or execution failed
+
+If you see TopicClassificationSuccess but NO ActionExecuted events, the agent is routing correctly but cannot invoke actions — check that GenAiFunction schema files exist (redeploy with sf_create_agent_action).
+
+Requires ConversationDefinitionEventLog access (Event Monitoring or Agentforce debug enabled in the org).`,
+        inputSchema: GetAgentLogsSchema,
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (params) => {
+        const auth = await getAuth();
+        const result = await getAgentLogs(auth, params);
+        return resultContent(result);
+    });
 }
-//# sourceMappingURL=agentforce.js.map
+//# sourceMappingURL=agentforce.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "salesforce-metadata-mcp",
-  "version": "2.1.2",
+  "version": "2.1.4",
   "description": "The most comprehensive Salesforce metadata and development MCP server: 60+ tools for custom objects, flows, Apex, LWC, Agentforce, deployments, and more",
   "license": "MIT",
   "private": false,