homeassistant-mcp/docs/contributing.md

layout, title, nav_order

layout	title	nav_order
default	Contributing	5

Contributing Guide 🤝

Thank you for your interest in contributing to the MCP Server project! This guide will help you get started with contributing to the project.

Getting Started

Prerequisites

Before you begin, ensure you have:

• Bun >= 1.0.26
• Node.js >= 18
• Docker (optional, for containerized development)
• A running Home Assistant instance for testing

Development Setup

1. Fork and clone the repository:

   git clone https://github.com/YOUR_USERNAME/advanced-homeassistant-mcp.git
   cd advanced-homeassistant-mcp
   

2. Install dependencies:

   bun install
   

3. Set up your development environment:

   cp .env.example .env
   # Edit .env with your Home Assistant details
   

4. Start the development server:

   bun run dev
   

Development Workflow

Branch Naming Convention

• feature/ - New features
• fix/ - Bug fixes
• docs/ - Documentation updates
• refactor/ - Code refactoring
• test/ - Test improvements

Example:

git checkout -b feature/voice-commands

Commit Messages

We follow the Conventional Commits specification:

type(scope): description

[optional body]

[optional footer]

Types:

• feat: - New features
• fix: - Bug fixes
• docs: - Documentation changes
• style: - Code style changes (formatting, etc.)
• refactor: - Code refactoring
• test: - Test updates
• chore: - Maintenance tasks

Examples:

feat(api): add voice command endpoint
fix(sse): resolve connection timeout issue
docs(readme): update installation instructions

Testing

Run tests before submitting your changes:

# Run all tests
bun test

# Run specific test file
bun test test/api/command.test.ts

# Run tests with coverage
bun test --coverage

Code Style

We use ESLint and Prettier for code formatting:

# Check code style
bun run lint

# Fix code style issues
bun run lint:fix

Pull Request Process

1. Update Documentation

   • Add/update relevant documentation
   • Include inline code comments where necessary
   • Update API documentation if endpoints change

2. Write Tests

   • Add tests for new features
   • Update existing tests if needed
   • Ensure all tests pass

3. Create Pull Request

   • Fill out the PR template
   • Link related issues
   • Provide clear description of changes

4. Code Review

   • Address review comments
   • Keep discussions focused
   • Be patient and respectful

PR Template

## Description
Brief description of the changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## How Has This Been Tested?
Describe your test process

## Checklist
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] Code follows style guidelines
- [ ] All tests passing

Development Guidelines

Code Organization

src/
├── api/          # API endpoints
├── core/         # Core functionality
├── models/       # Data models
├── services/     # Business logic
├── utils/        # Utility functions
└── types/        # TypeScript types

Best Practices

1. Type Safety

   // Use explicit types
   interface CommandRequest {
       command: string;
       parameters?: Record<string, unknown>;
   }
   
   function processCommand(request: CommandRequest): Promise<CommandResponse> {
       // Implementation
   }
   

2. Error Handling

   try {
       await processCommand(request);
   } catch (error) {
       if (error instanceof ValidationError) {
           // Handle validation errors
       }
       throw error;
   }
   

3. Async/Await

   // Prefer async/await over promises
   async function handleRequest() {
       const result = await processData();
       return result;
   }
   

Documentation

API Documentation

Update API documentation when adding/modifying endpoints:

/**
 * Process a voice command
 * @param command - The voice command to process
 * @returns Promise<CommandResult>
 * @throws {ValidationError} If command is invalid
 */
async function processVoiceCommand(command: string): Promise<CommandResult> {
    // Implementation
}

README Updates

Keep the README up to date with:

• New features
• Changed requirements
• Updated examples
• Modified configuration

Getting Help

• Check Discussions
• Review existing Issues

Community Guidelines

We expect all contributors to:

• Be respectful and inclusive
• Focus on constructive feedback
• Help maintain a positive environment
• Follow our code style guidelines
• Write clear documentation
• Test their code thoroughly

License

By contributing, you agree that your contributions will be licensed under the MIT License.