From 18f09bb5ce19fc0289d0a5dbd8dfa019e88cb425 Mon Sep 17 00:00:00 2001
From: jango-blockchained <info@cryptolinx.de>
Date: Mon, 3 Feb 2025 15:38:55 +0100
Subject: [PATCH] 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
---
 docs/README.md             |  60 ++++++++++++
 docs/development/README.md | 188 ++++++++++++++++++++++++++++++++++++
 docs/getting-started.md    | 122 +++++++++++++++++++++++
 docs/tools/README.md       | 127 ++++++++++++++++++++++++
 docs/troubleshooting.md    | 193 +++++++++++++++++++++++++++++++++++++
 5 files changed, 690 insertions(+)
 create mode 100644 docs/README.md
 create mode 100644 docs/development/README.md
 create mode 100644 docs/getting-started.md
 create mode 100644 docs/tools/README.md
 create mode 100644 docs/troubleshooting.md

diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..4e6b19c
--- /dev/null
+++ b/docs/README.md
@@ -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. 
\ No newline at end of file
diff --git a/docs/development/README.md b/docs/development/README.md
new file mode 100644
index 0000000..1e1a251
--- /dev/null
+++ b/docs/development/README.md
@@ -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 
\ No newline at end of file
diff --git a/docs/getting-started.md b/docs/getting-started.md
new file mode 100644
index 0000000..22e56a4
--- /dev/null
+++ b/docs/getting-started.md
@@ -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) 
\ No newline at end of file
diff --git a/docs/tools/README.md b/docs/tools/README.md
new file mode 100644
index 0000000..ec49660
--- /dev/null
+++ b/docs/tools/README.md
@@ -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 
\ No newline at end of file
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
new file mode 100644
index 0000000..1da235f
--- /dev/null
+++ b/docs/troubleshooting.md
@@ -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 
\ No newline at end of file