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/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