asset-health-mcp

Un agente de IA que decide si enviar a un técnico de campo — y se niega a actuar sobre datos en los que no puede confiar.

Agente Agentforce basado en Salesforce Data Cloud, que llama a un servidor MCP personalizado para la validación de la calidad de los datos (Great Expectations) y la puntuación de anomalías (Databricks), con una escritura de retorno en Apex protegida que crea la WorkOrder.

🎥 Vídeo de demostración de 2 minutos — observa al agente validar, puntuar, crear una orden de trabajo y luego rechazar un lote corrupto.

Por qué existe

La mayoría de las demos de agentes dejan que el LLM actúe sobre los datos que recupera. En el servicio de campo, actuar sobre una lectura de contador corrupta significa enviar un técnico para nada — o peor, no atender un activo que está fallando. Este proyecto coloca una barrera de confianza de datos delante de cada decisión del agente:

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

Related MCP server: qc-validator-mcp

Decisiones de diseño

• Dos herramientas MCP seleccionadas, no un volcado de datos. El agente recibe juicio (confianza + severidad); el historial bruto le llega por separado a través del fundamento cero-copia de Data Cloud. Se mantiene muy dentro del presupuesto de herramientas de Agentforce.

• Los controles viven en el servidor. La acción Apex rechaza datos no confiables y solicitudes de severidad normal incluso si el agente lo pide — las instrucciones del agente no son un límite de seguridad (OWASP LLM07).

• Escritura idempotente. Los agentes reintentan; los despacho de campo duplicados cuestan dinero real. Una única Asset Health WorkOrder abierta por cada activo, aplicada en Apex.

• Se ejecutasu sin credenciales. El simulacamiento determinista de Databricks + el contexto efímero de GX hacen que pytest sea correcto en un clon sin servicios externos.

Stack

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

Estructura del repositorio

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

Cero-copia en una línea: las lecturas se quedan en Snowflake (Query Federation, pushdown de JDBC a analmacén XS aislado), las puntuaciones se quedan en Databricks (File Federation mediante UniForm/Iceberg, cero cómputo externo) — el modo se elige por tabla basado en coste, no por predeterminado. Detalles: datacloud/ZERO_COPY.md.

Cómo ejecutarlo

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

Manual de compilación completo: docs/SETUP.md (paso a paso, ordenado en torno a las restricciones de licencia de prueba) · integración del agente: docs/AGENT_BUILD.md · qué se ejecuta en cada edición y qué está documentado en lugar de demostrado: docs/ENVIRONMENTS.md.

Limitaciones conocidas

Autenticación de grado de demostración (PAT, no OAuth2 service principal), puntuaciones precalculadas en lugar de servir modelos en tiempo real, organización única. Limitaciones enumeradas deliberadamente — el objetivo del proyecto es la arquitectura, no el endurecimiento de producción.

Construido por Yamyle — Arquitecto Salesforce Senior e Ingeniero de Datos/IA. Más de 20 certificaciones de Salesforce · marcos de integración para servicios públicos y servicios financieros.