red-design-mcp 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -12,10 +12,10 @@
12
12
  [![PRs welcome](https://img.shields.io/badge/PRs-welcome-22c55e?style=flat-square)](#contributing)
13
13
 
14
14
  ![MCP compatible](https://img.shields.io/badge/MCP-compatible-e11d48?style=flat-square)
15
- ![31 tools](https://img.shields.io/badge/tools-31-e11d48?style=flat-square)
15
+ ![36 tools](https://img.shields.io/badge/tools-36-e11d48?style=flat-square)
16
16
  ![API key optional](https://img.shields.io/badge/API%20key-optional-22c55e?style=flat-square)
17
- ![7 workflows](https://img.shields.io/badge/agent%20workflows-7-e11d48?style=flat-square)
18
- ![13 agents](https://img.shields.io/badge/agents-13-D97757?style=flat-square)
17
+ ![8 workflows](https://img.shields.io/badge/agent%20workflows-8-e11d48?style=flat-square)
18
+ ![14 agents](https://img.shields.io/badge/agents-14-D97757?style=flat-square)
19
19
  ![Claude Code](https://img.shields.io/badge/Claude%20Code-supported-D97757?style=flat-square)
20
20
  ![Codex](https://img.shields.io/badge/Codex-supported-111827?style=flat-square)
21
21
  ![Cursor](https://img.shields.io/badge/Cursor-supported-000000?style=flat-square)
@@ -39,8 +39,9 @@ Analyze, recreate, reimagine, critique and audit **any design** straight from Cl
39
39
  | **No API key needed** | In host mode your AI tool does the seeing, so there is no second bill and no second key. |
40
40
  | **Math, not vibes** | Contrast ratios, palettes, color-blindness simulation, type scales and originality scores are computed in code, so they are exact and repeatable. |
41
41
  | **Whole design system in one call** | `generate_design_system` turns a brand color and a mood into palette, light and dark themes, fonts, fluid type, spacing, radii and shadows, with contrast verified. |
42
- | **Agents included** | 13 specialist agents for Claude Code, Cursor, Codex, Gemini CLI and Copilot (plus AGENTS.md), 7 one-command workflows, and an autonomous `audit_site`. |
42
+ | **Agents included** | 14 agents for Claude Code, Cursor, Codex, Gemini CLI and Copilot (plus AGENTS.md), 8 one-command workflows, and an autonomous `audit_site`. |
43
43
  | **Reverse-engineer any website** | Point it at a URL: it reads the live CSS for tokens, lints it, or screenshots the page for the vision tools. |
44
+ | **Security checks (Red Chex)** | Reviews headers, CSP, cookies, leaked secrets and trackers on a live page, then writes the fixes as ready-to-paste config. |
44
45
  | **Tools on demand** | Let your AI discover and run only the tools a task needs with `RED_TOOLS=auto`, or pin the groups you want yourself. |
45
46
  | **Inspiration dial** | Slide from a faithful rebuild (0) to a wild reinterpretation (100) and get up to 3 variations at once. |
46
47
  | **Accessible by default** | Recreations fix contrast, semantics and tap targets unless you say otherwise. |
@@ -66,9 +67,10 @@ npx red-design-mcp install # auto-detect your tools
66
67
  npx red-design-mcp install --client codex,cursor
67
68
  npx red-design-mcp install --all # every supported client
68
69
  npx red-design-mcp install --print # just show the config snippets
70
+ npx red-design-mcp install --global # use a globally installed binary (offline friendly)
69
71
  npx red-design-mcp doctor # check Node, mode and detected clients
70
72
  npx red-design-mcp doctor --check # also confirm your model still exists
71
- npx red-design-mcp agents # install 13 design agents for your AI tools
73
+ npx red-design-mcp agents # install 14 design agents for your AI tools
72
74
  ```
73
75
 
74
76
  **Claude Code**
@@ -130,6 +132,17 @@ These work on live websites.
130
132
  | `extract_css_tokens` | Read a site's real stylesheets (or pasted CSS) and extract **colors, fonts, sizes, radii, spacing and shadows**. No screenshot, no key. Export as JSON, CSS, Tailwind, W3C or Figma. |
131
133
  | `lint_css` | Score CSS on design quality: contrast, removed focus outlines, tiny text, color and font sprawl, off-grid spacing, missing reduced-motion, and drift from your tokens. |
132
134
 
135
+ ### Security tools (Red Chex)
136
+ Red Chex is the security and privacy side of red-design-mcp. It is **defensive and passive**: `audit_security` sends one normal request to a public page and inspects what any visitor receives, and nothing is ever exploited or probed. Only check sites and code you own or have permission to review. These are not a substitute for a penetration test.
137
+
138
+ | Tool | What it does |
139
+ |---|---|
140
+ | `audit_security` | Grades one public page (A to F): HTTPS and redirects, HSTS, Content-Security-Policy, clickjacking and other headers, cookie flags, mixed content, forms, third-party scripts without Subresource Integrity, leaked credentials in the markup, trackers, and information disclosure, with a fix for each. |
141
+ | `scan_secrets` | Scans text you pass in (config, `.env` examples, front-end bundles) for API keys, tokens, private keys and passwords in connection strings. Findings show line and kind with a **redacted preview**; a full secret is never returned. |
142
+ | `generate_csp` | Builds a Content-Security-Policy from a page's real markup, with **SHA-256 hashes for inline scripts and styles** so you can avoid `'unsafe-inline'`. Starts in report-only mode. |
143
+ | `generate_security_headers` | Writes the recommended security headers as ready-to-paste config for **Netlify, Cloudflare Pages, Vercel, nginx, Apache, Caddy or Express**. Rejects input that could break out of the config file. |
144
+ | `audit_html` | Static audit of markup for accessibility and quality: `lang`, title, viewport zoom, alt text, unlabeled fields, empty buttons and links, heading order, duplicate ids, and more. |
145
+
133
146
  ### Deterministic tools
134
147
  These never need a model or a key. Same input, same answer, instantly.
135
148
 
@@ -155,12 +168,14 @@ These never need a model or a key. Same input, same answer, instantly.
155
168
  | `generate_spacing_scale` | A consistent spacing scale from a 4px or 8px base, in rem or px. |
156
169
  | `originality_check` | Compare a source and your new design on palette, type, shape and spacing. Get a similarity score and tips to differentiate. |
157
170
 
171
+ Anywhere a color is expected you can use hex (`#rgb`, `#rrggbb`, `#rrggbbaa`), `rgb()`, `hsl()`, `hwb()`, `oklch()`, `oklab()` or a CSS color name. Translucent colors are rejected with a clear message, because contrast depends on what is behind them.
172
+
158
173
  ## Agents
159
174
 
160
175
  red-design-mcp ships agents on three levels, so you pick how much to delegate.
161
176
 
162
177
  ### 1. Workflow prompts (any MCP client)
163
- Seven ready-made playbooks that tell your AI exactly which tools to run, in order, and how to report. In Claude Code they appear as slash commands such as `/mcp__red__redesign`.
178
+ Eight ready-made playbooks that tell your AI exactly which tools to run, in order, and how to report. In Claude Code they appear as slash commands such as `/mcp__red__redesign`.
164
179
 
165
180
  | Workflow | What the agent does |
166
181
  |---|---|
@@ -171,10 +186,11 @@ Seven ready-made playbooks that tell your AI exactly which tools to run, in orde
171
186
  | `brand-refresh` | Extract the current look, build a new palette and fonts, compare old vs new. |
172
187
  | `design-review` | Senior-designer verdict plus the top 5 prioritized fixes. |
173
188
  | `polish-css` | Lint and fix in a loop until the CSS scores 90 or more. |
189
+ | `security-check` | Audit headers, CSP, cookies and leaked secrets, then generate the fixes (report-only CSP first). |
174
190
 
175
191
  ### 2. Specialist agents for every major AI coding tool
176
192
 
177
- Every tool has its own agent format, so one command writes each agent in the native format of the tools you use. There are **13 agents**: 12 specialists for specific tasks, plus a **design lead** that handles everything else.
193
+ Every tool has its own agent format, so one command writes each agent in the native format of the tools you use. There are **14 agents**: 13 specialists for specific tasks, plus a **design lead** that handles everything else.
178
194
 
179
195
  ```bash
180
196
  npx red-design-mcp agents # install into the tools it detects
@@ -215,6 +231,7 @@ The `AGENTS.md` block is wrapped in markers, so running the command again refres
215
231
  | `red-component-designer` | Accessible buttons, forms, input states and favicons. |
216
232
  | `red-dataviz-designer` | Color-blind-safe chart and graph palettes. |
217
233
  | `red-typography-designer` | Font pairings, type scales and text rhythm. |
234
+ | `red-chex` | Security and privacy checks: headers, CSP, cookies, leaked secrets and trackers, then the fixes. |
218
235
 
219
236
  **The design lead, for everything else.** `red-design-lead` is the generalist. It classifies the task and picks the right specialist. For multi-part work it chains them in a sensible order (extract, then system, then components, then accessibility, then originality). If your tool supports subagents it delegates by name. If not, it follows that specialist's process itself.
220
237
 
@@ -351,21 +368,23 @@ Claude Code: `claude mcp add --scope user -e GEMINI_API_KEY=your-key red -- npx
351
368
  | `RED_BASE_URL`, `RED_API_KEY` | Use any OpenAI-compatible endpoint. |
352
369
  | `RED_MAX_TOKENS` | Cap the reply length (default 16000, which leaves room for model thinking). |
353
370
  | `RED_TOOLS` | Load fewer tools. See [Choosing tools](#choosing-tools). |
371
+ | `RED_ALLOW_PRIVATE_URLS` | Set to `1` to let tools fetch or capture `localhost` and private-network addresses. See [Security](#security). |
372
+ | `RED_ALLOWED_DIRS` | Optional list of folders images may be read from (separated by `:` on Mac and Linux, `;` on Windows). See [Security](#security). |
354
373
 
355
374
  `npx red-design-mcp doctor` shows which provider and model are active, and `doctor --check` asks the provider whether that model is still available. Requests that hit a rate limit or a temporary server error are retried once automatically.
356
375
 
357
376
  ## Choosing tools
358
377
 
359
- red-design-mcp has 31 tools. Loading all of them is the default, but you can control what your AI sees, or let the AI choose for itself. Set `RED_TOOLS` in your client's `env`.
378
+ red-design-mcp has 36 tools. Loading all of them is the default, but you can control what your AI sees, or let the AI choose for itself. Set `RED_TOOLS` in your client's `env`.
360
379
 
361
380
  | Mode | `RED_TOOLS` | What happens |
362
381
  |---|---|---|
363
- | Everything | unset, or `all` | All 31 tools load directly. |
382
+ | Everything | unset, or `all` | All 36 tools load directly. |
364
383
  | You choose | `core`, `core,web`, `all,-capture_url` | Only the groups or tools you name load. |
365
384
  | The AI chooses | `auto` | Only two small tools load: `find_tools` and `run_tool`. The AI describes its task, gets the matching tools with their parameters, and runs them. |
366
385
  | Mixed | `core,auto` | The 9 core tools load directly and the AI discovers the rest on demand. |
367
386
 
368
- Groups: `core` (the 9 essentials), `vision`, `web`, `color`, `system`, `components`, `quality`. Combine groups with commas and exclude a tool with a dash.
387
+ Groups: `core` (the 9 essentials), `vision`, `web`, `color`, `system`, `components`, `quality`, `security`. Combine groups with commas and exclude a tool with a dash.
369
388
 
370
389
  ```json
371
390
  {
@@ -404,6 +423,20 @@ Exact tools never call a model: contrast, palettes, scales and audits are comput
404
423
 
405
424
  A typical flow chains the tools: `analyze_design` → `extract_tokens` → `reimagine` → `audit_accessibility` → `originality_check`.
406
425
 
426
+ ## Security
427
+
428
+ red-design-mcp runs on your machine with your permissions, and its tools are driven by an AI that can be misled by text it reads (prompt injection). These guards limit what a misled prompt can do.
429
+
430
+ - **Images only.** Local files are read only if they are real PNG, JPEG, GIF or WebP images, checked by file extension and by file signature, and at most 20 MB. A text file, key or config cannot be read through the image tools, and symlinks are resolved before the check. To confine reads to specific folders, set `RED_ALLOWED_DIRS` (the capture folder is always allowed).
431
+ - **No internal network.** URLs for image downloads, stylesheet reading and screenshots must resolve to public addresses. Loopback, private ranges, link-local addresses (including the `169.254.169.254` cloud metadata service) and reserved ranges are blocked, and every redirect is re-checked. In screenshots, each page request the browser makes is checked as well.
432
+ - **Your own dev server.** To capture `localhost` or a private address, set `RED_ALLOW_PRIVATE_URLS=1`. Link-local and reserved addresses stay blocked even then.
433
+ - **Size limits.** Downloaded pages and stylesheets are capped at 2 MB, and images at 20 MB.
434
+ - **Safe installs.** `install` never rewrites a config it cannot parse (for example one with comments); it stops without changing anything. When it does edit a config it keeps your formatting, writes atomically, and never overwrites an earlier backup.
435
+
436
+ Limits to know about: the address check happens just before each request, so a hostile DNS server that changes its answer between the check and the connection could in theory slip through. If that matters to you, run the server in a container or on a network without access to anything sensitive. Never put API keys in files you commit; keep them in your AI tool's `env` settings.
437
+
438
+ **Offline or restricted networks.** `npx` downloads the package, so it needs access to the npm registry. Run `npm install -g red-design-mcp` once, then `red-design-mcp install --global` so your tools start the installed binary directly.
439
+
407
440
  ## Responsible use
408
441
 
409
442
  red-design-mcp is built to learn from **structure and style**, not to copy someone's brand. Recreations use neutral placeholders instead of logos or trademarked artwork, and `originality_check` helps you confirm your result is genuinely your own. It compares tokens only (not layout or content) and is not legal advice.
@@ -417,7 +450,8 @@ red-design-mcp is built to learn from **structure and style**, not to copy someo
417
450
  - [x] One-command installer and API-key-free host mode
418
451
  - [x] Multiple model providers: Anthropic, OpenAI, Gemini, Groq, OpenRouter and any OpenAI-compatible endpoint
419
452
  - [x] Complete design-system generator with light and dark themes
420
- - [x] Agent workflows, 13 specialist agents for five AI tools plus AGENTS.md, and an autonomous site audit
453
+ - [x] Agent workflows, 14 agents for five AI tools plus AGENTS.md, and an autonomous site audit
454
+ - [x] Red Chex security agent: header and privacy audit, secret scanner, CSP and security-header generators, HTML audit
421
455
  - [x] Capture screenshots from a URL and extract tokens from live CSS
422
456
  - [x] CSS design linter
423
457
  - [ ] Generate real Figma frames through the Figma API
package/dist/a11y.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { SUPPORTED_COLOR_FORMATS, parseColor } from "./colorparse.js";
1
2
  export const AUDIT_PROMPT = `You are an accessibility specialist (WCAG 2.2). Audit this design and reply with ONLY valid JSON, no fences:
2
3
  {
3
4
  "pairs": [ { "element": "primary button label", "foreground": "#hex", "background": "#hex", "large_text": false, "kind": "text" } ],
@@ -8,13 +9,23 @@ Rules:
8
9
  - Estimate hex values as precisely as you can.
9
10
  - large_text is true only for text of 24px+ or 18.66px+ bold. Use kind "ui" for icons and component borders.
10
11
  - Also report non-contrast issues you can see: small tap targets, tiny text, color-only meaning, missing labels or alt text, weak focus cues.`;
11
- export function hexToRgb(hex) {
12
- let h = hex.trim().replace(/^#/, "");
13
- if (h.length === 3)
14
- h = h.split("").map((c) => c + c).join("");
15
- if (!/^[0-9a-fA-F]{6}$/.test(h))
16
- return null;
17
- return [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16));
12
+ export { parseColor, SUPPORTED_COLOR_FORMATS } from "./colorparse.js";
13
+ /**
14
+ * Parse any supported opaque color (hex, rgb(), hsl(), hwb(), oklch(), oklab() or a CSS name).
15
+ * Kept under its original name. Translucent colors return null because contrast depends on the background.
16
+ */
17
+ export function hexToRgb(input) {
18
+ const c = parseColor(input);
19
+ return c && c.alpha >= 1 ? c.rgb : null;
20
+ }
21
+ /** Like hexToRgb but explains what went wrong. */
22
+ export function requireColor(input, label) {
23
+ const c = parseColor(input);
24
+ if (!c)
25
+ throw new Error(`"${input}" (${label}) is not a color I can read. Use ${SUPPORTED_COLOR_FORMATS}.`);
26
+ if (c.alpha < 1)
27
+ throw new Error(`"${input}" (${label}) is translucent, so its contrast depends on what is behind it. Pass the final opaque color instead.`);
28
+ return c.rgb;
18
29
  }
19
30
  function toHex(rgb) {
20
31
  return "#" + rgb.map((v) => Math.round(v).toString(16).padStart(2, "0")).join("");
@@ -51,6 +62,8 @@ export function suggestFix(fg, bg, required) {
51
62
  }
52
63
  export function evaluatePairs(pairs) {
53
64
  return pairs.map((p) => {
65
+ requireColor(p.foreground, `${p.element} foreground`);
66
+ requireColor(p.background, `${p.element} background`);
54
67
  const ratio = contrastRatio(p.foreground, p.background);
55
68
  const isUi = p.kind === "ui";
56
69
  const required = isUi || p.large_text ? 3 : 4.5;
package/dist/agents.js CHANGED
@@ -24,6 +24,7 @@ export const AGENTS = [
24
24
  "- Dark mode, gradients, shadows, motion, layout, spacing: red-theme-builder",
25
25
  "- Buttons, forms, input states, favicon: red-component-designer",
26
26
  "- Chart and data-visualization colors: red-dataviz-designer",
27
+ "- Security headers, CSP, leaked secrets, cookies, privacy and trackers: red-chex",
27
28
  "- Fonts, type scale, text sizing: red-typography-designer",
28
29
  "",
29
30
  "Process",
@@ -243,6 +244,29 @@ export const AGENTS = [
243
244
  "4. Apply to the chart code (CSS variables or the chart library's theme) and report the palette and the checks.",
244
245
  ],
245
246
  },
247
+ {
248
+ name: "red-chex",
249
+ role: "specialist",
250
+ description: "Security and privacy checker. Use when asked to check a website or front-end code for security headers, CSP, cookies, leaked secrets, mixed content, trackers or hardening before launch.",
251
+ when: "Security headers, CSP, secrets, privacy",
252
+ tools: ["audit_security", "scan_secrets", "generate_csp", "generate_security_headers", "audit_html"],
253
+ readonly: false,
254
+ body: [
255
+ "You are Red Chex, a defensive web security and privacy checker. You review sites and front-end code the user owns or is allowed to test, and you help fix what you find. You never exploit anything.",
256
+ TOOLS_NOTE,
257
+ "",
258
+ "Rules",
259
+ "- Only check sites and code the user owns or has permission to review. The tools make one normal GET request and inspect headers and markup. Do not try to reach anything non-public, and do not attempt attacks, bypasses or scanning of other systems.",
260
+ "- If a secret is found, never repeat it. Quote only the redacted preview, tell the user to revoke and rotate it, and remind them it stays in git history until that history is cleaned.",
261
+ "",
262
+ "Process",
263
+ "1. Live site: call `audit_security`. Local code or HTML: call `audit_html`, and call `scan_secrets` on the contents of config files, .env examples and front-end bundles (pass the text in).",
264
+ "2. For each high and medium finding, explain the risk in one sentence and give the exact fix.",
265
+ "3. Build the fix: `generate_csp` (report-only first) and `generate_security_headers` for the user's host (Netlify, Vercel, nginx, Apache, Caddy, Express or Cloudflare Pages). Apply them in the project's config.",
266
+ "4. After deployment, call `audit_security` again and report the grade before and after.",
267
+ "5. Be honest about scope: this is a passive review of headers and markup, not a penetration test, and it cannot find flaws in application logic.",
268
+ ],
269
+ },
246
270
  {
247
271
  name: "red-typography-designer",
248
272
  role: "specialist",
package/dist/cli.js CHANGED
@@ -1,4 +1,4 @@
1
- import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
1
+ import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
2
2
  import { homedir, platform } from "node:os";
3
3
  import { dirname, join } from "node:path";
4
4
  import { spawnSync } from "node:child_process";
@@ -8,9 +8,13 @@ import { ALL_TOOLS, parseToolset, unknownEntries, wantsGateway } from "./toolset
8
8
  const NAME = "red";
9
9
  const PKG = "red-design-mcp";
10
10
  const isWin = platform() === "win32";
11
- const launcher = isWin
12
- ? { command: "cmd", args: ["/c", "npx", "-y", PKG] }
13
- : { command: "npx", args: ["-y", PKG] };
11
+ /** How AI tools start the server: through npx (default), or the globally installed binary (offline friendly). */
12
+ function launcherFor(globalBin = false) {
13
+ if (globalBin)
14
+ return isWin ? { command: "cmd", args: ["/c", PKG] } : { command: PKG, args: [] };
15
+ return isWin ? { command: "cmd", args: ["/c", "npx", "-y", PKG] } : { command: "npx", args: ["-y", PKG] };
16
+ }
17
+ const tomlArgs = (l) => `[${l.args.map((a) => JSON.stringify(a)).join(", ")}]`;
14
18
  const ALL = ["claude-code", "codex", "cursor", "claude-desktop"];
15
19
  function claudeDesktopPath() {
16
20
  const h = homedir();
@@ -45,42 +49,77 @@ export function detect() {
45
49
  return found;
46
50
  }
47
51
  function backup(file) {
48
- if (existsSync(file))
49
- copyFileSync(file, file + ".bak");
52
+ if (!existsSync(file))
53
+ return;
54
+ let target = `${file}.bak`;
55
+ for (let i = 1; existsSync(target) && i < 50; i++)
56
+ target = `${file}.bak.${i}`; // keep the earliest backup intact
57
+ copyFileSync(file, target);
50
58
  }
51
- function installJson(file) {
59
+ /** Write to a temp file, then rename, so a crash can never leave a half-written config. */
60
+ function writeAtomic(file, text) {
61
+ const tmp = `${file}.tmp-${process.pid}`;
62
+ try {
63
+ writeFileSync(tmp, text);
64
+ renameSync(tmp, file);
65
+ }
66
+ catch (err) {
67
+ try {
68
+ unlinkSync(tmp);
69
+ }
70
+ catch {
71
+ /* temp file already gone */
72
+ }
73
+ throw err;
74
+ }
75
+ }
76
+ function installJson(file, launcher) {
52
77
  let cfg = {};
78
+ let raw = "";
53
79
  if (existsSync(file)) {
54
- const raw = readFileSync(file, "utf8").trim();
55
- if (raw) {
80
+ raw = readFileSync(file, "utf8");
81
+ if (raw.trim()) {
56
82
  try {
57
83
  cfg = JSON.parse(raw);
58
84
  }
59
85
  catch {
60
- throw new Error(`${file} is not valid JSON. Fix it or add the server manually (run with --print).`);
86
+ throw new Error(`${file} contains comments, trailing commas or other non-standard JSON that this installer cannot rewrite without losing them. Nothing was changed. Add the server by hand instead (run: npx red-design-mcp install --print).`);
61
87
  }
62
88
  }
63
89
  }
90
+ if (cfg === null || typeof cfg !== "object" || Array.isArray(cfg))
91
+ throw new Error(`${file} is not a JSON object. Nothing was changed.`);
92
+ if (cfg.mcpServers !== undefined && (cfg.mcpServers === null || typeof cfg.mcpServers !== "object" || Array.isArray(cfg.mcpServers))) {
93
+ throw new Error(`"mcpServers" in ${file} is not an object. Nothing was changed.`);
94
+ }
64
95
  cfg.mcpServers ??= {};
65
96
  if (cfg.mcpServers[NAME])
66
97
  return "already installed";
98
+ // Keep the user's indentation, line endings and trailing newline.
99
+ const indentMatch = raw.match(/^([ \t]+)"/m);
100
+ const indent = indentMatch ? (indentMatch[1].includes("\t") ? "\t" : indentMatch[1].length) : 2;
101
+ const crlf = raw.includes("\r\n");
102
+ const trailingNewline = !raw || raw.endsWith("\n");
103
+ cfg.mcpServers[NAME] = launcher;
104
+ let out = JSON.stringify(cfg, null, indent) + (trailingNewline ? "\n" : "");
105
+ if (crlf)
106
+ out = out.replace(/\n/g, "\r\n");
67
107
  backup(file);
68
108
  mkdirSync(dirname(file), { recursive: true });
69
- cfg.mcpServers[NAME] = launcher;
70
- writeFileSync(file, JSON.stringify(cfg, null, 2) + "\n");
109
+ writeAtomic(file, out);
71
110
  return `added to ${file}`;
72
111
  }
73
- function installCodex(file) {
112
+ function installCodex(file, launcher) {
74
113
  const current = existsSync(file) ? readFileSync(file, "utf8") : "";
75
114
  if (current.includes(`[mcp_servers.${NAME}]`))
76
115
  return "already installed";
77
116
  backup(file);
78
117
  mkdirSync(dirname(file), { recursive: true });
79
- const block = `\n[mcp_servers.${NAME}]\ncommand = "${launcher.command}"\nargs = [${launcher.args.map((a) => JSON.stringify(a)).join(", ")}]\n`;
80
- writeFileSync(file, current + block);
118
+ const block = `\n[mcp_servers.${NAME}]\ncommand = "${launcher.command}"\nargs = ${tomlArgs(launcher)}\n`;
119
+ writeAtomic(file, current + block);
81
120
  return `added to ${file}`;
82
121
  }
83
- function installClaudeCode() {
122
+ function installClaudeCode(launcher) {
84
123
  const r = spawnSync("claude", ["mcp", "add", "--scope", "user", NAME, "--", launcher.command, ...launcher.args], {
85
124
  encoding: "utf8",
86
125
  shell: isWin,
@@ -92,15 +131,48 @@ function installClaudeCode() {
92
131
  return "already installed";
93
132
  throw new Error(out || "`claude mcp add` failed");
94
133
  }
95
- export function installClient(client) {
134
+ export function installClient(client, opts = {}) {
96
135
  const p = paths();
136
+ const launcher = launcherFor(opts.global);
97
137
  switch (client) {
98
- case "claude-code": return installClaudeCode();
99
- case "codex": return installCodex(p.codex);
100
- case "cursor": return installJson(p.cursor);
101
- case "claude-desktop": return installJson(p["claude-desktop"]);
138
+ case "claude-code": return installClaudeCode(launcher);
139
+ case "codex": return installCodex(p.codex, launcher);
140
+ case "cursor": return installJson(p.cursor, launcher);
141
+ case "claude-desktop": return installJson(p["claude-desktop"], launcher);
102
142
  }
103
143
  }
144
+ /** What doctor reports: is red configured in each detected tool, and is that tool's config readable? */
145
+ export function inspectClients(clients = detect()) {
146
+ const p = paths();
147
+ return clients.map((client) => {
148
+ if (client === "claude-code")
149
+ return { client, status: "not-inspected", detail: "managed by Claude Code itself; run: claude mcp list" };
150
+ const file = client === "codex" ? p.codex : client === "cursor" ? p.cursor : p["claude-desktop"];
151
+ if (!existsSync(file))
152
+ return { client, status: "no-config", detail: `no config file yet (${file})` };
153
+ let raw;
154
+ try {
155
+ raw = readFileSync(file, "utf8");
156
+ }
157
+ catch (err) {
158
+ return { client, status: "invalid-config", detail: `cannot read ${file}: ${err.message}` };
159
+ }
160
+ if (client === "codex") {
161
+ return raw.includes(`[mcp_servers.${NAME}]`)
162
+ ? { client, status: "installed", detail: file }
163
+ : { client, status: "not-installed", detail: file };
164
+ }
165
+ if (!raw.trim())
166
+ return { client, status: "not-installed", detail: `${file} is empty` };
167
+ try {
168
+ const cfg = JSON.parse(raw);
169
+ return cfg?.mcpServers?.[NAME] ? { client, status: "installed", detail: file } : { client, status: "not-installed", detail: file };
170
+ }
171
+ catch (err) {
172
+ return { client, status: "invalid-config", detail: `${file} is not valid JSON (${err.message})` };
173
+ }
174
+ });
175
+ }
104
176
  export const AGENT_LABELS = {
105
177
  claude: "Claude Code",
106
178
  cursor: "Cursor",
@@ -165,7 +237,6 @@ export function installAgentsMd(file) {
165
237
  writeFileSync(file, next);
166
238
  return start !== -1 ? `updated ${file}` : `added to ${file}`;
167
239
  }
168
- const SNIPPET = JSON.stringify({ mcpServers: { [NAME]: launcher } }, null, 2);
169
240
  const HELP = `red-design-mcp: recreate and reimagine any design (MCP server)
170
241
 
171
242
  Usage:
@@ -173,8 +244,9 @@ Usage:
173
244
  npx red-design-mcp install --client codex,cursor
174
245
  npx red-design-mcp install --all Install into every supported client
175
246
  npx red-design-mcp install --print Only print the config snippets
247
+ npx red-design-mcp install --global Use the globally installed binary instead of npx (works offline after: npm i -g red-design-mcp)
176
248
  npx red-design-mcp doctor Check setup and mode (add --check to confirm your model exists)
177
- npx red-design-mcp agents Install 13 design agents into the AI tools it detects
249
+ npx red-design-mcp agents Install 14 design agents into the AI tools it detects
178
250
  npx red-design-mcp agents --target claude,cursor,codex,gemini,copilot,agents-md
179
251
  npx red-design-mcp agents --all Every supported tool (AGENTS.md goes in the current folder)
180
252
  npx red-design-mcp agents --project Install into this project instead of your home folder
@@ -212,6 +284,8 @@ export async function runCli(args) {
212
284
  ? `API mode (${prov.label}, model ${prov.model || "NOT SET: set RED_MODEL"})`
213
285
  : "Host mode (no key needed)";
214
286
  console.log(`Node: ${process.version}`);
287
+ if (Number(process.versions.node.split(".")[0]) < 18)
288
+ console.log("Warning: Node 18 or newer is required.");
215
289
  console.log(`Mode: ${mode}`);
216
290
  if (process.env.RED_PROVIDER && !prov)
217
291
  console.log(`Warning: RED_PROVIDER=${process.env.RED_PROVIDER} has no matching key or is not a known provider (anthropic, openai, google, groq, openrouter, custom).`);
@@ -227,6 +301,10 @@ export async function runCli(args) {
227
301
  console.log(`Warning: unknown RED_TOOLS entries: ${bad.join(", ")}`);
228
302
  const found = detect();
229
303
  console.log(`Detected clients: ${found.length ? found.join(", ") : "none"}`);
304
+ for (const c of inspectClients(found)) {
305
+ const label = { installed: "red is installed", "not-installed": "red is not installed", "no-config": "no config yet", "invalid-config": "CONFIG PROBLEM", "not-inspected": "not inspected" }[c.status];
306
+ console.log(` ${c.client}: ${label} (${c.detail})`);
307
+ }
230
308
  if (args.includes("--check")) {
231
309
  if (!prov)
232
310
  console.log("Model check: skipped (host mode, no provider configured)");
@@ -300,10 +378,12 @@ export async function runCli(args) {
300
378
  console.log(HELP);
301
379
  return;
302
380
  }
381
+ const globalBin = args.includes("--global");
303
382
  if (args.includes("--print")) {
304
- console.log(`Claude Code:\n claude mcp add --scope user ${NAME} -- ${[launcher.command, ...launcher.args].join(" ")}\n`);
305
- console.log(`Codex (~/.codex/config.toml):\n [mcp_servers.${NAME}]\n command = "${launcher.command}"\n args = [${launcher.args.map((a) => JSON.stringify(a)).join(", ")}]\n`);
306
- console.log(`Cursor / Claude Desktop / others (JSON):\n${SNIPPET}`);
383
+ const l = launcherFor(globalBin);
384
+ console.log(`Claude Code:\n claude mcp add --scope user ${NAME} -- ${[l.command, ...l.args].join(" ")}\n`);
385
+ console.log(`Codex (~/.codex/config.toml):\n [mcp_servers.${NAME}]\n command = "${l.command}"\n args = ${tomlArgs(l)}\n`);
386
+ console.log(`Cursor / Claude Desktop / others (JSON):\n${JSON.stringify({ mcpServers: { [NAME]: l } }, null, 2)}`);
307
387
  return;
308
388
  }
309
389
  let targets;
@@ -322,7 +402,7 @@ export async function runCli(args) {
322
402
  let failed = false;
323
403
  for (const c of targets) {
324
404
  try {
325
- console.log(` ok ${c}: ${installClient(c)}`);
405
+ console.log(` ok ${c}: ${installClient(c, { global: globalBin })}`);
326
406
  }
327
407
  catch (err) {
328
408
  failed = true;
@@ -330,7 +410,7 @@ export async function runCli(args) {
330
410
  }
331
411
  }
332
412
  console.log("\nDone. Restart your AI tool, then ask it to analyze or recreate a design image.");
333
- console.log("Tip: run `npx red-design-mcp agents` to add 13 design agents for Claude Code, Cursor, Codex, Gemini CLI and Copilot.");
413
+ console.log("Tip: run `npx red-design-mcp agents` to add 14 design agents for Claude Code, Cursor, Codex, Gemini CLI and Copilot.");
334
414
  if (failed)
335
415
  process.exitCode = 1;
336
416
  }