Content
# Tool List
[](./test_report.md)
[](https://python.org)
[](https://modelcontextprotocol.io)
A professional MCP (Model Context Protocol) service focusing on DJI drone route planning and KMZ file generation. Based on the DJI WPML (WayPoint Markup Language) standard, it provides automated route planning, KMZ file generation, and route optimization.
## ✨ Main Features
- 🛩️ **Multiple Flight Modes**: Supports waypoint flight, mapping, oblique photography, and inspection.
- 🎯 **Intelligent Route Planning**: Automatically generates optimal route paths, supports complex survey areas, and various constraints.
- 📁 **WPML Standard**: Generates KMZ files compliant with the DJI WPML standard, directly importable into DJI Pilot 2.
- 🔧 **Route Optimization**: Built-in multiple optimization algorithms to minimize flight distance and time.
- 🌐 **Coordinate Conversion**: Supports multiple coordinate system conversions (WGS84, GCJ02, BD09, etc.).
- ✅ **Compatibility Check**: Automatically verifies device compatibility and parameter safety.
- 🚁 **Multi-Platform Support**: Supports multiple DJI drones such as M300/M350/M30/M3 series.
## 🚀 Quick Start
### Requirements
- Python 3.8+
- Supported operating systems: macOS, Linux, Windows
### Install Dependencies
```bash
# Clone the project
git clone <repository-url>
cd dji-waypoint-mcp
# Install dependencies
pip install -r requirements.txt
# Install development dependencies (optional)
pip install -r requirements-dev.txt
```
### Run the Service
```bash
# Start the MCP service
python -m src.dji_waypoint_mcp.server
# Or use development mode
python src/dji_waypoint_mcp/server.py
```
### Test Installation
```bash
# Run comprehensive tests
python test_comprehensive.py
# View test report
cat test_report.md
```
## 📖 Usage Guide
### MCP Tool Overview
| Tool Name | Function | Applicable Scenario |
|---------|------|---------|
| `plan_waypoint_mission` | Waypoint flight planning | Precise positioning operations |
| `plan_mapping_mission` | Mapping mission planning | Terrain surveying |
| `plan_oblique_mission` | Oblique photography planning | 3D modeling |
| `plan_strip_mission` | Strip flight planning | Linear inspection |
| `optimize_route` | Route optimization | Efficiency improvement |
| `generate_kmz` | KMZ file generation | File export |
### Basic Usage Examples
#### 1. Waypoint Flight Mission
```python
# Plan a simple waypoint flight mission
waypoint_mission = {
"waypoints": [
{
"latitude": 39.9042,
"longitude": 116.4074,
"altitude": 100.0,
"actions": [{"type": "take_photo"}]
},
{
"latitude": 39.9142,
"longitude": 116.4174,
"altitude": 100.0,
"actions": [{"type": "take_photo"}]
}
],
"aircraft_type": "M30",
"flight_params": {
"speed": 5.0,
"altitude": 100.0
}
}
```
#### 2. Mapping Mission
```python
# Plan a rectangular survey area mapping mission
mapping_mission = {
"survey_area": {
"type": "rectangle",
"coordinates": [
[116.4074, 39.9042], # Bottom left
[116.4174, 39.9142] # Top right
]
},
"mapping_params": {
"altitude": 120.0,
"overlap_rate": {
"front": 0.8,
"side": 0.7
},
"direction": 0
},
"aircraft_type": "M30"
}
```
#### 3. Generate KMZ File
```python
# Generate a WPML-standard KMZ file
kmz_config = {
"flight_plan": {
"waypoints": [...], # Waypoint data
"flight_speed": 5.0,
"aircraft_type": "M30"
},
"output_filename": "mission.kmz",
"include_template": True,
"author": "Route Planner"
}
```
## 🛠️ Development Guide
### Project Structure
```
dji-waypoint-mcp/
├── src/dji_waypoint_mcp/ # Main source code
│ ├── server.py # MCP server main program
│ ├── config.py # Configuration management
│ ├── models/ # Data models
│ ├── tools/ # MCP tool implementations
│ ├── utils/ # Utility functions
│ └── data/ # Data files
├── tests/ # Test files
├── docs/ # Documentation
├── mcp/ # MCP protocol implementation
└── requirements.txt # Dependency list
```
### Adding New Tools
1. Create a new tool file in `src/dji_waypoint_mcp/tools/`
2. Inherit the `BaseTool` class and implement necessary methods
3. Register the new tool in `server.py`
4. Add corresponding test cases
### Code Style
- Use Python type annotations
- Follow PEP 8 code style
- Write complete docstrings
- Add proper error handling
- Write unit tests
## 🔧 Configuration
### Environment Variables
```bash
# Log level
export LOG_LEVEL=INFO
# Output directory
export OUTPUT_DIR=./output
# Temporary directory
export TEMP_DIR=./temp
```
### Configuration File
Main configurations are in `src/dji_waypoint_mcp/config.py`:
```python
# Server configuration
SERVER_NAME = "dji-waypoint-mcp"
SERVER_VERSION = "1.0.0"
# File path configuration
OUTPUT_DIR = Path("./output")
TEMP_DIR = Path("./temp")
# Log configuration
LOG_LEVEL = "INFO"
LOG_FORMAT = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
```
## 📊 Performance Metrics
- **Test Coverage**: 100%
- **Supported Platforms**: 9 DJI drone models
- **Number of Tools**: 10 professional tools
- **Coordinate Systems**: Supports 5 coordinate system conversions
- **Optimization Algorithms**: 5 route optimization algorithms
## 🤝 Contribution Guide
We welcome community contributions! Please follow these steps:
1. Fork the project
2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
### Contribution Types
- 🐛 Bug fixes
- ✨ New feature development
- 📚 Documentation improvement
- 🎨 Code optimization
- 🧪 Test cases
## 📋 Changelog
### v1.0.0 (2024-07-20)
- ✅ Complete MCP service implementation
- ✅ 10 professional route planning tools
- ✅ WPML-standard KMZ file generation
- ✅ Multiple coordinate system conversions
- ✅ Intelligent route optimization algorithms
- ✅ Device compatibility checks
- ✅ 100% test coverage
## 🆘 Troubleshooting
### Common Issues
**Q: Failed to import module**
```bash
# Ensure Python path is correct
export PYTHONPATH=$PYTHONPATH:$(pwd)/src
```
**Q: Inaccurate coordinate conversion**
```bash
# Check coordinate system settings
# Use GCJ02 for mainland China, WGS84 for outside
```
**Q: KMZ file cannot be imported into DJI Pilot 2**
```bash
# Check file format and WPML standard compatibility
# Ensure the number of waypoints does not exceed 99
```
For more issues, see [Troubleshooting Guide](docs/Troubleshooting Guide.md)
## 📄 License
This project is licensed under the MIT License - see [LICENSE](LICENSE) file for details
## 🙏 Acknowledgments
- [DJI Innovation](https://www.dji.com/) - WPML standard and technical support
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP protocol specification
- Various excellent libraries and tools from the open-source community
## 📞 Contact Us
- 📧 Email: [your-email@example.com]
- 🐛 Issue reporting: [GitHub Issues](https://github.com/your-repo/issues)
- 💬 Discussion: [GitHub Discussions](https://github.com/your-repo/discussions)
---
⭐ If this project helps you, please give us a star!
