Servidor MCP de Salesforce CLI

Servidor de Protocolo de contexto de modelo (MCP) para proporcionar funcionalidad CLI de Salesforce a herramientas LLM como Claude Desktop.

Descripción general

Este servidor MCP encapsula la herramienta de línea de comandos Salesforce CLI ( sf ) y expone sus comandos como herramientas y recursos MCP, lo que permite a los agentes con tecnología LLM:

Ver información de ayuda sobre temas y comandos de Salesforce CLI
Ejecute comandos CLI de Salesforce con los parámetros adecuados
Aproveche las capacidades de Salesforce CLI en los flujos de trabajo de IA

Requisitos

Node.js 18+ y npm
Salesforce CLI ( sf ) instalado y configurado
Sus credenciales de organización de Salesforce configuradas en la CLI

Instalación

# Clone the repository
git clone <repository-url>
cd sfMcp

# Install dependencies
npm install

Uso

Iniciando el servidor

# Basic usage
npm start

# With project roots
npm start /path/to/project1 /path/to/project2
# or using the convenience script
npm run with-roots /path/to/project1 /path/to/project2

# As an npx package with roots
npx -y codefriar/sf-mcp /path/to/project1 /path/to/project2

El servidor MCP utiliza el transporte stdio, que se puede utilizar con clientes MCP como MCP Inspector o Claude Desktop.

Configuración en Claude Desktop

Para configurar este MCP en la configuración .claude.json de Claude Desktop:

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

Usando el paquete npm directamente:

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

Desarrollo

# Watch mode (recompiles on file changes)
npm run dev

# In another terminal
npm start [optional project roots...]

Herramientas y recursos disponibles

Este servidor MCP proporciona comandos de Salesforce CLI como herramientas MCP. Detecta y registra automáticamente todos los comandos disponibles de Salesforce CLI e implementa específicamente los comandos más comunes.

Herramientas principales

sf_version : obtener la información de la versión de Salesforce CLI
sf_help : obtenga información de ayuda para los comandos CLI de Salesforce
sf_cache_clear - Borra la caché de descubrimiento de comandos
sf_cache_refresh - Actualizar la caché de descubrimiento de comandos

Gestión del directorio de proyectos (raíces)

Para los comandos que requieren un contexto de proyecto de Salesforce (como las implementaciones), debe especificar el directorio del proyecto. El MCP admite varios directorios de proyecto (raíces), de forma similar al MCP del sistema de archivos.

Métodos de configuración

Método 1: mediante argumentos de la línea de comandos

# Start the MCP with project roots
npm start /path/to/project1 /path/to/project2
# or
npx -y codefriar/sf-mcp /path/to/project1 /path/to/project2

Cuando se configura de esta manera, las raíces se nombrarán automáticamente root1 , root2 , etc., y la primera se establecerá como predeterminada.

Método 2: Uso de herramientas MCP

sf_set_project_directory : establece un directorio de proyecto de Salesforce para usar con los comandos
- Parámetros:
  - directory - Ruta a un directorio que contiene un archivo sfdx-project.json
  - name - (Opcional) Nombre para esta raíz del proyecto
  - description - (Opcional) Descripción de la raíz de este proyecto
  - isDefault - (Opcional) Establezca esta raíz como predeterminada para la ejecución del comando
sf_list_roots - Lista todas las raíces del proyecto configuradas
sf_detect_project_directory : intenta detectar el directorio del proyecto a partir de los mensajes del usuario

Ejemplo de uso:

# Set project directory with a name
sf_set_project_directory --directory=/path/to/your/sfdx/project --name=project1 --isDefault=true

# List all configured roots
sf_list_roots

# Or include in your message:
"Please deploy the apex code from the project in /path/to/your/sfdx/project to my scratch org"

Método 3: Configuración de escritorio de Claude Configure las raíces del proyecto en .claude.json como se describe a continuación.

Uso de las raíces del proyecto

Puede ejecutar comandos en raíces de proyectos específicos:

# Using resource URI
sf://roots/project1/commands/project deploy start --sourcedir=force-app

# Using rootName parameter
sf_project_deploy_start --sourcedir=force-app --rootName=project1

Se debe especificar el directorio del proyecto para comandos como implementaciones, recuperación de código fuente y otras operaciones específicas del proyecto. Si se configuran varias raíces, se usará la raíz predeterminada a menos que se especifique lo contrario.

Herramientas clave implementadas

Los siguientes comandos están implementados específicamente y se garantiza que funcionan:

Gestión de la organización

sf_org_list - Lista de organizaciones de Salesforce
- Parámetros: json , verbose
sf_auth_list_orgs - Lista de organizaciones de Salesforce autenticadas
- Parámetros: json , verbose
sf_org_display - Mostrar detalles sobre una organización
- Parámetros: targetusername , json
sf_org_open - Abre una organización en el navegador
- Parámetros: targetusername , path , urlonly

Código Apex

sf_apex_run - Ejecutar código Apex anónimo
- Parámetros: targetusername , file , apexcode , json
sf_apex_test_run - Ejecutar pruebas de Apex
- Parámetros: targetusername , testnames , suitenames , classnames , json

Gestión de datos

sf_data_query - Ejecutar una consulta SOQL
- Parámetros: targetusername , query , json
sf_schema_list_objects - Lista de sObjects en la organización
- Parámetros: targetusername , json
sf_schema_describe : describe un objeto de Salesforce
- Parámetros: targetusername , sobject , json

Despliegue

sf_project_deploy_start - Implementar la fuente en una organización
- Parámetros: targetusername , sourcedir , json , wait

Herramientas descubiertas dinámicamente

El servidor descubre todos los comandos CLI de Salesforce disponibles y los registra como herramientas con el formato: sf_<topic>_<command> .

Por ejemplo:

sf_apex_run - Ejecutar código Apex anónimo
sf_data_query - Ejecutar una consulta SOQL

Para los comandos de temas anidados, el nombre de la herramienta incluye la ruta completa con guiones bajos:

sf_apex_log_get - Obtener registros de Apex
sf_org_login_web - Iniciar sesión en una organización mediante el flujo web

El servidor también crea alias simplificados para comandos anidados comunes cuando es posible:

sf_get como alias para sf_apex_log_get
sf_web como alias para sf_org_login_web

Los comandos disponibles varían según los complementos CLI de Salesforce instalados.

Nota: La detección de comandos se almacena en caché para mejorar el rendimiento del inicio. Si instala nuevos complementos de SF CLI, utilice la herramienta sf_cache_refresh para actualizar la caché y, a continuación, reinicie el servidor.

Recursos

Los siguientes recursos proporcionan documentación sobre Salesforce CLI:

sf://help - Documentación principal de la CLI
sf://topics/{topic}/help - Documentación de ayuda del tema
sf://commands/{command}/help - Documentación de ayuda de comandos
sf://topics/{topic}/commands/{command}/help - Documentación de ayuda sobre temas y comandos
sf://version - Información de la versión
sf://roots - Lista todas las raíces del proyecto configuradas
sf://roots/{root}/commands/{command} - Ejecutar un comando en una raíz de proyecto específica

Cómo funciona

Al iniciarse, el servidor busca una lista de comandos en caché (almacenada en ~/.sf-mcp/command-cache.json )
Si existe un caché válido, se utiliza para registrar comandos; de lo contrario, los comandos se descubren dinámicamente.
Durante el descubrimiento, el servidor consulta sf commands --json para obtener una lista completa de los comandos disponibles.
Los metadatos del comando (incluidos parámetros y descripciones) se extraen directamente de la salida JSON
Todos los comandos se registran como herramientas MCP con esquemas de parámetros apropiados
Los recursos están registrados para la documentación de ayuda.
Cuando se llama a una herramienta, se ejecuta el comando CLI de Salesforce correspondiente

Gestión de raíces del proyecto

Para los comandos que requieren un contexto de proyecto de Salesforce:

El servidor verifica si se han configurado raíces de proyecto a través de sf_set_project_directory
Si se configuran varias raíces, se utiliza la raíz predeterminada a menos que se especifique una raíz específica
Si no se establecen raíces, el servidor solicitará al usuario que especifique un directorio de proyecto.
Los comandos se ejecutan dentro del directorio del proyecto apropiado, lo que garantiza el contexto adecuado.
El usuario puede agregar o cambiar entre múltiples raíces de proyecto según sea necesario

Los comandos específicos del proyecto (como implementaciones, recuperaciones, etc.) se ejecutarán automáticamente en el directorio del proyecto correspondiente. Para los comandos que no requieren contexto de proyecto, el directorio de trabajo no importa.

Puede ejecutar comandos en raíces de proyectos específicos mediante:

Usando la URI del recurso: sf://roots/{rootName}/commands/{command}
Proporcionar un parámetro rootName a las herramientas de comando (detalles de implementación interna)
Establecer una raíz específica como predeterminada con sf_set_project_directory --isDefault=true

Almacenamiento en caché de comandos

Para mejorar el rendimiento de inicio, el servidor MCP almacena en caché los comandos descubiertos:

El caché se almacena en ~/.sf-mcp/command-cache.json
Incluye todos los temas, comandos, parámetros y descripciones.
El caché tiene una marca de tiempo de validación y una verificación de versión de SF CLI
De forma predeterminada, la caché caduca después de 7 días.
Cuando instale nuevos complementos de Salesforce CLI, utilice sf_cache_refresh para actualizar la caché

Solución de problemas de caché

La primera ejecución del servidor realiza un descubrimiento completo de comandos, lo cual puede tardar un tiempo. Si encuentra algún problema con comandos faltantes o problemas de caché:

Detener el servidor MCP (si está en ejecución)
Eliminar manualmente el archivo de caché: rm ~/.sf-mcp/command-cache.json
Inicie el servidor nuevamente: npm start

Esto forzará un redescubrimiento completo de todos los comandos utilizando los metadatos oficiales de la CLI.

Si aún faltan comandos específicos o ha instalado nuevos complementos de SF CLI:

Utilice la herramienta sf_cache_refresh de Claude Desktop
Detener y reiniciar el servidor MCP

Manejo de temas anidados

La CLI de Salesforce tiene una estructura de comandos jerárquica que puede tener varios niveles de profundidad. Este servidor MCP gestiona estos comandos anidados mediante:

Conversión de rutas separadas por dos puntos al formato de guión bajo ( apex:log:get → sf_apex_log_get )
Proporcionar alias para comandos profundos comunes cuando sea posible ( sf_get para sf_apex_log_get )
Preservación de la jerarquía de comandos completa en los nombres de las herramientas
Usando la estructura de comando oficial de sf commands --json

Los comandos de temas anidados se registran dos veces cuando es posible: una vez con el nombre de la jerarquía completa y otra con un alias simplificado, lo que hace que sean más fáciles de descubrir y usar.

Licencia

ISC

Salesforce CLI MCP Server

Integrations