# codefriar/sf-mcp architecture

> Architecture diagram of the GitHub repository codefriar/sf-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/codefriar/sf-mcp
- Repository: https://github.com/codefriar/sf-mcp

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Client
    Client["MCP Client (LLM)"]:::external

    %% Node.js MCP Server
    subgraph "Node.js MCP Server"
        direction TB
        Transport["Transport Module\nNode.js 18+, TypeScript"]:::internal
        Resources["Resource Registry\n(help, version, roots)"]:::internal
        Commands["Command Registry\n(core sf tools, dynamic)"]:::internal
        Utilities["Utility Layer\n(cache, child_process, project-roots)"]:::internal
    end

    %% External and Data Stores
    SFCLI["Salesforce CLI (sf)"]:::externalCLI
    Cache["Cache File\n~/.sf-mcp/command-cache.json"]:::datastore
    Roots["Project Directories"]:::datastore

    %% Build Artifacts
    subgraph "Build Artifacts"
        direction TB
        BIndex["build/index.js"]:::artifact
        BResources["build/resources.js"]:::artifact
        BSfCommands["build/sfCommands.js"]:::artifact
        BUtils["build/utils.js"]:::artifact
    end

    %% Configs & Scripts
    subgraph "Configs & Scripts"
        direction TB
        Run["run.sh"]:::artifact
        Package["package.json"]:::artifact
        TSConfig["tsconfig.json"]:::artifact
        ESLint["eslint.config.js"]:::artifact
        Prettier[".prettierrc"]:::artifact
        CI[".github/workflows/npm-publish.yml"]:::artifact
    end

    %% Legend
    subgraph Legend
        direction TB
        IM["Internal Modules"]:::internal
        ES["External Systems"]:::externalCLI
        DS["Data Stores"]:::datastore
        AR["Configs & Artifacts"]:::artifact
    end

    %% Connections
    Client -->|"stdio"| Transport
    Transport -->|"lookup"| Resources
    Transport -->|"lookup"| Commands
    Commands -->|"read/write cache"| Cache
    Commands -->|"spawn sf"| SFCLI
    SFCLI -->|"JSON output"| Commands
    Commands -->|"use project roots"| Roots
    Resources -->|"use utils"| Utilities
    Commands -->|"use utils"| Utilities
    Utilities -->|"manage roots"| Roots

    %% Click Events
    click Transport "https://github.com/codefriar/sf-mcp/blob/main/src/index.ts"
    click Resources "https://github.com/codefriar/sf-mcp/blob/main/src/resources.ts"
    click Commands "https://github.com/codefriar/sf-mcp/blob/main/src/sfCommands.ts"
    click Utilities "https://github.com/codefriar/sf-mcp/blob/main/src/utils.ts"
    click BIndex "https://github.com/codefriar/sf-mcp/blob/main/build/index.js"
    click BResources "https://github.com/codefriar/sf-mcp/blob/main/build/resources.js"
    click BSfCommands "https://github.com/codefriar/sf-mcp/blob/main/build/sfCommands.js"
    click BUtils "https://github.com/codefriar/sf-mcp/blob/main/build/utils.js"
    click Run "https://github.com/codefriar/sf-mcp/blob/main/run.sh"
    click Package "https://github.com/codefriar/sf-mcp/blob/main/package.json"
    click TSConfig "https://github.com/codefriar/sf-mcp/blob/main/tsconfig.json"
    click ESLint "https://github.com/codefriar/sf-mcp/blob/main/eslint.config.js"
    click Prettier "https://github.com/codefriar/sf-mcp/blob/main/.prettierrc"
    click CI "https://github.com/codefriar/sf-mcp/blob/main/.github/workflows/npm-publish.yml"

    %% Styles
    classDef internal fill:#cfe2f3,stroke:#000,stroke-width:1px;
    classDef external fill:#d9ead3,stroke:#000,stroke-width:1px;
    classDef externalCLI fill:#b6d7a8,stroke:#000,stroke-width:1px;
    classDef datastore fill:#f9cb9c,stroke:#000,stroke-width:1px;
    classDef artifact fill:#ececec,stroke:#000,stroke-width:1px;
```
