@thedesignagent/mcp 0.0.0-stage → 0.2.0

package/dist/auth-capture.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/auth-capture.js

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+import { findChromeExecutable, isLoginUrl } from './screenshot.js';
+import { saveStoredAuth } from './auth-store.js';
+import { createInterface } from 'node:readline';
+function printUsage() {
+    console.error('Usage: thedesignagent-auth capture <url>');
+    console.error('Example: thedesignagent-auth capture http://localhost:3000');
+}
+async function snapshotSession(browser, page, hostname) {
+    try {
+        const rawCookies = await browser.defaultBrowserContext().cookies();
+        const cookies = rawCookies
+            .filter(c => c.domain.includes(hostname) || hostname.includes(c.domain.replace(/^\./, '')))
+            .map(c => ({
+            name: c.name,
+            value: c.value,
+            domain: c.domain,
+            path: c.path,
+            httpOnly: c.httpOnly,
+            secure: c.secure,
+            sameSite: (c.sameSite === 'Strict' || c.sameSite === 'Lax' || c.sameSite === 'None') ? c.sameSite : undefined,
+        }));
+        const storage = await page.evaluate(() => ({
+            localStorage: Object.fromEntries(Object.keys(localStorage).map(k => [k, localStorage.getItem(k) ?? ''])),
+            sessionStorage: Object.fromEntries(Object.keys(sessionStorage).map(k => [k, sessionStorage.getItem(k) ?? ''])),
+        }));
+        return {
+            cookies,
+            localStorage: storage.localStorage,
+            sessionStorage: storage.sessionStorage,
+            finalUrl: page.url(),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function waitForEnter() {
+    return new Promise(resolve => {
+        if (!process.stdin.isTTY) {
+            // No TTY (e.g. backgrounded by an agent) — never resolves. Browser-close will trigger instead.
+            return;
+        }
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        rl.once('line', () => { rl.close(); resolve('enter'); });
+    });
+}
+function waitForBrowserClose(browser) {
+    return new Promise(resolve => {
+        browser.on('disconnected', () => resolve('closed'));
+    });
+}
+// Post-trigger verification: if the browser is still alive after Enter was
+// pressed, navigate back to the original URL and re-snapshot. Catches "user
+// pressed Enter too early" — the partial session would otherwise be saved
+// silently and fail on every subsequent visual call.
+async function verifyAndSnapshot(browser, page, url, trigger, fallback) {
+    if (trigger !== 'enter' || !browser.connected)
+        return fallback;
+    try {
+        console.log('Verifying session…');
+        await page.goto(url.href, { waitUntil: 'networkidle0', timeout: 15000 });
+        const snap = await snapshotSession(browser, page, url.hostname);
+        return snap ?? fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
+async function main() {
+    const [, , subcommand, urlArg] = process.argv;
+    if (subcommand !== 'capture' || !urlArg) {
+        printUsage();
+        process.exit(1);
+    }
+    let url;
+    try {
+        url = new URL(urlArg);
+    }
+    catch {
+        console.error(`Invalid URL: ${urlArg}`);
+        process.exit(1);
+    }
+    const chromePath = findChromeExecutable();
+    if (!chromePath) {
+        console.error('Chrome/Chromium not found. Install Google Chrome (or set CHROME_PATH).');
+        process.exit(1);
+    }
+    const puppeteer = (await import('puppeteer-core')).default;
+    console.log(`▌TheDesignAgent▐ auth capture`);
+    console.log(`Opening ${url.href} in a browser window…`);
+    const browser = await puppeteer.launch({
+        executablePath: chromePath,
+        headless: false,
+        defaultViewport: { width: 1440, height: 900 },
+        args: ['--no-sandbox', '--disable-setuid-sandbox'],
+    });
+    const [page] = await browser.pages();
+    await page.goto(url.href, { waitUntil: 'domcontentloaded', timeout: 30000 });
+    // Continuously snapshot the session as the user navigates, so we always have
+    // a recent capture even if the browser is closed before they confirm.
+    let lastSnapshot = null;
+    const pollInterval = setInterval(async () => {
+        const snap = await snapshotSession(browser, page, url.hostname);
+        if (snap)
+            lastSnapshot = snap;
+    }, 2000);
+    const interactiveHint = process.stdin.isTTY
+        ? '→ When you\'re logged in, press Enter in your terminal OR close the browser window.'
+        : '→ When you\'re logged in, close the browser window. (No TTY detected.)';
+    console.log('');
+    console.log('→ Log in to your app in the browser window that just opened.');
+    console.log(interactiveHint);
+    console.log('');
+    const trigger = await Promise.race([waitForEnter(), waitForBrowserClose(browser)]);
+    clearInterval(pollInterval);
+    const verifiedSnapshot = await verifyAndSnapshot(browser, page, url, trigger, lastSnapshot);
+    if (trigger !== 'closed') {
+        try {
+            await browser.close();
+        }
+        catch { /* already closing */ }
+    }
+    if (!verifiedSnapshot) {
+        console.error('');
+        console.error('✗ No session captured — browser may have closed before login completed.');
+        console.error('  Re-run the command and log in before closing the window.');
+        process.exit(1);
+    }
+    if (isLoginUrl(verifiedSnapshot.finalUrl)) {
+        console.error('');
+        console.error('✗ Session not saved — after capture, navigating to the target URL still');
+        console.error('  redirected to a login page. This usually means:');
+        console.error('  • Login was not fully completed (2FA still pending? form not submitted?)');
+        console.error('  • You confirmed before reaching a logged-in page');
+        console.error('');
+        console.error(`  Final URL after verification: ${verifiedSnapshot.finalUrl}`);
+        console.error('');
+        console.error('  Re-run the command. Make sure you reach a logged-in page in the');
+        console.error('  browser before pressing Enter or closing the window.');
+        process.exit(1);
+    }
+    const seed = {
+        cookies: verifiedSnapshot.cookies,
+        ...(Object.keys(verifiedSnapshot.localStorage).length && { localStorage: verifiedSnapshot.localStorage }),
+        ...(Object.keys(verifiedSnapshot.sessionStorage).length && { sessionStorage: verifiedSnapshot.sessionStorage }),
+    };
+    const savedPath = saveStoredAuth(url.href, seed);
+    console.log('');
+    console.log(`✓ Trigger: ${trigger === 'closed' ? 'browser closed' : 'Enter pressed'}`);
+    console.log(`✓ Captured ${verifiedSnapshot.cookies.length} cookies, ${Object.keys(verifiedSnapshot.localStorage).length} localStorage entries, ${Object.keys(verifiedSnapshot.sessionStorage).length} sessionStorage entries`);
+    console.log(`✓ Final URL: ${verifiedSnapshot.finalUrl}`);
+    console.log(`✓ Saved to: ${savedPath}`);
+    console.log('');
+    console.log(`▌TheDesignAgent▐ will now auto-apply this session for any URL on ${url.origin}.`);
+    console.log(`To re-capture (after expiry or logout), run this command again.`);
+    process.exit(0);
+}
+main().catch(err => {
+    console.error('auth-capture failed:', err instanceof Error ? err.message : err);
+    process.exit(1);
+});

package/dist/auth-store.d.ts

@@ -0,0 +1,5 @@
+import type { AuthSeed } from './screenshot.js';
+export declare const AUTH_STORE_DIR: string;
+export declare function authFilePath(url: string): string;
+export declare function loadStoredAuth(url: string): AuthSeed | null;
+export declare function saveStoredAuth(url: string, seed: AuthSeed): string;

package/dist/auth-store.js

@@ -0,0 +1,27 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export const AUTH_STORE_DIR = join(homedir(), '.thedesignagent', 'auth');
+function safeFilename(origin) {
+    return origin.replace(/^https?:\/\//, '').replace(/[^a-z0-9.-]/gi, '_') + '.json';
+}
+export function authFilePath(url) {
+    return join(AUTH_STORE_DIR, safeFilename(new URL(url).origin));
+}
+export function loadStoredAuth(url) {
+    try {
+        const path = authFilePath(url);
+        if (!existsSync(path))
+            return null;
+        return JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function saveStoredAuth(url, seed) {
+    mkdirSync(AUTH_STORE_DIR, { recursive: true });
+    const path = authFilePath(url);
+    writeFileSync(path, JSON.stringify(seed, null, 2));
+    return path;
+}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * TheDesignAgent MCP Server
+ * Exposes three tools — discover, ux, visual — discoverable by Claude Code, Cursor, etc.
+ *
+ * Usage in claude_desktop_config.json:
+ * {
+ *   "mcpServers": {
+ *     "TheDesignAgent": {
+ *       "command": "npx",
+ *       "args": ["-y", "--package=@thedesignagent/mcp", "thedesignagent-mcp"],
+ *       "env": {
+ *         "THEDESIGNAGENT_API_KEY": "your_key_here",
+ *         "ANTHROPIC_API_KEY": "your_anthropic_key"  // optional: enables prompted fallback
+ *       }
+ *     }
+ *   }
+ * }
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,589 @@
+#!/usr/bin/env node
+/**
+ * TheDesignAgent MCP Server
+ * Exposes three tools — discover, ux, visual — discoverable by Claude Code, Cursor, etc.
+ *
+ * Usage in claude_desktop_config.json:
+ * {
+ *   "mcpServers": {
+ *     "TheDesignAgent": {
+ *       "command": "npx",
+ *       "args": ["-y", "--package=@thedesignagent/mcp", "thedesignagent-mcp"],
+ *       "env": {
+ *         "THEDESIGNAGENT_API_KEY": "your_key_here",
+ *         "ANTHROPIC_API_KEY": "your_anthropic_key"  // optional: enables prompted fallback
+ *       }
+ *     }
+ *   }
+ * }
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import Anthropic from '@anthropic-ai/sdk';
+import { z } from 'zod';
+import { dirname, join } from 'node:path';
+import { captureScreenshot } from './screenshot.js';
+import { loadStoredAuth } from './auth-store.js';
+const API_KEY = process.env.THEDESIGNAGENT_API_KEY;
+const API_BASE = process.env.THEDESIGNAGENT_API_BASE ?? 'https://bxqifcmkydlsgwgcpqda.supabase.co/functions/v1';
+const ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
+// ---- Logging --------------------------------------------------------------
+function log(level, step, detail) {
+    const ts = new Date().toISOString();
+    const line = detail
+        ? `[${ts}] [${level.toUpperCase()}] [${step}] ${detail}`
+        : `[${ts}] [${level.toUpperCase()}] ${step}`;
+    console.error(line);
+}
+// ---- Prompted fallback (ux only) ------------------------------------------
+const FALLBACK_SYSTEM_PROMPT = `You are TheDesignAgent — the UX judgment layer for agent-generated UI, running in degraded fallback mode (the primary pipeline is unavailable).
+
+You do NOT have a captured persona or job profile in this mode. Score against a generic professional user; flag this as low-confidence and recommend re-running once the pipeline is healthy.
+
+## The frame
+
+Cognitive Load Theory (Sweller, 1988) — three pillars:
+- INTRINSIC: unavoidable effort the task itself demands.
+- EXTRANEOUS: avoidable friction the interface adds (subsumes Quality, Accessibility, Copy issues — they all manifest as extraneous load).
+- GERMANE: productive effort that builds mental models / supports learning.
+
+Jobs-to-be-Done (Christensen et al.) — calibrates CLT scores.
+
+## Output format (ONLY valid JSON)
+{
+  "ux_score": number (0–10),
+  "summary": string (2–3 sentences on overall quality and the most important issue, note fallback mode),
+  "findings": [{ "dimension": string, "description": string, "severity": "critical"|"high"|"medium"|"low", "location": string? }],
+  "recommendations": [{ "change": string, "reason": string, "priority": "critical"|"high"|"medium"|"low" }],
+  "scores": { "heuristics": number, "cognitive": number, "patterns": number, "jtbd_fit": number }
+}
+
+findings: 3–8 specific violations. recommendations: 3–6 ordered by priority, actionable.`;
+async function runFallback(task, artifact, codebaseContext) {
+    const client = new Anthropic({ apiKey: ANTHROPIC_API_KEY });
+    const contextSection = codebaseContext
+        ? `\n\n## Codebase Context\n${codebaseContext.slice(0, 3000)}`
+        : '';
+    const userMessage = `## Task\n${task}\n\n## Artifact to Evaluate\n${artifact}${contextSection}\n\nReturn ONLY valid JSON matching the schema in the system prompt.`;
+    const response = await client.messages.create({
+        model: 'claude-opus-4-7',
+        max_tokens: 4000,
+        system: FALLBACK_SYSTEM_PROMPT,
+        messages: [{ role: 'user', content: userMessage }],
+    });
+    const text = response.content[0].type === 'text' ? response.content[0].text : '';
+    const jsonStr = text.replace(/^```(?:json)?\n?/m, '').replace(/\n?```$/m, '').trim();
+    try {
+        const parsed = JSON.parse(jsonStr);
+        return { ...parsed, status: 'ok', project_id: 'fallback' };
+    }
+    catch {
+        throw new Error(`Fallback Claude returned unparseable JSON. Raw: ${text.slice(0, 200)}`);
+    }
+}
+// ---- Output formatting ----------------------------------------------------
+function fmtScore(score) {
+    if (score === null || score === undefined || Number.isNaN(score))
+        return 'n/a';
+    return score % 1 === 0 ? `${score}.0` : `${score}`;
+}
+function formatUxBreakdown(scores) {
+    return (`Heuristics: ${fmtScore(scores.heuristics)} · Cognitive: ${fmtScore(scores.cognitive)} · ` +
+        `Patterns: ${fmtScore(scores.patterns)} · JTBD fit: ${fmtScore(scores.jtbd_fit)}`);
+}
+function formatVisualBreakdown(scores) {
+    return (`Brand: ${fmtScore(scores.brand)} · Visual cognitive: ${fmtScore(scores.visual_cognitive)} · ` +
+        `Aesthetic: ${fmtScore(scores.aesthetic)}`);
+}
+function formatFindings(findings) {
+    if (!findings?.length)
+        return [];
+    const lines = ['### Findings'];
+    for (const f of findings) {
+        const dim = f.dimension ?? f.track ?? 'general';
+        const loc = f.location ? ` *(${f.location})*` : '';
+        lines.push(`**[${f.severity.toUpperCase()}] ${dim}** — ${f.description}${loc}`, '');
+    }
+    return lines;
+}
+function formatRecommendations(recs) {
+    if (!recs?.length)
+        return [];
+    const lines = ['### Recommendations (implement before continuing)'];
+    for (const r of recs) {
+        lines.push(`**[${r.priority.toUpperCase()}]** ${r.change}`, `  *${r.reason}*`, '');
+    }
+    return lines;
+}
+function formatUxEval(result, isFallback) {
+    const parts = [];
+    if (isFallback) {
+        parts.push('⚠ Pipeline unavailable — evaluation ran in prompted mode (no corpus or project context).', '  Re-run when pipeline is healthy to get corpus-backed results.', '');
+    }
+    if (result.degradations?.length) {
+        parts.push(`⚠ Degraded: ${result.degradations.join(', ')}`, '');
+    }
+    parts.push(`## ▌TheDesignAgent▐ [ux] Evaluation`, '', `**ux_score: ${fmtScore(result.ux_score)}/10** | ${formatUxBreakdown(result.scores)}`, '', `### Summary`, result.summary, '', ...formatFindings(result.findings), ...formatRecommendations(result.recommendations));
+    return parts.join('\n');
+}
+function formatVisualEval(result) {
+    const parts = [];
+    if (result.degradations?.length) {
+        parts.push(`⚠ Degraded: ${result.degradations.join(', ')}`, '');
+    }
+    parts.push(`## ▌TheDesignAgent▐ [visual] Evaluation`, '', `**visual_score: ${fmtScore(result.visual_score)}/10** | ${formatVisualBreakdown(result.scores)}`, '', `### Summary`, result.summary, '', ...formatFindings(result.findings), ...formatRecommendations(result.recommendations));
+    return parts.join('\n');
+}
+function resolveAuthSeed(url, callSeed) {
+    if (callSeed)
+        return { seed: callSeed, source: 'param' };
+    const raw = process.env.THEDESIGNAGENT_AUTH_SEED;
+    if (raw) {
+        try {
+            return { seed: JSON.parse(raw), source: 'env' };
+        }
+        catch (e) {
+            log('warn', 'auth_seed_env_parse_failed', e instanceof Error ? e.message : String(e));
+        }
+    }
+    const stored = loadStoredAuth(url);
+    if (stored)
+        return { seed: stored, source: 'stored' };
+    return { source: 'none' };
+}
+async function tryCaptureScreenshot(url, authSeed) {
+    if (!url)
+        return {};
+    const { seed, source } = resolveAuthSeed(url, authSeed);
+    try {
+        const shot = await captureScreenshot(url, seed);
+        log('info', 'screenshot_captured', `path=${shot.localPath} bytes=${shot.bytes} auth_seed=${source} auth_required=${shot.authRequired} final_url=${shot.finalUrl}`);
+        return {
+            screenshot: shot.base64,
+            screenshotPath: shot.localPath,
+            authRequired: shot.authRequired,
+            finalUrl: shot.finalUrl,
+            authSeedSource: source,
+        };
+    }
+    catch (e) {
+        const screenshotError = e instanceof Error ? e.message : String(e);
+        log('warn', 'screenshot_failed', screenshotError);
+        return { screenshotError, authSeedSource: source };
+    }
+}
+function suggestedAuthCmd(renderUrl) {
+    try {
+        const origin = new URL(renderUrl).origin;
+        const authCapturePath = join(dirname(process.argv[1]), 'auth-capture.js');
+        return `node ${authCapturePath} capture ${origin}`;
+    }
+    catch {
+        return 'thedesignagent-auth capture <your-app-url>';
+    }
+}
+function buildAuthRequiredFooter(renderUrl, capture) {
+    const { screenshotPath, finalUrl, authSeedSource } = capture;
+    const expired = authSeedSource === 'stored';
+    const stateLine = expired
+        ? `A saved session for this origin existed but appears expired.`
+        : `No saved session for this origin yet.`;
+    const lines = [
+        `---`,
+        `🛑 ▌TheDesignAgent▐ — ACTION REQUIRED: page is behind authentication`,
+        ``,
+        `The visual eval ran against a login page, not the target screen. The findings above describe the login form and should be DISCARDED.`,
+        ``,
+        `${stateLine} The user must run this exact command in their own terminal:`,
+        ``,
+        `   ${suggestedAuthCmd(renderUrl)}`,
+        ``,
+        `WHAT TO DO NEXT:`,
+        `1. Surface the command above to the user verbatim.`,
+        `2. Tell them: a Chrome window will open — log in normally, then close it (or press Enter in the terminal).`,
+        `3. Wait for them to confirm they've run it.`,
+        `4. Then retry this visual call with the same render_url. Auth will be auto-applied.`,
+        ``,
+        `WHAT NOT TO DO:`,
+        `- Do not search the app's source for auth keys, JWT names, or localStorage tokens.`,
+        `- Do not attempt to construct auth_seed manually — it almost always fails (HttpOnly cookies are invisible to code search).`,
+        `- Do not run the capture command yourself in the background — it needs the user's interactive login.`,
+    ];
+    if (finalUrl) {
+        lines.push(``, `(Diagnostics: redirected to ${finalUrl})`);
+    }
+    if (screenshotPath) {
+        lines.push(`(Login-page screenshot saved at ${screenshotPath} for reference.)`);
+    }
+    return lines.join('\n');
+}
+function buildVisualFooter(renderUrl, capture) {
+    const { screenshotPath, screenshotError, authRequired, authSeedSource } = capture;
+    if (authRequired && renderUrl) {
+        return buildAuthRequiredFooter(renderUrl, capture);
+    }
+    if (screenshotPath) {
+        const lines = [`---`, `📸 Screenshot: ${screenshotPath}`, `   Source URL: ${renderUrl}`, `   (auto-deleted after 24h)`];
+        if (authSeedSource && authSeedSource !== 'none') {
+            lines.push(`   Auth seed: ${authSeedSource}`);
+        }
+        return lines.join('\n');
+    }
+    if (screenshotError && renderUrl) {
+        return [`---`, `⚠ Screenshot failed for ${renderUrl}: ${screenshotError}`, `   Eval ran in text-only mode (code analysis).`].join('\n');
+    }
+    if (renderUrl) {
+        return [`---`, `⚠ Screenshot not captured. Eval ran in text-only mode.`].join('\n');
+    }
+    return '';
+}
+function formatDiscoveryResult(result) {
+    if (result.status === 'needs_setup') {
+        return [
+            `## ▌TheDesignAgent▐ [discover] — Setup Required`,
+            '',
+            `**project_id:** ${result.project_id}`,
+            '',
+            `This is the first call for this project. No project model is stored yet.`,
+            '',
+            `### Extraction Task`,
+            result.extraction_task,
+            '',
+            `Resubmit to \`discover\` with \`project_model\` populated once extraction is complete.`,
+        ].join('\n');
+    }
+    if (result.status === 'model_stale') {
+        return [
+            `## ▌TheDesignAgent▐ [discover] — Model Stale`,
+            '',
+            `**project_id:** ${result.project_id}`,
+            '',
+            `The stored project model's schema_hash no longer matches. Re-extract and resubmit.`,
+            '',
+            `### Extraction Task`,
+            result.extraction_task,
+        ].join('\n');
+    }
+    const ok = result;
+    const parts = [
+        `## ▌TheDesignAgent▐ [discover] — Build Brief`,
+        '',
+        `**project_id:** ${ok.project_id} | type: ${ok.project_type} | design tokens: ${ok.has_design_tokens ? 'yes' : 'no'}`,
+        `**Active job:** ${ok.active_job}`,
+        '',
+    ];
+    if (ok.degradations?.length) {
+        parts.push(`⚠ Degraded: ${ok.degradations.join(', ')}`, '');
+    }
+    parts.push(ok.brief);
+    if (ok.tda_instructions) {
+        parts.push('', `---`, `_${ok.tda_instructions}_`);
+    }
+    return parts.join('\n');
+}
+// ---- Tool handlers --------------------------------------------------------
+async function handleUxCall(args) {
+    if (!API_KEY) {
+        return {
+            content: [{ type: 'text', text: 'THEDESIGNAGENT_API_KEY is not set. Add it to your MCP server config.' }],
+            isError: true,
+        };
+    }
+    log('info', 'pipeline_call', `tool=ux project_id=${args.project_id ?? 'none'} task_len=${args.task.length}`);
+    let pipelineStatus = 0;
+    let pipelineErrorType = 'unknown';
+    try {
+        const response = await fetch(`${API_BASE}/ux`, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                task: args.task,
+                artifact: args.artifact,
+                project_id: args.project_id,
+                repo_hash: args.repo_hash,
+                codebaseContext: args.codebase_context,
+                ...(args.stages?.length && { stages: args.stages }),
+            }),
+        });
+        pipelineStatus = response.status;
+        if (response.ok) {
+            const result = await response.json();
+            log('info', 'pipeline_ok', `ux_score=${result.ux_score}`);
+            return { content: [{ type: 'text', text: formatUxEval(result, false) }] };
+        }
+        const err = await response.json();
+        pipelineErrorType = err.error;
+        if (response.status === 401 || response.status === 403) {
+            log('error', 'pipeline_auth_failed', `${response.status} ${err.message}`);
+            return {
+                content: [{ type: 'text', text: `Authentication failed (${response.status}): ${err.message}\nCheck your THEDESIGNAGENT_API_KEY.` }],
+                isError: true,
+            };
+        }
+        if (response.status === 429) {
+            log('warn', 'pipeline_rate_limited', err.message);
+            return {
+                content: [{ type: 'text', text: `Rate limit reached: ${err.message}\nUpgrade your plan or wait until your monthly counter resets.` }],
+                isError: true,
+            };
+        }
+        if (response.status === 400) {
+            log('error', 'pipeline_bad_request', `${err.error}: ${err.message}`);
+            return {
+                content: [{ type: 'text', text: `Bad request (${err.error}): ${err.message}` }],
+                isError: true,
+            };
+        }
+        log('warn', 'pipeline_server_error', `status=${response.status} error=${err.error}`);
+    }
+    catch (networkErr) {
+        pipelineStatus = 0;
+        pipelineErrorType = 'network_error';
+        log('warn', 'pipeline_network_error', networkErr instanceof Error ? networkErr.message : String(networkErr));
+    }
+    // Prompted fallback
+    if (!ANTHROPIC_API_KEY) {
+        log('error', 'fallback_skipped', 'ANTHROPIC_API_KEY not set — cannot run prompted fallback');
+        return {
+            content: [{
+                    type: 'text',
+                    text: [
+                        `Pipeline unavailable (${pipelineStatus}, ${pipelineErrorType}).`,
+                        '',
+                        'A prompted fallback evaluation is available but requires ANTHROPIC_API_KEY in your MCP config.',
+                        'Add it and reload to enable automatic fallback when the pipeline is down.',
+                    ].join('\n'),
+                }],
+            isError: true,
+        };
+    }
+    log('info', 'fallback_start', `pipeline_status=${pipelineStatus} error=${pipelineErrorType}`);
+    try {
+        const fallback = await runFallback(args.task, args.artifact, args.codebase_context);
+        log('info', 'fallback_ok', `ux_score=${fallback.ux_score}`);
+        return { content: [{ type: 'text', text: formatUxEval(fallback, true) }] };
+    }
+    catch (fallbackErr) {
+        const msg = fallbackErr instanceof Error ? fallbackErr.message : String(fallbackErr);
+        log('error', 'fallback_failed', msg);
+        return {
+            content: [{
+                    type: 'text',
+                    text: [
+                        `Pipeline unavailable (${pipelineStatus}, ${pipelineErrorType}) and prompted fallback also failed.`,
+                        '',
+                        `Fallback error: ${msg}`,
+                        '',
+                        'Try again in a moment.',
+                    ].join('\n'),
+                }],
+            isError: true,
+        };
+    }
+}
+async function handleVisualCall(args) {
+    if (!API_KEY) {
+        return {
+            content: [{ type: 'text', text: 'THEDESIGNAGENT_API_KEY is not set.' }],
+            isError: true,
+        };
+    }
+    log('info', 'pipeline_call', `tool=visual project_id=${args.project_id ?? 'none'} task_len=${args.task.length} render_url=${args.render_url ?? 'none'}`);
+    const capture = await tryCaptureScreenshot(args.render_url, args.auth_seed);
+    const { screenshot } = capture;
+    try {
+        const response = await fetch(`${API_BASE}/visual`, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                task: args.task,
+                artifact: args.artifact,
+                project_id: args.project_id,
+                repo_hash: args.repo_hash,
+                ...(screenshot && { screenshot }),
+                ...(args.render_url && { render_url: args.render_url }),
+            }),
+        });
+        if (response.ok) {
+            const result = await response.json();
+            log('info', 'pipeline_ok', `visual_score=${result.visual_score} auth_required=${capture.authRequired ?? false}`);
+            const footer = buildVisualFooter(args.render_url, capture);
+            // When auth is required, the eval ran on a login page — its findings are
+            // misleading and should not influence the agent. Lead with the action
+            // and skip the findings entirely.
+            if (capture.authRequired) {
+                return { content: [{ type: 'text', text: footer }] };
+            }
+            const evalText = formatVisualEval(result);
+            return { content: [{ type: 'text', text: footer ? `${evalText}\n\n${footer}` : evalText }] };
+        }
+        const err = await response.json();
+        if (response.status === 401 || response.status === 403) {
+            return {
+                content: [{ type: 'text', text: `Authentication failed (${response.status}): ${err.message}\nCheck your THEDESIGNAGENT_API_KEY.` }],
+                isError: true,
+            };
+        }
+        if (response.status === 429) {
+            return {
+                content: [{ type: 'text', text: `Rate limit reached: ${err.message}` }],
+                isError: true,
+            };
+        }
+        log('warn', 'pipeline_server_error', `status=${response.status} error=${err.error} detail=${err.detail ?? 'none'}`);
+        const detailLine = err.detail ? `\nDetail: ${err.detail}` : '';
+        return {
+            content: [{ type: 'text', text: `Pipeline error (${response.status}): ${err.message}${detailLine}` }],
+            isError: true,
+        };
+    }
+    catch (networkErr) {
+        const msg = networkErr instanceof Error ? networkErr.message : String(networkErr);
+        log('warn', 'pipeline_network_error', msg);
+        return {
+            content: [{ type: 'text', text: `Network error reaching pipeline: ${msg}` }],
+            isError: true,
+        };
+    }
+}
+async function handleDiscoverCall(args) {
+    if (!API_KEY) {
+        return {
+            content: [{ type: 'text', text: 'THEDESIGNAGENT_API_KEY is not set.' }],
+            isError: true,
+        };
+    }
+    log('info', 'pipeline_call', `tool=discover project_id=${args.project_id ?? 'none'} task_len=${args.task.length}`);
+    try {
+        const response = await fetch(`${API_BASE}/discovery`, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                task: args.task,
+                project_id: args.project_id,
+                repo_hash: args.repo_hash,
+                codebaseContext: args.codebase_context,
+                schemaHash: args.schema_hash,
+                ...(args.project_model && { projectModel: args.project_model }),
+                ...(args.skills?.length && { skills: args.skills }),
+            }),
+        });
+        if (response.ok) {
+            const result = await response.json();
+            log('info', 'pipeline_ok', `status=${result.status} project_id=${result.project_id}`);
+            return { content: [{ type: 'text', text: formatDiscoveryResult(result) }] };
+        }
+        const err = await response.json();
+        if (response.status === 401 || response.status === 403) {
+            return {
+                content: [{ type: 'text', text: `Authentication failed (${response.status}): ${err.message}\nCheck your THEDESIGNAGENT_API_KEY.` }],
+                isError: true,
+            };
+        }
+        if (response.status === 429) {
+            return {
+                content: [{ type: 'text', text: `Rate limit reached: ${err.message}` }],
+                isError: true,
+            };
+        }
+        log('warn', 'pipeline_server_error', `status=${response.status} error=${err.error} detail=${err.detail ?? 'none'}`);
+        const detailLine = err.detail ? `\nDetail: ${err.detail}` : '';
+        return {
+            content: [{ type: 'text', text: `Pipeline error (${response.status}): ${err.message}${detailLine}` }],
+            isError: true,
+        };
+    }
+    catch (networkErr) {
+        const msg = networkErr instanceof Error ? networkErr.message : String(networkErr);
+        log('warn', 'pipeline_network_error', msg);
+        return {
+            content: [{ type: 'text', text: `Network error reaching pipeline: ${msg}` }],
+            isError: true,
+        };
+    }
+}
+// ---- MCP server -----------------------------------------------------------
+const evalInputSchema = {
+    task: z.string().describe("Describe the workflow or screen you're building"),
+    artifact: z.string().describe('The UI description or component code to evaluate'),
+    project_id: z.string().optional().describe('project_id from .thedesignagent file in project root'),
+    repo_hash: z.string().optional().describe('SHA256 of git remote origin URL (fallback if no .thedesignagent)'),
+    codebase_context: z.string().optional().describe('Optional surrounding code context'),
+};
+const server = new McpServer({ name: 'TheDesignAgent', version: '0.2.0' });
+server.registerTool('discover', {
+    description: `Get a build brief calibrated to your project, persona, and the specific screen you're building.
+
+Call this BEFORE building any screen. TheDesignAgent:
+- Resolves the active Job-to-be-Done for the task
+- Retrieves relevant heuristics, cognitive guidance, and patterns from the corpus
+- Returns a focused build brief (~600 tokens) to inject into your build context
+
+On first call for a new project: returns a needs_setup status with an extraction task — scan your repo and resubmit with project_model populated.
+On subsequent calls: returns brief immediately (context is stored).
+
+Use project_id from .thedesignagent if available; otherwise pass repo_hash (SHA256 of git remote URL).`,
+    inputSchema: {
+        task: z.string().describe("Describe the screen you're about to build"),
+        project_id: z.string().optional().describe('project_id from .thedesignagent file'),
+        repo_hash: z.string().optional().describe('SHA256 of git remote origin URL'),
+        codebase_context: z.string().optional().describe('Surrounding code snippet for context'),
+        schema_hash: z.string().optional().describe('SHA256 of schema/type files — triggers model refresh if stale'),
+        project_model: z.record(z.unknown()).optional().describe('Project model (required on first call or after model_stale)'),
+        skills: z.array(z.string()).optional().describe('Per-call skill selection (overrides project defaults)'),
+    },
+}, async (args) => handleDiscoverCall(args));
+server.registerTool('ux', {
+    description: `Evaluate a built UI artifact for JTBD fit, heuristic compliance, cognitive load, and pattern conformance.
+
+Call this AFTER building a screen. TheDesignAgent scores:
+- Heuristics: violations against Nielsen's heuristics + project-specific anti-patterns
+- Cognitive: load profile against the stored persona
+- Patterns: conformance to established project pattern decisions
+- JTBD fit: does the artifact serve the resolved job?
+
+Returns ux_score (0–10) + findings + prioritised recommendations.
+
+Stores new anti-patterns to project context — future builds benefit automatically.`,
+    inputSchema: {
+        ...evalInputSchema,
+        stages: z.array(z.enum(['heuristics', 'cognitive', 'patterns', 'jtbd-fit'])).optional()
+            .describe('Run only named stages (omit to run all)'),
+    },
+}, async (args) => handleUxCall(args));
+server.registerTool('visual', {
+    description: `Evaluate a built UI artifact for visual design quality — brand compliance, visual cognitive load, and aesthetic quality.
+
+Call for visual design review after building. TheDesignAgent scores across three tracks:
+- Brand: color and token compliance against project DESIGN.md
+- Visual cognitive: perceptual hierarchy, focal points, visual complexity
+- Aesthetic: spacing system, type scale, color harmony
+
+If render_url is provided, the MCP server takes a real screenshot via headless Chrome and the pipeline runs Vision-based analysis. Otherwise it falls back to text analysis of the artifact code.
+
+AUTH-GATED PAGES: If the page is behind login, this tool will detect the redirect and return an auth-required response with a one-line command for the user to run (\`thedesignagent-auth capture <origin>\`). When you receive this response: STOP, surface that exact command to the user, and ask them to retry once they've run it. DO NOT investigate the app's auth scheme. DO NOT attempt to populate auth_seed by grepping for tokens or localStorage keys. The capture command handles all of that automatically; trying to construct auth_seed yourself wastes the user's time and usually doesn't work.
+
+Screenshots are saved to ~/.thedesignagent/screenshots/ (24h TTL) so you can open them to see exactly what was evaluated.
+
+Returns visual_score (0–10) + findings + prioritised recommendations.`,
+    inputSchema: {
+        ...evalInputSchema,
+        render_url: z.string().optional().describe('Optional URL to screenshot (e.g. http://localhost:3000/checkout). If provided, evaluation uses Claude Vision on the rendered output instead of inferring from code.'),
+        auth_seed: z.object({
+            cookies: z.array(z.object({
+                name: z.string(),
+                value: z.string(),
+                domain: z.string().optional(),
+                path: z.string().optional(),
+                httpOnly: z.boolean().optional(),
+                secure: z.boolean().optional(),
+                sameSite: z.enum(['Strict', 'Lax', 'None']).optional(),
+            })).optional(),
+            localStorage: z.record(z.string()).optional(),
+            sessionStorage: z.record(z.string()).optional(),
+        }).optional().describe('ADVANCED ESCAPE HATCH for headless/CI use only. For interactive use, do NOT populate this — instead let the tool detect auth redirects and surface the thedesignagent-auth capture command for the user to run. Manually constructing auth_seed almost always fails because production auth uses HttpOnly cookies invisible to your code search.'),
+    },
+}, async (args) => handleVisualCall(args));
+const transport = new StdioServerTransport();
+await server.connect(transport);
+log('info', 'server_start', `pipeline=${API_BASE} fallback=${ANTHROPIC_API_KEY ? 'enabled' : 'disabled (set ANTHROPIC_API_KEY to enable)'}`);

package/dist/screenshot.d.ts

@@ -0,0 +1,26 @@
+export declare function findChromeExecutable(): string | null;
+export interface AuthSeedCookie {
+    name: string;
+    value: string;
+    domain?: string;
+    path?: string;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+}
+export interface AuthSeed {
+    cookies?: AuthSeedCookie[];
+    localStorage?: Record<string, string>;
+    sessionStorage?: Record<string, string>;
+}
+export interface ScreenshotResult {
+    base64: string;
+    localPath: string;
+    width: number;
+    height: number;
+    bytes: number;
+    authRequired: boolean;
+    finalUrl: string;
+}
+export declare function isLoginUrl(urlStr: string): boolean;
+export declare function captureScreenshot(url: string, authSeed?: AuthSeed): Promise<ScreenshotResult>;

package/dist/screenshot.js

@@ -0,0 +1,167 @@
+import { existsSync, mkdirSync, readdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+const SCREENSHOTS_DIR = join(homedir(), '.thedesignagent', 'screenshots');
+const TTL_MS = 24 * 60 * 60 * 1000;
+const MAC_PATHS = [
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    '/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary',
+    '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+    '/Applications/Arc.app/Contents/MacOS/Arc',
+    '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
+];
+const LINUX_BINS = ['google-chrome', 'google-chrome-stable', 'chromium-browser', 'chromium', 'microsoft-edge', 'brave-browser'];
+const WIN_PATHS = [
+    'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+    'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+    'C:\\Program Files\\Microsoft\\Edge\\Application\\msedge.exe',
+];
+export function findChromeExecutable() {
+    if (process.env.CHROME_PATH && existsSync(process.env.CHROME_PATH)) {
+        return process.env.CHROME_PATH;
+    }
+    if (process.platform === 'darwin') {
+        for (const p of MAC_PATHS)
+            if (existsSync(p))
+                return p;
+    }
+    else if (process.platform === 'linux') {
+        for (const bin of LINUX_BINS) {
+            try {
+                const path = execSync(`which ${bin}`, { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+                if (path && existsSync(path))
+                    return path;
+            }
+            catch { /* not installed */ }
+        }
+    }
+    else if (process.platform === 'win32') {
+        for (const p of WIN_PATHS)
+            if (existsSync(p))
+                return p;
+    }
+    return null;
+}
+function ensureDir() {
+    mkdirSync(SCREENSHOTS_DIR, { recursive: true });
+}
+function cleanOldScreenshots() {
+    if (!existsSync(SCREENSHOTS_DIR))
+        return;
+    const cutoff = Date.now() - TTL_MS;
+    for (const f of readdirSync(SCREENSHOTS_DIR)) {
+        const p = join(SCREENSHOTS_DIR, f);
+        try {
+            if (statSync(p).mtimeMs < cutoff)
+                unlinkSync(p);
+        }
+        catch { /* ignore */ }
+    }
+}
+function safeFilenameSlug(url) {
+    return url.replace(/^https?:\/\//, '').replace(/[^a-z0-9]/gi, '-').slice(0, 60);
+}
+const LOGIN_URL_PATTERNS = [
+    /\/login(\/|$|\?)/i,
+    /\/sign-?in(\/|$|\?)/i,
+    /\/auth(\/|$|\?)/i,
+    /\/sso(\/|$|\?)/i,
+    /\/sessions\/new(\/|$|\?)/i,
+    /\/accounts\/login(\/|$|\?)/i,
+];
+const LOGIN_TITLE_PATTERNS = [
+    /sign\s*in/i,
+    /log\s*in/i,
+    /\blogin\b/i,
+];
+export function isLoginUrl(urlStr) {
+    try {
+        const path = new URL(urlStr).pathname;
+        return LOGIN_URL_PATTERNS.some(p => p.test(path));
+    }
+    catch {
+        return false;
+    }
+}
+function detectAuthRequired(requestedUrl, finalUrl, title) {
+    // If the user explicitly asked for a login URL, they meant to evaluate it. Don't flag.
+    if (isLoginUrl(requestedUrl))
+        return false;
+    return isLoginUrl(finalUrl) || LOGIN_TITLE_PATTERNS.some(p => p.test(title));
+}
+export async function captureScreenshot(url, authSeed) {
+    ensureDir();
+    cleanOldScreenshots();
+    const chromePath = findChromeExecutable();
+    if (!chromePath) {
+        throw new Error('Chrome/Chromium not found. Install Google Chrome (or Edge/Brave/Chromium), or set CHROME_PATH env var to your browser binary.');
+    }
+    // Lazy import so the MCP server still starts if puppeteer-core isn't installed.
+    const puppeteer = (await import('puppeteer-core')).default;
+    const browser = await puppeteer.launch({
+        executablePath: chromePath,
+        headless: true,
+        args: ['--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage'],
+    });
+    try {
+        const page = await browser.newPage();
+        await page.setViewport({ width: 1440, height: 900, deviceScaleFactor: 1 });
+        if (authSeed) {
+            await applyAuthSeed(page, url, authSeed);
+        }
+        await page.goto(url, { waitUntil: 'networkidle0', timeout: 30000 });
+        // Brief settle for hydration / animations
+        await new Promise(r => setTimeout(r, 500));
+        const finalUrl = page.url();
+        const title = await page.title();
+        const authRequired = detectAuthRequired(url, finalUrl, title);
+        const buffer = Buffer.from(await page.screenshot({
+            type: 'jpeg',
+            quality: 88,
+            fullPage: true,
+        }));
+        const ts = new Date().toISOString().replaceAll(':', '-').replaceAll('.', '-');
+        const slug = safeFilenameSlug(url);
+        const filename = `${ts}__${slug}.jpg`;
+        const localPath = join(SCREENSHOTS_DIR, filename);
+        writeFileSync(localPath, buffer);
+        return {
+            base64: buffer.toString('base64'),
+            localPath,
+            width: 1440,
+            height: 900,
+            bytes: buffer.length,
+            authRequired,
+            finalUrl,
+        };
+    }
+    finally {
+        await browser.close();
+    }
+}
+async function applyAuthSeed(page, url, seed) {
+    const { hostname } = new URL(url);
+    if (seed.cookies?.length) {
+        const cookies = seed.cookies.map(c => ({
+            ...c,
+            // Default cookies to the target hostname if domain not provided.
+            domain: c.domain ?? hostname,
+        }));
+        await page.browserContext().setCookie(...cookies);
+    }
+    if (seed.localStorage || seed.sessionStorage) {
+        const ls = seed.localStorage ?? {};
+        const ss = seed.sessionStorage ?? {};
+        await page.evaluateOnNewDocument((lsEntries, ssEntries) => {
+            try {
+                for (const [k, v] of lsEntries)
+                    localStorage.setItem(k, v);
+                for (const [k, v] of ssEntries)
+                    sessionStorage.setItem(k, v);
+            }
+            catch { /* storage unavailable on some origins; ignore */ }
+        }, Object.entries(ls), Object.entries(ss));
+    }
+}

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@thedesignagent/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "MCP server for TheDesignAgent — UX and visual judgment layer for agent-generated UI",
+  "type": "module",
+  "homepage": "https://thedesignagent.ai",
+  "bin": {
+    "thedesignagent-mcp": "./dist/index.js",
+    "thedesignagent-auth": "./dist/auth-capture.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.36.0",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "puppeteer-core": "^23.11.1",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.