pypddlengine
Python PDDL引擎和 MCP（模型上下文协议） 该服务器使AI代理能够交互式地探索PDDL规划问题。
特性
- 独立PDDL发动机 --解析、验证和执行PDDL域和问题
- 交互式计划探索 --逐步执行计划，查询可执行的操作，检查世界状态
- MCP服务器 --将引擎作为工具暴露给任何兼容MCP的AI代理（Claude Desktop、VS Code等）
- Python API --使用结构化JSON响应进行直接编程访问
- 会话日志记录 --将代理交互记录到CSV/JSON进行分析
支持的PDDL功能
| 功能 | 要求 | 注意事项 |
|---|---|---|
| 条状物 | :strips | 基本行动、积极/消极先决条件和影响 |
| 打字 | :typing | 类型化对象/参数、类型层次结构 |
| 平等 | :equality | (= ?x ?y) 在前提条件下 |
| 负面先决条件 | :negative-preconditions | (not ...) 前提条件和目标 |
| 否定前提条件 | :disjunctive-preconditions | (or ...) 在前提条件下 |
| 存在的先决条件 | :existential-preconditions | (exists (?x - type) ...) |
| 普遍先决条件 | :universal-preconditions | (forall (?x - type) ...) 在前提条件下 |
| 条件效应 | :conditional-effects | (when ...) 和 (forall ... effect) |
| 含义 | :adl | (imply ...) 在前提条件下 |
| 数字分数 | :numeric-fluents | increase, decrease, assign, scale-up, scale-down |
| 行动成本/指标 | :action-costs | (total-cost) 随着 (:metric minimize ...) |
| 常量 | -- | :constants 在域中 |
不支持的PDDL功能
| 功能 | 备注 |
|---|---|
持续行动(:durative-actions) | 用描述性消息引发显式错误 |
派生谓词(:derived) | 未解析；将在负载下失效 |
| 最大化指标 | 仅 minimize 支持 |
| 条件中的算术 | 数值表达式，如 (+ ?x ?y) 不支持先决条件 |
安装
git clone https://github.com/kgoe-ait/pypddlengine
cd pypddlengine
uv sync或者从PyPI安装（发布后）：
pip install pypddlengine用法
Python API-模拟器
from pypddlengine.engine import Simulator
sim = Simulator(domain_str, problem_str, plan_str)
sim.step_all()
print(sim.is_goal_reached())手动完成步骤：
sim = Simulator(domain_str, problem_str)
sim.step(("move", ("loc1", "loc2")))
print(sim.get_executable_actions())
print(sim.is_goal_reached())Python API-探索API
具有结构化JSON响应的高级API，专为AI代理工具使用而设计：
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()会话记录器
将探索API打包，并将每次交互记录到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服务器（克劳德桌面）
添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：
{
"mcpServers": {
"pddl-engine": {
"command": "uv",
"args": ["run", "python", "-m", "pypddlengine.server"],
"cwd": "/path/to/pypddlengine"
}
}
}MCP服务器（VS代码）
已在中配置 .vscode/mcp.json --打开此项目时，它可以开箱即用。
MCP工具
一旦连接，AI代理就可以使用这些工具：
| 工具 | 说明 |
|---|---|
pddl_init | 使用域和问题PDDL字符串初始化会话 |
pddl_init_from_files | 从域和问题文件路径初始化会话 |
pddl_get_available_actions | 获取当前状态下的所有可执行操作 |
pddl_execute_action | 按名称和参数执行操作 |
pddl_get_current_state | 查看所有真实谓词和符 |
pddl_is_goal_reached | 检查是否满足目标条件 |
pddl_reset | 重置为初始状态 |
pddl_get_action_history | 审查迄今采取的行动 |
pddl_get_domain | 重新阅读PDDL域定义 |
pddl_get_problem | 重新阅读PDDL问题定义 |
运行测试
uv run pytest项目结构
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许可证
Apache 2.0——请参阅 许可证.