Salesforce MCP UI Automation

MCP server Python per automatizzare Salesforce via browser Playwright con sessione persistente. L'MVP parte da Data Cloud, ma i tool sono generici abbastanza da coprire Setup, Marketing Cloud Growth, Agentforce e altre aree configurabili solo da UI.

Setup

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
python -m playwright install chromium
Copy-Item .env.example .env

Aggiorna .env con l'URL della tua org e, se usi le API Data Cloud, con endpoint tenant e token:

SALESFORCE_ORG_URL=https://your-domain.my.salesforce.com
SALESFORCE_INSTANCE_URL=https://your-domain.my.salesforce.com
SALESFORCE_ACCESS_TOKEN=
SALESFORCE_API_VERSION=61.0
SALESFORCE_DATACLOUD_API_URL=https://your-data-cloud-tenant.example.com
SALESFORCE_DATACLOUD_INGESTION_URL=https://your-ingestion-tenant.example.com
SALESFORCE_DATACLOUD_QUERY_URL=
SALESFORCE_DATACLOUD_ACCESS_TOKEN=
SALESFORCE_JOURNAL_REDACT_FIELDS=token,password,secret,access_token,refresh_token,authorization
SALESFORCE_OAUTH_CLIENT_ID=
SALESFORCE_OAUTH_CLIENT_SECRET=
SALESFORCE_OAUTH_REDIRECT_URI=http://localhost:1717/oauth/callback
SALESFORCE_OAUTH_SCOPES=api refresh_token
SALESFORCE_PROFILE=default
SALESFORCE_HEADLESS=false

Avvio MCP

python -m salesforce_mcp

Oppure, dopo installazione editable:

salesforce-mcp

Per configurare un client MCP, parti da mcp.example.json e aggiorna SALESFORCE_ORG_URL.

Autenticazione

Il server non salva username, password o token applicativi. Al primo uso apre Chromium con profilo persistente in .auth/<profile>. Completa login, SSO e MFA manualmente. Le chiamate successive riusano la stessa sessione finche Salesforce la mantiene valida.

Per usare le API senza copiare manualmente SALESFORCE_ACCESS_TOKEN, puoi chiamare use_browser_session_token dopo il login Playwright: il tool legge il cookie Salesforce sid tramite API Playwright e lo usa come token runtime in memoria. Il refresh token non viene estratto dalla normale sessione browser; per ottenerlo usa start_oauth_token_flow con una Connected App configurata per Authorization Code + PKCE e scope refresh_token.

Tool Esposti

Browser e Setup

• open_org: apre l'org configurata o un URL specifico.
• snapshot: restituisce URL, titolo, testo visibile, screenshot opzionale, DOM opzionale, iframe e suggerimenti.
• click: clicca per testo, selector CSS o ruolo accessibile.
• fill: compila un input per label/placeholder/testo o selector CSS.
• select: seleziona un valore in un campo select.
• wait_for: attende caricamenti, testo o selector.
• search_setup: apre Setup e cerca una voce.
• open_datacloud_area: apre o ricerca aree Data Cloud note.
• diagnose_datacloud: raccoglie uno snapshot diagnostico orientato a Data Cloud.
• close_browser: chiude browser e profilo persistente.

Autenticazione API

• browser_auth_status: verifica sessione Playwright e token runtime senza mostrare segreti.
• use_browser_session_token: usa il cookie sid Salesforce come token runtime per query_salesforce.
• start_oauth_token_flow: avvia OAuth Authorization Code + PKCE in Playwright e salva access/refresh token in memoria.
• refresh_oauth_token: rinnova l'access token runtime usando il refresh token.
• clear_runtime_tokens: svuota i token runtime in memoria.

Orchestrazione supervisionata

• list_capabilities: elenca workflow Data Cloud supportati, input attesi e classe di rischio.
• plan_request: crea un run journal per Data Streams, metadata, ingestion e validazioni Data Cloud.
• execute_plan: esegue il piano fino a completamento, errore o richiesta approvazione.
• get_run_status: legge lo stato completo di un run.
• approve_step: approva uno step supervisionato.
• rollback_run: prepara rollback safe/manual_review/dangerous sulle sole risorse tracciate.

Verifica dati

• query_salesforce: esegue SOQL usando token runtime o SALESFORCE_INSTANCE_URL e SALESFORCE_ACCESS_TOKEN.
• query_datacloud: esegue query Data Cloud su endpoint configurabile SALESFORCE_DATACLOUD_QUERY_URL.
• datacloud_submit_query: invia una query SQL alla Data Cloud Query API.
• datacloud_query_status: legge lo stato di una query Data Cloud.
• datacloud_query_rows: legge righe paginabili per una query Data Cloud.
• datacloud_cancel_query: cancella una query Data Cloud in esecuzione.
• datacloud_metadata: legge metadata Data Cloud per DLO, DMO, Calculated Insights, campi, chiavi e relazioni.
• assert_records: valida record count, campi obbligatori, valori attesi, freshness e assenza errori.
• compare_before_after: confronta evidenze query raccolte nel run journal.

Workflow supportati da plan_request:

• data_streams: configurazione supervisionata via browser.
• validate_data_stream: validazione metadata/query di uno stream.
• ingest_streaming_records: validazione e invio JSON via Streaming Ingestion API.
• ingest_bulk_csv: validazione CSV, creazione job, upload, close e status Bulk Ingestion API.
• inspect_data_model: ispezione DLO, DMO, relazioni, chiavi e key qualifier.
• validate_identity_resolution: validazione output identity resolution.
• validate_calculated_insight: validazione metadata e risultati Calculated Insight.
• validate_data_action: validazione dati e metadata collegati a Data Actions.

I run journal sono salvati in runs/<run_id>/run.json, esclusi da Git perche possono contenere dati operativi e screenshot correlati. I campi configurati in SALESFORCE_JOURNAL_REDACT_FIELDS vengono mascherati prima della scrittura.

Guardrail

Le azioni potenzialmente distruttive richiedono confirm_dangerous=true. Screenshot e log operativi sono salvati in logs/, escluso da Git insieme a .auth/ e .env.

Le scritture Data Cloud dei workflow ingestion richiedono approvazione step tramite approve_step. Gli endpoint Data Cloud restano configurabili per tenant: usa SALESFORCE_DATACLOUD_API_URL per Query/Metadata API, SALESFORCE_DATACLOUD_INGESTION_URL per Ingestion API e SALESFORCE_DATACLOUD_QUERY_URL solo come endpoint legacy compatibile per query_datacloud.

Test

pytest

I test automatici validano configurazione, guardrail, journal, planner, assertion engine e shape degli output. Se la directory temp utente non e' scrivibile, usa:

pytest -p no:cacheprovider --basetemp .testtmp

Il test reale su Salesforce resta manuale perche richiede una org e login interattivo.

Per validare anche Chromium/Playwright su una pagina HTML locale:

$env:RUN_PLAYWRIGHT_SMOKE="1"
pytest tests/test_browser_smoke.py