asset-health-mcp

An AI agent that decides whether to dispatch a field technician — and refuses to act on data it can't trust.

Agentforce agent grounded on Salesforce Data Cloud, calling a custom MCP server for data-quality validation (Great Expectations) and anomaly scoring (Databricks), with a guarded Apex write-back that creates the WorkOrder.

🎥 2-minute demo video — watch the agent validate, score, create a work order, then refuse a corrupted batch.

Why this exists

Most agent demos let the LLM act on whatever data it retrieves. In field service, acting on a corrupted meter reading means dispatching a technician for nothing — or worse, missing a failing asset. This project puts a data-trust gate in front of every agent decision:

readings ──▶ Ingestion API ──▶ Data Cloud (zero-copy grounding)
                                     │
                                     ▼
                          Agentforce agent
                          │ 1. check_reading_quality   MCP / Great Expectations
                          │ 2. score_asset_anomaly     MCP / Databricks
                          │ 3. create work order       Apex (guarded write-back)
                                     │
                                     ▼
                            Salesforce WorkOrder

Design decisions

• Two curated MCP tools, not a data dump. The agent gets judgment (trust + severity); raw history reaches it separately through Data Cloud zero-copy grounding. Stays far inside Agentforce's tool budget.
• Guards live server-side. The Apex action refuses untrusted data and normal-severity requests even if the agent asks — agent instructions are not a security boundary (OWASP LLM07).
• Idempotent write-back. Agents retry; duplicate field dispatches cost real money. One open Asset Health WorkOrder per asset, enforced in Apex.
• Runs with zero credentials. Deterministic Databricks mock + GX ephemeral context mean pytest is green on a fresh clone with no external services.

Stack

Python 3.11 · FastMCP (mcp 1.x) · Great Expectations 1.18 · Databricks (Unity Catalog) · Salesforce Data Cloud (Ingestion API, DMO grounding) · Agentforce · Apex

Repository layout

src/asset_health_mcp/    FastMCP server: tools, GX validation, Databricks client
pipeline/                Ingestion API pipeline → Meter Reading DMO (fallback path)
force-app/               Apex write-back action + tests
databricks/              PySpark scoring job → Unity Catalog Delta table with
                         UniForm (Iceberg) — zero-copy File Federation ready
snowflake/               readings warehouse DDL + least-privilege key-pair
                         integration user for Query Federation
datacloud/               ZERO_COPY.md — federation-mode decisions and setup
docs/                    AGENT_BUILD.md (Agentforce wiring), demo script
tests/                   smoke suite, green with zero external services

Zero-copy design in one line: readings stay in Snowflake (Query Federation, JDBC pushdown to an isolated XS warehouse), scores stay in Databricks (File Federation via UniForm/Iceberg, zero external compute) — mode chosen per table on cost, not by default. Details: datacloud/ZERO_COPY.md.

Run it

pip install -e ".[dev]" && pytest          # zero-credential smoke suite
python -m asset_health_mcp.server          # stdio, for Claude Desktop
MCP_TRANSPORT=streamable-http \
  python -m asset_health_mcp.server        # HTTP, for Agentforce registry
sf project deploy start                    # Apex action + tests

Full build runbook: docs/SETUP.md (step by step, ordered around trial-licence constraints) · agent wiring: docs/AGENT_BUILD.md · what runs on which edition and what is documented rather than demonstrated: docs/ENVIRONMENTS.md.

Known limits

Demo-grade auth (PAT, not OAuth service principal), precomputed scores rather than real-time model serving, single-org. Listed deliberately — the point of the project is the architecture, not production hardening.

---

Built by Yamyle — Senior Salesforce Architect & Data/AI Engineer. 20+ Salesforce certifications · integration frameworks for utilities and financial services.