turtleSpaces MCP (Model Context Protocol) Integration

Overview

turtleSpaces supports the Model Context Protocol (MCP), enabling AI assistants like Claude and Gemini to interact directly with the Logo programming environment. This integration allows AI models to read, write, and execute Logo code, capture graphics output, and manage projects.

Command Line Options

To enable MCP mode in turtleSpaces, use the following command line options:

• -mcp – Enable MCP server mode
• -mcp-port <port> – Set the MCP server port (default: 1967)

You can also start the MCP from the File menu…

Example Usage

# Start turtleSpaces with MCP enabled on default port 1967
./turtleSpaces -mcp

# Start turtleSpaces with MCP on custom port 8080
./turtleSpaces -mcp -mcp-port 8080

MCP Configuration

For Claude (via claude_cli or similar)

Create or update your MCP configuration file (typically ~/.config/claude/mcp.json or similar):

{
    "mcpServers": {
        "turtleSpaces": {
            "url": "http://localhost:1967/mcp/sse",
            "type": "sse",
            "description": "turtleSpaces MCP server with SSE transport"
        }
    }
}

For Gemini CLI

Add to your Gemini MCP configuration:

{
    "servers": {
        "turtleSpaces": {
            "endpoint": "http://localhost:1967/mcp/sse",
            "transport": "sse",
            "name": "turtleSpaces Logo Environment"
        }
    }
}

Available MCP Tools

The turtleSpaces MCP server provides the following tools for AI interaction:

Core Tools

• app_name – Returns the name of the application
• execute_command – Executes a Logo command in the interpreter
• break – Breaks execution and clears the command prompt

Workspace Management

• read_workspace – Reads the current Logo workspace procedures
• write_workspace – Loads Logo workspace code
• read_proc – Reads a specific procedure from a turtle
• write_proc – Creates or updates a Logo procedure

Turtle Management

• get_turtles – Returns a list of all turtles in the workspace
• get_current_turtle – Returns the current active turtle

Screen and Graphics

• get_graphics_screen – Captures the current graphics screen and saves it as a PNG file
• get_text_screen – Returns the text content of the screen buffer

Help and Documentation

• get_help – Returns help information for a Logo command
• get_commands – Returns all available Logo commands and functions

Project Management

• user_list_projects – Returns a list of user projects with name and description
• user_load_project – Loads a user project by name
• user_save_project – Saves the current project
• examples_list_projects – Returns a list of example projects with ID, name, description and tags
• examples_load_project – Loads an example project by ID

Example AI Assistant Usage

Once configured, AI assistants can interact with turtleSpaces using natural language. Here are some example interactions:

User: "Draw a square with side length 100"
AI: [Uses execute_command to run: REPEAT 4 [FORWARD 100 RIGHT 90]]

User: "Show me what's on the screen"
AI: [Uses get_graphics_screen to capture and display the current graphics]

User: "Create a procedure to draw a hexagon"
AI: [Uses write_proc to create: TO HEXAGON :SIZE
       REPEAT 6 [FORWARD :SIZE RIGHT 60]
     END]

User: "Load the fractal example"
AI: [Uses examples_list_projects to find fractal examples, then examples_load_project to load one]

Troubleshooting

1. Connection Issues: Ensure turtleSpaces is running with the -mcp flag before attempting to connect
2. Port Conflicts: If port 1967 is in use, specify a different port with -mcp-port
3. SSE Transport: The MCP server uses Server-Sent Events (SSE) transport – ensure your AI client supports this

Security Considerations

• The MCP server listens on localhost by default
• No authentication is required for local connections
• Be cautious when exposing the MCP port to external networks