@salesforce/mcp 0.17.1 → 0.17.2-dev.2

package/lib/{modules/platform-cli → tools}/sf-suggest-cli-command.js

@@ -14,16 +14,30 @@
  * 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'),
-});
+import { McpTool, Toolset } from '@salesforce/mcp-provider-api';
+import { getAssets } from '../utils/assets.js';
 /**
  * Suggest a Salesforce CLI (sf) command based on user input.
  */
-export const suggestCliCommand = (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.
+const suggestCliCommandParamsSchema = z.object({
+    query: z.string().describe('The natural language query to suggest an `sf` command'),
+});
+export class SuggestCliCommandMcpTool extends McpTool {
+    services;
+    constructor(services) {
+        super();
+        this.services = services;
+    }
+    getToolsets() {
+        return [Toolset.CORE];
+    }
+    getName() {
+        return 'sf-suggest-cli-command';
+    }
+    getConfig() {
+        return {
+            title: 'Suggest CLI Command',
+            description: `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.
 
 AGENT INSTRUCTIONS:
 Use this tool whenever a user:
@@ -34,22 +48,28 @@ Use this tool whenever a user:
 NEVER use this tool for enabling Salesforce MCP tools (use sf-enable-tools instead).
 NEVER use this tool for listing available Salesforce MCP tools (use sf-list-tools instead).
 NEVER use this tool for understanding the Salesforce MCP server's capabilities.
-NEVER use this tool for understanding the input schema of a Salesforce MCP tool.`, suggestCliCommandParamsSchema.shape, {
-        readOnlyHint: true,
-    }, async ({ query }) => {
-        const assets = await getAssets();
+NEVER use this tool for understanding the input schema of a Salesforce MCP tool.`,
+            inputSchema: suggestCliCommandParamsSchema.shape,
+            outputSchema: undefined,
+            annotations: {
+                readOnlyHint: true,
+            },
+        };
+    }
+    async exec(input) {
+        const assets = await getAssets(this.services.getConfigService().getDataDir(), 'sf-commands.json', 'commands-index.bin');
         // Embed the user query
-        const queryEmbedding = await assets.embedder(query, {
+        const queryEmbedding = await assets.embedder(input.query, {
             pooling: 'mean',
             normalize: true,
         });
         // Perform Semantic Search (FAISS)
-        const searchResults = assets.faissIndex.search(
+        const searchResults = assets.index.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);
+            const command = assets.data.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;
@@ -65,7 +85,7 @@ NEVER use this tool for understanding the input schema of a Salesforce MCP tool.
 - Do not use any flags or commands not listed in the reference.
 
 User Request:
-"${query}"
+"${input.query}"
 
 Command Reference:
 ${JSON.stringify(contextCommands, null, 2)}
@@ -83,7 +103,15 @@ Notes about Flag Properties:
 
 Synthesize the single "sf" command that best fulfills the user's request.
 `;
-        return textResponse(prompt);
-    });
-};
+        return {
+            isError: false,
+            content: [
+                {
+                    type: 'text',
+                    text: prompt,
+                },
+            ],
+        };
+    }
+}
 //# sourceMappingURL=sf-suggest-cli-command.js.map

package/lib/utils/assets.d.ts

@@ -0,0 +1,21 @@
+import { FeatureExtractionPipeline } from '@huggingface/transformers';
+import faiss from 'faiss-node';
+type Assets<T> = {
+    data: T;
+    embedder: FeatureExtractionPipeline;
+    index: faiss.IndexFlatL2;
+};
+/**
+ * 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 indexPath - The path to the FAISS index file.
+ * @param detached - Whether to run the build process detached (default: true)
+ */
+export declare function maybeBuildIndex(indexPath: string, detached?: boolean): Promise<void>;
+export declare function getAssets<T>(dataDir: string, dataPath: string, indexPath: string): Promise<Assets<T>>;
+export {};

package/lib/{assets.js → utils/assets.js}

@@ -19,7 +19,6 @@ 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.
  *
@@ -28,36 +27,31 @@ let CACHED_DATA_DIR = null;
  * 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 indexPath - The path to the FAISS index file.
  * @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');
+export async function maybeBuildIndex(indexPath, detached = true) {
     try {
-        const stats = fs.statSync(faissIndexPath);
+        const stats = fs.statSync(indexPath);
         const oneWeekAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
-        ux.stderr(`Checking FAISS index in ${outputDir}...`);
+        ux.stderr(`Checking FAISS index in ${indexPath}...`);
         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);
+            ux.stderr(`FAISS index is more than 1 week old - rebuilding in ${indexPath}...`);
+            await spawnBuildScript(indexPath, detached);
         }
         else {
-            ux.stderr(`FAISS index is up to date in ${outputDir}. No rebuild needed.`);
+            ux.stderr(`FAISS index is up to date in ${indexPath}. No rebuild needed.`);
         }
     }
     catch (error) {
         // File doesn't exist, so build the index
-        ux.stderr(`Building FAISS index in ${outputDir}...`);
-        await spawnBuildScript(outputDir, detached);
+        ux.stderr(`Building FAISS index in ${indexPath}...`);
+        await spawnBuildScript(indexPath, detached);
     }
 }
 function spawnBuildScript(outputDir, detached) {
-    const scriptPath = resolve(import.meta.dirname, 'scripts', 'build-index.js');
+    const scriptPath = resolve(import.meta.dirname, '..', 'scripts', 'build-index.js');
     const args = [scriptPath, outputDir];
     if (detached) {
         spawn('node', args, {
@@ -85,37 +79,33 @@ function spawnBuildScript(outputDir, detached) {
         });
     }
 }
-export async function getAssets() {
-    if (!CACHED_DATA_DIR) {
-        throw new Error('Data directory not set. Please call maybeBuildIndex first.');
-    }
+export async function getAssets(dataDir, dataPath, indexPath) {
+    const fullDataPath = join(dataDir, dataPath);
+    const fullIndexPath = join(dataDir, indexPath);
     // 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');
+    await maybeBuildIndex(fullIndexPath, false);
     try {
-        await fs.promises.access(commandsPath);
+        await fs.promises.access(fullDataPath);
     }
     catch {
-        throw new Error(`Commands file not found at ${commandsPath}. Please run maybeBuildIndex to build the index.`);
+        throw new Error(`Commands file not found at ${fullDataPath}. Please run maybeBuildIndex to build the index.`);
     }
     try {
-        await fs.promises.access(faissIndexPath);
+        await fs.promises.access(fullIndexPath);
     }
     catch {
-        throw new Error(`FAISS index not found at ${faissIndexPath}. Please run maybeBuildIndex to build the index.`);
+        throw new Error(`FAISS index not found at ${fullIndexPath}. 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 dataRaw = await fs.promises.readFile(fullDataPath, 'utf-8');
+        const data = JSON.parse(dataRaw);
+        const index = faiss.IndexFlatL2.read(fullIndexPath);
         const embedder = await pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2', {
             dtype: 'fp32',
         });
         return {
-            commands,
-            commandNames: commands.map((cmd) => cmd.command),
-            faissIndex,
+            data,
+            index,
             embedder,
         };
     }

package/lib/{shared → utils}/auth.d.ts

@@ -1,5 +1,5 @@
 import { Connection, type OrgAuthorization } from '@salesforce/core';
-import { type ConfigInfoWithCache, type SanitizedOrgAuthorization } from './types.js';
+import { type OrgConfigInfo, type SanitizedOrgAuthorization } from '@salesforce/mcp-provider-api';
 /**
  * Sanitizes org authorization data by filtering out sensitive fields
  *
@@ -7,14 +7,9 @@ import { type ConfigInfoWithCache, type SanitizedOrgAuthorization } from './type
  * @returns Array of sanitized org authorization objects with only allowed fields
  */
 export declare function sanitizeOrgs(orgs: OrgAuthorization[]): SanitizedOrgAuthorization[];
-export declare function suggestUsername(): Promise<{
-    suggestedUsername: string | undefined;
-    reasoning: string;
-    aliasForReference?: string;
-}>;
 export declare function getConnection(username: string): Promise<Connection>;
 export declare function findOrgByUsernameOrAlias(allOrgs: SanitizedOrgAuthorization[], usernameOrAlias: string): SanitizedOrgAuthorization | undefined;
 export declare function getAllAllowedOrgs(): Promise<SanitizedOrgAuthorization[]>;
 export declare function filterAllowedOrgs(orgs: SanitizedOrgAuthorization[], allowList: Set<string>): Promise<SanitizedOrgAuthorization[]>;
-export declare function getDefaultTargetOrg(): Promise<ConfigInfoWithCache | undefined>;
-export declare function getDefaultTargetDevHub(): Promise<ConfigInfoWithCache | undefined>;
+export declare function getDefaultTargetOrg(): Promise<OrgConfigInfo | undefined>;
+export declare function getDefaultTargetDevHub(): Promise<OrgConfigInfo | undefined>;

package/lib/{shared → utils}/auth.js

@@ -13,7 +13,6 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-/* eslint-disable no-console */
 import { AuthInfo, Connection, ConfigAggregator, OrgConfigProperties } from '@salesforce/core';
 import Cache from './cache.js';
 /**
@@ -36,41 +35,6 @@ export function sanitizeOrgs(orgs) {
         isExpired: org.isExpired,
     }));
 }
-export async function suggestUsername() {
-    let reasoning;
-    let suggestedUsername;
-    let aliasForReference;
-    const allAllowedOrgs = await getAllAllowedOrgs();
-    const defaultTargetOrg = await getDefaultTargetOrg();
-    const defaultTargetDevHub = await getDefaultTargetDevHub();
-    const targetOrgLocation = defaultTargetOrg?.location ? `(${defaultTargetOrg.location}) ` : '';
-    const targetDevHubLocation = defaultTargetDevHub?.location ? `(${defaultTargetDevHub.location}) ` : '';
-    if (allAllowedOrgs.length === 1) {
-        suggestedUsername = allAllowedOrgs[0].username;
-        aliasForReference = allAllowedOrgs[0].aliases?.[0];
-        reasoning = 'it was the only org found in the MCP Servers allowlisted orgs';
-    }
-    else if (defaultTargetOrg?.value) {
-        const foundOrg = findOrgByUsernameOrAlias(allAllowedOrgs, defaultTargetOrg.value);
-        suggestedUsername = foundOrg?.username;
-        aliasForReference = foundOrg?.aliases?.[0];
-        reasoning = `it is the default ${targetOrgLocation}target org`;
-    }
-    else if (defaultTargetDevHub?.value) {
-        const foundOrg = findOrgByUsernameOrAlias(allAllowedOrgs, defaultTargetDevHub.value);
-        suggestedUsername = foundOrg?.username;
-        aliasForReference = foundOrg?.aliases?.[0];
-        reasoning = `it is the default ${targetDevHubLocation}dev hub org`;
-    }
-    else {
-        reasoning = 'Error: no org was inferred. Ask the user to specify one';
-    }
-    return {
-        suggestedUsername,
-        aliasForReference,
-        reasoning,
-    };
-}
 // This function is the main entry point for Tools to get an allowlisted Connection
 export async function getConnection(username) {
     // We get all allowed orgs each call in case the directory has changed (default configs)
@@ -91,11 +55,7 @@ export function findOrgByUsernameOrAlias(allOrgs, usernameOrAlias) {
     });
 }
 export async function getAllAllowedOrgs() {
-    // Support for passing orgs via URL parameters for testing purposes
-    const url = new URL(import.meta.url);
-    const params = url.searchParams.get('orgs');
-    const paramOrg = params ? params : undefined;
-    const orgAllowList = paramOrg ? new Set([paramOrg]) : (await Cache.safeGet('allowedOrgs')) ?? new Set();
+    const orgAllowList = (await Cache.safeGet('allowedOrgs')) ?? new Set();
     // Get all orgs on the user's machine
     const allOrgs = await AuthInfo.listAllAuthorizations();
     // Sanitize the orgs to remove sensitive data
@@ -162,7 +122,7 @@ async function getDefaultConfig(property) {
     if (defaultOrgMaps[property].has(path)) {
         // If the cache has the config's path set, use the cached config
         const cachedConfig = defaultOrgMaps[property].get(path);
-        return { ...cachedConfig, cached: true };
+        return cachedConfig;
     }
     else {
         defaultOrgMaps[property].set(path, typedConfig);

package/lib/utils/registry-utils.d.ts

@@ -0,0 +1,4 @@
+import { Toolset } from '@salesforce/mcp-provider-api';
+import { SfMcpServer } from '../sf-mcp-server.js';
+import { Services } from '../services.js';
+export declare function registerToolsets(toolsets: Array<Toolset | 'all'>, useDynamicTools: boolean, server: SfMcpServer, services: Services): Promise<void>;

package/lib/utils/registry-utils.js

@@ -0,0 +1,87 @@
+/*
+ * 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 { ux } from '@oclif/core';
+import { MCP_PROVIDER_API_VERSION, Toolset, TOOLSETS, } from '@salesforce/mcp-provider-api';
+import { MCP_PROVIDER_REGISTRY } from '../registry.js';
+import { addTool } from '../utils/tools.js';
+import { createDynamicServerTools } from '../main-server-provider.js';
+export async function registerToolsets(toolsets, useDynamicTools, server, services) {
+    if (useDynamicTools) {
+        const dynamicTools = createDynamicServerTools(server);
+        ux.stderr('Registering dynamic tools');
+        // eslint-disable-next-line no-await-in-loop
+        await registerTools(dynamicTools, server, useDynamicTools);
+    }
+    else {
+        ux.stderr('Skipping registration of dynamic tools');
+    }
+    const toolsetsToEnable = toolsets.includes('all')
+        ? new Set(TOOLSETS.filter((ts) => ts !== Toolset.EXPERIMENTAL))
+        : new Set([Toolset.CORE, ...toolsets]);
+    const newToolRegistry = await createToolRegistryFromProviders(MCP_PROVIDER_REGISTRY, services);
+    for (const toolset of TOOLSETS) {
+        if (toolsetsToEnable.has(toolset)) {
+            ux.stderr(`Registering ${toolset} tools`);
+            // eslint-disable-next-line no-await-in-loop
+            await registerTools(newToolRegistry[toolset], server, useDynamicTools);
+        }
+        else {
+            ux.stderr(`Skipping registration of ${toolset} tools`);
+        }
+    }
+}
+async function registerTools(tools, server, useDynamicTools) {
+    for (const tool of tools) {
+        const registeredTool = server.registerTool(tool.getName(), tool.getConfig(), (...args) => tool.exec(...args));
+        const toolsets = tool.getToolsets();
+        if (useDynamicTools && !toolsets.includes(Toolset.CORE)) {
+            registeredTool.disable();
+        }
+        // eslint-disable-next-line no-await-in-loop
+        await addTool(registeredTool, tool.getName());
+    }
+}
+async function createToolRegistryFromProviders(providers, services) {
+    // Initialize an empty registry
+    const registry = Object.fromEntries(Object.values(Toolset).map((key) => [key, []]));
+    // Avoid calling await in a loop by first getting all the promises
+    const toolPromises = [];
+    for (const provider of providers) {
+        validateMcpProviderVersion(provider);
+        const toolsPromise = provider.provideTools(services);
+        toolPromises.push(toolsPromise);
+    }
+    // Get all the tools from the promises and then add them to the registry
+    const tools = (await Promise.all(toolPromises)).flat();
+    for (const tool of tools) {
+        for (const toolset of tool.getToolsets()) {
+            registry[toolset].push(tool);
+        }
+    }
+    return registry;
+}
+/**
+ * Validation function to confirm that providers are at the expected major version.
+ */
+function validateMcpProviderVersion(provider) {
+    if (provider.getVersion().major !== MCP_PROVIDER_API_VERSION.major) {
+        throw new Error(`The version '${provider
+            .getVersion()
+            .toString()}' for '${provider.getName()}' is incompatible with this MCP Server.\n` +
+            `Expected the major version to be '${MCP_PROVIDER_API_VERSION.major}'.`);
+    }
+}
+//# sourceMappingURL=registry-utils.js.map

package/lib/{modules/platform-cli/utils → utils}/tools.js

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import Cache from '../../../shared/cache.js';
+import Cache from './cache.js';
 /**
  * Add a tool to the cache
  */

package/lib/utils/types.d.ts

@@ -0,0 +1,5 @@
+import { RegisteredTool } from '@modelcontextprotocol/sdk/server/mcp.js';
+export type ToolInfo = {
+    tool: RegisteredTool;
+    name: string;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/mcp",
-  "version": "0.17.1",
+  "version": "0.17.2-dev.2",
   "description": "MCP Server for interacting with Salesforce instances",
   "bin": {
     "sf-mcp-server": "bin/run.js"
@@ -20,6 +20,7 @@
     "link-check": "wireit",
     "lint": "wireit",
     "lint-fix": "yarn sf-lint --fix",
+    "package": "yarn pack",
     "postpack": "sf-clean --ignore-signing-artifacts",
     "prepack": "sf-prepack",
     "prepare": "sf-install",
@@ -36,23 +37,26 @@
     "bin",
     "lib",
     "!lib/**/*.map",
-    "messages"
+    "messages",
+    "LICENSE.txt",
+    "package.json"
   ],
   "dependencies": {
     "@huggingface/transformers": "^3.7.0",
-    "@jsforce/jsforce-node": "^3.9.4",
     "@modelcontextprotocol/sdk": "^1.16.0",
     "@oclif/core": "^4.5.1",
     "@salesforce/agents": "^0.15.4",
     "@salesforce/apex-node": "^8.2.1",
     "@salesforce/core": "^8.18.0",
     "@salesforce/kit": "^3.1.6",
+    "@salesforce/mcp-provider-api": "^0.1.0",
+    "@salesforce/mcp-provider-dx-core": "^0.1.2",
+    "@salesforce/mcp-provider-code-analyzer": "^0.0.1",
     "@salesforce/source-deploy-retrieve": "^12.22.0",
     "@salesforce/source-tracking": "^7.4.8",
     "@salesforce/telemetry": "^6.1.0",
     "@salesforce/ts-types": "^2.0.11",
     "faiss-node": "^0.5.1",
-    "open": "^10.1.2",
     "zod": "^3.25.76"
   },
   "devDependencies": {