docs: Enhance documentation deployment and site configuration

- Update MkDocs configuration with new features and plugins
- Add deployment guide for documentation
- Restructure documentation navigation and index page
- Create GitHub Actions workflow for automatic documentation deployment
- Fix typos in site URLs and configuration

.github/workflows/deploy-docs.yml

@@ -1,64 +1,38 @@
-name: Deploy Documentation to GitHub Pages
+name: Deploy MkDocs
-
 on:
   push:
     branches:
-      - main
+      - main  # or master, depending on your default branch
-    paths:
+  workflow_dispatch:
-      - 'docs/**'
-      - '.github/workflows/deploy-docs.yml'
 
 permissions:
-  contents: read
+  contents: write
-  pages: write
-  id-token: write
-
-# Allow only one concurrent deployment
-concurrency:
-  group: "pages"
-  cancel-in-progress: true
 
 jobs:
-  build:
+  deploy:
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout
+      - uses: actions/checkout@v4
-        uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
-
-      - name: Setup Ruby
-        uses: ruby/setup-ruby@v1
         with:
-          ruby-version: '3.2'
+          python-version: '3.x'
-          bundler-cache: true
-          cache-version: 0
-
-      - name: Setup Pages
-        uses: actions/configure-pages@v4
-
       - name: Install dependencies
         run: |
-          cd docs
+          pip install mkdocs-material
-          bundle install
+          pip install mkdocs-git-revision-date-localized-plugin
-
+          pip install mkdocstrings[python]
-      - name: Build site
+      - name: Configure Git
         run: |
-          cd docs
+          git config --global user.name "github-actions[bot]"
-          bundle exec jekyll build
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
-        env:
+      - name: Build docs
-          JEKYLL_ENV: production
+        run: mkdocs build
-
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
-        with:
-          path: docs/_site
-
-  deploy:
-    needs: build
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
-    steps:
       - name: Deploy to GitHub Pages
-        id: deployment
+        run: |
-        uses: actions/deploy-pages@v4 
+          git checkout --orphan gh-pages
+          git rm -rf .
+          mv site/* .
+          rm -rf site
+          git add .
+          git commit -m "docs: Update documentation"
+          git push origin gh-pages --force 

README.md

@@ -1,8 +1,6 @@
 # MCP Server for Home Assistant 🏠🤖
 
-[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)  
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Bun](https://img.shields.io/badge/bun-%3E%3D1.0.26-black)](https://bun.sh) [![TypeScript](https://img.shields.io/badge/typescript-%5E5.0.0-blue.svg)](https://www.typescriptlang.org) [![smithery badge](https://smithery.ai/badge/@jango-blockchained/advanced-homeassistant-mcp)](https://smithery.ai/server/@jango-blockchained/advanced-homeassistant-mcp)
-[![Bun](https://img.shields.io/badge/bun-%3E%3D1.0.26-black)](https://bun.sh)  
-[![TypeScript](https://img.shields.io/badge/typescript-%5E5.0.0-blue.svg)](https://www.typescriptlang.org)
 
 ## Overview 🌐
 

docs/.github/workflows/deploy-docs.yml

@@ -0,0 +1,38 @@
+name: Deploy MkDocs
+on:
+  push:
+    branches:
+      - main
+      - master
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.x'
+      
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install mkdocs-material
+          pip install mkdocs-minify-plugin
+          pip install mkdocs-git-revision-date-plugin
+          pip install mkdocs-mkdocstrings
+          pip install mkdocs-social-plugin
+          pip install mkdocs-redirects
+      
+      - name: Deploy
+        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 

docs/api.md

@@ -148,7 +148,7 @@ async function controlDevice(entityId: string, command: string, params?: Record<
     }
 
     return await response.json();
-  } catch (error) {
+} catch (error) {
     console.error('Device control failed:', error);
     throw error;
   }

docs/api/index.md

@@ -232,3 +232,11 @@ The current API version is v1. Include the version in the URL:
 - [Core Functions](core.md) - Detailed endpoint documentation
 - [Architecture Overview](../architecture.md) - System design details
 - [Troubleshooting](../troubleshooting.md) - Common issues and solutions
+
+# API Reference
+
+The Advanced Home Assistant MCP provides several APIs for integration and automation:
+
+- [Core API](core-api.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/deployment.md

@@ -0,0 +1,103 @@
+# Deployment Guide
+
+This documentation is automatically deployed to GitHub Pages using GitHub Actions. Here's how it works and how to manage deployments.
+
+## Automatic Deployment
+
+The documentation is automatically deployed when changes are pushed to the `main` or `master` branch. The deployment process:
+
+1. Triggers on push to main/master
+2. Sets up Python environment
+3. Installs required dependencies
+4. Builds the documentation
+5. Deploys to the `gh-pages` branch
+
+### GitHub Actions Workflow
+
+The deployment is handled by the workflow in `.github/workflows/deploy-docs.yml`:
+
+```yaml
+name: Deploy MkDocs
+on:
+  push:
+    branches:
+      - main
+      - master
+```
+
+## Manual Deployment
+
+If needed, you can deploy manually using:
+
+```bash
+# Install dependencies
+pip install -r docs/requirements.txt
+
+# Deploy to GitHub Pages
+mkdocs gh-deploy --force
+```
+
+## Best Practices
+
+### 1. Documentation Updates
+- Test locally before pushing: `mkdocs serve`
+- Verify all links work
+- Ensure images are optimized
+- Check mobile responsiveness
+
+### 2. Version Control
+- Keep documentation in sync with code versions
+- Use meaningful commit messages
+- Tag important documentation versions
+
+### 3. Content Guidelines
+- Use consistent formatting
+- Keep navigation structure logical
+- Include examples where appropriate
+- Maintain up-to-date screenshots
+
+### 4. Maintenance
+- Regularly review and update content
+- Check for broken links
+- Update dependencies
+- Monitor GitHub Actions logs
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Failed Deployments**
+   - Check GitHub Actions logs
+   - Verify dependencies are up to date
+   - Ensure all required files exist
+
+2. **Broken Links**
+   - Run `mkdocs build --strict`
+   - Use relative paths in markdown
+   - Check case sensitivity
+
+3. **Style Issues**
+   - Verify theme configuration
+   - Check CSS customizations
+   - Test on multiple browsers
+
+## Configuration Files
+
+### requirements.txt
+
+Create a requirements file for documentation dependencies:
+
+```txt
+mkdocs-material
+mkdocs-minify-plugin
+mkdocs-git-revision-date-plugin
+mkdocs-mkdocstrings
+mkdocs-social-plugin
+mkdocs-redirects
+```
+
+## Monitoring
+
+- Check [GitHub Pages settings](https://github.com/jango-blockchained/advanced-homeassistant-mcp/settings/pages)
+- Monitor build status in Actions tab
+- Verify site accessibility 

docs/getting-started/index.md

@@ -0,0 +1,8 @@
+# Getting Started
+
+Welcome to the Advanced Home Assistant MCP getting started guide. Follow these steps to begin:
+
+1. [Installation](installation.md)
+2. [Configuration](configuration.md)
+3. [Docker Setup](docker.md)
+4. [Quick Start](quickstart.md) 

docs/index.md

@@ -4,9 +4,18 @@ title: Home
 nav_order: 1
 ---
 
-# 🏠 MCP Server for Home Assistant
+# Advanced Home Assistant MCP
 
-Welcome to the Model Context Protocol (MCP) Server documentation! This guide will help you get started with integrating a lightweight automation tool with your Home Assistant setup.
+Welcome to the Advanced Home Assistant Master Control Program documentation.
+
+This documentation provides comprehensive information about setting up, configuring, and using the Advanced Home Assistant MCP system.
+
+## Quick Links
+
+- [Getting Started](getting-started/index.md)
+- [API Reference](api/index.md)
+- [Configuration Guide](getting-started/configuration.md)
+- [Docker Setup](getting-started/docker.md)
 
 ## What is MCP Server?
 

docs/requirements.txt

@@ -0,0 +1 @@
+ 

mkdocs.yml

@@ -1,23 +1,19 @@
-site_name: Home Assistant MCP
+site_name: Advanced Home Assistant MCP
-site_description: A bridge between Home Assistant and Language Learning Models
+site_url: https://jango-blockchained.github.io/advanced-homeassistant-mcp
-site_url: https://jango-blockchained.github.io/advanced-homeassistant-mcp/
 repo_url: https://github.com/jango-blockchained/advanced-homeassistant-mcp
-repo_name: jango-blockchained/advanced-homeassistant-mcp
 
 theme:
   name: material
   logo: assets/images/logo.png
   favicon: assets/images/favicon.ico
   palette:
-    - media: "(prefers-color-scheme: light)"
+    - scheme: default
-      scheme: default
       primary: indigo
       accent: indigo
       toggle:
         icon: material/brightness-7
         name: Switch to dark mode
-    - media: "(prefers-color-scheme: dark)"
+    - scheme: slate
-      scheme: slate
       primary: indigo
       accent: indigo
       toggle:
@@ -32,65 +28,52 @@ theme:
     - search.suggest
     - search.highlight
     - content.code.copy
+    - content.tabs.link
+    - content.tooltips
+    - toc.integrate
 
 markdown_extensions:
-  - admonition
-  - attr_list
-  - def_list
-  - footnotes
-  - meta
-  - toc:
-      permalink: true
-  - pymdownx.arithmatex:
-      generic: true
-  - pymdownx.betterem:
-      smart_enable: all
-  - pymdownx.caret
-  - pymdownx.details
-  - pymdownx.emoji:
-      emoji_index: !!python/name:material.extensions.emoji.twemoji
-      emoji_generator: !!python/name:material.extensions.emoji.to_svg
   - pymdownx.highlight:
       anchor_linenums: true
   - pymdownx.inlinehilite
-  - pymdownx.keys
+  - pymdownx.snippets
-  - pymdownx.magiclink
+  - pymdownx.superfences
-  - pymdownx.mark
+  - admonition
-  - pymdownx.smartsymbols
+  - pymdownx.details
-  - pymdownx.superfences:
+  - attr_list
-      custom_fences:
+  - md_in_html
-        - name: mermaid
+  - pymdownx.emoji
-          class: mermaid
+  - pymdownx.tasklist
-          format: !!python/name:pymdownx.superfences.fence_code_format
+  - footnotes
-  - pymdownx.tabbed:
+  - tables
-      alternate_style: true
-  - pymdownx.tasklist:
-      custom_checkbox: true
-  - pymdownx.tilde
 
 plugins:
   - search
-  - git-revision-date-localized:
+  - minify:
-      type: date
+      minify_html: true
+  - git-revision-date
   - mkdocstrings:
       default_handler: python
-      handlers:
+  - social
-        python:
+  - tags
-          options:
+  - redirects
-            show_source: true
+  - gh-deploy
 
 nav:
   - Home: index.md
+  - Usage: usage.md
+  - Configuration:
+    - Claude Desktop Config: claude_desktop_config.md
+    - Client Config: client_config.md
   - Getting Started:
-    - Overview: getting-started.md
+    - Overview: getting-started/index.md
     - Installation: getting-started/installation.md
     - Configuration: getting-started/configuration.md
     - Docker Setup: getting-started/docker.md
     - Quick Start: getting-started/quickstart.md
-    - Usage: usage.md
   - API Reference:
     - Overview: api/index.md
-    - Core API: api.md
+    - Core API: api/core-api.md
     - SSE API: api/sse.md
     - Core Functions: api/core.md
   - Tools:
@@ -118,6 +101,7 @@ nav:
     - Interfaces: development/interfaces.md
     - Tool Development: development/tools.md
     - Testing Guide: testing.md
+    - Deployment Guide: deployment.md
   - Architecture: architecture.md
   - Contributing: contributing.md
   - Troubleshooting: troubleshooting.md
@@ -136,6 +120,9 @@ extra:
     property: !ENV GOOGLE_ANALYTICS_KEY
 
 extra_css:
-  - assets/stylesheets/extra.css
+  - stylesheets/extra.css
 
-copyright: Copyright © 2024 Jango Blockchained 
+extra_javascript:
+  - javascripts/extra.js
+
+copyright: Copyright © 2025 jango-blockchained