Agentforce MCP 服务器

此 MCP 服务器提供与 Salesforce Agentforce API 交互的工具。它允许与 Agentforce 坐席进行身份验证、会话创建和消息交换。

克隆后的入门指南

如果您刚刚克隆了此存储库，可以使用交互式设置脚本快速配置和运行服务器：

chmod +x setup.sh
./setup.sh

设置脚本将执行以下操作：

1. 检查您的 Python 版本
2. 安装所需的依赖项
3. 指导您输入 Salesforce 凭据
4. 测试与 Salesforce 的连接
5. 提供启动服务器的选项
6. 提供配置 Claude Desktop 的说明

或者，您可以按照以下手动步骤操作：

1. 安装依赖项:

   pip install -r requirements.txt
   

2. 设置您的环境变量:

   cp .env.example .env
   

3. 收集您的 Salesforce 凭据:

   • SALESFORCE_ORG_ID: 您的 18 位 Salesforce 组织 ID
   • SALESFORCE_AGENT_ID: 来自您的 Agentforce 坐席的 18 位坐席 ID
   • SALESFORCE_CLIENT_ID: 来自您的互联应用的 Consumer Key
   • SALESFORCE_CLIENT_SECRET: 来自您的互联应用的 Consumer Secret
   • SALESFORCE_SERVER_URL: 您的 Salesforce My Domain URL，不带 https:// 前缀

4. 使用收集的凭据编辑您的 .env 文件:

   SALESFORCE_ORG_ID="00D5f000000J2PKEA0"
   SALESFORCE_AGENT_ID="0XxHn000000x9F1KAI"
   SALESFORCE_CLIENT_ID="3MVG9OGq41FnYVsFgnaG0AzJDWnoy37Bb18e0R.GgDJu2qB9sqppVl7ehWmJhGvPSLrrA0cBNhDJdsbZXnv52"
   SALESFORCE_CLIENT_SECRET="210117AC36E9E4C8AFCA02FF062B8A677BACBFFB71D2BB1162D60D316382FADE"
   SALESFORCE_SERVER_URL="example.my.salesforce.com"
   

   （注意：这些是虚构的示例值。请替换为您的实际凭据。）

5. 使服务器脚本可执行:

   chmod +x agentforce_mcp_server.py
   

6. 运行服务器:

   python agentforce_mcp_server.py
   

有关查找 Salesforce 凭据的详细说明，请参见下面的 设置 Salesforce 部分。

设置

1. 确保您已安装 Python 3.10 或更高版本。

2. 安装所需的依赖项：

   pip install -r requirements.txt
   

3. 使服务器脚本可执行：

   chmod +x agentforce_mcp_server.py
   

配置

服务器使用环境变量进行配置。这些变量从 .env 文件加载。

1. 复制示例环境变量文件以创建您自己的文件：

   cp .env.example .env
   

2. 编辑 .env 文件并填写您的值：

   SALESFORCE_ORG_ID="your_org_id_here"
   SALESFORCE_AGENT_ID="your_agent_id_here"  # 您在 Salesforce 中找到的 18 位坐席 ID
   SALESFORCE_CLIENT_ID="your_client_id_here"  # 来自您的互联应用的 Consumer Key
   SALESFORCE_CLIENT_SECRET="your_client_secret_here"  # 来自您的互联应用的 Consumer Secret
   SALESFORCE_SERVER_URL="your_server_url_here"  # 您的 My Domain URL（例如，example.my.salesforce.com）
   

Salesforce 配置

要使用 Agentforce API，您需要：

1. 在您的 Salesforce 组织中创建一个互联应用
2. 找到您的 Agentforce 坐席 ID
3. 记下您的 Salesforce My Domain URL

有关这些步骤的详细说明，请参见下面的 设置 Salesforce 部分。

运行服务器

使用以下命令运行服务器：

python agentforce_mcp_server.py

可用工具

MCP 服务器公开以下工具：

1. authenticate

使用客户端电子邮件向 Agentforce API 进行身份验证。

参数：

• client_email: 用于身份验证的客户端电子邮件

2. create_agent_session

使用配置的 Agentforce 坐席创建一个会话。

参数：

• client_email: 经过身份验证的客户端电子邮件

3. send_message_to_agent

向 Agentforce 坐席发送消息并返回响应。

参数：

• client_email: 经过身份验证的客户端电子邮件
• message: 要发送给坐席的消息

4. get_session_status

获取当前会话的状态，包括身份验证状态、会话 ID 和序列 ID。

参数：

• client_email: 经过身份验证的客户端电子邮件

5. complete_agentforce_conversation

方便的方法，可处理完整的流程 - 身份验证、会话创建和消息发送。

参数：

• client_email: 用于身份验证的客户端电子邮件
• user_query: 要发送给坐席的消息

与 Claude for Desktop 一起使用

要将此服务器与 Claude for Desktop 一起使用，请更新您的 claude_desktop_config.json 文件：

{
  "mcpServers": {
    "agentforce": {
      "command": "python",
      "args": [
        "/path/to/your/agentforce_mcp_server.py"
      ]
    }
  }
}

将路径替换为计算机上服务器脚本的绝对路径。

按平台划分的路径位置

macOS

• 配置文件：~/Library/Application Support/Claude/claude_desktop_config.json
• 示例路径：/Users/yourusername/Projects/agentforce-mcp-server/agentforce_mcp_server.py

Windows

• 配置文件：%APPDATA%\Claude\claude_desktop_config.json
• 示例路径：C:\Users\yourusername\Projects\agentforce-mcp-server\agentforce_mcp_server.py

设置 Salesforce

创建互联应用

要使用 Agentforce API，您需要在您的 Salesforce 组织中创建一个互联应用：

1. 以管理员身份登录到您的 Salesforce 组织
2. 转到 设置
3. 在快速查找框中，搜索“应用管理器”并单击它
4. 单击 新建互联应用 按钮
5. 填写基本信息：
   • 互联应用名称: Agentforce MCP 集成（或您喜欢的任何名称）
   • API 名称: Agentforce_MCP_Integration（这将自动填写）
   • 联系人电子邮件: 您的电子邮件地址
6. 选中 启用 OAuth 设置
7. 将 回调 URL 设置为 https://localhost/oauth/callback（未使用，但必需）
8. 在 选定的 OAuth 范围 下，添加：
   • 通过 API 管理用户数据 (api)
   • 随时执行请求 (refresh_token, offline_access)
9. 单击 保存
10. 保存后，您将被重定向到互联应用详细信息页面
11. 记下 Consumer Key（这是您的客户端 ID），然后单击 单击以显示 旁边的 Consumer Secret 以获取您的客户端密钥

查找您的坐席 ID

要查找您的 Agentforce 坐席 ID：

1. 登录到您的 Salesforce 组织
2. 导航到 Einstein 坐席构建器
3. 选择要使用的坐席
4. 查看浏览器中的 URL - 它将包含以下格式的坐席 ID：https://your-salesforce-instance.lightning.force.com/lightning/r/Agent__c/0XxXXXXXXXXXXXXX/view
5. 坐席 ID 是 URL 中的 18 位 ID (0XxXXXXXXXXXXXXX)

查找您的 Salesforce My Domain URL

要查找您的 Salesforce My Domain URL：

1. 登录到您的 Salesforce 组织
2. 转到 设置
3. 在快速查找框中，搜索“我的域”并单击它
4. 您将看到您的域，格式为 DOMAIN-NAME.my.salesforce.com
5. 在您的 .env 文件中使用此 URL，不带 "https://" 前缀

查找您的组织 ID

要查找您的 Salesforce 组织 ID：

1. 登录到您的 Salesforce 组织
2. 转到 设置
3. 在快速查找框中，搜索“公司信息”并单击它
4. 查找“组织 ID”字段 - 这是您的 Salesforce 组织 ID
5. 它将是一个 15 或 18 位的字母数字字符串

注意事项

• 服务器自动管理消息交换的序列 ID
• 为每个客户端电子邮件维护身份验证和会话状态
• 所有 API 交互都将记录以进行调试

故障排除

如果您遇到问题：

1. 身份验证失败: 验证您的互联应用设置，并确保客户端 ID 和密钥正确
2. 会话创建错误: 检查您的坐席 ID，并确保它是 18 位版本
3. 连接问题: 验证您的 Salesforce My Domain URL 是否正确（不带 "https://" 前缀）
4. 权限错误: 确保您的互联应用已启用正确的 OAuth 范围

测试设置

您可以使用包含的测试脚本测试您的设置：

python test_agentforce.py

这将尝试进行身份验证、创建会话以及与您的 Agentforce 坐席交换消息。

贡献和 GitHub 推送

此存储库包含一个有用的脚本，可简化将更改推送到 GitHub 的过程：

chmod +x github_push.sh
./github_push.sh

github_push.sh 脚本将执行以下操作：

1. 检查您的系统上是否安装了 git
2. 验证是否不会推送 .env 等敏感文件（它们位于 .gitignore 中）
3. 提示您输入 GitHub 存储库 URL
4. 如果需要，初始化 git 存储库，或更新远程 URL
5. 添加所有文件并显示它们以供您查看
6. 使用描述性消息提交更改
7. 将更改推送到 GitHub

这使得共享您的自定义项或贡献回项目变得容易，同时确保敏感信息的安全。