docs: Restructure documentation and enhance configuration
- 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
@@ -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
197
docs/development/environment.md
Normal 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
54
docs/development/index.md
Normal 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)
|
||||
Reference in New Issue
Block a user