mirror of
https://github.com/penpot/penpot.git
synced 2026-10-03 09:16:15 +00:00
📚 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
This commit is contained in:
Dr. Dominik Jain
GitHub
parent
1554847d40
commit
3a0ed93360
@ -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
|
||||
in [multi-user mode](docs/multi-user-mode.md).
|
||||
The server supports additional modes of operation, which are intended for
|
||||
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),
|
||||
you may set the following environment variables to configure the two servers
|
||||
(MCP server & plugin server) appropriately:
|
||||
* `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).
|
||||
* **remote mode**:
|
||||
In remote mode, the server is not assumed to be accessed by a local user on the same machine,
|
||||
with corresponding limitations being enforced (tools offering local file system access are restricted/disabled).
|
||||
|
||||
* **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:
|
||||
1. Ensure release version is set correctly in package.json (call `bash scripts/set-version` to update it automatically)
|
||||
2. Create npm package: `bash scripts/pack` (creates `penpot-mcp-<version>.tgz` for publishing)
|
||||
3. Publish to npm: `npm publish penpot-mcp-<version>.tgz --access public`
|
||||
* Packaging and publishing:
|
||||
1. Ensure that the API type data is up-to-date (see above).
|
||||
2. Ensure release version is set correctly in package.json (call `bash scripts/set-version` to update it automatically)
|
||||
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`
|
||||
|
||||
@ -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.
|
||||
Loading…
x
Reference in New Issue
Block a user