@salesforce/mcp 0.15.4 → 0.16.1

package/lib/scripts/create-embedding-text.js

@@ -0,0 +1,468 @@
+/*
+ * 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.
+ */
+/**
+ * Action words - verbs that describe what a command does
+ * These should get the highest weight (3x) in embedding text
+ */
+export const SF_ACTION_WORDS = [
+    // Core CRUD operations
+    'create',
+    'generate',
+    'delete',
+    'update',
+    'upsert',
+    'get',
+    'set',
+    'unset',
+    // Deployment & sync operations
+    'deploy',
+    'retrieve',
+    'push',
+    'pull',
+    'sync',
+    'convert',
+    'validate',
+    'preview',
+    // Execution operations
+    'run',
+    'execute',
+    'test',
+    'start',
+    'stop',
+    'resume',
+    'cancel',
+    'quick',
+    // Information operations
+    'list',
+    'display',
+    'show',
+    'describe',
+    'query',
+    'search',
+    'audit',
+    'check',
+    // Management operations
+    'assign',
+    'open',
+    'login',
+    'logout',
+    'install',
+    'uninstall',
+    'enable',
+    'disable',
+    'publish',
+    'report',
+    // Data operations
+    'import',
+    'export',
+    'bulk',
+    'tree',
+    'results',
+    // Package operations
+    'promote',
+    'demote',
+    'version',
+];
+/**
+ * Domain words - nouns that represent Salesforce concepts and objects
+ * These should get medium weight (2x) in embedding text
+ */
+export const SF_DOMAIN_WORDS = [
+    // Core Salesforce concepts
+    'org',
+    'metadata',
+    'project',
+    'package',
+    'source',
+    'data',
+    'user',
+    'permission',
+    'permset',
+    'permsetlicense',
+    // Development concepts
+    'apex',
+    'flow',
+    'trigger',
+    'class',
+    'component',
+    'lwc',
+    'aura',
+    'lightning',
+    'visualforce',
+    'app',
+    'tab',
+    'field',
+    'object',
+    'record',
+    'sobject',
+    // Org types
+    'scratch',
+    'sandbox',
+    'production',
+    'devhub',
+    'shape',
+    'snapshot',
+    // Metadata types
+    'layout',
+    'workflow',
+    'validation',
+    'rule',
+    'profile',
+    'role',
+    'queue',
+    'group',
+    'territory',
+    'sharing',
+    // Testing & analysis
+    'test',
+    'coverage',
+    'log',
+    'debug',
+    'trace',
+    'analyzer',
+    'doctor',
+    // AI & Agents
+    'agent',
+    'bot',
+    'template',
+    'spec',
+    'topic',
+    'action',
+    'evaluation',
+    // Data management
+    'bulk',
+    'tree',
+    'query',
+    'soql',
+    'sosl',
+    'csv',
+    'json',
+    'xml',
+    // Package management
+    'managed',
+    'unlocked',
+    'unmanaged',
+    'installed',
+    'subscriber',
+    // Community & Experience
+    'community',
+    'experience',
+    'site',
+    'portal',
+    // Custom metadata
+    'cmdt',
+    'custom',
+    'standard',
+    // Development tools
+    'plugin',
+    'command',
+    'flag',
+    'config',
+    'alias',
+    'autocomplete',
+    'help',
+    'interactive',
+    // API & Integration
+    'api',
+    'rest',
+    'graphql',
+    'soap',
+    'request',
+    'response',
+    'endpoint',
+    // Analytics
+    'analytics',
+    'dashboard',
+    'report',
+    'dataset',
+    // DevOps & Pipeline
+    'pipeline',
+    'devops',
+    'branch',
+    'git',
+    'repository',
+    'manifest',
+    // File types
+    'file',
+    'directory',
+    'path',
+    'zip',
+    'archive',
+];
+/**
+ * Modifier words - adjectives and adverbs that modify actions
+ * These should get light weight (1.5x) in embedding text
+ */
+export const SF_MODIFIER_WORDS = [
+    // Action modifiers
+    'quick',
+    'async',
+    'sync',
+    'force',
+    'dry',
+    'preview',
+    'validate',
+    'check',
+    'watch',
+    'tail',
+    'poll',
+    // Scope modifiers
+    'all',
+    'local',
+    'remote',
+    'global',
+    'default',
+    'target',
+    'source',
+    'current',
+    'recent',
+    'latest',
+    'specific',
+    // State modifiers
+    'active',
+    'inactive',
+    'enabled',
+    'disabled',
+    'tracked',
+    'untracked',
+    'deployed',
+    'pending',
+    'failed',
+    'successful',
+    // Type modifiers
+    'managed',
+    'unmanaged',
+    'unlocked',
+    'locked',
+    'protected',
+    'public',
+    'private',
+    'shared',
+    // Format modifiers
+    'formatted',
+    'raw',
+    'pretty',
+    'compact',
+    'verbose',
+    'concise',
+    'detailed',
+    'summary',
+];
+/**
+ * Context words - structural terms that provide context
+ * These should get normal weight (1x) in embedding text
+ */
+export const SF_CONTEXT_WORDS = [
+    // Structural
+    'force',
+    'sf',
+    'sfdx',
+    'cli',
+    'salesforce',
+    // Directories
+    'app',
+    'main',
+    'default',
+    'classes',
+    'objects',
+    'layouts',
+    'tabs',
+    'flows',
+    'triggers',
+    'components',
+    'static',
+    'resources',
+    // File extensions (without dots)
+    'cls',
+    'trigger',
+    'page',
+    'component',
+    'app',
+    'evt',
+    'intf',
+    'cmp',
+    'design',
+    'svg',
+    'css',
+    'js',
+    'xml',
+    'meta',
+    // Common patterns
+    'scratch',
+    'def',
+    'definition',
+    'configuration',
+    'settings',
+    'preferences',
+    'options',
+    'parameters',
+    'arguments',
+    'flags',
+    'values',
+];
+/**
+ * Synonym mappings for expanding keywords with related terms
+ * This helps match user queries that use different but related terminology
+ */
+const SYNONYM_MAP = {
+    // Action synonyms
+    deploy: ['deployment', 'deploying', 'push', 'upload', 'send'],
+    retrieve: ['pull', 'download', 'fetch', 'get', 'sync'],
+    list: ['show', 'display', 'enumerate', 'ls', 'view'],
+    create: ['make', 'generate', 'new', 'add', 'build'],
+    delete: ['remove', 'destroy', 'rm', 'drop', 'erase'],
+    update: ['modify', 'change', 'edit', 'alter', 'refresh'],
+    run: ['execute', 'start', 'launch', 'invoke'],
+    query: ['search', 'find', 'select', 'lookup'],
+    open: ['launch', 'start', 'view', 'access'],
+    login: ['authenticate', 'auth', 'signin', 'connect'],
+    logout: ['disconnect', 'signout', 'unauthenticate'],
+    install: ['add', 'setup', 'configure'],
+    uninstall: ['remove', 'delete', 'unsetup'],
+    convert: ['transform', 'migrate', 'change', 'translate'],
+    validate: ['verify', 'check', 'confirm', 'test'],
+    preview: ['view', 'show', 'display', 'check'],
+    report: ['status', 'info', 'summary', 'details'],
+    resume: ['continue', 'restart', 'proceed'],
+    cancel: ['stop', 'abort', 'terminate', 'halt'],
+    // Domain synonyms
+    org: ['organization', 'environment', 'instance', 'tenant'],
+    metadata: ['meta', 'components', 'definitions', 'config'],
+    scratch: ['dev', 'development', 'temp', 'temporary', 'trial'],
+    sandbox: ['test', 'staging', 'non-prod', 'development'],
+    production: ['prod', 'live', 'main', 'release'],
+    apex: ['code', 'classes', 'triggers', 'programming'],
+    flow: ['workflow', 'process', 'automation'],
+    component: ['comp', 'lwc', 'aura', 'element'],
+    lightning: ['lwc', 'aura', 'web-component'],
+    object: ['sobject', 'entity', 'table', 'record-type'],
+    field: ['column', 'attribute', 'property'],
+    record: ['row', 'data', 'entry', 'item'],
+    user: ['person', 'account', 'profile', 'identity'],
+    permission: ['access', 'rights', 'privileges', 'security'],
+    permset: ['permission-set', 'permissions', 'access-set'],
+    package: ['app', 'bundle', 'module', 'extension'],
+    source: ['code', 'files', 'project-files'],
+    data: ['records', 'information', 'content'],
+    test: ['testing', 'tests', 'verification', 'validation'],
+    log: ['logs', 'debug', 'trace', 'output'],
+    agent: ['bot', 'assistant', 'ai', 'chatbot'],
+    template: ['spec', 'blueprint', 'pattern', 'example'],
+    manifest: ['package-xml', 'config', 'definition'],
+    bulk: ['batch', 'mass', 'multiple', 'many'],
+    api: ['service', 'endpoint', 'interface', 'web-service'],
+    devhub: ['dev-hub', 'development-hub', 'hub'],
+    // Format synonyms
+    json: ['javascript-object-notation', 'data'],
+    xml: ['markup', 'config', 'meta'],
+    csv: ['comma-separated', 'spreadsheet', 'data'],
+    // Common user terms
+    setup: ['configure', 'install', 'create', 'initialize'],
+    config: ['configuration', 'settings', 'preferences'],
+    info: ['information', 'details', 'data', 'summary'],
+    help: ['assistance', 'documentation', 'guide', 'support'],
+};
+/**
+ * Expand a list of keywords with their synonyms
+ */
+function expandWithSynonyms(keywords) {
+    const expanded = new Set(keywords);
+    keywords.forEach((keyword) => {
+        const synonyms = SYNONYM_MAP[keyword];
+        if (synonyms) {
+            synonyms.forEach((synonym) => expanded.add(synonym));
+        }
+    });
+    return Array.from(expanded);
+}
+/**
+ * Extract keywords from a command string and categorize them
+ */
+function extractKeywords(command) {
+    const words = command
+        .toLowerCase()
+        .split(/[\s:-]+/)
+        .filter((word) => word.length > 0);
+    return {
+        actions: words.filter((word) => SF_ACTION_WORDS.includes(word)),
+        domains: words.filter((word) => SF_DOMAIN_WORDS.includes(word)),
+        modifiers: words.filter((word) => SF_MODIFIER_WORDS.includes(word)),
+        context: words.filter((word) => SF_CONTEXT_WORDS.includes(word)),
+    };
+}
+/**
+ * Create weighted embedding text for a command
+ */
+export function createWeightedEmbeddingText({ command, summary, description, examples, }) {
+    const keywords = extractKeywords(command);
+    // Expand keywords with synonyms for better matching
+    const expandedActions = expandWithSynonyms(keywords.actions);
+    const expandedDomains = expandWithSynonyms(keywords.domains);
+    const expandedModifiers = expandWithSynonyms(keywords.modifiers);
+    // Build weighted sections with cleaner formatting
+    const weightedSections = [];
+    // Primary actions (3x weight) - space-separated repetitions
+    if (keywords.actions.length > 0) {
+        const actionWords = keywords.actions.join(' ');
+        weightedSections.push(`${actionWords} ${actionWords} ${actionWords}`);
+        // Add synonyms (2x weight)
+        const synonyms = expandedActions.filter((word) => !keywords.actions.includes(word));
+        if (synonyms.length > 0) {
+            const synonymText = synonyms.join(' ');
+            weightedSections.push(`${synonymText} ${synonymText}`);
+        }
+    }
+    // Domain objects (2x weight) - space-separated repetitions
+    if (keywords.domains.length > 0) {
+        const domainWords = keywords.domains.join(' ');
+        weightedSections.push(`${domainWords} ${domainWords}`);
+        // Add synonyms (1x weight)
+        const synonyms = expandedDomains.filter((word) => !keywords.domains.includes(word));
+        if (synonyms.length > 0) {
+            weightedSections.push(synonyms.join(' '));
+        }
+    }
+    // Modifiers (1.5x weight - approximate with 1.5 repetitions)
+    if (keywords.modifiers.length > 0) {
+        const modifierWords = keywords.modifiers.join(' ');
+        weightedSections.push(`${modifierWords} ${modifierWords}`);
+        // Add modifier synonyms
+        const synonyms = expandedModifiers.filter((word) => !keywords.modifiers.includes(word));
+        if (synonyms.length > 0) {
+            weightedSections.push(synonyms.join(' '));
+        }
+    }
+    // Natural language expansion
+    if (keywords.actions.length > 0 && keywords.domains.length > 0) {
+        const primaryAction = keywords.actions[0];
+        const primaryDomain = keywords.domains[0];
+        // Core action-domain pairs
+        weightedSections.push(`${primaryAction} ${primaryDomain}`);
+        weightedSections.push(`how to ${primaryAction} ${primaryDomain}`);
+        // Add top synonym variations for better natural language matching
+        const actionSynonyms = SYNONYM_MAP[primaryAction];
+        const domainSynonyms = SYNONYM_MAP[primaryDomain];
+        if (actionSynonyms && actionSynonyms.length > 0) {
+            weightedSections.push(`${actionSynonyms[0]} ${primaryDomain}`);
+        }
+        if (domainSynonyms && domainSynonyms.length > 0) {
+            weightedSections.push(`${primaryAction} ${domainSynonyms[0]}`);
+        }
+    }
+    // Include natural content for semantic understanding
+    return `${weightedSections.join(' ')}\n\nCommand: ${command}\nSummary: ${summary}\n\nDescription: ${description}\n\nExamples:\n${examples?.join('\n') ?? 'No examples available'}`;
+}
+//# sourceMappingURL=create-embedding-text.js.map

package/lib/shared/tools.js

@@ -18,7 +18,7 @@ export const TOOLSETS = ['orgs', 'data', 'users', 'metadata', 'testing', 'experi
 /*
  * These are tools that are always enabled at startup. They cannot be disabled and they cannot be dynamically enabled.
  */
-export const CORE_TOOLS = ['sf-get-username', 'sf-resume', 'sf-enable-tool', 'sf-list-tools'];
+export const CORE_TOOLS = ['sf-get-username', 'sf-resume', 'sf-enable-tool', 'sf-list-tools', 'sf-suggest-cli-command'];
 /**
  * Determines which toolsets should be enabled based on the provided toolsets array and dynamic tools flag.
  *

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

@@ -1,2 +1,3 @@
 export * from './sf-get-username.js';
 export * from './sf-resume.js';
+export * from './sf-suggest-cli-command.js';

package/lib/tools/core/index.js

@@ -15,4 +15,5 @@
  */
 export * from './sf-get-username.js';
 export * from './sf-resume.js';
+export * from './sf-suggest-cli-command.js';
 //# sourceMappingURL=index.js.map

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

@@ -6,9 +6,9 @@ export declare const resumeParamsSchema: z.ZodObject<{
     usernameOrAlias: z.ZodString;
     directory: z.ZodEffects<z.ZodString, string, string>;
 }, "strip", z.ZodTypeAny, {
-    wait: number;
     directory: string;
     jobId: string;
+    wait: number;
     usernameOrAlias: string;
 }, {
     directory: string;

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

@@ -0,0 +1,5 @@
+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/core/sf-suggest-cli-command.js

@@ -0,0 +1,78 @@
+/*
+ * 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 { getAssets } from '../../assets.js';
+import { textResponse } from '../../shared/utils.js';
+const suggestCliCommandParamsSchema = z.object({
+    query: z.string().describe('The natural language query to suggest an `sf` command'),
+});
+/**
+ * Suggest a Salesforce CLI (sf) command based on user input.
+ */
+export const registerToolSuggestCliCommand = (server) => {
+    server.tool('sf-suggest-cli-command', "Suggests an `sf` CLI command based on a natural language query. It finds relevant commands from a local index and uses an LLM to construct the final, precise command to fulfill the user's request. Use this tool whenever a user asks for guidance on how to use the Salesforce CLI (`sf` or `sfdx`), needs help with command syntax, wants to know what command to run for a specific task, or asks questions like 'how do I...', 'what command...', or 'how to...' related to Salesforce development operations.", suggestCliCommandParamsSchema.shape, {
+        readOnlyHint: true,
+    }, async ({ query }) => {
+        const assets = await getAssets();
+        // Embed the user query
+        const queryEmbedding = await assets.embedder(query, {
+            pooling: 'mean',
+            normalize: true,
+        });
+        // Perform Semantic Search (FAISS)
+        const searchResults = assets.faissIndex.search(
+        // Convert the embedding tensor data to a flat array of numbers
+        Array.from(queryEmbedding.data), 5);
+        const topCandidateIds = searchResults.labels.slice(0, 5);
+        const contextCommands = topCandidateIds.map((id) => {
+            const command = assets.commands.find((c) => c.id === id);
+            // Remove the embedding text to avoid sending it to the LLM
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            const { embeddingText, ...commandWithoutEmbeddingText } = command;
+            return commandWithoutEmbeddingText;
+        });
+        contextCommands.forEach((command, index) => {
+            // eslint-disable-next-line no-console
+            console.error(`Command: ${command.command}, Score: ${searchResults.distances[index]}`);
+        });
+        const prompt = `System: You are a precise expert on the Salesforce CLI (sf). Your sole purpose is to construct a single, valid sf command based on the user's request and the Command Reference provided.
+- Base your answer STRICTLY on the user's request and the Command Reference.
+- If there is no command that matches the user's request, tell the user that you cannot find a command.
+- Do not use any flags or commands not listed in the reference.
+
+User Request:
+"${query}"
+
+Command Reference:
+${JSON.stringify(contextCommands, null, 2)}
+
+Notes about Flag Properties:
+- multiple: Flags that support multiple values should be specified with the '--flag value1 --flag value2' syntax.
+- dependsOn: If a flag depends on another flag, ensure that the dependent flag is included in the command.
+- atLeastOne: If a flag requires at least one of a set of flags, ensure that at least one of those flags is included in the command.
+- exactlyOne: If a flag requires exactly one of a set of flags, ensure that exactly one of those flags is included in the command.
+- exclusive: If a flag is exclusive with another flag, ensure that only one of those flags is included in the command.
+- required: If a flag is required, ensure that it is included in the command unless it has a default value.
+- relationships: If a flag has relationships with other flags, ensure that those relationships are respected in the command.
+- options: If a flag has options, ensure that one of those options is used
+
+
+Synthesize the single "sf" command that best fulfills the user's request.
+`;
+        return textResponse(prompt);
+    });
+};
+//# sourceMappingURL=sf-suggest-cli-command.js.map

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

@@ -23,7 +23,8 @@ export function registerToolEnableTool(server) {
     server.tool('sf-enable-tool', `Enable one of the tools the Salesforce MCP server provides.
 
 AGENT INSTRUCTIONS:
-use sf-list-all-tools first to learn what tools are available for enabling'`, enableToolParamsSchema.shape, {
+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.`, enableToolParamsSchema.shape, {
         title: 'Enable an individual tool',
         readOnlyHint: true,
         openWorldHint: false,

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

@@ -19,10 +19,15 @@ export function registerToolListTools(server) {
     server.tool('sf-list-tools', `List all available tools this Salesforce MCP server can offer, providing the enabled status and description of each.
 
 AGENT INSTRUCTIONS:
-Use this when a task could be achieved with a MCP tool and the currently available tools aren't enough.
-If there's a tool that can accomplish the user's request, do not use this tool.
-Once you find the tool you want to enable, call sf-enable-tool with the tool name.
-Once you have enabled the tool, you can invoke the tool to accomplish the user's request.`, {
+DO NOT USE THIS TOOL if you already know what tool you need - try to call the tool directly first.
+ONLY use this tool if:
+1. You tried to call a tool and got an error that it doesn't exist or isn't enabled
+2. You genuinely don't know what tools are available for a specific task
+3. You need to discover new tools for an unfamiliar use case
+
+If you find a tool you want to enable, call sf-enable-tool with the tool name.
+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.
+Once a tool has been enabled, you do not need to call sf-list-tools again - instead, invoke the desired tool directly.`, {
         title: 'List all individual tools',
         readOnlyHint: true,
         openWorldHint: false,

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

@@ -10,16 +10,16 @@ declare const deployMetadataParams: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     directory: string;
     usernameOrAlias: string;
-    manifest?: string | undefined;
     sourceDir?: string[] | undefined;
-    apexTestLevel?: "RunLocalTests" | "RunAllTestsInOrg" | "NoTestRun" | undefined;
+    manifest?: string | undefined;
+    apexTestLevel?: "NoTestRun" | "RunLocalTests" | "RunAllTestsInOrg" | undefined;
     apexTests?: string[] | undefined;
 }, {
     directory: string;
     usernameOrAlias: string;
-    manifest?: string | undefined;
     sourceDir?: string[] | undefined;
-    apexTestLevel?: "RunLocalTests" | "RunAllTestsInOrg" | "NoTestRun" | undefined;
+    manifest?: string | undefined;
+    apexTestLevel?: "NoTestRun" | "RunLocalTests" | "RunAllTestsInOrg" | undefined;
     apexTests?: string[] | undefined;
 }>;
 export type DeployMetadata = z.infer<typeof deployMetadataParams>;

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

@@ -16,8 +16,8 @@ export declare const createOrgSnapshotParams: z.ZodObject<{
     directory: string;
     devHub: string;
     sourceOrg: string;
-    description?: string | undefined;
     name?: string | undefined;
+    description?: string | undefined;
 }>;
 export type CreateOrgSnapshotOptions = z.infer<typeof createOrgSnapshotParams>;
 export declare const registerToolCreateOrgSnapshot: (server: McpServer) => void;