alex/homeassistant-mcp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Restructure documentation and enhance configuration

Browse Source 
- 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
This commit is contained in:
jango-blockchained
2025-02-06 04:11:16 +01:00
parent 1328bd1306
commit 81d6dea7da
11 changed files with 596 additions and 384 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
docs/config/index.md Normal file
View File

@@ -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

106
docs/configuration.md Normal file
View File

@@ -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.

190
docs/development/development.md
View File

@@ -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

197
docs/development/environment.md Normal file
View File

@@ -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)

54
docs/development/index.md Normal file
View File

@@ -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)

30
docs/getting-started.md
View File

@@ -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.

3
docs/requirements.txt
View File

@@ -6,7 +6,6 @@ mkdocs-material>=9.5.3
mkdocs-minify-plugin>=0.7.1
mkdocs-git-revision-date-localized-plugin>=1.2.1
mkdocs-glightbox>=0.3.4
mkdocs-optimize>=0.1.1
mkdocs-git-authors-plugin>=0.7.2
mkdocs-git-committers-plugin>=0.2.3
mkdocs-static-i18n>=1.2.0
@@ -16,8 +15,6 @@ 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
mkdocs-pdf-export-plugin>=0.5.10
mkdocs-with-pdf>=0.9.3
# Code Documentation
mkdocstrings>=0.24.0

146
docs/security.md Normal file
View File

@@ -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/)

42
docs/tools/index.md Normal file
View File

@@ -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

127
docs/tools/tools.md
View File

@@ -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

55
mkdocs.yml
View File

@@ -107,8 +107,8 @@ markdown_extensions:
- attr_list
- md_in_html
- pymdownx.emoji:
emoji_index: !!python/name:materialx.emoji.twemoji
emoji_generator: !!python/name:materialx.emoji.to_svg
emoji_index: !!python/name:material.extensions.emoji.twemoji
emoji_generator: !!python/name:material.extensions.emoji.to_svg
- footnotes
- tables
- def_list
@@ -124,35 +124,14 @@ plugins:
# Advanced Features
- social:
cards: true
cards_color:
fill: "#1e1e2e"
text: "#cdd6f4"
cards: false
- tags
- offline
- optimize
# Version Management
- git-revision-date-localized:
enable_creation_date: true
type: date
# Analytics
- analytics:
provider: google
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!
extra:
# Consent Management
@@ -196,9 +175,13 @@ extra:
- 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
@@ -224,11 +207,14 @@ nav:
- Overview: api/index.md
- Core API: api/core.md
- SSE API: api/sse.md
- API Documentation: api.md
- Usage: usage.md
- Configuration:
- Overview: config/index.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
@@ -247,16 +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: development/test-migration-guide.md
- Testing: testing.md
- Deployment Guide: deployment.md
- Architecture: architecture.md
- Contributing: contributing.md
- Troubleshooting: troubleshooting.md
- Test Migration Guide: development/test-migration-guide.md
- Troubleshooting: troubleshooting.md
- Deployment: deployment.md
- Roadmap: roadmap.md
- Examples:
- Overview: examples/index.md
- Roadmap: roadmap.md
- Overview: examples/index.md