@salesforce/mcp 0.0.1 → 0.2.6

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

@@ -0,0 +1,122 @@
+/*
+ * 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, SfProject } from '@salesforce/core';
+import { SourceTracking } from '@salesforce/source-tracking';
+import { ComponentSetBuilder } from '@salesforce/source-deploy-retrieve';
+import { ensureString } from '@salesforce/ts-types';
+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 retrieveMetadataParams = z.object({
+    sourceDir: z
+        .array(z.string())
+        .describe('Path to the local source files to retrieve. Leave this unset if the user is vague about what to retrieve.')
+        .optional(),
+    manifest: z.string().describe('Full file path for manifest (XML file) of components to retrieve.').optional(),
+    usernameOrAlias: usernameOrAliasParam,
+    directory: directoryParam,
+});
+/*
+ * Retrieve metadata from an org to your local project.
+ *
+ * Parameters:
+ * - sourceDir: Path to the local source files to retrieve.
+ * - manifest: Full file path for manifest (XML file) of components to retrieve.
+ * - usernameOrAlias: Username or alias of the Salesforce org to retrieve from.
+ * - directory: Directory of the local project.
+ *
+ * Returns:
+ * - textResponse: Retrieve result.
+ */
+export const registerToolRetrieveMetadata = (server) => {
+    server.tool('sf-retrieve-metadata', `Retrieve metadata from an org to your local project.
+
+AGENT INSTRUCTIONS:
+If the user doesn't specify what to retrieve exactly ("retrieve my changes"), leave the "sourceDir" and "manifest" params empty so the tool calculates which files to retrieve.
+
+EXAMPLE USAGE:
+Retrieve changes
+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 }) => {
+        if (sourceDir && manifest) {
+            return textResponse("You can't specify both `sourceDir` and `manifest` parameters.", true);
+        }
+        // needed for org allowlist to work
+        process.chdir(directory);
+        const connection = await getConnection(usernameOrAlias);
+        const project = await SfProject.resolve(directory);
+        const org = await Org.create({ connection });
+        if (!sourceDir && !manifest && !(await org.tracksSource())) {
+            return textResponse('This org does not have source-tracking enabled or does not support source-tracking. You should specify the files or a manifest to retrieve.', true);
+        }
+        try {
+            const stl = await SourceTracking.create({
+                org,
+                project,
+                subscribeSDREvents: true,
+            });
+            const componentSet = await buildRetrieveComponentSet(connection, project, stl, sourceDir, manifest);
+            if (componentSet.size === 0) {
+                // STL found no changes
+                return textResponse('No remote changes to retrieve were found.');
+            }
+            const retrieve = await componentSet.retrieve({
+                usernameOrConnection: connection,
+                merge: true,
+                format: 'source',
+                output: project.getDefaultPackage().fullPath,
+            });
+            // polling freq. is set dynamically by SDR based no the component set size.
+            const result = await retrieve.pollStatus({
+                timeout: Duration.minutes(10),
+            });
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            const { zipFile, ...retrieveResult } = result.response;
+            return textResponse(`Retrieve result: ${JSON.stringify(retrieveResult)}`, !retrieveResult.success);
+            // }
+        }
+        catch (error) {
+            return textResponse(`Failed to retrieve metadata: ${error instanceof Error ? error.message : 'Unknown error'}`, true);
+        }
+    });
+};
+async function buildRetrieveComponentSet(connection, project, stl, sourceDir, manifestPath) {
+    if (sourceDir || manifestPath) {
+        return ComponentSetBuilder.build({
+            apiversion: connection.getApiVersion(),
+            sourceapiversion: ensureString((await project.resolveProjectConfig()).sourceApiVersion),
+            sourcepath: sourceDir,
+            ...(manifestPath
+                ? {
+                    manifest: {
+                        manifestPath,
+                        directoryPaths: project.getUniquePackageDirectories().map((pDir) => pDir.fullPath),
+                    },
+                }
+                : {}),
+            projectDir: project.getPath(),
+        });
+    }
+    // No specific metadata requested to retrieve, build component set from STL.
+    const cs = await stl.maybeApplyRemoteDeletesToLocal(true);
+    return cs.componentSetFromNonDeletes;
+}
+//# sourceMappingURL=sf-retrieve-metadata.js.map

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

@@ -0,0 +1 @@
+export * from './sf-list-all-orgs.js';

package/lib/tools/orgs/index.js

@@ -0,0 +1,17 @@
+/*
+ * 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-list-all-orgs.js';
+//# sourceMappingURL=index.js.map

package/lib/tools/orgs/sf-list-all-orgs.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare const registerToolListAllOrgs: (server: McpServer) => void;

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

@@ -0,0 +1,49 @@
+/*
+ * 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 { getAllAllowedOrgs } from '../../shared/auth.js';
+import { textResponse } from '../../shared/utils.js';
+/*
+ * List all Salesforce orgs
+ *
+ * Lists all configured Salesforce orgs.
+ *
+ * Parameters:
+ * - None required
+ *
+ * Returns:
+ * - textResponse: List of configured Salesforce orgs
+ */
+export const registerToolListAllOrgs = (server) => {
+    server.tool('sf-list-all-orgs', `Lists all configured Salesforce orgs.
+
+AGENT INSTRUCTIONS:
+DO NOT use this tool to try to determine which org a user wants, use #sf-get-username instead. Only use it if the user explicitly asks for a list of orgs.
+
+Example usage:
+Can you list all Salesforce orgs for me
+List all Salesforce orgs
+List all orgs
+`, {}, async () => {
+        try {
+            const orgs = await getAllAllowedOrgs();
+            return textResponse(`List of configured Salesforce orgs:\n\n${JSON.stringify(orgs, null, 2)}`);
+        }
+        catch (error) {
+            return textResponse(`Failed to list orgs: ${error instanceof Error ? error.message : 'Unknown error'}`, true);
+        }
+    });
+};
+//# sourceMappingURL=sf-list-all-orgs.js.map

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

@@ -0,0 +1 @@
+export * from './sf-assign-permission-set.js';

package/lib/tools/users/index.js

@@ -0,0 +1,17 @@
+/*
+ * 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-assign-permission-set.js';
+//# sourceMappingURL=index.js.map

package/lib/tools/users/sf-assign-permission-set.d.ts

@@ -0,0 +1,20 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+export declare const assignPermissionSetParamsSchema: z.ZodObject<{
+    permissionSetName: z.ZodString;
+    usernameOrAlias: z.ZodString;
+    onBehalfOf: z.ZodOptional<z.ZodString>;
+    directory: z.ZodEffects<z.ZodString, string, string>;
+}, "strip", z.ZodTypeAny, {
+    directory: string;
+    usernameOrAlias: string;
+    permissionSetName: string;
+    onBehalfOf?: string | undefined;
+}, {
+    directory: string;
+    usernameOrAlias: string;
+    permissionSetName: string;
+    onBehalfOf?: string | undefined;
+}>;
+export type AssignPermissionSetOptions = z.infer<typeof assignPermissionSetParamsSchema>;
+export declare const registerToolAssignPermissionSet: (server: McpServer) => void;

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

@@ -0,0 +1,84 @@
+/*
+ * 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 { Org, StateAggregator, User } from '@salesforce/core';
+import { z } from 'zod';
+import { directoryParam, usernameOrAliasParam } from '../../shared/params.js';
+import { textResponse } from '../../shared/utils.js';
+import { getConnection } from '../../shared/auth.js';
+/*
+ * Assign permission set
+ *
+ * Assign a permission set to one or more org users.
+ *
+ * Parameters:
+ * - permissionSetName: Permission set to assign (required)
+ *   Example: "Set the permission set MyPermSet", "Set the perm set MyPermSet"
+ * - usernameOrAlias: Username or alias for the Salesforce org (required)
+ * - onBehalfOf: Username or alias to assign the permission set to (optional)
+ *   Note: This is only used when "on behalf of" is explicitly mentioned.
+ *   Otherwise, the permission will be set to the usernameOrAlias user.
+ *   Example: "Set the permission set MyPermSet on behalf of my-alias"
+ *
+ * Returns:
+ * - textResponse: Permission set assignment result
+ */
+export const assignPermissionSetParamsSchema = z.object({
+    permissionSetName: z.string().describe(`A single permission set to assign
+
+EXAMPLE USAGE:
+Set the permission set MyPermSet
+Set the perm set MyPermSet`),
+    usernameOrAlias: usernameOrAliasParam,
+    onBehalfOf: z.string().optional()
+        .describe(`A single username or alias (other than the usernameOrAlias) to assign the permission set to
+
+AGENT INSTRUCTIONS:
+If the user does not specifically say "on behalf of" this will be empty.
+If the user does specifically say "on behalf of", but it is unclear what the target-org is, run the #sf-get-username tool.
+In that case, use the usernameOrAlias parameter as the org to assign the permission set to.
+
+USAGE EXAMPLE:
+Assign the permission set MyPermSet.
+Set the permission set MyPermSet on behalf of test-3uyb8kmftiu@example.com.
+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 }) => {
+        try {
+            process.chdir(directory);
+            // We build the connection from the usernameOrAlias
+            const connection = await getConnection(usernameOrAlias);
+            // We need to clear the instance so we know we have the most up to date aliases
+            // If a user sets an alias after server start up, it was not getting picked up
+            StateAggregator.clearInstance();
+            // Must NOT be nullish coalescing (??) In case the LLM uses and empty string
+            const assignTo = (await StateAggregator.getInstance()).aliases.resolveUsername(onBehalfOf || usernameOrAlias);
+            if (!assignTo.includes('@')) {
+                return textResponse('Unable to resolve the username for alias. Make sure it is correct', true);
+            }
+            const org = await Org.create({ connection });
+            const user = await User.create({ org });
+            const queryResult = await connection.singleRecordQuery(`SELECT Id FROM User WHERE Username='${assignTo}'`);
+            await user.assignPermissionSets(queryResult.Id, [permissionSetName]);
+            return textResponse(`Assigned ${permissionSetName} to ${assignTo}`);
+        }
+        catch (error) {
+            return textResponse(`Failed to assign permission set: ${error instanceof Error ? error.message : 'Unknown error'}`, true);
+        }
+    });
+};
+//# sourceMappingURL=sf-assign-permission-set.js.map