MCP Google Analytics 4 Server

# Contributing to MCP GA4 Ultimate Thank you for your interest in contributing! This document provides guidelines for contributing to the project. ## 🎯 How to Contribute ### Reporting Issues - Use the [GitHub Issues](https://github.com/your-org/mcp-ga4-ultimate/issues) tracker - Search existing issues before creating new ones - Provide detailed information including: - Python version - MCP client (Cursor, Claude Desktop, etc.) - Error messages and stack traces - Steps to reproduce ### Feature Requests - Create an issue with the "enhancement" label - Describe the use case and expected behavior - Consider if it fits within the scope of GA4 analytics ### Code Contributions #### Setup Development Environment ```bash # Clone the repository git clone https://github.com/your-org/mcp-ga4-ultimate.git cd mcp-ga4-ultimate # Create virtual environment python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate # Install development dependencies pip install -e .[dev] ``` #### Code Standards - Follow PEP 8 style guidelines - Use type hints for all functions - Write docstrings for public methods - Maintain test coverage above 90% #### Testing ```bash # Run all tests pytest # Run with coverage pytest --cov=mcp_ga4_ultimate --cov-report=html # Run specific test file pytest tests/test_server.py -v ``` #### Code Formatting ```bash # Format code black mcp_ga4_ultimate/ isort mcp_ga4_ultimate/ # Lint code flake8 mcp_ga4_ultimate/ mypy mcp_ga4_ultimate/ ``` ### Pull Request Process 1. **Fork** the repository 2. **Create** a feature branch: `git checkout -b feature/your-feature-name` 3. **Make** your changes with tests 4. **Ensure** all tests pass: `pytest` 5. **Format** your code: `black . && isort .` 6. **Commit** with clear messages 7. **Push** to your fork 8. **Submit** a pull request #### Pull Request Guidelines - Link to relevant issues - Describe changes made - Include test coverage for new features - Update documentation if needed - Ensure CI passes ## 🔧 Development Guidelines ### Adding New Tools When adding new GA4 API tools: 1. **Add the method** to `MCPGoogleAnalytics4Ultimate` class 2. **Follow naming convention**: `action_resource_target` 3. **Include proper error handling** 4. **Add comprehensive docstring** 5. **Write unit tests** 6. **Update documentation** Example: ```python def get_custom_report(self, report_config: Dict[str, Any]) -> Dict[str, Any]: """ Generate custom GA4 report with specified configuration. Args: report_config: Report configuration parameters Returns: Dict containing report data and metadata Raises: ValueError: Invalid configuration parameters GoogleAPIError: API request failed """ # Implementation here ``` ### Testing Guidelines - **Unit tests** for each tool method - **Integration tests** for API interactions - **Mock external dependencies** appropriately - **Test error conditions** and edge cases ### Documentation - Update `docs/tools.md` for new tools - Add usage examples - Update README if needed - Include docstrings in code ## 🏗️ Architecture ### Project Structure ``` mcp-ga4-ultimate/ ├── mcp_ga4_ultimate/ │ ├── __init__.py │ └── server.py # Main MCP server implementation ├── tests/ │ ├── test_server.py # Server tests │ └── conftest.py # Test configuration ├── docs/ │ ├── tools.md # Tool documentation │ └── examples.md # Usage examples ├── pyproject.toml # Package configuration └── README.md ``` ### Design Principles 1. **Comprehensive**: Cover all major GA4 API capabilities 2. **Professional**: Enterprise-grade error handling and logging 3. **Compliant**: GDPR and privacy-first design 4. **Extensible**: Easy to add new tools and features 5. **Tested**: High test coverage and validation ## 📝 Code of Conduct ### Standards - Be respectful and inclusive - Focus on constructive feedback - Welcome newcomers and questions - Share knowledge and help others ### Enforcement Issues will be addressed by maintainers. Serious violations may result in temporary or permanent bans from the project. ## 🤝 Getting Help - **Documentation**: Check the [docs/](docs/) folder - **Issues**: Search existing issues or create new ones - **Discussions**: Use GitHub Discussions for questions - **Email**: Contact maintainers for sensitive issues ## 📋 Release Process Releases follow semantic versioning (SemVer): - **Major** (1.0.0): Breaking changes - **Minor** (1.1.0): New features, backward compatible - **Patch** (1.0.1): Bug fixes Only maintainers can create releases. --- Thank you for contributing to MCP GA4 Ultimate! 🚀