Add comprehensive documentation for Home Assistant MCP project
- Created detailed getting started guide with installation and configuration instructions - Added main documentation README with structured table of contents - Developed troubleshooting guide with common issues, debugging tips, and FAQ - Included development guide with project structure, setup, and contribution guidelines - Added tools documentation with overview of available management tools
This commit is contained in:
jango-blockchained
60
docs/README.md
Normal file
60
docs/README.md
Normal file
@@ -0,0 +1,60 @@
|
|||||||
|
# Home Assistant MCP Documentation
|
||||||
|
|
||||||
|
Welcome to the Home Assistant MCP (Master Control Program) documentation. This documentation provides comprehensive information about setting up, configuring, and using the Home Assistant MCP.
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
|
||||||
|
1. [Getting Started](./getting-started.md)
|
||||||
|
- Installation
|
||||||
|
- Configuration
|
||||||
|
- First Steps
|
||||||
|
|
||||||
|
2. [API Reference](./API.md)
|
||||||
|
- REST API Endpoints
|
||||||
|
- Authentication
|
||||||
|
- Error Handling
|
||||||
|
|
||||||
|
3. [SSE (Server-Sent Events)](./SSE_API.md)
|
||||||
|
- Event Subscriptions
|
||||||
|
- Real-time Updates
|
||||||
|
- Connection Management
|
||||||
|
|
||||||
|
4. [Tools](./tools/README.md)
|
||||||
|
- Device Control
|
||||||
|
- Automation Management
|
||||||
|
- Add-on Management
|
||||||
|
- Package Management
|
||||||
|
|
||||||
|
5. [Configuration](./configuration/README.md)
|
||||||
|
- Environment Variables
|
||||||
|
- Security Settings
|
||||||
|
- Performance Tuning
|
||||||
|
|
||||||
|
6. [Development](./development/README.md)
|
||||||
|
- Project Structure
|
||||||
|
- Contributing Guidelines
|
||||||
|
- Testing
|
||||||
|
|
||||||
|
7. [Troubleshooting](./troubleshooting.md)
|
||||||
|
- Common Issues
|
||||||
|
- Debugging
|
||||||
|
- FAQ
|
||||||
|
|
||||||
|
## Quick Links
|
||||||
|
|
||||||
|
- [GitHub Repository](https://github.com/yourusername/homeassistant-mcp)
|
||||||
|
- [Issue Tracker](https://github.com/yourusername/homeassistant-mcp/issues)
|
||||||
|
- [Change Log](./CHANGELOG.md)
|
||||||
|
- [Security Policy](./SECURITY.md)
|
||||||
|
|
||||||
|
## Support
|
||||||
|
|
||||||
|
If you need help or have questions:
|
||||||
|
|
||||||
|
1. Check the [Troubleshooting Guide](./troubleshooting.md)
|
||||||
|
2. Search existing [Issues](https://github.com/yourusername/homeassistant-mcp/issues)
|
||||||
|
3. Create a new issue if your problem isn't already reported
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
This project is licensed under the MIT License - see the [LICENSE](../LICENSE) file for details.
|
||||||
188
docs/development/README.md
Normal file
188
docs/development/README.md
Normal file
@@ -0,0 +1,188 @@
|
|||||||
|
# Development Guide
|
||||||
|
|
||||||
|
This guide provides information for developers who want to contribute to or extend the Home Assistant MCP.
|
||||||
|
|
||||||
|
## Project Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
homeassistant-mcp/
|
||||||
|
├── src/
|
||||||
|
│ ├── api/ # API endpoints and route handlers
|
||||||
|
│ ├── config/ # Configuration management
|
||||||
|
│ ├── hass/ # Home Assistant integration
|
||||||
|
│ ├── interfaces/ # TypeScript interfaces
|
||||||
|
│ ├── mcp/ # MCP core functionality
|
||||||
|
│ ├── middleware/ # Express middleware
|
||||||
|
│ ├── routes/ # Route definitions
|
||||||
|
│ ├── security/ # Security utilities
|
||||||
|
│ ├── sse/ # Server-Sent Events handling
|
||||||
|
│ ├── tools/ # Tool implementations
|
||||||
|
│ ├── types/ # TypeScript type definitions
|
||||||
|
│ └── utils/ # Utility functions
|
||||||
|
├── __tests__/ # Test files
|
||||||
|
├── docs/ # Documentation
|
||||||
|
├── dist/ # Compiled JavaScript
|
||||||
|
└── scripts/ # Build and utility scripts
|
||||||
|
```
|
||||||
|
|
||||||
|
## Development Setup
|
||||||
|
|
||||||
|
1. Install dependencies:
|
||||||
|
```bash
|
||||||
|
npm install
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Set up development environment:
|
||||||
|
```bash
|
||||||
|
cp .env.example .env.development
|
||||||
|
```
|
||||||
|
|
||||||
|
3. Start development server:
|
||||||
|
```bash
|
||||||
|
npm run dev
|
||||||
|
```
|
||||||
|
|
||||||
|
## Code Style
|
||||||
|
|
||||||
|
We follow these coding standards:
|
||||||
|
|
||||||
|
1. TypeScript best practices
|
||||||
|
- Use strict type checking
|
||||||
|
- Avoid `any` types
|
||||||
|
- Document complex types
|
||||||
|
|
||||||
|
2. ESLint rules
|
||||||
|
- Run `npm run lint` to check
|
||||||
|
- Run `npm run lint:fix` to auto-fix
|
||||||
|
|
||||||
|
3. Code formatting
|
||||||
|
- Use Prettier
|
||||||
|
- Run `npm run format` to format code
|
||||||
|
|
||||||
|
## Testing
|
||||||
|
|
||||||
|
1. Unit tests:
|
||||||
|
```bash
|
||||||
|
npm run test
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Integration tests:
|
||||||
|
```bash
|
||||||
|
npm run test:integration
|
||||||
|
```
|
||||||
|
|
||||||
|
3. Coverage report:
|
||||||
|
```bash
|
||||||
|
npm run test:coverage
|
||||||
|
```
|
||||||
|
|
||||||
|
## Creating New Tools
|
||||||
|
|
||||||
|
1. Create a new file in `src/tools/`:
|
||||||
|
```typescript
|
||||||
|
import { z } from 'zod';
|
||||||
|
import { Tool } from '../types';
|
||||||
|
|
||||||
|
export const myTool: Tool = {
|
||||||
|
name: 'my_tool',
|
||||||
|
description: 'Description of my tool',
|
||||||
|
parameters: z.object({
|
||||||
|
// Define parameters
|
||||||
|
}),
|
||||||
|
execute: async (params) => {
|
||||||
|
// Implement tool logic
|
||||||
|
}
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Add to `src/tools/index.ts`
|
||||||
|
3. Create tests in `__tests__/tools/`
|
||||||
|
4. Add documentation in `docs/tools/`
|
||||||
|
|
||||||
|
## Contributing
|
||||||
|
|
||||||
|
1. Fork the repository
|
||||||
|
2. Create a feature branch
|
||||||
|
3. Make your changes
|
||||||
|
4. Write/update tests
|
||||||
|
5. Update documentation
|
||||||
|
6. Submit a pull request
|
||||||
|
|
||||||
|
### Pull Request Process
|
||||||
|
|
||||||
|
1. Ensure all tests pass
|
||||||
|
2. Update documentation
|
||||||
|
3. Update CHANGELOG.md
|
||||||
|
4. Get review from maintainers
|
||||||
|
|
||||||
|
## Building
|
||||||
|
|
||||||
|
1. Development build:
|
||||||
|
```bash
|
||||||
|
npm run build:dev
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Production build:
|
||||||
|
```bash
|
||||||
|
npm run build
|
||||||
|
```
|
||||||
|
|
||||||
|
## Documentation
|
||||||
|
|
||||||
|
1. Update documentation for changes
|
||||||
|
2. Follow documentation structure
|
||||||
|
3. Include examples
|
||||||
|
4. Update type definitions
|
||||||
|
|
||||||
|
## Debugging
|
||||||
|
|
||||||
|
1. Development debugging:
|
||||||
|
```bash
|
||||||
|
npm run dev:debug
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Test debugging:
|
||||||
|
```bash
|
||||||
|
npm run test:debug
|
||||||
|
```
|
||||||
|
|
||||||
|
3. VSCode launch configurations provided
|
||||||
|
|
||||||
|
## Performance
|
||||||
|
|
||||||
|
1. Follow performance best practices
|
||||||
|
2. Use caching where appropriate
|
||||||
|
3. Implement rate limiting
|
||||||
|
4. Monitor memory usage
|
||||||
|
|
||||||
|
## Security
|
||||||
|
|
||||||
|
1. Follow security best practices
|
||||||
|
2. Validate all inputs
|
||||||
|
3. Use proper authentication
|
||||||
|
4. Handle errors securely
|
||||||
|
|
||||||
|
## Deployment
|
||||||
|
|
||||||
|
1. Build for production:
|
||||||
|
```bash
|
||||||
|
npm run build
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Start production server:
|
||||||
|
```bash
|
||||||
|
npm start
|
||||||
|
```
|
||||||
|
|
||||||
|
3. Docker deployment:
|
||||||
|
```bash
|
||||||
|
docker-compose up -d
|
||||||
|
```
|
||||||
|
|
||||||
|
## Support
|
||||||
|
|
||||||
|
Need development help?
|
||||||
|
1. Check documentation
|
||||||
|
2. Search issues
|
||||||
|
3. Create new issue
|
||||||
|
4. Join discussions
|
||||||
122
docs/getting-started.md
Normal file
122
docs/getting-started.md
Normal file
@@ -0,0 +1,122 @@
|
|||||||
|
# Getting Started with Home Assistant MCP
|
||||||
|
|
||||||
|
This guide will help you get started with the Home Assistant MCP (Master Control Program).
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
Before you begin, ensure you have:
|
||||||
|
|
||||||
|
1. Node.js (v16 or higher)
|
||||||
|
2. A running Home Assistant instance
|
||||||
|
3. A Home Assistant Long-Lived Access Token
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
1. Clone the repository:
|
||||||
|
```bash
|
||||||
|
git clone https://github.com/yourusername/homeassistant-mcp.git
|
||||||
|
cd homeassistant-mcp
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Install dependencies:
|
||||||
|
```bash
|
||||||
|
npm install
|
||||||
|
```
|
||||||
|
|
||||||
|
3. Copy the example environment file:
|
||||||
|
```bash
|
||||||
|
cp .env.example .env
|
||||||
|
```
|
||||||
|
|
||||||
|
4. Edit the `.env` file with your configuration:
|
||||||
|
```env
|
||||||
|
# Server Configuration
|
||||||
|
PORT=3000
|
||||||
|
NODE_ENV=development
|
||||||
|
|
||||||
|
# Home Assistant Configuration
|
||||||
|
HASS_HOST=http://your-hass-instance:8123
|
||||||
|
HASS_TOKEN=your-long-lived-access-token
|
||||||
|
|
||||||
|
# Security Configuration
|
||||||
|
JWT_SECRET=your-secret-key
|
||||||
|
```
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
### Environment Variables
|
||||||
|
|
||||||
|
- `PORT`: The port number for the MCP server (default: 3000)
|
||||||
|
- `NODE_ENV`: The environment mode (development, production, test)
|
||||||
|
- `HASS_HOST`: Your Home Assistant instance URL
|
||||||
|
- `HASS_TOKEN`: Your Home Assistant Long-Lived Access Token
|
||||||
|
- `JWT_SECRET`: Secret key for JWT token generation
|
||||||
|
|
||||||
|
### Development Mode
|
||||||
|
|
||||||
|
For development, you can use:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run dev
|
||||||
|
```
|
||||||
|
|
||||||
|
This will start the server in development mode with hot reloading.
|
||||||
|
|
||||||
|
### Production Mode
|
||||||
|
|
||||||
|
For production, build and start the server:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run build
|
||||||
|
npm start
|
||||||
|
```
|
||||||
|
|
||||||
|
## First Steps
|
||||||
|
|
||||||
|
1. Check the server is running:
|
||||||
|
```bash
|
||||||
|
curl http://localhost:3000/api/health
|
||||||
|
```
|
||||||
|
|
||||||
|
2. List available devices:
|
||||||
|
```bash
|
||||||
|
curl -H "Authorization: Bearer your-token" http://localhost:3000/api/tools/devices
|
||||||
|
```
|
||||||
|
|
||||||
|
3. Subscribe to events:
|
||||||
|
```bash
|
||||||
|
curl -H "Authorization: Bearer your-token" http://localhost:3000/api/sse/subscribe?events=state_changed
|
||||||
|
```
|
||||||
|
|
||||||
|
## Next Steps
|
||||||
|
|
||||||
|
- Read the [API Documentation](./API.md) for available endpoints
|
||||||
|
- Learn about [Server-Sent Events](./SSE_API.md) for real-time updates
|
||||||
|
- Explore available [Tools](./tools/README.md) for device control
|
||||||
|
- Check the [Configuration Guide](./configuration/README.md) for advanced settings
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
If you encounter issues:
|
||||||
|
|
||||||
|
1. Verify your Home Assistant instance is accessible
|
||||||
|
2. Check your environment variables are correctly set
|
||||||
|
3. Look for errors in the server logs
|
||||||
|
4. Consult the [Troubleshooting Guide](./troubleshooting.md)
|
||||||
|
|
||||||
|
## Development
|
||||||
|
|
||||||
|
For development and contributing:
|
||||||
|
|
||||||
|
1. Fork the repository
|
||||||
|
2. Create a feature branch
|
||||||
|
3. Follow the [Development Guide](./development/README.md)
|
||||||
|
4. Submit a pull request
|
||||||
|
|
||||||
|
## Support
|
||||||
|
|
||||||
|
Need help? Check out:
|
||||||
|
|
||||||
|
- [GitHub Issues](https://github.com/yourusername/homeassistant-mcp/issues)
|
||||||
|
- [Troubleshooting Guide](./troubleshooting.md)
|
||||||
|
- [FAQ](./troubleshooting.md#faq)
|
||||||
127
docs/tools/README.md
Normal file
127
docs/tools/README.md
Normal file
@@ -0,0 +1,127 @@
|
|||||||
|
# Home Assistant MCP Tools
|
||||||
|
|
||||||
|
This section documents all available tools in the Home Assistant MCP.
|
||||||
|
|
||||||
|
## Available Tools
|
||||||
|
|
||||||
|
### Device Management
|
||||||
|
|
||||||
|
1. [List Devices](./list-devices.md)
|
||||||
|
- List all available Home Assistant devices
|
||||||
|
- Group devices by domain
|
||||||
|
- Get device states and attributes
|
||||||
|
|
||||||
|
2. [Device Control](./control.md)
|
||||||
|
- Control various device types
|
||||||
|
- Support for lights, switches, covers, climate devices
|
||||||
|
- Domain-specific commands and parameters
|
||||||
|
|
||||||
|
### History and State
|
||||||
|
|
||||||
|
1. [History](./history.md)
|
||||||
|
- Fetch device state history
|
||||||
|
- Filter by time range
|
||||||
|
- Get significant changes
|
||||||
|
|
||||||
|
2. [Scene Management](./scene.md)
|
||||||
|
- List available scenes
|
||||||
|
- Activate scenes
|
||||||
|
- Scene state information
|
||||||
|
|
||||||
|
### Automation
|
||||||
|
|
||||||
|
1. [Automation Management](./automation.md)
|
||||||
|
- List automations
|
||||||
|
- Toggle automation state
|
||||||
|
- Trigger automations manually
|
||||||
|
|
||||||
|
2. [Automation Configuration](./automation-config.md)
|
||||||
|
- Create new automations
|
||||||
|
- Update existing automations
|
||||||
|
- Delete automations
|
||||||
|
- Duplicate automations
|
||||||
|
|
||||||
|
### Add-ons and Packages
|
||||||
|
|
||||||
|
1. [Add-on Management](./addon.md)
|
||||||
|
- List available add-ons
|
||||||
|
- Install/uninstall add-ons
|
||||||
|
- Start/stop/restart add-ons
|
||||||
|
- Get add-on information
|
||||||
|
|
||||||
|
2. [Package Management](./package.md)
|
||||||
|
- Manage HACS packages
|
||||||
|
- Install/update/remove packages
|
||||||
|
- List available packages by category
|
||||||
|
|
||||||
|
### Notifications
|
||||||
|
|
||||||
|
1. [Notify](./notify.md)
|
||||||
|
- Send notifications
|
||||||
|
- Support for multiple notification services
|
||||||
|
- Custom notification data
|
||||||
|
|
||||||
|
### Real-time Events
|
||||||
|
|
||||||
|
1. [Event Subscription](./subscribe-events.md)
|
||||||
|
- Subscribe to Home Assistant events
|
||||||
|
- Monitor specific entities
|
||||||
|
- Domain-based monitoring
|
||||||
|
|
||||||
|
2. [SSE Statistics](./sse-stats.md)
|
||||||
|
- Get SSE connection statistics
|
||||||
|
- Monitor active subscriptions
|
||||||
|
- Connection management
|
||||||
|
|
||||||
|
## Using Tools
|
||||||
|
|
||||||
|
All tools can be accessed through:
|
||||||
|
|
||||||
|
1. REST API endpoints
|
||||||
|
2. WebSocket connections
|
||||||
|
3. Server-Sent Events (SSE)
|
||||||
|
|
||||||
|
### Authentication
|
||||||
|
|
||||||
|
Tools require authentication using:
|
||||||
|
- Home Assistant Long-Lived Access Token
|
||||||
|
- JWT tokens for specific operations
|
||||||
|
|
||||||
|
### Error Handling
|
||||||
|
|
||||||
|
All tools follow a consistent error handling pattern:
|
||||||
|
```typescript
|
||||||
|
{
|
||||||
|
success: boolean;
|
||||||
|
message?: string;
|
||||||
|
data?: any;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Rate Limiting
|
||||||
|
|
||||||
|
Tools are subject to rate limiting:
|
||||||
|
- Default: 100 requests per 15 minutes
|
||||||
|
- Configurable through environment variables
|
||||||
|
|
||||||
|
## Tool Development
|
||||||
|
|
||||||
|
Want to create a new tool? Check out:
|
||||||
|
- [Tool Development Guide](../development/tools.md)
|
||||||
|
- [Tool Interface Documentation](../development/interfaces.md)
|
||||||
|
- [Best Practices](../development/best-practices.md)
|
||||||
|
|
||||||
|
## Examples
|
||||||
|
|
||||||
|
Each tool documentation includes:
|
||||||
|
- Usage examples
|
||||||
|
- Code snippets
|
||||||
|
- Common use cases
|
||||||
|
- Troubleshooting tips
|
||||||
|
|
||||||
|
## Support
|
||||||
|
|
||||||
|
Need help with tools?
|
||||||
|
- Check individual tool documentation
|
||||||
|
- See [Troubleshooting Guide](../troubleshooting.md)
|
||||||
|
- Create an issue on GitHub
|
||||||
193
docs/troubleshooting.md
Normal file
193
docs/troubleshooting.md
Normal file
@@ -0,0 +1,193 @@
|
|||||||
|
# Troubleshooting Guide
|
||||||
|
|
||||||
|
This guide helps you diagnose and fix common issues with the Home Assistant MCP.
|
||||||
|
|
||||||
|
## Common Issues
|
||||||
|
|
||||||
|
### Connection Issues
|
||||||
|
|
||||||
|
#### Cannot Connect to Home Assistant
|
||||||
|
|
||||||
|
**Symptoms:**
|
||||||
|
- Connection timeout errors
|
||||||
|
- "Failed to connect to Home Assistant" messages
|
||||||
|
- 401 Unauthorized errors
|
||||||
|
|
||||||
|
**Solutions:**
|
||||||
|
1. Verify Home Assistant is running
|
||||||
|
2. Check HASS_HOST environment variable
|
||||||
|
3. Validate HASS_TOKEN is correct
|
||||||
|
4. Ensure network connectivity
|
||||||
|
5. Check firewall settings
|
||||||
|
|
||||||
|
#### SSE Connection Drops
|
||||||
|
|
||||||
|
**Symptoms:**
|
||||||
|
- Frequent disconnections
|
||||||
|
- Missing events
|
||||||
|
- Connection reset errors
|
||||||
|
|
||||||
|
**Solutions:**
|
||||||
|
1. Check network stability
|
||||||
|
2. Increase connection timeout
|
||||||
|
3. Implement reconnection logic
|
||||||
|
4. Monitor server resources
|
||||||
|
|
||||||
|
### Authentication Issues
|
||||||
|
|
||||||
|
#### Invalid Token
|
||||||
|
|
||||||
|
**Symptoms:**
|
||||||
|
- 401 Unauthorized responses
|
||||||
|
- "Invalid token" messages
|
||||||
|
- Authentication failures
|
||||||
|
|
||||||
|
**Solutions:**
|
||||||
|
1. Generate new Long-Lived Access Token
|
||||||
|
2. Check token expiration
|
||||||
|
3. Verify token format
|
||||||
|
4. Update environment variables
|
||||||
|
|
||||||
|
#### Rate Limiting
|
||||||
|
|
||||||
|
**Symptoms:**
|
||||||
|
- 429 Too Many Requests
|
||||||
|
- "Rate limit exceeded" messages
|
||||||
|
|
||||||
|
**Solutions:**
|
||||||
|
1. Implement request throttling
|
||||||
|
2. Adjust rate limit settings
|
||||||
|
3. Cache responses
|
||||||
|
4. Optimize request patterns
|
||||||
|
|
||||||
|
### Tool Issues
|
||||||
|
|
||||||
|
#### Tool Not Found
|
||||||
|
|
||||||
|
**Symptoms:**
|
||||||
|
- "Tool not found" errors
|
||||||
|
- 404 Not Found responses
|
||||||
|
|
||||||
|
**Solutions:**
|
||||||
|
1. Check tool name spelling
|
||||||
|
2. Verify tool registration
|
||||||
|
3. Update tool imports
|
||||||
|
4. Check tool availability
|
||||||
|
|
||||||
|
#### Tool Execution Fails
|
||||||
|
|
||||||
|
**Symptoms:**
|
||||||
|
- Tool execution errors
|
||||||
|
- Unexpected responses
|
||||||
|
- Timeout issues
|
||||||
|
|
||||||
|
**Solutions:**
|
||||||
|
1. Validate input parameters
|
||||||
|
2. Check error logs
|
||||||
|
3. Debug tool implementation
|
||||||
|
4. Verify Home Assistant permissions
|
||||||
|
|
||||||
|
## Debugging
|
||||||
|
|
||||||
|
### Server Logs
|
||||||
|
|
||||||
|
1. Enable debug logging:
|
||||||
|
```env
|
||||||
|
LOG_LEVEL=debug
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Check logs:
|
||||||
|
```bash
|
||||||
|
npm run logs
|
||||||
|
```
|
||||||
|
|
||||||
|
3. Filter logs:
|
||||||
|
```bash
|
||||||
|
npm run logs | grep "error"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Network Debugging
|
||||||
|
|
||||||
|
1. Check API endpoints:
|
||||||
|
```bash
|
||||||
|
curl -v http://localhost:3000/api/health
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Monitor SSE connections:
|
||||||
|
```bash
|
||||||
|
curl -N http://localhost:3000/api/sse/stats
|
||||||
|
```
|
||||||
|
|
||||||
|
3. Test WebSocket:
|
||||||
|
```bash
|
||||||
|
wscat -c ws://localhost:3000
|
||||||
|
```
|
||||||
|
|
||||||
|
### Performance Issues
|
||||||
|
|
||||||
|
1. Monitor memory usage:
|
||||||
|
```bash
|
||||||
|
npm run stats
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Check response times:
|
||||||
|
```bash
|
||||||
|
curl -w "%{time_total}\n" -o /dev/null -s http://localhost:3000/api/health
|
||||||
|
```
|
||||||
|
|
||||||
|
3. Profile code:
|
||||||
|
```bash
|
||||||
|
npm run profile
|
||||||
|
```
|
||||||
|
|
||||||
|
## FAQ
|
||||||
|
|
||||||
|
### Q: How do I reset my configuration?
|
||||||
|
A: Delete `.env` and copy `.env.example` to start fresh.
|
||||||
|
|
||||||
|
### Q: Why are my events delayed?
|
||||||
|
A: Check network latency and server load. Consider adjusting buffer sizes.
|
||||||
|
|
||||||
|
### Q: How do I update my token?
|
||||||
|
A: Generate a new token in Home Assistant and update HASS_TOKEN.
|
||||||
|
|
||||||
|
### Q: Why do I get "Maximum clients reached"?
|
||||||
|
A: Adjust SSE_MAX_CLIENTS in configuration or clean up stale connections.
|
||||||
|
|
||||||
|
## Error Codes
|
||||||
|
|
||||||
|
- `E001`: Connection Error
|
||||||
|
- `E002`: Authentication Error
|
||||||
|
- `E003`: Rate Limit Error
|
||||||
|
- `E004`: Tool Error
|
||||||
|
- `E005`: Configuration Error
|
||||||
|
|
||||||
|
## Support Resources
|
||||||
|
|
||||||
|
1. Documentation
|
||||||
|
- [API Reference](./API.md)
|
||||||
|
- [Configuration Guide](./configuration/README.md)
|
||||||
|
- [Development Guide](./development/README.md)
|
||||||
|
|
||||||
|
2. Community
|
||||||
|
- GitHub Issues
|
||||||
|
- Discussion Forums
|
||||||
|
- Stack Overflow
|
||||||
|
|
||||||
|
3. Tools
|
||||||
|
- Diagnostic Scripts
|
||||||
|
- Testing Tools
|
||||||
|
- Monitoring Tools
|
||||||
|
|
||||||
|
## Still Need Help?
|
||||||
|
|
||||||
|
1. Create a detailed issue:
|
||||||
|
- Error messages
|
||||||
|
- Steps to reproduce
|
||||||
|
- Environment details
|
||||||
|
- Logs
|
||||||
|
|
||||||
|
2. Contact support:
|
||||||
|
- GitHub Issues
|
||||||
|
- Email Support
|
||||||
|
- Community Forums
|
||||||
Reference in New Issue
Block a user