feat(21st): replace the magic MCP with the @21st-dev CLI + skill pack

Upstream supersedes `@21st-dev/magic` with `@21st-dev/cli` (bin `21st`):
same endpoint, `21st login` in place of an API key, no MCP process loaded
into every session.

- install-plugins.sh Step 8.7: `npm i -g @21st-dev/cli` (pinned in
  plugins.lock.json), staged `21st skills install`, TTY-only login offer,
  pack disabled by default. update-all.sh 7.4 refreshes both.
- The documented `21st install-skill` cannot be used: the installer refuses
  to follow a symlink on the target path and `~/.claude/skills` is one. The
  install runs under a throwaway HOME and the result moves into
  skills-external/21st-* (gitignored), symlinked on demand.
- toggle-external.sh manages `21st` as a pack (names globbed from
  skills-external/21st-*, parked under plain names). `magic` is gone.
- The 5 design skills join design/web/web-full/full and MANAGED_EXTERNALS;
  21st-registry and 21st-design-sync stay parked. MANAGED_MCPS is now empty
  and profile.sh's dead magic branches are removed.
- Design gate: GATE-BLOCK gains `21st` (required-manual, magic's old slot)
  and `21st-ui-build`; PATH repair extended to the npm global bin.
- settings.json: the 4 mcp__magic__* ask entries go; the outward-facing
  21st verbs land in autoMode.soft_deny, the tier that holds under auto
  mode (LRN-153).
- Docs: README, CLAUDE.global.md, design-gate.md, profile SKILL.md,
  .env.example, .gitleaks.toml, link.sh. BDR-093, LRN-158.

Tests: profile-set-managed 17/17, make test green except 2 pre-existing
gitflow FAILs (gitleaks binary absent on this host), shellcheck clean.
This commit is contained in:
bastien
2026-09-22 02:53:31 +00:00
parent 413b35a913
commit 7c05f75eab
26 changed files with 515 additions and 195 deletions
+44 -22
View File
@@ -253,10 +253,9 @@ in `env`, `command`, `args`, `url`, and `headers` — for both project (`.mcp.js
and user (`~/.claude.json`) scope. Use that instead of a literal value:
```bash
MAGIC_API_KEY=<Enter your magic api key here from https://21st.dev/settings/api-keys >
# single-quoted so bash doesn't expand it; Claude Code expands it at
# launch, reading the var from its own process environment:
claude mcp add magic --scope user --env 'API_KEY=${MAGIC_API_KEY}' -- npx -y @21st-dev/magic@latest
claude mcp add <name> --scope user --env 'API_KEY=${SOME_API_KEY}' -- <command>
```
The var still has to exist in the **environment of the process that starts
@@ -265,8 +264,12 @@ would defeat the point (every subprocess, every stray `env`/`printenv`, would
then see it). This repo's `~/.bashrc` instead wraps the `claude` command
itself: a `claude()` shell function sources `~/.claude/.env` into a subshell
and `exec`s the real binary, so the var reaches `claude` and its children only
— never the ambient shell. See `lib/toggle-external.sh`'s `magic` case for
the pattern to copy for a new MCP server.
— never the ambient shell.
This config currently registers no MCP server at all. The one it used to
carry, `@21st-dev/magic`, is gone: 21st.dev replaced it with a plain CLI (see
below), so there is no key left to protect by reference. The pattern stays
documented for the next MCP server that needs a secret.
There is no `claude mcp add` flag that writes the reference form for you —
the `${VAR}` syntax has to be typed by hand (or via a wrapper script), same as
@@ -292,25 +295,44 @@ Then run the one-time consent flow: `make seo-connect` (per-label token
store, multi-site safe). Missing credentials never break an audit — `/seo`
degrades gracefully to anonymous PageSpeed lab data.
### magic MCP (`@21st-dev/magic`) — known callback-injection risk
### 21st.dev CLI (replaces the magic MCP)
`21st_magic_component_builder` opens an **unauthenticated** local callback
server (`127.0.0.1:9221+`, `Access-Control-Allow-Origin: *`, no token/origin
check) for up to 10 minutes per call; any local process or open browser tab
can `POST` to it and that body is injected **verbatim** into the tool result
the model consumes (job8 audit, `dist/utils/callback-server.js:36`). This is
in the third-party package's code, not this repo's config — **we don't patch
it**. The mitigation lives on our side: `settings.json`
`permissions.ask` explicitly lists all 4 `mcp__magic__*` tools.
Read that as a declared intent, not a proven hard gate: under
`defaultMode: auto` (this config's default) Bash `ask` rules were observed
auto-approving with no prompt raised (LRN-146). Whether MCP `ask` rules
behave the same has not been verified here, so re-check before relying on
it. `deny` is the only tier the auto-mode classifier cannot lift; for a
gate that holds under auto mode without banning the tool outright, the
right home is `autoMode.soft_deny`. Don't allowlist
`21st_magic_component_builder` or `21st_magic_component_refiner` (arbitrary
absolute-path read → vendor exfil, same audit) under any circumstance.
`@21st-dev/cli` (bin `21st`) supersedes the `@21st-dev/magic` MCP server that
this config used to register. Same endpoint, one browser login, no API key,
and nothing loaded into a session that isn't using it:
```bash
npm i -g @21st-dev/cli
21st login # browser flow, token saved in ~/.config/21st
```
`make plugin` does both (Step 8.7 installs the CLI, then offers the login in
an interactive terminal) and installs the skill pack that drives it:
`21st-ui-build`, `-ui-explore`, `-ui-review`, `-cli-use`, `-ai`, plus the two
publishing skills `-registry` and `-design-sync`. The pack is disabled by
default, the same policy the MCP had. `/profile design` turns on the five
design skills; `bash lib/toggle-external.sh enable 21st` turns on all seven.
The pack is machine-owned and gitignored. It cannot be installed the way
upstream documents it (`21st install-skill`, i.e. `21st skills install
--global`): that writes into `~/.claude/skills/`, and the installer refuses to
follow a symlink anywhere on that path, while `~/.claude/skills` is itself a
symlink to this repo's `skills/`. So the install runs under a throwaway `HOME`
and the result is moved into `skills-external/21st-*`, where
`toggle-external.sh` and `profile.sh` symlink it in on demand.
Two risks from the MCP era go away with it. The unauthenticated local callback
server `21st_magic_component_builder` opened (`127.0.0.1:9221+`, CORS `*`, a
10-minute local prompt-injection window, job8 audit / LRN-110). And the API
key that `claude mcp add --env` materialized into `~/.claude.json`.
The permission gate is now one `autoMode.soft_deny` entry covering the
outward-facing verbs (`21st publish*`, `submit`, `edit`, `delete`,
`remove-from-catalog`, `profile set|upload`), because publishing a component
puts it on a public listing under your account. That tier rather than `ask`:
under `defaultMode: auto` (this config's default) `ask` rules were observed
auto-approving with no prompt raised (LRN-153), so an `ask` entry would have
declared an intent without gating anything.
---