@thedesignagent/mcp 0.2.0 → 0.2.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TheDesignAgent
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+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.

package/README.md

@@ -0,0 +1,141 @@
+# @thedesignagent/mcp
+
+MCP server for [TheDesignAgent](https://thedesignagent.ai): UX and visual judgment for UI that coding agents build.
+
+Your agent gets a build brief before it builds a screen, and a scored review after: does the screen serve the user's job, does it follow UX heuristics, does it match your design system. Reviews use a real screenshot when the page is running.
+
+Works with any MCP client: Claude Code, Codex, Cursor, Grok Build, Claude Desktop and others.
+
+## Tools
+
+| Tool | When | What it returns |
+| --- | --- | --- |
+| `Discover` | Before building a screen | A ~600-token build brief: the user's job, heuristics to apply, patterns, design tokens |
+| `Ux` | After building | 0–10 score for heuristics, cognitive load, pattern conformance and job fit, with findings and fixes |
+| `Visual` | After building | 0–10 score for brand compliance, visual hierarchy and aesthetics, from a screenshot when you pass `render_url` |
+
+Project context is stored server-side and improves with every call: anti-patterns found in one review shape the next brief.
+
+## Hosted or local?
+
+TheDesignAgent runs in two places. The same API key works in both.
+
+| | Hosted: `https://www.thedesignagent.ai/mcp` | Local: this package |
+| --- | --- | --- |
+| Tools | `Discover`, `Ux` | `Discover`, `Ux`, `Visual` |
+| Install | Nothing to install | Node.js 20+, runs through `npx` |
+| Screenshots | No: it can't reach `localhost` | Yes, with your local browser |
+
+Use the hosted server if you only need briefs and UX reviews. Use this package when you want `Visual` reviews of pages running on your machine.
+
+## Setup
+
+Get an API key (it starts with `tda_`) at [thedesignagent.ai/dashboard/api-keys](https://thedesignagent.ai/dashboard/api-keys).
+
+### Claude Code (recommended: the plugin)
+
+The plugin includes this server, plus skills that teach the agent the brief → build → review loop and `/thedesignagent:brief` and `/thedesignagent:review` commands:
+
+```
+/plugin marketplace add CMBurnett/the-design-agent-plugin
+/plugin install thedesignagent@thedesignagent
+```
+
+Or add the server on its own:
+
+```
+claude mcp add thedesignagent -e THEDESIGNAGENT_API_KEY=tda_... -- npx -y --package=@thedesignagent/mcp thedesignagent-mcp
+```
+
+Or the hosted server, with no install:
+
+```
+claude mcp add --transport http thedesignagent https://www.thedesignagent.ai/mcp --header "Authorization: Bearer tda_..."
+```
+
+### Codex
+
+In `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.thedesignagent]
+command = "npx"
+args = ["-y", "--package=@thedesignagent/mcp", "thedesignagent-mcp"]
+env = { THEDESIGNAGENT_API_KEY = "tda_..." }
+```
+
+### Cursor, Claude Desktop and other JSON-configured clients
+
+Local:
+
+```json
+{
+  "mcpServers": {
+    "thedesignagent": {
+      "command": "npx",
+      "args": ["-y", "--package=@thedesignagent/mcp", "thedesignagent-mcp"],
+      "env": { "THEDESIGNAGENT_API_KEY": "tda_..." }
+    }
+  }
+}
+```
+
+Hosted:
+
+```json
+{
+  "mcpServers": {
+    "thedesignagent": {
+      "url": "https://www.thedesignagent.ai/mcp",
+      "headers": { "Authorization": "Bearer tda_..." }
+    }
+  }
+}
+```
+
+The package has two commands, so pass `--package` and name `thedesignagent-mcp` as shown. A bare `npx @thedesignagent/mcp` won't start.
+
+## How agents use it
+
+1. **Identify the project.** Pass `project_id` from a `.thedesignagent` file in the repo root, or `repo_hash` (SHA-256 of the git remote URL) if there isn't one yet.
+2. **Call `Discover`** with the screen you're about to build. On a project's first call it returns `needs_setup` with an extraction task: the agent scans the repo, builds a project model and calls again. After that, briefs come back immediately.
+3. **Build** following the brief.
+4. **Call `Ux` and `Visual`** with the built code as `artifact`. Pass `render_url` (for example `http://localhost:3000/checkout`) to `Visual` for a screenshot-based review.
+5. **Fix** critical and high findings, then re-check once.
+
+After the first successful `Discover`, write `{ "project_id": "<id>" }` to `.thedesignagent` and commit it, so every agent on the repo shares the same project context.
+
+## Screenshots
+
+`Visual` screenshots `render_url` with your local Chrome, Edge, Brave or Chromium. If it can't find one, set `CHROME_PATH` to the browser binary.
+
+Screenshots are saved to `~/.thedesignagent/screenshots/` for 24 hours, so you can see exactly what was reviewed.
+
+### Pages behind login
+
+Capture a logged-in session once per app:
+
+```
+npx -y --package=@thedesignagent/mcp thedesignagent-auth capture http://localhost:3000
+```
+
+A browser opens; log in, then press Enter (or close the browser). The session is saved under `~/.thedesignagent/auth/` and reused for that origin. When `Visual` hits a login redirect, it tells the agent to ask you to run this command.
+
+## Environment variables
+
+| Variable | Required | Purpose |
+| --- | --- | --- |
+| `THEDESIGNAGENT_API_KEY` | Yes | Your `tda_` API key |
+| `CHROME_PATH` | No | Browser binary for screenshots, if it isn't found automatically |
+| `ANTHROPIC_API_KEY` | No | Enables a fallback review through Claude when TheDesignAgent's API is unreachable |
+
+## Errors
+
+- An authentication error means the API key is missing, wrong or revoked.
+- A rate-limit message means wait briefly and retry.
+- Account errors are returned as tool errors; the message says what to do.
+
+## Links
+
+- Website: [thedesignagent.ai](https://thedesignagent.ai)
+- Claude Code plugin: [CMBurnett/the-design-agent-plugin](https://github.com/CMBurnett/the-design-agent-plugin)

package/dist/index.d.ts

@@ -1,20 +1,23 @@
 #!/usr/bin/env node
 /**
- * TheDesignAgent MCP Server
- * Exposes three tools — discover, ux, visual — discoverable by Claude Code, Cursor, etc.
+ * TheDesignAgent MCP Server — local stdio variant
  *
- * 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
- *       }
- *     }
- *   }
- * }
+ * Most users do NOT need this. The hosted MCP at https://www.thedesignagent.ai/mcp
+ * covers `discover` and `ux`. Install it with:
+ *
+ *   claude mcp add --transport http --scope user TheDesignAgent \
+ *     https://www.thedesignagent.ai/mcp \
+ *     --header "Authorization: Bearer tda_..."
+ *
+ * This local server is only needed for the `visual` tool, which screenshots
+ * http://localhost (unreachable from the hosted gateway). Install it from npm
+ * and register alongside the hosted MCP. The package has two bins, so name
+ * the command explicitly:
+ *
+ *   claude mcp add TheDesignAgent-local --scope user \
+ *     --env THEDESIGNAGENT_API_KEY=tda_... \
+ *     -- npx -y --package=@thedesignagent/mcp thedesignagent-mcp
+ *
+ * Same API key works in both places.
  */
 export {};

package/dist/index.js

@@ -1,21 +1,24 @@
 #!/usr/bin/env node
 /**
- * TheDesignAgent MCP Server
- * Exposes three tools — discover, ux, visual — discoverable by Claude Code, Cursor, etc.
+ * TheDesignAgent MCP Server — local stdio variant
  *
- * 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
- *       }
- *     }
- *   }
- * }
+ * Most users do NOT need this. The hosted MCP at https://www.thedesignagent.ai/mcp
+ * covers `discover` and `ux`. Install it with:
+ *
+ *   claude mcp add --transport http --scope user TheDesignAgent \
+ *     https://www.thedesignagent.ai/mcp \
+ *     --header "Authorization: Bearer tda_..."
+ *
+ * This local server is only needed for the `visual` tool, which screenshots
+ * http://localhost (unreachable from the hosted gateway). Install it from npm
+ * and register alongside the hosted MCP. The package has two bins, so name
+ * the command explicitly:
+ *
+ *   claude mcp add TheDesignAgent-local --scope user \
+ *     --env THEDESIGNAGENT_API_KEY=tda_... \
+ *     -- npx -y --package=@thedesignagent/mcp thedesignagent-mcp
+ *
+ * Same API key works in both places.
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
@@ -26,7 +29,50 @@ 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';
+// Discover/Ux route through the hosted gateway so mcp_call_logs telemetry
+// captures local-stdio calls too. Visual stays direct because it needs local
+// screenshot capability that the gateway can't provide.
+const GATEWAY_BASE = process.env.THEDESIGNAGENT_GATEWAY ?? 'https://www.thedesignagent.ai';
 const ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
+async function callGatewayTool(name, args) {
+    let response;
+    try {
+        response = await fetch(`${GATEWAY_BASE}/mcp`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${API_KEY}`,
+                'Content-Type': 'application/json',
+                'Accept': 'application/json',
+            },
+            body: JSON.stringify({
+                jsonrpc: '2.0',
+                id: Date.now(),
+                method: 'tools/call',
+                params: { name, arguments: args },
+            }),
+        });
+    }
+    catch (e) {
+        return { ok: false, status: 0, message: e instanceof Error ? e.message : String(e) };
+    }
+    if (!response.ok) {
+        return { ok: false, status: response.status, message: `Gateway HTTP ${response.status}` };
+    }
+    let envelope;
+    try {
+        envelope = await response.json();
+    }
+    catch (e) {
+        return { ok: false, status: response.status, message: `Gateway parse error: ${e instanceof Error ? e.message : String(e)}` };
+    }
+    if (envelope.error) {
+        return { ok: false, status: response.status, message: envelope.error.message };
+    }
+    if (!envelope.result) {
+        return { ok: false, status: response.status, message: 'Gateway returned no result' };
+    }
+    return { ok: true, result: envelope.result };
+}
 // ---- Logging --------------------------------------------------------------
 function log(level, step, detail) {
     const ts = new Date().toISOString();
@@ -289,57 +335,38 @@ async function handleUxCall(args) {
             isError: true,
         };
     }
-    log('info', 'pipeline_call', `tool=ux project_id=${args.project_id ?? 'none'} task_len=${args.task.length}`);
+    log('info', 'pipeline_call', `tool=ux project_id=${args.project_id ?? 'none'} task_len=${args.task.length} via=gateway`);
     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,
-            };
+    // Route through hosted gateway so mcp_call_logs telemetry captures this call.
+    const gw = await callGatewayTool('Ux', {
+        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 }),
+    });
+    if (gw.ok) {
+        const status = gw.result._meta?.tda_status;
+        if (!gw.result.isError) {
+            log('info', 'pipeline_ok', `via=gateway status=${status ?? 'healthy'}`);
+            return { content: gw.result.content };
         }
-        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,
-            };
+        // Tool reported an error inside a 200 envelope. Auth + rate-limit are
+        // user-facing — return as-is, no fallback. pipeline_error falls through.
+        if (status === 'auth_failed' || status === 'rate_limited' || status === 'insufficient_credits') {
+            log('warn', 'pipeline_user_error', `status=${status}`);
+            return { content: gw.result.content, isError: true };
         }
-        log('warn', 'pipeline_server_error', `status=${response.status} error=${err.error}`);
+        pipelineStatus = 500;
+        pipelineErrorType = status ?? 'pipeline_error';
+        log('warn', 'pipeline_server_error', `via=gateway status=${status}`);
     }
-    catch (networkErr) {
-        pipelineStatus = 0;
-        pipelineErrorType = 'network_error';
-        log('warn', 'pipeline_network_error', networkErr instanceof Error ? networkErr.message : String(networkErr));
+    else {
+        pipelineStatus = gw.status;
+        pipelineErrorType = gw.status === 0 ? 'network_error' : 'gateway_error';
+        log('warn', 'pipeline_network_error', gw.message);
     }
     // Prompted fallback
     if (!ANTHROPIC_API_KEY) {
@@ -453,54 +480,30 @@ async function handleDiscoverCall(args) {
             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);
+    log('info', 'pipeline_call', `tool=discover project_id=${args.project_id ?? 'none'} task_len=${args.task.length} via=gateway`);
+    // Route through hosted gateway so mcp_call_logs telemetry captures this call.
+    const gw = await callGatewayTool('Discover', {
+        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 (gw.ok) {
+        const status = gw.result._meta?.tda_status ?? 'unknown';
+        log('info', gw.result.isError ? 'pipeline_returned_error' : 'pipeline_ok', `via=gateway status=${status} project_id=${gw.result._meta?.tda_project_id ?? 'none'}`);
         return {
-            content: [{ type: 'text', text: `Network error reaching pipeline: ${msg}` }],
-            isError: true,
+            content: gw.result.content,
+            ...(gw.result.isError && { isError: true }),
         };
     }
+    log('warn', 'pipeline_network_error', gw.message);
+    return {
+        content: [{ type: 'text', text: `Network error reaching pipeline: ${gw.message}` }],
+        isError: true,
+    };
 }
 // ---- MCP server -----------------------------------------------------------
 const evalInputSchema = {
@@ -510,8 +513,8 @@ 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.0' });
-server.registerTool('discover', {
+const server = new McpServer({ name: 'TheDesignAgent', version: '0.2.3' });
+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:
@@ -533,7 +536,7 @@ Use project_id from .thedesignagent if available; otherwise pass repo_hash (SHA2
         skills: z.array(z.string()).optional().describe('Per-call skill selection (overrides project defaults)'),
     },
 }, async (args) => handleDiscoverCall(args));
-server.registerTool('ux', {
+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:
@@ -551,7 +554,7 @@ Stores new anti-patterns to project context — future builds benefit automatica
             .describe('Run only named stages (omit to run all)'),
     },
 }, async (args) => handleUxCall(args));
-server.registerTool('visual', {
+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:

package/package.json

@@ -1,12 +1,24 @@
 {
   "name": "@thedesignagent/mcp",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "description": "MCP server for TheDesignAgent — UX and visual judgment layer for agent-generated UI",
+  "license": "MIT",
   "type": "module",
   "homepage": "https://thedesignagent.ai",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "design",
+    "ux",
+    "ui-review",
+    "design-system",
+    "claude-code",
+    "codex",
+    "ai-agents"
+  ],
   "bin": {
-    "thedesignagent-mcp": "./dist/index.js",
-    "thedesignagent-auth": "./dist/auth-capture.js"
+    "thedesignagent-mcp": "dist/index.js",
+    "thedesignagent-auth": "dist/auth-capture.js"
   },
   "files": [
     "dist"