docs: add comprehensive documentation for MCP project
- Create comprehensive documentation structure using MkDocs - Add markdown files for API reference, architecture, getting started, and troubleshooting - Configure GitHub Pages deployment workflow - Include custom Jekyll and MkDocs configurations - Add custom styling and layout for documentation site
This commit is contained in:
jango-blockchained
32
.github/workflows/docs-deploy.yml
vendored
Normal file
32
.github/workflows/docs-deploy.yml
vendored
Normal file
@@ -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
|
||||||
9
.gitignore
vendored
9
.gitignore
vendored
@@ -79,3 +79,12 @@ coverage/
|
|||||||
.bun/
|
.bun/
|
||||||
.cursorconfig
|
.cursorconfig
|
||||||
bun.lockb
|
bun.lockb
|
||||||
|
|
||||||
|
# MkDocs
|
||||||
|
site/
|
||||||
|
.site/
|
||||||
|
|
||||||
|
# Python
|
||||||
|
__pycache__/
|
||||||
|
*.py[cod]
|
||||||
|
*$py.class
|
||||||
10
README.md
10
README.md
@@ -218,3 +218,13 @@ A: Absolutely! We welcome contributions from the community. See the [Contributin
|
|||||||
## License
|
## License
|
||||||
|
|
||||||
This project is licensed under the MIT License. See [LICENSE](LICENSE) for the full license text.
|
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
|
||||||
|
|||||||
13
docs/Gemfile
Normal file
13
docs/Gemfile
Normal file
@@ -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
|
||||||
26
docs/_config.yml
Normal file
26
docs/_config.yml
Normal file
@@ -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
|
||||||
52
docs/_layouts/default.html
Normal file
52
docs/_layouts/default.html
Normal file
@@ -0,0 +1,52 @@
|
|||||||
|
<!DOCTYPE html>
|
||||||
|
<html lang="{{ site.lang | default: " en-US" }}">
|
||||||
|
|
||||||
|
<head>
|
||||||
|
<meta charset="UTF-8">
|
||||||
|
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
||||||
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||||
|
{% seo %}
|
||||||
|
<link rel="stylesheet" href="{{ " /assets/css/style.css?v=" | append: site.github.build_revision | relative_url }}">
|
||||||
|
</head>
|
||||||
|
|
||||||
|
<body>
|
||||||
|
<div class="wrapper">
|
||||||
|
<header>
|
||||||
|
<h1><a href="{{ " /" | absolute_url }}">{{ site.title | default: site.github.repository_name }}</a></h1>
|
||||||
|
|
||||||
|
{% if site.logo %}
|
||||||
|
<img src="{{site.logo | relative_url}}" alt="Logo" />
|
||||||
|
{% endif %}
|
||||||
|
|
||||||
|
<p>{{ site.description | default: site.github.project_tagline }}</p>
|
||||||
|
|
||||||
|
<p class="view"><a href="{{ site.github.repository_url }}">View the Project on GitHub <small>{{
|
||||||
|
site.github.repository_nwo }}</small></a></p>
|
||||||
|
|
||||||
|
<nav class="main-nav">
|
||||||
|
<h3>Documentation</h3>
|
||||||
|
<ul>
|
||||||
|
<li><a href="{{ '/getting-started' | relative_url }}">Getting Started</a></li>
|
||||||
|
<li><a href="{{ '/api' | relative_url }}">API Reference</a></li>
|
||||||
|
<li><a href="{{ '/sse-api' | relative_url }}">SSE API</a></li>
|
||||||
|
<li><a href="{{ '/architecture' | relative_url }}">Architecture</a></li>
|
||||||
|
<li><a href="{{ '/contributing' | relative_url }}">Contributing</a></li>
|
||||||
|
<li><a href="{{ '/troubleshooting' | relative_url }}">Troubleshooting</a></li>
|
||||||
|
</ul>
|
||||||
|
</nav>
|
||||||
|
</header>
|
||||||
|
<section>
|
||||||
|
{{ content }}
|
||||||
|
</section>
|
||||||
|
<footer>
|
||||||
|
{% if site.github.is_project_page %}
|
||||||
|
<p>This project is maintained by <a href="{{ site.github.owner_url }}">{{ site.github.owner_name }}</a></p>
|
||||||
|
{% endif %}
|
||||||
|
<p><small>Hosted on GitHub Pages — Theme by <a
|
||||||
|
href="https://github.com/orderedlist">orderedlist</a></small></p>
|
||||||
|
</footer>
|
||||||
|
</div>
|
||||||
|
<script src="{{ " /assets/js/scale.fix.js" | relative_url }}"></script>
|
||||||
|
</body>
|
||||||
|
|
||||||
|
</html>
|
||||||
54
docs/assets/css/style.scss
Normal file
54
docs/assets/css/style.scss
Normal file
@@ -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;
|
||||||
|
}
|
||||||
5
docs/getting-started/configuration.md
Normal file
5
docs/getting-started/configuration.md
Normal file
@@ -0,0 +1,5 @@
|
|||||||
|
# Configuration
|
||||||
|
|
||||||
|
## Basic Configuration
|
||||||
|
|
||||||
|
## Advanced Settings
|
||||||
124
docs/getting-started/installation.md
Normal file
124
docs/getting-started/installation.md
Normal file
@@ -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)
|
||||||
46
docs/index.md
Normal file
46
docs/index.md
Normal file
@@ -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.
|
||||||
5
docs/usage.md
Normal file
5
docs/usage.md
Normal file
@@ -0,0 +1,5 @@
|
|||||||
|
# Usage Guide
|
||||||
|
|
||||||
|
## Basic Usage
|
||||||
|
|
||||||
|
## Advanced Features
|
||||||
26
mkdocs.yml
Normal file
26
mkdocs.yml
Normal file
@@ -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
|
||||||
Reference in New Issue
Block a user