How codefriar/sf-mcp works
Project Type and Purpose
• This is a backend “MCP server” (a Node.js command‐line service) that wraps the Salesforce CLI (sf) and exposes its commands over the Model Context Protocol.
• Its purpose is to let LLM-based clients (e.g., Claude Desktop) invoke Salesforce CLI functionality via stdio transport, with automatic command discovery, caching, and project-root management.
File Structure
• Top‐level source:
• src/index.ts – entry point, bootstrap logic for MCP server
• src/resources.ts – registration of MCP resources (help docs, version, roots)
• src/sfCommands.ts – core implementation of specific Salesforce CLI tools (org, apex, data, deploy)
• src/utils.ts – utility functions (cache management, process execution, project‐roots)
• Build output under build/ mirrors src/ as compiled JavaScript.
• Config files: tsconfig.json, .prettierrc, eslint.config.js, GitHub Actions workflow for publishing.
• Package manifest (package.json) and shell script (run.sh) for startup convenience.
README for Additional Insights
• Describes startup modes (with optional project roots), MCP transport over stdio.
• Explains dynamic discovery of all sf commands via sf commands --json, caching results in ~/.sf-mcp/command-cache.json.
• Lists core tools/resources for help, version, cache, roots, and frequently used commands.
• Outlines project‐root management, caching strategy, and nested topic handling.
Main Components and Interactions
a. MCP Client (external)
• E.g., Claude Desktop or any MCP‐aware LLM agent
• Communicates over stdio
b. Node.js MCP Server
• Entry (src/index.ts) sets up stdio transport and MCP registry
• Resource Layer (src/resources.ts) – defines help, version, roots resources
• Command Layer (src/sfCommands.ts) – implements core sf_* tools, dynamic command registration
• Utility Layer (src/utils.ts) – handles cache I/O, child_process invocation of sf, project‐root state
c. Salesforce CLI (sf)
• External executable invoked via child_process
• Produces JSON metadata (during discovery) or command output
d. Local Cache Store
• JSON file at ~/.sf-mcp/command-cache.json
• Used to speed up discovery and tool registration
e. Filesystem (project roots)
• One or more Salesforce project directories passed as CLI args or set via tools
• Used as working directories for commands requiring project context
Architectural Patterns and Design Principles
• Layered Architecture:
• Transport layer (stdio ↔ MCP protocol)
• Registry layer (resources & tools registration)
• Execution layer (command invocation, caching)
• Plugin/Discovery Pattern: dynamically discovers CLI commands and registers them as MCP tools
• Single‐process, event‐driven, modular Node.js application
• Separation of concerns: distinct modules for resources, commands, and utilities