Thank you for your interest in contributing to the Flight Control MCP Server! This document provides guidelines and information for contributors.
- Code of Conduct
- Getting Started
- Development Setup
- Making Changes
- Testing
- Code Style
- Submitting Changes
- Reporting Issues
- Development Workflow
- Getting Help
This project follows the standard open source code of conduct. Please be respectful, inclusive, and constructive in all interactions.
This project requires all contributors to sign off on their commits using the Developer Certificate of Origin. This is a lightweight way to certify that you wrote or otherwise have the right to pass on the code you are contributing.
By signing off on your commits, you are certifying that:
- You wrote the code yourself, OR
- You have the right to pass on the code as open source, OR
- Someone who had that right passed it on to you
All commits must be signed off. Add the -s flag to your commit:
git commit -s -m "Add new feature for device filtering"This automatically adds a "Signed-off-by" line to your commit message:
Add new feature for device filtering
Signed-off-by: Your Name <your.email@example.com>
If you forget to sign off commits, you can fix them:
# For the last commit
git commit --amend --signoff
# For multiple commits (interactive rebase)
git rebase -i HEAD~3 # Replace 3 with number of commits
# In the editor, change 'pick' to 'edit' for commits needing sign-off
# For each commit:
git commit --amend --signoff
git rebase --continueDCO provides legal clarity for the project and its users by ensuring:
- Clear provenance of contributions
- Protection against copyright issues
- Compliance with open source licensing
- Peace of mind for enterprise users
- Python 3.9+ (recommended: 3.11 or 3.12)
- Git for version control
- Docker/Podman for container testing (optional)
- Flight Control instance for live testing (optional)
The Flight Control MCP Server provides:
- Read-only access to Flight Control resources (devices, fleets, events, etc.)
- Remote command execution on devices via console commands
- Integration with Model Context Protocol (MCP) for AI assistants
Key components:
main.py- MCP server entry point and tool definitionsresource_queries.py- Flight Control API client with authenticationcli.py- CLI management and console command execution- Test files for comprehensive testing strategy
# Fork the repository on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/flightctl-mcp.git
cd flightctl-mcp
# Add upstream remote
git remote add upstream https://github.com/ORIGINAL_OWNER/flightctl-mcp.git# Install dependencies
pip install -r requirements.txt
# Install development tools
make install-dev
# Or manually:
pip install pytest pytest-mock pytest-cov black flake8 mypy# Run smoke tests
make smoke-test
# Run unit tests
make test-unit
# Check code formatting
make lintFor live testing (not required for most contributions):
# If you have a Flight Control instance
flightctl login
# Test against live instance
python test_live_instance.py# Create a feature branch
git checkout -b feature/your-feature-name
# Or for bug fixes
git checkout -b fix/issue-descriptionWe welcome:
- 🐛 Bug fixes - Fix issues in existing functionality
- ✨ New features - Add new MCP tools or capabilities
- 📚 Documentation - Improve docs, examples, comments
- 🧪 Tests - Add or improve test coverage
- 🔧 Infrastructure - CI/CD, build tools, development experience
- 🎨 Code quality - Refactoring, performance improvements
All contributions must include appropriate tests! See TESTING.md and CI-TESTING.md for detailed testing information.
# Add a test that reproduces the bug (should fail initially)
# Fix the bug
# Verify the test now passes
make test-unit# Add unit tests for new functionality
# Add integration tests if needed
# Update documentation
make test# Run all local tests
make test
# Test code formatting
make lint
# Test against live Flight Control (if available)
python test_live_instance.py- Unit Tests (required) - Fast tests with mocked dependencies
- Integration Tests (recommended) - Component interaction tests
- Live Tests (optional) - Manual testing against real Flight Control
We follow PEP 8 with these specific requirements:
# Format code with Black
black --line-length=120 *.py
# Check linting with flake8
flake8 *.py --max-line-length=120 --ignore=E501,W503
# Type checking with mypy
mypy *.py --ignore-missing-imports- Line length: 120 characters maximum
- Type hints: Use type hints for function signatures
- Docstrings: Document all public functions and classes
- Error handling: Use proper exception handling with typed exceptions
- Logging: Use the project's logging framework
- Security: Follow secure coding practices
def query_devices(
self,
label_selector: Optional[str] = None,
field_selector: Optional[str] = None,
limit: Optional[int] = None
) -> List[Dict[str, Any]]:
"""
Query Flight Control devices with optional filtering.
Args:
label_selector: Kubernetes label selector for filtering
field_selector: Kubernetes field selector for filtering
limit: Maximum number of results to return
Returns:
List of device objects from the Flight Control API
Raises:
APIError: If the API request fails
AuthenticationError: If authentication fails
"""
# Implementation here...-
Update from upstream:
git fetch upstream git rebase upstream/main
-
Run full test suite:
make test make lint -
Commit with clear, signed-off messages:
git commit -s -m "Add support for device labels filtering - Implement label selector validation - Add unit tests for new functionality - Update documentation with examples"
-
Push and create PR:
git push origin feature/your-feature-name # Create PR on GitHub
✅ Required for PR approval:
- All CI tests pass (unit tests, linting, container builds)
- Code follows style guidelines (Black formatting, flake8 compliance)
- New code has appropriate test coverage
- Documentation updated if needed
- Clear commit messages and PR description
✅ PR Template:
## Description
Brief description of changes
## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Code refactoring
## Testing
- [ ] Unit tests added/updated
- [ ] Integration tests added/updated
- [ ] Tested against live Flight Control instance
- [ ] All existing tests pass
## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] No breaking changes (or breaking changes documented)- Automated checks - CI must pass
- Code review - Maintainer review for quality and correctness
- Testing - Verify functionality works as expected
- Documentation - Ensure changes are properly documented
Use the GitHub issue template and include:
**Describe the bug**
Clear description of what went wrong
**To Reproduce**
Steps to reproduce the behavior:
1. Set up environment with...
2. Run command...
3. See error...
**Expected behavior**
What you expected to happen
**Environment:**
- OS: [e.g. Linux, macOS]
- Python version: [e.g. 3.11]
- Flight Control version: [if applicable]
- MCP server version/commit: [git commit hash]
**Additional context**
- Configuration details (redact sensitive info)
- Log files (use LOG_LEVEL=DEBUG)
- Screenshots if applicable**Feature Description**
Clear description of the proposed feature
**Use Case**
Why is this feature needed? What problem does it solve?
**Proposed Solution**
How should this feature work?
**Alternatives Considered**
Other solutions you've considered
**Additional Context**
Any other context, mockups, or examples# 1. Set up development environment
make install-dev
# 2. Create feature branch
git checkout -b feature/new-tool
# 3. Develop with TDD approach
# Write failing test
pytest test_flightctl_mcp.py::TestNewFeature::test_new_functionality -v
# Implement feature
# Run test again (should pass)
# 4. Run full test suite frequently
make test-unit # Quick feedback (30 seconds)
# 5. Before committing
make test # Full test suite (2 minutes)
make lint # Code quality checks
# 6. Manual testing (if needed)
python test_live_instance.py
# 7. Commit with sign-off and submit PR
git commit -s -m "Add new MCP tool for device management
- Implement device filtering functionality
- Add comprehensive unit tests
- Update documentation"
git push origin feature/new-tool# View logs
make logs
# Run tests with debugging
pytest --pdb test_flightctl_mcp.py::TestClass::test_method
# Run with detailed output
pytest -vvv -s test_flightctl_mcp.py
# Debug configuration issues
LOG_LEVEL=DEBUG python main.py- 📖 Documentation: README.md, TESTING.md
- 🧪 Testing Guide: CI-TESTING.md
- 🐛 Issues: GitHub Issues
- 💬 Discussions: GitHub Discussions
Q: How do I test without a Flight Control instance? A: Most development can be done with unit tests that use mocks. See TESTING.md for details.
Q: My tests are failing in CI but passing locally? A: Check the CI-TESTING.md guide. Likely a dependency or environment difference.
Q: How do I add a new MCP tool?
A: Add the tool function in main.py, implement the backend logic in resource_queries.py, and add comprehensive tests.
Q: What's the difference between unit and integration tests? A: Unit tests mock external dependencies, integration tests may use mocked HTTP responses but test component interactions.
Q: I forgot to sign off my commits, how do I fix it?
A: Use git commit --amend --signoff for the last commit, or git rebase -i for multiple commits. See the DCO section above for details.
Q: Why do I need to sign off commits? A: The Developer Certificate of Origin (DCO) ensures legal clarity about contribution rights and protects both contributors and users of the project.
- Check existing issues - Your question might already be answered
- Read the documentation - Comprehensive guides are available
- Start a discussion - For questions about architecture or design
- Create an issue - For bugs or feature requests
- Submit a draft PR - For complex changes, get early feedback
Contributors are recognized in:
- Git commit history
- Release notes for significant contributions
- GitHub contributor graphs
- Special thanks in major releases
Thank you for contributing to Flight Control MCP Server! 🚀