docx-mcp

# Contributing to docx-mcp Thank you for your interest in contributing to docx-mcp! This document provides guidelines and instructions for contributing to the project. ## Code of Conduct We are committed to providing a welcoming and inspiring community for all. Please read and adhere to our Code of Conduct in all interactions. ## Getting Started ### Prerequisites - Python 3.10 or higher - pip and virtual environment support ### Development Setup 1. Clone the repository: ```bash git clone https://github.com/rajesh/docx-mcp.git cd docx-mcp ``` 2. Create and activate a virtual environment: ```bash python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate ``` 3. Install the project in development mode with dependencies: ```bash pip install -e ".[dev]" ``` ### Running Tests Run the test suite: ```bash python -m pytest tests/ -v ``` Run tests with coverage: ```bash python -m pytest tests/ --cov=src/docx_mcp --cov-report=html ``` ### Code Quality The project uses several tools to maintain code quality: **Formatting with Black:** ```bash black src/docx_mcp tests ``` **Linting with Ruff:** ```bash ruff check src/docx_mcp --fix ``` **Type checking with mypy:** ```bash mypy src/docx_mcp ``` Run all checks: ```bash black src/docx_mcp tests && ruff check src/docx_mcp --fix && mypy src/docx_mcp && python -m pytest tests/ ``` ## Making Changes ### Branch Naming Use descriptive branch names: - `feature/description` - for new features - `fix/description` - for bug fixes - `docs/description` - for documentation changes - `refactor/description` - for refactoring work ### Commit Messages Write clear, descriptive commit messages: - Use the imperative mood ("add feature" not "added feature") - Keep the first line under 50 characters - Reference issues and pull requests when relevant ### Pull Request Process 1. Create a feature branch from `main` 2. Make your changes with clear, descriptive commits 3. Ensure all tests pass: `python -m pytest tests/ -v` 4. Ensure code quality checks pass 5. Create a pull request with: - Clear title describing the change - Description of what changed and why - Reference to any related issues 6. Address any review feedback 7. Once approved, your PR will be merged ## Adding New Features When adding new MCP tools: 1. Create the tool function in `src/docx_mcp/server.py` with the `@app.tool()` decorator 2. Add comprehensive docstrings with Args and Returns sections 3. Include proper error handling with custom exceptions 4. Add logging for debugging 5. Create tests in `tests/test_server.py` 6. Update the CHANGELOG.md with the new feature ## Testing Guidelines - Write tests for all new functionality - Ensure existing tests continue to pass - Aim for >80% code coverage - Test both happy paths and error cases - Use descriptive test names ## Documentation - Update README.md if your changes affect user-facing functionality - Add docstrings to all functions and classes - Use type hints for all parameters and return values - Update CHANGELOG.md for user-facing changes ## Security Considerations - The project includes path validation to prevent directory traversal - Always validate file paths before processing - Be cautious with XML parsing and external data - Report security issues privately (do not open public issues) ## License By contributing to docx-mcp, you agree that your contributions will be licensed under the MIT License. ## Questions? Feel free to open an issue for questions or discussions about the project. Thank you for contributing!