Phase 1 - Safe ROS 2 Project Creation

Goal

Phase 1 establishes the development-focused ros2_dev_mcp server and provides controlled ROS 2 project creation through MCP.

The main goal is to allow an MCP-compatible client such as Codex to create ROS 2 development projects without giving the client unrestricted filesystem or shell access.

This phase also establishes the architectural separation between ROS 2 runtime operations and ROS 2 development operations.

Runtime operations belong to:

ros2_mcp

Development operations belong to:

ros2_dev_mcp

Generated and managed ROS 2 workspaces are stored separately below:

~/projects/robotics/mcp_workspaces/

The result is a clear separation:

~/projects/robotics/
├── ros2_mcp/          # ROS 2 runtime MCP server
├── ros2_dev_mcp/      # ROS 2 development MCP server
├── mcp_workspaces/    # MCP-managed ROS 2 workspaces
└── ...

---

Why a Separate Development MCP Server?

ROS 2 runtime interaction and ROS 2 software development have different responsibilities and different safety requirements.

A runtime MCP server needs access to the running ROS graph.

Typical runtime operations include:

list_nodes
list_topics
read_topic
list_services
list_parameters
get_parameter

A development MCP server needs controlled access to project files and development commands.

Typical development operations include:

create_workspace
create_package
create_node
create_launch_file
create_parameter_file
create_tests
build_project
run_tests

Combining both responsibilities in one server would create a larger security boundary and a more complex architecture.

Therefore the projects are intentionally separated.

                   MCP Client
                       |
             +---------+---------+
             |                   |
             v                   v
       ros2_dev_mcp          ros2_mcp
             |                   |
       Development             Runtime
             |                   |
       Workspace               Nodes
       Packages                Topics
       Nodes                   Services
       Launch files            Parameters
       Parameter files         Runtime state
       Tests
       Build
       Test

This also makes future specialized MCP servers easier to add.

Examples:

ros2_control_mcp
moveit2_mcp
nav2_mcp

---

Phase 1 Responsibilities

Phase 1 focuses on ROS 2 project generation.

The project creation tools are:

create_workspace
create_package
create_node
create_launch_file
create_parameter_file
create_tests

Controlled build and test execution are implemented by the same development server but documented separately in:

docs/README_PHASE_2_BUILD_TEST.md

using:

build_project
run_tests

---

Architecture

The project creation path is:

MCP Client
    |
    v
ros2_dev_mcp
    |
    v
MCP Project Tools
    |
    v
ProjectService
    |
    v
ProjectAdapter
    |
    v
FilesystemProjectAdapter
    |
    v
SafeFilesystem
    |
    v
Configured Managed Root
    |
    v
ROS 2 Workspace

The layers have separate responsibilities.

---

MCP Layer

Location:

src/ros2_dev_mcp/mcp/project_tools.py

Responsibilities:

• expose project operations as MCP tools
• validate MCP tool arguments
• obtain the application service from the MCP context
• delegate operations to ProjectService
• return structured results to the MCP client

The MCP layer does not directly manipulate project files.

---

Application Layer

Location:

src/ros2_dev_mcp/application/project/service.py

The ProjectService contains the development use cases.

Responsibilities include delegating:

create_workspace
create_package
create_node
create_launch_file
create_parameter_file
create_tests
build_project
run_tests

to the appropriate adapters.

This keeps MCP-specific behavior separate from project implementation details.

---

Project Adapter

Location:

src/ros2_dev_mcp/project/adapter.py

The Project Adapter defines the interface required by the application layer.

The application service therefore does not need to know how project files are physically created.

The concrete filesystem implementation is located at:

src/ros2_dev_mcp/project/filesystem/adapter.py

This design allows the implementation to evolve without tightly coupling the application layer to filesystem details.

---

Filesystem Security Boundary

One of the most important requirements of ros2_dev_mcp is that Codex or another MCP client must not receive unrestricted filesystem access through the server.

All project operations are restricted to a configured root directory.

Current managed root:

/home/sarvg/projects/robotics/mcp_workspaces

Equivalent user path:

~/projects/robotics/mcp_workspaces

Configuration file:

config/ros2_dev_mcp.toml

Current configuration:

[project]
allowed_root = "/home/sarvg/projects/robotics/mcp_workspaces"

[execution]
build_timeout_sec = 120.0
test_timeout_sec = 120.0

The managed root is intentionally outside the MCP server repositories themselves.

This means generated projects can be placed here:

~/projects/robotics/mcp_workspaces/test_ws
~/projects/robotics/mcp_workspaces/pubsub_ws
~/projects/robotics/mcp_workspaces/my_robot_ws

while existing projects outside that directory remain outside the project filesystem boundary.

Examples include:

~/projects/robotics/ros2_mcp
~/projects/robotics/ros2_dev_mcp
~/projects/robotics/openmanipulator
~/projects/robotics/turtlebot3
~/projects/robotics/universal_robots
~/projects/robotics/robotics_portfolio_1

The development MCP should not use these existing projects as writable project targets.

---

SafeFilesystem

The filesystem boundary is implemented by:

src/ros2_dev_mcp/project/filesystem/safe_filesystem.py

SafeFilesystem resolves requested project paths against the configured allowed root.

Its responsibilities include:

• resolving relative paths below the allowed root
• accepting absolute paths only when they remain below the allowed root
• rejecting parent-directory traversal outside the root
• resolving paths before validating them
• preventing symlink-based escapes from the allowed root

Conceptually:

Requested Path
      |
      v
Resolve Path
      |
      v
Is Path Inside allowed_root?
      |
   +--+--+
   |     |
  Yes    No
   |     |
   v     v
Allow  Reject

Examples of valid targets:

test_ws
pubsub_ws
/home/sarvg/projects/robotics/mcp_workspaces/test_ws

Examples that must be rejected:

../ros2_mcp
../openmanipulator
/tmp/test_ws
/home/sarvg/projects/robotics/ros2_mcp
/home/sarvg/projects/robotics/openmanipulator

This boundary was explicitly verified during development.

---

Workspace Creation

The MCP tool:

create_workspace

creates a ROS 2 workspace below the configured managed root.

Example MCP request conceptually:

create_workspace(
    workspace_path="test_ws"
)

Result:

~/projects/robotics/mcp_workspaces/test_ws/
└── src/

The workspace follows the standard ROS 2 workspace layout:

workspace/
└── src/

Build directories are not created during workspace creation.

They are generated later by colcon build.

Typical build result:

workspace/
├── build/
├── install/
├── log/
└── src/

---

Package Creation

The MCP tool:

create_package

creates a ROS 2 Python package inside an existing managed workspace.

Example:

Workspace:
pubsub_ws

Package:
demo_pubsub

Resulting structure:

pubsub_ws/
└── src/
    └── demo_pubsub/
        ├── demo_pubsub/
        │   └── __init__.py
        ├── package.xml
        ├── resource/
        │   └── demo_pubsub
        ├── setup.cfg
        └── setup.py

The generated package uses the ROS 2 Python package structure based on:

ament_python

The package metadata and Python package directory are created automatically.

---

Node Creation

The MCP tool:

create_node

creates a Python ROS 2 node inside an existing package.

Example:

package:
demo_pubsub

node:
publisher_node

Generated file:

pubsub_ws/
└── src/
    └── demo_pubsub/
        └── demo_pubsub/
            └── publisher_node.py

Another node can be added independently:

subscriber_node.py

Result:

demo_pubsub/
└── demo_pubsub/
    ├── __init__.py
    ├── publisher_node.py
    └── subscriber_node.py

---

ROS 2 Executable Registration

Creating a Python file alone is not enough for:

ros2 run

Therefore generated nodes are registered as Python console scripts.

Conceptually:

entry_points={
    "console_scripts": [
        "publisher_node = demo_pubsub.publisher_node:main",
        "subscriber_node = demo_pubsub.subscriber_node:main",
    ],
}

After building and sourcing the workspace, ROS 2 can discover the executables.

Example verification:

cd ~/projects/robotics/mcp_workspaces/pubsub_ws
source /opt/ros/jazzy/setup.bash
source install/setup.bash

ros2 pkg executables demo_pubsub

A successfully generated package can expose:

demo_pubsub publisher_node
demo_pubsub subscriber_node

The nodes can then be started with:

ros2 run demo_pubsub publisher_node

and:

ros2 run demo_pubsub subscriber_node

---

setup.cfg

Generated Python ROS 2 packages include:

setup.cfg

with ROS 2 executable installation paths.

Conceptually:

[develop]
script_dir=$base/lib/demo_pubsub

[install]
install_scripts=$base/lib/demo_pubsub

This is required so installed Python executables are placed where ROS 2 expects them.

---

Launch File Creation

The MCP tool:

create_launch_file

creates a Python ROS 2 launch file.

Typical result:

demo_pubsub/
└── launch/
    └── demo.launch.py

The launch file can reference one or more nodes from the package.

This allows a higher-level development request such as:

Create a publisher and subscriber and create a launch file
that starts both nodes.

The long-term goal is that Codex can express the intent while ros2_dev_mcp performs the controlled project operations.

---

Parameter File Creation

The MCP tool:

create_parameter_file

creates a ROS 2 YAML parameter file.

Typical structure:

demo_pubsub/
└── config/
    └── demo_params.yaml

A minimal ROS 2 parameter structure can look like:

publisher_node:
  ros__parameters: {}

Parameter values can later be expanded according to the project requirements.

Configuration files belong to the generated ROS 2 package and remain inside the managed workspace boundary.

---

Test Creation

The MCP tool:

create_tests

creates basic tests for a generated Python ROS 2 package.

Typical structure:

demo_pubsub/
└── test/
    └── test_package_import.py

The initial test verifies that the generated Python package can be imported correctly.

Additional ROS 2-specific tests can be added in later development phases.

---

Complete Generated Project Structure

A generated project can therefore look like:

pubsub_ws/
└── src/
    └── demo_pubsub/
        ├── config/
        │   └── demo_params.yaml
        ├── demo_pubsub/
        │   ├── __init__.py
        │   ├── publisher_node.py
        │   └── subscriber_node.py
        ├── launch/
        │   └── demo.launch.py
        ├── package.xml
        ├── resource/
        │   └── demo_pubsub
        ├── setup.cfg
        ├── setup.py
        └── test/
            └── test_package_import.py

After building, the workspace can contain:

pubsub_ws/
├── build/
├── install/
├── log/
└── src/
    └── demo_pubsub/
        └── ...

---

Configuration

Application configuration is loaded from:

config/ros2_dev_mcp.toml

Configuration loading is implemented in:

src/ros2_dev_mcp/config/settings.py

Current configurable values include:

project.allowed_root
execution.build_timeout_sec
execution.test_timeout_sec

These values are intentionally stored outside the application logic.

This avoids hard-coding environment-specific configuration throughout the source code.

---

Current Source Structure

The development server is organized as:

src/ros2_dev_mcp/
├── application/
│   ├── __init__.py
│   └── project/
│       ├── __init__.py
│       └── service.py
├── config/
│   ├── __init__.py
│   └── settings.py
├── __init__.py
├── mcp/
│   ├── __init__.py
│   └── project_tools.py
├── project/
│   ├── adapter.py
│   ├── execution/
│   │   ├── adapter.py
│   │   ├── __init__.py
│   │   ├── policy.py
│   │   └── subprocess_adapter.py
│   ├── filesystem/
│   │   ├── adapter.py
│   │   ├── __init__.py
│   │   └── safe_filesystem.py
│   └── __init__.py
└── server.py

The execution layer belongs primarily to the controlled build and test functionality documented in Phase 2.

---

Development Environment

The current development environment is based on:

Ubuntu 24.04
ROS 2 Jazzy
Python 3.12
uv
MCP Python SDK
colcon

---

Installation

Create or synchronize the Python environment:

cd ~/projects/robotics/ros2_dev_mcp

uv sync
source .venv/bin/activate

Verify Python:

python --version

The project currently targets:

Python >=3.12,<3.13

---

Start ros2_dev_mcp Directly

The server can be started directly for development or debugging.

cd ~/projects/robotics/ros2_dev_mcp
source .venv/bin/activate

python -m ros2_dev_mcp.server

The server uses MCP standard I/O transport.

When Codex starts the configured MCP server, starting it manually is normally unnecessary.

---

Codex Integration

ros2_dev_mcp can be registered as an MCP server in Codex.

Register it with:

cd ~/projects/robotics/ros2_dev_mcp
source .venv/bin/activate

codex mcp add ros2_dev_mcp \
  -- \
  bash -lc 'cd /home/sarvg/projects/robotics/ros2_dev_mcp && source .venv/bin/activate && exec python -m ros2_dev_mcp.server'

Check the registration:

codex mcp get ros2_dev_mcp

List all configured MCP servers:

codex mcp list

Start Codex:

cd ~/projects/robotics/ros2_dev_mcp
source .venv/bin/activate

codex

Inside Codex, inspect available MCP tools with:

/mcp

The expected ros2_dev_mcp tools are:

build_project
create_launch_file
create_node
create_package
create_parameter_file
create_tests
create_workspace
run_tests

---

Real Codex Verification

The separated development MCP server was tested with Codex.

The request was:

Use only the ros2_dev_mcp MCP server.

Create a new ROS 2 workspace named split_test_ws.

Do not use shell commands.
Do not use direct filesystem operations.
Do not use ros2_mcp.
Do not modify any existing project.

Codex invoked:

ros2_dev_mcp.create_workspace

The resulting workspace was:

/home/sarvg/projects/robotics/mcp_workspaces/split_test_ws
└── src/

This verifies the complete path:

User
  |
  v
Codex
  |
  v
ros2_dev_mcp
  |
  v
Project MCP Tool
  |
  v
ProjectService
  |
  v
FilesystemProjectAdapter
  |
  v
SafeFilesystem
  |
  v
mcp_workspaces

No existing ROS 2 project needed to be modified.

---

Publisher / Subscriber Development Example

A more complete development workflow was also tested using a publisher/subscriber workspace.

The development target was:

pubsub_ws

with package:

demo_pubsub

and nodes:

publisher_node
subscriber_node

The intended project structure is:

mcp_workspaces/
└── pubsub_ws/
    └── src/
        └── demo_pubsub/
            ├── demo_pubsub/
            │   ├── __init__.py
            │   ├── publisher_node.py
            │   └── subscriber_node.py
            ├── package.xml
            ├── resource/
            │   └── demo_pubsub
            ├── setup.cfg
            └── setup.py

The workspace was successfully built using the development MCP.

After sourcing the built workspace, ROS 2 reported the generated executables:

demo_pubsub publisher_node
demo_pubsub subscriber_node

The nodes were started and discovered by ROS 2.

Example node list:

/publisher_node
/ros2_mcp_runtime
/subscriber_node

This demonstrated that generated project artifacts could progress from MCP project creation to an actual ROS 2 workspace build and runtime discovery.

---

Example Codex Project Creation Request

A project creation request can be expressed at a high level.

Example:

Use only the ros2_dev_mcp MCP server.

Create a new ROS 2 workspace named pubsub_ws.

Inside it, create a Python package named demo_pubsub.

Create two nodes:

- publisher_node
- subscriber_node

Create a launch file for both nodes.

Create basic tests.

Do not use shell commands.
Do not use direct filesystem operations.
Do not use ros2_mcp.
Do not modify any existing project.

The intended MCP workflow is:

Codex
  |
  v
create_workspace
  |
  v
create_package
  |
  +------------------+
  |                  |
  v                  v
create_node       create_node
publisher         subscriber
  |                  |
  +--------+---------+
           |
           v
 create_launch_file
           |
           v
     create_tests

Build and test operations then continue through Phase 2.

---

Desired Higher-Level Workflow

The long-term goal is not to require the user to know every individual MCP tool.

Instead, a user should eventually be able to request:

Create a ROS 2 publisher/subscriber example with a launch file,
build it, test it, and report the result.

Codex can then plan the workflow and invoke the required MCP tools:

User Intent
    |
    v
Codex
    |
    +--> create_workspace
    |
    +--> create_package
    |
    +--> create_node
    |
    +--> create_node
    |
    +--> create_launch_file
    |
    +--> create_tests
    |
    +--> build_project
    |
    +--> run_tests
    |
    v
Result

The MCP server provides controlled capabilities.

The MCP client performs the higher-level orchestration.

---

Important Security Principle

ros2_dev_mcp is not intended to expose a generic shell.

For example, an MCP client should not receive a tool such as:

execute_arbitrary_shell_command

Instead, specific development operations are exposed:

create_workspace
create_package
create_node
create_launch_file
create_parameter_file
create_tests
build_project
run_tests

This creates a much smaller and more understandable security boundary.

---

Existing Project Protection

The managed workspace boundary is particularly important because the robotics directory contains existing projects.

For example:

~/projects/robotics/
├── mcp_workspaces/
├── oakd/
├── openmanipulator/
├── robotics_portfolio_1/
├── ros2_dev_mcp/
├── ros2_mcp/
├── turtlebot3/
├── universal_robots/
└── zed2/

ros2_dev_mcp project operations are restricted to:

mcp_workspaces/

The MCP development tools therefore have a dedicated area for generated projects instead of operating across the entire robotics directory.

---

MCP Client Independence

The server uses the Model Context Protocol rather than Codex-specific APIs.

The architecture is therefore:

MCP-compatible Client
        |
        v
ros2_dev_mcp

Codex is currently used as the primary development client.

The design should not intentionally depend on Codex-specific behavior inside the MCP server implementation.

Other MCP-compatible clients can potentially use the same server if they support the required MCP transport and tools.

---

Independent Implementation

ros2_dev_mcp is developed as an independent implementation.

Other ROS 2 MCP projects can be studied for:

• feature comparison
• architectural ideas
• identifying useful ROS 2 operations
• understanding MCP use cases
• comparing safety approaches

Their source code is not used as a copy-and-paste implementation basis.

The project should evolve according to its own architecture and requirements.

---

Relationship to ros2_mcp

The generic ROS MCP architecture is intentionally divided into two primary servers.

ros2_mcp

Responsibility:

ROS 2 Runtime

Examples:

list_nodes
list_topics
topic_info
read_topic
list_services
service_info
node_info
list_parameters
get_parameter

Future runtime capabilities may include controlled:

publish_topic
call_service
set_parameter
ROS 2 actions
process monitoring
launch management
logs
diagnostics

ros2_dev_mcp

Responsibility:

ROS 2 Development

Current capabilities:

create_workspace
create_package
create_node
create_launch_file
create_parameter_file
create_tests
build_project
run_tests

This separation keeps runtime control and source/project manipulation independent.

---

Future Specialized MCP Servers

The long-term architecture can grow through specialized MCP servers.

MCP Clients
     |
     +-------------------- ros2_mcp
     |                       Generic ROS 2 runtime
     |
     +-------------------- ros2_dev_mcp
     |                       ROS 2 development
     |
     +-------------------- ros2_control_mcp
     |                       ros2_control
     |
     +-------------------- moveit2_mcp
     |                       MoveIt 2
     |
     +-------------------- nav2_mcp
                             Nav2

This prevents the generic ROS MCP server from becoming a monolithic implementation containing every ROS 2 subsystem.

---

Completed Phase 1 Capabilities

The current development foundation provides:

Separate ros2_dev_mcp server        ✅
Runtime / development separation    ✅
Configurable managed root           ✅
Safe filesystem boundary            ✅
Parent traversal protection         ✅
Symlink escape protection           ✅
Workspace creation                  ✅
Python package creation             ✅
Python node creation                ✅
ROS executable registration         ✅
Launch file creation                ✅
Parameter file creation             ✅
Basic test creation                 ✅
Codex MCP integration               ✅
Real Codex workspace creation       ✅
Existing project isolation          ✅

---

Phase 1 Design Rules

Phase 1 establishes the following rules:

1. ROS 2 development and runtime operations remain separated.
2. Project writes are restricted to a configured managed root.
3. Existing ROS 2 projects outside that root are not development targets.
4. Project paths are validated before filesystem operations.
5. Symlink and parent-path escapes must be rejected.
6. MCP tools expose specific development capabilities instead of unrestricted filesystem access.
7. The MCP layer does not directly implement filesystem behavior.
8. Application logic is separated from concrete adapters.
9. Configuration values are loaded from configuration files.
10. MCP clients should remain replaceable.
11. The implementation remains independent from other ROS MCP projects.
12. Generated ROS 2 projects should follow normal ROS 2 conventions.
13. Development features should remain understandable and testable individually.
14. Specialized ROS 2 subsystems should later receive separate MCP servers where appropriate.

---

Next Phase

Phase 2 focuses on controlled project execution.

The primary tools are:

build_project
run_tests

The execution path is:

MCP Client
    |
    v
Project MCP Tools
    |
    v
ProjectService
    |
    v
ExecutionAdapter
    |
    v
SubprocessExecutionAdapter
    |
    +--> CommandPolicy
    |
    +--> SafeFilesystem
    |
    v
Controlled Process
    |
    +--> colcon build
    |
    +--> colcon test

Phase 2 adds:

• explicit command policy
• controlled colcon build
• controlled colcon test
• package selection
• working-directory validation
• build timeout
• test timeout
• structured execution results

See:

docs/README_PHASE_2_BUILD_TEST.md

for the build and test execution architecture.