# Contributing to Weather-by-Met MCP
Thank you for your interest in contributing to the Malaysian Weather MCP Server! We welcome contributions of all kinds, whether it's code improvements, bug reports, documentation, or new features.
## Code of Conduct
Please read and follow our [Code of Conduct](CODE_OF_CONDUCT.md) to ensure a welcoming and inclusive environment for all contributors.
## Getting Started
### Prerequisites
- Python 3.8 or higher
- MySQL 8.0 or higher
- Git
- pip
### Development Setup
1. **Fork the repository** on GitHub
2. **Clone your fork locally**:
```bash
git clone https://github.com/your-username/weather-by-met.git
cd weather-by-met
```
3. **Create a virtual environment**:
```bash
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
```
4. **Install development dependencies**:
```bash
pip install -r requirements.txt
```
5. **Configure database credentials**:
```bash
cp .env.example .env
nano .env # Update with your database credentials
```
6. **Initialize the database**:
```bash
python init_db.py
```
7. **Run the server locally**:
```bash
python server.py
```
Or run both scheduler and server:
```bash
python run.py
```
## How to Contribute
### Reporting Bugs
Before creating a bug report, please check the [existing issues](https://github.com/zhenkai-dev/weather-by-met/issues) to avoid duplicates.
When submitting a bug report, include:
- **Title**: A clear, descriptive title
- **Environment**: Python version, OS, MySQL version
- **Steps to reproduce**: Detailed steps to reproduce the issue
- **Expected behavior**: What you expected to happen
- **Actual behavior**: What actually happened
- **Error logs**: Relevant error messages or logs
- **Additional context**: Any other context (e.g., recent changes, workarounds)
### Suggesting Features
We love new feature ideas! Please check existing [issues](https://github.com/zhenkai-dev/weather-by-met/issues) first.
When suggesting a feature, include:
- **Title**: A clear, descriptive title
- **Problem**: What problem does this feature solve?
- **Proposed solution**: How should it work?
- **Alternatives**: Any alternative solutions you've considered
- **Use cases**: Specific use cases for this feature
### Pull Requests
We actively welcome pull requests! Here's the process:
1. **Create a new branch** from `master`:
```bash
git checkout -b feature/your-feature-name
```
2. **Make your changes**:
- Follow the existing code style and conventions
- Write clear, descriptive commit messages
- Add comments for complex logic
- Update docstrings for new functions
3. **Write/update tests** (if applicable):
- Test your changes locally
- Ensure existing functionality still works
4. **Update documentation**:
- Update README.md if adding features
- Add docstrings to new functions
- Update relevant .md files
5. **Commit your changes**:
```bash
git add .
git commit -m "Brief description of changes"
```
6. **Push to your fork**:
```bash
git push origin feature/your-feature-name
```
7. **Create a pull request** on GitHub with:
- **Title**: Clear description of the change
- **Description**: What changed and why
- **Related issues**: Link to any related issues
- **Testing**: How you tested the changes
## Code Style Guidelines
### Python Style
We follow [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guidelines:
```python
# Good: Clear variable names, proper spacing
def calculate_forecast_summary(forecast_data: dict) -> str:
"""
Calculate a weather summary from forecast data.
Args:
forecast_data: Dictionary containing weather information
Returns:
String summary of the forecast
"""
summary = forecast_data.get('summary', 'No data')
return summary
# Bad: Unclear variable names
def calc(d):
return d.get('s','N/A')
```
### Docstrings
Use comprehensive docstrings following Google style:
```python
def check_weather_today(location_query: Optional[str] = None) -> str:
"""
Check today's weather forecast for Malaysian locations.
This function retrieves weather data for the current day from the database.
If no location is specified, it may attempt to use the user's location.
Args:
location_query: Optional location name (city, town, state).
Max 100 characters.
Returns:
JSON string with weather data formatted with morning, afternoon,
and night forecasts for requested location(s).
Raises:
DatabaseError: If database connection fails
APIError: If data retrieval from API fails
Examples:
>>> result = check_weather_today("Kuala Lumpur")
>>> print(result) # Returns JSON with weather data
"""
```
### Comments
- Use comments to explain **why**, not what
- Keep comments up-to-date with code changes
- Use TODO/FIXME sparingly and include context
```python
# Good: Explains the reasoning
# Filter old records to prevent re-insertion since the API returns
# a rolling forecast that includes past dates
filtered_records = filter_old_records(api_response)
# Bad: States the obvious
# Set x to 5
x = 5
```
## Project Structure
```
weather-by-met/
├── server.py # MCP server implementation
├── scheduler.py # Automated job scheduler
├── run.py # Process launcher
├── init_db.py # Database initialization
├── requirements.txt # Python dependencies
├── .env.example # Environment template
├── README.md # Main documentation
├── CONTRIBUTING.md # This file
└── LICENSE # MIT License
```
## Testing
Currently, manual testing is performed. To test your changes:
1. **Test the server**:
```bash
python server.py
```
In Claude or your MCP client, verify both tools work:
- `check_weather_today` with and without location
- `check_7day_forecast` with timeframe and specific day modes
2. **Test the scheduler** (if modified):
```bash
python scheduler.py
```
Verify jobs execute on schedule and database updates correctly
3. **Test database operations**:
```bash
python init_db.py # Check schema creation/updates
```
4. **Check logs for errors**:
```bash
tail -f weather_scheduler.log
```
## Commit Message Guidelines
Use clear, descriptive commit messages:
```
# Good
feat: Add support for state-level weather aggregation
fix: Handle missing location data gracefully
docs: Update setup instructions for Railway deployment
refactor: Simplify database connection pooling
# Bad
update stuff
fix bug
wip
asdf
```
Format:
```
<type>: <subject>
<body (optional)>
<footer (optional)>
```
Types: `feat`, `fix`, `docs`, `refactor`, `test`, `perf`, `chore`, `ci`
## Review Process
1. A maintainer will review your PR
2. Address any requested changes
3. Once approved, your PR will be merged
4. Your contribution will be acknowledged!
## Questions?
Feel free to:
- Open a GitHub issue with your question
- Check existing documentation
- Join discussions in the repository
## License
By contributing, you agree that your contributions will be licensed under the MIT License - see the LICENSE file for details.
Thank you for making Weather-by-Met better! 🙏
