CONTRIBUTING.md•4.15 kB
# Contributing to GCP MCP Server
Thank you for your interest in contributing to the GCP MCP Server! This guide will help you get started.
## 🚀 Quick Start
1. **Fork and Clone**
```bash
git clone https://github.com/JayRajGoyal/gcp-mcp.git
cd gcp-mcp
```
2. **Set up Development Environment**
```bash
python3.11 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -e ".[dev]"
```
3. **Run Tests**
```bash
python test_setup.py
pytest tests/
```
## 🛠️ Development Guidelines
### Code Quality
- **Python 3.10+** required (MCP dependency)
- **Type hints** required for all public APIs
- **Docstrings** required for all public functions/classes
- **Error handling** must be comprehensive
- **Tests** required for all new features
### Code Style
```bash
# Format code
black gcp_mcp/
isort gcp_mcp/
# Type checking
mypy gcp_mcp/
# Linting
flake8 gcp_mcp/
```
### Testing
- **Unit tests** for all tool functions
- **Integration tests** for GCP API interactions
- **MCP protocol tests** for server functionality
- **Error handling tests** for edge cases
### Documentation
- Update README.md for user-facing changes
- Add docstrings for new functions/classes
- Update examples/ for new tools
- Add troubleshooting info for common issues
## 🔧 Adding New Tools
1. **Create tool class** in `gcp_mcp/tools/`
2. **Add comprehensive tests** in `tests/`
3. **Update documentation** and examples
4. **Follow error handling patterns**
Example tool structure:
```python
class NewGCPTool:
async def get_tools(self) -> List[Tool]:
"""Return MCP tool definitions."""
pass
async def handle_tool_call(self, name: str, args: Dict[str, Any]) -> List[TextContent]:
"""Handle tool execution with proper error handling."""
pass
```
## 🐛 Bug Reports
**Before submitting:**
- [ ] Search existing issues
- [ ] Try latest version
- [ ] Check troubleshooting guide
**Include:**
- GCP MCP Server version
- Python version
- Operating system
- MCP client (Claude Code, etc.)
- Complete error messages
- Steps to reproduce
- Expected vs actual behavior
## ✨ Feature Requests
**Consider:**
- Is this a common use case?
- Does it fit the project scope?
- Can it be implemented securely?
- Would it benefit multiple users?
**Include:**
- Clear description of the need
- Proposed solution or API
- Example usage scenarios
- Willingness to contribute implementation
## 🔒 Security
**Never commit:**
- GCP service account keys
- API keys or tokens
- Personal project IDs
- Production credentials
**Report security issues:**
- Email: [security-email-here]
- Use GitHub Security Advisories
- Include detailed reproduction steps
## 📋 Pull Request Process
1. **Branch naming:**
- `feature/add-cloud-sql-tools`
- `fix/logging-filter-bug`
- `docs/improve-readme`
2. **Commit messages:**
```
feat: add Cloud SQL connectivity tools
- Add connection testing functionality
- Support for MySQL and PostgreSQL
- Include connection pooling options
```
3. **PR Requirements:**
- [ ] Tests pass (`python test_setup.py`)
- [ ] Code formatted (`black`, `isort`)
- [ ] Type checking passes (`mypy`)
- [ ] Documentation updated
- [ ] No credentials in code/config
- [ ] Backward compatibility maintained
4. **Review Process:**
- Maintainer review required
- CI checks must pass
- Documentation review for user-facing changes
## 🏷️ Release Process
1. **Version bumping** (maintainers only)
2. **Changelog updates**
3. **Tag creation**
4. **PyPI publishing**
5. **Docker image updates**
## 💬 Community
- **Discussions:** Use GitHub Discussions for questions
- **Issues:** Use GitHub Issues for bugs/features
- **Discord:** [Link to Discord if available]
## 📄 License
By contributing, you agree that your contributions will be licensed under the MIT License.
## 🙏 Recognition
Contributors will be acknowledged in:
- README.md contributors section
- Release notes
- Annual contributor appreciation
---
**Questions?** Open a Discussion or reach out to maintainers!