# Contributing to ROS-MCP-Server
---
## 📌 Ways to Contribute
- **Report issues**: Bug reports, documentation gaps, or feature requests.
- **Improve documentation**: Clarify installation steps, add tutorials, or share demos.
- **Submit code**: Bug fixes, new features, refactors, or tests.
- **Share use cases**: Show how you use ROS-MCP with your robot.
- **Community support**: Answer GitHub Discussions or ROS Discourse questions.
---
## 🔀 How to Pull-request
1. **Fork the repository:** Click the "Fork" button in the top right corner of the GitHub page.
2. **Create a new branch:** Create a separate branch for your changes to keep them isolated from the main project.
```bash
git checkout -b "your_branch_name"
```
3. **Make your changes:** Edit files with your additions or corrections. Please follow the existing format and style guidelines. When adding a new function, make sure to include:
* The function name and format.
* A brief description of the function's functionality.
* Any parameters the function takes.
* The return type of the function.
4. **Commit your changes:** Commit your changes with a clear and concise message explaining what you've done.
```bash
git commit -m "your_commit_message"
```
5. **Push your branch:** Push your branch to your forked repository.
```bash
git push origin "your_branch_name"
```
6. **Create a pull request:** Navigate to the original repository and click the "New pull request" button. Select your fork and the branch you pushed. **Important:** Target the `develop` branch (not `main`) for your pull request. Provide a clear title and description of your changes.
7. **Review and merge:** Your pull request will be reviewed by the maintainers. They may suggest changes or ask for clarification. Once approved, your changes will be merged into the main repository.
Thank you for contributing!
---
## Style & CI
We use **Ruff** for both linting and formatting. CI requires:
- `ruff format --check .`
- `ruff check .`
**Local setup**
- Option A (recommended): `pre-commit install` (auto-fixes on commit)
- Option B (manual): `ruff format . && ruff check --fix .`
**Using Black locally?**
- That's fine. Please align with:
- `line-length = 100`, target `py310`
- Avoid `--preview`, `--skip-string-normalization`, `--skip-magic-trailing-comma`
- CI uses Ruff as the final arbiter; run `ruff format .` before pushing.
---
## Optional: Using Devcontainer
The devcontainer provides a stable testing platform with ROS2 humble pre-installed as well as an environment to test the MCP server in http transport. (stdio transport is not compatible with the devcontainer)
1. Install [VSCode](https://code.visualstudio.com/) and the **Remote - Containers** extension.
2. Open the `ros-mcp-server` repository in VSCode.
3. When prompted, **reopen in container**.
- The container includes ROS2 Humble, Python 3.10+, `ruff`, `pre-commit`, `uv`, and `git`.
- The repository is mounted at `/root/workspace`.
- **Note for GUI apps** (`turtlesim`, `rviz`, `Gazebo`):
Ensure the container can access your host X server by running the following command once on the host:
<details>
<summary> Ubuntu host </summary>
```bash
sudo apt install x11-xserver-utils # if xhost is not installed
xhost +local:root # allow container user access
```
</details>
<details>
<summary> Windows WSL2 host </summary>
```bash
export DISPLAY=$(grep nameserver /etc/resolv.conf | awk '{print $2}'):0
export QT_X11_NO_MITSHM=1
xhost +local:root
```
</details>
4. You can now control the Turtlesim robot following **Step-2** and **Step-4** from the [installation guide](installation.md).
5. Initialize pre-commit hooks (optional but recommended):
```bash
pre-commit install
pre-commit run --all-files
```
6. Check Python code formatting with `ruff`
```bash
ruff check .
ruff format --check .
```
<details>
<summary>SSH Agent Setup for Git (click to expand)</summary>
This should be run on the host side prior to building the devcontainer.
```bash
# Start the SSH agent
eval "$(ssh-agent -s)"
# List keys currently loaded
ssh-add -l
```
If it says “The agent has no identities”, you must load your key, for example:
```bash
ssh-add ~/.ssh/id_ed25519
ssh-add -l # confirm fingerprint shows up
```
</details>
**Note:** This setup has been tested and verified on Ubuntu.
## License
This project is licensed under the **Apache License 2.0**. By contributing to this project, you agree that your contributions will be licensed under the same license.
**Key points for contributors:**
- Your contributions will be licensed under Apache 2.0
- You retain copyright to your contributions
- You grant the project a perpetual, worldwide, non-exclusive license to use your contributions
- No additional legal agreements required for standard contributions
For the full license text, see [LICENSE](../LICENSE) in the project root.