# 🤖 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
