# 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](https://modelcontextprotocol.io) 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](docs/demo.mp4)** — 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](datacloud/ZERO_COPY.md).

## Run it

```bash
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](docs/SETUP.md)** (step by step, ordered
around trial-licence constraints) · agent wiring:
[docs/AGENT_BUILD.md](docs/AGENT_BUILD.md) · what runs on which edition and
what is documented rather than demonstrated:
[docs/ENVIRONMENTS.md](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.*