asset-health-mcp

フィールド技術者を派遣するかどうかを判断するAIエージェント — 信頼できないデータには、動作しない。

Salesforce Data Cloud にグラウンディングされた Agentforce エージェント。データ品質検証（Great Expectations）と異常スコアリング（Databricks）のためにカスタム MCP サーバーを呼び出し、WorkOrder を作成するガード付き Apex ライトバックを備えています。

🎥 2分のデモ動画 — エージェントが検証・スコアリング・作業指示書の作成を行い、その後で破損したバッチを拒否する様子をご覧ください。

なぜこのプロジェクトがあるのか

たいていのエージェントデモは、LLM が取得したデータをそのまま利用して行動できます。しかしフィールドサービスでは、破損したメーター測定値に基づいて行動すると、無駄に技術者を派遣することになります — あるいは、もっと悪い場合には、故障している資産を見逃してしまいます。このプロジェクトは、すべてのエージェント意思決定の前に、データへの信頼ゲートを置きます：

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

設計上の決定

• データダンプではなく、厳選された2つの MCP ツール。 エージェントは 判断（信頼度 + 重大度）を得ます。生の履歴は、Data Cloud のゼロコピー・グラウンディングを通じて別途到達します。Agentforce が利用できるツール数の範囲内に十分収まります。

• ガードはサーバーサイドに実装。 Apex アクションは、エージェントが要求しても、信頼できないデータや通常の重大度のリクエストを拒否します — エージェントの指示はセキュリティ境界ではありません（OWASP LLM07）。

• 冪等なライトバック。 エージェントは再試行しますが、フィールド派遣の重複は実際のコストとなります。Apex は、アセットごとに1件のオープン中の Asset Health WorkOrder を強制します。

• クレデンシャルなしで実行可能。 決定論的な Databricks モックと GX のエフェメラルコンテキストにより、pytest は外部サービスがなく新しいクローンでもグリーンになります。

技術スタック

Python 3.11 · FastMCP（mcp 1.x）· Great Expectations 1.18 · Databricks（Unity Catalog）· Salesforce Data Cloud（Ingestion API、DMO グラウンディング）· 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

ゼロコピー設計を一行で言うと： 読み取り値は Snowflake に残ります（Query Federation、分離された XS ウェアハウスへの JDBC プッシュダウン）。スコアは Databricks に残ります（UniForm/Iceberg による File Federation、外部計算ゼロ）。— モードはデフォルトではなく、コストに基づいてテーブルごとに選択されます。詳細：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。

既知の制限

デモ品質の認証（OAuth サービスプリンシパルではなく PAT）、リアルタイムのサーバーモデルではなく事前計算されたスコア、シングルオーガニゼーション。これらは意図的に示しています — このプロジェクトの要点はアーキテクチャであり、プロダクションの堅牢化ではありません。

Yamyle — シニア Salesforce アーキテクト & データ/AI エンジニアによる制作。 Salesforce の認定資格を20以上 · 公共サービス業界と金融サービス向け統合フレームワーク。