Salesforce CLI Integration Adapter (MCP)

This component functions as an intermediary server, bridging the gap between Model Context Protocol (MCP) compatible AI agents (such as Claude Desktop) and the native Salesforce CLI (sf). It translates high-level AI requests into direct execution of sf commands.

Core Capabilities

This adapter empowers AI agents to perform the following actions securely and contextually:

• Execution: Run arbitrary Salesforce CLI commands with specified arguments.
• Information Retrieval: Fetch help documentation (--help) for commands and topics.
• Project Context Management: Define, switch between, and utilize multiple local Salesforce project directories (roots) for context-aware operations like deployments or source tracking.
• Metadata Access: Directly query organizational details, user data, and schema information.

Prerequisites for Deployment

To successfully launch and operate this service, the following environment prerequisites must be met:

1. Runtime Environment: A stable installation of Node.js (version 18 or newer) alongside npm.
2. CLI Dependency: The Salesforce CLI (sf) must be fully installed and accessible in the system's PATH.
3. Authentication: Valid Salesforce organization credentials must be configured locally for the CLI to interact with target environments (e.g., via sf auth login).

Setup and Initialization

Follow these steps to obtain and install the server code:

bash

Obtain the source repository

git clone cd sfMcp

Install required Node.js packages

npm install

Launching the Service

The server operates using standard input/output (stdio) for communication with the MCP client.

Standard Startup

Initiate the adapter via npm:

bash

Start basic service

npm start

Start with predefined project workspace roots

npm start /path/to/workspace_a /path/to/workspace_b

Or use the provided execution script

npm run with-roots /path/to/workspace_a /path/to/workspace_b

Direct execution using npx (recommended for deployment)

npx -y codefriar/sf-mcp /path/to/workspace_a /path/to/workspace_b

Integration with Claude Desktop

To register this tool in Claude Desktop's configuration file (.claude.json):

Option A: Using direct Node execution path:

{ "tools": { "salesforce_ops": { "command": "/path/to/node", "args": [ "/path/to/sf-mcp/build/index.js", "/path/to/project1", "/path/to/project2" ] } } }

Option B: Using the npx package reference:

{ "tools": { "salesforce_ops": { "command": "/path/to/npx", "args": [ "-y", "codefriar/sf-mcp", "/path/to/project1", "/path/to/project2" ] } } }

Development Mode

For active development, use the watch script to enable automatic recompilation upon source code modifications:

bash

Terminal 1: Watch for code changes

npm run dev

Terminal 2: Run the server alongside the watcher

npm start [optional project roots...]

Available Functionality: Tools and Documentation Resources

This adapter dynamically maps nearly all available sf CLI functionalities into discrete MCP tools, typically named sf_<topic>_<command>.

Essential Internal Tools

These tools manage the adapter's own operational state:

• sf_version: Reports the host Salesforce CLI version.
• sf_help: Retrieves generalized CLI help content.
• sf_cache_clear / sf_cache_refresh: Manages the command discovery cache.

Project Context Management (Workspace Roots)

Commands requiring a local project structure (like metadata deployments) rely on 'roots.' The adapter supports maintaining multiple defined project contexts.

Methods for Defining Roots:

1. Startup Parameters: Specifying paths during server launch (as shown above), resulting in indexed names (root1, root2, etc.).
2. Runtime Tool Invocation:
   • sf_set_project_directory: Manually registers a project path, allowing assignment of custom names and designation of a default context.
   • sf_list_roots: Displays all currently active project contexts.

Execution Context Switching:

Commands can target specific roots using Resource URIs or parameters:

Targeting via Resource URI, assuming 'development_project' is a configured root name

sf://roots/development_project/commands/project deploy start --sourcedir=src

Targeting via explicit parameter

sf_project_deploy_start --sourcedir=src --rootName=development_project

Curated High-Frequency Tools

The following tools represent common, critical operations abstracted for ease of use:

Organization & Authentication

• sf_org_list: Enumerates connected orgs.
• sf_org_open: Launches a specified scratch org or sandbox in the default web browser.
• sf_auth_list_orgs: Similar to sf_org_list, focusing on authenticated connections.

Apex Operations

• sf_apex_run: Executes anonymous Apex code blocks or scripts from files.
• sf_apex_test_run: Triggers execution of specified test classes or suites.

Data Manipulation

• sf_data_query: Runs SOQL statements against a target org.
• sf_schema_describe: Retrieves metadata for a specific SObject.

Tool Naming Convention for Nested Commands

To map the deep hierarchy of the sf command tree (e.g., apex:log:get), the adapter flattens the structure using underscores: sf_apex_log_get.

In select, highly frequent cases, simplified aliases are also generated (e.g., sf_get mapping to sf_apex_log_get).

Documentation Resources

The adapter exposes documentation endpoints mirroring the CLI structure:

• sf://help: General CLI documentation portal.
• sf://topics/{topic}/help: Specific section documentation.
• sf://roots: List of active project contexts.

Operational Flow and Context Binding

The adapter prioritizes performance and contextual accuracy:

1. Startup Discovery: Upon initialization, the server attempts to load command definitions from a local cache (~/.sf-mcp/command-cache.json). If absent or invalid, it executes sf commands --json to build a fresh, comprehensive catalog.
2. Command Execution: When an AI invokes a tool, the server maps the tool name back to the original sf command structure.
3. Context Resolution: For project-dependent actions, the server checks for an explicit root parameter (rootName) or falls back to the designated default root. If no context is found for a required operation, the execution halts, prompting the user or agent to define the necessary workspace.

Managing Cache Invalidation

If new plugins are installed in the host Salesforce CLI, the command cache becomes stale. To synchronize:

• Manual Refresh: Execute the sf_cache_refresh tool from the client, followed by a server restart.
• Forced Reset: Manually remove the cache file (rm ~/.sf-mcp/command-cache.json) and restart the server to trigger a full re-scan.