pddl-mcp-server by NBNBTM - MCP Server

PDDL MCP Server

A PDDL planning server based on the FastMCP framework, providing natural language to PDDL planning conversion, execution, and batch processing capabilities.

✨ Features

🗣️ Natural Language Processing: Generate PDDL planning tasks from natural language descriptions
🤖 Automatic Problem Generation: Create PDDL problem files based on task parameters
📦 Batch Task Processing: Run multiple tasks in batch and generate detailed execution reports
🔒 Type Safety: Data validation and type checking with Pydantic
⚙️ Configuration Validation: Built-in configuration and system info checking

📁 Project Structure

pddl-mcp/
├── core/                   # Core modules
├── templates/              # PDDL template files
├── tasks/                  # Task configuration files
├── output/                 # Output directory
├── config.py               # Configuration management
├── constants.py            # Constants
├── error_handler.py        # Error handling
├── server.py               # MCP server
├── test_server.py          # Test suite
├── .env                    # Environment variables
└── requirements.txt        # Dependencies

⚙️ Installation & Setup

1. Install Dependencies

pip install -r requirements.txt

2. Configure Fast Downward

git clone https://github.com/aibasel/downward.git
cd downward
./build.py

3. Environment Configuration

Copy .env.example to .env and set:

FAST_DOWNWARD_PATH=/path/to/fast-downward.py
PDDL_DOMAIN_PATH=./templates/domain.pddl

🔧 MCP Client Configuration

Claude Desktop

Find the config file:
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
Add server config:

{
  "mcpServers": {
    "pddl-planner": {
      "command": "python",
      "args": ["d:/PDDL/pddl-mcp/server.py"],
      "cwd": "d:/PDDL/pddl-mcp",
      "env": {
        "FAST_DOWNWARD_PATH": "/path/to/fast-downward.py"
      }
    }
  }
}

Restart Claude Desktop

Trae AI IDE

Open MCP Settings:
- Click settings → MCP Servers
- Or use shortcut Ctrl+Shift+M
Add new server:

{
  "name": "PDDL Planner",
  "command": "python",
  "args": ["d:/PDDL/pddl-mcp/server.py"],
  "cwd": "d:/PDDL/pddl-mcp",
  "description": "PDDL planning and NLP server"
}

Test Connection

🚀 Running & Usage

Start the Server

python server.py

You should see:

✅ PDDL MCP Server initialized
🚀 Starting FastMCP server...

Run Tests

python test_server.py

Batch Task Processing

python core/batch_runner.py

💬 Prompt Examples

Basic Planning Task

Please plan a robot task:
- Robot: robot1
- Start: room1
- Goal: room3
- Task type: delivery

Generate a complete PDDL plan.

Natural Language Planning

Robot r2 needs to move from the warehouse to the office. Please generate a complete movement plan.

Multi-Robot Coordination

I have a multi-robot coordination task:
1. Robot r1 in room1, needs to go to room5
2. Robot r2 in room3, needs to go to room2
Please generate an individual plan for each robot and analyze possible path conflicts.

Batch Task Processing

Please batch process the following robot tasks:
1. r1: room1 → room3 (delivery)
2. r2: room2 → room4 (patrol)
3. r3: room5 → room1 (maintenance)

Generate a batch execution report including execution time and success rate for each task.

System Configuration & Diagnostics

Check the configuration status of the PDDL planning system, including:
- Fast Downward path
- Environment variables
- Dependency versions
- System performance

My PDDL planning task failed with error: [error message]
Please diagnose the problem and provide a solution.

🧪 Testing Guide

Prerequisites

Python 3.8+
Dependencies installed (pip install -r requirements.txt)
.env configured
Trae IDE imported project

Server Status

MCP server should show as connected in Trae IDE

Testing Methods

1. Trae IDE Direct Test

System config check
Simple planning task
Natural language planning
Multi-robot coordination
Batch task processing

2. Command Line

Start server: python server.py
Run test suite: python test_server.py
Batch tasks: python core/batch_runner.py

Expected Results

System config check returns JSON with config path, Fast Downward path, env status, output dir
Planning tasks generate:
- PDDL problem files (output/pddl/)
- Plan files (output/plan/)
- Explanation files (output/explanation/)
Batch tasks generate:
- Batch report (output/report.json)
- Analysis (output/report.md)
- Individual task files

Common Test Scenarios

Basic move task: single robot, simple path, expect 1-3 steps
Complex path: robot passes multiple rooms, expect optimal path
Multi-robot coordination: possible path conflicts, expect conflict analysis and solution
Error handling: invalid task params, expect clear error message

Troubleshooting

Server fails to start:
1. Check dependencies: pip install -r requirements.txt
2. Check Python version: python --version
3. Check .env config
Planning fails:
1. Validate Fast Downward path
2. Check templates/domain.pddl
3. Check output directory permissions
MCP connection fails:
1. Restart Trae IDE
2. Check .mcp.json config
3. Ensure server port is free
Files not generated:
1. Check output/ directory permissions
2. Ensure enough disk space
3. Validate file paths

Performance Testing

Response time: Simple task < 2s (run multiple times)
Concurrency: Multiple tasks at once, expect no conflict
Large-scale tasks: 10+ robots, expect successful coordination

Test Checklist

Test Report Template

Test Date: [date]
Environment: [OS, Python version]
Scope: [modules tested]

Results:
✅ Passed
❌ Failed
⚠️  Issues

Performance:
- Avg response time: [time]
- Success rate: [percent]
- Resource usage: [memory, CPU]

Suggestions:
[improvements]

Next Steps

Expand test cases for more complex scenarios
Optimize performance based on results
Add new planning algorithms or features
Improve documentation and API reference

Note: For issues during testing, check logs in the output/ directory or run python test_server.py for diagnostics.

📄 License

MIT License