@salesforce/mcp 0.15.3 → 0.16.0

package/README.md

@@ -55,7 +55,7 @@ But you're not limited to using only VS Code and Copilot! You can [configure man
 
 For the best getting-started experience, make sure that you have a Salesforce DX environment set up on your computer. In particular:
 
-- [Install Salesforce CLI](https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_setup_intro.htm) on your computer. 
+- [Install Salesforce CLI](https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_setup_intro.htm) on your computer.
 - [Install VS Code](https://code.visualstudio.com/docs) on your computer.
 - [Create a Salesforce DX project](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_ws_create_new.htm) and open it in VS Code. You can also clone an example repo, such as [dreamhouse-lwc](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_intro_sample_repo.htm), which is a ready-to-use DX project that contains a simple Salesforce application, with metadata and test data.
 - [Authorize at least one Salesforce org](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_auth_web_flow.htm) to use with your DX project. You can also create a scratch org.

package/lib/assets.d.ts

@@ -0,0 +1,44 @@
+import faiss from 'faiss-node';
+import { FeatureExtractionPipeline } from '@huggingface/transformers';
+type CommandData = {
+    id: number;
+    command: string;
+    summary: string;
+    description: string;
+    examples?: string[];
+    flags?: Array<{
+        name: string;
+        description: string;
+        type?: string;
+        required?: boolean;
+        options?: string[];
+        atLeastOne?: boolean;
+        exactlyOne?: boolean;
+        relationships?: string[];
+        default?: string | boolean | number | string[];
+    }>;
+    embeddingText: string;
+};
+type Assets = {
+    commands: CommandData[];
+    commandNames: string[];
+    faissIndex: faiss.IndexFlatL2;
+    embedder: FeatureExtractionPipeline;
+};
+/**
+ * Conditionally builds or rebuilds a FAISS index based on its existence and age.
+ *
+ * This function checks if a FAISS index file exists in the specified output directory.
+ * If the index exists but is older than one week, it triggers a rebuild. If the index
+ * doesn't exist, it initiates the initial build process. The build process can run as a
+ * detached child process or in the same process depending on the detached parameter.
+ *
+ * @param outputDir - The directory path where the FAISS index should be located or created
+ * @param detached - Whether to run the build process detached (default: true)
+ *
+ * @remarks
+ * - Sets the global CACHED_DATA_DIR variable to the provided outputDir. This is used to locate the index file.
+ */
+export declare function maybeBuildIndex(outputDir: string, detached?: boolean): Promise<void>;
+export declare function getAssets(): Promise<Assets>;
+export {};

package/lib/assets.js

@@ -0,0 +1,126 @@
+/*
+ * 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 fs from 'node:fs';
+import { resolve, join } from 'node:path';
+import { spawn } from 'node:child_process';
+import faiss from 'faiss-node';
+import { pipeline } from '@huggingface/transformers';
+import { ux } from '@oclif/core';
+let CACHED_DATA_DIR = null;
+/**
+ * Conditionally builds or rebuilds a FAISS index based on its existence and age.
+ *
+ * This function checks if a FAISS index file exists in the specified output directory.
+ * If the index exists but is older than one week, it triggers a rebuild. If the index
+ * doesn't exist, it initiates the initial build process. The build process can run as a
+ * detached child process or in the same process depending on the detached parameter.
+ *
+ * @param outputDir - The directory path where the FAISS index should be located or created
+ * @param detached - Whether to run the build process detached (default: true)
+ *
+ * @remarks
+ * - Sets the global CACHED_DATA_DIR variable to the provided outputDir. This is used to locate the index file.
+ */
+export async function maybeBuildIndex(outputDir, detached = true) {
+    CACHED_DATA_DIR = outputDir;
+    const faissIndexPath = join(outputDir, 'faiss-index.bin');
+    try {
+        const stats = fs.statSync(faissIndexPath);
+        const oneWeekAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
+        ux.stderr(`Checking FAISS index in ${outputDir}...`);
+        ux.stderr(`Last modified: ${stats.mtime.toString()}`);
+        if (stats.mtime < oneWeekAgo) {
+            ux.stderr(`FAISS index is more than 1 week old - rebuilding in ${outputDir}...`);
+            await spawnBuildScript(outputDir, detached);
+        }
+        else {
+            ux.stderr(`FAISS index is up to date in ${outputDir}. No rebuild needed.`);
+        }
+    }
+    catch (error) {
+        // File doesn't exist, so build the index
+        ux.stderr(`Building FAISS index in ${outputDir}...`);
+        await spawnBuildScript(outputDir, detached);
+    }
+}
+function spawnBuildScript(outputDir, detached) {
+    const scriptPath = resolve(import.meta.dirname, 'scripts', 'build-index.js');
+    const args = [scriptPath, outputDir];
+    if (detached) {
+        spawn('node', args, {
+            detached: true,
+            stdio: 'ignore',
+        }).unref();
+        return Promise.resolve();
+    }
+    else {
+        return new Promise((res, reject) => {
+            const childProcess = spawn('node', args, {
+                stdio: 'inherit',
+            });
+            childProcess.on('close', (code) => {
+                if (code === 0) {
+                    res();
+                }
+                else {
+                    reject(new Error(`Build script exited with code ${code ?? 'UNKNOWN'}`));
+                }
+            });
+            childProcess.on('error', (error) => {
+                reject(error);
+            });
+        });
+    }
+}
+export async function getAssets() {
+    if (!CACHED_DATA_DIR) {
+        throw new Error('Data directory not set. Please call maybeBuildIndex first.');
+    }
+    // Ensure the index is built or rebuilt if necessary
+    await maybeBuildIndex(CACHED_DATA_DIR, false);
+    const commandsPath = join(CACHED_DATA_DIR, 'sf-commands.json');
+    const faissIndexPath = join(CACHED_DATA_DIR, 'faiss-index.bin');
+    try {
+        await fs.promises.access(commandsPath);
+    }
+    catch {
+        throw new Error(`Commands file not found at ${commandsPath}. Please run maybeBuildIndex to build the index.`);
+    }
+    try {
+        await fs.promises.access(faissIndexPath);
+    }
+    catch {
+        throw new Error(`FAISS index not found at ${faissIndexPath}. Please run maybeBuildIndex to build the index.`);
+    }
+    try {
+        const commandsData = await fs.promises.readFile(commandsPath, 'utf-8');
+        const commands = JSON.parse(commandsData);
+        const faissIndex = faiss.IndexFlatL2.read(faissIndexPath);
+        const embedder = await pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2', {
+            dtype: 'fp32',
+        });
+        return {
+            commands,
+            commandNames: commands.map((cmd) => cmd.command),
+            faissIndex,
+            embedder,
+        };
+    }
+    catch (error) {
+        throw new Error(`Failed to load assets: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}
+//# sourceMappingURL=assets.js.map

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" | "experimental" | "metadata" | "all" | "users" | "orgs" | "testing")[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        toolsets: import("@oclif/core/interfaces").OptionFlag<("all" | "users" | "data" | "orgs" | "metadata" | "testing" | "experimental")[] | undefined, 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

@@ -26,6 +26,7 @@ import * as dynamic from './tools/dynamic/index.js';
 import Cache from './shared/cache.js';
 import { Telemetry } from './telemetry.js';
 import { SfMcpServer } from './sf-mcp-server.js';
+import { maybeBuildIndex } from './assets.js';
 import { determineToolsetsToEnable, TOOLSETS } from './shared/tools.js';
 /**
  * Sanitizes an array of org usernames by replacing specific orgs with a placeholder.
@@ -138,6 +139,7 @@ You can also use special values to control access to orgs:
             telemetry: this.telemetry,
             dynamicTools: flags['dynamic-tools'] ?? false,
         });
+        await maybeBuildIndex(this.config.dataDir);
         const toolsetsToEnable = determineToolsetsToEnable(flags.toolsets ?? ['all'], flags['dynamic-tools'] ?? false);
         // ************************
         // CORE TOOLS (always on)
@@ -150,6 +152,7 @@ You can also use special values to control access to orgs:
         // get username
         core.registerToolGetUsername(server);
         core.registerToolResume(server);
+        core.registerToolSuggestCliCommand(server);
         // DYNAMIC TOOLSETS
         // ************************
         if (toolsetsToEnable.dynamic) {

package/lib/scripts/build-index.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/scripts/build-index.js

@@ -0,0 +1,124 @@
+/*
+ * 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 { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { Args, Parser, ux } from '@oclif/core';
+import { pipeline } from '@huggingface/transformers';
+import faiss from 'faiss-node';
+import { createWeightedEmbeddingText } from './create-embedding-text.js';
+const normalizeCommandName = (command) => (command ?? '').split(':').join(' ');
+const main = async () => {
+    const { args: { outputDir }, } = await Parser.parse(process.argv.slice(2), {
+        args: {
+            outputDir: Args.string({
+                description: 'Directory to save the output files',
+                required: true,
+            }),
+        },
+    });
+    if (!outputDir) {
+        ux.stderr('Output directory not specified. Please provide a path as the first argument.');
+        process.exit(1);
+    }
+    // Define the output file paths
+    const commandsPath = path.join(outputDir, 'sf-commands.json');
+    const faissIndexPath = path.join(outputDir, 'faiss-index.bin');
+    ux.stderr('Starting offline data preparation...');
+    // 1. Ensure output directory exists
+    if (!fs.existsSync(outputDir)) {
+        fs.mkdirSync(outputDir);
+    }
+    // 2. Get Command Data from Salesforce CLI
+    ux.stderr('Fetching commands from sf CLI...');
+    const rawCommandsJson = execSync('sf commands --json').toString();
+    const rawCommands = JSON.parse(rawCommandsJson);
+    // 3. Process and Clean the Data
+    ux.stderr('Processing and cleaning command data...');
+    const commandsData = rawCommands.map((cmd, index) => ({
+        id: index, // Use our own sequential ID for FAISS
+        command: normalizeCommandName(cmd.id),
+        summary: cmd.summary ?? 'No summary available.',
+        description: cmd.description ?? 'No description available.',
+        examples: cmd.examples ?? [],
+        flags: Object.values(cmd.flags ?? {})
+            .filter((flag) => !flag.hidden)
+            .map((flag) => ({
+            name: flag.name,
+            summary: flag.summary ?? 'No summary available.',
+            description: flag.description ?? 'No description available.',
+            type: flag.type ?? 'string',
+            required: flag.required ?? false,
+            // @ts-expect-error because options doesn't exist on boolean flags
+            options: (flag.options ?? []),
+            // @ts-expect-error because multiple doesn't exist on boolean flags
+            multiple: !!flag.multiple,
+            dependsOn: flag.dependsOn,
+            exclusive: flag.exclusive,
+            atLeastOne: flag.atLeastOne,
+            exactlyOne: flag.exactlyOne,
+            relationships: flag.relationships,
+            default: flag.default,
+        })),
+        // Create a more descriptive text for better embedding quality
+        // This will be stripped from the final output sent to the LLM to save token count
+        embeddingText: createWeightedEmbeddingText({
+            command: normalizeCommandName(cmd.id),
+            summary: cmd.summary ?? '',
+            description: cmd.description ?? '',
+            examples: cmd.examples ?? [],
+        }),
+    }));
+    if (commandsData.length === 0) {
+        ux.stderr('No command data could be processed. Is `sf` CLI installed and working?');
+        return;
+    }
+    ux.stderr(`Processed ${commandsData.length} commands.`);
+    // 4. Generate Embeddings
+    ux.stderr('Loading embedding model... (This may take a moment)');
+    const embedder = await pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2', {
+        dtype: 'fp32',
+    });
+    ux.stderr('Generating embeddings for all commands...');
+    const embeddings = await Promise.all(commandsData.map((cmd) => embedder(cmd.embeddingText, { pooling: 'mean', normalize: true })));
+    // The output tensor needs to be converted to a flat Float32Array for FAISS
+    const embeddingDimension = embeddings[0].dims[1];
+    const flattenedEmbeddings = new Float32Array(commandsData.length * embeddingDimension);
+    embeddings.forEach((tensor, i) => {
+        flattenedEmbeddings.set(tensor.data, i * embeddingDimension);
+    });
+    ux.stderr(`Generated embeddings with dimension: ${embeddingDimension}`);
+    // 5. Build and Save the FAISS Index
+    ux.stderr('Building FAISS index...');
+    const index = new faiss.IndexFlatL2(embeddingDimension);
+    // Convert Float32Array to regular array for faiss-node
+    const embeddingsArray = Array.from(flattenedEmbeddings);
+    index.add(embeddingsArray);
+    const vectorCount = index.ntotal();
+    ux.stderr(`FAISS index built with ${String(vectorCount)} vectors.`);
+    // Use the correct method name for faiss-node
+    index.write(faissIndexPath);
+    ux.stderr(`FAISS index saved to: ${faissIndexPath}`);
+    // 6. Save the Processed Command Data
+    fs.writeFileSync(commandsPath, JSON.stringify(commandsData, null, 2));
+    ux.stderr(`Command data saved to: ${commandsPath}`);
+    ux.stderr('Offline preparation complete!');
+};
+main().catch((error) => {
+    // eslint-disable-next-line no-console
+    console.error(error);
+});
+//# sourceMappingURL=build-index.js.map

package/lib/scripts/create-embedding-text.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Action words - verbs that describe what a command does
+ * These should get the highest weight (3x) in embedding text
+ */
+export declare const SF_ACTION_WORDS: readonly string[];
+/**
+ * Domain words - nouns that represent Salesforce concepts and objects
+ * These should get medium weight (2x) in embedding text
+ */
+export declare const SF_DOMAIN_WORDS: readonly string[];
+/**
+ * Modifier words - adjectives and adverbs that modify actions
+ * These should get light weight (1.5x) in embedding text
+ */
+export declare const SF_MODIFIER_WORDS: readonly string[];
+/**
+ * Context words - structural terms that provide context
+ * These should get normal weight (1x) in embedding text
+ */
+export declare const SF_CONTEXT_WORDS: readonly string[];
+/**
+ * Create weighted embedding text for a command
+ */
+export declare function createWeightedEmbeddingText({ command, summary, description, examples, }: {
+    command: string;
+    summary: string;
+    description: string;
+    examples: string[];
+}): string;