fix: enable stateless_http in add-on and fix runtime Python version

[sergeykad]

What does this PR do?

Two fixes for the Home Assistant add-on:

1. Enable stateless_http=True in start.py — The add-on was the only HTTP deployment mode missing this parameter, which was introduced in v6.4.0 (PR feat: enable stateless_http mode for restart resilience #495) for all other modes (main_web, main_sse, main_oauth). Without it, the server runs in stateful session mode, requiring mcp-proxy to
   correctly forward Mcp-Session-Id headers on every request. If the proxy doesn't maintain session state consistently, the server either creates orphaned sessions (returning stale data) or silently rejects requests — matching the symptoms reported in mcp-proxy connection returns stale data, writes fail silently #585.

2. Fix runtime Docker image Python version — The runtime stage used Python 3.14 while the builder stage uses Python 3.13, causing ModuleNotFoundError: No module named 'ha_mcp' because the venv's site-packages lives under python3.13/ but the runtime Python looks under python3.14/. This also
   caused the test_addon_startup_logs e2e test to always fail.

Type of change

• 🐛 Bug fix
• ✨ New feature
• 📚 Documentation
• 🔧 Maintenance/refactor
• 💥 Breaking change

Testing

• I have tested these changes with a LLM agent
• All automated tests pass (uv run pytest)
• Code follows style guidelines (uv run ruff check)

All 3 add-on e2e tests now pass (previously test_addon_startup_logs always failed due to the Python version mismatch):

tests/addon/test_addon_startup.py::TestAddonStartup::test_addon_startup_logs PASSED
tests/addon/test_addon_startup.py::TestAddonStartup::test_addon_startup_custom_secret_path PASSED
tests/addon/test_addon_startup.py::TestAddonStartup::test_addon_startup_missing_supervisor_token PASSED

Checklist

• I have updated documentation if needed

Fixes #585

[gemini-code-assist]

Summary of Changes

Hello @sergeykad, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request addresses two critical bug fixes for the Home Assistant add-on, enhancing its stability and reliability. It resolves session management inconsistencies by enabling stateless HTTP, and corrects a Python version mismatch in the Docker build process, which was causing module import errors and test failures. These changes ensure the add-on operates as expected and passes all relevant automated tests.

Highlights

• Stateless HTTP Mode Enabled: The stateless_http=True parameter has been added to start.py for the Home Assistant add-on. This resolves issues with stateful session management, preventing orphaned sessions and silently rejected requests, which was a common symptom reported in issue mcp-proxy connection returns stale data, writes fail silently #585.
• Runtime Python Version Fixed: The runtime Docker image for the add-on now uses Python 3.13, matching the builder stage. This corrects a ModuleNotFoundError caused by a mismatch with Python 3.14, which also fixes the test_addon_startup_logs e2e test.

Changelog

• homeassistant-addon/Dockerfile
  • Updated the base Python image from python:3.14-slim-bookworm to python:3.13-slim-bookworm for the runtime stage.
• homeassistant-addon/start.py
  • Added stateless_http=True to the run_server function call.

Activity

• The author confirmed that all automated tests pass (uv run pytest).
• The author verified that the code follows style guidelines (uv run ruff check).
• The author reported that all 3 add-on e2e tests now pass, specifically noting that test_addon_startup_logs no longer fails.
• The author indicated that documentation was updated if needed.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request delivers two key fixes for the Home Assistant add-on. It corrects the Python version in the Dockerfile to match the builder stage, resolving ModuleNotFoundError issues. It also enables stateless HTTP mode in start.py, which fixes session handling bugs and aligns the add-on with the project's stateless architecture. The changes are clear, correct, and well-justified. Great work!

[kingpanther13]

Review: Approve

Thoroughly verified both fixes against the upstream codebase. This PR is correct, minimal, and well-motivated.

Fix 1: stateless_http=True in start.py

Verified correct. The add-on's start.py calls mcp.run() directly, bypassing _http_run_kwargs() in __main__.py (line 254-264) which already includes stateless_http=True for all other HTTP modes (main_web, main_sse, main_oauth). This was introduced in PR #495 and the add-on was missed.

Without stateless mode, mcp-proxy must consistently forward Mcp-Session-Id headers. If it doesn't, the server creates orphaned sessions or silently rejects requests — matching exactly the symptoms in #585 (stale reads, silent write failures).

Fix 2: Runtime Python 3.14 → 3.13

Verified correct. PR #598 (Renovate bot) bumped the runtime FROM python:3.13-slim-bookworm → python:3.14-slim-bookworm in all three Dockerfiles, but the builder stages remain on ghcr.io/astral-sh/uv:0.9.30-python3.13-bookworm-slim. The venv's site-packages lives under python3.13/ but a Python 3.14 runtime looks under python3.14/, causing ModuleNotFoundError: No module named 'ha_mcp'.

All three Dockerfiles (Dockerfile, homeassistant-addon/Dockerfile, homeassistant-addon-dev/Dockerfile) are correctly reverted.

CI

All checks green: Docker & Add-on Validation, E2E (x86 + ARM), Unit Tests, Ruff Lint.

Non-blocking observation

The Renovate dockerfile manager bumped the runtime Python image independently of the builder (which uses a different base image from ghcr.io/astral-sh/uv). Consider either:

• Adding a packageRules group to pin the runtime Python to match the builder, or
• Adding a CI check that validates builder/runtime Python version consistency

This is a separate concern and shouldn't block this PR.