@salesforce/mcp 0.6.3 → 0.8.1

package/README.md

@@ -158,6 +158,7 @@ These are the available toolsets:
 - `data` - [Tools to manage the data in your org, such as listing all accounts.](README.md#data-toolset)
 - `users` - [Tools to manage org users, such as assigning a permission set.](README.md#users-toolset)
 - `metadata` - [Tools to deploy and retrieve metadata to and from your org and your DX project.](README.md#metadata-toolset)
+- `testing` - [Tools to test your code and features](README.md#testing-toolset)
 
 This example shows how to enable the `data`, `orgs`, and `metadata` toolsets when configuring the MCP server for VS Code:
 
@@ -203,6 +204,14 @@ Includes these tools:
 
 - `sf-deploy-metadata` - Deploys metadata from your DX project to an org.
 - `sf-retrieve-metadata` - Retrieves metadata from your org to your DX project.
+-
+
+#### Testing Toolset
+
+Includes these tools:
+
+- `sf-test-agents` - Executes agent tests in your org.
+- `sf-test-apex` - Executes apex tests in your org
 
 ## Configure Other Clients to Use the Salesforce DX MCP Server
 

package/lib/index.d.ts

@@ -4,7 +4,7 @@ export default class McpServerCommand extends Command {
     static description: string;
     static flags: {
         orgs: import("@oclif/core/interfaces").OptionFlag<string[], import("@oclif/core/interfaces").CustomOptions>;
-        toolsets: import("@oclif/core/interfaces").OptionFlag<("data" | "metadata" | "all" | "users" | "orgs")[], import("@oclif/core/interfaces").CustomOptions>;
+        toolsets: import("@oclif/core/interfaces").OptionFlag<("data" | "metadata" | "all" | "users" | "orgs" | "testing")[], import("@oclif/core/interfaces").CustomOptions>;
         version: import("@oclif/core/interfaces").BooleanFlag<void>;
         'no-telemetry': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         debug: import("@oclif/core/interfaces").BooleanFlag<boolean>;

package/lib/index.js

@@ -20,11 +20,12 @@ import * as core from './tools/core/index.js';
 import * as orgs from './tools/orgs/index.js';
 import * as data from './tools/data/index.js';
 import * as users from './tools/users/index.js';
+import * as testing from './tools/testing/index.js';
 import * as metadata from './tools/metadata/index.js';
 import Cache from './shared/cache.js';
 import { Telemetry } from './telemetry.js';
 import { SfMcpServer } from './sf-mcp-server.js';
-const TOOLSETS = ['all', 'orgs', 'data', 'users', 'metadata'];
+const TOOLSETS = ['all', 'testing', 'orgs', 'data', 'users', 'metadata'];
 /**
  * Sanitizes an array of org usernames by replacing specific orgs with a placeholder.
  * Special values (DEFAULT_TARGET_ORG, DEFAULT_TARGET_DEV_HUB, ALLOW_ALL_ORGS) are preserved.
@@ -128,8 +129,6 @@ You can also use special values to control access to orgs:
                 tools: {},
             },
         }, { telemetry: this.telemetry });
-        // // TODO: Should we add annotations to our tools? https://modelcontextprotocol.io/docs/concepts/tools#tool-definition-structure
-        // // TODO: Move tool names into a shared file, that way if we reference them in multiple places, we can update them in one place
         const enabledToolsets = new Set(flags.toolsets);
         const all = enabledToolsets.has('all');
         // ************************
@@ -164,6 +163,14 @@ You can also use special values to control access to orgs:
             users.registerToolAssignPermissionSet(server);
         }
         // ************************
+        // testing TOOLS
+        // ************************
+        if (all || enabledToolsets.has('testing')) {
+            this.logToStderr('Registering testing tools');
+            testing.registerToolRunApexTest(server);
+            testing.registerToolRunAgentTest(server);
+        }
+        // ************************
         // METADATA TOOLS
         // ************************
         if (all || enabledToolsets.has('metadata')) {

package/lib/tools/core/sf-get-username.js

@@ -69,7 +69,11 @@ This tool handles three distinct scenarios:
 EXAMPLE USAGE:
 - When user says "Do X for my org" → defaultTargetOrg=false, defaultDevHub=false
 - When user says "For my default org" → defaultTargetOrg=true
-- When user says "For my default dev hub" → defaultDevHub=true`, getUsernameParamsSchema.shape, async ({ defaultTargetOrg, defaultDevHub, directory }) => {
+- When user says "For my default dev hub" → defaultDevHub=true`, getUsernameParamsSchema.shape, {
+        title: 'Get Username',
+        readOnlyHint: true,
+        openWorldHint: false,
+    }, async ({ defaultTargetOrg, defaultDevHub, directory }) => {
         try {
             process.chdir(directory);
             const generateResponse = (defaultFromConfig) => textResponse(`ALWAYS notify the user the following 3 (maybe 4) pieces of information:

package/lib/tools/core/sf-resume.js

@@ -63,7 +63,10 @@ Resume the deployment to my org
 Resume scratch org creation
 Resume job 2SR1234567890
 Resume agent tests
-`, resumeParamsSchema.shape, async ({ jobId, wait, usernameOrAlias, directory }) => {
+`, resumeParamsSchema.shape, {
+        title: 'Resume',
+        openWorldHint: false,
+    }, async ({ jobId, wait, usernameOrAlias, directory }) => {
         if (!jobId) {
             return textResponse('The jobId parameter is required.', true);
         }

package/lib/tools/data/sf-query-org.js

@@ -35,7 +35,11 @@ export const queryOrgParamsSchema = z.object({
     directory: directoryParam,
 });
 export const registerToolQueryOrg = (server) => {
-    server.tool('sf-query-org', 'Run a SOQL query against a Salesforce org.', queryOrgParamsSchema.shape, async ({ query, usernameOrAlias, directory }) => {
+    server.tool('sf-query-org', 'Run a SOQL query against a Salesforce org.', queryOrgParamsSchema.shape, {
+        title: 'Query Org',
+        openWorldHint: false,
+        readOnlyHint: true,
+    }, async ({ query, usernameOrAlias, directory }) => {
         try {
             if (!usernameOrAlias)
                 return textResponse('The usernameOrAlias parameter is required, if the user did not specify one use the #sf-get-username tool', true);

package/lib/tools/metadata/sf-deploy-metadata.js

@@ -82,7 +82,11 @@ Deploy this file to my org
 Deploy the manifest
 Deploy X metadata to my org
 Deploy X to my org and run A,B and C apex tests.
-`, deployMetadataParams.shape, async ({ sourceDir, usernameOrAlias, apexTests, apexTestLevel, directory, manifest }) => {
+`, deployMetadataParams.shape, {
+        title: 'Deploy Metadata',
+        destructiveHint: true,
+        openWorldHint: false,
+    }, async ({ sourceDir, usernameOrAlias, apexTests, apexTestLevel, directory, manifest }) => {
         if (apexTests && apexTestLevel) {
             return textResponse("You can't specify both `apexTests` and `apexTestLevel` parameters.", true);
         }

package/lib/tools/metadata/sf-retrieve-metadata.js

@@ -55,7 +55,11 @@ Retrieve changes from my org
 Retrieve this file from my org
 Retrieve the metadata in the manifest
 Retrieve X metadata from my org
-`, retrieveMetadataParams.shape, async ({ sourceDir, usernameOrAlias, directory, manifest }) => {
+`, retrieveMetadataParams.shape, {
+        title: 'Retrieve Metadata',
+        openWorldHint: false,
+        destructiveHint: true,
+    }, async ({ sourceDir, usernameOrAlias, directory, manifest }) => {
         if (sourceDir && manifest) {
             return textResponse("You can't specify both `sourceDir` and `manifest` parameters.", true);
         }

package/lib/tools/orgs/sf-list-all-orgs.js

@@ -41,7 +41,11 @@ Example usage:
 Can you list all Salesforce orgs for me
 List all Salesforce orgs
 List all orgs
-`, listAllOrgsParamsSchema.shape, async ({ directory }) => {
+`, listAllOrgsParamsSchema.shape, {
+        title: 'List All Orgs',
+        readOnlyHint: true,
+        openWorldHint: false,
+    }, async ({ directory }) => {
         try {
             process.chdir(directory);
             const orgs = await getAllAllowedOrgs();

package/lib/tools/testing/index.d.ts

@@ -0,0 +1,2 @@
+export * from './sf-test-apex.js';
+export * from './sf-test-agents.js';

package/lib/tools/testing/index.js

@@ -0,0 +1,18 @@
+/*
+ * Copyright 2025, Salesforce, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export * from './sf-test-apex.js';
+export * from './sf-test-agents.js';
+//# sourceMappingURL=index.js.map

package/lib/tools/testing/sf-test-agents.d.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+import { SfMcpServer } from '../../sf-mcp-server.js';
+declare const runAgentTestsParam: z.ZodObject<{
+    agentApiName: z.ZodString;
+    usernameOrAlias: z.ZodString;
+    directory: z.ZodEffects<z.ZodString, string, string>;
+}, "strip", z.ZodTypeAny, {
+    directory: string;
+    usernameOrAlias: string;
+    agentApiName: string;
+}, {
+    directory: string;
+    usernameOrAlias: string;
+    agentApiName: string;
+}>;
+export type AgentRunTests = z.infer<typeof runAgentTestsParam>;
+export declare const registerToolRunAgentTest: (server: SfMcpServer) => void;
+export {};

package/lib/tools/testing/sf-test-agents.js

@@ -0,0 +1,73 @@
+/*
+ * Copyright 2025, Salesforce, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { z } from 'zod';
+import { AgentTester } from '@salesforce/agents';
+import { Duration } from '@salesforce/kit';
+import { directoryParam, usernameOrAliasParam } from '../../shared/params.js';
+import { textResponse } from '../../shared/utils.js';
+import { getConnection } from '../../shared/auth.js';
+const runAgentTestsParam = z.object({
+    agentApiName: z.string().describe(`Agent test to run
+            if unsure, list all files matching the pattern *.aiEvaluationDefinition-meta.xml
+            only one test can be executed at a time
+`),
+    usernameOrAlias: usernameOrAliasParam,
+    directory: directoryParam,
+});
+/*
+ * Run Agent tests in a Salesforce org.
+ *
+ * Parameters:
+ * - agentApiName: this will be the aiEvaluationDefinition's name
+ * - usernameOrAlias: Username or alias of the Salesforce org to run tests in.
+ * - directory: Directory of the local project.
+ *
+ * Returns:
+ * - textResponse: Test result.
+ */
+export const registerToolRunAgentTest = (server) => {
+    server.tool('sf-test-agents', `Run Agent tests in an org.
+
+AGENT INSTRUCTIONS:
+If the user doesn't specify what to test, take context from the currently open file
+This will ONLY run Agent tests, NOT apex tests, lightning tests, flow tests, or any other type of test.
+
+this should be chosen when a file in the 'aiEvaluationDefinitions' directory is mentioned
+
+EXAMPLE USAGE:
+Run tests for the X agent
+Run this test
+`, runAgentTestsParam.shape, {
+        title: 'Run Agent Tests',
+        openWorldHint: false,
+    }, async ({ usernameOrAlias, agentApiName, directory }) => {
+        if (!usernameOrAlias)
+            return textResponse('The usernameOrAlias parameter is required, if the user did not specify one use the #sf-get-username tool', true);
+        // needed for org allowlist to work
+        process.chdir(directory);
+        const connection = await getConnection(usernameOrAlias);
+        try {
+            const agentTester = new AgentTester(connection);
+            const test = await agentTester.start(agentApiName);
+            const result = await agentTester.poll(test.runId, { timeout: Duration.minutes(10) });
+            return textResponse(`Test result: ${JSON.stringify(result)}`);
+        }
+        catch (e) {
+            return textResponse(`Failed to run Agent Tests: ${e instanceof Error ? e.message : 'Unknown error'}`, true);
+        }
+    });
+};
+//# sourceMappingURL=sf-test-agents.js.map

package/lib/tools/testing/sf-test-apex.d.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import { TestLevel } from '@salesforce/apex-node';
+import { SfMcpServer } from '../../sf-mcp-server.js';
+declare const runApexTestsParam: z.ZodObject<{
+    testLevel: z.ZodEnum<[TestLevel.RunLocalTests, TestLevel.RunAllTestsInOrg, TestLevel.RunSpecifiedTests]>;
+    classNames: z.ZodArray<z.ZodString, "many">;
+    usernameOrAlias: z.ZodString;
+    directory: z.ZodEffects<z.ZodString, string, string>;
+}, "strip", z.ZodTypeAny, {
+    testLevel: TestLevel;
+    directory: string;
+    usernameOrAlias: string;
+    classNames: string[];
+}, {
+    testLevel: TestLevel;
+    directory: string;
+    usernameOrAlias: string;
+    classNames: string[];
+}>;
+export type ApexRunTests = z.infer<typeof runApexTestsParam>;
+export declare const registerToolRunApexTest: (server: SfMcpServer) => void;
+export {};

package/lib/tools/testing/sf-test-apex.js

@@ -0,0 +1,86 @@
+/*
+ * Copyright 2025, Salesforce, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { z } from 'zod';
+import { TestService } from '@salesforce/apex-node';
+import { directoryParam, usernameOrAliasParam } from '../../shared/params.js';
+import { textResponse } from '../../shared/utils.js';
+import { getConnection } from '../../shared/auth.js';
+const runApexTestsParam = z.object({
+    testLevel: z.enum(["RunLocalTests" /* TestLevel.RunLocalTests */, "RunAllTestsInOrg" /* TestLevel.RunAllTestsInOrg */, "RunSpecifiedTests" /* TestLevel.RunSpecifiedTests */]).describe(`Apex test level
+
+AGENT INSTRUCTIONS
+Choose the correct value based on what tests are meant to be executed in some of these ways:
+
+RunLocalTests="Run all tests in the org, except the ones that originate from installed managed and unlocked packages."
+RunAllTestsInOrg="Run all tests in the org, including tests of managed packages"
+RunSpecifiedTests="Run the Apex tests I specify, these will be specified in the classNames parameter"
+`),
+    classNames: z.array(z.string()).describe(`Apex tests classes to run.
+            if Running all tests, all tests should be listed
+            if unsure, find apex classes matching the pattern **/classes/*.cls, that include the @isTest decorator in the file and then join their test names together with ','
+`),
+    usernameOrAlias: usernameOrAliasParam,
+    directory: directoryParam,
+});
+/*
+ * Run Apex tests in a Salesforce org.
+ *
+ * Parameters:
+ * - testLevel: 'RunSpecifiedTests', 'RunLocalTests', 'RunAllTestsInOrg', used to specify the specific test-level.
+ * - classNames: if testLevel='RunSpecifiedTests', this will be the specified tests to run
+ * - usernameOrAlias: Username or alias of the Salesforce org to run tests in.
+ * - directory: Directory of the local project.
+ *
+ * Returns:
+ * - textResponse: Test result.
+ */
+export const registerToolRunApexTest = (server) => {
+    server.tool('sf-test-apex', `Run Apex tests in an org.
+
+AGENT INSTRUCTIONS:
+If the user doesn't specify what to test, take context from the currently open file
+This will ONLY run APEX tests, NOT agent tests, lightning tests, flow tests, or any other type of test.
+
+this should be chosen when a file in the 'classes' directory is mentioned
+
+EXAMPLE USAGE:
+Run tests A, B, C.
+Run the tests, find apex classes matching the pattern **/classes/*.cls, that include the @isTest decorator in the file and then join their test names together with ','
+Run all tests in the org.
+`, runApexTestsParam.shape, {
+        title: 'Apex Tests',
+        openWorldHint: false,
+    }, async ({ testLevel, usernameOrAlias, classNames, directory }) => {
+        if (testLevel !== "RunSpecifiedTests" /* TestLevel.RunSpecifiedTests */ && classNames?.length && classNames?.length >= 1) {
+            return textResponse("You can't specify which tests to run without setting testLevel='RunSpecifiedTests'", true);
+        }
+        if (!usernameOrAlias)
+            return textResponse('The usernameOrAlias parameter is required, if the user did not specify one use the #sf-get-username tool', true);
+        // needed for org allowlist to work
+        process.chdir(directory);
+        const connection = await getConnection(usernameOrAlias);
+        try {
+            const testService = new TestService(connection);
+            const payload = await testService.buildAsyncPayload(testLevel, classNames.join(','));
+            const result = (await testService.runTestAsynchronous(payload, false));
+            return textResponse(`Test result: ${JSON.stringify(result)}`);
+        }
+        catch (e) {
+            return textResponse(`Failed to run Apex Tests: ${e instanceof Error ? e.message : 'Unknown error'}`, true);
+        }
+    });
+};
+//# sourceMappingURL=sf-test-apex.js.map

package/lib/tools/users/sf-assign-permission-set.js

@@ -57,7 +57,10 @@ Set the permission set MyPermSet on behalf of my-alias.`),
     directory: directoryParam,
 });
 export const registerToolAssignPermissionSet = (server) => {
-    server.tool('sf-assign-permission-set', 'Assign a permission set to one or more org users.', assignPermissionSetParamsSchema.shape, async ({ permissionSetName, usernameOrAlias, onBehalfOf, directory }) => {
+    server.tool('sf-assign-permission-set', 'Assign a permission set to one or more org users.', assignPermissionSetParamsSchema.shape, {
+        title: 'Assign Permission Set',
+        openWorldHint: false,
+    }, async ({ permissionSetName, usernameOrAlias, onBehalfOf, directory }) => {
         try {
             if (!usernameOrAlias)
                 return textResponse('The usernameOrAlias parameter is required, if the user did not specify one use the #sf-get-username tool', true);