designmd-forge 1.2.0

package/dist/httpServer.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+import express from 'express';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { createServer, SERVER_NAME, SERVER_VERSION } from './server.js';
+const PORT = Number(process.env.PORT ?? 3000);
+const MCP_PATH = process.env.MCP_PATH ?? '/mcp';
+const app = express();
+app.use(express.json({ limit: '2mb' }));
+// Permissive CORS so browser-based MCP clients (e.g. Claude web) can
+// connect directly, matching the no-auth remote-connector pattern used
+// for mcp.quran.us.kg. Tighten this (specific origins) if you'd rather
+// not allow arbitrary browser origins.
+app.use((req, res, next) => {
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Mcp-Session-Id, Mcp-Protocol-Version');
+    res.setHeader('Access-Control-Expose-Headers', 'Mcp-Session-Id');
+    if (req.method === 'OPTIONS') {
+        res.sendStatus(204);
+        return;
+    }
+    next();
+});
+app.get('/', (_req, res) => {
+    res.json({
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
+        transport: 'streamable-http',
+        mcp_endpoint: MCP_PATH,
+        status: 'ok',
+    });
+});
+app.get('/health', (_req, res) => {
+    res.status(200).send('ok');
+});
+// Stateless mode: a fresh McpServer + transport per request. No session
+// state is needed since every tool here is a pure read (or a lint call
+// with no cross-request memory), so there's nothing to gain from holding
+// a session open, and it keeps the deployment simple (no session store,
+// safe behind a load balancer / restart without losing in-flight state).
+app.post(MCP_PATH, async (req, res) => {
+    try {
+        const server = createServer();
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: undefined,
+        });
+        res.on('close', () => {
+            transport.close();
+            server.close();
+        });
+        await server.connect(transport);
+        await transport.handleRequest(req, res, req.body);
+    }
+    catch (error) {
+        console.error('MCP request error:', error);
+        if (!res.headersSent) {
+            res.status(500).json({
+                jsonrpc: '2.0',
+                error: { code: -32603, message: 'Internal server error' },
+                id: null,
+            });
+        }
+    }
+});
+// Stateless mode has no session to resume or close, so GET (server-push
+// streams) and DELETE (session termination) aren't meaningful here.
+app.get(MCP_PATH, (_req, res) => {
+    res.status(405).json({
+        jsonrpc: '2.0',
+        error: { code: -32000, message: 'Method not allowed: this server runs in stateless mode' },
+        id: null,
+    });
+});
+app.delete(MCP_PATH, (_req, res) => {
+    res.status(405).json({
+        jsonrpc: '2.0',
+        error: { code: -32000, message: 'Method not allowed: this server runs in stateless mode' },
+        id: null,
+    });
+});
+app.listen(PORT, () => {
+    console.error(`${SERVER_NAME} (Streamable HTTP) listening on port ${PORT}, endpoint ${MCP_PATH}`);
+});

package/dist/index.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('designmd-forge running on stdio');
+}
+main().catch((error) => {
+    console.error('Server error:', error);
+    process.exit(1);
+});

package/dist/server.js

@@ -0,0 +1,32 @@
+import { createRequire } from 'node:module';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerBrowseTools } from './tools/browse.js';
+import { registerGetDesignTool } from './tools/getDesign.js';
+import { registerGuardrailsTool } from './tools/guardrails.js';
+import { registerLintTool } from './tools/lint.js';
+import { registerDiffTool } from './tools/diff.js';
+import { registerAuthoringTools } from './tools/authoring.js';
+// Derive name/version from package.json so they never drift from the npm
+// manifest (works from src/ in dev and dist/ after build, both one level deep).
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+export const SERVER_NAME = pkg.name;
+export const SERVER_VERSION = pkg.version;
+/**
+ * Builds a fresh McpServer instance with all tools registered. Used by
+ * both the stdio entry point (one long-lived server per process) and the
+ * HTTP entry point (one server per request, in stateless mode).
+ */
+export function createServer() {
+    const server = new McpServer({
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
+    });
+    registerBrowseTools(server);
+    registerGetDesignTool(server);
+    registerGuardrailsTool(server);
+    registerLintTool(server);
+    registerDiffTool(server);
+    registerAuthoringTools(server);
+    return server;
+}

package/dist/services/designStore.js

@@ -0,0 +1,59 @@
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DATA_DIR = join(__dirname, '..', 'data');
+let cachedIndex = null;
+export function loadIndex() {
+    if (cachedIndex)
+        return cachedIndex;
+    const raw = readFileSync(join(DATA_DIR, 'index.json'), 'utf-8');
+    cachedIndex = JSON.parse(raw);
+    return cachedIndex;
+}
+export function getEntryBySlug(slug) {
+    const normalized = slug.trim().toLowerCase();
+    return loadIndex().designs.find((d) => d.slug.toLowerCase() === normalized);
+}
+export function readDesignMdContent(slug) {
+    const path = join(DATA_DIR, 'designs', `${slug}.md`);
+    return readFileSync(path, 'utf-8');
+}
+export function listCategories() {
+    return loadIndex().categories;
+}
+/**
+ * Lightweight relevance scoring across title, category, short/long
+ * description. No external search dependency needed for ~85 documents.
+ */
+export function searchDesigns(query, opts = {}) {
+    const { designs } = loadIndex();
+    const terms = query
+        .toLowerCase()
+        .split(/\s+/)
+        .map((t) => t.trim())
+        .filter(Boolean);
+    const scored = designs
+        .filter((d) => opts.category ? d.category.toLowerCase() === opts.category.toLowerCase() : true)
+        .filter((d) => (opts.platform ? d.platform === opts.platform : true))
+        .map((d) => {
+        const haystacks = [
+            [d.title.toLowerCase(), 5],
+            [d.slug.toLowerCase(), 4],
+            [d.category.toLowerCase(), 2],
+            [d.short_description.toLowerCase(), 3],
+            [d.long_description.toLowerCase(), 1],
+        ];
+        let score = 0;
+        for (const term of terms) {
+            for (const [text, weight] of haystacks) {
+                if (text.includes(term))
+                    score += weight;
+            }
+        }
+        return { ...d, score };
+    })
+        .filter((d) => terms.length === 0 || d.score > 0)
+        .sort((a, b) => b.score - a.score);
+    return scored.slice(0, opts.limit ?? 20);
+}

package/dist/services/linter.js

@@ -0,0 +1,87 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { writeFile, unlink, mkdtemp } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+const execFileAsync = promisify(execFile);
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// Resolve the locally installed CLI entry point and run it through the current
+// node binary rather than shelling out to the npm `.bin` shim. This works
+// offline after `npm install`/`yarn install`, doesn't silently fetch a
+// different version at call time, and avoids Windows `.cmd` spawn quirks
+// (execFile cannot launch batch wrappers without a shell).
+const CLI_ENTRY = join(__dirname, '..', '..', 'node_modules', '@google', 'design.md', 'dist', 'index.js');
+/**
+ * Runs the official @google/design.md CLI (npm: @google/design.md, binary:
+ * designmd) with `lint` on the given content. The CLI can exit non-zero on
+ * findings while still printing valid JSON to stdout, so we parse stdout on
+ * both success and non-zero exit paths. Writes content to a temp file for
+ * portability across platforms.
+ */
+export async function lintDesignMdContent(content) {
+    const dir = await mkdtemp(join(tmpdir(), 'designmd-lint-'));
+    const filePath = join(dir, 'DESIGN.md');
+    try {
+        await writeFile(filePath, content, 'utf-8');
+        const { stdout } = await execFileAsync(process.execPath, [CLI_ENTRY, 'lint', '--format', 'json', filePath], {
+            timeout: 15000,
+        });
+        return JSON.parse(stdout);
+    }
+    catch (err) {
+        const asExecError = err;
+        if (asExecError.stdout) {
+            try {
+                return JSON.parse(asExecError.stdout);
+            }
+            catch {
+                // fall through to rethrow below
+            }
+        }
+        throw new Error(`designmd lint CLI failed: ${asExecError.message ?? String(err)}`, {
+            cause: err,
+        });
+    }
+    finally {
+        await unlink(filePath).catch(() => { });
+    }
+}
+/**
+ * Compares two DESIGN.md documents with the official @google/design.md CLI's
+ * `diff` command. It diffs declared tokens (colors, typography, rounded,
+ * spacing, components) and reports a `regression` flag (exit 1 = regression).
+ * Returns the parsed JSON it prints to stdout.
+ */
+export async function diffDesignMdContent(beforeContent, afterContent) {
+    const dir = await mkdtemp(join(tmpdir(), 'designmd-diff-'));
+    const beforePath = join(dir, 'before.DESIGN.md');
+    const afterPath = join(dir, 'after.DESIGN.md');
+    try {
+        await writeFile(beforePath, beforeContent, 'utf-8');
+        await writeFile(afterPath, afterContent, 'utf-8');
+        const { stdout } = await execFileAsync(process.execPath, [CLI_ENTRY, 'diff', beforePath, afterPath], {
+            timeout: 15000,
+        });
+        return JSON.parse(stdout);
+    }
+    catch (err) {
+        // Non-zero exit on regression still prints the JSON to stdout.
+        const asExecError = err;
+        if (asExecError.stdout) {
+            try {
+                return JSON.parse(asExecError.stdout);
+            }
+            catch {
+                // fall through to rethrow below
+            }
+        }
+        throw new Error(`designmd diff CLI failed: ${asExecError.message ?? String(err)}`, {
+            cause: err,
+        });
+    }
+    finally {
+        await unlink(beforePath).catch(() => { });
+        await unlink(afterPath).catch(() => { });
+    }
+}

package/dist/services/sectionParser.js

@@ -0,0 +1,154 @@
+/**
+ * Parses a DESIGN.md file's "## Section" headings into a normalized map,
+ * regardless of which of the two observed formats it uses:
+ *   - Numbered Stitch-extended format: "## 1. Visual Theme & Atmosphere"
+ *   - Plain format: "## Overview", "## Colors", "## Do's and Don'ts"
+ */
+export const CANONICAL_SECTIONS = [
+    'overview',
+    'colors',
+    'typography',
+    'layout',
+    'elevation',
+    'shapes',
+    'components',
+    'dos_and_donts',
+    'responsive',
+    'iteration_guide',
+    'known_gaps',
+    'agent_prompt_guide',
+    // Mobile-specific sections (TrustOtc/awesome-mobile-design-md archetypes)
+    'design_principles',
+    'safe_area',
+    'touch_interaction',
+    'navigation',
+    'motion',
+    'iconography',
+    'accessibility',
+    'platform_adaptation',
+];
+const HEADING_ALIASES = {
+    overview: 'overview',
+    'visual theme & atmosphere': 'overview',
+    colors: 'colors',
+    'color palette & roles': 'colors',
+    typography: 'typography',
+    'typography rules': 'typography',
+    layout: 'layout',
+    'layout principles': 'layout',
+    elevation: 'elevation',
+    'elevation & depth': 'elevation',
+    'depth & elevation': 'elevation',
+    shapes: 'shapes',
+    components: 'components',
+    'component stylings': 'components',
+    "do's and don'ts": 'dos_and_donts',
+    'responsive behavior': 'responsive',
+    'iteration guide': 'iteration_guide',
+    'known gaps': 'known_gaps',
+    'agent prompt guide': 'agent_prompt_guide',
+    // Mobile archetypes (TrustOtc/awesome-mobile-design-md)
+    'design principles': 'design_principles',
+    'color system': 'colors',
+    'spacing system': 'layout',
+    'layout & safe area': 'safe_area',
+    'touch & interaction': 'touch_interaction',
+    'navigation patterns': 'navigation',
+    motion: 'motion',
+    iconography: 'iconography',
+    accessibility: 'accessibility',
+    'platform adaptation': 'platform_adaptation',
+    "do / don't": 'dos_and_donts',
+    "do and don't": 'dos_and_donts',
+};
+function normalizeHeading(raw) {
+    // Strip a leading "N. " numbering prefix, then lowercase for lookup
+    const cleaned = raw
+        .replace(/^\d+\.\s*/, '')
+        .trim()
+        .toLowerCase();
+    return HEADING_ALIASES[cleaned] ?? null;
+}
+/**
+ * Splits a DESIGN.md file's body into canonical sections. Content before
+ * the first "## " heading (e.g. YAML frontmatter, an "# Title" line, or
+ * intro prose) is not included in any section.
+ */
+export function parseSections(content) {
+    const lines = content.split('\n');
+    const sections = [];
+    let current = null;
+    for (const line of lines) {
+        const match = line.match(/^##\s+(.+?)\s*$/);
+        if (match) {
+            if (current) {
+                sections.push({
+                    canonical: current.canonical,
+                    heading: current.heading,
+                    content: current.lines.join('\n').trim(),
+                });
+            }
+            const canonical = normalizeHeading(match[1]);
+            current = canonical ? { heading: match[1], canonical, lines: [] } : null;
+            continue;
+        }
+        // Stop capturing if we hit a top-level "# " heading after a section started
+        if (/^#\s+/.test(line) && current) {
+            sections.push({
+                canonical: current.canonical,
+                heading: current.heading,
+                content: current.lines.join('\n').trim(),
+            });
+            current = null;
+            continue;
+        }
+        if (current)
+            current.lines.push(line);
+    }
+    if (current) {
+        sections.push({
+            canonical: current.canonical,
+            heading: current.heading,
+            content: current.lines.join('\n').trim(),
+        });
+    }
+    return sections;
+}
+export function getSection(content, section) {
+    return parseSections(content).find((s) => s.canonical === section);
+}
+/**
+ * Splits a parsed section's body into its "### " component sub-groups
+ * (e.g. the sub-groups inside a "Component Stylings" section: Buttons,
+ * Navigation, Cards & Containers, Input Fields, Distinctive Components).
+ * Names are NOT a controlled vocabulary - they vary per file - so matching is
+ * best-effort (exact, then substring either direction).
+ */
+export function getComponentGroups(sectionBody) {
+    const lines = sectionBody.split('\n');
+    const groups = [];
+    let current = null;
+    for (const line of lines) {
+        const m = line.match(/^###\s+(.+?)\s*$/);
+        if (m) {
+            if (current)
+                groups.push(current);
+            current = { heading: m[1].trim(), content: '' };
+            continue;
+        }
+        if (current)
+            current.content += line + '\n';
+    }
+    if (current)
+        groups.push(current);
+    return groups.map((g) => ({ heading: g.heading, content: g.content.trim() }));
+}
+export function findComponentGroup(sectionBody, query) {
+    const groups = getComponentGroups(sectionBody);
+    const available = groups.map((g) => g.heading);
+    const q = query.trim().toLowerCase();
+    const group = groups.find((g) => g.heading.toLowerCase() === q) ??
+        groups.find((g) => g.heading.toLowerCase().includes(q)) ??
+        groups.find((g) => q.includes(g.heading.toLowerCase()));
+    return { group, available };
+}

package/dist/tools/authoring.js

@@ -0,0 +1,131 @@
+import { z } from 'zod';
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+function loadAuthoringGuide() {
+    return readFileSync(join(__dirname, '..', 'data', 'authoring-guide.md'), 'utf-8');
+}
+const ScaffoldInputSchema = z
+    .object({
+    product_name: z
+        .string()
+        .min(1)
+        .max(100)
+        .default('Your Product')
+        .describe("Name to use in the scaffold's placeholder comments (default: 'Your Product')."),
+})
+    .strict();
+function buildScaffold(productName) {
+    return `---
+name: ${productName}
+colors:
+  primary: "#000000" # TODO: your primary color's actual hex
+  # TODO: add the rest of your token block (typography, spacing, rounding, components)
+---
+
+## Overview
+
+<!--
+Write 2-4 concrete sentences on this product's visual personality — concrete
+enough to rule things out, not just describe a vibe. Weak: "clean and modern".
+Stronger: "information-dense, no gradients, no decorative illustration,
+professional tone closer to a financial terminal than a consumer app."
+This is the section an agent falls back on for anything your tokens don't
+explicitly cover, so vague prose here costs you everywhere.
+-->
+
+## Colors
+
+<!--
+For EACH color token, state its role and its boundary, not just its value.
+Weak: "primary: #0D7377" (that's already in the YAML above).
+Stronger: "Primary teal is reserved for interactive elements — buttons,
+links, active states. It never appears on backgrounds, dividers, or
+decorative elements." Add one sentence per token that has a role beyond
+"just a color". This section tends to be worth more per sentence than any
+other — expect it to grow the most as you catch misapplications.
+-->
+
+## Do's and Don'ts
+
+<!--
+Negative, specific constraints tend to be followed more reliably than
+positive general ones. Build this list from OBSERVED failures, not
+speculation — every time a generated screen gets a decision wrong (not a
+token wrong), add the specific "never do X, do Y instead" line that would
+have prevented it. Also seed it with known team pain points:
+  - What has an AI-generated screen from this project gotten wrong before?
+  - What accessibility/contrast rules does QA care about?
+  - What visual patterns does this product deliberately avoid that a
+    generic Tailwind-style agent would reach for by default (shadows on
+    cards? gradients? rounded corners everywhere)?
+-->
+
+<!-- Optional secondary sections below — fill in if relevant, skip if not. -->
+
+## Typography
+
+## Layout
+
+## Elevation
+
+## Components
+
+## Responsive Behavior
+
+## Agent Prompt Guide
+`;
+}
+export function registerAuthoringTools(server) {
+    server.registerTool('designmd_get_authoring_guide', {
+        title: 'Get DESIGN.md Authoring Guide',
+        description: `Fetch a condensed, field-tested guide on WRITING a DESIGN.md file's prose sections — not fetching an existing one.
+
+Covers: why token-only DESIGN.md files under-perform, which sections tend to carry most of the improvement (Overview, Colors, Do's and Don'ts), concrete prose-writing principles (specificity, negative constraints, edge-case coverage, conciseness), a recommended draft-then-refine process, and known format limitations. This is reference material for a human or agent about to draft or improve a DESIGN.md for their OWN product — it does not fetch any of the bundled example designs (use designmd_get_design_md for that).
+
+Args: none.
+
+Returns: the guide as markdown text.
+
+Examples:
+  - Use when: "help me write a DESIGN.md for my app" -> call this first, then designmd_scaffold_template
+  - Use when: "why isn't my DESIGN.md changing the agent's output?" -> likely a token-only-file problem this guide addresses directly
+  - Don't use when: you want an existing site's design system (use designmd_search_designs / designmd_get_design_md)`,
+        inputSchema: {},
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async () => {
+        const guide = loadAuthoringGuide();
+        return { content: [{ type: 'text', text: guide }] };
+    });
+    server.registerTool('designmd_scaffold_template', {
+        title: 'Scaffold a New DESIGN.md Template',
+        description: `Generate a fill-in-the-blank DESIGN.md skeleton for a NEW file, structured around the three sections that tend to matter most (Overview, Colors, Do's and Don'ts) with inline prompts guiding what to write in each — rather than a bare empty section list.
+
+This is a starting scaffold, not a finished file: the YAML token block is a stub you fill in with your own real values, and the prose comments are prompts, not filler — replace them with your product's actual answers. Pair with designmd_get_authoring_guide for the reasoning behind why the scaffold is shaped this way, and designmd_lint once drafted.
+
+Args:
+  - product_name (string, optional): Used in the scaffold's YAML name field and comments. Defaults to "Your Product".
+
+Returns: the scaffold as markdown text, ready to save as DESIGN.md and edit.
+
+Examples:
+  - Use when: "give me a DESIGN.md starting point for [product]" -> product_name="[product]"
+  - Don't use when: you want an existing site's file to use as inspiration (use designmd_get_design_md instead, then don't copy its prose verbatim — write your own)`,
+        inputSchema: ScaffoldInputSchema.shape,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async (params) => {
+        const scaffold = buildScaffold(params.product_name);
+        return { content: [{ type: 'text', text: scaffold }] };
+    });
+}