@thedesignagent/mcp 0.2.0 → 0.2.1

package/README.md

@@ -0,0 +1,109 @@
+# @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.
+
+## Setup
+
+Get an API key at [thedesignagent.ai/dashboard/api-keys](https://thedesignagent.ai/dashboard/api-keys). The free plan includes 100 calls a month.
+
+Requires Node.js 20 or later.
+
+### Claude Code (recommended: the plugin)
+
+The plugin adds skills that teach the agent the brief → build → review loop, plus `/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=sk_... -- npx -y --package=@thedesignagent/mcp thedesignagent-mcp
+```
+
+### Codex
+
+In `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.thedesignagent]
+command = "npx"
+args = ["-y", "--package=@thedesignagent/mcp", "thedesignagent-mcp"]
+env = { THEDESIGNAGENT_API_KEY = "sk_..." }
+```
+
+### Cursor, Claude Desktop and other JSON-configured clients
+
+```json
+{
+  "mcpServers": {
+    "thedesignagent": {
+      "command": "npx",
+      "args": ["-y", "--package=@thedesignagent/mcp", "thedesignagent-mcp"],
+      "env": { "THEDESIGNAGENT_API_KEY": "sk_..." }
+    }
+  }
+}
+```
+
+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 `sk_` 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 |
+
+## Limits and errors
+
+- Each plan has a monthly call limit. When you reach it, calls return a limit message; upgrade at [thedesignagent.ai](https://thedesignagent.ai) or wait for the monthly reset.
+- An authentication error means the API key is missing, wrong or revoked.
+
+## 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.js

@@ -510,7 +510,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.0' });
+const server = new McpServer({ name: 'TheDesignAgent', version: '0.2.1' });
 server.registerTool('discover', {
     description: `Get a build brief calibrated to your project, persona, and the specific screen you're building.
 

package/package.json

@@ -1,9 +1,20 @@
 {
   "name": "@thedesignagent/mcp",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "MCP server for TheDesignAgent — UX and visual judgment layer for agent-generated UI",
   "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"