Salesforce MCP Lib

Salesforce MCP库

](https://www.npmjs.com/package/salesforce-mcp-lib) 

通过开源桥梁将AI代理连接到Salesforce 模型上下文协议.

Architecture

两个包，零外部依赖：

______________________________________________________________________

运作原理

1. MCP客户端 （Claude、ChatGPT、任何MCP主机）通过以下方式发送JSON-RPC 2.0消息 标准
2. npm代理 通过OAuth 2.0（客户端凭据或每用户登录）进行身份验证，通过HTTPS转发请求，并自动处理令牌刷新
3. Apex MCP服务器 向您的注册用户发送请求 工具, 资源，以及 提示 --所有这些都在Salesforce内部运行，具有完整的平台安全性

使用npm代理时，步骤1-2适用。如果您的MCP主机可以使用有效的Bearer令牌通过HTTPS直接到达Apex端点，则只需要步骤3。

Apex服务器是 无状态 --它在每次请求时重建其处理程序链。没有会话清理，没有状态错误，没有交叉请求数据泄漏。

当你需要代理时（以及当你不需要代理时）

叶尖 @RestResource 端点 是 MCP服务器——它实现JSON-RPC 2.0、能力协商和所有工具/资源/提示调度。TypeScript代理是一个身份验证和传输桥梁，而不是协议逻辑。大多数MCP客户端同时支持stdio和HTTP，因此代理的主要值不是传输，而是 OAuth令牌生命周期管理：获取令牌，缓存它，在到期时刷新它，并在401上重新进行身份验证。配置一次，永远运行。

当您需要代理时 您的MCP主机不会自行管理Salesforce OAuth令牌。这涵盖了大多数桌面客户端（Claude desktop、Cursor、VS Code扩展）以及任何没有内置Salesforce凭据存储的集成。

在以下情况下，您可以跳过代理 消费者已经处理了Salesforce OAuth——例如，一个具有本地Salesforce连接器的云平台、一个像n8n这样的自动化服务，或者一个获取令牌、用MCP触发代理、将响应路由回并重复的自定义代理编排层。Apex端点是无状态的，因此在调用之间没有要维护的会话。

如果删除代理，则不会消除复杂性。您将在另一个地方获得它的所有权——具体来说，OAuth令牌获取、刷新逻辑和会话管理将转移到您的消费者手中。

有关这两条路径和直接连接要求的更深入讨论，请参阅 docs/architecture.md.

安全性——4层，其中3层是自动的

______________________________________________________________________

为什么选择外部客户端应用程序

此库使用OAuth 2.0 client_credentials 流，并且与哪个Salesforce应用程序容器颁发了凭据无关。项目文件有意标准化 外部客户端应用程序（ECA） 因此，设置指导始终领先于Salesforce的平台方向。

快速开始

1.安装Apex框架

sf package install --package 04tdL000000So9xQAC --target-org YOUR_ORG --wait 10

2.创建MCP端点（2个Apex类）

端点 一 @RestResource 这会增强你的能力。在这个未锁定的包中，框架API保持不变 public；端点本身是 global 因为Apex REST入口点需要它：

@RestResource(urlMapping='/mcp/minimal')
global inherited sharing class MinimalMcpEndpoint {
    @HttpPost
    global static void handlePost() {
        McpServer server = new McpServer();
        server.registerTool(new MinimalTool());
        server.handleRequest(RestContext.request, RestContext.response);
    }
}

工具 --扩展包的 public McpToolDefinition 基类和实现 inputSchema(), validate(), execute():

public inherited sharing class MinimalTool extends McpToolDefinition {
    public MinimalTool() {
        this.name = 'echo';
        this.description = 'Echoes the provided message back to the caller';
    }
    public override Map inputSchema() {
        return new Map{
            'type' => 'object',
            'properties' => new Map{
                'message' => new Map{
                    'type' => 'string',
                    'description' => 'The message to echo'
                }
            },
            'required' => new List{ 'message' }
        };
    }
    public override void validate(Map arguments) {
        if (!arguments.containsKey('message')) {
            throw new McpInvalidParamsException('message is required');
        }
    }
    public override McpToolResult execute(Map arguments) {
        String msg = (String) arguments.get('message');
        McpToolResult result = new McpToolResult();
        result.content = new List{ new McpTextContent(msg) };
        return result;
    }
}

3.配置外部客户端应用程序

选项A——客户端凭据 （服务帐户，无用户交互）： 使用创建外部客户端应用程序 OAuth 2.0客户端凭据 流动。注意 client_id 和 client_secret.

选项B——按用户授权 （个人身份，推荐）： 使用创建外部客户端应用程序 授权码+PKCE 流动。回调URL： http://localhost:13338/oauth/callback.范围： api, refresh_token。参见 每用户身份验证设置指南 详细步骤。

4.连接AI代理

每用户身份验证 （个人身份——建议用于Claude Code）：

# One-time login in your terminal:
npx salesforce-mcp-lib login \
  --instance-url https://your-org.my.salesforce.com \
  --client-id YOUR_CLIENT_ID

然后通过以下方式添加到Claude Code /mcp → 添加服务器或编辑 ~/.claude.json:

{
  "mcpServers": {
    "salesforce": {
      "command": "npx",
      "args": [
        "-y", "salesforce-mcp-lib",
        "--instance-url", "https://your-org.my.salesforce.com",
        "--client-id", "YOUR_CLIENT_ID",
        "--endpoint", "/services/apexrest/mcp/minimal"
      ]
    }
  }
}

客户端凭证 （服务帐户--现有行为）：

{
  "mcpServers": {
    "salesforce": {
      "command": "npx",
      "args": [
        "-y", "salesforce-mcp-lib",
        "--instance-url", "https://your-org.my.salesforce.com",
        "--client-id", "YOUR_CLIENT_ID",
        "--client-secret", "YOUR_CLIENT_SECRET",
        "--endpoint", "/services/apexrest/mcp/minimal"
      ]
    }
  }
}

自动检测身份验证模式： --client-secret 当前→ 客户端凭据缺失→ 每个用户身份验证。

就是这样。代理现在可以发现和调用您的Salesforce工具。

inherited sharing 和 with sharing 帮助强制执行记录级访问默认值，但它们本身并不强制执行CRUD/FLS。当您的工具读取或写入受保护的字段或对象时，使用显式安全检查。

______________________________________________________________________

所有三种MCP功能

在单个端点中注册工具、资源和提示：

@RestResource(urlMapping='/mcp/e2e')
global inherited sharing class E2eHttpEndpoint {
    @HttpPost
    global static void handlePost() {
        McpServer server = new McpServer();
        server.registerTool(new ExampleQueryTool());
        server.registerResource(new ExampleOrgResource());
        server.registerPrompt(new ExampleSummarizePrompt());
        server.handleRequest(RestContext.request, RestContext.response);
    }
}

看 examples/ 完整的工作代码。

______________________________________________________________________

CLI参考

MCP服务器模式

salesforce-mcp-lib [options]

\*何时 --client-secret 提供→ 客户端凭据流。当省略时→ 每个用户身份验证（需要事先 login).

登录子命令（按用户身份验证）

salesforce-mcp-lib login [options]

______________________________________________________________________

技术栈

• 顶点：Salesforce API 65.0-54个类，零外部依赖项
• TypeScript：ES2022，Node.js>=20--10个模块，零npm生产依赖
• 协议：MCP 2025-11-25JSON-RPC 2.0——实现了所有11种MCP方法
• 包装：Salesforce 2GP解锁包（无命名空间）

项目结构

force-app/main/
  json-rpc/classes/    # JSON-RPC 2.0 core (14 classes)
  mcp/classes/         # MCP server framework (40 classes)
packages/salesforce-mcp-lib/
  src/                 # TypeScript stdio proxy (10 modules)
  tests/               # Unit tests
examples/
  minimal/             # Single-tool echo example
  e2e-http-endpoint/   # Tools + resources + prompts
scripts/               # Build, deploy, and release scripts

贡献

欢迎捐款。在提交之前，在新的草稿组织中验证Apex的更改：

./scripts/org-create.sh your-alias
./scripts/org-test.sh

org-create.sh 设置一个新的scratch组织，将其设置为默认组织，并进行部署 force-app. org-test.sh 然后在该组织中运行Apex测试套件。在提交之前也运行现有的TypeScript测试套件：

cd packages/salesforce-mcp-lib && npm test && npm run lint

许可证

麻省理工学院