📚 Improve MCP README (#12022)

* Make the scope of the usage instructions clear (local usage)
* Provide overview of the server's different modes of operation
* Improve npm release instructions
* Remove deprecated multi-user mode documentation

mcp/README.md

@@ -40,14 +40,24 @@ but also the supporting Penpot MCP Plugin
 
 ## Usage
 
-To use the Penpot MCP server, you must
+> [!IMPORTANT]
+> **These instructions are for local MCP server usage only!**
+>
+> The instructions below are for users who want to run the server locally,
+> allowing the server to have access to local files, which can be 
+> relevant for development/coding tasks.
+> 
+> If you need to work only on designs, the centrally hosted **remote MCP server**
+> should be considered instead. 
+> Please refer to the [MCP usage instructions in the help center](https://help.penpot.app/mcp/).
+
+To run the Penpot MCP server locally, you must
  * run the MCP server and connect your AI client to it,
  * run the web server providing the Penpot MCP plugin, and
  * open the Penpot MCP plugin in Penpot and connect it to the MCP server. 
 
 Follow the steps below to enable the integration.
 
-
 ### Prerequisites
 
 The project requires [Node.js](https://nodejs.org/) 20 or later (tested with v22.x).
@@ -161,15 +171,15 @@ This bootstrap command will:
 >     (If you are using a standard commercial model, it almost certainly supports vision already.)
 
 By default, the server provides a Streamable HTTP endpoint at `http://localhost:4401/mcp`.
+Simply configure the client to connect the MCP server by providing the respective URL.
 
 The legacy `/sse` and `/messages` endpoints are no longer supported.
 Clients using the legacy SSE transport must switch to Streamable HTTP at `/mcp`.
 
 You can change the port by setting the `PENPOT_MCP_SERVER_PORT` environment variable
 before starting the server. This endpoint can be used directly by MCP clients that support Streamable HTTP.
-Simply configure the client to connect the MCP server by providing the respective URL.
 
-#### Configuring your client
+#### Automatically configuring your client
 
 You can configure your client with the [add-mcp](https://github.com/neon-solutions/add-mcp) helper.
 Simply call 
@@ -286,22 +296,33 @@ The Penpot MCP server can be configured using environment variables.
 |-------------------------------------------|-----------------------------------------------------------------------------------------|--------------|
 | `PENPOT_MCP_PLUGIN_SERVER_HOST`           | Address on which the plugin web server listens (single address or comma-separated list) | (local only) |
 
-## Beyond Local Execution
+## The Server's Modes of Operation
 
-The above instructions describe how to run the MCP server and plugin server locally.
+The above instructions describe how to run the MCP server and plugin server locally,
+for a single user – its simplest mode of operation.
 
-The Penpot MCP server can also support multiple remote users simultaneously
+The server supports additional modes of operation, which are intended for
-in [multi-user mode](docs/multi-user-mode.md).
+non-local usage (and which are relevant to hosted deployments only).
+Some of the aforementioned configuration options control these modes.
 
-To run the server remotely (even for a single user),
+* **remote mode**:  
-you may set the following environment variables to configure the two servers
+  In remote mode, the server is not assumed to be accessed by a local user on the same machine,
-(MCP server & plugin server) appropriately:
+  with corresponding limitations being enforced (tools offering local file system access are restricted/disabled).
- * `PENPOT_MCP_REMOTE_MODE=true`: This ensures that the MCP server is operating
-   in remote mode, with local file system access disabled.
- * `PENPOT_MCP_SERVER_HOST` and `PENPOT_MCP_PLUGIN_SERVER_HOST`:
-   Set these according to your requirements for remote connectivity.
-   To bind all interfaces, use `0.0.0.0` (use caution in untrusted networks).
 
+* **multi-user mode**:  
+  In multi-user mode, the server can be accessed by multiple users simultaneously.
+  This mode always implies *remote mode*.
+  User tokens are passed to the server both when connecting an MCP client and when establishing
+  plugin connections, associating each connection with the respective user and allowing tasks to be routed to the correct Penpot instance.
+  This mode is intended for hosted deployments using the integrated version of the Penpot MCP plugin, 
+  which automatically sends the user token to the server when establishing WebSocket connections.
+  It is enabled by running the server with the `--multi-user` flag.
+
+* **multi-instance mode**:  
+  In multi-instance mode, multiple instances of the MCP server can be run in parallel (load balancing).
+  This can result in connections from the same user being owned by different server instances,
+  making it necessary to dispatch tasks to the correct instance. This is handled through Redis,
+  and the mode is thus enabled by setting the environment variable providing the Redis connection URI.
 
 ## Development
 
@@ -312,7 +333,8 @@ you may set the following environment variables to configure the two servers
   - Ensure that at least the major, minor and patch components of the version are always up-to-date.
   - The MCP plugin assumes that a mismatch between the MCP version and the Penpot version (as returned by the API) 
     indicates incompatibility, resulting in the display of a warning message in the plugin UI.
-* Packaging and publishing: 
+* Packaging and publishing:
-  1. Ensure release version is set correctly in package.json (call `bash scripts/set-version` to update it automatically)
+  1. Ensure that the API type data is up-to-date (see above).
-  2. Create npm package: `bash scripts/pack` (creates `penpot-mcp-<version>.tgz` for publishing)
+  2. Ensure release version is set correctly in package.json (call `bash scripts/set-version` to update it automatically)
-  3. Publish to npm: `npm publish penpot-mcp-<version>.tgz --access public`
+  3. Create npm package: `bash scripts/pack` (creates `penpot-mcp-<version>.tgz` for publishing)
+  4. Publish to npm: `npm publish penpot-mcp-<version>.tgz --access public`

mcp/docs/multi-user-mode.md

@@ -1,41 +0,0 @@
-# Multi-User Mode
-
-> [!WARNING]
-> Multi-user mode is under development and not yet fully integrated.
-> This information is provided for testing purposes only.
-
-The Penpot MCP server supports a multi-user mode, allowing multiple Penpot users
-to connect to the same MCP server instance simultaneously.
-This supports remote deployments of the MCP server, without requiring each user
-to run their own server instance.
-
-## Limitations
-
-Multi-user mode has the limitation that tools which read from or write to
-the local file system are not supported, as the server cannot access
-the client's file system. This affects the import and export tools.
-
-## Running Components in Multi-User Mode
-
-To run the MCP server and the Penpot MCP plugin in multi-user mode (for testing),
-you can use the following command:
-
-```shell
-npm run bootstrap:multi-user
-```
-
-This will:
-* launch the MCP server in multi-user mode (adding the `--multi-user` flag),
-* build and launch the Penpot MCP plugin server in multi-user mode.
-
-See the package.json scripts for both `mcp-server` and `penpot-plugin` for details.
-
-In multi-user mode, users are required to be authenticated via a token.
-
-* This token is provided in the URL used to connect to the MCP server,
-  e.g. `http://localhost:4401/mcp?userToken=USER_TOKEN`.
-* The same token must be provided when connecting the Penpot MCP plugin
-  to the MCP server.    
-  In the future, the token will, most likely be generated by Penpot and
-  provided to the plugin automatically.
-  :warning: For now, it is hard-coded in the plugin's source code for testing purposes.