Assess the re-write as a custom component

[julienld]

I was thinking for a bit to re-write this MCP as a custom component, but the refactor efforts are big (5 to 10 days or work).

I did a post on Reddit and the founder of Home assistant suggested for this mcp to be a custom component.

This is a push in that direction.

Benefits :

• Access to the filesystem and internal API of Home Assistant.
• De-coupled architecture (currently, we use a non-documented API)
• Simpler deployements : HACS
• Possibilities for some tools to be polished and incorporated into some components of Core at some point
• use the reverse proxy of the HA instance.

However, this is a very big change.

Some caveat to address:

• Switching the code to the internal API would not be retro-compatible. People would have to migrate there deployement right-away to get the new features.
• Parallel between the new and the old deployement methods might be done, but require the websocket API to be accessible by the custom component. We would also need a 2-3 week code freeze. Might require some rewrite of the websocket client api to work in both modes. Would also be temporary to let people do the shift. might not worth the extra work.
• Might require the drop of some FastMCP feature (I think Core use the official Python SDK).
• our test coverage is good, but could be better. need to get to 80-90%.
• some tests may be too specific to our current architecture and not the same or not required for the custom component
• some people might not want to switch to a custom component at all.
• some Authentification might not be available. the mcp_server component seam to support OAuth2, but no DCR

Todo:

• check Core compatibility with all our tools/features
• check our supported client to see if all would still be supported
• address each caveat
• choose the migration path (fork vs retro-compat)
• make a plan for all that
• make time for the migration

[julienld]

Note: This is an automated triage based on the analysis of this code base and public search (Web, Home Assistant Source code, ...).

Issue Triage Analysis

Summary

This issue proposes a major architectural shift: rewriting ha-mcp from a standalone MCP server (80+ tools, 166 test files) to a Home Assistant custom component. This would leverage HA Core's internal APIs instead of the current REST/WebSocket approach. The migration is estimated at 5-10 days and has both significant benefits and substantial risks.

Codebase Analysis

Current Architecture:

• FastMCP-based server (src/ha_mcp/server.py) with lazy initialization
• Dual API clients: REST (client/rest_client.py, 795 lines) and WebSocket (client/websocket_client.py, 657 lines)
• 80+ tools across 28 modules in tools/ directory
• 166 test files with E2E coverage using testcontainers
• Current deployment: PyPI package + Docker + HA Add-on (uses external API via HTTP/WS)

Key Dependencies:

• fastmcp>=2.11.0 - MCP framework
• httpx>=0.27.0 - REST client
• websockets>=12.0 - Real-time state monitoring
• Python 3.13 only

Home Assistant MCP Integration (2025.2+):
Research confirms HA Core now includes an official mcp_server integration (introduced 2025.2) that:

• Exposes /api/mcp endpoint with OAuth2 + DCR support
• Uses Streamable HTTP protocol (stateless)
• Supports full HA Authentication API
• Does NOT require pre-defined OAuth Client IDs (DCR handles registration)

Research Findings

1. HA Core's MCP Support ✅

• OAuth2 with DCR: Fully supported - the caveat about "no DCR" in the issue appears outdated based on current docs
• Official integration: Both server (mcp_server) and client (mcp) integrations exist
• SDK: HA Core uses the official MCP Python SDK (not FastMCP), but FastMCP 1.0 was incorporated into the official SDK

2. Custom Component Viability ⚠️

• Internal API access: Custom components can access HA's full internal Python API (entities, services, state machine, etc.)
• Filesystem access: Components run inside HA's Python environment with controlled filesystem access
• Deployment: HACS is the standard distribution method for custom components
• Architecture: Components live in <config_dir>/custom_components/ and integrate via registries

3. FastMCP Compatibility ⚠️

• HA Core SDK: Uses official MCP Python SDK, which includes mcp.server.fastmcp module
• Compatibility: FastMCP 2.0 extends the official SDK significantly - may need evaluation of which features are needed
• Migration path: Could potentially use official SDK features present in HA Core

Implementation Assessment

This requires multiple strategic decisions from the maintainer before implementation can begin.

Decision 1: Migration Strategy

Option A: Hard Cut (Recommended in issue)

• Create v6.0.0 as custom component only
• Deprecate standalone package immediately
• Pros: Clean architecture, no dual maintenance
• Cons: Forces all users to migrate immediately, breaks existing deployments

Option B: Parallel Deployment (2-3 week code freeze)

• Maintain both standalone + custom component
• Shared codebase with adapter layer
• Pros: Gradual migration path
• Cons: High complexity, long code freeze, significant engineering effort

Option C: Fork Approach

• New repo for custom component version
• Keep standalone MCP maintained separately
• Pros: No breaking changes to existing users
• Cons: Splits community, duplicates maintenance effort

Decision 2: API Compatibility

Internal API Migration:

• Current: 795-line REST client + 657-line WebSocket client using documented/undocumented HTTP APIs
• Target: Direct Python imports from HA Core (e.g., homeassistant.core, homeassistant.helpers)
• Impact: Many tools rely on HTTP API patterns (see call_service, get_states, send_websocket_message)
• Estimate: 70-80% of client code needs rewrite

Testing Impact:

• Current E2E tests use Docker + testcontainers (external API approach)
• Custom component tests would need HA Core dev environment integration
• Some tests may become unit tests (direct Python calls vs HTTP verification)

Decision 3: Feature Parity

Potential FastMCP Feature Losses:
Based on FastMCP 2.0 capabilities, evaluate if needed:

• Server composition/proxying
• OpenAPI/FastAPI generation
• Advanced testing frameworks
• Enterprise auth integrations (may not apply to component context)

Deployment Changes:

• Lose: PyPI distribution, standalone Docker, multi-client support (Claude Desktop, Gemini CLI, etc.)
• Gain: HACS distribution, tighter HA integration, no auth token management
• Critical: Verify all current MCP clients (15+ mentioned in wizard) can connect to custom component via /api/mcp

Decision 4: Reverse Proxy & Client Support

The issue mentions "use the reverse proxy of the HA instance" as a benefit. Key questions:

• Will the custom component expose MCP via HA's /api/mcp endpoint?
• Can Claude Desktop / other clients connect to this endpoint?
• Does this replace the current Add-on's port 9583 HTTP server?

Todo Breakdown (Addressing Issue's Todos)

Todo 1: Check Core Compatibility with All Tools/Features

What to verify:

1. For each of the 80+ tools, map current REST/WebSocket calls to HA Core internal API equivalents
   • Example: client.get_states() → hass.states.async_all()
   • Example: client.call_service() → hass.services.async_call()
2. WebSocket verification patterns: Device control tools use real-time state monitoring - verify HA Core event bus can replace
3. Fuzzy search: Current textdistance library - confirm compatible in HA Core environment
4. File access: Tools like ha_get_camera_image, backup operations - verify filesystem access from component context

Methodology:

• Create mapping document: Current API call → HA Core internal API
• Identify gaps where HA Core may not expose equivalent functionality
• Test internal API access from minimal custom component POC

Todo 2: Check Supported Clients

Current clients (from setup wizard): Claude Desktop, Gemini CLI, ChatGPT, Open WebUI, VSCode, Cursor, etc.

Verification needed:

1. Can clients connect to HA's /api/mcp endpoint (via HA's OAuth2 + DCR)?
2. Does custom component mode break stdio mode (used by Claude Desktop)?
3. Will HTTP/SSE modes still work through HA's reverse proxy?
4. Add-on currently exposes port 9583 - how does this map to component architecture?

Test approach:

• Create minimal custom component exposing MCP via /api/mcp
• Test connection from Claude Desktop, Gemini CLI
• Verify OAuth2 flow works for each client

Todo 3: Address Each Caveat

Based on issue description + research:

Caveat	Analysis	Recommendation
Retro-compatibility	Hard cut means users must migrate immediately	Provide migration guide, deprecation notice in v5.x releases
Parallel deployment	Requires websocket API abstraction, 2-3 week freeze	Not recommended - complexity too high for benefit
FastMCP features	HA Core uses official SDK; may lose FastMCP 2.0 extras	Audit which features are actually used (likely none of the advanced ones)
Test coverage	Current 166 test files, need 80-90% target	Many integration tests convert to unit tests; E2E still needed
Architecture-specific tests	Some tests assume HTTP API patterns	Rewrite as internal API tests; estimate 30-40% test refactor
User adoption	Some users may prefer standalone deployment	Communicate benefits clearly; maintain standalone for 1-2 releases as deprecated
OAuth2/DCR	Issue claims no DCR support Research shows full DCR support in 2025.2+	✅ Not a blocker

Priority Assessment

Recommended Priority: HIGH

Justification:

1. Strategic alignment: Home Assistant founder endorsed this direction (mentioned in issue)
2. Architecture benefits: Direct API access is cleaner, more performant, better long-term
3. Deployment simplification: HACS distribution is easier for HA users than external setup
4. Ecosystem positioning: Aligns with HA Core's official MCP integration (2025.2+)

Comparison with other high-priority issues:

• Issue [FEATURE] Support MCP Client of Home assistant #44 (MCP Client support) is blocked - would benefit from custom component approach
• Issue [FEATURE] OAuth 2.1 Authentication with DCR and Consent Form #245 (OAuth 2.1 with DCR) - already solved in HA Core's MCP integration
• Issue Partial update strategy + statelessness + progressive disclosure #296 (Partial updates) - architectural concern that custom component could address

However, this is a multi-week project (5-10 days estimate seems low given scope) that requires:

• Clear migration strategy decision
• Communication plan for existing users
• Phased implementation (POC → core tools → full migration → deprecation)

Labels Applied

• needs-choices: Multiple implementation approaches require stakeholder decisions
• enhancement: New deployment architecture
• priority: high: Strategic importance, maintainer/founder endorsement
• triaged: Analysis complete

Next Steps (Recommended)

1. Maintainer decides on Decision 1 (migration strategy) and Decision 4 (client support model)
2. Create POC: Minimal custom component with 2-3 tools using internal APIs
3. Validate clients: Test Claude Desktop + 2-3 other clients can connect
4. Map APIs: Complete tool-by-tool mapping of REST/WS → internal APIs
5. Test strategy: Design new test approach for custom component architecture
6. Migration plan: Document user migration path, deprecation timeline
7. Implementation: If POC successful, proceed with full migration

---

Automated triage by Claude Code

Sources:

• Model Context Protocol Server - Home Assistant
• Model Context Protocol - Home Assistant
• Creating your first integration | Home Assistant Developer Docs
• FastMCP vs Official Python SDK
• Welcome to FastMCP 2.0
• Dynamic Client Registration (DCR) - MCP Context Forge

[julienld]

My notes:

• Use https://developers.home-assistant.io/docs/core/llm/
• Create a new repo. focus on the goal for the name : provide enhanced tools from controlling HA.
• Do a Proof of Value. get_automation, set_automation, get_overview. Test how well it's working with multiple clients.
• Make a test framework. e2e (use an mcp client to test) + unit
• Port over e2e tests. identify required tools.
• Port tool by tool (1:1) to the new custom component. enable e2e and make them pass.
• Make an announcement for the new version.
• Make a UI to enable/disable tools. Explore descriptions (and customize them?).
• Make an UI to help configure MCP clients (?)

[julienld]

More notes

• Not sure anymore I want to deprecate the current one. Some things might be valuable in the current form.
• Need to asses all the dependencies (compatibility of running inside HA).

[github-actions[bot]]

This issue is stale because it has been open for 30 days with no activity.