Agentforce MCP Server

Agentforce MCP 服务器

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

克隆后入门

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

安装脚本将：

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 ：来自您连接的应用程序的消费者密钥
   • SALESFORCE_CLIENT_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" # The 18-character Agent ID you found in Salesforce SALESFORCE_CLIENT_ID="your_client_id_here" # The Consumer Key from your Connected App SALESFORCE_CLIENT_SECRET="your_client_secret_here" # The Consumer Secret from your Connected App SALESFORCE_SERVER_URL="your_server_url_here" # Your My Domain URL (e.g., example.my.salesforce.com)

Salesforce 配置

要使用 Agentforce API，您需要：

1. 在您的 Salesforce 组织中创建连接的应用程序
2. 查找您的 Agentforce 代理 ID
3. 记下您的 Salesforce My Domain URL

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

运行服务器

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

可用工具

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文件：

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

不同平台的路径位置

macOS

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

视窗

• 配置文件： %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 Integration（或您喜欢的任何名称）
   • API 名称：Agentforce_MCP_Integration（将自动填充）
   • 联系邮箱：您的电子邮件地址
6. 检查启用 OAuth 设置
7. 将回调 URL设置为https://localhost/oauth/callback （虽然未使用但必需）
8. 在Selected OAuth Scopes下，添加：
   • 通过API（api）管理用户数据
   • 随时执行请求（refresh_token、offline_access）
9. 点击**“保存”**
10. 保存后，您将被重定向到已连接的应用详细信息页面
11. 记下消费者密钥（这是您的客户端 ID），然后单击消费者密钥旁边的单击以显示以获取您的客户端密钥

查找您的代理 ID

要查找您的 Agentforce 代理 ID：

1. 登录您的 Salesforce 组织
2. 导航至Einstein Agent Builder
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 范围

测试设置

您可以使用附带的测试脚本测试您的设置：

这将尝试进行身份验证、创建会话并与您的 Agentforce 代理交换消息。

贡献和 GitHub Push

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

github_push.sh脚本将：

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

这使得您可以轻松共享您的定制或回馈项目，同时确保敏感信息的安全。