docs: Restructure documentation and enhance configuration

- Reorganize MkDocs navigation structure with new sections
- Add configuration, security, and development environment documentation
- Remove outdated development and getting started files
- Update requirements and plugin configurations
- Improve overall documentation layout and content

.github/workflows/deploy-docs.yml

@@ -14,13 +14,21 @@ jobs:
       contents: write
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
       - uses: actions/setup-python@v5
         with:
           python-version: '3.x'
           cache: 'pip'
-      - run: pip install -r docs/requirements.txt
+      - name: Install dependencies
-      - name: Deploy Documentation
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r docs/requirements.txt
+      - name: Configure Git
         run: |
           git config --global user.name "github-actions[bot]"
           git config --global user.email "github-actions[bot]@users.noreply.github.com"
-          mkdocs gh-deploy --force 
+      - name: Build and Deploy
+        run: |
+          mkdocs build --strict
+          mkdocs gh-deploy --force --clean 

.gitignore

@@ -31,7 +31,7 @@ wheels/
 venv/
 ENV/
 env/
-
+.venv/
 # Logs
 logs
 *.log
@@ -89,4 +89,13 @@ __pycache__/
 *.py[cod]
 *$py.class
 
-models/
+models/
+
+*.code-workspace
+*.ttf
+*.otf
+*.woff
+*.woff2
+*.eot
+*.svg
+*.png

docs/api/index.md

@@ -237,6 +237,6 @@ The current API version is v1. Include the version in the URL:
 
 The Advanced Home Assistant MCP provides several APIs for integration and automation:
 
-- [Core API](core-api.md) - Primary interface for system control
+- [Core API](core.md) - Primary interface for system control
 - [SSE API](sse.md) - Server-Sent Events for real-time updates
 - [Core Functions](core.md) - Essential system functions 

docs/config/index.md

@@ -0,0 +1,30 @@
+# Configuration
+
+This section covers the configuration options available in the Home Assistant MCP Server.
+
+## Overview
+
+The MCP Server can be configured through various configuration files and environment variables. This section will guide you through the available options and their usage.
+
+## Configuration Files
+
+The main configuration files are:
+
+1. `.env` - Environment variables
+2. `config.yaml` - Main configuration file
+3. `devices.yaml` - Device-specific configurations
+
+## Environment Variables
+
+Key environment variables that can be set:
+
+- `MCP_HOST` - Host address (default: 0.0.0.0)
+- `MCP_PORT` - Port number (default: 8123)
+- `MCP_LOG_LEVEL` - Logging level (default: INFO)
+- `MCP_CONFIG_DIR` - Configuration directory path
+
+## Next Steps
+
+- See [System Configuration](../configuration.md) for detailed configuration options
+- Check [Environment Setup](../getting-started/configuration.md) for initial setup
+- Review [Security](../security.md) for security-related configurations 

docs/configuration.md

@@ -0,0 +1,106 @@
+# System Configuration
+
+This document provides detailed information about configuring the Home Assistant MCP Server.
+
+## Configuration File Structure
+
+The MCP Server uses a hierarchical configuration structure:
+
+```yaml
+server:
+  host: 0.0.0.0
+  port: 8123
+  log_level: INFO
+
+security:
+  jwt_secret: YOUR_SECRET_KEY
+  allowed_origins:
+    - http://localhost:3000
+    - https://your-domain.com
+
+devices:
+  scan_interval: 30
+  default_timeout: 10
+```
+
+## Server Settings
+
+### Basic Server Configuration
+- `host`: Server binding address (default: 0.0.0.0)
+- `port`: Server port number (default: 8123)
+- `log_level`: Logging level (INFO, DEBUG, WARNING, ERROR)
+
+### Security Settings
+- `jwt_secret`: Secret key for JWT token generation
+- `allowed_origins`: CORS allowed origins list
+- `ssl_cert`: Path to SSL certificate (optional)
+- `ssl_key`: Path to SSL private key (optional)
+
+### Device Management
+- `scan_interval`: Device state scan interval in seconds
+- `default_timeout`: Default device command timeout
+- `retry_attempts`: Number of retry attempts for failed commands
+
+## Environment Variables
+
+Environment variables override configuration file settings:
+
+```bash
+MCP_HOST=0.0.0.0
+MCP_PORT=8123
+MCP_LOG_LEVEL=INFO
+MCP_JWT_SECRET=your-secret-key
+```
+
+## Advanced Configuration
+
+### Rate Limiting
+```yaml
+rate_limit:
+  enabled: true
+  requests_per_minute: 100
+  burst: 20
+```
+
+### Caching
+```yaml
+cache:
+  enabled: true
+  ttl: 300  # seconds
+  max_size: 1000  # entries
+```
+
+### Logging
+```yaml
+logging:
+  file: /var/log/mcp-server.log
+  max_size: 10MB
+  backup_count: 5
+  format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+```
+
+## Best Practices
+
+1. Always use environment variables for sensitive information
+2. Keep configuration files in a secure location
+3. Regularly backup your configuration
+4. Use SSL in production environments
+5. Monitor log files for issues
+
+## Validation
+
+The server validates configuration on startup:
+- Required fields are checked
+- Value types are verified
+- Ranges are validated
+- Security settings are assessed
+
+## Troubleshooting
+
+Common configuration issues:
+1. Permission denied accessing files
+2. Invalid YAML syntax
+3. Missing required fields
+4. Type mismatches in values
+
+See the [Troubleshooting Guide](troubleshooting.md) for solutions. 

docs/development/development.md

@@ -1,190 +0,0 @@
-# Development Guide
-
-This guide provides information for developers who want to contribute to or extend the Home Assistant MCP.
-
-## Project Structure
-
-```
-homeassistant-mcp/
-├── src/
-│   ├── __tests__/        # Test files
-│   ├── __mocks__/       # Mock files
-│   ├── 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 

docs/development/environment.md

@@ -0,0 +1,197 @@
+# Development Environment Setup
+
+This guide will help you set up your development environment for the Home Assistant MCP Server.
+
+## Prerequisites
+
+### Required Software
+- Python 3.10 or higher
+- pip (Python package manager)
+- git
+- Docker (optional, for containerized development)
+- Node.js 18+ (for frontend development)
+
+### System Requirements
+- 4GB RAM minimum
+- 2 CPU cores minimum
+- 10GB free disk space
+
+## Initial Setup
+
+1. Clone the Repository
+```bash
+git clone https://github.com/jango-blockchained/homeassistant-mcp.git
+cd homeassistant-mcp
+```
+
+2. Create Virtual Environment
+```bash
+python -m venv .venv
+source .venv/bin/activate  # Linux/macOS
+# or
+.venv\Scripts\activate  # Windows
+```
+
+3. Install Dependencies
+```bash
+pip install -r requirements.txt
+pip install -r docs/requirements.txt  # for documentation
+```
+
+## Development Tools
+
+### Code Editor Setup
+We recommend using Visual Studio Code with these extensions:
+- Python
+- Docker
+- YAML
+- ESLint
+- Prettier
+
+### VS Code Settings
+```json
+{
+  "python.linting.enabled": true,
+  "python.linting.pylintEnabled": true,
+  "python.formatting.provider": "black",
+  "editor.formatOnSave": true
+}
+```
+
+## Configuration
+
+1. Create Local Config
+```bash
+cp config.example.yaml config.yaml
+```
+
+2. Set Environment Variables
+```bash
+cp .env.example .env
+# Edit .env with your settings
+```
+
+## Running Tests
+
+### Unit Tests
+```bash
+pytest tests/unit
+```
+
+### Integration Tests
+```bash
+pytest tests/integration
+```
+
+### Coverage Report
+```bash
+pytest --cov=src tests/
+```
+
+## Docker Development
+
+### Build Container
+```bash
+docker build -t mcp-server-dev -f Dockerfile.dev .
+```
+
+### Run Development Container
+```bash
+docker run -it --rm \
+  -v $(pwd):/app \
+  -p 8123:8123 \
+  mcp-server-dev
+```
+
+## Database Setup
+
+### Local Development Database
+```bash
+docker run -d \
+  -p 5432:5432 \
+  -e POSTGRES_USER=mcp \
+  -e POSTGRES_PASSWORD=development \
+  -e POSTGRES_DB=mcp_dev \
+  postgres:14
+```
+
+### Run Migrations
+```bash
+alembic upgrade head
+```
+
+## Frontend Development
+
+1. Install Node.js Dependencies
+```bash
+cd frontend
+npm install
+```
+
+2. Start Development Server
+```bash
+npm run dev
+```
+
+## Documentation
+
+### Build Documentation
+```bash
+mkdocs serve
+```
+
+### View Documentation
+Open http://localhost:8000 in your browser
+
+## Debugging
+
+### VS Code Launch Configuration
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Python: MCP Server",
+      "type": "python",
+      "request": "launch",
+      "program": "src/main.py",
+      "console": "integratedTerminal"
+    }
+  ]
+}
+```
+
+## Git Hooks
+
+### Install Pre-commit
+```bash
+pip install pre-commit
+pre-commit install
+```
+
+### Available Hooks
+- black (code formatting)
+- flake8 (linting)
+- isort (import sorting)
+- mypy (type checking)
+
+## Troubleshooting
+
+Common Issues:
+1. Port already in use
+   - Check for running processes: `lsof -i :8123`
+   - Kill process if needed: `kill -9 PID`
+
+2. Database connection issues
+   - Verify PostgreSQL is running
+   - Check connection settings in .env
+
+3. Virtual environment problems
+   - Delete and recreate: `rm -rf .venv && python -m venv .venv`
+   - Reinstall dependencies
+
+## Next Steps
+
+1. Review the [Architecture Guide](../architecture.md)
+2. Check [Contributing Guidelines](../contributing.md)
+3. Start with [Simple Issues](https://github.com/jango-blockchained/homeassistant-mcp/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) 

docs/development/index.md

@@ -0,0 +1,54 @@
+# Development Guide
+
+Welcome to the development guide for the Home Assistant MCP Server. This section provides comprehensive information for developers who want to contribute to or extend the project.
+
+## Development Overview
+
+The MCP Server is built with modern development practices in mind, focusing on:
+
+- Clean, maintainable code
+- Comprehensive testing
+- Clear documentation
+- Modular architecture
+
+## Getting Started
+
+1. Set up your development environment
+2. Fork the repository
+3. Install dependencies
+4. Run tests
+5. Make your changes
+6. Submit a pull request
+
+## Development Topics
+
+- [Architecture](../architecture.md) - System architecture and design
+- [Contributing](../contributing.md) - Contribution guidelines
+- [Testing](../testing.md) - Testing framework and guidelines
+- [Troubleshooting](../troubleshooting.md) - Common issues and solutions
+- [Deployment](../deployment.md) - Deployment procedures
+- [Roadmap](../roadmap.md) - Future development plans
+
+## Best Practices
+
+- Follow the coding style guide
+- Write comprehensive tests
+- Document your changes
+- Keep commits atomic
+- Use meaningful commit messages
+
+## Development Workflow
+
+1. Create a feature branch
+2. Make your changes
+3. Run tests
+4. Update documentation
+5. Submit a pull request
+6. Address review comments
+7. Merge when approved
+
+## Next Steps
+
+- Review the [Architecture](../architecture.md)
+- Check [Contributing Guidelines](../contributing.md)
+- Set up your [Development Environment](environment.md) 

docs/getting-started.md

@@ -1,30 +0,0 @@
-# Getting Started
-
-Begin your journey with the Home Assistant MCP Server by following these steps:
-
-- **API Documentation:** Read the [API Documentation](api.md) for available endpoints.
-- **Real-Time Updates:** Learn about [Server-Sent Events](api/sse.md) for live communication.
-- **Tools:** Explore available [Tools](tools/tools.md) for device control and automation.
-- **Configuration:** Refer to the [Configuration Guide](getting-started/configuration.md) for setup and advanced settings.
-
-## Troubleshooting
-
-If you encounter any issues:
-1. Verify that your Home Assistant instance is accessible.
-2. Ensure that all required environment variables are properly set.
-3. Consult the [Troubleshooting Guide](troubleshooting.md) for additional solutions.
-
-## Development
-
-For contributors:
-1. Fork the repository.
-2. Create a feature branch.
-3. Follow the [Development Guide](development/development.md) for contribution guidelines.
-4. Submit a pull request with your enhancements.
-
-## Support
-
-Need help?
-- Visit our [GitHub Issues](https://github.com/jango-blockchained/homeassistant-mcp/issues).
-- Review the [Troubleshooting Guide](troubleshooting.md).
-- Check the [FAQ](troubleshooting.md#faq) for common questions. 

docs/javascripts/extra.js

@@ -0,0 +1,62 @@
+// Dark mode handling
+document.addEventListener('DOMContentLoaded', function () {
+    // Check for saved dark mode preference
+    const darkMode = localStorage.getItem('darkMode');
+    if (darkMode === 'true') {
+        document.body.classList.add('dark-mode');
+    }
+});
+
+// Smooth scrolling for anchor links
+document.querySelectorAll('a[href^="#"]').forEach(anchor => {
+    anchor.addEventListener('click', function (e) {
+        e.preventDefault();
+        document.querySelector(this.getAttribute('href')).scrollIntoView({
+            behavior: 'smooth'
+        });
+    });
+});
+
+// Add copy button to code blocks
+document.querySelectorAll('pre code').forEach((block) => {
+    const button = document.createElement('button');
+    button.className = 'copy-button';
+    button.textContent = 'Copy';
+
+    button.addEventListener('click', async () => {
+        await navigator.clipboard.writeText(block.textContent);
+        button.textContent = 'Copied!';
+        setTimeout(() => {
+            button.textContent = 'Copy';
+        }, 2000);
+    });
+
+    const pre = block.parentNode;
+    pre.insertBefore(button, block);
+});
+
+// Add version selector handling
+const versionSelector = document.querySelector('.version-selector');
+if (versionSelector) {
+    versionSelector.addEventListener('change', (e) => {
+        const version = e.target.value;
+        window.location.href = `/${version}/`;
+    });
+}
+
+// Add feedback handling
+document.querySelectorAll('.feedback-button').forEach(button => {
+    button.addEventListener('click', function () {
+        const feedback = this.getAttribute('data-feedback');
+        // Send feedback to analytics
+        if (typeof gtag !== 'undefined') {
+            gtag('event', 'feedback', {
+                'event_category': 'Documentation',
+                'event_label': feedback
+            });
+        }
+        // Show thank you message
+        this.textContent = 'Thank you!';
+        this.disabled = true;
+    });
+}); 

docs/javascripts/mathjax.js

@@ -0,0 +1,12 @@
+window.MathJax = {
+    tex: {
+        inlineMath: [["\\(", "\\)"]],
+        displayMath: [["\\[", "\\]"]],
+        processEscapes: true,
+        processEnvironments: true
+    },
+    options: {
+        ignoreHtmlClass: ".*|",
+        processHtmlClass: "arithmatex"
+    }
+}; 

docs/requirements.txt

@@ -1,11 +1,42 @@
-mkdocs>=1.5.0
+# Core
-mkdocs-material>=9.0.0
+mkdocs>=1.5.3
+mkdocs-material>=9.5.3
+
+# Enhanced Functionality
 mkdocs-minify-plugin>=0.7.1
-mkdocs-git-revision-date-plugin>=0.3.2
+mkdocs-git-revision-date-localized-plugin>=1.2.1
-mkdocs-mkdocstrings>=0.24.0
-mkdocs-social-plugin>=0.1.1
-mkdocs-redirects>=1.2.1
 mkdocs-glightbox>=0.3.4
-pillow>=10.0.0
+mkdocs-git-authors-plugin>=0.7.2
-cairosvg>=2.7.0
+mkdocs-git-committers-plugin>=0.2.3
-pymdown-extensions>=10.0 
+mkdocs-static-i18n>=1.2.0
+mkdocs-awesome-pages-plugin>=2.9.2
+mkdocs-redirects>=1.2.1
+mkdocs-include-markdown-plugin>=6.0.4
+mkdocs-macros-plugin>=1.0.4
+mkdocs-meta-descriptions-plugin>=3.0.0
+mkdocs-print-site-plugin>=2.3.6
+
+# Code Documentation
+mkdocstrings>=0.24.0
+mkdocstrings-python>=1.7.5
+
+# Markdown Extensions
+pymdown-extensions>=10.5
+markdown>=3.5.1
+mdx_truly_sane_lists>=1.3
+pygments>=2.17.2
+
+# Math Support
+python-markdown-math>=0.8
+
+# Diagrams
+plantuml-markdown>=3.9.2
+mkdocs-mermaid2-plugin>=1.1.1
+
+# Search Enhancements
+mkdocs-material[imaging]>=9.5.3
+pillow>=10.2.0
+cairosvg>=2.7.1
+
+# Development Tools
+mike>=2.0.0  # For version management 

docs/security.md

@@ -0,0 +1,146 @@
+# Security Guide
+
+This document outlines security best practices and configurations for the Home Assistant MCP Server.
+
+## Authentication
+
+### JWT Authentication
+The server uses JWT (JSON Web Tokens) for API authentication:
+
+```http
+Authorization: Bearer YOUR_JWT_TOKEN
+```
+
+### Token Configuration
+```yaml
+security:
+  jwt_secret: YOUR_SECRET_KEY
+  token_expiry: 24h
+  refresh_token_expiry: 7d
+```
+
+## Access Control
+
+### CORS Configuration
+Configure allowed origins to prevent unauthorized access:
+
+```yaml
+security:
+  allowed_origins:
+    - http://localhost:3000
+    - https://your-domain.com
+```
+
+### IP Filtering
+Restrict access by IP address:
+
+```yaml
+security:
+  allowed_ips:
+    - 192.168.1.0/24
+    - 10.0.0.0/8
+```
+
+## SSL/TLS Configuration
+
+### Enable HTTPS
+```yaml
+ssl:
+  enabled: true
+  cert_file: /path/to/cert.pem
+  key_file: /path/to/key.pem
+```
+
+### Certificate Management
+1. Use Let's Encrypt for free SSL certificates
+2. Regularly renew certificates
+3. Monitor certificate expiration
+
+## Rate Limiting
+
+### Basic Rate Limiting
+```yaml
+rate_limit:
+  enabled: true
+  requests_per_minute: 100
+  burst: 20
+```
+
+### Advanced Rate Limiting
+```yaml
+rate_limit:
+  rules:
+    - endpoint: /api/control
+      requests_per_minute: 50
+    - endpoint: /api/state
+      requests_per_minute: 200
+```
+
+## Data Protection
+
+### Sensitive Data
+- Use environment variables for secrets
+- Encrypt sensitive data at rest
+- Implement secure backup procedures
+
+### Logging Security
+- Avoid logging sensitive information
+- Rotate logs regularly
+- Protect log file access
+
+## Best Practices
+
+1. Regular Security Updates
+   - Keep dependencies updated
+   - Monitor security advisories
+   - Apply patches promptly
+
+2. Password Policies
+   - Enforce strong passwords
+   - Implement password expiration
+   - Use secure password storage
+
+3. Monitoring
+   - Log security events
+   - Monitor access patterns
+   - Set up alerts for suspicious activity
+
+4. Network Security
+   - Use VPN for remote access
+   - Implement network segmentation
+   - Configure firewalls properly
+
+## Security Checklist
+
+- [ ] Configure SSL/TLS
+- [ ] Set up JWT authentication
+- [ ] Configure CORS properly
+- [ ] Enable rate limiting
+- [ ] Implement IP filtering
+- [ ] Secure sensitive data
+- [ ] Set up monitoring
+- [ ] Configure backup encryption
+- [ ] Update security policies
+
+## Incident Response
+
+1. Detection
+   - Monitor security logs
+   - Set up intrusion detection
+   - Configure alerts
+
+2. Response
+   - Document incident details
+   - Isolate affected systems
+   - Investigate root cause
+
+3. Recovery
+   - Apply security fixes
+   - Restore from backups
+   - Update security measures
+
+## Additional Resources
+
+- [Security Best Practices](https://owasp.org/www-project-top-ten/)
+- [JWT Security](https://jwt.io/introduction)
+- [SSL Configuration](https://ssl-config.mozilla.org/) 

docs/stylesheets/extra.css

@@ -0,0 +1,164 @@
+/* Modern Dark Theme Enhancements */
+[data-md-color-scheme="slate"] {
+    --md-default-bg-color: #1a1b26;
+    --md-default-fg-color: #a9b1d6;
+    --md-default-fg-color--light: #a9b1d6;
+    --md-default-fg-color--lighter: #787c99;
+    --md-default-fg-color--lightest: #4e5173;
+    --md-primary-fg-color: #7aa2f7;
+    --md-primary-fg-color--light: #7dcfff;
+    --md-primary-fg-color--dark: #2ac3de;
+    --md-accent-fg-color: #bb9af7;
+    --md-accent-fg-color--transparent: #bb9af722;
+    --md-accent-bg-color: #1a1b26;
+    --md-accent-bg-color--light: #24283b;
+}
+
+/* Code Blocks */
+.highlight pre {
+    background-color: #24283b !important;
+    border-radius: 6px;
+    padding: 1em;
+    margin: 1em 0;
+    overflow: auto;
+}
+
+.highlight code {
+    font-family: 'Roboto Mono', monospace;
+    font-size: 0.9em;
+}
+
+/* Copy Button */
+.copy-button {
+    position: absolute;
+    right: 0.5em;
+    top: 0.5em;
+    padding: 0.4em 0.8em;
+    background-color: var(--md-accent-bg-color--light);
+    border: 1px solid var(--md-accent-fg-color--transparent);
+    border-radius: 4px;
+    color: var(--md-default-fg-color);
+    font-size: 0.8em;
+    cursor: pointer;
+    transition: all 0.2s ease;
+}
+
+.copy-button:hover {
+    background-color: var(--md-accent-fg-color--transparent);
+    border-color: var(--md-accent-fg-color);
+}
+
+/* Navigation Enhancements */
+.md-nav {
+    font-size: 0.9rem;
+}
+
+.md-nav__link {
+    padding: 0.4rem 0;
+    transition: color 0.2s ease;
+}
+
+.md-nav__link:hover {
+    color: var(--md-primary-fg-color) !important;
+}
+
+/* Tabs */
+.md-tabs__link {
+    opacity: 0.8;
+    transition: opacity 0.2s ease;
+}
+
+.md-tabs__link:hover {
+    opacity: 1;
+}
+
+.md-tabs__link--active {
+    opacity: 1;
+}
+
+/* Admonitions */
+.md-typeset .admonition,
+.md-typeset details {
+    border-width: 0;
+    border-left-width: 4px;
+    border-radius: 4px;
+}
+
+/* Tables */
+.md-typeset table:not([class]) {
+    border-radius: 4px;
+    box-shadow: 0 2px 4px var(--md-accent-fg-color--transparent);
+}
+
+.md-typeset table:not([class]) th {
+    background-color: var(--md-accent-bg-color--light);
+    border-bottom: 2px solid var(--md-accent-fg-color--transparent);
+}
+
+/* Search */
+.md-search__form {
+    background-color: var(--md-accent-bg-color--light);
+    border-radius: 4px;
+}
+
+/* Feedback Buttons */
+.feedback-button {
+    padding: 0.5em 1em;
+    margin: 0 0.5em;
+    border-radius: 4px;
+    background-color: var(--md-accent-bg-color--light);
+    border: 1px solid var(--md-accent-fg-color--transparent);
+    color: var(--md-default-fg-color);
+    cursor: pointer;
+    transition: all 0.2s ease;
+}
+
+.feedback-button:hover {
+    background-color: var(--md-accent-fg-color--transparent);
+    border-color: var(--md-accent-fg-color);
+}
+
+.feedback-button:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+}
+
+/* Version Selector */
+.version-selector {
+    padding: 0.5em;
+    border-radius: 4px;
+    background-color: var(--md-accent-bg-color--light);
+    border: 1px solid var(--md-accent-fg-color--transparent);
+    color: var(--md-default-fg-color);
+}
+
+/* Scrollbar */
+::-webkit-scrollbar {
+    width: 8px;
+    height: 8px;
+}
+
+::-webkit-scrollbar-track {
+    background: var(--md-accent-bg-color--light);
+}
+
+::-webkit-scrollbar-thumb {
+    background: var(--md-accent-fg-color--transparent);
+    border-radius: 4px;
+}
+
+::-webkit-scrollbar-thumb:hover {
+    background: var(--md-accent-fg-color);
+}
+
+/* Print Styles */
+@media print {
+    .md-typeset a {
+        color: var(--md-default-fg-color) !important;
+    }
+    
+    .md-content__inner {
+        margin: 0;
+        padding: 1rem;
+    }
+} 

docs/tools/index.md

@@ -0,0 +1,42 @@
+# Tools Overview
+
+The Home Assistant MCP Server provides a variety of tools to help you manage and interact with your home automation system.
+
+## Available Tools
+
+### Device Management
+- [List Devices](device-management/list-devices.md) - View and manage connected devices
+- [Device Control](device-management/control.md) - Control device states and settings
+
+### History & State
+- [History](history-state/history.md) - View and analyze historical data
+- [Scene Management](history-state/scene.md) - Create and manage scenes
+
+### Automation
+- [Automation Management](automation/automation.md) - Create and manage automations
+- [Automation Configuration](automation/automation-config.md) - Configure automation settings
+
+### Add-ons & Packages
+- [Add-on Management](addons-packages/addon.md) - Manage server add-ons
+- [Package Management](addons-packages/package.md) - Handle package installations
+
+### Notifications
+- [Notify](notifications/notify.md) - Send and manage notifications
+
+### Events
+- [Event Subscription](events/subscribe-events.md) - Subscribe to system events
+- [SSE Statistics](events/sse-stats.md) - Monitor Server-Sent Events statistics
+
+## Getting Started
+
+To get started with these tools:
+
+1. Ensure you have the MCP Server properly installed and configured
+2. Check the specific tool documentation for detailed usage instructions
+3. Use the API endpoints or command-line interface as needed
+
+## Next Steps
+
+- Review the [API Documentation](../api/index.md) for programmatic access
+- Check [Configuration](../config/index.md) for tool-specific settings
+- See [Examples](../examples/index.md) for practical use cases 

docs/tools/tools.md

@@ -1,127 +0,0 @@
-# Home Assistant MCP Tools
-
-This section documents all available tools in the Home Assistant MCP.
-
-## Available Tools
-
-### Device Management
-
-1. [List Devices](device-management/list-devices.md)
-   - List all available Home Assistant devices
-   - Group devices by domain
-   - Get device states and attributes
-
-2. [Device Control](device-management/control.md)
-   - Control various device types
-   - Support for lights, switches, covers, climate devices
-   - Domain-specific commands and parameters
-
-### History and State
-
-1. [History](history-state/history.md)
-   - Fetch device state history
-   - Filter by time range
-   - Get significant changes
-
-2. [Scene Management](history-state/scene.md)
-   - List available scenes
-   - Activate scenes
-   - Scene state information
-
-### Automation
-
-1. [Automation Management](automation/automation.md)
-   - List automations
-   - Toggle automation state
-   - Trigger automations manually
-
-2. [Automation Configuration](automation/automation-config.md)
-   - Create new automations
-   - Update existing automations
-   - Delete automations
-   - Duplicate automations
-
-### Add-ons and Packages
-
-1. [Add-on Management](addons-packages/addon.md)
-   - List available add-ons
-   - Install/uninstall add-ons
-   - Start/stop/restart add-ons
-   - Get add-on information
-
-2. [Package Management](addons-packages/package.md)
-   - Manage HACS packages
-   - Install/update/remove packages
-   - List available packages by category
-
-### Notifications
-
-1. [Notify](notifications/notify.md)
-   - Send notifications
-   - Support for multiple notification services
-   - Custom notification data
-
-### Real-time Events
-
-1. [Event Subscription](events/subscribe-events.md)
-   - Subscribe to Home Assistant events
-   - Monitor specific entities
-   - Domain-based monitoring
-
-2. [SSE Statistics](events/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 

mkdocs.yml

@@ -1,74 +1,220 @@
-site_name: Project Documentation
+site_name: MCP Server for Home Assistant
 site_url: https://jango-blockchained.github.io/advanced-homeassistant-mcp
 repo_url: https://github.com/jango-blockchained/advanced-homeassistant-mcp
+site_description: Home Assistant MCP Server Documentation
+# Add this to handle GitHub Pages serving from a subdirectory
+site_dir: site/advanced-homeassistant-mcp
 
 theme:
   name: material
   logo: assets/images/logo.png
   favicon: assets/images/favicon.ico
-  palette:
+  
-    - scheme: default
+  # Modern Features
-      primary: indigo
-      accent: indigo
-      toggle:
-        icon: material/brightness-7
-        name: Switch to dark mode
-    - scheme: slate
-      primary: indigo
-      accent: indigo
-      toggle:
-        icon: material/brightness-4
-        name: Switch to light mode
   features:
-    - navigation.instant
+    # Navigation Enhancements
-    - navigation.tracking
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.indexes
     - navigation.sections
     - navigation.expand
-    - navigation.top
+    - navigation.path
+    - navigation.footer
+    - navigation.prune
+    - navigation.tracking
+    - navigation.instant
+    
+    # UI Elements
+    - header.autohide
+    - toc.integrate
+    - toc.follow
+    - announce.dismiss
+    
+    # Search Features
     - search.suggest
     - search.highlight
+    - search.share
+    
+    # Code Features
+    - content.code.annotate
     - content.code.copy
+    - content.code.select
     - content.tabs.link
     - content.tooltips
-    - toc.integrate
+    
+  # Theme Configuration
+  palette:
+    # Dark mode as primary
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: deep-purple
+      accent: purple
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to light mode
+    # Light mode as secondary
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: deep-purple
+      accent: purple
+      toggle:
+        icon: material/weather-night
+        name: Switch to dark mode
+  
+  font:
+    text: Roboto
+    code: Roboto Mono
+  
+  icon:
+    repo: fontawesome/brands/github
+    edit: material/pencil
+    view: material/eye
 
 markdown_extensions:
+  # Modern Code Highlighting
   - pymdownx.highlight:
       anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
   - pymdownx.inlinehilite
   - pymdownx.snippets
-  - pymdownx.superfences
+  
-  - admonition
+  # Advanced Formatting
+  - pymdownx.critic
+  - pymdownx.caret
+  - pymdownx.keys
+  - pymdownx.mark
+  - pymdownx.tilde
+  
+  # Interactive Elements
   - pymdownx.details
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  
+  # Diagrams & Formatting
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.arithmatex:
+      generic: true
+  
+  # Additional Extensions
+  - admonition
   - attr_list
   - md_in_html
-  - pymdownx.emoji
+  - pymdownx.emoji:
-  - pymdownx.tasklist
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
   - footnotes
   - tables
+  - def_list
+  - abbr
 
 plugins:
-  - search
+  # Core Plugins
+  - search:
+      separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'
   - minify:
       minify_html: true
-  - git-revision-date-plugin
+  - mkdocstrings
-  - mkdocstrings:
+  
-      default_handler: python
+  # Advanced Features
-  - social
+  - social:
+      cards: false
   - tags
-  - redirects
+  - offline
-  - gh-deploy
+  
+  # Version Management
+  - git-revision-date-localized:
+      enable_creation_date: true
+      type: date
 
+extra:
+  # Consent Management
+  consent:
+    title: Cookie consent
+    description: >- 
+      We use cookies to recognize your repeated visits and preferences, as well
+      as to measure the effectiveness of our documentation and whether users
+      find what they're searching for. With your consent, you're helping us to
+      make our documentation better.
+    actions:
+      - accept
+      - reject
+      - manage
+  
+  # Version Management
+  version:
+    provider: mike
+    default: latest
+  
+  # Social Links
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/jango-blockchained/homeassistant-mcp
+    - icon: fontawesome/brands/docker
+      link: https://hub.docker.com/r/jangoblockchained/homeassistant-mcp
+  
+  # Status Indicators
+  status:
+    new: Recently added
+    deprecated: Deprecated
+    beta: Beta
+  
+  # Analytics
+  analytics:
+    provider: google
+    property: !ENV GOOGLE_ANALYTICS_KEY
+    feedback:
+      title: Was this page helpful?
+      ratings:
+        - icon: material/emoticon-happy-outline
+          name: This page was helpful
+          data: 1
+          note: >-
+            Thanks for your feedback!
+        - icon: material/emoticon-sad-outline
+          name: This page could be improved
+          data: 0
+          note: >-
+            Thanks for your feedback! Please consider creating an issue to help us improve.
+
+extra_css:
+  - stylesheets/extra.css
+
+extra_javascript:
+  - javascripts/mathjax.js
+  - https://polyfill.io/v3/polyfill.min.js?features=es6
+  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
+  - javascripts/extra.js
+
+copyright: Copyright © 2025 jango-blockchained
+
+# Keep existing nav structure
 nav:
   - Home: index.md
-  - Getting Started: getting-started.md
+  - Getting Started:
-  - API Reference: api.md
+    - Overview: getting-started/index.md
+    - Installation: getting-started/installation.md
+    - Quick Start: getting-started/quickstart.md
+    - Configuration: getting-started/configuration.md
+    - Docker Setup: getting-started/docker.md
+  - API Reference:
+    - Overview: api/index.md
+    - Core API: api/core.md
+    - SSE API: api/sse.md
+    - API Documentation: api.md
   - Usage: usage.md
   - Configuration:
-    - Claude Desktop Config: claude_desktop_config.md
+    - Overview: config/index.md
-    - Client Config: client_config.md
+    - System Configuration: configuration.md
+    - Security: security.md
   - Tools:
-    - Overview: tools/tools.md
+    - Overview: tools/index.md
     - Device Management:
       - List Devices: tools/device-management/list-devices.md
       - Device Control: tools/device-management/control.md
@@ -87,33 +233,17 @@ nav:
       - Event Subscription: tools/events/subscribe-events.md
       - SSE Statistics: tools/events/sse-stats.md
   - Development:
-    - Overview: development/development.md
+    - Overview: development/index.md
+    - Environment Setup: development/environment.md
+    - Architecture: architecture.md
+    - Contributing: contributing.md
+    - Testing: testing.md
     - Best Practices: development/best-practices.md
     - Interfaces: development/interfaces.md
     - Tool Development: development/tools.md
-    - Testing Guide: testing.md
+    - Test Migration Guide: development/test-migration-guide.md
-    - Deployment Guide: deployment.md
+    - Troubleshooting: troubleshooting.md
-  - Architecture: architecture.md
+    - Deployment: deployment.md
-  - Contributing: contributing.md
+    - Roadmap: roadmap.md
-  - Troubleshooting: troubleshooting.md
   - Examples:
-    - Overview: examples/index.md
+    - Overview: examples/index.md
-  - Roadmap: roadmap.md
-
-extra:
-  social:
-    - icon: fontawesome/brands/github
-      link: https://github.com/jango-blockchained/homeassistant-mcp
-    - icon: fontawesome/brands/docker
-      link: https://hub.docker.com/r/jangoblockchained/homeassistant-mcp
-  analytics:
-    provider: google
-    property: !ENV GOOGLE_ANALYTICS_KEY
-
-extra_css:
-  - stylesheets/extra.css
-
-extra_javascript:
-  - javascripts/extra.js
-
-copyright: Copyright © 2025 jango-blockchained