Salesforce Headless MCP AI

Продакшн-ориентированное приложение для Frappe v15+, которое предоставляет каждому авторизованному пользователю Frappe веб-ИИ-ассистента на основе настраиваемого ИИ-провайдера и Salesforce Hosted MCP. OAuth-токены Salesforce и ключи ИИ-API остаются зашифрованными на сервере Frappe; код браузера вызывает только разрешённые методы Frappe.

Salesforce Headless 360 MCP в настоящее время является бета-сервисом Salesforce. Проверьте доступность, лимиты и условия для вашей организации перед использованием в продакшене.

Документация проекта

• Техническая документация по разработке

• Полный сценарий презентации проекта

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 в режиме только для чтения доступны только инструменты, помеченные как read-only (плюс известные инструменты чтения схемы/запросов/поиска/идентификации/связей Salesforce). Когда запись включена, обнаруженные инструменты мутации становятся доступными, и каждый вызов create/update/delete проходит через тот же механизм подтверждения.

Требования

• Frappe Framework v15 или новее и работающий сайт Bench

• Python 3.10+

• Организация Salesforce с API v67.0+ и активированным Headless 360

• Внешнее клиентское приложение Salesforce, настроенное для OAuth Authorization Code + PKCE S256

• Ключ OpenAI API с доступом к настроенной модели

• HTTPS для публичного сайта Frappe

Зависимости 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 найдите MCP Servers.

2. Выберите MCP Servers, найдите headless-360 и активируйте его.

3. Перейдите в External Client App Manager и создайте внешнее клиентское приложение.

4. Включите поток OAuth Authorization Code и требуйте PKCE с S256.

5. Добавьте области mcp_api, refresh_token и offline_access (используйте метки/опции, доступные в вашем релизе Salesforce).

6. Установите URL обратного вызова точно как:

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

7. Скопируйте consumer key и, если требуется политикой приложения, client secret в Salesforce MCP Settings.

Salesforce применяет CRUD, безопасность на уровне полей, правила совместного доступа, профили и наборы разрешений подключённого пользователя для каждой MCP-операции. Дайте участникам воркшопа только те разрешения 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 и client secret внешнего клиентского приложения являются полями Password в Frappe. Токены доступа и обновления также являются полями Password в документе Salesforce Connection для каждого пользователя. Они читаются только серверным кодом через зашифрованный API паролей Frappe.

Песочница

Переключение без изменений кода:

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

Используйте внешнее клиентское приложение песочницы с тем же обратным вызовом и областями.

Сервер SObject All

Активируйте SObject All в Salesforce Setup → MCP Servers, затем настройте:

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 и другим записям. Включайте запись только когда требуются операции create/update/delete; подтверждение обычно должно оставаться включённым.

Конфигурация ИИ-провайдера

Выберите одного провайдера в Salesforce MCP Settings:

• OpenAI: введите ключ OpenAI API и модель.

• Claude: введите ключ Anthropic API и имя модели Claude.

• Gemini: введите ключ Gemini API и имя модели.

• Azure OpenAI: введите ключ, HTTPS-эндпоинт ресурса и имя развёртывания. Используется текущая конечная точка v1.

• Локальная LLM (совместимая с OpenAI): введите базовый URL /v1, совместимый с OpenAI, и имя модели. Ключ может быть пустым для незащищённого loopback-сервера.

Примеры для локальных серверов:

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 принимается только для loopback-имени хоста или адреса; удалённые эндпоинты требуют HTTPS. Агент отправляет фиксированные инструкции безопасности и только динамически возвращаемые, отфильтрованные по политике MCP-схемы. Максимум подсчитывается по отдельным вызовам инструментов, а не только по итерациям.

Безопасность и продакшн-заметки

• Держите Allow Write Operations выключенным, если мутации не требуются. Оставляйте подтверждение включённым, когда запись активна.

• OAuth state и PKCE-верификатор являются записями серверного кэша, истекают через десять минут и используются один раз.

• Ожидающие записи привязаны к пользователю, одноразовые и истекают через десять минут.

• Настроенный MCP-хост ограничен HTTPS на api.salesforce.com для снижения риска SSRF.

• Ошибки авторизации вызывают ровно одну попытку обновления токена. Неудачные обновления отключают аккаунт.

• Аудиторские полезные нагрузки маскируются и усекаются. Не добавляйте секретные поля в трассировки или пользовательские журналы.

• Обслуживайте Frappe только через HTTPS, защищайте Redis и ключ шифрования, ротируйте секреты, используйте ограничительные роли и настраивайте резервное копирование.

• Изучите бета-условия Salesforce и политику обработки данных вашей организации перед отправкой данных Salesforce в LLM.

• Обычный чат синхронен для ясности воркшопа. Сервисные классы изолированы, чтобы более поздняя конечная точка могла вызывать их через 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 state, обновление токена, фильтрацию и блокировку инструментов read-only, владение подключениями/журналами и настройку лимита вызовов инструментов. Для релиза также выполните браузерный смоук-тест /salesforce-ai, OAuth-обратного вызова, обнаружения инструментов и одного read-only запроса с выделенным тестовым пользователем Salesforce.

Демо для воркшопа

1. Войдите как пользователь с ролью Salesforce MCP User.

2. Откройте /salesforce-ai, нажмите Connect Salesforce и завершите OAuth.

3. Убедитесь, что бейдж зелёный, режим показывает Read Only, и MCP-инструменты отображаются.

4. Спросите: «Найди Acme Corporation». Разверните трассировку, чтобы показать discover, describe и dispatch_readonly.

5. Спросите: «Покажи её открытые сделки», затем «Какой сделке мне отдать приоритет?»

6. При желании включите запись как менеджер. Попросите создать задачу на последующие действия, просмотрите предложенные аргументы dispatch и нажмите Confirm & Execute.

7. Откройте Salesforce MCP Log, чтобы показать усечённый аудиторский след.

Устранение неполадок

• OAuth state недействителен или истёк: перезапустите Connect Salesforce и завершите в течение десяти минут; проверьте здоровье Redis/кэша и что обратный вызов возвращается в то же развёртывание Frappe.

• redirect_uri не совпадает: скопируйте обратный вызов, показанный выше, точно, включая схему и имя хоста.

• Недействительный scope / отказ в доступе MCP: активируйте Headless 360, подтвердите API v67.0+, scope mcp_api и разрешения пользователя Salesforce.

• 401 после подключения: переподключитесь, если обновление не удалось; проверьте политику refresh-токена внешнего клиентского приложения и требование client secret.

• Нет MCP-инструментов: подтвердите настроенный продакшн/песочница эндпоинт и активацию сервера.

• Ошибка OpenAI: проверьте ключ API, доступ к модели, квоту, исходящий сетевой доступ и таймаут.

• Достигнут максимум вызовов инструментов: сделайте запрос более конкретным или осторожно поднимите лимит (максимум, принимаемый этим приложением, — 20).

• Страница перенаправляет на вход / отказ в доступе: войдите и назначьте одну из ролей 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