Add MCP server and duration-based override system for batcontrol

[MaStr]

Summary

This PR adds a Model Context Protocol (MCP) server to batcontrol, enabling AI assistants and other MCP clients to query system state, forecasts, and battery information, as well as manage manual overrides. It also replaces the single-shot api_overwrite flag with a proper duration-based override manager that persists across evaluation cycles.

Key Changes

1. Duration-Based Override Manager (override_manager.py)

• New OverrideManager class replaces the single-shot api_overwrite boolean flag
• OverrideState dataclass tracks mode, charge rate, duration, reason, and expiration time
• Overrides automatically expire after their configured duration
• Thread-safe implementation with locking for concurrent access
• Backward compatible: MQTT mode/set now uses the override manager with a configurable default duration (30 minutes)

2. MCP Server Implementation (mcp_server.py)

• New BatcontrolMcpServer class exposes batcontrol as AI-accessible tools
• Read tools (9 total):
  • get_system_status: Current mode, SOC, charge rate, override status
  • get_price_forecast: Electricity prices for next 24-48 hours
  • get_solar_forecast: PV production forecast
  • get_consumption_forecast: Household consumption forecast
  • get_net_consumption_forecast: Grid dependency (consumption - production)
  • get_battery_info: Detailed battery state and capacity info
  • get_decision_explanation: Human-readable reasoning for current mode
  • get_configuration: Runtime parameters (thresholds, limits, offsets)
  • get_override_status: Active override details
• Write tools (4 total):
  • set_mode_override: Override mode for N minutes with reason
  • clear_mode_override: Cancel active override, resume autonomous logic
  • set_charge_rate: Force charge at specified rate for N minutes
  • set_parameter: Adjust runtime configuration parameters
• Supports both Streamable HTTP (primary, for Docker/HA addon) and stdio (secondary, for local development) transports
• Runs in-process as a thread alongside main evaluation loop

3. Core Integration (core.py)

• Initialize OverrideManager on startup
• Replace api_overwrite flag checks with override_manager.get_override() calls
• New _apply_override() method applies override mode/charge_rate to inverter
• Initialize MCP server if enabled in config
• Publish override status to MQTT (override_active, override_remaining_minutes, override_duration)
• New MQTT callbacks for override_duration/set and clear_override/set

4. Decision Explainability (logic/default.py, logic_interface.py)

• Add explanation: List[str] field to CalculationOutput dataclass
• New _explain() helper method for logic engine to append reasoning steps
• Logic engine now documents its decision-making process for AI consumption

5. Configuration & Deployment

• Add mcp section to batcontrol_config_dummy.yaml with transport, host, port options
• Expose port 8081 in Dockerfile for MCP HTTP server
• Add --mcp-stdio CLI flag in __main__.py for stdio transport mode
• Add mcp>=1.0 dependency to pyproject.toml

6. Testing

• New test_override_manager.py: Unit tests for override state and manager
• New test_mcp_server.py: Tests for MCP tool registration and execution
• Updated test_core.py: Verify override manager integration

Notable Implementation Details

• Thread Safety: Override manager uses a lock to protect concurrent access from main loop and MCP/MQTT threads
• Forecast Formatting: Helper function _format_forecast_array() converts numpy arrays to structured JSON with timestamps
• Backward Compatibility: MQTT mode/set continues to work, now using override manager with 30-minute default duration

https://claude.ai/code/session_0145EbJrBDema8V6xSTGdL8M

[Copilot]

Pull request overview

Adds an MCP (Model Context Protocol) server and a duration-based override system to batcontrol, enabling external clients (AI tools, MQTT users) to query system state/forecasts and apply manual, time-bounded control overrides across evaluation cycles.

Changes:

• Introduces OverrideManager/OverrideState to replace the single-shot api_overwrite mechanism with expiring, thread-safe overrides.
• Adds an in-process MCP server (BatcontrolMcpServer) exposing read/write tools for status, forecasts, decision explanation, and overrides (HTTP + stdio).
• Extends logic output with explanation steps and integrates override status + controls into core + MQTT.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
todo.md	Adds an implementation plan / design notes for MCP + overrides.
src/batcontrol/override_manager.py	New duration-based override manager and state dataclass.
src/batcontrol/mcp_server.py	New MCP server implementation (tools + HTTP/stdin transports).
src/batcontrol/core.py	Integrates override manager + MCP server startup; publishes override status to MQTT; adds decision explanation getter.
src/batcontrol/mqtt_api.py	Publishes override-related MQTT topics and adds HA discovery entities for override status/duration.
src/batcontrol/logic/logic_interface.py	Adds explanation: List[str] to CalculationOutput.
src/batcontrol/logic/default.py	Appends human-readable explanation steps during decision-making.
src/batcontrol/main.py	Adds --mcp-stdio CLI path to run MCP over stdio.
config/batcontrol_config_dummy.yaml	Adds MCP configuration section (enabled/transport/host/port).
pyproject.toml	Adds mcp>=1.0 dependency.
Dockerfile	Exposes port 8081 for MCP HTTP server.
tests/batcontrol/test_override_manager.py	Adds unit tests for override manager/state.
tests/batcontrol/test_mcp_server.py	Adds tests for tool registration and basic tool behavior.
tests/batcontrol/test_core.py	Updates tests to assert override manager activation instead of api_overwrite.

[Copilot]

Pull request overview

This PR introduces an MCP (Model Context Protocol) server for Batcontrol and replaces the previous single-cycle api_overwrite flag with a duration-based, thread-safe override system that persists across evaluation cycles.

Changes:

• Added a new OverrideManager/OverrideState implementation and integrated it into core.py, MQTT callbacks, and status publishing.
• Implemented an optional MCP server (FastMCP) exposing read/write tools for status, forecasts, decision explanations, overrides, and runtime parameter tuning.
• Added decision explainability support by extending CalculationOutput and annotating the default logic with explanation steps, plus new tests and docs.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tests/batcontrol/test_override_manager.py	Adds unit tests for override state/manager behavior (expiry, replacement, thread-safety).
tests/batcontrol/test_mcp_server.py	Adds MCP tool registration/execution tests (skipped when MCP SDK unavailable).
tests/batcontrol/test_core.py	Updates core test to assert override manager activation instead of api_overwrite.
src/batcontrol/override_manager.py	New duration-based override manager replacing single-shot overwrite behavior.
src/batcontrol/mqtt_api.py	Publishes override status/duration and registers HA discovery entities for override sensors/number.
src/batcontrol/mcp_server.py	New MCP server with read/write tools, forecast formatting helper, HTTP/stdin transports.
src/batcontrol/logic/logic_interface.py	Extends CalculationOutput with explanation: List[str].
src/batcontrol/logic/default.py	Adds _explain() and populates explanation steps throughout decision logic.
src/batcontrol/core.py	Integrates OverrideManager, adds _apply_override(), MCP startup, MQTT override callbacks, explanation getter.
src/batcontrol/__main__.py	Adds --mcp-stdio flag and stdio-mode MCP server execution path.
pyproject.toml	Adds optional dependency group mcp.
docs/override-manager.md	Documents override manager design, API, MQTT topics, and HA discovery entities.
docs/mcp-server.md	Documents MCP server architecture, configuration, and tool reference.
docs/decision-explainability.md	Documents explanation data flow and example output for decision explainability.
config/batcontrol_config_dummy.yaml	Adds example mcp config section.
Dockerfile	Exposes MCP port and attempts to install wheel with MCP extras in the runtime image.

[Copilot]

Pull request overview

This PR introduces a duration-based manual override system (replacing the prior one-shot api_overwrite flag) and adds an optional MCP (Model Context Protocol) server that exposes batcontrol state/forecasts and control actions as AI-accessible tools.

Changes:

• Added OverrideManager / OverrideState for time-bounded overrides, integrated into core.py + MQTT publishing of override status.
• Added optional MCP server (mcp_server.py) with read/write tools, plus a --mcp-stdio CLI mode and optional dependency wiring.
• Added decision explainability plumbing (CalculationOutput.explanation) and annotated default logic with explanation steps; added unit tests and docs.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/batcontrol/test_override_manager.py	New unit tests for override manager behavior and expiry.
tests/batcontrol/test_mcp_server.py	New tests validating MCP tool wiring and behavior (currently coupled to MCP internals).
tests/batcontrol/test_core.py	Updated assertion for override integration (uses override manager instead of api_overwrite).
src/batcontrol/override_manager.py	New duration-based override state + manager with locking and auto-expiry.
src/batcontrol/mqtt_api.py	Publishes/discovers new MQTT entities for override status and override duration configuration.
src/batcontrol/mcp_server.py	New optional MCP server exposing batcontrol tools (read + write) over HTTP/stdio.
src/batcontrol/logic/logic_interface.py	Adds explanation list to calculation output to support explainability.
src/batcontrol/logic/default.py	Adds _explain() and appends human-readable reasoning throughout decision logic.
src/batcontrol/core.py	Integrates OverrideManager, applies overrides in the main loop, adds MQTT callbacks, and exposes decision explanations; optional MCP server startup/shutdown wiring.
src/batcontrol/main.py	Adds --mcp-stdio mode and disables HTTP MCP startup when using stdio.
pyproject.toml	Adds optional extra mcp dependency gated to Python >= 3.10.
docs/override-manager.md	New design/API documentation for override manager + MQTT contract.
docs/mcp-server.md	New architecture/configuration guide for MCP server and available tools.
docs/decision-explainability.md	New documentation for explanation data flow and example output.
config/batcontrol_config_dummy.yaml	Adds mcp: config section to the dummy config template.
Dockerfile	Installs MCP dependency in the container image and exposes port 8081.

[Copilot]

Pull request overview

This PR introduces a duration-based manual override system and adds an optional MCP (Model Context Protocol) server so external MCP clients (e.g., AI assistants) can query batcontrol status/forecasts and set overrides/parameters.

Changes:

• Added OverrideManager + OverrideState to replace the one-shot api_overwrite flag with time-bounded overrides.
• Implemented an optional in-process MCP server (HTTP or stdio via CLI) with read/write tools for status, forecasts, overrides, and runtime parameter updates.
• Added decision explainability by recording reasoning steps in CalculationOutput.explanation, plus tests/docs/config/deployment updates.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/batcontrol/override_manager.py	New thread-safe, duration-based override state/manager.
src/batcontrol/mcp_server.py	New MCP server exposing batcontrol read/write tools.
src/batcontrol/core.py	Integrates override manager, override application, MQTT publishing, and optional MCP startup.
src/batcontrol/mqtt_api.py	Publishes/discovers new MQTT entities for override status/duration + new set callbacks.
src/batcontrol/logic/logic_interface.py	Extends CalculationOutput with explanation list.
src/batcontrol/logic/default.py	Adds _explain() calls to document decision-making steps.
src/batcontrol/__main__.py	Adds --mcp-stdio flag and prevents HTTP MCP startup when using stdio mode.
tests/batcontrol/test_override_manager.py	Unit tests for override manager/state behavior.
tests/batcontrol/test_mcp_server.py	MCP tool registration/execution tests (skipped if mcp not installed).
tests/batcontrol/test_core.py	Updates assertion for override-manager-based mode override.
pyproject.toml	Adds optional extra mcp dependency with Python>=3.10 marker.
Dockerfile	Installs MCP dependency and exposes port 8081.
config/batcontrol_config_dummy.yaml	Adds mcp: configuration section.
docs/override-manager.md	Documents override manager behavior, MQTT topics, and contract.
docs/mcp-server.md	Documents MCP server architecture, tools, configuration, and usage.
docs/decision-explainability.md	Documents explanation data flow and example output.

[Copilot]

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated 8 comments.

[Copilot]

The module docstring says /clear_override/set clears the override with “any value”, but the callback is registered with convert=int (core.py), so non-integer payloads (e.g., "true") will be rejected and the clear won’t run. Either update the documentation to match the actual requirement (integer payload), or register the callback with a converter that accepts any payload (e.g., lambda _payload: 0).

Suggested change

	- /clear_override/set: clear active override (any value triggers the clear)
	- /clear_override/set: clear active override (any integer payload triggers the clear)

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated 4 comments.

[Copilot]

VALID_OVERRIDE_MODES duplicates the mode constants now centralized in batcontrol._modes (used by both core.py and mcp_server.py). To prevent future drift, import and reuse VALID_MODES (or the individual MODE_* constants) from ._modes here instead of maintaining a separate set.

Suggested change

	logger = logging.getLogger(__name__)
	# Default duration for MQTT overrides (backward compatible)
	DEFAULT_OVERRIDE_DURATION_MINUTES = 30
	# Valid inverter modes accepted by the override system
	VALID_OVERRIDE_MODES = {-1, 0, 8, 10}
	from ._modes import VALID_MODES as VALID_OVERRIDE_MODES
	logger = logging.getLogger(__name__)
	# Default duration for MQTT overrides (backward compatible)
	DEFAULT_OVERRIDE_DURATION_MINUTES = 30
	# Valid inverter modes accepted by the override system (imported from batcontrol._modes)

[Copilot]

set_override() accepts charge_rate for any mode and doesn’t validate it. This can create inconsistent override state (e.g., mode != -1 but charge_rate set) or even propagate negative/zero charge rates into force_charge() if set programmatically. Consider validating that charge_rate is only allowed for MODE_FORCE_CHARGING and must be > 0, otherwise raise ValueError (or coerce to None).

[Copilot]

get_configuration() returns production_offset but other MCP outputs (e.g., get_solar_forecast) expose the same value as production_offset_percent. To keep the MCP schema consistent (and preserve backward compatibility if clients relied on the earlier *_percent naming), consider returning both keys (e.g., include production_offset_percent as an alias) or standardize on one name across all tools.

Suggested change

	'production_offset': bc.production_offset_percent,
	'production_offset': bc.production_offset_percent,
	'production_offset_percent': bc.production_offset_percent,

[Copilot]

In mock_bc, api_get_limit_battery_charge_rate isn’t configured. Since get_configuration() calls bc.api_get_limit_battery_charge_rate(), the tool currently returns a MagicMock for limit_battery_charge_rate, which isn’t JSON-serializable and can mask schema/type regressions. Set bc.api_get_limit_battery_charge_rate.return_value (e.g., bc._limit_battery_charge_rate) so the test exercises realistic output types.