saglitzdesign-mcp 0.3.1 → 0.4.0

package/LICENSE

@@ -19,11 +19,3 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
-
----
-
-Note on bundled research content: the files under knowledge/ are original
-syntheses written for this project, with sources cited in each document's
-frontmatter. Screenshot images referenced by knowledge/examples/*.json are a
-local research asset, are NOT part of this repository or the published
-package, and may not be redistributed.

package/NOTICE.md

@@ -0,0 +1,16 @@
+# Notice on bundled content
+
+The software is licensed under the [MIT License](LICENSE).
+
+Additional notes on the research content shipped in this repository:
+
+- The documents under `knowledge/` are original syntheses written for this
+  project. Sources consulted are cited in each document's frontmatter
+  (`sources:`). No third‑party text is reproduced verbatim.
+- Screenshot images referenced by `knowledge/examples/*.json` are a local
+  research asset. They are **not** part of this repository or any published
+  package (`knowledge/examples/images/` is git‑ignored), and may not be
+  redistributed. See [`scripts/regenerate-examples.md`](scripts/regenerate-examples.md).
+
+These notes describe the provenance of the bundled content; they do not modify
+the MIT License terms above.

package/README.md

@@ -9,7 +9,11 @@ expert‑level guidance on **web, iOS, Android and macOS design** — plus the
 **UX, copywriting, SEO, GEO and marketing** knowledge that makes a product
 actually convert.
 
-56 curated knowledge documents · 10 tools · phased roadmaps · real‑world visual examples
+56 curated knowledge documents · 10 tools · 5 build/review workflows · phased roadmaps · real‑world visual examples
+
+[![npm](https://img.shields.io/npm/v/saglitzdesign-mcp?color=cb3837&logo=npm)](https://www.npmjs.com/package/saglitzdesign-mcp)
+[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![MCP](https://img.shields.io/badge/Model_Context_Protocol-server-000)](https://modelcontextprotocol.io)
 
 [Why](#why) · [What's inside](#whats-inside) · [Tools](#tools) · [Install](#install) · [Usage](#usage) · [Extending](#extending-the-knowledge-base) · [License](#license)
 
@@ -54,6 +58,28 @@ instead of guessing.
 | 📣 **Marketing** | Branding & identity (strategy, logo systems, brand voice) · email marketing (design, lifecycle, deliverability) · ad creative (hooks, platform specs, testing) |
 | 🖼️ **Patterns & examples** | Real‑world patterns studied from top apps & sites, plus a curated screenshot library served as images |
 
+## Workflows (`/` prompts) — "build me a…"
+
+Beyond answering questions, SaglitzDesign ships **prompts** that orchestrate an
+entire build end‑to‑end. In Claude Code they appear in the `/` menu; invoke one
+and the agent runs the full method — roadmap → positioning & copy → real
+examples → **writes the actual code** → opens it in a browser, screenshots,
+scores it against the critique rubric, and iterates until it passes.
+
+| Prompt | What it does |
+|---|---|
+| **`build_landing_page`** | Designs & builds a conversion‑focused landing page, copy‑first, with a visual critique loop. |
+| **`build_website`** | Builds a multi‑page marketing site — positioning, IA, SEO/GEO, shared design system. |
+| **`build_mobile_app_ui`** | Builds iOS or Android screens on the correct platform baseline (HIG/Liquid Glass or Material 3). |
+| **`design_review`** | Audits an existing site/app against the checklists and the 0–40 critique rubric, ranked by severity. |
+| **`redesign`** | Improves an existing UI (bolder / quieter / higher‑converting) using the craft standards, with before→after scoring. |
+
+> Just say, e.g., *"/build_landing_page for a SaaS invoicing tool for freelancers"* — the workflow asks for anything missing, then builds it.
+>
+> The visual critique loop uses whatever browser tool is connected (Claude in
+> Chrome, Playwright, or chrome‑devtools MCP) to see and refine its own output.
+> Without one, it reviews the code directly.
+
 ## Tools
 
 | Tool | What it does |
@@ -73,7 +99,7 @@ instead of guessing.
 
 **Requirements:** Node.js 18+.
 
-**From npm** (once published):
+**From npm** (no clone needed):
 
 ```bash
 npx saglitzdesign-mcp
@@ -90,13 +116,17 @@ npm run build
 
 ### Claude Code
 
-Register it once, available in every project:
+Register it once (via npm — no clone), available in every project:
 
 ```bash
-claude mcp add --scope user saglitzdesign node /absolute/path/to/saglitzdesign-mcp/dist/index.js
+claude mcp add --scope user saglitzdesign -- npx -y saglitzdesign-mcp
 ```
 
-Or use the project‑scoped `.mcp.json` already in this repo (relative `dist/index.js`).
+Or, if you cloned the repo, point it at the built file:
+
+```bash
+claude mcp add --scope user saglitzdesign node /absolute/path/to/saglitzdesign-mcp/dist/index.js
+```
 
 ### Claude Desktop
 
@@ -106,8 +136,8 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 {
   "mcpServers": {
     "saglitzdesign": {
-      "command": "node",
-      "args": ["/absolute/path/to/saglitzdesign-mcp/dist/index.js"]
+      "command": "npx",
+      "args": ["-y", "saglitzdesign-mcp"]
     }
   }
 }
@@ -115,7 +145,7 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
 ### Cursor / other MCP clients
 
-Point the client at `node /absolute/path/to/saglitzdesign-mcp/dist/index.js` over stdio.
+Run `npx -y saglitzdesign-mcp` over stdio (or `node /absolute/path/to/dist/index.js` from a clone).
 
 ### Dev & debug
 
@@ -184,7 +214,8 @@ To rebuild the local image library (or add your own examples), see
 [MIT](LICENSE) © 2026 Saglitz Design.
 
 The `knowledge/` documents are original syntheses with sources cited per file.
-Referenced screenshots are not part of this repo and may not be redistributed.
+Referenced screenshots are not part of this repo and may not be redistributed —
+see [NOTICE.md](NOTICE.md).
 
 <div align="center">
 <sub>Built for the <a href="https://modelcontextprotocol.io">Model Context Protocol</a>.</sub>

package/dist/index.js

@@ -7,6 +7,7 @@ import { dirname, join } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
 import { loadKnowledge, searchKnowledge, sections } from "./knowledge.js";
 import { loadExamples, searchExamples, imageMime } from "./examples.js";
+import { registerPrompts } from "./prompts.js";
 // knowledge/ sits next to dist/ (repo root) both in dev (tsx) and after build
 const here = dirname(fileURLToPath(import.meta.url));
 const knowledgeDir = [join(here, "..", "knowledge"), join(here, "..", "..", "knowledge")].find(existsSync);
@@ -19,7 +20,7 @@ const examplesDir = join(knowledgeDir, "examples");
 const examples = loadExamples(examplesDir);
 const server = new McpServer({
     name: "saglitzdesign",
-    version: "0.3.1",
+    version: "0.4.0",
 });
 function docHeader(d) {
     return `# ${d.title}\n_id: ${d.id} · category: ${d.category} · platform: ${d.platform} · tags: ${d.tags.join(", ")}_\n`;
@@ -368,6 +369,13 @@ server.tool("knowledge_freshness", "Report how fresh each knowledge document is
     ];
     return text(lines.join("\n"));
 });
+// ── prompts (user-invocable build/review/redesign workflows) ─────────────────
+registerPrompts(server, {
+    brief: z
+        .string()
+        .optional()
+        .describe("What to build/review, in your words (audience, offer, stack, URL…). Optional — the workflow will ask for anything missing."),
+});
 // ── start ────────────────────────────────────────────────────────────────────
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/dist/prompts.js

@@ -0,0 +1,146 @@
+// SaglitzDesign MCP prompts — user-invocable workflows that orchestrate the
+// server's knowledge tools into an end-to-end "build / review / redesign"
+// experience. In Claude Code these appear in the "/" (slash) prompt menu.
+const TOOLS_NOTE = `You have the SaglitzDesign knowledge tools available. Use them — do not design from memory:
+- get_design_roadmap(project_type) — the phased plan; call FIRST.
+- search_design_knowledge(query) / get_design_doc(id) — rules & specs.
+- get_component_guidance(component, platform) — per-component specs + patterns.
+- get_design_examples(query, platform) — real annotated screenshots to reference.
+- get_design_language(language) — Material 3 / Liquid Glass / iOS / Android / macOS / Fluent / web-trends / tokens.
+- seo_geo_guide(scope, topic) — SEO & GEO for web.
+- design_review_checklist(project_type, focus) — the audit gate.`;
+const CRITIQUE_LOOP = `## Visual critique loop (do this, don't skip it)
+After you build something runnable:
+1. Run it and open it in a browser. If a browser-automation tool is available
+   (Claude in Chrome, Playwright, or chrome-devtools MCP), navigate to the page
+   and take a screenshot at both mobile (390px) and desktop (1440px) widths.
+   If no browser tool is available, say so and review the code directly instead.
+2. Look at the screenshot as a critical senior designer. Score it against the
+   rubric in get_design_doc("design-critique-scoring") (0–40) and run the
+   matching design_review_checklist.
+3. Fix the highest-severity issues first (hierarchy, one primary CTA, spacing
+   from the scale, contrast ≥ the required ratios, real content stress).
+4. Re-screenshot and repeat until it passes the checklist and the squint test
+   (the primary action is the first thing you see). Report the before/after.`;
+const QUALITY_BAR = `## Non-negotiables (from the knowledge base)
+- Content & copy BEFORE chrome: write the real headline/CTA/empty/error copy first (never lorem ipsum).
+- Exactly one primary CTA per view; verb-first labels ("Start free trial", never "Submit").
+- Everything on the 8pt spacing scale; tokens for color/type/spacing, not ad-hoc values.
+- Text contrast ≥4.5:1, non-text ≥3:1; visible focus states; keyboard reachable.
+- Design every state: default, empty, loading, error, long-content, zero-results.
+- Respect prefers-reduced-motion; motion durations/easings per the motion doc.
+- For web: semantic HTML, LCP ≤2.5s discipline (image/font rules), no layout shift.`;
+const BUILD_PROMPTS = [
+    {
+        name: "build_landing_page",
+        title: "Build a landing page (SaglitzDesign)",
+        description: "Design & build a conversion-focused landing page end-to-end using SaglitzDesign expertise, with a visual critique loop.",
+        build: (brief) => `Build a high-converting **landing page**${brief ? ` for: ${brief}` : ""}, using the SaglitzDesign method.
+
+${TOOLS_NOTE}
+
+## Sequence
+1. Call get_design_roadmap("landing-page") and follow its phases.
+2. **Positioning & message first.** If key facts are missing (who it's for, the offer, the one conversion goal, proof points), ask me up to 4 concise questions before building. Then draft the hero headline, subhead, primary CTA + risk-reducers, and the section narrative (hero → proof → benefits → objections/FAQ → final CTA). Pull rules from get_design_doc("storybrand-copywriting"), get_design_doc("conversion-ux"), get_design_doc("influence-persuasion").
+3. **Reference real examples:** get_design_examples("hero", "web"), get_design_examples("pricing", "web"), get_design_examples("social proof", "web").
+4. **Build it.** Write the actual code (default to a single responsive HTML file with inline CSS unless I specify a stack like Next.js/React/Tailwind). Apply the foundations: typography, color-systems, spacing-layout, buttons, visual-craft-standards.
+5. **SEO/GEO:** apply seo_geo_guide("both") essentials — semantic HTML, meta/title, one H1, JSON-LD, fast images/fonts.
+
+${QUALITY_BAR}
+
+${CRITIQUE_LOOP}
+
+Finish with: the files created, how to preview it, the critique score, and what you'd test/improve next.`,
+    },
+    {
+        name: "build_website",
+        title: "Build a website (SaglitzDesign)",
+        description: "Design & build a multi-page marketing website end-to-end using SaglitzDesign expertise, with a visual critique loop.",
+        build: (brief) => `Build a marketing **website**${brief ? ` for: ${brief}` : ""}, using the SaglitzDesign method.
+
+${TOOLS_NOTE}
+
+## Sequence
+1. Call get_design_roadmap("website") and follow its phases (positioning → copy → IA/SEO → design → build → CRO).
+2. **Positioning + IA first.** Ask me up to 4 questions if the audience, offer, conversion goal, or page set is unclear. Then propose a sitemap (home, product/features, pricing, about, contact, etc.), each page mapped to one search intent.
+3. **Copy before layout** for each page (get_design_doc("storybrand-copywriting"), get_design_doc("marketing-website-roadmap")).
+4. **SEO/GEO foundations up front:** seo_geo_guide("both") — rendering, meta, schema plan, llms.txt, internal linking.
+5. **Reference real examples** via get_design_examples for each section type.
+6. **Build it** as a coherent multi-page site (default: static HTML/CSS with shared styles, or a Next.js app if I ask). Shared design tokens; consistent nav/footer; every page in all states.
+
+${QUALITY_BAR}
+
+${CRITIQUE_LOOP}
+
+Finish with: sitemap built, files, preview instructions, per-page critique scores, SEO/GEO checklist status, and next steps.`,
+    },
+    {
+        name: "build_mobile_app_ui",
+        title: "Build a mobile app UI (SaglitzDesign)",
+        description: "Design & build iOS or Android app screens end-to-end using SaglitzDesign expertise, with a visual critique loop.",
+        build: (brief) => `Design and build **mobile app UI**${brief ? ` for: ${brief}` : ""}, using the SaglitzDesign method.
+
+${TOOLS_NOTE}
+
+## Sequence
+1. Ask which platform (iOS or Android) and stack (SwiftUI / Jetpack Compose / React Native / Flutter) if not stated, plus the 2–3 core screens to build. Ask up to 4 questions max.
+2. Call get_design_roadmap("ios-app") or ("android-app") and follow it.
+3. Load the platform baseline: get_design_language("ios-app-design") + ("apple-hig-liquid-glass"), or ("android-app-design") + ("material-3"). Respect native navigation, controls, safe areas, Dynamic Type / sp.
+4. **Reference real examples** with get_design_examples (platform "mobile"): onboarding, paywall, navigation, empty-state, etc.
+5. **Build the screens** with get_component_guidance for each element; design every state; thumb-zone the primary actions.
+
+${QUALITY_BAR}
+
+${CRITIQUE_LOOP}
+
+Finish with: screens built, how to run/preview, critique scores, platform-fit notes, and next steps.`,
+    },
+];
+const ACTION_PROMPTS = [
+    {
+        name: "design_review",
+        title: "Design review (SaglitzDesign)",
+        description: "Audit an existing website / app / landing page against SaglitzDesign checklists and the 0–40 critique rubric.",
+        build: (brief) => `Do an expert **design review**${brief ? ` of: ${brief}` : ""}, using the SaglitzDesign method.
+
+${TOOLS_NOTE}
+
+## Sequence
+1. Identify the project type (website / landing-page / mobile-app / macos-app / dashboard). If it's a URL or running app and a browser tool is available, open it and screenshot mobile + desktop; otherwise review the code/design provided.
+2. Run design_review_checklist for that type (and a focused pass: accessibility, conversion, seo, etc.).
+3. Score against get_design_doc("design-critique-scoring") (0–40) with per-heuristic notes.
+4. Report findings ranked by severity (P0→P3): what's wrong, why (cite the rule/doc), and the concrete fix. Separate "must fix" from "polish".
+5. If asked, apply the top fixes and re-review.
+
+Be specific and prescriptive — every finding cites a SaglitzDesign rule and gives an actionable fix, not vague advice.`,
+    },
+    {
+        name: "redesign",
+        title: "Redesign / improve a UI (SaglitzDesign)",
+        description: "Improve an existing UI (bolder, quieter, cleaner, higher-converting) using SaglitzDesign craft standards, with a visual critique loop.",
+        build: (brief) => `**Redesign / improve** the UI${brief ? `: ${brief}` : ""}, using the SaglitzDesign method.
+
+${TOOLS_NOTE}
+
+## Sequence
+1. First review the current state: run design_review_checklist and score it (get_design_doc("design-critique-scoring")). State the top problems and the design direction you'll take (and why).
+2. Pull the relevant craft docs: visual-craft-standards, typography-craft, and the foundations (typography, color-systems, spacing-layout). For conversion goals, add conversion-ux + storybrand-copywriting.
+3. Reference real examples with get_design_examples for the pattern in question.
+4. **Apply the changes in code**, preserving working behavior. Improve hierarchy by de-emphasizing secondary content rather than only enlarging primary; fix spacing to the scale; one primary CTA; contrast; states.
+
+${QUALITY_BAR}
+
+${CRITIQUE_LOOP}
+
+Finish with a concrete before→after: the score change, what you changed and why, and what to test next.`,
+    },
+];
+const ALL_PROMPTS = [...BUILD_PROMPTS, ...ACTION_PROMPTS];
+// Registered against an McpServer-like object exposing registerPrompt.
+export function registerPrompts(server, briefArg) {
+    for (const p of ALL_PROMPTS) {
+        server.registerPrompt(p.name, { title: p.title, description: p.description, argsSchema: briefArg }, ({ brief }) => ({
+            messages: [{ role: "user", content: { type: "text", text: p.build((brief ?? "").trim()) } }],
+        }));
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "saglitzdesign-mcp",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "SaglitzDesign — expert MCP server for mobile app & website design: UI, UX, buttons, design languages, SEO and GEO guidance backed by a curated knowledge base and real-world pattern research.",
   "type": "module",
   "bin": {
@@ -13,7 +13,8 @@
     "!knowledge/examples/images",
     "scripts/regenerate-examples.md",
     "LICENSE",
-    "README.md"
+    "README.md",
+    "NOTICE.md"
   ],
   "engines": {
     "node": ">=18"