robotmcp--ros-mcp-server/docs/contributing.md

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.

   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.

   git commit -m "your_commit_message"
   

5. Push your branch: Push your branch to your forked repository.

   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 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:

     Ubuntu host

     sudo apt install x11-xserver-utils   # if xhost is not installed
     xhost +local:root                    # allow container user access
     

     Windows WSL2 host

     export DISPLAY=$(grep nameserver /etc/resolv.conf | awk '{print $2}'):0
     export QT_X11_NO_MITSHM=1
     xhost +local:root
     

     macOS host

     Install XQuartz and enable "Allow connections from network clients" in XQuartz → Settings → Security. Log out and back in (or restart XQuartz) for the setting to take effect.

     xhost +   # allow connections (run on macOS host, not inside the container)
     

     Inside the devcontainer terminal, override the display variable:

     export DISPLAY=host.docker.internal:0   # Docker's built-in DNS to reach host XQuartz
     

     Note: The postStartCommand (xhost +local:vscode || true) runs inside the container and only works on Linux hosts with a shared X11 socket. On macOS, you must run xhost on the host side as shown above.

     NVIDIA GPU passthrough (Linux only)

     If you have an NVIDIA GPU and the NVIDIA Container Toolkit installed, you can enable GPU passthrough by adding "--gpus=all" to runArgs in .devcontainer/devcontainer.json:

     "runArgs": [
         "--gpus=all",
         ...
     ]
     

     This flag is not included by default because it prevents the container from starting on macOS and Windows, where the NVIDIA Container Toolkit is not available.

4. You can now control the Turtlesim robot following the Rosbridge setup and Connect to your robot guides.

5. Initialize pre-commit hooks (optional but recommended):

   pre-commit install
   pre-commit run --all-files
   

6. Check Python code formatting with ruff

   ruff check .
   ruff format --check .
   

SSH Agent Setup for Git (click to expand)

This should be run on the host side prior to building the devcontainer.

# 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:

ssh-add ~/.ssh/id_ed25519
ssh-add -l   # confirm fingerprint shows up

Note: This setup has been tested and verified on Ubuntu and macOS (Apple Silicon).

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 in the project root.