asset-health-mcp

현장 기술자를 파견할 지 결정하고 — 신뢰할 수 없는 데이터에는 행동하지 않는 AI 에이전트.

Salesforce Data Cloud에 기반을 둔 Agentforce 에이전트로, 커스텀 MCP 서버를 호출해 데이터 품질 검증(Great Expectations)과 변칙 점수 산정(Databricks)을 수행하고, 보호된(guarded) Apex write-back으로 WorkOrder를 생성합니다.

🎥 2분 데모 영상 — 에이전트가 검증하고, 점수를 매기고, 작업 오더를 만든 뒤, 손상된 배치를 거부하는 모습을 확인하세요.

Why this exists

대부분의 에이전트 데모는 LLM이 조회한 데이터라면 그대로 행동하도록 둡니다. 하지만 필드 서비스에서 손상된 계량기 판독값(meter reading)을 신뢰한 채 행동하면 기술자를 헛되이 파견하거나 — 더 심하면 고장 난 자산을 놓치는 일이 생깁니다. 이 프로젝트는 모든 에이전트 결정 앞에 데이터 신뢰 게이트(data-trust gate) 를 둡니다:

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

설계 결정 사항

• 데이터 덤프가 아니라 엄선된 두 개의 MCP 도구. 에이전트는 판단(신뢰도 + 심각도)을 받을 뿐이며, 원본 이력은 Data Cloud zero-copy grounding을 통해 별 스트림으로 전달됩니다. Agentforce의 도구 예산(tool budget) 한도 내에서 넉넉하게 동작합니다.

• 가드는 서버 측에서 유지됩니다. Agent Apex 액션은 에이전트가 요청하더라도 신뢰할 수 없는 데이터와 일반 심각도(normal-severity) 요청은 거부합니다. 에이전트 지침은 보안 경계가 아니기 때문입니다(OWASP LLM07).

• 멱등성(idempotent) write-back. 에이전트는 재시도하지만, 중복된 현장 파견은 실지로 비용이 드는 일입니다. 자산당 열려 있는 Asset Health WorkOrder는 하나뿐이도록 Apex에서 강제합니다.

• zero credentials로 실행됩니다. 결정적(Deterministic) Databricks mock + GX 일회성(ephemeral) 컨텍스트 덕분에 외부 서비스 없이 새로운 클론에서도 pytest가 그대로 통과(green)합니다.

기술 스택

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

저장소 구조

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 설계의 한 줄 정리: 판독값은 Snowflake 있다 (Query Federation, JDBC pushdown to an isolated XS warehouse 또는 Query Federation), 점수는 Databricks에 남습니다 — (UniForm/Iceberg 경유의 File Federation, zero external compute). 기본이 아니라 비용을 테이블별로 선택하는 모드입니다. 자세한 내용은: datacloud/ZERO_COPY.md.

실행하기

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

전체 빌드 런북: docs/SETUP.md — 트라이얼 라이선스 제약을 반영한 단계별 순서 · 에이전트 연동: docs/AGENT_BUILD.md · 어떤 에디션에서 어떤 것이 실행되고 어떤 것이 데모가 아닌 문서로 제공되는지: docs/ENVIRONMENTS.md.

알려진 한계

데모 수준 인증(PAT, OAuth 서비스 주체 아님), 실시간 모델 서빙이 아닌 미리 계산된 점수(precomputed scores), 단일 조직(single-org). 의도된 한계가 분명히 나열되어 있습니다. 이 프로젝트의 초점요지는 프로덕션 레벨 안정화가 아니라 아키텍처입니다.

Built by Yamyle — Senior Salesforce Architect & Data/AI Engineer. Salesforce 인증 20+ 보유 · 유틸리티•금융 서비스용 통합 프레임워크.