Add comprehensive documentation for Home Assistant MCP project
- Created detailed getting started guide with installation and configuration instructions - Added main documentation README with structured table of contents - Developed troubleshooting guide with common issues, debugging tips, and FAQ - Included development guide with project structure, setup, and contribution guidelines - Added tools documentation with overview of available management tools
This commit is contained in:
jango-blockchained
60
docs/README.md
Normal file
60
docs/README.md
Normal file
@@ -0,0 +1,60 @@
|
||||
# Home Assistant MCP Documentation
|
||||
|
||||
Welcome to the Home Assistant MCP (Master Control Program) documentation. This documentation provides comprehensive information about setting up, configuring, and using the Home Assistant MCP.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Getting Started](./getting-started.md)
|
||||
- Installation
|
||||
- Configuration
|
||||
- First Steps
|
||||
|
||||
2. [API Reference](./API.md)
|
||||
- REST API Endpoints
|
||||
- Authentication
|
||||
- Error Handling
|
||||
|
||||
3. [SSE (Server-Sent Events)](./SSE_API.md)
|
||||
- Event Subscriptions
|
||||
- Real-time Updates
|
||||
- Connection Management
|
||||
|
||||
4. [Tools](./tools/README.md)
|
||||
- Device Control
|
||||
- Automation Management
|
||||
- Add-on Management
|
||||
- Package Management
|
||||
|
||||
5. [Configuration](./configuration/README.md)
|
||||
- Environment Variables
|
||||
- Security Settings
|
||||
- Performance Tuning
|
||||
|
||||
6. [Development](./development/README.md)
|
||||
- Project Structure
|
||||
- Contributing Guidelines
|
||||
- Testing
|
||||
|
||||
7. [Troubleshooting](./troubleshooting.md)
|
||||
- Common Issues
|
||||
- Debugging
|
||||
- FAQ
|
||||
|
||||
## Quick Links
|
||||
|
||||
- [GitHub Repository](https://github.com/yourusername/homeassistant-mcp)
|
||||
- [Issue Tracker](https://github.com/yourusername/homeassistant-mcp/issues)
|
||||
- [Change Log](./CHANGELOG.md)
|
||||
- [Security Policy](./SECURITY.md)
|
||||
|
||||
## Support
|
||||
|
||||
If you need help or have questions:
|
||||
|
||||
1. Check the [Troubleshooting Guide](./troubleshooting.md)
|
||||
2. Search existing [Issues](https://github.com/yourusername/homeassistant-mcp/issues)
|
||||
3. Create a new issue if your problem isn't already reported
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the MIT License - see the [LICENSE](../LICENSE) file for details.
|
||||
188
docs/development/README.md
Normal file
188
docs/development/README.md
Normal file
@@ -0,0 +1,188 @@
|
||||
# Development Guide
|
||||
|
||||
This guide provides information for developers who want to contribute to or extend the Home Assistant MCP.
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
homeassistant-mcp/
|
||||
├── src/
|
||||
│ ├── 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
|
||||
122
docs/getting-started.md
Normal file
122
docs/getting-started.md
Normal file
@@ -0,0 +1,122 @@
|
||||
# Getting Started with Home Assistant MCP
|
||||
|
||||
This guide will help you get started with the Home Assistant MCP (Master Control Program).
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before you begin, ensure you have:
|
||||
|
||||
1. Node.js (v16 or higher)
|
||||
2. A running Home Assistant instance
|
||||
3. A Home Assistant Long-Lived Access Token
|
||||
|
||||
## Installation
|
||||
|
||||
1. Clone the repository:
|
||||
```bash
|
||||
git clone https://github.com/yourusername/homeassistant-mcp.git
|
||||
cd homeassistant-mcp
|
||||
```
|
||||
|
||||
2. Install dependencies:
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
3. Copy the example environment file:
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
4. Edit the `.env` file with your configuration:
|
||||
```env
|
||||
# Server Configuration
|
||||
PORT=3000
|
||||
NODE_ENV=development
|
||||
|
||||
# Home Assistant Configuration
|
||||
HASS_HOST=http://your-hass-instance:8123
|
||||
HASS_TOKEN=your-long-lived-access-token
|
||||
|
||||
# Security Configuration
|
||||
JWT_SECRET=your-secret-key
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
- `PORT`: The port number for the MCP server (default: 3000)
|
||||
- `NODE_ENV`: The environment mode (development, production, test)
|
||||
- `HASS_HOST`: Your Home Assistant instance URL
|
||||
- `HASS_TOKEN`: Your Home Assistant Long-Lived Access Token
|
||||
- `JWT_SECRET`: Secret key for JWT token generation
|
||||
|
||||
### Development Mode
|
||||
|
||||
For development, you can use:
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
This will start the server in development mode with hot reloading.
|
||||
|
||||
### Production Mode
|
||||
|
||||
For production, build and start the server:
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
npm start
|
||||
```
|
||||
|
||||
## First Steps
|
||||
|
||||
1. Check the server is running:
|
||||
```bash
|
||||
curl http://localhost:3000/api/health
|
||||
```
|
||||
|
||||
2. List available devices:
|
||||
```bash
|
||||
curl -H "Authorization: Bearer your-token" http://localhost:3000/api/tools/devices
|
||||
```
|
||||
|
||||
3. Subscribe to events:
|
||||
```bash
|
||||
curl -H "Authorization: Bearer your-token" http://localhost:3000/api/sse/subscribe?events=state_changed
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Read the [API Documentation](./API.md) for available endpoints
|
||||
- Learn about [Server-Sent Events](./SSE_API.md) for real-time updates
|
||||
- Explore available [Tools](./tools/README.md) for device control
|
||||
- Check the [Configuration Guide](./configuration/README.md) for advanced settings
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If you encounter issues:
|
||||
|
||||
1. Verify your Home Assistant instance is accessible
|
||||
2. Check your environment variables are correctly set
|
||||
3. Look for errors in the server logs
|
||||
4. Consult the [Troubleshooting Guide](./troubleshooting.md)
|
||||
|
||||
## Development
|
||||
|
||||
For development and contributing:
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch
|
||||
3. Follow the [Development Guide](./development/README.md)
|
||||
4. Submit a pull request
|
||||
|
||||
## Support
|
||||
|
||||
Need help? Check out:
|
||||
|
||||
- [GitHub Issues](https://github.com/yourusername/homeassistant-mcp/issues)
|
||||
- [Troubleshooting Guide](./troubleshooting.md)
|
||||
- [FAQ](./troubleshooting.md#faq)
|
||||
127
docs/tools/README.md
Normal file
127
docs/tools/README.md
Normal file
@@ -0,0 +1,127 @@
|
||||
# Home Assistant MCP Tools
|
||||
|
||||
This section documents all available tools in the Home Assistant MCP.
|
||||
|
||||
## Available Tools
|
||||
|
||||
### Device Management
|
||||
|
||||
1. [List Devices](./list-devices.md)
|
||||
- List all available Home Assistant devices
|
||||
- Group devices by domain
|
||||
- Get device states and attributes
|
||||
|
||||
2. [Device Control](./control.md)
|
||||
- Control various device types
|
||||
- Support for lights, switches, covers, climate devices
|
||||
- Domain-specific commands and parameters
|
||||
|
||||
### History and State
|
||||
|
||||
1. [History](./history.md)
|
||||
- Fetch device state history
|
||||
- Filter by time range
|
||||
- Get significant changes
|
||||
|
||||
2. [Scene Management](./scene.md)
|
||||
- List available scenes
|
||||
- Activate scenes
|
||||
- Scene state information
|
||||
|
||||
### Automation
|
||||
|
||||
1. [Automation Management](./automation.md)
|
||||
- List automations
|
||||
- Toggle automation state
|
||||
- Trigger automations manually
|
||||
|
||||
2. [Automation Configuration](./automation-config.md)
|
||||
- Create new automations
|
||||
- Update existing automations
|
||||
- Delete automations
|
||||
- Duplicate automations
|
||||
|
||||
### Add-ons and Packages
|
||||
|
||||
1. [Add-on Management](./addon.md)
|
||||
- List available add-ons
|
||||
- Install/uninstall add-ons
|
||||
- Start/stop/restart add-ons
|
||||
- Get add-on information
|
||||
|
||||
2. [Package Management](./package.md)
|
||||
- Manage HACS packages
|
||||
- Install/update/remove packages
|
||||
- List available packages by category
|
||||
|
||||
### Notifications
|
||||
|
||||
1. [Notify](./notify.md)
|
||||
- Send notifications
|
||||
- Support for multiple notification services
|
||||
- Custom notification data
|
||||
|
||||
### Real-time Events
|
||||
|
||||
1. [Event Subscription](./subscribe-events.md)
|
||||
- Subscribe to Home Assistant events
|
||||
- Monitor specific entities
|
||||
- Domain-based monitoring
|
||||
|
||||
2. [SSE Statistics](./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
|
||||
193
docs/troubleshooting.md
Normal file
193
docs/troubleshooting.md
Normal file
@@ -0,0 +1,193 @@
|
||||
# Troubleshooting Guide
|
||||
|
||||
This guide helps you diagnose and fix common issues with the Home Assistant MCP.
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Connection Issues
|
||||
|
||||
#### Cannot Connect to Home Assistant
|
||||
|
||||
**Symptoms:**
|
||||
- Connection timeout errors
|
||||
- "Failed to connect to Home Assistant" messages
|
||||
- 401 Unauthorized errors
|
||||
|
||||
**Solutions:**
|
||||
1. Verify Home Assistant is running
|
||||
2. Check HASS_HOST environment variable
|
||||
3. Validate HASS_TOKEN is correct
|
||||
4. Ensure network connectivity
|
||||
5. Check firewall settings
|
||||
|
||||
#### SSE Connection Drops
|
||||
|
||||
**Symptoms:**
|
||||
- Frequent disconnections
|
||||
- Missing events
|
||||
- Connection reset errors
|
||||
|
||||
**Solutions:**
|
||||
1. Check network stability
|
||||
2. Increase connection timeout
|
||||
3. Implement reconnection logic
|
||||
4. Monitor server resources
|
||||
|
||||
### Authentication Issues
|
||||
|
||||
#### Invalid Token
|
||||
|
||||
**Symptoms:**
|
||||
- 401 Unauthorized responses
|
||||
- "Invalid token" messages
|
||||
- Authentication failures
|
||||
|
||||
**Solutions:**
|
||||
1. Generate new Long-Lived Access Token
|
||||
2. Check token expiration
|
||||
3. Verify token format
|
||||
4. Update environment variables
|
||||
|
||||
#### Rate Limiting
|
||||
|
||||
**Symptoms:**
|
||||
- 429 Too Many Requests
|
||||
- "Rate limit exceeded" messages
|
||||
|
||||
**Solutions:**
|
||||
1. Implement request throttling
|
||||
2. Adjust rate limit settings
|
||||
3. Cache responses
|
||||
4. Optimize request patterns
|
||||
|
||||
### Tool Issues
|
||||
|
||||
#### Tool Not Found
|
||||
|
||||
**Symptoms:**
|
||||
- "Tool not found" errors
|
||||
- 404 Not Found responses
|
||||
|
||||
**Solutions:**
|
||||
1. Check tool name spelling
|
||||
2. Verify tool registration
|
||||
3. Update tool imports
|
||||
4. Check tool availability
|
||||
|
||||
#### Tool Execution Fails
|
||||
|
||||
**Symptoms:**
|
||||
- Tool execution errors
|
||||
- Unexpected responses
|
||||
- Timeout issues
|
||||
|
||||
**Solutions:**
|
||||
1. Validate input parameters
|
||||
2. Check error logs
|
||||
3. Debug tool implementation
|
||||
4. Verify Home Assistant permissions
|
||||
|
||||
## Debugging
|
||||
|
||||
### Server Logs
|
||||
|
||||
1. Enable debug logging:
|
||||
```env
|
||||
LOG_LEVEL=debug
|
||||
```
|
||||
|
||||
2. Check logs:
|
||||
```bash
|
||||
npm run logs
|
||||
```
|
||||
|
||||
3. Filter logs:
|
||||
```bash
|
||||
npm run logs | grep "error"
|
||||
```
|
||||
|
||||
### Network Debugging
|
||||
|
||||
1. Check API endpoints:
|
||||
```bash
|
||||
curl -v http://localhost:3000/api/health
|
||||
```
|
||||
|
||||
2. Monitor SSE connections:
|
||||
```bash
|
||||
curl -N http://localhost:3000/api/sse/stats
|
||||
```
|
||||
|
||||
3. Test WebSocket:
|
||||
```bash
|
||||
wscat -c ws://localhost:3000
|
||||
```
|
||||
|
||||
### Performance Issues
|
||||
|
||||
1. Monitor memory usage:
|
||||
```bash
|
||||
npm run stats
|
||||
```
|
||||
|
||||
2. Check response times:
|
||||
```bash
|
||||
curl -w "%{time_total}\n" -o /dev/null -s http://localhost:3000/api/health
|
||||
```
|
||||
|
||||
3. Profile code:
|
||||
```bash
|
||||
npm run profile
|
||||
```
|
||||
|
||||
## FAQ
|
||||
|
||||
### Q: How do I reset my configuration?
|
||||
A: Delete `.env` and copy `.env.example` to start fresh.
|
||||
|
||||
### Q: Why are my events delayed?
|
||||
A: Check network latency and server load. Consider adjusting buffer sizes.
|
||||
|
||||
### Q: How do I update my token?
|
||||
A: Generate a new token in Home Assistant and update HASS_TOKEN.
|
||||
|
||||
### Q: Why do I get "Maximum clients reached"?
|
||||
A: Adjust SSE_MAX_CLIENTS in configuration or clean up stale connections.
|
||||
|
||||
## Error Codes
|
||||
|
||||
- `E001`: Connection Error
|
||||
- `E002`: Authentication Error
|
||||
- `E003`: Rate Limit Error
|
||||
- `E004`: Tool Error
|
||||
- `E005`: Configuration Error
|
||||
|
||||
## Support Resources
|
||||
|
||||
1. Documentation
|
||||
- [API Reference](./API.md)
|
||||
- [Configuration Guide](./configuration/README.md)
|
||||
- [Development Guide](./development/README.md)
|
||||
|
||||
2. Community
|
||||
- GitHub Issues
|
||||
- Discussion Forums
|
||||
- Stack Overflow
|
||||
|
||||
3. Tools
|
||||
- Diagnostic Scripts
|
||||
- Testing Tools
|
||||
- Monitoring Tools
|
||||
|
||||
## Still Need Help?
|
||||
|
||||
1. Create a detailed issue:
|
||||
- Error messages
|
||||
- Steps to reproduce
|
||||
- Environment details
|
||||
- Logs
|
||||
|
||||
2. Contact support:
|
||||
- GitHub Issues
|
||||
- Email Support
|
||||
- Community Forums
|
||||
Reference in New Issue
Block a user