alex/homeassistant-mcp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update README with Bun runtime migration and comprehensive workflow details

Browse Source 
- Replaced Node.js and npm references with Bun runtime configuration
- Updated badges to reflect Bun version
- Added new sections on Bun performance benefits and development workflow
- Expanded troubleshooting and performance optimization guidelines
- Simplified installation, build, and testing instructions
- Included Bun-specific commands for development and testing
This commit is contained in:
jango-blockchained
2025-02-03 19:07:31 +01:00
parent d7c12676f5
commit d46a19c698
1 changed files with 137 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files

173
README.md
View File

@@ -5,9 +5,8 @@ The server uses the MCP protocol to share access to a local Home Assistant insta
A powerful bridge between your Home Assistant instance and Language Learning Models (LLMs), enabling natural language control and monitoring of your smart home devices through the Model Context Protocol (MCP). This server provides a comprehensive API for managing your entire Home Assistant ecosystem, from device control to system administration. A powerful bridge between your Home Assistant instance and Language Learning Models (LLMs), enabling natural language control and monitoring of your smart home devices through the Model Context Protocol (MCP). This server provides a comprehensive API for managing your entire Home Assistant ecosystem, from device control to system administration.
![License](https://img.shields.io/badge/license-MIT-blue.svg) ![License](https://img.shields.io/badge/license-MIT-blue.svg)
![Node.js](https://img.shields.io/badge/node-%3E%3D20.10.0-green.svg) ![Bun](https://img.shields.io/badge/bun-%3E%3D1.0.26-black)
![Docker Compose](https://img.shields.io/badge/docker-compose-%3E%3D1.27.0-blue.svg) ![Docker Compose](https://img.shields.io/badge/docker-compose-%3E%3D1.27.0-blue.svg)
![NPM](https://img.shields.io/badge/npm-%3E%3D7.0.0-orange.svg)
![TypeScript](https://img.shields.io/badge/typescript-%5E5.0.0-blue.svg) ![TypeScript](https://img.shields.io/badge/typescript-%5E5.0.0-blue.svg)
![Test Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen.svg) ![Test Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen.svg)
@@ -123,8 +122,7 @@ See [SSE_API.md](docs/SSE_API.md) for complete documentation of the SSE system.
## Prerequisites ## Prerequisites
- **Node.js** 20.10.0 or higher - **Bun** 1.0.26 or higher
- **NPM** package manager
- **Docker Compose** for containerization - **Docker Compose** for containerization
- Running **Home Assistant** instance - Running **Home Assistant** instance
- Home Assistant long-lived access token ([How to get token](https://community.home-assistant.io/t/how-to-get-long-lived-access-token/162159)) - Home Assistant long-lived access token ([How to get token](https://community.home-assistant.io/t/how-to-get-long-lived-access-token/162159))
@@ -141,10 +139,10 @@ git clone https://github.com/jango-blockchained/homeassistant-mcp.git
cd homeassistant-mcp cd homeassistant-mcp
# Install dependencies # Install dependencies
npm install bun install
# Build the project # Build the project
npm run build bun run build
``` ```
### Docker Setup (Recommended) ### Docker Setup (Recommended)
@@ -170,7 +168,7 @@ The project includes Docker support for easy deployment and consistent environme
# Server Configuration # Server Configuration
PORT=3000 PORT=3000
NODE_ENV=production BUN_ENV=production
DEBUG=false DEBUG=false
``` ```
@@ -201,7 +199,7 @@ The project includes Docker support for easy deployment and consistent environme
#### Docker Configuration #### Docker Configuration
The Docker setup includes: The Docker setup includes:
- Multi-stage build for optimal image size - Multi-stage build using Bun for optimal performance
- Health checks for container monitoring - Health checks for container monitoring
- Volume mounting for environment configuration - Volume mounting for environment configuration
- Automatic container restart on failure - Automatic container restart on failure
@@ -214,7 +212,7 @@ All environment variables can be configured in the `.env` file. The following va
- `HASS_TOKEN`: Long-lived access token for Home Assistant - `HASS_TOKEN`: Long-lived access token for Home Assistant
- `HASS_SOCKET_URL`: WebSocket URL for Home Assistant - `HASS_SOCKET_URL`: WebSocket URL for Home Assistant
- `PORT`: Server port (default: 3000) - `PORT`: Server port (default: 3000)
- `NODE_ENV`: Environment (production/development) - `BUN_ENV`: Environment (production/development)
- `DEBUG`: Enable debug mode (true/false) - `DEBUG`: Enable debug mode (true/false)
## Configuration ## Configuration
@@ -229,7 +227,7 @@ HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket # WebSocket URL
# Server Configuration # Server Configuration
PORT=3000 # Server port (default: 3000) PORT=3000 # Server port (default: 3000)
NODE_ENV=production # Environment (production/development) BUN_ENV=production # Environment (production/development)
DEBUG=false # Enable debug mode DEBUG=false # Enable debug mode
# Test Configuration # Test Configuration
@@ -247,25 +245,19 @@ TEST_HASS_TOKEN=test_token # Test token
```bash ```bash
# Development mode with hot reload # Development mode with hot reload
npm run dev bun run dev
# Build project
npm run build
# Production mode
npm run start
# Run tests # Run tests
npx jest --config=jest.config.cjs bun test
# Run tests with coverage # Run tests with coverage
npx jest --coverage bun test --coverage
# Lint code # Build the project
npm run lint bun run build
# Format code # Start the production server
npm run format bun start
``` ```
## API Reference ## API Reference
@@ -289,7 +281,7 @@ Performs a comprehensive system analysis including:
```bash ```bash
# Run standard analysis # Run standard analysis
npm run test:openai bun run test:openai
# Select option 1 when prompted # Select option 1 when prompted
``` ```
@@ -303,7 +295,7 @@ Allows you to ask specific questions about your Home Assistant setup. The analys
```bash ```bash
# Run custom analysis # Run custom analysis
npm run test:openai bun run test:openai
# Select option 2 when prompted # Select option 2 when prompted
``` ```
@@ -318,30 +310,23 @@ OPENAI_API_KEY=your_openai_api_key
### Common Issues ### Common Issues
1. **Node.js Version (`toSorted is not a function`)** 1. **Connection Issues**
- **Solution:** Update to Node.js 20.10.0+
```bash
nvm install 20.10.0
nvm use 20.10.0
```
2. **Connection Issues**
- Verify Home Assistant is running - Verify Home Assistant is running
- Check `HASS_HOST` accessibility - Check `HASS_HOST` accessibility
- Validate token permissions - Validate token permissions
- Ensure WebSocket connection for real-time updates - Ensure WebSocket connection for real-time updates
3. **Add-on Management Issues** 2. **Add-on Management Issues**
- Verify Supervisor access - Verify Supervisor access
- Check add-on compatibility - Check add-on compatibility
- Validate system resources - Validate system resources
4. **HACS Integration Issues** 3. **HACS Integration Issues**
- Verify HACS installation - Verify HACS installation
- Check HACS integration status - Check HACS integration status
- Validate repository access - Validate repository access
5. **Automation Issues** 4. **Automation Issues**
- Verify entity availability - Verify entity availability
- Check trigger conditions - Check trigger conditions
- Validate service calls - Validate service calls
@@ -398,3 +383,119 @@ OPENAI_API_KEY=your_openai_api_key
## License ## License
MIT License - See [LICENSE](LICENSE) file MIT License - See [LICENSE](LICENSE) file
## Performance Benefits with Bun
This project leverages Bun's high-performance runtime and package manager for:
- 🚀 **Faster Execution**: Bun's JavaScript runtime is significantly faster than Node.js
- ⚡ **Quick Development**: Hot reload and TypeScript support out of the box
- 📦 **Efficient Package Management**: Faster installation and better dependency resolution
- 🧪 **Integrated Testing**: Built-in test runner with Jest compatibility
- 🔄 **Native TypeScript Support**: No transpilation needed for development
## Development Workflow
### Testing
```bash
# Run all tests
bun test
# Run tests in watch mode
bun test --watch
# Run tests with coverage
bun test --coverage
# Run specific test file
bun test path/to/test.test.ts
```
### Building
```bash
# Build the project
bun run build
# Clean and rebuild
bun run clean && bun run build
```
### Type Checking
```bash
# Check types
bun run types:check
# Install type definitions
bun run types:install
```
### Linting
```bash
# Run ESLint
bun run lint
# Fix linting issues
bun run lint:fix
```
## Troubleshooting
### Common Issues
1. **Connection Issues**
- Verify Home Assistant is running
- Check `HASS_HOST` accessibility
- Validate token permissions
- Ensure WebSocket connection for real-time updates
2. **Add-on Management Issues**
- Verify Supervisor access
- Check add-on compatibility
- Validate system resources
3. **HACS Integration Issues**
- Verify HACS installation
- Check HACS integration status
- Validate repository access
4. **Automation Issues**
- Verify entity availability
- Check trigger conditions
- Validate action sequences
- Debug execution flow
### Performance Optimization
1. **Development Mode**
- Use `bun --watch` for faster development cycles
- Enable hot module replacement
- Utilize Bun's built-in performance tools
2. **Production Mode**
- Use production builds for optimal performance
- Enable compression and caching
- Implement proper error handling
3. **Docker Optimization**
- Use multi-stage builds
- Implement proper caching
- Optimize layer ordering
## Contributing
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Install dependencies (`bun install`)
4. Make your changes
5. Run tests (`bun test`)
6. Commit your changes (`git commit -m 'Add amazing feature'`)
7. Push to the branch (`git push origin feature/amazing-feature`)
8. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.