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
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
|
||||
Reference in New Issue
Block a user