MCP Support

The desktop version of Cinderella offers access via a so-called MCP server that enables AI assistants to programmatically access Cinderella's functionality. In particular, you can access the current constructions, modify them and evaluate CindyScript functions. Also, it is possible to simulate user input (see Modes and Actions below).

Preliminary

The current experimental MCP implementation is available in the beta version of Cinderella and might change without notice in future versions of Cinderella.

MCP, the Model Context Protocol, is an open standard that lets AI assistants use external programs as tools. An assistant that is connected to Cinderella can, for example, draw a construction you describe, look at the result, write the scripts of a construction, and correct its own mistakes, because Cinderella reports errors back to it.

Configuration hints¶

Two things are needed: the MCP server of Cinderella has to be switched on, and the AI assistant has to be told where to find it.

Switching on the MCP server¶

Open the Inspector, choose the section Construction Behavior and tick Enable MCP Server under Advanced Options. Cinderella remembers this setting, so the server is started automatically the next time. Untick the box to stop it again.

While the server is running, it is available at the address

http://localhost:3001/mcp

It speaks the Streamable HTTP transport of MCP. If port 3001 is already used by another program, the server is not started. Start Cinderella with the Java system property cinderella.mcp.port to choose another port, for example -Dcinderella.mcp.port=3005. The property -Dcinderella.mcp=true switches the server on regardless of the setting in the Inspector.

Claude Code¶

Claude Code connects to the server directly. Register it once with the following command:

claude mcp add --transport http cinderella http://localhost:3001/mcp

Claude Desktop¶

Claude Desktop starts local MCP servers as programs and talks to them through their standard input and output. A small bridge program translates between this and the address of Cinderella. One such bridge is mcp-remote, which needs Node.js to be installed. Add the following entry to the file claude_desktop_config.json, which you can open from the settings of Claude Desktop (Developer → Edit Config), and restart Claude Desktop:

{
  "mcpServers": {
    "cinderella": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:3001/mcp"]
    }
  }
}

Cinderella has to be running, with the MCP server switched on, before Claude Desktop is started.

ChatGPT and other assistants¶

Any assistant that runs on your own computer and supports MCP can be connected in one of the two ways shown above: with the address of the server, if it supports the Streamable HTTP transport, or through a bridge like mcp-remote otherwise.

Assistants that run in a web browser or on the servers of their provider, like ChatGPT, contact MCP servers over the internet. They cannot reach a program on your computer, and Cinderella deliberately refuses such requests (see below). Such an assistant can therefore not be connected to Cinderella directly. It takes a proxy program on your computer that passes the requests on to Cinderella; this is not described here.

Security¶

An assistant that is connected to Cinderella can do what you can do in Cinderella, including running scripts and actions like saving or closing a construction. Keep this in mind:

The server only accepts requests from your own computer. Requests from other computers, and from web pages that are open in your browser, are refused.
Every program on your computer can use the server while it is switched on. Switch it off in the Inspector when you do not need it.
A web application that runs on your computer and is supposed to control Cinderella from the browser must be allowed explicitly with the Java system property cinderella.mcp.allowedOrigins, for example -Dcinderella.mcp.allowedOrigins=https://example.org.

Trying it out¶

Start a new conversation with the assistant and ask it, for example: “Construct a triangle and its circumcircle in Cinderella.” The assistant should find the open construction, draw the triangle and the circle, and show you a picture of the result.

What the assistant can do¶

The MCP server offers the following tools to the assistant. You do not call them yourself; the assistant chooses them as needed.

Tool	Purpose
`get_open_constructions`, `get_version`	list the open constructions; report the version of Cinderella
`get_viewports`, `get_viewport_image`	list the views of a construction with their visible range; get a picture of a view
`list_modes`, `list_actions`, `get_mode_help`	list modes and actions and look up what this manual says about them
`set_mode`, `do_action`	select a mode; carry out an action
`simulate_mouse`	click, drag or move the mouse in a view, at positions given in the coordinates of the construction
`run_cindyscript`	execute CindyScript code and return its result, its console output and its errors
`get_scripts`, `add_script`, `set_script`, `remove_script`	read and change the scripts in the CindyScript Editor
`get_cindyscript_help`	look up a function in the CindyScript reference

Names of modes and actions, hints and manual texts are given to the assistant in English, unless it asks for the language of the user interface.

Modes and Actions¶

Preliminary

The programmatic access to modes and actions is preliminary and might be dropped from or changed in future versions of Cinderella.

Everything a user does in Cinderella by choosing a tool from the toolbar or an entry from a menu is either a mode or an action. A mode is a tool that reacts to the mouse in a view, such as Move, Add a Point or Add a Line (see Interactive Modes). It stays selected until another mode is chosen. An action is a command that is carried out at once, such as Undo or Select All. The following two operators make modes and actions available to scripts.

Modes and actions are named by strings that look like constructor calls. The name consists of the class of the mode or action (without the leading de.cinderella.) and, in parentheses, an argument that is needed by some modes:

Name	Meaning
`"modes.Move()"`	the move mode
`"modes.SingleAdd()"`	add a single point
`"modes.MultiAdd(algorithms.Join)"`	add a line through two points
`"modes.MultiAdd(algorithms.CircleMP)"`	add a circle by center and point
`"actions.Undo()"`	undo the last operation
`"actions.SelectAll()"`	select all elements
`"actions.Fetch()"`	zoom the view to show all points

These are the same names that are used to compose menus and toolbars in the configuration file cinderella2.properties, which lists all of them.

Selecting a mode: `changemode(<string>)`¶

Description: This operator selects the mode with the name <string>, as if the user had chosen it from the toolbar. The mode is then used for the following mouse interactions of the user. The operator returns the name of the mode that is selected afterwards. If there is no mode with the given name, the move mode is selected.

Example: The following line, placed for instance in a script of a button, lets the user draw a line next:

changemode("modes.MultiAdd(algorithms.Join)");

Carrying out an action: `doaction(<string>)`¶

Description: This operator carries out the action with the name <string>, as if the user had chosen it from a menu. The mode that is selected does not change. Actions that open a dialog, such as loading or saving a construction, wait until the user has closed the dialog.

Example: The following code selects all points and deletes them:

doaction("actions.SelectPoints()");
doaction("actions.Delete()");

See also: Interaction with Geometry for operators that create, move and remove elements directly.