diff --git a/.github/workflows/docs-deploy.yml b/.github/workflows/docs-deploy.yml new file mode 100644 index 0000000..c2ec3dc --- /dev/null +++ b/.github/workflows/docs-deploy.yml @@ -0,0 +1,32 @@ +name: Deploy Documentation + +on: + push: + branches: + - main + paths: + - 'docs/**' + - 'mkdocs.yml' + +permissions: + contents: write + +jobs: + deploy-docs: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: 3.x + + - name: Install dependencies + run: | + pip install mkdocs-material + pip install mkdocs + + - name: Deploy documentation + run: mkdocs gh-deploy --force \ No newline at end of file diff --git a/.gitignore b/.gitignore index 89c3839..cbc5353 100644 --- a/.gitignore +++ b/.gitignore @@ -78,4 +78,13 @@ coverage/ .bun/ .cursorconfig -bun.lockb \ No newline at end of file +bun.lockb + +# MkDocs +site/ +.site/ + +# Python +__pycache__/ +*.py[cod] +*$py.class \ No newline at end of file diff --git a/README.md b/README.md index c597d75..12bea8a 100644 --- a/README.md +++ b/README.md @@ -218,3 +218,13 @@ A: Absolutely! We welcome contributions from the community. See the [Contributin ## License This project is licensed under the MIT License. See [LICENSE](LICENSE) for the full license text. + +## Documentation + +Full documentation is available at: https://yourusername.github.io/your-repo-name/ + +## Quick Start + +## Installation + +## Usage diff --git a/docs/Gemfile b/docs/Gemfile new file mode 100644 index 0000000..50ae9ef --- /dev/null +++ b/docs/Gemfile @@ -0,0 +1,13 @@ +source "https://rubygems.org" + +gem "github-pages", group: :jekyll_plugins +gem "jekyll-theme-minimal" +gem "jekyll-relative-links" +gem "jekyll-seo-tag" + +# Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem +# and associated library. +platforms :mingw, :x64_mingw, :mswin, :jruby do + gem "tzinfo", ">= 1" + gem "tzinfo-data" +end \ No newline at end of file diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 0000000..df4eee9 --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,26 @@ +title: Model Context Protocol (MCP) +description: A bridge between Home Assistant and Language Learning Models +theme: jekyll-theme-minimal +markdown: kramdown +plugins: + - jekyll-relative-links + - jekyll-seo-tag + +# Enable relative links +relative_links: + enabled: true + collections: true + +# Navigation structure +header_pages: + - index.md + - getting-started.md + - api.md + - contributing.md + +# Exclude files from processing +exclude: + - Gemfile + - Gemfile.lock + - node_modules + - vendor \ No newline at end of file diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html new file mode 100644 index 0000000..e350c93 --- /dev/null +++ b/docs/_layouts/default.html @@ -0,0 +1,52 @@ + + + + + + + + {% seo %} + + + + +
+
+

{{ site.title | default: site.github.repository_name }}

+ + {% if site.logo %} + Logo + {% endif %} + +

{{ site.description | default: site.github.project_tagline }}

+ +

View the Project on GitHub {{ + site.github.repository_nwo }}

+ + +
+
+ {{ content }} +
+ +
+ + + + \ No newline at end of file diff --git a/docs/API.md b/docs/api.md similarity index 100% rename from docs/API.md rename to docs/api.md diff --git a/docs/ARCHITECTURE.md b/docs/architecture.md similarity index 100% rename from docs/ARCHITECTURE.md rename to docs/architecture.md diff --git a/docs/assets/css/style.scss b/docs/assets/css/style.scss new file mode 100644 index 0000000..bd19b34 --- /dev/null +++ b/docs/assets/css/style.scss @@ -0,0 +1,54 @@ +@import "{{ site.theme }}"; + +// Custom styles +.main-nav { + margin-top: 20px; + + ul { + list-style: none; + padding: 0; + margin: 0; + } + + li { + margin-bottom: 8px; + } + + a { + color: #267CB9; + text-decoration: none; + + &:hover { + text-decoration: underline; + } + } +} + +h1, +h2, +h3 { + color: #333; +} + +code { + background-color: #f8f8f8; + border: 1px solid #ddd; + border-radius: 3px; + padding: 2px 5px; +} + +pre { + background-color: #f8f8f8; + border: 1px solid #ddd; + border-radius: 3px; + padding: 10px; + overflow-x: auto; +} + +.wrapper { + max-width: 960px; +} + +section { + max-width: 700px; +} \ No newline at end of file diff --git a/docs/CONTRIBUTING.md b/docs/contributing.md similarity index 100% rename from docs/CONTRIBUTING.md rename to docs/contributing.md diff --git a/docs/GETTING_STARTED.md b/docs/getting-started.md similarity index 100% rename from docs/GETTING_STARTED.md rename to docs/getting-started.md diff --git a/docs/getting-started/configuration.md b/docs/getting-started/configuration.md new file mode 100644 index 0000000..42386c3 --- /dev/null +++ b/docs/getting-started/configuration.md @@ -0,0 +1,5 @@ +# Configuration + +## Basic Configuration + +## Advanced Settings \ No newline at end of file diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md new file mode 100644 index 0000000..c339bcf --- /dev/null +++ b/docs/getting-started/installation.md @@ -0,0 +1,124 @@ +# Installation Guide + +## Prerequisites + +### System Requirements +- **Operating System:** Linux, macOS, or Windows (Docker recommended) +- **Runtime:** Bun v1.0.26 or higher +- **Home Assistant:** v2023.11 or higher +- **Minimum Hardware:** + - 2 CPU cores + - 2GB RAM + - 10GB free disk space + +### Software Dependencies +- Bun runtime +- Docker (optional, recommended for deployment) +- Git +- Node.js (for some development tasks) + +## Installation Methods + +### 1. Basic Setup + +#### Install Bun +```bash +curl -fsSL https://bun.sh/install | bash +``` + +#### Clone Repository +```bash +git clone https://github.com/jango-blockchained/homeassistant-mcp.git +cd homeassistant-mcp +``` + +#### Install Dependencies +```bash +bun install +``` + +#### Configure Environment +1. Copy environment template +```bash +cp .env.example .env +``` +2. Edit `.env` file with your Home Assistant configuration + - Set `HASS_HOST` + - Configure authentication tokens + - Adjust other settings as needed + +#### Build and Start +```bash +bun run build +bun start +``` + +### 2. Docker Setup (Recommended) + +#### Prerequisites +- Docker +- Docker Compose + +#### Deployment Steps +```bash +# Clone repository +git clone https://github.com/jango-blockchained/homeassistant-mcp.git +cd homeassistant-mcp + +# Configure environment +cp .env.example .env +# Edit .env file with your settings + +# Deploy with Docker Compose +docker compose up -d +``` + +### 3. Home Assistant Add-on (Coming Soon) +We're working on a direct Home Assistant add-on for even easier installation. + +## Verification + +### Check Installation +- Web Interface: [http://localhost:3000](http://localhost:3000) +- Logs: `docker compose logs` or check `logs/` directory + +### Troubleshooting +- Ensure all environment variables are correctly set +- Check network connectivity to Home Assistant +- Verify authentication tokens + +## Updating + +### Basic Setup +```bash +git pull +bun install +bun run build +bun start +``` + +### Docker +```bash +git pull +docker compose up -d --build +``` + +## Uninstallation + +### Basic Setup +```bash +cd homeassistant-mcp +bun stop # Stop the application +rm -rf node_modules dist +``` + +### Docker +```bash +docker compose down +docker rmi homeassistant-mcp # Remove image +``` + +## Next Steps +- [Configuration Guide](configuration.md) +- [Usage Instructions](../usage.md) +- [Troubleshooting](../troubleshooting.md) \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..e85097d --- /dev/null +++ b/docs/index.md @@ -0,0 +1,46 @@ +--- +layout: default +title: Home +nav_order: 1 +--- + +# Model Context Protocol (MCP) Server + +## Overview + +The Model Context Protocol (MCP) Server is a cutting-edge bridge between Home Assistant and Language Learning Models (LLMs), designed to revolutionize smart home automation and control. + +## Key Features + +### 🏠 Smart Home Integration +- Natural language control of smart devices +- Real-time device state monitoring +- Advanced automation capabilities + +### 🤖 LLM Powered Interactions +- Intuitive voice and text-based commands +- Context-aware device management +- Intelligent automation suggestions + +### 🔒 Security & Performance +- Token-based authentication +- High-performance Bun runtime +- Secure, real-time communication protocols + +## Documentation + +- [Getting Started](getting-started.md) - Installation and basic setup +- [API Reference](api.md) - Complete API documentation +- [SSE API](sse-api.md) - Server-Sent Events API documentation +- [Architecture](architecture.md) - System architecture and design +- [Contributing](contributing.md) - How to contribute to the project +- [Troubleshooting](troubleshooting.md) - Common issues and solutions + +## Community and Support + +- [GitHub Issues](https://github.com/jango-blockchained/homeassistant-mcp/issues) - Report bugs and request features +- [GitHub Discussions](https://github.com/jango-blockchained/homeassistant-mcp/discussions) - Ask questions and share ideas + +## License + +Licensed under the MIT License. See [LICENSE](https://github.com/jango-blockchained/homeassistant-mcp/blob/main/LICENSE) for details. \ No newline at end of file diff --git a/docs/SSE_API.md b/docs/sse-api.md similarity index 100% rename from docs/SSE_API.md rename to docs/sse-api.md diff --git a/docs/TROUBLESHOOTING.md b/docs/troubleshooting.md similarity index 100% rename from docs/TROUBLESHOOTING.md rename to docs/troubleshooting.md diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..86e9dbd --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,5 @@ +# Usage Guide + +## Basic Usage + +## Advanced Features \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..2e98535 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,26 @@ +site_name: Project Documentation +site_url: https://yourusername.github.io/your-repo-name/ +repo_url: https://github.com/yourusername/your-repo-name + +theme: + name: material + features: + - navigation.tabs + - navigation.sections + - toc.integrate + - search.suggest + - search.highlight + +markdown_extensions: + - pymdownx.highlight + - pymdownx.superfences + - admonition + - pymdownx.details + +nav: + - Home: index.md + - Getting Started: + - Installation: getting-started/installation.md + - Configuration: getting-started/configuration.md + - Usage: usage.md + - Contributing: contributing.md \ No newline at end of file