pypddlengine

A Python PDDL engine and MCP (Model Context Protocol) server that enables AI agents to interactively explore PDDL planning problems.

Features

• Standalone PDDL engine — parse, validate, and execute PDDL domains and problems
• Interactive plan exploration — step through plans, query reachable actions, inspect world state
• MCP server — expose the engine as tools to any MCP-compatible AI agent (Claude Desktop, VS Code, etc.)
• Python API — direct programmatic access with structured JSON responses
• Session logging — record agent interactions to CSV/JSON for analysis

Supported PDDL Features

Feature	Requirement	Notes
STRIPS	:strips	Basic actions, positive/negative preconditions & effects
Typing	:typing	Typed objects/parameters, type hierarchies
Equality	:equality	(= ?x ?y) in preconditions
Negative preconditions	:negative-preconditions	(not ...) in preconditions and goals
Disjunctive preconditions	:disjunctive-preconditions	(or ...) in preconditions
Existential preconditions	:existential-preconditions	(exists (?x - type) ...)
Universal preconditions	:universal-preconditions	(forall (?x - type) ...) in preconditions
Conditional effects	:conditional-effects	(when ...) and (forall ... effect)
Implication	:adl	(imply ...) in preconditions
Numeric fluents	:numeric-fluents	increase, decrease, assign, scale-up, scale-down
Action costs / metric	:action-costs	(total-cost) with (:metric minimize ...)
Constants	—	:constants in domain

Unsupported PDDL Features

Feature	Notes
Durative actions (:durative-actions)	Raises an explicit error with a descriptive message
Derived predicates (:derived)	Not parsed; will fail on load
Maximize metric	Only minimize is supported
Arithmetic in conditions	Numeric expressions like (+ ?x ?y) in preconditions are not supported

Installation

git clone https://github.com/kgoe-ait/pypddlengine
cd pypddlengine
uv sync

Or install from PyPI (once published):

pip install pypddlengine

Usage

Python API — Simulator

from pypddlengine.engine import Simulator

sim = Simulator(domain_str, problem_str, plan_str)
sim.step_all()
print(sim.is_goal_reached())

Step through manually:

sim = Simulator(domain_str, problem_str)
sim.step(("move", ("loc1", "loc2")))
print(sim.get_executable_actions())
print(sim.is_goal_reached())

Python API — Exploration API

Higher-level API with structured JSON responses, designed for AI agent tool use:

from pypddlengine.api import PDDLExplorationAPI

api = PDDLExplorationAPI(domain_str, problem_str)
actions = api.get_available_actions()        # {"count": 4, "actions": [...]}
result  = api.execute_action("move", ("a", "b"))  # {"success": true, ...}
api.is_goal_reached()                        # {"goal_reached": false, ...}
api.reset()

Session Logger

Wraps the exploration API and logs every interaction to CSV/JSON:

from pypddlengine.session_logger import PDDLSessionLogger

session = PDDLSessionLogger(domain_str, problem_str, session_id="experiment_1")
session.execute_action("move", ["loc1", "loc2"])
session.export_to_csv("session.csv")
session.export_to_json("session.json")
session.print_summary()

MCP Server (Claude Desktop)

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "pddl-engine": {
      "command": "uv",
      "args": ["run", "python", "-m", "pypddlengine.server"],
      "cwd": "/path/to/pypddlengine"
    }
  }
}

MCP Server (VS Code)

Already configured in .vscode/mcp.json — works out of the box when opening this project.

MCP Tools

Once connected, the AI agent can use these tools:

Tool	Description
pddl_init	Initialize session with domain and problem PDDL strings
pddl_init_from_files	Initialize session from domain and problem file paths
pddl_get_available_actions	Get all executable actions in current state
pddl_execute_action	Execute an action by name and arguments
pddl_get_current_state	View all true predicates and fluents
pddl_is_goal_reached	Check if goal conditions are met
pddl_reset	Reset to initial state
pddl_get_action_history	Review actions taken so far
pddl_get_domain	Re-read the PDDL domain definition
pddl_get_problem	Re-read the PDDL problem definition

Running Tests

uv run pytest

Project Structure

pypddlengine/
├── server.py            # MCP server
├── api.py               # Exploration API (structured JSON responses)
├── session_logger.py    # Session logging wrapper
└── engine/              # Core PDDL engine
    ├── simulator.py     # Plan simulation
    ├── parser/          # PDDL lexer & parser
    ├── interpreter/     # Domain/problem interpretation
    └── execution/       # State management & action execution

License

Apache 2.0 — see LICENSE.