Salesforce CLI MCP Server

Instructions

Implementation Reference

• src/index.ts:66-90 (registration)

  Registers the sf_set_project_directory MCP tool with Zod input schema and inline handler that delegates to setProjectDirectory helper

  server.tool('sf_set_project_directory', 'Set a Salesforce project directory for command execution context', {
      directory: z.string().describe('The absolute path to a directory containing an sfdx-project.json file'),
      name: z.string().optional().describe('Optional name for this project root'),
      description: z.string().optional().describe('Optional description for this project root'),
      isDefault: z.boolean().optional().describe('Set this root as the default for command execution')
  }, async (params) => {
      
      // Set the project directory with optional metadata
      const result = setProjectDirectory(params.directory, {
          name: params.name,
          description: params.description,
          isDefault: params.isDefault
      });
      
      return {
          content: [
              {
                  type: 'text',
                  text: result
                      ? `Successfully set Salesforce project root: ${params.directory}${params.name ? ` with name "${params.name}"` : ''}${params.isDefault ? ' (default)' : ''}`
                      : `Failed to set project directory. Make sure the path exists and contains an sfdx-project.json file.`,
              },
          ],
      };
  });

• src/sfCommands.ts:210-280 (handler)

  Core implementation of project directory setting: validates Salesforce project (sfdx-project.json), manages projectRoots array, handles updates/defaults

  export function setProjectDirectory(
      directory: string, 
      options: { name?: string; description?: string; isDefault?: boolean } = {}
  ): boolean {
      try {
          // Validate that the directory exists and contains an sfdx-project.json file
          if (!isValidSalesforceProject(directory)) {
              console.error(`Invalid Salesforce project: ${directory}`);
              return false;
          }
          
          // Check if this root already exists
          const existingIndex = projectRoots.findIndex(root => root.path === directory);
          
          if (existingIndex >= 0) {
              // Update existing root with new options
              projectRoots[existingIndex] = {
                  ...projectRoots[existingIndex],
                  ...options,
                  path: directory
              };
              
              // If this is now the default root, update defaultRootPath
              if (options.isDefault) {
                  // Remove default flag from other roots
                  projectRoots.forEach((root, idx) => {
                      if (idx !== existingIndex) {
                          root.isDefault = false;
                      }
                  });
                  defaultRootPath = directory;
              }
              
              console.error(`Updated Salesforce project root: ${directory}`);
          } else {
              // Add as new root
              const isDefault = options.isDefault ?? (projectRoots.length === 0);
              
              projectRoots.push({
                  path: directory,
                  name: options.name || path.basename(directory),
                  description: options.description,
                  isDefault
              });
              
              // If this is now the default root, update defaultRootPath
              if (isDefault) {
                  // Remove default flag from other roots
                  projectRoots.forEach((root, idx) => {
                      if (idx !== projectRoots.length - 1) {
                          root.isDefault = false;
                      }
                  });
                  defaultRootPath = directory;
              }
              
              console.error(`Added Salesforce project root: ${directory}`);
          }
          
          // Always ensure we have exactly one default root if any roots exist
          if (projectRoots.length > 0 && !projectRoots.some(root => root.isDefault)) {
              projectRoots[0].isDefault = true;
              defaultRootPath = projectRoots[0].path;
          }
          
          return true;
      } catch (error) {
          console.error('Error setting project directory:', error);
          return false;
      }
  }

• src/sfCommands.ts:183-186 (helper)

  Helper function to validate if a directory is a valid Salesforce project by checking for sfdx-project.json

  function isValidSalesforceProject(directory: string): boolean {
      const projectFilePath = path.join(directory, 'sfdx-project.json');
      return fs.existsSync(directory) && fs.existsSync(projectFilePath);
  }

• src/sfCommands.ts:192-194 (helper)

  Helper to retrieve list of configured project roots

  export function getProjectRoots(): ProjectRoot[] {
      return [...projectRoots];
  }

• src/sfCommands.ts:168-172 (helper)

  Type definition for project root configuration used by the tool

  interface ProjectRoot {
      path: string;
      name?: string;
      description?: string;
      isDefault?: boolean;