plansys2_mcp_server

# PlanSys2 MCP Server   [](https://github.com/ajtudela/plansys2_mcp_server/actions/workflows/python-package.yml) [](https://github.com/ajtudela/plansys2_mcp_server/actions/workflows/docker_image.yml)   [](https://codecov.io/gh/ajtudela/plansys2_mcp_server) 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: ```bash cp .env.example .env ``` 2. Edit `.env` to customize settings: ```bash # 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](https://docs.ros.org/en/jazzy/): Middleware for robotics (Jazzy) - [PlanSys2](https://github.com/PlanSys2/ros2_planning_system): Automated planning framework - [fastmcp](https://github.com/jlowin/fastmcp): MCP server framework ### Install with uv (recommended) Clone the repository and install with uv: ```bash 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: ```bash uv add git+https://github.com/ajtudela/plansys2_mcp_server.git ``` ### Docker #### Build the image Build the image: ```bash docker build -t plansys2_mcp_server:latest . ``` #### Pull the image Pull the latest image from the Docker registry: ```bash docker pull ghcr.io/ajtudela/plansys2_mcp_server:latest ``` ## Usage ### Running with uv ```bash uv run plansys2-mcp-server ``` ### Running in HTTP mode ```bash 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) ```json { "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) ```json "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 ```json "plansys2 mcp server": { "type": "http", "url": "http://localhost:3001/mcp", "env": { "TRANSPORT_MODE": "http", "LOG_LEVEL": "INFO" } } ```