Homeassistant MCP

🚀 Model Context

This project provides a model context for Home Assistant, enabling easy access to device states and management.

🚀 Quick Start

📦 Installation

npm install home-assistant-model-context

💻 Usage Examples

Basic Usage

const { ModelContext } = require('home-assistant-model-context');

// Initialize the model context
async function initializeModel() {
  const model = new ModelContext({
    host: 'localhost',
    port: 8123,
    tokenPath: '/config/secrets.yaml'
  });

  // Get the current state
  await model.initialize();
  const state = await model.getState('light.living_room');
  console.log('Light state:', state.state);
}

// Execute the initialization
initializeModel().catch(console.error);

📚 Documentation

Development Guide

Run Commands

# Development mode (with hot reloading)
npm run dev

# Build the project
npm run build

# Production mode
npm run start

# Run tests
npx jest --config=jest.config.cjs

# Code formatting
npm run lint

# Generate documentation
npm run doc:gen

Configuration File

// config.json
{
  "host": "localhost",
  "port": 8123,
  "token": "your_api_key_here"
}

Troubleshooting

Common Issues

1. Node.js Version (toSorted is not a function)

   • Solution: Update to Node.js 20.10.0+

     nvm install 20.10.0
     nvm use 20.10.0
     

2. Connection Issues

   • Ensure Home Assistant is running.
   • Check if HASS_HOST is accessible.
   • Verify token permissions.

3. Device Management Issues

   • Ensure Supervisor access rights.
   • Check the compatibility of added components.
   • Verify system resources.

📊 Project Status

✅ Completed

• Entity, floor, and area access
• Device control (lights, climate, awnings, switches, contacts)
• Add-on management functionality
• HACS integration package management
• Advanced automation configuration
• Basic state management
• Error handling and validation
• Docker containerization
• Jest testing framework
• TypeScript integration

🚧 In Progress

• WebSocket implementation for real-time updates
• Enhanced security features
• Tool organization optimization
• Performance optimization
• Resource context integration
• API documentation generation
• Multi-platform desktop integration
• Advanced macOS integration
• Type safety improvements
• Test coverage expansion

🤝 Project Contribution

1. Fork the repository.
2. Create a feature branch.
3. Implement changes.
4. Add tests for new features.
5. Ensure all tests pass.
6. Submit a pull request.

🔗 Resource Links

• MCP Documentation
• Home Assistant Official Documentation
• Node.js Official Website

📄 License

MIT License

Copyright (c) 2023, Author 姓名

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.