@salesforce/mcp 0.17.1-dev.0 → 0.17.2-dev.1

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

@@ -1,109 +0,0 @@
-/*
- * 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 { textResponse } from '../../shared/utils.js';
-import { getDefaultTargetOrg, getDefaultTargetDevHub, suggestUsername } from '../../shared/auth.js';
-import { directoryParam } from '../../shared/params.js';
-/*
- * Get username for Salesforce org
- *
- * Intelligently determines the appropriate username or alias for Salesforce operations.
- *
- * Parameters:
- * - defaultTargetOrg: Force lookup of default target org (optional)
- * - defaultDevHub: Force lookup of default dev hub (optional)
- * - directory: The directory to run this tool from
- *
- * Returns:
- * - textResponse: Username/alias and org configuration
- */
-export const getUsernameParamsSchema = z.object({
-    defaultTargetOrg: z.boolean().optional().default(false).describe(`Try to find default org
-AGENT INSTRUCTIONS:
-ONLY SET TO TRUE when the user explicitly asks for the default org or default target org.
-Leave it as false when the user is vague and says something like "for my org" or "for my-alias".
-
-USAGE EXAMPLE:
-Get username for my default org
-...for my default target org`),
-    defaultDevHub: z.boolean().optional().default(false).describe(`Try to find default dev hub
-AGENT INSTRUCTIONS:
-ONLY SET TO TRUE when the user explicitly asks for the default dev hub or default target devhub.
-Leave it as false when the user is vague and says something like "for my org" or "for my-alias".
-
-USAGE EXAMPLE:
-Get username for my default dev hub
-...for my default target dev hub
-...for my default devhub`),
-    directory: directoryParam,
-});
-export const registerToolGetUsername = (server) => {
-    server.tool('sf-get-username', `Intelligently determines the appropriate username or alias for Salesforce operations.
-
-AGENT/LLM INSTRUCTIONS:
-Use this tool when uncertain which username/org a user wants for Salesforce operations.
-This tool handles three distinct scenarios:
-
-1. When defaultTargetOrg=true: Fetches the default target org configuration
-   - Use when user says "for my default org" or "for my default target org"
-
-2. When defaultDevHub=true: Fetches the default dev hub configuration
-   - Use when user says "for my default dev hub" or "for my default target dev hub"
-
-3. When both are false (default): Uses suggestUsername to intelligently determine the appropriate org
-   - Use when user is vague and says something like "for my org" or doesn't specify
-
-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, {
-        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:
-1. If it is default target-org or target-dev-hub ('.key' on the config)
-2. The value of '.location' on the config
-3. The value of '.value' on the config
-4. IF '.cached' IS TRUE, tell then we are using a cached value and if they have changed it, restart the MCP Server
-
-- Full config: ${JSON.stringify(defaultFromConfig, null, 2)}
-
-UNLESS THE USER SPECIFIES OTHERWISE, use this username for the "usernameOrAlias" parameter in future Tool calls.`);
-            // Case 1: User explicitly asked for default target org
-            if (defaultTargetOrg)
-                return generateResponse(await getDefaultTargetOrg());
-            // Case 2: User explicitly asked for default dev hub
-            if (defaultDevHub)
-                return generateResponse(await getDefaultTargetDevHub());
-            // Case 3: User was vague, so suggest a username
-            const { aliasForReference, suggestedUsername, reasoning } = await suggestUsername();
-            if (!suggestedUsername) {
-                return textResponse("No suggested username found. Please specify a username or alias explicitly. Also check the MCP server's startup args for allowlisting orgs.", true);
-            }
-            return textResponse(`
-YOU MUST inform the user that we are going to use "${suggestedUsername}" ${aliasForReference ? `(Alias: ${aliasForReference}) ` : ''}for the "usernameOrAlias" parameter.
-YOU MUST explain the reasoning for selecting this org, which is: "${reasoning}"
-UNLESS THE USER SPECIFIES OTHERWISE, use this username for the "usernameOrAlias" parameter in future Tool calls.`);
-        }
-        catch (error) {
-            return textResponse(`Failed to determine appropriate username: ${error instanceof Error ? error.message : 'Unknown error'}`, true);
-        }
-    });
-};
-//# sourceMappingURL=sf-get-username.js.map

package/lib/tools/core/sf-resume.d.ts

@@ -1,20 +0,0 @@
-import { z } from 'zod';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-export declare const resumeParamsSchema: z.ZodObject<{
-    jobId: z.ZodString;
-    wait: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
-    usernameOrAlias: z.ZodString;
-    directory: z.ZodEffects<z.ZodString, string, string>;
-}, "strip", z.ZodTypeAny, {
-    directory: string;
-    jobId: string;
-    wait: number;
-    usernameOrAlias: string;
-}, {
-    directory: string;
-    jobId: string;
-    usernameOrAlias: string;
-    wait?: number | undefined;
-}>;
-export type ResumeParamsSchema = z.infer<typeof resumeParamsSchema>;
-export declare const registerToolResume: (server: McpServer) => void;

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

@@ -1,149 +0,0 @@
-/*
- * 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 { validateSalesforceId, scratchOrgResume, PollingClient } from '@salesforce/core';
-import { Duration } from '@salesforce/kit';
-import { MetadataApiDeploy } from '@salesforce/source-deploy-retrieve';
-import { textResponse } from '../../shared/utils.js';
-import { directoryParam, usernameOrAliasParam } from '../../shared/params.js';
-import { getConnection } from '../../shared/auth.js';
-const resumableIdPrefixes = new Map([
-    ['deploy', '0Af'],
-    ['scratchOrg', '2SR'],
-    ['agentTest', '4KB'],
-    ['orgSnapshot', '0Oo'],
-]);
-/*
- * Resume a long running operation that was not completed by another tool.
- *
- * Intelligently determines the appropriate username or alias for Salesforce operations.
- *
- * Parameters:
- * - jobId: The job id of the long running operation to resume (required)
- * - wait: The amount of time to wait for the operation to complete in minutes (optional)
- * - defaultTargetOrg: Force lookup of default target org (optional)
- * - directory: The directory to run this tool from
- *
- * Returns:
- * - textResponse: Username/alias and org configuration
- */
-export const resumeParamsSchema = z.object({
-    jobId: z.string().describe('The job id of the long running operation to resume (required)'),
-    wait: z
-        .number()
-        .optional()
-        .default(30)
-        .describe('The amount of time to wait for the operation to complete in minutes (optional)'),
-    usernameOrAlias: usernameOrAliasParam,
-    directory: directoryParam,
-});
-export const registerToolResume = (server) => {
-    server.tool('sf-resume', `Resume a long running operation that was not completed by another tool.
-
-AGENT INSTRUCTIONS:
-Use this tool to resume a long running operation.
-
-EXAMPLE USAGE:
-Resume the metadata deploy job 0Af1234567890
-Resume the deployment and wait for 10 minutes
-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,
-    }, async ({ jobId, wait, usernameOrAlias, directory }) => {
-        if (!jobId) {
-            return textResponse('The jobId parameter is required.', true);
-        }
-        if (!validateSalesforceId(jobId)) {
-            return textResponse('The jobId parameter is not a valid Salesforce id.', true);
-        }
-        if (!usernameOrAlias)
-            return textResponse('The usernameOrAlias parameter is required, if the user did not specify one use the #sf-get-username tool', true);
-        process.chdir(directory);
-        const connection = await getConnection(usernameOrAlias);
-        switch (jobId.substring(0, 3)) {
-            case resumableIdPrefixes.get('deploy'):
-                return resumeDeployment(connection, jobId, wait);
-            case resumableIdPrefixes.get('scratchOrg'):
-                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);
-        }
-    });
-};
-async function resumeDeployment(connection, jobId, wait) {
-    try {
-        const deploy = new MetadataApiDeploy({ usernameOrConnection: connection, id: jobId });
-        const result = await deploy.pollStatus({ timeout: Duration.minutes(wait) });
-        return textResponse(`Deploy result: ${JSON.stringify(result.response)}`, !result.response.success);
-    }
-    catch (error) {
-        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));
-        return textResponse(`Scratch org created: ${JSON.stringify(result)}`, false);
-    }
-    catch (error) {
-        return textResponse(`Resumed scratch org creation failed: ${error instanceof Error ? error.message : 'Unknown error'}`, true);
-    }
-}
-async function resumeAgentTest(connection, jobId, wait) {
-    try {
-        const agentTester = new AgentTester(connection);
-        const result = await agentTester.poll(jobId, { timeout: Duration.minutes(wait) });
-        return textResponse(`Agent test result: ${JSON.stringify(result)}`, !!result.errorMessage);
-    }
-    catch (error) {
-        return textResponse(`Resumed agent test failed: ${error instanceof Error ? error.message : 'Unknown error'}`, true);
-    }
-}
-//# sourceMappingURL=sf-resume.js.map

package/lib/tools/core/sf-suggest-cli-command.d.ts

@@ -1,5 +0,0 @@
-import { SfMcpServer } from '../../sf-mcp-server.js';
-/**
- * Suggest a Salesforce CLI (sf) command based on user input.
- */
-export declare const registerToolSuggestCliCommand: (server: SfMcpServer) => void;

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

@@ -1 +0,0 @@
-export * from './sf-query-org.js';

package/lib/tools/data/index.js

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

package/lib/tools/data/sf-query-org.d.ts

@@ -1,20 +0,0 @@
-import { z } from 'zod';
-import { SfMcpServer } from '../../sf-mcp-server.js';
-export declare const queryOrgParamsSchema: z.ZodObject<{
-    query: z.ZodString;
-    usernameOrAlias: z.ZodString;
-    directory: z.ZodEffects<z.ZodString, string, string>;
-    useToolingApi: z.ZodOptional<z.ZodBoolean>;
-}, "strip", z.ZodTypeAny, {
-    query: string;
-    directory: string;
-    usernameOrAlias: string;
-    useToolingApi?: boolean | undefined;
-}, {
-    query: string;
-    directory: string;
-    usernameOrAlias: string;
-    useToolingApi?: boolean | undefined;
-}>;
-export type QueryOrgOptions = z.infer<typeof queryOrgParamsSchema>;
-export declare const registerToolQueryOrg: (server: SfMcpServer) => void;

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

@@ -1,66 +0,0 @@
-/*
- * 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.
- */
-/*
- * Query Salesforce org
- *
- * Run a SOQL query against a Salesforce org.
- *
- * Parameters:
- * - query: SOQL query to run (required)
- * - usernameOrAlias: username or alias for the Salesforce org to run the query against
- *
- * Returns:
- * - textResponse: SOQL query results
- */
-import { z } from 'zod';
-import { getConnection } from '../../shared/auth.js';
-import { textResponse } from '../../shared/utils.js';
-import { directoryParam, usernameOrAliasParam, useToolingApiParam } from '../../shared/params.js';
-export const queryOrgParamsSchema = z.object({
-    query: z.string().describe('SOQL query to run'),
-    usernameOrAlias: usernameOrAliasParam,
-    directory: directoryParam,
-    useToolingApi: useToolingApiParam,
-});
-export const registerToolQueryOrg = (server) => {
-    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, useToolingApi }) => {
-        try {
-            if (!usernameOrAlias)
-                return textResponse('The usernameOrAlias parameter is required, if the user did not specify one use the #sf-get-username tool', true);
-            process.chdir(directory);
-            const connection = await getConnection(usernameOrAlias);
-            const result = useToolingApi ? await connection.tooling.query(query) : await connection.query(query);
-            return textResponse(`SOQL query results:\n\n${JSON.stringify(result, null, 2)}`);
-        }
-        catch (error) {
-            let errorMessage = error instanceof Error ? error.message : 'Unknown error';
-            if (errorMessage.endsWith('is not supported.')) {
-                if (useToolingApi) {
-                    errorMessage += '\nTry not using the Tooling API for this query.';
-                }
-                else {
-                    errorMessage += '\nTry using the Tooling API for this query.';
-                }
-            }
-            return textResponse(`Failed to query org: ${errorMessage}`, true);
-        }
-    });
-};
-//# sourceMappingURL=sf-query-org.js.map

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

@@ -1,2 +0,0 @@
-export { registerToolEnableTools } from './sf-enable-tools.js';
-export { registerToolListTools } from './sf-list-tools.js';

package/lib/tools/dynamic/index.js

@@ -1,18 +0,0 @@
-/*
- * 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 { registerToolEnableTools } from './sf-enable-tools.js';
-export { registerToolListTools } from './sf-list-tools.js';
-//# sourceMappingURL=index.js.map

package/lib/tools/dynamic/sf-enable-tools.d.ts

@@ -1,2 +0,0 @@
-import { SfMcpServer } from '../../sf-mcp-server.js';
-export declare function registerToolEnableTools(server: SfMcpServer): void;

package/lib/tools/dynamic/sf-enable-tools.js

@@ -1,42 +0,0 @@
-/*
- * 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 { textResponse } from '../../shared/utils.js';
-import { enableTools } from '../../shared/tools.js';
-const enableToolsParamsSchema = z.object({
-    tools: z.array(z.string()).describe('The names of the tools to enable'),
-});
-export function registerToolEnableTools(server) {
-    server.tool('sf-enable-tools', `Enable one or more of the tools the Salesforce MCP server provides.
-
-AGENT INSTRUCTIONS:
-Use sf-list-all-tools first to learn what tools are available for enabling.
-Once you have enabled the tool, you MUST invoke that tool to accomplish the user's original request - DO NOT USE A DIFFERENT TOOL OR THE COMMAND LINE.`, enableToolsParamsSchema.shape, {
-        title: 'Enable Salesforce MCP tools',
-        readOnlyHint: true,
-        openWorldHint: false,
-    }, async ({ tools }) => {
-        if (tools.length === 0) {
-            return textResponse('No tools specified to enable.', true);
-        }
-        const results = await enableTools(tools);
-        server.sendToolListChanged();
-        const hasError = results.some((result) => !result.success);
-        const resultMessages = results.map((result) => result.message).join('\n');
-        return textResponse(resultMessages, hasError);
-    });
-}
-//# sourceMappingURL=sf-enable-tools.js.map

package/lib/tools/dynamic/sf-list-tools.d.ts

@@ -1,2 +0,0 @@
-import { SfMcpServer } from '../../sf-mcp-server.js';
-export declare function registerToolListTools(server: SfMcpServer): void;

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

@@ -1,2 +0,0 @@
-export * from './sf-deploy-metadata.js';
-export * from './sf-retrieve-metadata.js';

package/lib/tools/metadata/index.js

@@ -1,18 +0,0 @@
-/*
- * 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-deploy-metadata.js';
-export * from './sf-retrieve-metadata.js';
-//# sourceMappingURL=index.js.map

package/lib/tools/metadata/sf-deploy-metadata.d.ts

@@ -1,27 +0,0 @@
-import { z } from 'zod';
-import { SfMcpServer } from '../../sf-mcp-server.js';
-declare const deployMetadataParams: z.ZodObject<{
-    sourceDir: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    manifest: z.ZodOptional<z.ZodString>;
-    apexTestLevel: z.ZodOptional<z.ZodEnum<["NoTestRun", "RunLocalTests", "RunAllTestsInOrg"]>>;
-    apexTests: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    usernameOrAlias: z.ZodString;
-    directory: z.ZodEffects<z.ZodString, string, string>;
-}, "strip", z.ZodTypeAny, {
-    directory: string;
-    usernameOrAlias: string;
-    sourceDir?: string[] | undefined;
-    manifest?: string | undefined;
-    apexTestLevel?: "NoTestRun" | "RunLocalTests" | "RunAllTestsInOrg" | undefined;
-    apexTests?: string[] | undefined;
-}, {
-    directory: string;
-    usernameOrAlias: string;
-    sourceDir?: string[] | undefined;
-    manifest?: string | undefined;
-    apexTestLevel?: "NoTestRun" | "RunLocalTests" | "RunAllTestsInOrg" | undefined;
-    apexTests?: string[] | undefined;
-}>;
-export type DeployMetadata = z.infer<typeof deployMetadataParams>;
-export declare const registerToolDeployMetadata: (server: SfMcpServer) => void;
-export {};