Salesforce CLI MCP 服务器

用于为 Claude Desktop 等 LLM 工具提供 Salesforce CLI 功能的模型上下文协议 (MCP) 服务器。

概述

此 MCP 服务器封装了 Salesforce CLI (sf) 命令行工具，并将其命令公开为 MCP 工具和资源，从而允许 LLM 驱动的代理执行以下操作：

• 查看有关 Salesforce CLI 主题和命令的帮助信息
• 使用适当的参数执行 Salesforce CLI 命令
• 在 AI 工作流程中利用 Salesforce CLI 功能

要求

• Node.js 18+ 和 npm
• 已安装并配置 Salesforce CLI (sf)
• 您的 Salesforce 组织凭据已在 CLI 中配置

安装

# 克隆存储库
git clone <repository-url>
cd sfMcp

# 安装依赖项
npm install

用法

启动服务器

# 基本用法
npm start

# 使用项目根目录
npm start /path/to/project1 /path/to/project2
# 或使用便捷脚本
npm run with-roots /path/to/project1 /path/to/project2

# 作为带有根目录的 npx 包
npx -y codefriar/sf-mcp /path/to/project1 /path/to/project2

MCP 服务器使用 stdio 传输，可以与 MCP 客户端（如 MCP Inspector 或 Claude Desktop）一起使用。

在 Claude Desktop 中配置

要在 Claude Desktop 的 .claude.json 配置文件中配置此 MCP，请执行以下操作：

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

直接使用 npm 包：

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

开发

# 监视模式（在文件更改时重新编译）
npm run dev

# 在另一个终端中
npm start [可选项目根目录...]

可用工具和资源

此 MCP 服务器提供 Salesforce CLI 命令作为 MCP 工具。 它会自动发现并注册 Salesforce CLI 中的所有可用命令，并专门实现最常用的命令。

核心工具

• sf_version - 获取 Salesforce CLI 版本信息
• sf_help - 获取 Salesforce CLI 命令的帮助信息
• sf_cache_clear - 清除命令发现缓存
• sf_cache_refresh - 刷新命令发现缓存

项目目录管理（根目录）

对于需要 Salesforce 项目上下文的命令（如部署），您必须指定项目目录。 MCP 支持多个项目目录（根目录），类似于文件系统 MCP。

配置方法

方法 1：通过命令行参数

# 使用项目根目录启动 MCP
npm start /path/to/project1 /path/to/project2
# 或
npx -y codefriar/sf-mcp /path/to/project1 /path/to/project2

以这种方式配置时，根目录将自动命名为 root1、root2 等，第一个根目录设置为默认根目录。

方法 2：使用 MCP 工具

• sf_set_project_directory - 设置要用于命令的 Salesforce 项目目录
  • 参数：
    • directory - 包含 sfdx-project.json 文件的目录的路径
    • name - （可选）此项目根目录的名称
    • description - （可选）此项目根目录的描述
    • isDefault - （可选）将此根目录设置为命令执行的默认根目录
• sf_list_roots - 列出所有已配置的项目根目录
• sf_detect_project_directory - 尝试从用户消息中检测项目目录

用法示例：

# 使用名称设置项目目录
sf_set_project_directory --directory=/path/to/your/sfdx/project --name=project1 --isDefault=true

# 列出所有已配置的根目录
sf_list_roots

# 或包含在您的消息中：
"请将 /path/to/your/sfdx/project 中的项目中的 apex 代码部署到我的暂挂组织"

方法 3：Claude Desktop 配置 在 .claude.json 中配置项目根目录，如下所述。

使用项目根目录

您可以在特定项目根目录中执行命令：

# 使用资源 URI
sf://roots/project1/commands/project deploy start --sourcedir=force-app

# 使用 rootName 参数
sf_project_deploy_start --sourcedir=force-app --rootName=project1

对于部署、源检索和其他特定于项目的操作等命令，必须指定项目目录。 如果配置了多个根目录，则将使用默认根目录，除非另有说明。

关键已实现工具

以下命令已专门实现并保证可以工作：

组织管理

• sf_org_list - 列出 Salesforce 组织
  • 参数：json、verbose
• sf_auth_list_orgs - 列出已验证的 Salesforce 组织
  • 参数：json、verbose
• sf_org_display - 显示有关组织的详细信息
  • 参数：targetusername、json
• sf_org_open - 在浏览器中打开组织
  • 参数：targetusername、path、urlonly

Apex 代码

• sf_apex_run - 运行匿名 Apex 代码
  • 参数：targetusername、file、apexcode、json
• sf_apex_test_run - 运行 Apex 测试
  • 参数：targetusername、testnames、suitenames、classnames、json

数据管理

• sf_data_query - 执行 SOQL 查询
  • 参数：targetusername、query、json
• sf_schema_list_objects - 列出组织中的 sObject
  • 参数：targetusername、json
• sf_schema_describe - 描述 Salesforce 对象
  • 参数：targetusername、sobject、json

部署

• sf_project_deploy_start - 将源部署到组织
  • 参数：targetusername、sourcedir、json、wait

动态发现的工具

服务器发现所有可用的 Salesforce CLI 命令，并将它们注册为格式为 sf_<topic>_<command> 的工具。

例如：

• sf_apex_run - 运行匿名 Apex 代码
• sf_data_query - 执行 SOQL 查询

对于嵌套主题命令，工具名称包括带有下划线的完整路径：

• sf_apex_log_get - 获取 apex 日志
• sf_org_login_web - 使用 Web 流登录到组织

服务器还为常见的嵌套命令创建简化的别名（如果可能）：

• sf_get 作为 sf_apex_log_get 的别名
• sf_web 作为 sf_org_login_web 的别名

可用命令因已安装的 Salesforce CLI 插件而异。

注意： 命令发现会被缓存以提高启动性能。 如果您安装了新的 SF CLI 插件，请使用 sf_cache_refresh 工具更新缓存，然后重新启动服务器。

资源

以下资源提供有关 Salesforce CLI 的文档：

• sf://help - 主要 CLI 文档
• sf://topics/{topic}/help - 主题帮助文档
• sf://commands/{command}/help - 命令帮助文档
• sf://topics/{topic}/commands/{command}/help - 主题-命令帮助文档
• sf://version - 版本信息
• sf://roots - 列出所有已配置的项目根目录
• sf://roots/{root}/commands/{command} - 在特定项目根目录中执行命令

工作原理

1. 启动时，服务器检查缓存的命令列表（存储在 ~/.sf-mcp/command-cache.json 中）
2. 如果存在有效的缓存，则使用它来注册命令；否则，将动态发现命令
3. 在发现期间，服务器查询 sf commands --json 以获取可用命令的完整列表
4. 命令元数据（包括参数和描述）直接从 JSON 输出中提取
5. 所有命令都注册为具有适当参数架构的 MCP 工具
6. 资源已注册用于帮助文档
7. 调用工具时，将执行相应的 Salesforce CLI 命令

项目根目录管理

对于需要 Salesforce 项目上下文的命令：

1. 服务器检查是否已通过 sf_set_project_directory 配置任何项目根目录
2. 如果配置了多个根目录，则使用默认根目录，除非指定了特定根目录
3. 如果未设置任何根目录，服务器将提示用户指定项目目录
4. 命令在相应的项目目录中执行，确保正确的上下文
5. 用户可以根据需要添加或切换多个项目根目录

特定于项目的命令（如部署、检索等）将自动在相应的项目目录中运行。 对于不需要项目上下文的命令，工作目录无关紧要。

您可以通过以下方式在特定项目根目录中执行命令：

• 使用资源 URI：sf://roots/{rootName}/commands/{command}
• 向命令工具提供 rootName 参数（内部实现详细信息）
• 使用 sf_set_project_directory --isDefault=true 将特定根目录设置为默认根目录

命令缓存

为了提高启动性能，MCP 服务器会缓存发现的命令：

• 缓存存储在 ~/.sf-mcp/command-cache.json 中
• 它包括所有主题、命令、参数和描述
• 缓存具有验证时间戳和 SF CLI 版本检查
• 默认情况下，缓存会在 7 天后过期
• 安装新的 Salesforce CLI 插件时，请使用 sf_cache_refresh 更新缓存

解决缓存问题

服务器的首次运行会执行完整的命令发现，这可能需要一些时间。 如果您遇到任何缺少命令或缓存问题：

1. 停止 MCP 服务器（如果正在运行）
2. 手动删除缓存文件：rm ~/.sf-mcp/command-cache.json
3. 再次启动服务器：npm start

这将强制使用官方 CLI 元数据完全重新发现所有命令。

如果仍然缺少特定命令，或者您已安装新的 SF CLI 插件：

1. 使用 Claude Desktop 中的 sf_cache_refresh 工具
2. 停止并重新启动 MCP 服务器

处理嵌套主题

Salesforce CLI 具有一个分层命令结构，该结构可以有多个级别。 此 MCP 服务器通过以下方式处理这些嵌套命令：

• 将冒号分隔的路径转换为下划线格式 (apex:log:get → sf_apex_log_get)
• 在可能的情况下为常见的深度命令提供别名（sf_get 用于 sf_apex_log_get）
• 在工具名称中保留完整的命令层次结构
• 使用来自 sf commands --json 的官方命令结构

嵌套主题命令在可能的情况下注册两次 - 一次使用完整的层次结构名称，一次使用简化的别名， 使它们更容易发现和使用。

许可证

ISC