# Path Migration Guide
This document describes the changes made to remove hardcoded paths from the codebase.
## Summary of Changes
All hardcoded paths have been replaced with generic placeholders or environment variables to make the codebase more portable across different systems and users.
## Python Files Updated
The following Python files now use environment variables with fallback paths:
### Core Tools
- `src/gazebo_mcp/tools/model_management.py`
- `src/gazebo_mcp/tools/sensor_tools.py`
- `src/gazebo_mcp/tools/simulation_tools.py`
- `src/gazebo_mcp/tools/world_tools.py`
- `src/gazebo_mcp/server.py`
### Test Files
- `tests/conftest.py`
- `test_mcp_protocol.py`
### Scripts
- `scripts/generate_mcp_assets.py`
- `scripts/test_mcp_integration.py`
## Environment Variables
### `CLAUDE_ROOT`
**Purpose**: Specifies the location of the `claude` directory containing MCP infrastructure.
**Default fallback**: `<project-root>/claude`
**Usage in Python**:
```python
import os
from pathlib import Path
CLAUDE_ROOT = Path(os.environ.get("CLAUDE_ROOT", Path(__file__).parents[3] / "claude"))
if CLAUDE_ROOT.exists():
sys.path.insert(0, str(CLAUDE_ROOT))
```
**How to set**:
```bash
export CLAUDE_ROOT=/path/to/your/claude
```
### `GAZEBO_MCP_SERVER`
**Purpose**: Specifies the location of the `gazebo-mcp-server` wrapper script.
**Default fallback**: `~/.local/bin/gazebo-mcp-server`
**Usage in Python**:
```python
server_script = os.environ.get("GAZEBO_MCP_SERVER",
os.path.expanduser("~/.local/bin/gazebo-mcp-server"))
```
**How to set**:
```bash
export GAZEBO_MCP_SERVER=/path/to/gazebo-mcp-server
```
## Documentation Updates
### Main Documentation Files
The following files have been updated with generic path placeholders:
- `INSTALL_MCP.md` - Changed specific paths to `<path-to-ros2_gazebo_mcp>`
- `QUICK_INSTALL.md` - Changed specific paths to `<path-to-ros2_gazebo_mcp>`
- `MCP_SETUP_GUIDE.md` - Changed specific paths to `<path-to-ros2_gazebo_mcp>`
- `mcp/README.md` - Changed specific paths to `<path-to-ros2_gazebo_mcp>`
- `tests/README.md` - Changed specific paths to `<path-to-ros2_gazebo_mcp>`
### Files with Historical Paths
The following files contain hardcoded paths in old plans/demos but don't require immediate updates as they are historical documents:
- `plans/DEMO_IMPLEMENTATION_PLAN.md`
- `plans/DEMO2_NAV2_UPGRADE_PLAN.md`
- `demos/CONVERSATIONAL_DEMO_GUIDE.md`
- `demos/MANUAL_SETUP_GUIDE.md`
- `demos/02_obstacle_course/CONVERSATIONAL_DEMO.md`
- `demos/02_obstacle_course/README.md`
- `demos/02_obstacle_course/TEST_RESULTS.md`
- `demos/TROUBLESHOOTING.md`
- `docs/QUICK_START_IMPROVEMENTS.md`
- `docs/IMPLEMENTATION_IMPROVEMENTS.md`
**Note**: When following instructions in these documents, replace any hardcoded paths with your actual project path.
## Installation Scripts
The installation scripts (`install_mcp_global.sh`) dynamically detect the project root and don't require manual path configuration.
## Shell Scripts (Auto-generated)
The following shell scripts are auto-generated by the build system and contain system-specific paths:
- `install/local_setup.sh`
- `install/setup.sh`
- `build/gazebo_mcp/prefix_override/sitecustomize.py`
These are regenerated on each build and don't need manual updates.
## Migration Checklist for New Systems
When setting up on a new system:
1. ✅ Clone the repository to your desired location
2. ✅ (Optional) Set `CLAUDE_ROOT` if using external claude directory
3. ✅ Run `./install_mcp_global.sh --with-ros2`
4. ✅ The installation script will automatically configure paths
5. ✅ Verify with `gazebo-mcp-server` (should be in `~/.local/bin`)
## For Developers
When writing new code:
**DO**:
- Use `Path(__file__).parents[N]` for relative path resolution
- Use `os.environ.get()` with sensible defaults
- Use `os.path.expanduser("~")` for home directory paths
- Test with `CLAUDE_ROOT` set to different locations
**DON'T**:
- Hardcode `/home/username/` paths
- Hardcode `/Users/username/` paths
- Hardcode absolute paths specific to your machine
- Assume project location
## Example: Adding a New Module
```python
import sys
import os
from pathlib import Path
# Add claude project to path (if needed)
CLAUDE_ROOT = Path(os.environ.get("CLAUDE_ROOT", Path(__file__).parents[3] / "claude"))
if CLAUDE_ROOT.exists():
sys.path.insert(0, str(CLAUDE_ROOT))
# Use relative paths for project files
PROJECT_ROOT = Path(__file__).parents[2]
CONFIG_FILE = PROJECT_ROOT / "config" / "settings.yaml"
```
## Troubleshooting
### Import errors from claude/
**Error**: `ImportError: No module named 'skills'`
**Solution**:
1. Check if claude/ directory exists at the fallback location
2. Set `CLAUDE_ROOT` environment variable: `export CLAUDE_ROOT=/path/to/claude`
3. Or place the claude directory at the expected fallback location
### Server script not found
**Error**: `gazebo-mcp-server not found`
**Solution**:
1. Run `./install_mcp_global.sh` to install the wrapper script
2. Or set `GAZEBO_MCP_SERVER` to the script location
3. Verify the script exists: `ls ~/.local/bin/gazebo-mcp-server`
## Testing Path Independence
To test that your code is path-independent:
```bash
# Test with different CLAUDE_ROOT
export CLAUDE_ROOT=/tmp/test-claude
python -m your_module
# Test server from different directory
cd /tmp
gazebo-mcp-server
```
## Questions?
If you encounter path-related issues after migration:
1. Check environment variables are set correctly
2. Verify file permissions on scripts
3. Review this guide for proper usage patterns
4. Check that auto-generated files were rebuilt after migration
