Add embedded MCP server exposing MapMap control over local HTTP (#612)

* Add embedded MCP server exposing MapMap control over local HTTP

Adds a native Model Context Protocol server (QHttpServer, JSON-RPC 2.0)
running on the GUI thread, exposing sources, layers, playback, project
I/O and state read-back to MCP clients at http://localhost:<port>/mcp.

The port is configurable via QSettings (mcpListeningPort, default 49452)
and a new -m/--mcp-port CLI flag; 0 disables the server. Requires the
QtHttpServer module (and its QtWebSockets dependency).

Add port preference UI

Adapt McpServer to Paint->Source and Mapping->Layer renames. Fix
QHttpServer::listen() removal in Qt 6.11 by using QTcpServer::listen()
with QHttpServer::bind(). Add MCP port spinbox to Preferences Controls
tab (0 disables the server).

* Make MCP server build optional when qthttpserver is unavailable

Use qtHaveModule(httpserver) to conditionally enable MCP support,
guarded by HAVE_MCP preprocessor define throughout the codebase.
This fixes CI builds on platforms without the Qt HttpServer module.

* Add create_layer tool to MCP server for triangle, quad and ellipse shapes

Move addMesh/addTriangle/addEllipse from private to public slots in
MainWindow so the MCP server can call them directly.

* Add Claude Code skill for controlling MapMap via MCP

* Add set_vertices MCP tool and update skill doc

Allows setting the output shape vertices of a layer via MCP.
Documents vertex ordering and the new tool in the skill file.

* Guard mcpListeningPort write in writeSettings with HAVE_MCP

The member variable is only declared under #ifdef HAVE_MCP,
so writing it in writeSettings also needs the guard to fix
the build when qthttpserver is unavailable.

Author: aalex

.claude/skills/mapmap-mcp.md

@@ -0,0 +1,103 @@
+---
+name: mapmap-mcp
+description: Control MapMap via its embedded MCP server over local HTTP. Use this skill whenever the user asks to create, modify, inspect, or control sources, layers, playback, or project state in the running MapMap instance.
+trigger: When the user wants to interact with the running MapMap application - creating sources/layers, controlling playback, querying state, modifying properties, loading/saving projects.
+---
+
+# MapMap MCP Control
+
+MapMap exposes a JSON-RPC 2.0 MCP server at `http://localhost:49452/mcp` (POST only).
+
+## How to call
+
+```bash
+curl -s -X POST http://localhost:49452/mcp \
+  -H 'Content-Type: application/json' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"TOOL_NAME","arguments":{...}}}' \
+  | python3 -m json.tool
+```
+
+Increment the `id` for each call in a session. Always pipe through `python3 -m json.tool` for readable output.
+
+### First call: initialize
+
+Before any tool calls, send an initialize request:
+
+```bash
+curl -s -X POST http://localhost:49452/mcp \
+  -H 'Content-Type: application/json' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"claude","version":"1.0"}}}'
+```
+
+## Available tools
+
+### Playback & Project
+| Tool | Args | Description |
+|------|------|-------------|
+| `play` | — | Start playback |
+| `pause` | — | Pause playback |
+| `rewind` | — | Rewind to start |
+| `quit` | — | Quit MapMap |
+| `clear_project` | — | Clear all sources and layers |
+| `load_project` | `path` (string, required) | Load a .mmp project file |
+| `save_project` | `path` (string, required) | Save project to file |
+| `set_fps` | `fps` (number, required, > 0) | Set playback frame rate |
+
+### Sources
+| Tool | Args | Description |
+|------|------|-------------|
+| `create_color_source` | `color` (string, required: "#rrggbb" or name) | Create solid-color source |
+| `create_media_source` | `uri` (string, required), `is_image` (bool, default false) | Import image or video |
+| `delete_source` | `id` (int, required) | Delete source and its layers |
+
+### Layers
+| Tool | Args | Description |
+|------|------|-------------|
+| `create_layer` | `source_id` (int, required), `shape` (string, required: "triangle", "quad", or "ellipse") | Create a layer with a shape for a source |
+| `delete_layer` | `id` (int, required) | Delete a layer |
+| `duplicate_layer` | `id` (int, required) | Duplicate a layer |
+| `move_layer` | `id` (int, required), `index` (int, required, 0=bottom) | Move layer in stack |
+| `set_layer_visible` | `id` (int), `value` (bool) | Show/hide layer |
+| `set_layer_solo` | `id` (int), `value` (bool) | Solo a layer |
+| `set_layer_locked` | `id` (int), `value` (bool) | Lock/unlock layer |
+
+### Geometry
+| Tool | Args | Description |
+|------|------|-------------|
+| `set_vertices` | `id` (int, layer id), `vertices` (array of `{x, y}`) | Set the output vertices of a layer's shape |
+
+Vertex order is **clockwise from top-left**: top-left, top-right, bottom-right, bottom-left.
+- Quad: 4 vertices
+- Triangle: 3 vertices (bottom-left, bottom-right, top-center)
+- Ellipse: 5 vertices (left, top, right, bottom, rotation-handle)
+
+### Properties
+| Tool | Args | Description |
+|------|------|-------------|
+| `set_property` | `kind` ("source"/"layer"), `id` (int), `property` (string), `value` (any) | Set arbitrary property |
+
+Common properties:
+- **Source (color):** `color` ("#rrggbb"), `name`, `opacity` (0.0-1.0), `locked`
+- **Layer:** `name`, `opacity`, `visible`, `solo`, `locked`, `depth`
+
+### Introspection
+| Tool | Args | Description |
+|------|------|-------------|
+| `get_state` | — | Get playing, fps, counts, current selection |
+| `list_sources` | — | List all sources |
+| `list_layers` | — | List all layers |
+| `get_source` | `id` (int) | Get all properties of a source |
+| `get_layer` | `id` (int) | Get all properties of a layer |
+
+## Typical workflow
+
+1. Create a source (`create_color_source` or `create_media_source`)
+2. Create a layer for it (`create_layer` with `source_id` from step 1)
+3. Position the layer (`set_vertices` with the desired corner positions)
+4. Adjust properties as needed (`set_property`, `set_layer_visible`, etc.)
+5. Control playback (`play`, `pause`, `rewind`)
+
+## Response format
+
+Success returns `{"isError": false, "content": [...]}` with optional `structuredContent`.
+Errors return `{"isError": true, "content": [{"type":"text","text":"error message"}]}`.

src/app/main.cpp

@@ -104,6 +104,13 @@ int main(int argc, char *argv[])
     "Use OSC port number <osc-port>.", "osc-port", "");
   parser.addOption(oscPortOption);
 
+#ifdef HAVE_MCP
+  // --mcp-port option
+  QCommandLineOption mcpPortOption(QStringList() << "m" << "mcp-port",
+    "Use MCP server port number <mcp-port> (0 to disable).", "mcp-port", "");
+  parser.addOption(mcpPortOption);
+#endif
+
   // --lang option
   QCommandLineOption localeOption(QStringList() << "l" << "lang",
     "Use language <lang>.", "lang", "");
@@ -212,6 +219,12 @@ int main(int argc, char *argv[])
   if (parser.isSet(verboseOption))
     win->setVerbose(true);
 
+#ifdef HAVE_MCP
+  QString mcpPortValue = parser.value("mcp-port");
+  if (mcpPortValue != "")
+    win->setMcpPort(mcpPortValue);
+#endif
+
   bool optionOk;
   qreal fps = parser.value("frame-rate").toDouble(&optionOk);
   if (optionOk)