Expose Core measurement-quality reasons and energy provenance through MCP diagnostics #42

Problem

FTW Cloud's MCP connector can read live values and historical series, but it does not expose the diagnostic reasons and underlying energy/measurement provenance needed to troubleshoot a house-load failure. This forced the operator to use SSH, Docker and a direct LAN API request despite having an authorized FTW1 MCP connection with ftw.diag.run scope.

Real-world case on Core v0.152.1-beta.1, with the new Docker 0.x deployment. Related Core issue: srcfl/ftw#1744.

What MCP exposed

• status: fresh grid_w, battery_w, pv_w, ev_w and driver/source freshness, but no load_w field/value and no household-load failure reason.
• health_get: meter live and 3 drivers OK / 1 offline, but no indication of which source invalidated the house balance.
• history_query: load_w = null in every bucket checked, without the reason for the gap. This is aggregated history rather than Core's energy ledger with source, coverage and quality.
• drivers_status and config_get are useful, but alone cannot explain the load_estimate failure.
• diag_run and events_list are listed in internal/mcp/tools.go with descriptions explicitly stating they are not yet served by the box (currently E_UNKNOWN_OP). An authorized diagnostic scope therefore does not provide the promised checks.

What the local FTW Core API exposed

The same box answered the read-only GET /api/status over LAN:

grid_w: -109.96
bat_w: -3874
load_w: null
history_reason: missing:easee:ev
load_estimate:
  watts: null
  energy_wh: null
  method: reported_energy_balance_v3
  reason: missing:easee:ev

Further read-only configuration inspection showed:

drivers:
  - name: easee_cloud
    lua: drivers/easee_cloud.lua
loadpoints:
  - id: Laddbox
    driver_name: easee

This reveals a dangling charger binding (easee vs easee_cloud) rather than a site-meter issue. The operator had previously tested both Zap and Pixii as site meters without resolving it. The mismatch and runtime error are verified; relinking the loadpoint was suggested, but the fix outcome has not yet been verified.

Why this matters

The MCP response told us that house-load history was unavailable, not why. We could not distinguish missing:easee:ev from timing, staleness, skew or invalid-balance causes until the owner executed a terminal command. The phone app's instantaneous balance and the web UI's qualified interval estimate also differed, making this diagnostic metadata essential.

Requested change

1. Add a read-only, scoped diagnostic view/tool of the current Core measurement quality, preferably reusing Core's existing /api/status semantics. Expose load_w, history_quality, history_reason and load_estimate metadata (watts, reason, method, from_ms, to_ms, end_age_ms, timing_basis, energy_basis, etc.), with explicit null/unknown states.
2. Provide a source/flow-level reason and a safe driver↔loadpoint association where possible, so missing:<driver>:ev can be diagnosed without manual LAN access. Respect redaction for addresses, secrets, credentials, device serials, and personal identity.
3. Expose or provide safe read-only equivalents for /api/energy/history (Wh, quality, provenance, sample counts) and /api/series / /api/series/catalog (raw observations and timestamps), so missing energy or bad time coverage can be traced rather than inferred from aggregated history_query.
4. Implement and validate diag_run (and events_list when ready), or do not present unavailable operations as functional diagnostics; return a clear capability/unsupported response.
5. Keep the connector least-privilege: authorized diagnostic scope, explicit allowlist and response sanitization, read-only only; do not offer arbitrary HTTP passthrough, configuration mutation, control or credentials.
6. Add end-to-end tests for a missing/dangling EV flow and for interval-quality failures. Confirm that MCP exposes the same reason as local Core while not leaking restricted data.

Ownership / implementation pointers

• Cloud/MCP: srcfl/ftw-cloud/internal/mcp/tools.go (the exposed MCP tool list and constrained live/history reads).
• Core: srcfl/ftw/go/internal/api/api_history_quality.go computes history_reason and load_estimate, while go/internal/api/api_agent_catalog.go enumerates available read-only diagnostic routes, including status, energy history, and original series. Coordinate through the existing scoped agent protocol rather than bypassing it.

This is a tooling/observability request distinct from srcfl/ftw#1744, the underlying dangling-loadpoint configuration issue.