Salesforce Headless MCP AI

Eine produktionsorientierte Frappe-v15+-Anwendung, die jedem autorisierten Frappe-Benutzer einen Web-KI-Assistenten bietet, der von einem konfigurierbaren KI-Anbieter und Salesforce Hosted MCP unterstützt wird. Salesforce-OAuth-Tokens und KI-API-Schlüssel bleiben verschlüsselt auf dem Frappe-Server; Browser-Code ruft nur auf die Whitelist gesetzte Frappe-Methoden auf.

Salesforce Headless 360 MCP ist derzeit ein Salesforce-Betadienst. Prüfen Sie Verfügbarkeit, Limits und Bedingungen für Ihre Organisation, bevor Sie ihn in der Produktion einsetzen.

Projektdokumentation

• Technische Entwicklungsdokumentation

• Vollständiges Projektpräsentationsskript

Related MCP server: Salesforce MCP Server

Architektur

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

Die MCP-Toolliste wird zur Laufzeit abgerufen. Im Nur-Lese-Modus erlaubt der Server nur discover, describe und dispatch_readonly; dispatch wird aus den Tools des Modells entfernt und in Python unabhängig blockiert. Wenn Schreibvorgänge aktiviert sind, wird dispatch in einem zehnminütigen, benutzergebundenen Bestätigungsdatensatz gehalten, bis der Benutzer explizit bestätigt.

Die Anwendung unterstützt auch Salesforce-SObject-Server. Für platform/sobject-all werden im Nur-Lese-Modus nur als schreibgeschützt markierte Tools verfügbar gemacht (zusätzlich zu den bekannten Salesforce-Schema-/Abfrage-/Such-/Identitäts-/Beziehungs-Lesetools). Wenn Schreibvorgänge aktiviert sind, werden erkannte Mutations-Tools verfügbar gemacht, und jeder Create-/Update-/Delete-Aufruf verwendet dieselbe Bestätigungssperre.

Anforderungen

• Frappe Framework v15 oder neuer und eine funktionierende Bench-Site

• Python 3.10+

• Eine Salesforce-Organisation mit API v67.0+ und aktiviertem Headless 360

• Eine Salesforce External Client App, die für OAuth Authorization Code + PKCE S256 konfiguriert ist

• Ein OpenAI-API-Schlüssel mit Zugriff auf das konfigurierte Modell

• HTTPS für die öffentliche Frappe-Site

Python-Abhängigkeiten (httpx und openai) sind in pyproject.toml deklariert und werden mit der App installiert.

Installation

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

Für die lokale Entwicklung:

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

Weisen Sie Administratoren die Rolle Salesforce MCP Manager und Workshop-Benutzern Salesforce MCP User zu. Öffnen Sie Salesforce MCP Settings als Manager und speichern Sie die Konfiguration, dann besuchen Sie /salesforce-ai.

Nach einem Upgrade einer bestehenden Installation führen Sie bench --site yoursite.example migrate und bench --site yoursite.example clear-cache aus. Der öffentliche Salesforce MCP AI-Arbeitsbereich erscheint dann in Desk für Benutzer mit der Rolle Salesforce MCP User, Salesforce MCP Manager oder System Manager.

Salesforce-Einrichtung

1. Suchen Sie in der Salesforce-Einrichtung nach MCP Servers.

2. Wählen Sie MCP Servers, finden Sie headless-360 und aktivieren Sie es.

3. Gehen Sie zum External Client App Manager und erstellen Sie eine External Client App.

4. Aktivieren Sie den OAuth-Authorization-Code-Flow und verlangen Sie PKCE mit S256.

5. Fügen Sie die Scopes mcp_api, refresh_token und offline_access hinzu (verwenden Sie die von Ihrer Salesforce-Version bereitgestellten Bezeichnungen/Optionen).

6. Setzen Sie die Callback-URL exakt auf:

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

7. Kopieren Sie den Consumer Key und, falls von der App-Richtlinie gefordert, das Client Secret in Salesforce MCP Settings.

Salesforce erzwingt für jeden MCP-Vorgang die CRUD-, Feld-Sicherheits-, Freigabe-, Profil- und Berechtigungssatz-Regeln des verbundenen Benutzers. Geben Sie Workshop-Benutzern nur die Salesforce-Berechtigungen, die sie benötigen.

Konfiguration

Empfohlene Produktionskonfiguration:

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

Der OpenAI-API-Schlüssel und das Client Secret der External Client App sind Frappe-Password-Felder. Zugriffs- und Aktualisierungstokens sind ebenfalls Password-Felder im benutzerbezogenen Salesforce Connection-Dokument. Sie werden nur von Backend-Code über die verschlüsselte Passwort-API von Frappe gelesen.

Sandbox

Wechsel ohne Codeänderungen:

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

Verwenden Sie eine Sandbox-External-Client-App mit derselben Callback-URL und denselben Scopes.

SObject-All-Server

Aktivieren Sie SObject All unter Salesforce-Einrichtung → MCP Servers und konfigurieren Sie dann:

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

Verwenden Sie den Nur-Lese-Modus zum Abfragen von Cases, Opportunities, Accounts und anderen Datensätzen. Aktivieren Sie Schreibvorgänge nur, wenn Create-/Update-/Delete-Operationen erforderlich sind; die Bestätigung sollte normalerweise aktiviert bleiben.

KI-Anbieterkonfiguration

Wählen Sie einen Anbieter in Salesforce MCP Settings:

• OpenAI: Geben Sie einen OpenAI-API-Schlüssel und ein Modell ein.

• Claude: Geben Sie einen Anthropic-API-Schlüssel und einen Claude-Modellnamen ein.

• Gemini: Geben Sie einen Gemini-API-Schlüssel und einen Modellnamen ein.

• Azure OpenAI: Geben Sie den Schlüssel, den HTTPS-Ressourcenendpunkt und den Bereitstellungsnamen ein. Der aktuelle v1-Endpunkt wird verwendet.

• Lokales LLM (OpenAI-kompatibel): Geben Sie eine OpenAI-kompatible /v1-Basis-URL und einen Modellnamen ein. Der Schlüssel kann für einen ungesicherten Loopback-Server leer bleiben.

Beispiele für lokale Server:

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

Das ausgewählte Modell muss Tool-/Funktionsaufrufe unterstützen. Lokales HTTP wird nur für einen Loopback-Hostnamen oder eine Loopback-Adresse akzeptiert; entfernte Endpunkte erfordern HTTPS. Der Agent sendet feste Sicherheitsanweisungen und nur dynamisch zurückgegebene, richtliniengefilterte MCP-Schemas. Das Maximum wird über einzelne Tool-Aufrufe gezählt, nicht nur über Iterationen.

Sicherheits- und Produktionshinweise

• Lassen Sie Allow Write Operations deaktiviert, es sei denn, Mutationen sind erforderlich. Lassen Sie die Bestätigung aktiviert, wenn Schreibvorgänge aktiviert sind.

• OAuth-State und PKCE-Verifier sind Server-Cache-Einträge, laufen nach zehn Minuten ab und werden einmal verbraucht.

• Ausstehende Schreibvorgänge sind benutzergebunden, einmalig und laufen nach zehn Minuten ab.

• Der konfigurierte MCP-Host ist auf HTTPS auf api.salesforce.com beschränkt, um das SSRF-Risiko zu verringern.

• Autorisierungsfehler lösen genau einen Aktualisierungsversuch aus. Fehlgeschlagene Aktualisierungen trennen das Konto.

• Audit-Payloads werden geschwärzt und gekürzt. Fügen Sie keine geheimen Felder zu Traces oder benutzerdefinierten Protokollen hinzu.

• Betreiben Sie Frappe nur über HTTPS, sichern Sie Redis und den Verschlüsselungsschlüssel, rotieren Sie Geheimnisse, verwenden Sie restriktive Rollen und konfigurieren Sie Backups.

• Prüfen Sie die Salesforce-Betabedingungen und die Datenverarbeitungsrichtlinie Ihrer Organisation, bevor Sie Salesforce-Daten an ein LLM senden.

• Normaler Chat ist aus Gründen der Workshop-Klarheit synchron. Dienstklassen sind isoliert, sodass ein späterer Endpunkt sie über frappe.enqueue aufrufen kann.

Berechtigungen

• Salesforce MCP User: Assistent nutzen, eigenes Salesforce-Konto verbinden/trennen und nur eigene Protokolle anzeigen.

• Salesforce MCP Manager: Einstellungen konfigurieren und alle Audit-Protokolle/Verbindungen anzeigen. Geheime Werte werden niemals von einer API zurückgegeben.

Die Eigentümerschaft wird sowohl durch DocType-Berechtigungshooks als auch durch Filter in jeder auf der Whitelist stehenden Methode durchgesetzt.

Tests und Verifizierung

Tests verwenden Mocks und benötigen keine Live-Salesforce-Organisation oder keinen OpenAI-Aufruf:

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

Die Abdeckung umfasst PKCE, einmaligen OAuth-State, Token-Aktualisierung, Nur-Lese-Tool-Filterung und -Blockierung, Verbindungs-/Protokoll-Eigentümerschaft und die Tool-Aufruf-Limit-Einstellung. Für eine Veröffentlichung führen Sie außerdem einen Browser-Smoke-Test von /salesforce-ai, OAuth-Callback, Tool-Erkennung und einer Nur-Lese-Aufforderung gegen einen dedizierten Salesforce-Testbenutzer durch.

Workshop-Demo

1. Melden Sie sich als Benutzer mit der Rolle Salesforce MCP User an.

2. Öffnen Sie /salesforce-ai, klicken Sie auf Connect Salesforce und schließen Sie OAuth ab.

3. Bestätigen Sie, dass das Abzeichen grün ist, der Modus Read Only anzeigt und die MCP-Tools erscheinen.

4. Fragen Sie: „Finde Acme Corporation.“ Erweitern Sie den Trace, um discover, describe und dispatch_readonly zu zeigen.

5. Fragen Sie: „Zeige ihre offenen Opportunities“, dann „Welche Opportunity sollte ich priorisieren?“

6. Aktivieren Sie optional Schreibvorgänge als Manager. Bitten Sie darum, eine Folgeaufgabe zu erstellen, prüfen Sie die vorgeschlagenen dispatch-Argumente und klicken Sie auf Confirm & Execute.

7. Öffnen Sie Salesforce MCP Log, um den gekürzten Audit-Trail zu zeigen.

Fehlerbehebung

• OAuth-Status ungültig oder abgelaufen: Starten Sie Connect Salesforce neu und schließen Sie innerhalb von zehn Minuten ab; überprüfen Sie die Redis-/Cache-Gesundheit und dass der Callback zur selben Frappe-Bereitstellung zurückkehrt.

• redirect_uri-Stimmt-nicht-überein: Kopieren Sie die oben gezeigte Callback-URL exakt, einschließlich Schema und Hostname.

• Ungültiger Scope / MCP-Zugriff verweigert: Aktivieren Sie Headless 360, bestätigen Sie API v67.0+, den mcp_api-Scope und die Salesforce-Berechtigungen des Benutzers.

• 401 nach der Verbindung: Stellen Sie die Verbindung erneut her, wenn die Aktualisierung fehlgeschlagen ist; überprüfen Sie die Refresh-Token-Richtlinie und die Client-Secret-Anforderung der External Client App.

• Keine MCP-Tools: Bestätigen Sie den konfigurierten Produktions-/Sandbox-Endpunkt und die Server-Aktivierung.

• OpenAI-Fehler: Überprüfen Sie den API-Schlüssel, den Modellzugriff, das Kontingent, den ausgehenden Netzwerkzugriff und das Timeout.

• Maximale Tool-Aufrufe erreicht: Machen Sie die Aufforderung spezifischer oder erhöhen Sie das Limit vorsichtig (das von dieser Anwendung akzeptierte Maximum beträgt 20).

• Seite leitet zur Anmeldung um / Berechtigung verweigert: Melden Sie sich an und weisen Sie eine der Salesforce-MCP-Rollen zu.

Technische Fehler werden mit frappe.log_error protokolliert; Browser-Antworten enthalten keine Stack-Traces oder Geheimnisse.

Quellstruktur

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/

Lizenz

MIT