# 🤖 Blocksworld Simulation MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that enables Large Language Models (LLMs) to interact with the [Blocksworld Simulation](https://github.com/hsu-aut/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](https://github.com/hsu-aut/blocksworld_simulation#-quick-start)
   - Make sure the simulation is started before using the MCP server

### Installation

```bash
# 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`

```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`:

```python
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](https://github.com/hsu-aut/blocksworld_simulation)** - The visual simulation environment this server connects to