Salesforce Headless MCP AI

一个面向生产环境的 Frappe v15+ 应用，为每个授权 Frappe 用户提供基于可配置 AI 提供商和 Salesforce Hosted MCP 的 Web AI 助手。Salesforce OAuth 令牌和 AI API 密钥在 Frappe 服务器上保持加密；浏览器代码仅调用白名单中的 Frappe 方法。

Salesforce Headless 360 MCP 目前是 Salesforce Beta 服务。在生产使用前，请验证您组织的可用性、限制和条款。

项目文档

• 开发技术文档

• 完整项目演示脚本

Related MCP server: Salesforce MCP Server

架构

Frappe browser page (/salesforce-ai)
        ↓ authenticated frappe.call
Frappe Python services
        ├── OpenAI / Claude / Gemini / Azure / local LLM (tool calling)
        └── Salesforce Hosted MCP (Streamable HTTP + OAuth bearer token)
                    ↓
              Salesforce org

MCP 工具列表在运行时获取。在只读模式下，服务器仅允许 discover、describe 和 dispatch_readonly；dispatch 从模型的工具中移除，并在 Python 中独立阻止。当启用写入时，dispatch 保存在一个十分钟、用户绑定的确认记录中，直到用户明确确认。

该应用还支持 Salesforce SObject 服务器。对于 platform/sobject-all，只读模式仅暴露标记为只读的工具（加上 Salesforce 已知的 schema/query/search/identity/relationship 读取工具）。当启用写入时，发现的变更工具会被暴露，并且每次创建/更新/删除调用都使用相同的确认门控。

要求

• Frappe Framework v15 或更高版本，以及一个可用的 Bench 站点

• Python 3.10+

• 一个 Salesforce 组织，API v67.0+ 且已激活 Headless 360

• 一个配置了 OAuth Authorization Code + PKCE S256 的 Salesforce External Client App

• 一个 OpenAI API 密钥，可访问配置的模型

• 公共 Frappe 站点使用 HTTPS

Python 依赖（httpx 和 openai）在 pyproject.toml 中声明，并随应用安装。

安装

cd ~/frappe-bench
bench get-app https://github.com/TechwithZakir/salesforce_mcp_ai
bench --site yoursite.example install-app salesforce_mcp_ai
bench --site yoursite.example migrate
bench build --app salesforce_mcp_ai
bench restart

本地开发：

cd ~/frappe-bench
bench new-app salesforce_mcp_ai
# Replace the generated app with this repository, or clone it into apps/salesforce_mcp_ai.
bench --site development.localhost install-app salesforce_mcp_ai
bench --site development.localhost migrate
bench build --app salesforce_mcp_ai

将 Salesforce MCP Manager 分配给管理员，将 Salesforce MCP User 分配给工作坊用户。以管理员身份打开 Salesforce MCP Settings 并保存配置，然后访问 /salesforce-ai。

升级现有安装后，运行 bench --site yoursite.example migrate 和 bench --site yoursite.example clear-cache。然后，公共的 Salesforce MCP AI 工作区会出现在 Desk 中，供分配了 Salesforce MCP User、Salesforce MCP Manager 或 System Manager 的用户使用。

Salesforce 设置

1. 在 Salesforce Setup 中，搜索 MCP Servers。

2. 选择 MCP Servers，找到 headless-360 并激活它。

3. 转到 External Client App Manager 并创建一个 External Client App。

4. 启用 OAuth Authorization Code 流程，并使用 S256 要求 PKCE。

5. 添加作用域 mcp_api、refresh_token 和 offline_access（使用您的 Salesforce 版本暴露的标签/选项）。

6. 将回调 URL 精确设置为：

https://YOUR-FRAPPE-DOMAIN/api/method/salesforce_mcp_ai.api.auth.salesforce_callback

7. 将消费者密钥以及（如果应用策略要求）客户端密钥复制到 Salesforce MCP Settings 中。

Salesforce 对每个 MCP 操作强制执行连接用户的 CRUD、字段级安全、共享、配置文件和权限集。仅向工作坊用户授予他们所需的 Salesforce 权限。

配置

推荐的生产配置：

Enabled:                         On
AI Provider:                     OpenAI
API Key:                         (encrypted)
Model:                           gpt-5.6
Temperature:                     0.2
Max Tokens:                      4000
Salesforce Login URL:            https://login.salesforce.com
Salesforce MCP URL:              https://api.salesforce.com/platform/mcp/v1/platform/headless-360
Allow Write Operations:          Off
Require Write Confirmation:      On
Enable MCP Trace:                On
Enable Audit Logging:            On
Maximum MCP Tool Calls:          6
Request Timeout:                 60

OpenAI API 密钥和 External Client App 客户端密钥是 Frappe Password 字段。访问令牌和刷新令牌也是每个用户 Salesforce Connection 文档上的 Password 字段。它们仅由后端代码使用 Frappe 的加密密码 API 读取。

沙盒

无需代码更改即可切换：

Salesforce Login URL: https://test.salesforce.com
Salesforce MCP URL:   https://api.salesforce.com/platform/mcp/v1/sandbox/platform/headless-360

使用具有相同回调和作用域的沙盒 External Client App。

SObject All 服务器

在 Salesforce Setup → MCP Servers 下激活 SObject All，然后配置：

Production/Developer org: https://api.salesforce.com/platform/mcp/v1/platform/sobject-all
Sandbox/Scratch org:      https://api.salesforce.com/platform/mcp/v1/sandbox/platform/sobject-all

使用只读模式查询 Cases、Opportunities、Accounts 和其他记录。仅在需要创建/更新/删除操作时启用写入；确认通常应保持启用。

AI 提供商配置

在 Salesforce MCP Settings 中选择一个提供商：

• OpenAI：输入 OpenAI API 密钥和模型。

• Claude：输入 Anthropic API 密钥和 Claude 模型名称。

• Gemini：输入 Gemini API 密钥和模型名称。

• Azure OpenAI：输入密钥、HTTPS 资源端点和部署名称。使用当前的 v1 端点。

• 本地 LLM（OpenAI 兼容）：输入 OpenAI 兼容的 /v1 基础 URL 和模型名称。对于不安全的回环服务器，密钥可以为空。

本地服务器示例：

Ollama:    http://127.0.0.1:11434/v1
LM Studio: http://127.0.0.1:1234/v1
LiteLLM:   https://llm.example.com/v1
vLLM:      https://vllm.example.com/v1

所选模型必须支持工具/函数调用。仅接受回环主机名或地址的本地 HTTP；远程端点需要 HTTPS。代理发送固定的安全指令，并且仅发送动态返回的、策略过滤的 MCP 架构。最大值按单个工具调用计数，而不仅仅是迭代次数。

安全与生产说明

• 除非需要变更操作，否则保持 Allow Write Operations 关闭。当写入开启时，保持确认启用。

• OAuth 状态和 PKCE 验证器是服务器缓存条目，十分钟后过期，且仅使用一次。

• 待处理的写入是用户绑定的、单次使用，并在十分钟后过期。

• 配置的 MCP 主机限制为 api.salesforce.com 上的 HTTPS，以降低 SSRF 风险。

• 授权错误仅触发一次刷新尝试。刷新失败会断开账户。

• 审计负载已编辑并截断。不要向跟踪或自定义日志添加秘密字段。

• 仅通过 HTTPS 提供 Frappe 服务，保护 Redis 和加密密钥，轮换秘密，使用限制性角色，并配置备份。

• 在将 Salesforce 数据发送到 LLM 之前，请查看 Salesforce Beta 条款和您组织的数据处理政策。

• 普通聊天为工作坊清晰度而同步。服务类已隔离，以便后续端点可以通过 frappe.enqueue 调用它们。

权限

• Salesforce MCP User：使用助手，连接/断开自己的 Salesforce 账户，并仅查看自己的日志。

• Salesforce MCP Manager：配置设置并查看所有审计日志/连接。API 永远不会返回秘密值。

所有权由 DocType 权限钩子以及每个白名单方法中的过滤器强制执行。

测试与验证

测试使用模拟，不需要实时 Salesforce 组织或 OpenAI 调用：

bench --site development.localhost run-tests --app salesforce_mcp_ai
bench --site development.localhost migrate
bench build --app salesforce_mcp_ai

覆盖范围包括 PKCE、一次性 OAuth 状态、令牌刷新、只读工具过滤和阻止、连接/日志所有权以及工具调用限制设置。对于发布，还需对 /salesforce-ai、OAuth 回调、工具发现以及针对专用 Salesforce 测试用户的一个只读提示执行浏览器冒烟测试。

工作坊演示

1. 以具有 Salesforce MCP User 角色的用户身份登录。

2. 打开 /salesforce-ai，点击 Connect Salesforce，并完成 OAuth。

3. 确认徽章为绿色，模式显示 Read Only，并且 MCP 工具出现。

4. 询问：“Find Acme Corporation.” 展开跟踪以显示 discover、describe 和 dispatch_readonly。

5. 询问：“Show its open opportunities,” 然后 “Which opportunity should I prioritize?”

6. 可选：以管理员身份启用写入。要求创建后续任务，查看建议的 dispatch 参数，并点击 Confirm & Execute。

7. 打开 Salesforce MCP Log 以显示截断的审计跟踪。

故障排除

• OAuth state invalid or expired：重新启动 Connect Salesforce 并在十分钟内完成；验证 Redis/缓存健康状况以及回调是否返回到相同的 Frappe 部署。

• redirect_uri mismatch：精确复制上面显示的回调，包括方案和主机名。

• invalid scope / MCP access denied：激活 Headless 360，确认 API v67.0+、mcp_api 作用域以及用户的 Salesforce 权限。

• 401 after connection：如果刷新失败，请重新连接；验证 External Client App 的刷新令牌策略和客户端密钥要求。

• No MCP tools：确认配置的生产/沙盒端点和服务器激活。

• OpenAI error：验证 API 密钥、模型访问、配额、出站网络访问和超时。

• Maximum tool calls reached：使提示更具体，或谨慎提高限制（此应用接受的最大值为 20）。

• Page redirects to login / permission denied：登录并分配一个 Salesforce MCP 角色。

技术故障通过 frappe.log_error 记录；浏览器响应不包含堆栈跟踪或秘密。

源代码布局

salesforce_mcp_ai/
├── api/          # whitelisted auth, MCP, and agent methods
├── services/     # OAuth, token, MCP transport, OpenAI orchestration
├── utils/        # PKCE, validation, redaction
├── salesforce_mcp_ai/doctype/
├── tests/
└── www/salesforce-ai/

许可证

MIT