@salesforce/mcp 0.14.3 → 0.15.0

package/lib/index.js

@@ -210,6 +210,9 @@ You can also use special values to control access to orgs:
             this.logToStderr('Registering experimental tools');
             orgs.registerToolOrgOpen(server);
             // Add any experimental tools here
+            orgs.registerToolCreateScratchOrg(server);
+            orgs.registerToolDeleteOrg(server);
+            orgs.registerToolCreateOrgSnapshot(server);
         }
         const transport = new StdioServerTransport();
         await server.connect(transport);

package/lib/shared/params.js

@@ -16,7 +16,7 @@
 import { z } from 'zod';
 import { sanitizePath } from './utils.js';
 /*
- * A collection of reuseable Tool parameters
+ * A collection of reusable Tool parameters
  */
 export const usernameOrAliasParam = z.string()
     .describe(`The username or alias for the Salesforce org to run this tool against.

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

@@ -15,7 +15,7 @@
  */
 import { z } from 'zod';
 import { AgentTester } from '@salesforce/agents';
-import { validateSalesforceId, scratchOrgResume } from '@salesforce/core';
+import { validateSalesforceId, scratchOrgResume, PollingClient } from '@salesforce/core';
 import { Duration } from '@salesforce/kit';
 import { MetadataApiDeploy } from '@salesforce/source-deploy-retrieve';
 import { textResponse } from '../../shared/utils.js';
@@ -25,6 +25,7 @@ const resumableIdPrefixes = new Map([
     ['deploy', '0Af'],
     ['scratchOrg', '2SR'],
     ['agentTest', '4KB'],
+    ['orgSnapshot', '0Oo'],
 ]);
 /*
  * Resume a long running operation that was not completed by another tool.
@@ -63,6 +64,8 @@ Resume the deployment to my org
 Resume scratch org creation
 Resume job 2SR1234567890
 Resume agent tests
+Resume org snapshot with ID 0OoKa000000XZAbKAO
+Report on my org snapshot
 `, resumeParamsSchema.shape, {
         title: 'Resume',
         openWorldHint: false,
@@ -84,6 +87,8 @@ Resume agent tests
                 return resumeScratchOrg(jobId, wait);
             case resumableIdPrefixes.get('agentTest'):
                 return resumeAgentTest(connection, jobId, wait);
+            case resumableIdPrefixes.get('orgSnapshot'):
+                return resumeOrgSnapshot(connection, jobId, wait);
             default:
                 return textResponse(`The job id: ${jobId} is not resumeable.`, true);
         }
@@ -99,6 +104,29 @@ async function resumeDeployment(connection, jobId, wait) {
         return textResponse(`Resumed deployment failed: ${error instanceof Error ? error.message : 'Unknown error'}`, true);
     }
 }
+async function resumeOrgSnapshot(connection, jobId, wait) {
+    try {
+        const poller = await PollingClient.create({
+            timeout: Duration.minutes(wait),
+            frequency: Duration.seconds(30),
+            poll: async () => {
+                const queryResult = await connection.singleRecordQuery(`SELECT Status, Id, SnapshotName, Description, ExpirationDate, CreatedDate FROM OrgSnapshot WHERE Id = '${jobId}'`);
+                if (queryResult.Status !== 'In Progress') {
+                    // either done or error
+                    return { completed: true, payload: queryResult };
+                }
+                else {
+                    return { completed: false };
+                }
+            },
+        });
+        const result = await poller.subscribe();
+        return textResponse(`Org snapshot: ${JSON.stringify(result)}`);
+    }
+    catch (error) {
+        return textResponse(`Resumed org snapshot failed: ${error instanceof Error ? error.message : 'Unknown error'}`, true);
+    }
+}
 async function resumeScratchOrg(jobId, wait) {
     try {
         const result = await scratchOrgResume(jobId, Duration.minutes(wait));

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

@@ -1,2 +1,5 @@
 export * from './sf-list-all-orgs.js';
+export * from './sf-delete-org.js';
+export * from './sf-create-scratch-org.js';
+export * from './sf-create-org-snapshot.js';
 export * from './sf-org-open.js';

package/lib/tools/orgs/index.js

@@ -14,5 +14,8 @@
  * limitations under the License.
  */
 export * from './sf-list-all-orgs.js';
+export * from './sf-delete-org.js';
+export * from './sf-create-scratch-org.js';
+export * from './sf-create-org-snapshot.js';
 export * from './sf-org-open.js';
 //# sourceMappingURL=index.js.map

package/lib/tools/orgs/sf-create-org-snapshot.d.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare const createOrgSnapshotParams: z.ZodObject<{
+    directory: z.ZodEffects<z.ZodString, string, string>;
+    devHub: z.ZodString;
+    sourceOrg: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    name: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    directory: string;
+    devHub: string;
+    sourceOrg: string;
+    description?: string | undefined;
+}, {
+    directory: string;
+    devHub: string;
+    sourceOrg: string;
+    description?: string | undefined;
+    name?: string | undefined;
+}>;
+export type CreateOrgSnapshotOptions = z.infer<typeof createOrgSnapshotParams>;
+export declare const registerToolCreateOrgSnapshot: (server: McpServer) => void;

package/lib/tools/orgs/sf-create-org-snapshot.js

@@ -0,0 +1,88 @@
+/*
+ * 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 { Org } from '@salesforce/core';
+import { textResponse } from '../../shared/utils.js';
+import { directoryParam, usernameOrAliasParam } from '../../shared/params.js';
+import { getConnection } from '../../shared/auth.js';
+/*
+ * Create a new scratch org snapshot
+ *
+ * Parameters:
+ * - directory: directory to change to before running the command
+ * - devHub: Username or alias of the Dev Hub org
+ * - sourceOrg: ID or locally authenticated username or alias of scratch org to snapshot.
+ * - description: a description given to the snapshot
+ * - name: Unique name of snapshot
+ * Returns:
+ * - textResponse:
+ */
+export const createOrgSnapshotParams = z.object({
+    directory: directoryParam,
+    devHub: usernameOrAliasParam.describe('The default devhub username, use the #sf-get-username tool to get the default devhub if unsure'),
+    sourceOrg: usernameOrAliasParam.describe('The org username or alias to create a snapshot of, use the #sf-get-username tool to get the default target org if unsure'),
+    description: z.string().describe(' Description of snapshot.').optional(),
+    name: z.string().describe('Unique name of snapshot').max(15).default(Date.now().toString().substring(0, 15)),
+});
+export const registerToolCreateOrgSnapshot = (server) => {
+    server.tool('sf-create-org-snapshot', `Creates a new snapshot of an org
+
+AGENT INSTRUCTIONS:
+
+Example usage:
+Create a snapshot called 07042025
+create a snapshot called 07042025 with the description, "this is a snapshot for commit 5b1a09b1743 - new login flow working"
+create a snapshot of my MyScratch in myDevHub
+`, createOrgSnapshotParams.shape, {
+        title: 'Create a new snapshot',
+    }, async ({ directory, devHub, description, name, sourceOrg }) => {
+        try {
+            process.chdir(directory);
+            const sourceOrgId = (await Org.create({ aliasOrUsername: sourceOrg })).getOrgId();
+            const devHubConnection = await getConnection(devHub);
+            const createResponse = await devHubConnection.sobject('OrgSnapshot').create({
+                SourceOrg: sourceOrgId,
+                Description: description,
+                SnapshotName: name,
+                Content: 'metadatadata',
+            });
+            if (createResponse.success === false) {
+                return textResponse(`An error while created the org snapshot: ${JSON.stringify(createResponse)}`, true);
+            }
+            const result = await devHubConnection.singleRecordQuery(`SELECT Id,
+              SnapshotName,
+              Description,
+              Status,
+              SourceOrg,
+              CreatedDate,
+              LastModifiedDate,
+              ExpirationDate,
+              Error FROM OrgSnapshot WHERE Id = '${createResponse.id}'`);
+            return textResponse(`Successfully created the org snapshot: ${JSON.stringify(result)}`);
+        }
+        catch (error) {
+            const e = error;
+            // dev hub does not have snapshot pref enabled
+            if (e.name === 'NOT_FOUND') {
+                return textResponse("Scratch Org Snapshots isn't enabled for your Dev Hub.", true);
+            }
+            else {
+                return textResponse(`Error: ${e.name} : ${e.message}`, true);
+            }
+        }
+    });
+};
+//# sourceMappingURL=sf-create-org-snapshot.js.map

package/lib/tools/orgs/sf-create-scratch-org.d.ts

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare const createScratchOrgParams: z.ZodObject<{
+    directory: z.ZodEffects<z.ZodString, string, string>;
+    devHub: z.ZodString;
+    duration: z.ZodDefault<z.ZodNumber>;
+    edition: z.ZodOptional<z.ZodEnum<["developer", "enterprise", "group", "professional", "partner-developer", "partner-enterprise", "partner-group", "partner-professional"]>>;
+    definitionFile: z.ZodDefault<z.ZodString>;
+    alias: z.ZodOptional<z.ZodString>;
+    async: z.ZodDefault<z.ZodBoolean>;
+    setDefault: z.ZodOptional<z.ZodBoolean>;
+    snapshot: z.ZodOptional<z.ZodString>;
+    sourceOrg: z.ZodOptional<z.ZodString>;
+    username: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    orgName: z.ZodOptional<z.ZodString>;
+    adminEmail: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    duration: number;
+    async: boolean;
+    directory: string;
+    devHub: string;
+    definitionFile: string;
+    description?: string | undefined;
+    alias?: string | undefined;
+    snapshot?: string | undefined;
+    setDefault?: boolean | undefined;
+    username?: string | undefined;
+    edition?: "group" | "enterprise" | "developer" | "professional" | "partner-developer" | "partner-enterprise" | "partner-group" | "partner-professional" | undefined;
+    sourceOrg?: string | undefined;
+    orgName?: string | undefined;
+    adminEmail?: string | undefined;
+}, {
+    directory: string;
+    devHub: string;
+    duration?: number | undefined;
+    description?: string | undefined;
+    alias?: string | undefined;
+    async?: boolean | undefined;
+    snapshot?: string | undefined;
+    setDefault?: boolean | undefined;
+    username?: string | undefined;
+    edition?: "group" | "enterprise" | "developer" | "professional" | "partner-developer" | "partner-enterprise" | "partner-group" | "partner-professional" | undefined;
+    definitionFile?: string | undefined;
+    sourceOrg?: string | undefined;
+    orgName?: string | undefined;
+    adminEmail?: string | undefined;
+}>;
+export type CreateScratchOrgOptions = z.infer<typeof createScratchOrgParams>;
+export declare const registerToolCreateScratchOrg: (server: McpServer) => void;

package/lib/tools/orgs/sf-create-scratch-org.js

@@ -0,0 +1,132 @@
+/*
+ * 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 { join } from 'node:path';
+import * as fs from 'node:fs';
+import { z } from 'zod';
+import { Org, scratchOrgCreate } from '@salesforce/core';
+import { Duration } from '@salesforce/kit';
+import { textResponse } from '../../shared/utils.js';
+import { directoryParam, usernameOrAliasParam } from '../../shared/params.js';
+/*
+ * Create a new scratch org
+ *
+ * Parameters:
+ * - directory: directory to change to before running the command
+ * - usernameOrAlias: Username or alias of the Salesforce DevHub org to use to create from
+ * - duration: Duration in days of the scratch org to exist, default 7
+ * - edition: Edition of the scratch org
+ * - definitionFile: path to the scratch org definition file, default config/project-scratch-def.json
+ * - alias: Alias to use for the scratch org
+ * - async: Wait for the scratch org creation process to finish, default false
+ * - setDefault: set the newly created org as default-target-org
+ * - snapshot: The snapshot name to use when creating a scratch org
+ * - sourceOrg: 15-character ID of the org shape that the new scratch org is based on
+ * - username: Username of the scratch org admin user
+ * - description: a description given to the scratch org
+ * - orgName: Name of the scratch org
+ * - adminEmail: Email address that will be applied to the org's admin user.
+ * Returns:
+ * - textResponse:
+ */
+export const createScratchOrgParams = z.object({
+    directory: directoryParam,
+    devHub: usernameOrAliasParam.describe('The default devhub username, use the #sf-get-username tool to get the default devhub if unsure'),
+    duration: z.number().default(7).describe('number of days before the org expires'),
+    edition: z
+        .enum([
+        'developer',
+        'enterprise',
+        'group',
+        'professional',
+        'partner-developer',
+        'partner-enterprise',
+        'partner-group',
+        'partner-professional',
+    ])
+        .optional(),
+    definitionFile: z
+        .string()
+        .default(join('config', 'project-scratch-def.json'))
+        .describe('a normalized path to a scratch definition json file'),
+    alias: z.string().describe('the alias to be used for the scratch org').optional(),
+    async: z
+        .boolean()
+        .default(false)
+        .describe('Whether to wait for the org creation process to finish (false) or just quickly return the ID (true)'),
+    setDefault: z
+        .boolean()
+        .optional()
+        .describe('If true, will set the newly created scratch org to be the default-target-org'),
+    snapshot: z.string().describe('The snapshot name to use when creating a scratch org').optional(),
+    sourceOrg: z
+        .string()
+        .length(15)
+        .describe('15-character ID of the org shape that the new scratch org is based on')
+        .optional(),
+    username: z.string().describe('Username of the scratch org admin user').optional(),
+    description: z.string().describe('a description given to the scratch org').optional(),
+    orgName: z.string().describe('Name of the scratch org').optional(),
+    adminEmail: z.string().describe("Email address that will be applied to the org's admin user.").optional(),
+});
+export const registerToolCreateScratchOrg = (server) => {
+    server.tool('sf-create-scratch-org', `Creates a scratch org with the specified parameters.
+
+AGENT INSTRUCTIONS:
+
+Example usage:
+Create a scratch org
+create a scratch org with the definition file myDefinition.json that lasts 3 days
+create a scratch org aliased as MyNewOrg and set as default and don't wait for it to finish
+`, createScratchOrgParams.shape, {
+        title: 'Create a scratch org',
+    }, async ({ directory, devHub, orgName, adminEmail, description, snapshot, sourceOrg, username, edition, setDefault, async, duration, alias, definitionFile, }) => {
+        try {
+            process.chdir(directory);
+            const hubOrProd = await Org.create({ aliasOrUsername: devHub });
+            const requestParams = {
+                hubOrg: hubOrProd,
+                durationDays: duration,
+                wait: async ? Duration.minutes(0) : Duration.minutes(10),
+                orgConfig: {
+                    ...(definitionFile
+                        ? JSON.parse(await fs.promises.readFile(definitionFile, 'utf-8'))
+                        : {}),
+                    ...(edition ? { edition } : {}),
+                    ...(snapshot ? { snapshot } : {}),
+                    ...(username ? { username } : {}),
+                    ...(description ? { description } : {}),
+                    ...(orgName ? { orgName } : {}),
+                    ...(sourceOrg ? { sourceOrg } : {}),
+                    ...(adminEmail ? { adminEmail } : {}),
+                },
+                alias,
+                setDefault,
+                tracksSource: true,
+            };
+            const result = await scratchOrgCreate(requestParams);
+            if (async) {
+                return textResponse(`Successfully enqueued scratch org with job Id: ${JSON.stringify(result.scratchOrgInfo?.Id)} use the #sf-resume tool to resume this operation`);
+            }
+            else {
+                return textResponse(`Successfully created scratch org  ${JSON.stringify(result)}`);
+            }
+        }
+        catch (e) {
+            return textResponse(`Failed to create org: ${e instanceof Error ? e.message : 'Unknown error'}`, true);
+        }
+    });
+};
+//# sourceMappingURL=sf-create-scratch-org.js.map

package/lib/tools/orgs/sf-delete-org.d.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare const deleteOrgParams: z.ZodObject<{
+    directory: z.ZodEffects<z.ZodString, string, string>;
+    usernameOrAlias: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    directory: string;
+    usernameOrAlias: string;
+}, {
+    directory: string;
+    usernameOrAlias: string;
+}>;
+export type DeleteOrgOptions = z.infer<typeof deleteOrgParams>;
+export declare const registerToolDeleteOrg: (server: McpServer) => void;

package/lib/tools/orgs/sf-delete-org.js

@@ -0,0 +1,65 @@
+/*
+ * 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 { AuthRemover, Org } from '@salesforce/core';
+import { textResponse } from '../../shared/utils.js';
+import { directoryParam, usernameOrAliasParam } from '../../shared/params.js';
+/*
+ * Delete a locally authorized Salesforce org
+ *
+ * Parameters:
+ * - directory: directory to change to before running the command
+ * - usernameOrAlias: Username or alias of the Salesforce org to delete.
+ *
+ * Returns:
+ * - textResponse: Deletion request response
+ */
+export const deleteOrgParams = z.object({
+    directory: directoryParam,
+    usernameOrAlias: usernameOrAliasParam,
+});
+export const registerToolDeleteOrg = (server) => {
+    server.tool('sf-delete-org', `Deletes specified salesforce org.
+
+AGENT INSTRUCTIONS:
+ALWAYS confirm with the user before deleting an org
+
+Example usage:
+Can you delete my org
+Can you delete MyAliasedOrg
+Can you delete test-fe2n4tc8pgku@example.com
+`, deleteOrgParams.shape, {
+        title: 'Delete an Org',
+    }, async ({ directory, usernameOrAlias }) => {
+        try {
+            process.chdir(directory);
+            const org = await Org.create({ aliasOrUsername: usernameOrAlias });
+            await org.delete();
+            return textResponse(`Successfully deleted ${usernameOrAlias}`);
+        }
+        catch (e) {
+            if (e instanceof Error && e.name === 'DomainNotFoundError') {
+                // the org has expired, so remote operations won't work
+                // let's clean up the files locally
+                const authRemover = await AuthRemover.create();
+                await authRemover.removeAuth(usernameOrAlias);
+                return textResponse(`Successfully deleted ${usernameOrAlias}`);
+            }
+            return textResponse(`Failed to delete org: ${e instanceof Error ? e.message : 'Unknown error'}`, true);
+        }
+    });
+};
+//# sourceMappingURL=sf-delete-org.js.map