Agentforce MCP Server

此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：你的已连接应用中的消费者密钥
   • 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"  # 在Salesforce中找到的18位代理ID
   SALESFORCE_CLIENT_ID="your_client_id_here"  # 已连接应用中的消费者密钥
   SALESFORCE_CLIENT_SECRET="your_client_secret_here"  # 已连接应用中的消费者秘密
   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. 注意消费者密钥（这是你的客户端ID），并点击点击显示旁边的消费者秘密以获取你的客户端秘密

查找你的代理ID

要找到你的Agentforce代理ID：

1. 登录到你的Salesforce组织
2. 导航至Einstein Agent Builder
3. 选择你要使用的代理
4. 查看浏览器中的URL——它将包含格式为https://your-salesforce-instance.lightning.force.com/lightning/r/Agent__c/0XxXXXXXXXXXXXXX/view的代理ID
5. URL中的18位ID（0XxXXXXXXXXXXXXX）就是你的代理ID

查找你的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

这使得分享你的自定义内容或为项目做出贡献变得容易，同时确保敏感信息的安全。