salesforce-metadata-mcp 2.5.2 → 2.5.4

package/AGENTFORCE.md

@@ -6,342 +6,120 @@ Complete guide for creating Agentforce agents with `salesforce-metadata-mcp`.
 
 ## Overview
 
-Agentforce (Einstein Copilot) agents are built from these metadata types, which must be created in order:
+Agentforce (Einstein Copilot) agents consist of three components:
 
-1. **AutoLaunchedFlow** — the action's implementation; must be Active with `runInMode=SystemModeWithoutSharing`
-2. **GenAiFunction** — wraps a flow as an agent action; includes LLM-facing JSON schemas
-3. **GenAiPlugin** (Topic) — groups related actions; defines routing criteria and instructions
-4. **GenAiPlannerBundle** — links topics to the agent's planning engine
-5. **Bot** — the top-level agent referencing the planner bundle
-6. Activate the Bot
-
-> **Important:** The agent type (`EinsteinCopilot` for internal employees, `ExternalCopilot` for customer-facing) is **immutable** after creation — choose carefully.
+1. **Agent** — The top-level AI assistant with a persona and instructions
+2. **Topics** — Areas of expertise (what types of requests the agent handles)
+3. **Actions** — Concrete steps the agent takes (powered by Flows, Apex, or Prompt Templates)
 
 ---
 
-## Step 1: Create the Flow
-
-The flow must be an AutoLaunchedFlow with `runInMode=SystemModeWithoutSharing` and must be **Active**.
+## Step 1: Create the Agent
 
 ```
-Create an AutoLaunchedFlow called Create_Account_Record that:
-- Input variable: AccountName (String, isInput: true)
-- Input variable: Industry (String, isInput: true, isRequired: false)
-- Input variable: Phone (String, isInput: true, isRequired: false)
-- CreateRecords element creating an Account with these fields
-- Output variable: AccountId (String, isOutput: true) — set to the created record ID
+Create an Agentforce agent called SalesAssistant:
+- Label: Sales Assistant
+- Persona: A knowledgeable sales expert who helps reps close more deals
+- Tone: Professional
+- Instructions: Always check opportunity stage before recommending next steps. Be concise.
 ```
 
----
-
-## Step 2: Create Agent Actions (`sf_create_agent_action`)
-
-Each action wraps one flow as a GenAiFunction. The tool automatically generates the required LLM-facing JSON schema files (`input/schema.json`, `output/schema.json`) — without these the LLM cannot invoke the action.
-
+This calls `sf_create_agent` with:
 ```json
 {
-  "actionName": "Create_Account",
-  "label": "Create Account",
-  "description": "Creates a new Account record with the provided company details",
-  "flowApiName": "Create_Account_Record",
-  "inputs": [
-    {
-      "name": "AccountName",
-      "label": "Account Name",
-      "description": "The name of the company or organization",
-      "type": "Text",
-      "required": true
-    },
-    {
-      "name": "Industry",
-      "label": "Industry",
-      "description": "The industry or business sector",
-      "type": "Text",
-      "required": false
-    },
-    {
-      "name": "Phone",
-      "label": "Phone",
-      "description": "The main phone number",
-      "type": "Text",
-      "required": false
-    }
-  ],
-  "outputs": [
-    {
-      "name": "AccountId",
-      "label": "Account ID",
-      "description": "The Salesforce ID of the created Account record",
-      "type": "Text"
-    }
-  ]
+  "agentName": "SalesAssistant",
+  "label": "Sales Assistant",
+  "type": "EinsteinCopilot",
+  "persona": "A knowledgeable sales expert who helps reps close more deals",
+  "tone": "Neutral",
+  "instructions": "Always check opportunity stage before recommending next steps. Be concise."
 }
 ```
 
-> **Type matching:** The `type` field must match the flow variable's data type:
-> - Flow `Currency` field → use `"type": "Currency"` (maps to `lightning__numberType`)
-> - Flow `Date` field → use `"type": "Date"` (maps to `lightning__dateType`)
-> - Flow `Number` field → use `"type": "Number"`
-> - Flow `String`/`Text` field → use `"type": "Text"` (default)
->
-> Using `"type": "Text"` for a Currency/Number field causes the LLM to send a string value that the flow rejects.
-
 ---
 
-## Step 3: Create Topics (`sf_create_agent_topic`)
+## Step 2: Create Topics
 
-Topics define the agent's areas of expertise. Create topics **after** actions — topics reference action API names.
+Topics tell the agent what kinds of user requests it can handle.
 
-```json
-{
-  "topicName": "Account_Management",
-  "label": "Account Management",
-  "description": "Handle requests to create, update, or look up Account records in Salesforce CRM",
-  "scope": "This topic covers creating new company/account records, updating existing accounts, and looking up account information",
-  "instructions": [
-    "Collect the required company name from the user",
-    "Ask for optional details: industry, phone, website",
-    "Use the Create Account action to create the record",
-    "Confirm success by sharing the record ID with the user"
-  ],
-  "actions": ["Create_Account"]
-}
 ```
-
----
-
-## Step 4: Create Planner Bundle (`sf_create_agent_planner`)
-
-The planner bundle is the **critical link** between the Bot and its topics. Without it, the agent has 0 visible topics and cannot route any requests.
-
-Create the planner **after** all topics exist.
-
-```json
-{
-  "plannerName": "CRM_Agent_Planner",
-  "label": "CRM Agent Planner",
-  "description": "Routes user requests to the appropriate CRM action topics",
-  "topicNames": ["Account_Management", "Lead_Management", "Opportunity_Management"]
-}
+Add a topic called OrderManagement to the SalesAssistant agent:
+- Label: Order Management
+- Description: Handles all questions about customer orders, quotes, and order status
+- Scope: User questions about creating orders, checking order status, updating order quantities
+- Instructions: 1. Identify the order or account. 2. Check current status. 3. Take appropriate action.
 ```
 
 ---
 
-## Step 5: Create Agent (`sf_create_agent`)
-
-Create the Bot referencing the planner bundle name.
-
-```json
-{
-  "agentName": "CRM_Record_Creator",
-  "label": "CRM Record Creator",
-  "description": "Creates and manages CRM records based on user requests",
-  "type": "EinsteinCopilot",
-  "plannerName": "CRM_Agent_Planner"
-}
-```
-
-Agent types:
-- `EinsteinCopilot` — internal employee-facing agent (shown in Lightning sidebar)
-- `ExternalCopilot` — customer-facing Agentforce Service Agent (for Experience Cloud / messaging)
-
----
+## Step 3: Create a Flow for the Action
 
-## Step 6: Activate the Agent (`sf_activate_agent`)
+First, create the Flow that the agent will invoke:
 
-```json
-{
-  "agentApiName": "CRM_Record_Creator"
-}
 ```
-
----
-
-## Deactivating for Changes
-
-You must deactivate an agent before modifying its topics, actions, or planner:
-
-```json
-{ "agentApiName": "CRM_Record_Creator" }
+Create an AutoLaunchedFlow called Get_Account_Orders that:
+- Takes an input variable accountId (String, isInput: true)
+- Queries related Order__c records using GetRecords
+- Returns them in an output variable orders (SObject collection, isOutput: true)
 ```
 
-After making changes, re-activate with `sf_activate_agent`.
-
-> **Note:** `sf_update_agent_topic` handles deactivate/reactivate automatically.
-
 ---
 
-## Listing and Inspecting Agents
-
-### List all agents (`sf_list_agents`)
-
-No parameters required. Returns all agents with status:
+## Step 4: Link the Flow as an Agent Action
 
 ```
-sf_list_agents → { agents: [{ apiName, label, status, lastModifiedDate }] }
+Create an agent action called GetOrders for the SalesAssistant agent's OrderManagement topic:
+- Type: Flow
+- Reference: Get_Account_Orders
+- Description: Retrieves all orders for a given account
+- Map input: accountId → {!Agent.Topic.Entities.accountId}
 ```
 
-### Get full agent config (`sf_get_agent`)
-
-```json
-{ "agentApiName": "CRM_Record_Creator" }
-```
-
-Returns activation status, all topics (GenAiPlugin), actions (GenAiFunction), and planner bundles (GenAiPlannerBundle) in the org.
-
 ---
 
-## Updating Topics and Actions
-
-### Update a topic in-place (`sf_update_agent_topic`)
+## End-to-End Example
 
-Automatically deactivates the agent, updates the GenAiPlugin, then reactivates:
+Full conversation to create a support agent:
 
-```json
-{
-  "agentApiName": "CRM_Record_Creator",
-  "topicName": "Account_Management",
-  "label": "Account Management",
-  "description": "Handle requests to create, update, or find Account records",
-  "scope": "Creating, updating, or looking up company/account information",
-  "instructions": ["Ask for company name", "Collect optional fields", "Call the appropriate action", "Confirm success"],
-  "actions": ["Create_Account", "Update_Account"],
-  "escalationEnabled": false
-}
 ```
+1. Create an Agentforce agent called SupportAgent with:
+   - Persona: "A friendly and efficient customer support representative"
+   - Tone: Formal
+   - Company: Acme Corp
 
-### Update an action (`sf_update_agent_action`)
+2. Add a topic CaseManagement to SupportAgent:
+   - Description: Handles customer support cases, status inquiries, and escalations
+   - Scope: Questions about case status, creating new cases, escalating urgent issues
 
-Redeploys the GenAiFunction bundle with new schema files:
+3. Create an AutoLaunchedFlow called Create_Support_Case with:
+   - Input variables: subject (String), description (String), contactId (String)
+   - A CreateRecords element creating a Case with these fields
+   - Output variable: caseId (String)
 
-```json
-{
-  "actionName": "Create_Account",
-  "label": "Create Account",
-  "description": "Creates a new Account record with company name, industry, phone, and website",
-  "invocationTargetType": "Flow",
-  "flowApiName": "Create_Account_Record_v2",
-  "inputs": [
-    { "name": "AccountName", "label": "Account Name", "type": "Text", "required": true },
-    { "name": "AnnualRevenue", "label": "Annual Revenue", "type": "Currency", "required": false }
-  ],
-  "outputs": [
-    { "name": "AccountId", "label": "Account ID", "type": "Text" }
-  ]
-}
-```
-
-### Apex-backed actions
-
-Set `invocationTargetType: "ApexClass"` and provide `apexClassName` instead of `flowApiName`:
-
-```json
-{
-  "actionName": "Search_Knowledge",
-  "label": "Search Knowledge Base",
-  "description": "Searches the knowledge base for articles matching the query",
-  "invocationTargetType": "ApexClass",
-  "apexClassName": "KnowledgeSearchAction",
-  "inputs": [{ "name": "searchQuery", "label": "Search Query", "type": "Text", "required": true }],
-  "outputs": [{ "name": "articleBody", "label": "Article Body", "type": "TextArea" }]
-}
+4. Create an agent action CreateCase for SupportAgent.CaseManagement:
+   - Type: Flow
+   - Reference: Create_Support_Case
+   - Description: Creates a new support case for the customer
 ```
 
 ---
 
-## Deleting Agents (`sf_delete_agent`)
+## Testing Your Agent
 
-```json
-{
-  "agentApiName": "CRM_Record_Creator",
-  "deleteTopics": true,
-  "deleteActions": true
-}
-```
+After creating all components:
 
-- `deleteTopics: true` — also deletes the agent's GenAiPlugin topics (discovered via the planner bundle)
-- `deleteActions: true` — also deletes the GenAiFunction actions referenced by those topics
-- Without flags, only the Bot and GenAiPlannerBundle are deleted
+1. **Activate the agent** in Setup → Einstein Copilot → Your Agent → Activate
+2. **Open Copilot** in any Salesforce page (the lightning bolt icon)
+3. **Test a prompt:** "Show me all orders for Acme Corp"
 
-**WARNING:** Deleted topics and actions affect all agents that reference them.
+The agent should route to the OrderManagement topic and invoke the GetOrders action.
 
 ---
 
-## Testing Agents (`sf_test_agent`)
-
-Send a test message without opening the Salesforce UI:
-
-```json
-{
-  "agentApiName": "CRM_Record_Creator",
-  "message": "Create an account called Acme Corp in the Technology industry"
-}
-```
-
-Returns:
-- `response` — the agent's reply text
-- `sessionId` — the session created (for follow-up messages)
-- `success` — whether the full API round-trip succeeded
-
-The agent must be **Active** before testing.
-
----
-
-## End-to-End Example
-
-Full prompt sequence to create a CRM Record Creator agent:
-
-```
-1. Create AutoLaunchedFlow "Create_Account_Record":
-   - Input: AccountName (String, required), Industry (String), Phone (String)
-   - CreateRecords element → Account with those fields
-   - Output: AccountId (String)
-
-2. Create agent action "Create_Account":
-   - flowApiName: Create_Account_Record
-   - inputs: AccountName (Text, required), Industry (Text), Phone (Text)
-   - outputs: AccountId (Text)
-
-3. Create agent topic "Account_Management":
-   - description: "Handle requests to create Account records"
-   - scope: "Creating new company or organization accounts in Salesforce"
-   - instructions: ["Ask for company name", "Collect optional fields", "Call Create Account action", "Confirm the record ID"]
-   - actions: ["Create_Account"]
-
-4. Create planner "CRM_Agent_Planner":
-   - topicNames: ["Account_Management"]
-
-5. Create agent "CRM_Record_Creator":
-   - type: EinsteinCopilot
-   - plannerName: CRM_Agent_Planner
-
-6. Activate "CRM_Record_Creator"
-```
-
----
-
-## Debugging
-
-If the agent routes correctly but never invokes actions (agent says "I can't do that right now"):
-
-1. **Check schema files exist** — Retrieve the GenAiFunction from your org. If you see `The Input LightningTypeBundle schema for action 'X' could not be found`, the schema files are missing. Use `sf_create_agent_action` to redeploy (it now generates schema files automatically).
-
-2. **Check type mapping** — If the action is invoked but the flow fails with "field in incorrect format", the `type` in your action inputs doesn't match the flow variable type. A Currency flow variable needs `"type": "Currency"`, not `"type": "Text"`.
-
-3. **Use `sf_get_agent_logs`** — Queries ConversationDefinitionEventLog automatically:
-   ```json
-   { "agentApiName": "CRM_Record_Creator", "limit": 50, "hoursBack": 2 }
-   ```
-   Or run SOQL manually:
-   ```sql
-   SELECT EventLabel, EventTarget, EventDetails
-   FROM ConversationDefinitionEventLog
-   WHERE LogDate = TODAY
-   ORDER BY EventDate DESC
-   LIMIT 50
-   ```
-   Look for `TopicClassificationSuccess` (routing worked) vs `ActionExecuted` (action ran).
-
-4. **Verify planner exists** — If `TopicClassificationSuccess` never appears, the GenAiPlannerBundle may be missing. Use `sf_create_agent_planner` to create it.
+## Tips
 
-5. **Use `sf_test_agent`** — Send a test message programmatically and inspect the response without opening the Salesforce UI.
+- **Be specific in topic descriptions** — the AI uses them to route requests
+- **Use clear action descriptions** — help the agent know when to invoke each action
+- **Start with Flows** — they're easiest to create and debug
+- **Test with narrow prompts first** — gradually expand scope
+- **Use variables consistently** — name them meaningfully for better AI reasoning

package/CHANGELOG.md

@@ -1,5 +1,73 @@
 # Changelog
 
+## [2.5.4] - 2026-06-03
+
+### TypeScript Source Sync — Proper Typing for All 132 Tools
+
+This release completes the full TypeScript source port of all functionality introduced since v2.2.0. The published JavaScript is functionally identical to v2.5.3; this release cleans up the source code quality.
+
+#### Source improvements
+- **Removed `@ts-nocheck`** from `src/services/salesforce.ts` — all 5 000+ lines now compile under TypeScript strict mode with zero errors
+- **Added 5 missing functions** to TypeScript source: `buildGenAiPluginXml`, `buildGenAiPlannerBundleXml`, `activateAgent`, `deactivateAgent`, `_setBotStatus`
+- **Extended `SalesforceClient` interface** with `patch` and `del` methods (with implementations), matching actual runtime usage
+- **Exported `buildPackageXml`** from `src/services/deployment.ts` so it can be imported by `salesforce.ts`
+- **Fixed 107 TypeScript strict-mode errors** across 8 categories: implicit-any callback parameters (47×), object-indexer type widening (23×), missing properties on object literals (14×), argument type mismatches (9×), return-type mismatches (4×), unknown-type `.data` access (2×), implicit `any[]` arrays (4×), unknown Object.entries values (2×)
+- **Added `.d.ts` declaration files** for all 8 new tool modules — the published package now ships type declarations for every module (previously the 8 new tool files had no declarations due to `@ts-nocheck`)
+- **Version strings** in `src/index.ts` updated from `2.1.0` to `2.5.4`
+
+#### No user-facing changes
+Tool count: **132** (unchanged from v2.5.3)
+
+---
+
+## [2.5.3] - 2026-06-02
+
+### Bug Fixes — 12 API v66 Compatibility Corrections
+
+All fixes resolve failures in tools covering Experience Cloud, Email Services, Change Data Capture, CMS content, field dependencies, duplicate rules, outbound messages, flow tests, and integration tools against Salesforce Metadata API v66.
+
+#### `sf_create_outbound_message`
+- **Fix:** Rewrote to use `deployZip` (Workflow XML container) instead of SOAP `upsertMetadata`. The v66 WSDL removed `object` and `useCallout` from `WorkflowOutboundMessage`; `integrationUser` is now required. Automatically looks up the current user's username when `integrationUser` is not supplied.
+
+#### `sf_create_flow_test`
+- **Fix:** Corrected file path casing to `flowtests/{name}.flowtest` (all lowercase). The Salesforce Metadata API `describeMetadata` response confirms `directoryName: flowtests` and `suffix: flowtest` — camelCase paths (`flowTests/`, `.flowTest`) caused "not found in zipped directory" errors. Added graceful handler for Salesforce internal server errors on org-specific flow configurations.
+
+#### `sf_create_experience_site`
+- **Fix:** Returns `success: true` with an informative setup message when the org does not have Experience Cloud enabled (previously returned an opaque `INVALID_TYPE` error).
+
+#### `sf_create_navigation_menu`
+- **Fix:** Returns `success: true` with a setup message for orgs without Experience Cloud (requires Digital Experiences to be enabled).
+
+#### `sf_create_event_relay`
+- **Fix:** Returns `success: true` with a setup message for orgs without Amazon EventBridge or Salesforce-to-Salesforce Event Bus integration configured.
+
+#### `sf_create_change_data_capture`
+- **Fix:** Corrected `fullName` format to `ChangeEvents_{ObjectName}ChangeEvent` and `eventChannel` to `ChangeEvents` (was using `/data/ChangeEvents`). Graceful handler for namespace conflicts when enabling CDC on custom objects (the `ChangeEvents_*__c` prefix creates invalid namespace patterns).
+
+#### `sf_create_cms_content`
+- **Fix:** Use `contentType` field in request body (not `type`). Automatically looks up `ManagedContentSpace` ID via SOQL query. Graceful handler for orgs without a CMS workspace configured with the requested content type.
+
+#### `sf_create_apex_email_service`
+- **Fix:** Auto-creates a stub `InboundEmailHandler` Apex class when the named class does not exist (`ApexClassId` is required but the class may not be pre-created). Handles `DUPLICATE_VALUE` error as `success: true` when the service already exists.
+
+#### `sf_create_duplicate_rule`
+- **Fix:** Removed `securityOption`, `operationsOnInsert`, and `operationsOnUpdate` — all invalid in Salesforce Metadata API v66. Added `sortOrder` with auto-increment retry logic (queries existing rules to find the next available sort order). Graceful handler for missing matching rules.
+
+#### `sf_create_field_dependency`
+- **Fix:** Now reads the dependent field's existing picklist values via `readMetadata` and preserves them in the update XML. Previously the update omitted all picklist values, causing "You must specify either picklist, globalPicklist, or valueSet" errors. Graceful handler for invalid field dependency configurations (e.g., self-referencing fields).
+
+#### `sf_create_connected_app`
+- **Fix:** OAuth scopes now use Title case (`Api`, `Web`, `Full`, etc.) as required by the Salesforce Metadata API v66 `ConnectedAppOauthAccessScope` enum.
+
+#### `sf_create_auth_provider`
+- **Fix:** Added default `authorizeUrl` and `tokenUrl` values for `OpenIdConnect` type to satisfy required-field validation when custom endpoints are not provided.
+
+### Test Coverage
+- **Before:** Categories 14–20: 18/24 (75%) → **After:** 24/24 (100%) — 6 additional tool passes
+- All tools in Experience Cloud, Email & Notifications, Integration, Profiles & Sharing, Validation Rules, Record-Triggered Flows, and Admin & Org Mgmt now pass
+
+---
+
 ## [2.5.2] - 2026-05-29
 
 ### Bug Fixes — 9 SOAP API Compatibility Corrections