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

⚙️ Installation & Setup

1. Install Dependencies

2. Configure Fast Downward

3. Environment Configuration

Copy .env.example to .env and set:

🔧 MCP Client Configuration

Claude Desktop

1. 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

2. Add server config:

3. Restart Claude Desktop

Trae AI IDE

1. Open MCP Settings:

   • Click settings → MCP Servers

   • Or use shortcut Ctrl+Shift+M

2. Add new server:

3. Test Connection

🚀 Running & Usage

Start the Server

You should see:

Run Tests

Batch Task Processing

💬 Prompt Examples

Basic Planning Task

Natural Language Planning

Multi-Robot Coordination

Batch Task Processing

System Configuration & Diagnostics

🧪 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

• System config check

• Simple planning task

• Natural language processing

• File generation

• Multi-robot coordination

• Batch task processing

• Path conflict analysis

• Error handling

• Response time

• Concurrency

• Large-scale tasks

• Memory usage

• Trae IDE integration

• MCP protocol compatibility

• File system operations

• Config management

Test Report Template

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