AnyDocs MCP Server

# Contributing to AnyDocs MCP Server Thank you for your interest in contributing to the AnyDocs MCP Server project! We welcome contributions from the community and are grateful for your support in making this project better. ## Table of Contents - [Code of Conduct](#code-of-conduct) - [Getting Started](#getting-started) - [Development Setup](#development-setup) - [Contributing Guidelines](#contributing-guidelines) - [Pull Request Process](#pull-request-process) - [Issue Reporting](#issue-reporting) - [Development Workflow](#development-workflow) - [Code Style and Standards](#code-style-and-standards) - [Testing](#testing) - [Documentation](#documentation) - [Community](#community) ## Code of Conduct This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers. ### Our Pledge We pledge to make participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. ### Our Standards **Positive behavior includes:** - Using welcoming and inclusive language - Being respectful of differing viewpoints and experiences - Gracefully accepting constructive criticism - Focusing on what is best for the community - Showing empathy towards other community members **Unacceptable behavior includes:** - The use of sexualized language or imagery - Trolling, insulting/derogatory comments, and personal or political attacks - Public or private harassment - Publishing others' private information without explicit permission - Other conduct which could reasonably be considered inappropriate in a professional setting ## Getting Started ### Prerequisites Before you begin, ensure you have the following installed: - **Python 3.11+**: The project requires Python 3.11 or higher - **Git**: For version control - **Docker**: For containerized development (optional but recommended) - **Make**: For running development commands (optional) ### Quick Start 1. **Fork the repository** on GitHub 2. **Clone your fork** locally: ```bash git clone https://github.com/YOUR_USERNAME/anydocs-mcp-server.git cd anydocs-mcp-server ``` 3. **Set up the development environment**: ```bash python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate pip install -r requirements.txt pip install -r requirements-dev.txt ``` 4. **Run the setup script**: ```bash python scripts/setup.py --dev ``` 5. **Start the development server**: ```bash python start.py --mode hybrid --debug ``` ## Development Setup ### Environment Setup 1. **Create a virtual environment**: ```bash python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate ``` 2. **Install dependencies**: ```bash pip install -r requirements.txt pip install -r requirements-dev.txt ``` 3. **Copy environment configuration**: ```bash cp .env.example .env cp config.yaml.example config.yaml ``` 4. **Initialize the database**: ```bash python start.py --init-db ``` ### Docker Development For a containerized development environment: ```bash # Build and start development containers docker-compose -f docker-compose.dev.yml up --build # Run commands in the container docker-compose -f docker-compose.dev.yml exec anydocs-mcp-dev bash ``` ### Using Make Commands If you have Make installed, you can use the provided Makefile: ```bash # Setup development environment make setup-dev # Run tests make test # Run linting make lint # Format code make format # Start development server make dev ``` ## Contributing Guidelines ### Types of Contributions We welcome various types of contributions: 1. **Bug Reports**: Help us identify and fix issues 2. **Feature Requests**: Suggest new features or improvements 3. **Code Contributions**: Implement bug fixes or new features 4. **Documentation**: Improve or add documentation 5. **Testing**: Add or improve tests 6. **Performance**: Optimize performance and efficiency 7. **Security**: Identify and fix security vulnerabilities 8. **Translations**: Add support for additional languages ### Contribution Areas - **Core MCP Server**: Enhance the main server functionality - **Documentation Adapters**: Add support for new platforms - **Authentication**: Improve security and auth mechanisms - **Web Interface**: Enhance the management dashboard - **Performance**: Optimize speed and resource usage - **Testing**: Increase test coverage and quality - **Documentation**: Improve user and developer guides - **DevOps**: Enhance deployment and monitoring ## Pull Request Process ### Before Submitting 1. **Check existing issues** to avoid duplicates 2. **Create an issue** for significant changes 3. **Fork the repository** and create a feature branch 4. **Follow coding standards** and write tests 5. **Update documentation** as needed 6. **Test your changes** thoroughly ### Submitting a Pull Request 1. **Create a feature branch**: ```bash git checkout -b feature/your-feature-name ``` 2. **Make your changes** following our coding standards 3. **Add tests** for your changes: ```bash # Run tests to ensure they pass pytest tests/ ``` 4. **Update documentation** if needed 5. **Commit your changes**: ```bash git add . git commit -m "feat: add your feature description" ``` 6. **Push to your fork**: ```bash git push origin feature/your-feature-name ``` 7. **Create a Pull Request** on GitHub ### Pull Request Template When creating a pull request, please include: ```markdown ## Description Brief description of the changes ## Type of Change - [ ] Bug fix (non-breaking change which fixes an issue) - [ ] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) - [ ] Documentation update ## Testing - [ ] Tests pass locally - [ ] New tests added for new functionality - [ ] Manual testing completed ## Checklist - [ ] Code follows the project's coding standards - [ ] Self-review of the code completed - [ ] Documentation updated - [ ] No new warnings introduced ``` ### Review Process 1. **Automated Checks**: CI/CD pipeline runs tests and checks 2. **Code Review**: Maintainers review the code 3. **Feedback**: Address any feedback or requested changes 4. **Approval**: Once approved, the PR will be merged 5. **Cleanup**: Delete the feature branch after merge ## Issue Reporting ### Bug Reports When reporting bugs, please include: 1. **Clear title** describing the issue 2. **Steps to reproduce** the bug 3. **Expected behavior** vs actual behavior 4. **Environment details** (OS, Python version, etc.) 5. **Error messages** or logs if available 6. **Screenshots** if applicable ### Feature Requests For feature requests, please provide: 1. **Clear description** of the feature 2. **Use case** and motivation 3. **Proposed solution** if you have one 4. **Alternative solutions** considered 5. **Additional context** or examples ### Issue Templates We provide issue templates to help you structure your reports: - **Bug Report Template** - **Feature Request Template** - **Documentation Issue Template** - **Performance Issue Template** - **Security Issue Template** ## Development Workflow ### Git Workflow We follow a Git workflow based on feature branches: 1. **Main Branch**: `main` - stable, production-ready code 2. **Development Branch**: `develop` - integration branch for features 3. **Feature Branches**: `feature/feature-name` - individual features 4. **Hotfix Branches**: `hotfix/issue-description` - urgent fixes 5. **Release Branches**: `release/version-number` - release preparation ### Commit Messages We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification: ``` type(scope): description [optional body] [optional footer] ``` **Types:** - `feat`: New feature - `fix`: Bug fix - `docs`: Documentation changes - `style`: Code style changes (formatting, etc.) - `refactor`: Code refactoring - `test`: Adding or updating tests - `chore`: Maintenance tasks - `perf`: Performance improvements - `ci`: CI/CD changes - `build`: Build system changes **Examples:** ``` feat(auth): add OAuth2 authentication support fix(server): resolve memory leak in document processing docs(readme): update installation instructions test(adapters): add unit tests for GitBook adapter ``` ### Branch Naming - `feature/feature-name`: New features - `fix/bug-description`: Bug fixes - `docs/documentation-update`: Documentation updates - `refactor/component-name`: Code refactoring - `test/test-description`: Test additions/updates ## Code Style and Standards ### Python Code Style We follow PEP 8 and use automated tools to enforce consistency: - **Formatter**: Black - **Linter**: Flake8 - **Type Checker**: MyPy - **Import Sorter**: isort ### Code Quality Tools Run these commands before submitting: ```bash # Format code black src/ tests/ # Sort imports isort src/ tests/ # Lint code flake8 src/ tests/ # Type checking mypy src/ # Run all quality checks make lint ``` ### Code Standards 1. **Type Hints**: Use type hints for all functions and methods 2. **Docstrings**: Document all public functions, classes, and modules 3. **Error Handling**: Implement proper error handling and logging 4. **Security**: Follow security best practices 5. **Performance**: Consider performance implications 6. **Testing**: Write tests for new functionality ### Documentation Standards 1. **Docstrings**: Use Google-style docstrings 2. **Comments**: Write clear, concise comments 3. **README**: Keep README files up to date 4. **API Documentation**: Document all API endpoints 5. **Examples**: Provide usage examples ## Testing ### Test Structure ``` tests/ ├── unit/ # Unit tests ├── integration/ # Integration tests ├── e2e/ # End-to-end tests ├── fixtures/ # Test fixtures └── conftest.py # Pytest configuration ``` ### Running Tests ```bash # Run all tests pytest # Run with coverage pytest --cov=src # Run specific test file pytest tests/unit/test_server.py # Run tests with specific marker pytest -m "not slow" ``` ### Test Guidelines 1. **Write tests** for all new functionality 2. **Maintain coverage** above 80% 3. **Use fixtures** for common test data 4. **Mock external dependencies** appropriately 5. **Test edge cases** and error conditions 6. **Keep tests fast** and independent ### Test Categories - **Unit Tests**: Test individual components in isolation - **Integration Tests**: Test component interactions - **End-to-End Tests**: Test complete user workflows - **Performance Tests**: Test performance characteristics - **Security Tests**: Test security measures ## Documentation ### Documentation Types 1. **User Documentation**: How to use the software 2. **Developer Documentation**: How to contribute and extend 3. **API Documentation**: API reference and examples 4. **Architecture Documentation**: System design and architecture 5. **Deployment Documentation**: Installation and deployment guides ### Documentation Tools - **Sphinx**: For comprehensive documentation - **MkDocs**: For user-friendly documentation sites - **OpenAPI/Swagger**: For API documentation - **Mermaid**: For diagrams and flowcharts ### Writing Guidelines 1. **Clear and Concise**: Write in plain English 2. **Examples**: Provide practical examples 3. **Structure**: Use consistent structure and formatting 4. **Updates**: Keep documentation current with code changes 5. **Accessibility**: Ensure documentation is accessible ## Community ### Communication Channels - **GitHub Issues**: Bug reports and feature requests - **GitHub Discussions**: General discussions and Q&A - **Pull Requests**: Code review and collaboration - **Documentation**: Comprehensive guides and references ### Getting Help 1. **Check Documentation**: Start with the README and docs 2. **Search Issues**: Look for existing solutions 3. **Ask Questions**: Use GitHub Discussions 4. **Join Community**: Participate in discussions ### Community Guidelines 1. **Be Respectful**: Treat everyone with respect 2. **Be Helpful**: Help others when you can 3. **Be Patient**: Remember that everyone is learning 4. **Be Constructive**: Provide constructive feedback 5. **Be Inclusive**: Welcome newcomers and diverse perspectives ## Recognition ### Contributors We recognize and appreciate all contributors: - **Code Contributors**: Listed in the repository contributors - **Documentation Contributors**: Acknowledged in documentation - **Community Contributors**: Recognized in community discussions - **Special Recognition**: Outstanding contributions highlighted ### Contribution Levels - **First-time Contributors**: Welcome and guidance provided - **Regular Contributors**: Ongoing collaboration and support - **Core Contributors**: Trusted with additional responsibilities - **Maintainers**: Project leadership and decision-making ## License By contributing to this project, you agree that your contributions will be licensed under the same license as the project (MIT License). ## Questions? If you have any questions about contributing, please: 1. Check this contributing guide 2. Search existing issues and discussions 3. Create a new discussion or issue 4. Reach out to the maintainers Thank you for contributing to AnyDocs MCP Server! 🚀