Salesforce Apex MCP A2a Server

Salesforce MCP服务器

Salesforce的模型上下文协议（MCP）实现，使AI系统能够通过标准化协议与Salesforce CRM数据进行交互。

概述

Salesforce MCP Server是基于Apex的实现，通过MCP协议公开Salesforce功能。这使得AI模型和工具能够无缝访问和操作CRM数据，执行工具，并利用Salesforce生态系统中的预定义提示。

建筑

服务器采用模块化架构，包含以下关键组件：

核心组件

┌───────────────────────┐
│   REST Endpoint       │ ← Entry point (/mcp/*)
│ RestResourceMcpServer │
└──────────┬────────────┘
           │
           v
┌─────────────────────┐
│      Server         │ ← Main orchestrator
│   (MCP Protocol)    │
└──────────┬──────────┘
           │
           ├─── Tools ────────┐
           ├─── Resources ────┼── Pluggable Components
           └─── Prompts ──────┘

请求流

1. HTTP请求 → REST资源端点(/mcp/*)
2. 服务器初始化 → 使用已注册的组件创建MCP服务器实例
3. 方法路由 → 将MCP协议方法路由到适当的处理程序
4. 组件执行 → 执行工具、读取资源或处理提示
5. JSON响应 → 返回标准化的MCP响应

文件结构

RestResourceMcpServer.cls

处理传入MCP请求的主要REST端点。

主要特点：

• 地图到 /mcp/* URL模式
• 使用组件初始化MCP服务器
• 注册示例工具、资源和提示
• 将请求处理委托给Server类

服务器.cls

管理服务器生命周期的核心MCP协议实现。

主要职责：

• 协议遵从：执行MCP 2025-06-18规范
• 组件注册表：管理工具、资源和提示
• 请求路由：将MCP方法路由到适当的处理程序
• 错误处理：标准化的错误响应和异常管理
• JSON响应生成：创建符合要求的MCP响应

支持的MCP方法：

• initialize -服务器初始化和能力协商
• resources/list -列出可用资源
• resources/templates/list -列出资源模板
• resources/read -读取资源内容
• tools/list -列出可用工具
• tools/call -执行工具
• prompts/list -列出可用提示
• prompts/get -检索提示内容
• ping -健康检查

Method.cls

处理每个MCP协议方法的执行逻辑。

核心方法：

initialize()

执行MCP握手，返回：

• 协议版本兼容性
• 服务器信息（名称、版本、标题）
• 可用功能（工具、资源、提示）
• 可选服务器说明

resourcesList(Boolean retrieveTemplates)

根据参数返回静态资源或资源模板。

resourcesRead()

从特定资源URI读取内容，支持基于模板的资源匹配。

toolsList() / toolsCall()

列出可用工具，并使用提供的参数执行工具调用。

promptsList() / promptsGet()

管理提示模板并检索已处理的提示内容。

组件类型

工具

在Salesforce中执行操作的可执行函数。

示例: LeadTool -管理潜在客户操作（创建、更新、查询）

结构:

global abstract class Tool {
    global abstract String getName();
    global abstract String call(Map arguments);
    global abstract String toJson();
}

资源

AI系统可以读取的数据源。

示例: ProductResource -公开产品目录数据

结构:

global abstract class Resource {
    global abstract Boolean isTemplate();
    global abstract Boolean matchesTemplate(String uri);
    global abstract List read();
    global abstract String toJson();
}

提示

具有参数替换的可重用提示模板。

示例: CodeReviewPrompt -提供代码审查指南

结构:

global abstract class Prompt {
    global abstract String getName();
    global abstract List get(Map arguments);
    global abstract String toJson();
}

错误处理

服务器通过以下方式实现了全面的错误处理：

• MCP特定例外 (mcpException)违反协议
• Salesforce标准例外 平台错误
• 结构化错误响应 带有错误代码和详细信息
• 优雅降级 部分故障

配置

服务器安装程序

Server server = new Server('1.0.0', 'salesforce-mcp-server', 
                          'Salesforce MCP Server', 
                          'MCP Server to expose CRM data');

// Register components
server.registerTool(new LeadTool());
server.registerResource(new ProductResource());
server.registerPrompt(new CodeReviewPrompt());

测试MCP服务器

要测试服务器，请使用 MCP检查员 工具。

使用MCP检查器连接到您的服务器

1. 启用并激活公共Salesforce站点，并向其中添加RestResourceMcpServer apex类。
2. 打开终端，运行“npx@modelcontextprotocol/inspector”（必要时安装库）
3. 启动Web服务器后，选择 传输类型：流式HTTP
4. 输入您的服务器URL（例如。， https://{instance_url}/services/apexrest/mcp)
5. 点击 连接

成功连接后，您将看到可用资源、工具和提示的列表，如所示 下面的屏幕截图：

使用Python客户端连接到服务器

1. 安装依赖项：

pip install aiohttp

1. 运行python MCP客户端

python client/mcp-client.py

1. 结果

安全注意事项（Salesforce MCP Apex服务器）

• 用途 global without sharing REST端点允许外部访问
• 单个组件可以实现自己的共享规则
• 建议实施适当的身份验证和授权
• 考虑对生产部署进行速率限制

使用示例

初始化连接

POST /services/apexrest/mcp/
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "clientInfo": {
      "name": "my-client",
      "version": "1.0.0"
    }
  }
}

列出可用工具

POST /services/apexrest/mcp/
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

执行工具

POST /services/apexrest/mcp/
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "LeadTool",
    "arguments": {
      "action": "create",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com"
    }
  }
}

部署

1. 部署Apex类：将服务器类部署到Salesforce组织
2. 配置远程站点设置：如果获取外部资源
3. 设置已连接的应用程序：如果需要，用于OAuth身份验证
4. 测试终点：验证 /services/apexrest/mcp/ 端点可访问

扩展服务器

添加新工具

global class CustomTool extends Tool {
    global override String getName() {
        return 'CustomTool';
    }
    
    global override String call(Map arguments) {
        // Implementation logic
        return 'Tool execution result';
    }
    
    global override String toJson() {
        // Tool definition in JSON format
    }
}

添加新资源

global class CustomResource extends Resource {
    global override Boolean isTemplate() {
        return true; // or false for static resources
    }
    
    global override List read() {
        // Resource reading logic
    }
    
    // Other required methods...
}

协议遵从

此实现遵循MCP规范版本 2025-06-18 并支持：

• ✅ 服务器初始化和能力协商
• ✅ 工具列表和执行
• ✅ 资源列表和阅读（包括模板）
• ✅ 快速列出和检索
• ✅ 结构化错误响应
• ✅ JSON-RPC 2.0消息格式

贡献

扩展此服务器时：

1. 遵循Salesforce编码标准和最佳实践
2. 对所有操作实施适当的错误处理
3. 添加全面的测试覆盖率
4. 记录新组件及其使用情况
5. 确保安全和共享规则配置正确

许可证

该项目遵循Salesforce的标准许可条款。有关详细信息，请参阅您的Salesforce许可协议。

______________________________________________________________________

有关模型上下文协议的更多信息，请访问 MCP规范文件.