Plansys2

Build Docker image codecov

An MCP (Model Context Protocol) server that provides tools and resources to interact with PlanSys2 automated planning system, allowing AI agents to access PDDL domain knowledge, manage planning problems, generate plans, and monitor execution.

Features

• Domain Management: Access PDDL domain definitions, types, predicates, and actions.
• Problem Definition: Query and modify planning problems including instances and goals.
• Plan Generation: Generate plans using PDDL planners.
• Execution Monitoring: Monitor plan execution and track progress.
• ROS 2 Integration: Full compatibility with PlanSys2 and ROS 2 ecosystem.

Tools

Domain Expert Tools

Tool	Description	Parameters
get_domain	Get the complete PDDL domain definition	—
get_domain_actions	Get all actions (regular and durative) with complete details including parameters and preconditions	—
get_domain_action_details	Get detailed information about a specific action including parameters, preconditions, and effects	name: str
get_domain_durative_action_details	Get detailed information about a specific durative action including parameters and conditions	name: str
get_domain_constants	Get all constant instances of a specific type	type_name: str
get_domain_functions	Get all functions defined in the domain with their parameters	—
get_domain_function_details	Get detailed information about a specific function including its complete structure	name: str
get_domain_predicates	Get all predicates and derived predicates with their complete details and parameters	—
get_domain_predicate_details	Get detailed information about a specific predicate including its complete structure	name: str
get_domain_derived_predicate_details	Get detailed information about a specific derived predicate including parameters and derivation rule	name: str
get_domain_types	List all types defined in the domain	—

Problem Expert Tools

Tool	Description	Parameters
add_problem	Add a complete PDDL problem definition	problem: str
add_problem_function	Add a function with its value to the problem	function: str
add_problem_goal	Add or set the goal specification for the problem	goal: str
add_problem_instance	Add a new object instance to the problem	name: str, instance_type: str
add_problem_predicate	Add a predicate to the current state	predicate: str
clear_problem_knowledge	Reset all problem data (instances, predicates, and goals)	—
exist_problem_function	Check if a function exists in the problem	function: str
exist_problem_predicate	Check if a predicate exists in the problem	predicate: str
get_problem	Get the complete PDDL problem definition	—
get_problem_functions	Get all functions in the problem with their names and types	—
get_problem_function_details	Get detailed information about a specific function including value	function: str
get_problem_goal	Get the current problem goal	—
get_problem_instances	Get all object instances with their names and types	—
get_problem_instance_details	Get detailed information about a specific instance	name: str
get_problem_predicates	Get all predicates in current state	—
get_problem_predicate_details	Get detailed information about a specific predicate	predicate: str
is_problem_goal_satisfied	Check if a goal is satisfied in the current state	goal: str
remove_problem_function	Remove a function from the current state	function: str
remove_problem_goal	Remove the current goal from the problem	—
remove_problem_instance	Remove an object instance from the problem	name: str
remove_problem_predicate	Remove a predicate from the current state	predicate: str
update_problem_function	Update a function value in the problem	function: str

Planner Tools

Tool	Description	Parameters
generate_plan	Generate a plan for a given PDDL domain and problem	domain: str, problem: str
validate_domain	Validate a PDDL domain definition	domain: str

Executor Tools

Tool	Description	Parameters
execute_plan	Execute a plan	plan: str
get_current_plan	Get the plan currently being executed	—
get_remaining_plan	Get remaining actions in the plan	—

Resources

The server provides three MCP resources:

• plansys2://domain - Current PDDL domain
• plansys2://problem - Current PDDL problem
• plansys2://plan - Currently executing plan

Configuration

Environment Variables

Variable	Default	Description
TRANSPORT_MODE	stdio	Transport mode: stdio (local integration) or http (network)
HTTP_HOST	0.0.0.0	HTTP host binding (only used when TRANSPORT_MODE=http)
HTTP_PORT	3001	HTTP port (only used when TRANSPORT_MODE=http)
LOG_LEVEL	INFO	Logging level: DEBUG, INFO, WARNING, ERROR, CRITICAL
ROS_DOMAIN_ID	—	ROS 2 domain ID for network isolation (recommended)
ROS_LOCALHOST_ONLY	—	Set to '1' to restrict ROS 2 communication to localhost only

Setup

1. Copy the environment configuration template:

cp .env.example .env

2. Edit .env to customize settings:

# Transport mode: 'stdio' for local, 'http' for containerized/network
TRANSPORT_MODE=stdio

# HTTP settings (only needed if using http transport)
HTTP_HOST=0.0.0.0
HTTP_PORT=3001

# Logging
LOG_LEVEL=INFO

Installation

Dependencies

• Robot Operating System (ROS) 2: Middleware for robotics (Jazzy)
• PlanSys2: Automated planning framework
• fastmcp: MCP server framework

Install with uv (recommended)

Clone the repository and install with uv:

git clone https://github.com/ajtudela/plansys2_mcp_server.git
cd plansys2_mcp_server
# Set up ROS 2 environment variables if needed
export ROS_DOMAIN_ID=0
uv sync

Or install directly from the repository:

uv add git+https://github.com/ajtudela/plansys2_mcp_server.git

Docker

Build the image

Build the image:

docker build -t plansys2_mcp_server:latest .

Pull the image

Pull the latest image from the Docker registry:

docker pull ghcr.io/ajtudela/plansys2_mcp_server:latest

Usage

Running with uv

uv run plansys2-mcp-server

Running in HTTP mode

TRANSPORT_MODE=http HTTP_HOST=0.0.0.0 HTTP_PORT=3001 uv run plansys2-mcp-server

Configuration example for Claude Desktop/Cursor/VSCode

Add this configuration to your application's settings (mcp.json):

Using uv (stdio transport)

{
  "plansys2 mcp server": {
    "type": "stdio",
    "command": "uv",
    "args": [
      "run",
      "--directory",
      "/path/to/plansys2_mcp_server",
      "plansys2-mcp-server"
    ],
    "env": {
      "ROS_DOMAIN_ID": "0",
      "ROS_LOCALHOST_ONLY": "1",
      "TRANSPORT_MODE": "stdio",
      "LOG_LEVEL": "INFO"
    }
  }
}

Using Docker (stdio transport)

"plansys2 mcp server": {
    "type": "stdio",
    "command": "docker",
    "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/ajtudela/plansys2_mcp_server"
    ],
    "env": {
      "ROS_DOMAIN_ID": "0",
      "ROS_LOCALHOST_ONLY": "1",
      "TRANSPORT_MODE": "stdio",
      "LOG_LEVEL": "INFO"
    }
}

Using HTTP transport

"plansys2 mcp server": {
  "type": "http",
  "url": "http://localhost:3001/mcp",
  "env": {
    "TRANSPORT_MODE": "http",
    "LOG_LEVEL": "INFO"
  }
}