Add statistics API and date range queries for historical data #30
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
The function calls in server.py were passing use_cache=True parameter that didn't exist in the function signature, causing a TypeError. This fix adds the use_cache parameter to the get_entity_state() function signature with a default value of False. The parameter is accepted but not yet implemented, maintaining forward compatibility for future caching implementation. Fixes the error: TypeError: get_entity_state() got an unexpected keyword argument 'use_cache'
This was referenced Nov 1, 2025
- Add parse_datetime() utility function for flexible datetime parsing - Supports ISO 8601 format with/without timezone - Supports date-only format (YYYY-MM-DD) - Supports keywords: 'now', 'today', 'yesterday' - Add get_entity_history_range() function for date range queries - Accepts start_time and optional end_time parameters - Supports string or datetime objects - Uses parse_datetime() for flexible input handling - Refactor get_entity_history() to use get_entity_history_range() - Maintains backward compatibility - Eliminates code duplication - Add new get_history_range MCP tool - Allows querying history with specific date ranges - More flexible than hours-based queries - Clear examples in documentation - Add DEVELOPMENT.md to .gitignore
- Implement get_statistics and get_statistics_range MCP tools - Add get_entity_statistics and get_entity_statistics_range functions - Support 5-minute, hourly, daily, weekly, and monthly aggregations - Enable access to Home Assistant's long-term statistics storage - Fix API call to use POST method for statistics endpoint
- Add WebSocket client support using websockets library - Implement call_websocket_api() helper for WebSocket communication - Update get_entity_statistics_range to use recorder/statistics_during_period - Fix statistics tools to retrieve actual HA long-term statistics - Solves token limit issues by returning aggregated data instead of raw states
- Add clear token limit warnings (25,000 max) to all tools - Remove assumptions about sensor update frequencies - Clarify when to use raw history vs aggregated statistics - Document aggregation periods (5minute, hour, day, week, month) - Add explicit guidance for choosing the right tool - Emphasize get_statistics_range as best for historical data - Include WebSocket implementation details in docstrings
- Remove hardcoded 25,000 token limit references - Make warnings applicable to any LLM client - Different clients have different limits (Claude: 25k, GPT-4: 128k, etc.)
- Remove all emoji icons from tool docstrings - Keep documentation professional for open source contribution
Changes get_hass_error_log() function to use WebSocket API (system_log/list) instead of HTTP endpoint (/api/error_log). Benefits: - Returns structured log records with timestamps and metadata - More reliable integration name extraction from logger names - Better error/warning counting based on log level field - Consistent with other WebSocket-based API calls Updated MCP tool documentation to reflect new return format and added note about 50 record default limit. Co-Authored-By: Claude <[email protected]>
- list_automation_traces: Returns lean summaries (run_id, timestamp, trigger, state, outcome) - get_automation_trace: Returns full trace details for a specific run - Token-efficient design: requires automation_id, default limit of 10
- Rename package from hass-mcp to hass-mcp-plus - Update Docker image to rmaher001/hass-mcp-plus - Add attribution to original author Matt Voska - Update README with new features and reorganized tools - Add PyPI metadata (license, keywords, classifiers, URLs) - Bump version to 0.2.0 - Fix test configuration path
- Run container as non-root 'mcp' user - Use regular pip install instead of editable - Copy only necessary files explicitly - Add CI/CD and cache dirs to .dockerignore
- connect: 5s (fail fast on unreachable hosts) - read: 30s (allow time for long stats/history queries) - write: 5s (service calls should be quick) - pool: 5s (waiting for available connection)
- Validate HA_URL format (scheme and hostname) - Warn on placeholder tokens (YOUR_TOKEN, etc.) - Warn when HA_TOKEN is not set - Debug log for unusually short tokens
- Use ssl.create_default_context() for wss:// URLs - Validates server certificates by default - Protects against MITM attacks on secure connections
- Add sanitize_for_logging() function to redact sensitive fields - Redacts: token, password, api_key, secret, credential, etc. - Applied to service call and entity action logging
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Adds WebSocket-based statistics API support and date range queries for accessing Home Assistant historical data.
Changes
get_statisticsandget_statistics_rangetools for aggregated time-series dataget_history_rangetool for querying raw history by date/time rangeget_entity_stateby adding missinguse_cacheparameterUse Cases