@magnolia/mcp-dev-server-setup

Guided setup for the Magnolia MCP Dev Server. One command sets up everything: registry access, your AI tools, the plugins and their settings, and a protected secrets file. Then it checks that the server really starts.

cd path/to/your-magnolia-project
npx @magnolia/mcp-dev-server-setup

Run it from your Magnolia project's directory: the folder that holds your Magnolia workspace, such as a Jumpstart project, a webapp project, or a Maven backend project. When you set the server up for that project only, the setup writes mgnl.mcp.config.json to the directory you run it from, and the server finds it there because it looks for the file from your project upward. The setup also finds a configuration the project already has, and updates it.

This package is on the public npm registry, so it runs before you have access to the Magnolia registry (Nexus). Setting up that access is one of the things it does.

Before you start

You need Node.js. The setup itself runs on Node.js 20.12 or newer. The server needs 22.19 or newer, and the setup tells you if you need to upgrade.

Then collect what applies to you from the list below. Allow about five minutes; with the quick settings path, most runs ask only a handful of questions. Anything you don't have yet can be added later: the setup reports what's missing and where to add it.

• Your Nexus user token. Sign in at https://nexus.magnolia-cms.com/#user/usertoken and choose Access user token. The page shows the token's name code, its pass code, and a Base64-encoded form of the two. The setup asks for the name code, then the pass code; the Base64 form is only for writing ~/.npmrc by hand. The user token is not your Nexus login password. You don't need it if your ~/.npmrc already gives you access.
• Your AI tools. Which of Claude Code, Claude Desktop, Codex, Cursor, VS Code, and Windsurf you use. You can pick several.
• All projects, or one. Either way, run the setup from your Magnolia project's directory (see above).
• Your Magnolia instance. The base URL (default http://localhost:8080), the author instance path (default magnoliaAuthor; many installations are deployed at /), and a username and password. Use an account with only the permissions the work needs, not superuser. Magnolia doesn't have to be running; if it is, the final check finds the author instance path for you.
• How you build templates (CLI plugin). FreeMarker or SPA, and for SPA the framework; the name of your light module; and, for a Maven backend project, the light modules directory.
• A Figma personal access token (Figma designer). In Figma, go to Settings > Security > Personal access tokens and generate a token with the file_content:read and file_metadata:read scopes, plus projects:read to browse a team's projects. Tokens expire after at most 90 days. The setup doesn't ask for one if you choose the localMcp backend, which uses only the local Figma MCP server (the Figma desktop app in Dev Mode) and needs no token.
• A Figma file, or a team ID (Figma designer). The URL of the file you'll work from, copied from the browser; the setup takes the file key from it. To browse all of a team's files instead, the team ID: the number after /team/ in the URL of the team's page in Figma, which needs the token. You need one of the two; the final check warns when neither is set.
• A design system (designer plugin, optional). A Markdown file or a URL. A design-system.md in your project is found without asking.
• Where to keep secrets. ~/.secrets, or ~/.magnolia-mcp/secrets.env just for the MCP server. See 8. Passwords and tokens.

The HTML designer, the log plugin, and the Nodes, Definitions, and Commands APIs work with their defaults. For a run without questions, see --yes.

What the setup does

The setup runs ten steps in order. Each step first checks what is already there and reports it. It only changes something after showing you the change and asking.

| Step | What it checks | What it can change | | ------------------------------ | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | 1. Checking this machine | Node.js version, npm and npx on the PATH, and whether Nexus answers | Nothing | | 2. Access to Magnolia packages | ~/.npmrc sends @magnolia-ai packages to Nexus, and Nexus accepts its credentials | Adds or corrects the Nexus lines in ~/.npmrc | | 3. Available plugins | Which plugins Nexus offers, at which version, and whether it can read their setup questions | Nothing | | 4. AI tools | Which AI tools are installed, and whether each one starts the server correctly | Registers the server with the tools you pick | | 5. Configuration | Whether a configuration exists for all your projects, or for this project | Nothing (you choose where the configuration goes) | | 6. Plugins | Which plugins your configuration declares, and whether newer versions exist | Nothing (you choose plugins and companions) | | 7. Settings | Which settings already have a value, a default, or nothing | Nothing (it collects your answers; see Settings and defaults) | | 8. Passwords and tokens | Which secrets files exist, whether others can read them, and conflicting values | Writes passwords and tokens to the secrets file you pick | | 9. Saving the configuration | The configuration file that would result, as a diff against the current one | Writes mgnl.mcp.config.json | | 10. Final check | Starts the server exactly the way your AI tools will and talks to it | The author instance path, when Magnolia runs under another one and you confirm it |

How it checks your environment

Every check prints one line:

| Mark | Meaning | | ---- | ------------------------------------------------------- | | ✓ | Fine as it is | | ! | Works, but worth a look; the line below says what to do | | ✗ | Broken; the line below says how to fix it | | – | Nothing there yet, which is fine at this point |

A ✗ stops the run, because later steps depend on earlier ones. For example, there's no point registering AI tools for a server npm can't download. A ✗ that a step fixes during the run doesn't stop it. Every ✗ and ! comes with a fix line under it, so start there.

1. Checking this machine

• Node.js: the running version must be at least 22.19, the server's minimum.
• npm and npx: npm --version and npx --version must succeed. Both come with Node.js.
• Nexus: a request to https://nexus.magnolia-cms.com/repository/npm-dx-core/ must be answered. Any answer counts, a 401 included; this only checks the network. Behind a proxy (HTTPS_PROXY and similar), a failed direct request is only a warning: npm uses the proxy, but this check can't.

2. Access to Magnolia packages

The check reads the ~/.npmrc npm uses, which is the one named by NPM_CONFIG_USERCONFIG when that is set. It checks that:

• @magnolia-ai:registry points at Nexus;
• there are credentials for Nexus, stored as _auth. Nexus rejects _authToken, so an _authToken line fails the check;
• Nexus accepts them. The setup asks Nexus for the server package with those credentials, so an expired or mistyped token shows up here, not later as a 401 inside your IDE;
• only you can read the file.

When something is missing or wrong, the setup asks for your Nexus user token. It tries NEXUS_USERNAME and NEXUS_PASSWORD from the environment first, and gives you three attempts. Nexus checks the token before anything is saved. Then the setup offers to update ~/.npmrc: it backs the file up first, changes only the Nexus lines (comments and other registries stay as they were), and makes the file readable only by you. You won't be asked for the token again later in the run.

3. Available plugins

The setup asks Nexus for the latest version of each plugin, and for the setup questions each plugin publishes with it. If Nexus can't provide a plugin's questions, for example because it rate-limits the requests, the setup warns you and that plugin gets no questions. You can set its options in the configuration afterwards.

4. AI tools

The setup supports Claude Code, Claude Desktop, Codex, Cursor, VS Code, and Windsurf. Tools found on this machine are ticked in advance. For each one it reads the existing magnolia-dev entry and flags it when:

• the entry runs a command that no longer exists, or a different command;
• the entry's PATH doesn't include the folder Node.js is in. AI tools started from the Dock or Start menu don't get your shell's PATH, so npx wouldn't find node;
• the entry's PATH has folders npm adds only while it runs something: npx's cache, node_modules/.bin directories, and node-gyp-bin. They come from running the setup through npx, and would make every project see one project's binaries;
• for Claude Desktop, the entry names no project, or another one.

It registers npx -y @magnolia-ai/mcp-dev-server, with the absolute path to npx, in each tool you pick. Claude Code is registered through its own CLI. For the other tools the setup edits their configuration file and backs it up first. It never removes a registration you didn't pick. A tool you pick that is already registered correctly is left as it is, and the setup says so.

Claude Desktop doesn't start the server in your project, so its entry also sets MAGNOLIA_MCP_PROJECT_DIR to the directory you run the setup from. Run from your home directory, the setup sets none and tells you to run it from the project. Claude Desktop works on one project at a time: when its entry already names another project, the setup asks before switching it, and --yes never switches it.

| Tool | Configuration it edits (macOS) | | -------------- | ----------------------------------------------------------------- | | Claude Code | through claude mcp add (~/.claude.json) | | Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json | | Codex | ~/.codex/config.toml (or $CODEX_HOME) | | Cursor | ~/.cursor/mcp.json | | VS Code | ~/Library/Application Support/Code/User/mcp.json | | Windsurf | ~/.codeium/windsurf/mcp_config.json |

On Windows the Claude Desktop and VS Code files are under %APPDATA%. On Linux they are under $XDG_CONFIG_HOME (by default ~/.config).

5. Configuration

The server looks for mgnl.mcp.config.json by walking up from your project, then falls back to ~/.magnolia-mcp/. So you choose between:

• All my projects: ~/.magnolia-mcp/mgnl.mcp.config.json. This is the default, unless this project already has its own configuration.
• Just this project: mgnl.mcp.config.json in the current directory.

If the setup finds an old mgnl.mcp.config.js, it warns you: the server still loads that file, but nothing updates it any more.

6. Plugins

You choose from the catalog. On a first run every plugin is ticked; otherwise the ones your configuration already declares are. For a plugin with companions, the setup then offers those it finds on Nexus:

• the designer plugin offers the Figma and HTML designers;
• the Magnolia API plugin offers the Nodes, Definitions, and Commands APIs. Nodes and Definitions are ticked by default.

8. Passwords and tokens

Passwords and tokens never go into the configuration file. The configuration refers to them as ${NAME}, and the value goes into a secrets file you pick:

• Just for the MCP server: ~/.magnolia-mcp/secrets.env. This is the default, unless you already use ~/.secrets and don't have this file.
• Shared with other tools and your shell: ~/.secrets.

If one of these paths is a directory (some people keep a ~/.secrets/ folder), the setup leaves it alone and uses the other file without asking. The server reads the secrets file itself, so it doesn't need to be sourced from your shell profile.

The setup writes only its own marked block in the file, so the rest of the file stays as it is. It makes the file readable only by you every time. It warns you when your shell environment or an earlier secrets file sets the same name to something else, because those win.

9. Saving the configuration

The setup builds mgnl.mcp.config.json from your answers, on top of whatever the existing file holds that it doesn't ask about (such as skills, site, and plugin options without a question). It shows the change as a diff, with secrets masked, and backs up the old file before saving. A secret that couldn't be stored is left out, never written as a plain value.

10. Final check

This step checks that the server works the way your AI tools will start it:

1. npm can download the server. It runs npm view from your home directory.
2. The server starts. It starts the server with the registered command and a minimal environment, with none of your shell's variables, so every secret must come from the secrets file. Then it completes an MCP handshake. The first start installs the plugins, so your AI tool's first start doesn't time out doing it. When that start is slow, a second, warm start is timed too, and a warning is shown if it's still slow enough that an AI tool may give up waiting.
3. Every plugin has its tools. It asks the server for its tools (tools/list) and checks that every configured plugin contributed some.
4. The server's own checks. It runs mgnl_dev_validate_config.
5. Magnolia, when the Magnolia API plugin is loaded. Magnolia doesn't have to be running:
   • Nothing answers at the base URL. The setup notes that Magnolia isn't running right now. Start it before you use the Magnolia tools.
   • Magnolia answers, but not at the author instance path. The default path is /magnoliaAuthor, and many installations are deployed at /. The setup tries the common paths with Magnolia's Health API, then asks: "Magnolia is running on localhost:8080, but not deployed as /magnoliaAuthor. What is the path to your running instance?" The path it found is the default answer. It checks your answer, and saves it to the configuration after a backup when you confirm.
   • Magnolia answers at the author instance path. The server's mgnl_api_check_connection confirms the connection.

doctor runs the same checks without changing anything. It lists the path it would save.

Settings and defaults

A full run can involve twenty or more settings. Instead of asking each one, the setup first shows what every setting would get without a question:

  What each setting gets unless you change it:
  ✓ found   · default   ✗ required, missing   - optional, empty
  Magnolia Server
    · Magnolia base URL                        default: http://localhost:8080
    · Magnolia password                        default set (hidden)
  CLI Plugin
    · How will you be building templates…      default: freemarker
    · Default light module name                default: my-light-module
  Figma Designer
    ✗ Figma personal access token              required, nothing found
    ✓ Default Figma file key or URL            AbCdEf123 ($FIGMA_FILE_KEY)
    - Figma team ID for browsing projects…     optional, no default
? How do you want to set these?
❯ Keep what was found and the defaults; ask only the 1 required setting marked ✗
  Go through every setting

| Mark | Meaning | | ---- | --------------------------------------------------------------------------------------------- | | ✓ | Found: a value already exists, and the line says where. Secrets always show as hidden | | · | Default: nothing was found, but the plugin has a sensible default | | ✗ | Required, missing: the plugin needs a value, nothing supplies it, and there is no default | | - | Optional, empty: the plugin works without it |

• Keep what was found and the defaults (the quick path, and the default choice) keeps every ✓ and · value, leaves every - setting empty, and asks only the ✗ ones.
• Go through every setting asks each one in turn, offering the found value or the default as the answer.

Some settings are only asked when an earlier answer calls for them: the SPA framework, for example, is asked only if you build with SPA. The overview leaves those out when they don't apply.

A required setting you leave empty is reported at the end, with where to add it. For a secret, that's the variable to add to your secrets file; for anything else, the setting to add to the configuration.

Where a value is found

For each setting, the setup looks in this order and takes the first value it finds:

1. the existing configuration file, including ${NAME} references in it;
2. the environment variable the setting names (for example FIGMA_ACCESS_TOKEN);
3. a secrets file: the file named by MAGNOLIA_MCP_SECRETS, then ~/.magnolia-mcp/secrets.env, then ~/.secrets.

Otherwise the setting gets its default, if it has one.

Your own variables

You may already keep a token under a name of your own, such as FIGMA_PAT or NEXUS_PASSWORD_ENC. When nothing supplies a setting, the setup looks through your environment and secrets files for variables whose name fits it: the setting's family word (FIGMA, NEXUS) together with a word for its role (TOKEN, PAT, PASSWORD, USER, and similar). It lists them by name, never by value, and you can pick one:

? Figma personal access token: use a variable you already have?
❯ FIGMA_PAT (/Users/you/.secrets)
  No, type a value

The configuration then refers to that variable as ${FIGMA_PAT}, and nothing is copied. The overview names these variables too, for example required; you have FIGMA_PAT. The same works for the Nexus user token in the registry-access step.

A variable that is only in your environment, not in a secrets file, is marked as such: AI tools started from the Dock or Start menu don't inherit your shell's variables, so the server would only see it when started from a terminal. Variables another setting already uses, such as FIGMA_FILE_KEY, are never offered for a different one.

Before storing a password or token, the setup also checks whether one of your secrets files already holds exactly that value, under any name. If one does, the configuration refers to that variable and the value isn't stored twice. For example, Nexus credentials read from a working ~/.npmrc that you also keep in ~/.secrets stay where they are.

The server resolves values the same way when it starts, and there a variable set in the real environment wins over a secrets file.

The defaults

These are the settings and defaults as the plugins publish them. The setup always shows the current ones in its overview.

Magnolia Server

| Setting | Default | Variable | | -------------------- | ----------------------- | ------------------------ | | Magnolia base URL | http://localhost:8080 | magnoliaBaseUrl | | Magnolia username | superuser | magnoliaUsername | | Magnolia password | superuser | magnoliaPassword | | Author instance path | magnoliaAuthor | magnoliaAuthorInstance | | JCR login endpoint | none (optional) | jcrLogin | | Evidence folder | none (optional) | evidenceFolder |

The Nexus user token is taken from the registry-access step, so it isn't asked twice.

CLI plugin

| Setting | Default | Notes | | ----------------------- | ---------------------------------------- | --------------------------------- | | Development style | freemarker | freemarker or spa | | SPA framework | React (@magnolia/cli-react-prototypes) | Only asked for SPA projects | | Default light module | my-light-module | | | Light modules directory | none: the CLI default, ./light-modules | Set it for Maven backend projects |

Designer plugin

| Setting | Default | Notes | | ----------------- | ----------------------------------------------------- | --------------------------------------------------- | | Design system | none: design-system.md in the project, if it exists | A Markdown file or a URL | | Design system key | none | A provider-native identifier, e.g. a Figma file key |

Figma designer (a designer plugin companion)

| Setting | Default | Variable | Notes | | --------------------- | --------------------------- | --------------------- | ---------------------------------------------------------- | | Backend strategy | auto | FIGMA_BACKEND | auto tries the REST API, then the local Figma MCP server | | Personal access token | required | FIGMA_ACCESS_TOKEN | Not asked for localMcp; expires after 90 days | | Local Figma MCP URL | http://127.0.0.1:3845/mcp | FIGMA_LOCAL_MCP_URL | Needs the Figma desktop app in Dev Mode | | File key or URL | none (this or a team ID) | FIGMA_FILE_KEY | A Figma URL is accepted; the key is taken from it | | Team ID | none (this or a file key) | FIGMA_TEAM_ID | For browsing a team's projects instead of one file | | API base URL | https://api.figma.com/v1 | FIGMA_API_BASE_URL | |

HTML designer (a designer plugin companion)

| Setting | Default | | ----------------- | ------------------------------------------------- | | User-Agent | MagnoliaBot/1.0 (+https://www.magnolia-cms.com) | | Enable Playwright | no (needs Playwright installed) |

Magnolia API plugin and its companions

| Setting | Default | Plugin | | ----------------------- | ---------------------------- | ------------ | | Request timeout | 30000 ms | API plugin | | Default DAM asset UUID | none (optional) | API plugin | | Default command catalog | Magnolia's default catalog | Commands API |

The Nodes and Definitions APIs have no settings.

Log plugin

| Setting | Default | | ------------------ | -------------- | | Log buffer size | 1000 entries | | Correlation window | 5000 ms |

Running it again

Running the setup again is safe. Everything that's already correct is reported with ✓ and left alone, and the settings overview shows your current values as found. Use it to add a plugin, rotate a token, or fix whatever doctor reports.

Commands and options

| Command | What it does | | ----------------------------------------------- | ----------------------------------------------------------------------------- | | npx @magnolia/mcp-dev-server-setup | Guided setup | | npx @magnolia/mcp-dev-server-setup doctor | Runs every check and explains what's wrong; asks nothing and changes nothing | | npx @magnolia/mcp-dev-server-setup install | Creates a managed installation directory (--plugin, --dir, --local) | | npx @magnolia/mcp-dev-server-setup add-plugin | Adds plugins to an existing installation, and migrates a retired .js config |

| Option | What it does | | ------------- | -------------------------------------------------- | | --dry-run | Shows what setup would change, and changes nothing | | --yes, -y | Accepts every default without asking (see below) | | --help | Shows help | | --version | Shows the version of this setup tool |

Without questions: --yes

With --yes, or when the setup isn't run in a terminal, every question takes its default:

• Nexus: NEXUS_USERNAME and NEXUS_PASSWORD, holding the name code and pass code of your user token. Without them, registry access fails and the run stops.
• AI tools: the installed ones, plus any already registered.
• Configuration (where it goes): all projects, unless this project already has a configuration.
• Plugins: all of them on a first run; otherwise the declared ones.
• Settings: the quick path. Required settings that nothing supplies are reported as missing, so set their variables (for example FIGMA_ACCESS_TOKEN) before the run.
• Secrets file: ~/.magnolia-mcp/secrets.env, unless only ~/.secrets exists.

Changes are then made without asking.

Files it touches

| File | When | Backup | | --------------------------------------------- | -------------------------------------- | ------------------------------------- | | ~/.npmrc | Registry access is missing or rejected | ~/.npmrc.bak-<date>-<time> | | An AI tool's configuration (see step 4) | You pick that tool | <file>.bak-<date>-<time> | | ~/.magnolia-mcp/secrets.env or ~/.secrets | A password or token was answered | Only the setup's marked block changes | | mgnl.mcp.config.json | You confirm the diff | <file>.bak-<date>-<time> |

Files holding credentials are made readable only by you every time they're written: mode 600, or an owner-only ACL on Windows.

When something fails

• Start with the fix line under the ✗ or !.
• Server log: ~/.magnolia-mcp-dev-server.log, for anything from the final check on.
• More detail: MAGNOLIA_MCP_SETUP_DEBUG=1 npx @magnolia/mcp-dev-server-setup also prints the lines about the plugin catalog, companion search, and setup questions, including the status Nexus returned for each one.
• A 401 from Nexus usually means an expired user token, or a login password entered instead of the token. Get a new token from https://nexus.magnolia-cms.com/#user/usertoken and run the setup again.
• Reporting a problem: send the terminal output. The setup never prints a password or token, but check anything you paste from your own files first.

For contributors

Run from a workspace checkout (node dist/cli.js in this directory), the setup reads every plugin's setup questions from the workspace, not from Nexus, and says so under its heading. A plugin's build writes its questions into its package.json, so build the plugins you changed first.

| Variable | Effect | | -------------------------------- | -------------------------------------------------------------------------------------------------------- | | MAGNOLIA_MCP_LOCAL_REGISTRY | Where to read plugin questions from. Set automatically in a workspace; set it empty to use Nexus | | MAGNOLIA_MCP_SETUP_SERVER_SPEC | Registers this server spec instead of the published one, e.g. file:<workspace>/magnolia-mcp-dev-server | | MAGNOLIA_MCP_SETUP_DEBUG | 1 prints the install library's log lines |

A full local test run, including how to set your machine back afterwards, is in dev-docs/guided-installer-local-test.md.

License

See LICENSE.txt.