hsu-aut/blocksworld_mcp-server

🤖 Blocksworld Simulation MCP Server

A Model Context Protocol (MCP) server that enables Large Language Models (LLMs) to interact with the Blocksworld Simulation through tool calls. This allows AI agents or LLMs in general like Claude, ChatGPT, and other MCP-compatible systems to solve planning problems by directly controlling the simulation.

🎯 What is This?

This MCP server exposes the Blocksworld Simulation's REST API as a set of tools that LLMs can use. Instead of just talking about block manipulation, LLMs can actually:

• Execute actions: Pick up, put down, stack, and unstack blocks
• Query state: Get real-time information about block positions and robot status
• Verify plans: Test multi-step plans before execution
• Learn rules: Retrieve the complete set of constraints and preconditions

Perfect for:

• 🔬 AI Planning Research: Test LLM reasoning and planning capabilities
• 🎓 Educational Projects: Demonstrate AI problem-solving in action
• 🧪 Agent Development: Build and test autonomous AI agents
• 📊 Benchmarking: Evaluate LLM performance on classic planning problems

✨ Features

• 7 MCP Tools: Complete set of blocksworld operations exposed as LLM tools
• Rich Descriptions: Each tool includes detailed preconditions and effects
• Plan Verifciation: LLMs can verify plans without executing them
• State Inspection: Query current simulation state at any time
• Rule Discovery: LLMs can learn the rules dynamically
• Type Safety: Pydantic models ensure correct tool usage

🚀 Quick Start

Prerequisites

1. Python 3.10+ installed
2. Blocksworld Simulation running on localhost:5001
   • Follow the simulation setup guide
   • Make sure the simulation is started before using the MCP server

Installation

# Clone the repository
git clone https://github.com/hsu-aut/llmstudy_mcp-server.git
cd llmstudy_mcp-server

# Install dependencies
poetry install

# Run the MCP server
poetry run blocksworld-mcp-server

Using with Claude Desktop

Add this to your Claude Desktop configuration file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "blocksworld": {
      "command": "poetry",
      "args": [
        "--directory",
        "/path/to/llmstudy_mcp-server",
        "run",
        "blocksworld-mcp-server"
      ]
    }
  }
}

Restart Claude Desktop, and the blocksworld tools will be available!

🛠️ Available Tools

The MCP server provides the following tools to LLMs:

1. pick_up

Pick up a block from the ground.

Parameters:

• block (str): The name of the block to pick up

Preconditions:

• Block must be on the ground (not stacked)
• Block must be clear (nothing on top)
• Robot must be idle (not holding anything)

2. unstack

Remove a block from the top of another block.

Parameters:

• block_x (str): The block to remove
• block_y (str): The block underneath

Preconditions:

• Block x must be directly on top of block y
• Block x must be clear
• Robot must be idle

3. put_down

Place the held block on the ground.

Parameters:

• block (str): The name of the block to put down

Preconditions:

• Robot must be holding the specified block
• A free ground position must be available

4. stack

Place the held block on top of another block.

Parameters:

• block_x (str): The block to place (currently held)
• block_y (str): The block to stack on

Preconditions:

• Robot must be holding block x
• Block y must be clear

5. status

Get the current state of the simulation.

Returns:

• Complete JSON object with all block positions, stack configurations, and robot state

6. rules

Get the complete description of blocksworld rules and constraints.

Returns:

• Markdown-formatted text describing the environment, rules, and available actions

7. verify_plan

Verify a multi-step plan without executing it.

Parameters:

• plan (PlanRequest): A sequence of actions to verify

Returns:

• Success message if the plan is verified, or detailed error message indicating which step fails

Note: execute_plan is disabled by default to encourage LLMs to execute actions step-by-step for better reasoning.

📋 Example Usage

Here's how an LLM might use these tools to solve a simple problem:

User: "Stack block A on top of block B"

LLM thought process:
1. Call status() to see current state
2. Call rules() to understand constraints
3. Determine plan: pick_up(A) → stack(A, B)
4. Call verify_plan([pick_up(A), stack(A, B)]) to verify
5. Execute: pick_up(A)
6. Execute: stack(A, B)
7. Confirm success

🔧 Configuration

Changing the Simulation API URL

By default, the MCP server connects to http://localhost:5001. To change this, edit src/blocksworld_simulation_mcp_server/mcp_server.py:

SIM_API = "http://localhost:5001"  # Change this line

📚 Architecture

┌─────────────────────┐           MCP Protocol            ┌──────────────────┐
│   LLM (Claude)      │◄────────────────────────────────►│   MCP Server     │
│                     │      Tool Calls & Responses       │   (This Repo)    │
└─────────────────────┘                                   └──────────────────┘
                                                                    │
                                                           HTTP REST API
                                                                    │
                                                                    ▼
                                                          ┌──────────────────┐
                                                          │  Blocksworld     │
                                                          │  Simulation      │
                                                          │  (localhost:5001)│
                                                          └──────────────────┘

The MCP server acts as a bridge between:

• LLMs that speak the Model Context Protocol
• Blocksworld Simulation that exposes a REST API

🔗 Related Projects

• Blocksworld Simulation - The visual simulation environment this server connects to