@thedesignagent/mcp 0.2.5 → 0.4.0

package/dist/credentials.d.ts

@@ -0,0 +1,8 @@
+export declare const CREDENTIALS_PATH: string;
+export declare function looksLikeApiKey(key: string): boolean;
+export declare function loadApiKey(): {
+    key?: string;
+    source: 'env' | 'file' | 'none';
+};
+export declare function saveApiKey(key: string): string;
+export declare const MISSING_KEY_HELP: string;

package/dist/credentials.js

@@ -0,0 +1,44 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+// One key file for every client: MCP hosts with no standard way to prompt for
+// a key (Agent Plugins, Cursor, Copilot) and the CLI both read it. The env var
+// still wins, so CI and existing MCP configs behave as before.
+export const CREDENTIALS_PATH = join(homedir(), '.thedesignagent', 'credentials');
+export function looksLikeApiKey(key) {
+    return /^tda_[A-Za-z0-9_-]{8,}$/.test(key);
+}
+export function loadApiKey() {
+    const fromEnv = process.env.THEDESIGNAGENT_API_KEY?.trim();
+    if (fromEnv)
+        return { key: fromEnv, source: 'env' };
+    try {
+        if (!existsSync(CREDENTIALS_PATH))
+            return { source: 'none' };
+        const parsed = JSON.parse(readFileSync(CREDENTIALS_PATH, 'utf-8'));
+        if (typeof parsed.api_key === 'string' && parsed.api_key.trim()) {
+            return { key: parsed.api_key.trim(), source: 'file' };
+        }
+    }
+    catch {
+        // Unreadable or malformed: treat as missing; `login` rewrites it.
+    }
+    return { source: 'none' };
+}
+export function saveApiKey(key) {
+    const dir = dirname(CREDENTIALS_PATH);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    // Write a fresh 0600 file and rename it over the old one, so the key is
+    // never briefly readable through an existing file's looser mode.
+    const tmp = `${CREDENTIALS_PATH}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify({ api_key: key }, null, 2) + '\n', { mode: 0o600 });
+    chmodSync(tmp, 0o600);
+    renameSync(tmp, CREDENTIALS_PATH);
+    return CREDENTIALS_PATH;
+}
+export const MISSING_KEY_HELP = [
+    'No TheDesignAgent API key found.',
+    'Get one at https://thedesignagent.ai/dashboard/api-keys, then either:',
+    '  - run: npx -y --package=@thedesignagent/mcp thedesignagent login',
+    '  - or set the THEDESIGNAGENT_API_KEY environment variable.',
+].join('\n');

package/dist/index.js

@@ -24,10 +24,14 @@ 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 { existsSync } from 'node:fs';
 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;
+import { loadApiKey, MISSING_KEY_HELP } from './credentials.js';
+// Read per call: a key saved with `thedesignagent login` after the server
+// started still takes effect without a restart.
+const apiKey = () => loadApiKey().key;
 const API_BASE = process.env.THEDESIGNAGENT_API_BASE ?? 'https://bxqifcmkydlsgwgcpqda.supabase.co/functions/v1';
 // Discover/Ux route through the hosted gateway so mcp_call_logs telemetry
 // captures local-stdio calls too. Visual stays direct because it needs local
@@ -40,7 +44,7 @@ async function callGatewayTool(name, args) {
         response = await fetch(`${GATEWAY_BASE}/mcp`, {
             method: 'POST',
             headers: {
-                Authorization: `Bearer ${API_KEY}`,
+                Authorization: `Bearer ${apiKey()}`,
                 'Content-Type': 'application/json',
                 'Accept': 'application/json',
             },
@@ -111,13 +115,24 @@ async function runFallback(task, artifact, 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.`;
+    // Opus 5.5 always thinks: thinking shares max_tokens, and the reply is not
+    // content[0]. `fallbacks` (not yet in the SDK types) re-runs a safety
+    // classifier decline on Anthropic's recommended model within the same call.
     const response = await client.messages.create({
-        model: 'claude-opus-4-7',
-        max_tokens: 4000,
+        model: 'claude-opus-5-5',
+        max_tokens: 16000,
+        output_config: { effort: 'medium' },
         system: FALLBACK_SYSTEM_PROMPT,
         messages: [{ role: 'user', content: userMessage }],
-    });
-    const text = response.content[0].type === 'text' ? response.content[0].text : '';
+        fallbacks: 'default',
+    }, { headers: { 'anthropic-beta': 'server-side-fallback-2026-07-01' } });
+    if (response.stop_reason === 'refusal') {
+        throw new Error('Fallback Claude declined the request');
+    }
+    const text = response.content
+        .filter((b) => b.type === 'text')
+        .map((b) => b.text)
+        .join('');
     const jsonStr = text.replace(/^```(?:json)?\n?/m, '').replace(/\n?```$/m, '').trim();
     try {
         const parsed = JSON.parse(jsonStr);
@@ -218,43 +233,43 @@ async function tryCaptureScreenshot(url, authSeed) {
         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>';
-    }
+// The login recipe a repo can provide (written by the plugin's setup flow).
+// It prints either a URL that logs in when opened or an AuthSeed JSON.
+const LOGIN_RECIPE = '.thedesignagent-login.mjs';
+// Run the auth CLI that ships alongside this server, so its version always matches.
+// Pass the page being reviewed, not just the origin: many apps 404 or
+// redirect at the root, and the session is saved per origin either way.
+function authCmd(sub, pageUrl) {
+    const authCapturePath = join(dirname(process.argv[1]), 'auth-capture.js');
+    return `node "${authCapturePath}" ${sub} ${pageUrl}`;
 }
 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 origin = (() => { try {
+        return new URL(renderUrl).origin;
+    }
+    catch {
+        return renderUrl;
+    } })();
+    const stateLine = authSeedSource === 'stored'
+        ? `A saved session for ${origin} existed but has expired.`
+        : `No saved session for ${origin} yet.`;
+    const hasRecipe = existsSync(join(process.cwd(), LOGIN_RECIPE));
     const lines = [
         `---`,
-        `🛑 ▌TheDesignAgent▐ — ACTION REQUIRED: page is behind authentication`,
+        `🛑 ▌TheDesignAgent▐ — page is behind login. No review ran and no credits were charged.`,
         ``,
-        `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)}`,
+        stateLine,
         ``,
         `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 (hasRecipe) {
+        lines.push(`1. This repo has a login recipe. Run it (from the repo root):`, `     node ${LOGIN_RECIPE} | ${authCmd('login', renderUrl)}`, `2. When it prints TDA_AUTH_SAVED, retry this Visual call with the same render_url.`, `3. If it prints TDA_AUTH_FAILED, fall back to the manual capture below.`, ``, `Manual capture (fallback):`);
+    }
+    lines.push(`${hasRecipe ? '' : '1. '}Run this yourself, in the background (it opens a browser window for the user):`, `     ${authCmd('capture', renderUrl)}`, `   Tell the user: "A browser window opened at ${origin}. Log in there; it saves and closes by itself."`, `   Wait for the command to finish. It prints TDA_AUTH_SAVED when done (or TDA_AUTH_FAILED with a reason; it gives up after 10 minutes).`, `${hasRecipe ? '' : '2. '}Then retry this Visual call once with the same render_url. The session is applied automatically.`, ``, `WHAT NOT TO DO:`, `- Do not search the app's source for auth keys, JWT names, or localStorage tokens.`, `- Do not construct auth_seed by hand. HttpOnly cookies are invisible to code search, so it almost always fails.`);
+    if (!hasRecipe) {
+        lines.push(``, `To make this automatic next time, the plugin's setup flow can write a ${LOGIN_RECIPE} for this repo.`);
+    }
     if (finalUrl) {
         lines.push(``, `(Diagnostics: redirected to ${finalUrl})`);
     }
@@ -329,9 +344,9 @@ function formatDiscoveryResult(result) {
 }
 // ---- Tool handlers --------------------------------------------------------
 async function handleUxCall(args) {
-    if (!API_KEY) {
+    if (!apiKey()) {
         return {
-            content: [{ type: 'text', text: 'THEDESIGNAGENT_API_KEY is not set. Add it to your MCP server config.' }],
+            content: [{ type: 'text', text: MISSING_KEY_HELP }],
             isError: true,
         };
     }
@@ -409,19 +424,25 @@ async function handleUxCall(args) {
     }
 }
 async function handleVisualCall(args) {
-    if (!API_KEY) {
+    if (!apiKey()) {
         return {
-            content: [{ type: 'text', text: 'THEDESIGNAGENT_API_KEY is not set.' }],
+            content: [{ type: 'text', text: MISSING_KEY_HELP }],
             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;
+    // Landed on a login page: stop before the pipeline. Evaluating the login
+    // form would cost credits and produce findings the agent must discard.
+    if (capture.authRequired && args.render_url) {
+        log('info', 'visual_auth_required', `render_url=${args.render_url} final_url=${capture.finalUrl ?? 'unknown'}`);
+        return { content: [{ type: 'text', text: buildAuthRequiredFooter(args.render_url, capture) }] };
+    }
     try {
         const response = await fetch(`${API_BASE}/visual`, {
             method: 'POST',
-            headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
+            headers: { Authorization: `Bearer ${apiKey()}`, 'Content-Type': 'application/json' },
             body: JSON.stringify({
                 task: args.task,
                 artifact: args.artifact,
@@ -447,7 +468,7 @@ async function handleVisualCall(args) {
         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.` }],
+                content: [{ type: 'text', text: `Authentication failed (${response.status}): ${err.message}\nCheck your API key (THEDESIGNAGENT_API_KEY or "thedesignagent login").` }],
                 isError: true,
             };
         }
@@ -474,9 +495,9 @@ async function handleVisualCall(args) {
     }
 }
 async function handleDiscoverCall(args) {
-    if (!API_KEY) {
+    if (!apiKey()) {
         return {
-            content: [{ type: 'text', text: 'THEDESIGNAGENT_API_KEY is not set.' }],
+            content: [{ type: 'text', text: MISSING_KEY_HELP }],
             isError: true,
         };
     }
@@ -516,7 +537,7 @@ const evalInputSchema = {
     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.5' });
+const server = new McpServer({ name: 'TheDesignAgent', version: '0.4.0' });
 server.registerTool('Discover', {
     description: `Get a build brief calibrated to your project, persona, and the specific screen you're building.
 
@@ -567,7 +588,7 @@ Call for visual design review after building. TheDesignAgent scores across three
 
 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.
+AUTH-GATED PAGES: If the page is behind login, this tool stops before evaluating (no credits charged) and returns the exact commands to save a session: a repo login recipe (.thedesignagent-login.mjs) when one exists, otherwise a browser capture you run in the background while the user logs in (it saves and closes by itself). Follow those instructions, then retry once. DO NOT investigate the app's auth scheme or populate auth_seed by grepping for tokens or localStorage keys; that 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.
 

package/dist/screenshot.d.ts

@@ -7,6 +7,7 @@ export interface AuthSeedCookie {
     httpOnly?: boolean;
     secure?: boolean;
     sameSite?: 'Strict' | 'Lax' | 'None';
+    expires?: number;
 }
 export interface AuthSeed {
     cookies?: AuthSeedCookie[];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thedesignagent/mcp",
-  "version": "0.2.5",
-  "description": "MCP server for TheDesignAgent — UX and visual judgment layer for agent-generated UI",
+  "version": "0.4.0",
+  "description": "MCP server and CLI for TheDesignAgent \u2014 UX and visual judgment layer for agent-generated UI",
   "license": "MIT",
   "type": "module",
   "homepage": "https://thedesignagent.ai",
@@ -14,11 +14,14 @@
     "design-system",
     "claude-code",
     "codex",
-    "ai-agents"
+    "ai-agents",
+    "cli",
+    "ci"
   ],
   "bin": {
     "thedesignagent-mcp": "dist/index.js",
-    "thedesignagent-auth": "dist/auth-capture.js"
+    "thedesignagent-auth": "dist/auth-capture.js",
+    "thedesignagent": "dist/cli.js"
   },
   "files": [
     "dist"
@@ -35,7 +38,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.36.0",
+    "@anthropic-ai/sdk": "^0.92.0",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "puppeteer-core": "^23.11.1",
     "zod": "^3.22.0"