{"_id":"@cre8tivsystems/interfaceguard-mcp","name":"@cre8tivsystems/interfaceguard-mcp","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@cre8tivsystems/interfaceguard-mcp","version":"0.1.0","description":"MCP server for InterfaceGuard UX Analyzer — capture screenshots and run UX analysis from Claude Code, Cursor, and other AI coding tools","type":"module","main":"dist/index.js","bin":{"ux-analyzer-mcp":"dist/index.js"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/cre8tiv/ux.ai.git","directory":"ux-analyzer-mcp"},"keywords":["mcp","model-context-protocol","ux","claude","accessibility"],"scripts":{"build":"tsc","dev":"tsc --watch","type-check":"tsc --noEmit","lint":"eslint src --ext .ts","lint:fix":"eslint src --ext .ts --fix","format":"prettier --write \"src/**/*.ts\"","format:check":"prettier --check \"src/**/*.ts\"","start":"node dist/index.js","prepack":"npm run build","prepublishOnly":"npm run build"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","axios":"^1.6.0","form-data":"^4.0.0","playwright":"^1.61.1","zod":"^3.23.0"},"devDependencies":{"@types/node":"^18.0.0","@typescript-eslint/eslint-plugin":"^8.46.4","@typescript-eslint/parser":"^8.46.4","eslint":"^9","eslint-config-prettier":"^10.1.8","eslint-plugin-prettier":"^5.5.4","prettier":"^3.1.1","typescript":"^5.0.0"},"engines":{"node":">=18.0.0"},"gitHead":"079318f343963eae3a9eedc01dee0b6ce1bd07d1","types":"./dist/index.d.ts","_id":"@cre8tivsystems/interfaceguard-mcp@0.1.0","bugs":{"url":"https://github.com/cre8tiv/ux.ai/issues"},"homepage":"https://github.com/cre8tiv/ux.ai#readme","_nodeVersion":"22.14.0","_npmVersion":"11.7.0","dist":{"integrity":"sha512-BkgIfCCVmKd7wN0TIUnajDsJELav1MRqU6IgfUQLJ8zeiC4MbTlET/JUXrOmfFIu0vY5wYF5+NlNofMbcaA1pw==","shasum":"0a11ce5cbc717ada2fa255d26a55dee97910799b","tarball":"https://registry.npmjs.org/@cre8tivsystems/interfaceguard-mcp/-/interfaceguard-mcp-0.1.0.tgz","fileCount":31,"unpackedSize":63056,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCXh1QOvdaPp429FCk44aUokqwpImIP7vfYcrLipQvsEwIgUHHNbas0tdGiulfJRH5tDRJjjTbpFaZuRg4tgeFqhKQ="}]},"_npmUser":{"name":"cre8tiv","email":"bmartin@cre8tivsystems.com"},"directories":{},"maintainers":[{"name":"cre8tiv","email":"bmartin@cre8tivsystems.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/interfaceguard-mcp_0.1.0_1784670700960_0.5792850030996914"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-21T21:51:40.805Z","0.1.0":"2026-07-21T21:51:41.110Z","modified":"2026-07-21T21:51:41.479Z"},"maintainers":[{"name":"cre8tiv","email":"bmartin@cre8tivsystems.com"}],"description":"MCP server for InterfaceGuard UX Analyzer — capture screenshots and run UX analysis from Claude Code, Cursor, and other AI coding tools","homepage":"https://github.com/cre8tiv/ux.ai#readme","keywords":["mcp","model-context-protocol","ux","claude","accessibility"],"repository":{"type":"git","url":"git+https://github.com/cre8tiv/ux.ai.git","directory":"ux-analyzer-mcp"},"bugs":{"url":"https://github.com/cre8tiv/ux.ai/issues"},"license":"MIT","readme":"# InterfaceGuard MCP Server\r\n\r\nAn [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that brings InterfaceGuard UX analysis directly into AI coding tools — Claude Code, Cursor, Windsurf, and any other MCP-compatible environment. Capture screenshots with embedded Playwright, submit analysis jobs, and consume prioritized UX recommendations without leaving your editor.\r\n\r\n## Features\r\n\r\n- **Screenshot Capture**: Headless Chromium captures desktop, tablet, and mobile viewports — no external browser server needed\r\n- **Multi-Viewport Analysis**: Responsive UX issues caught at 1440×900, 768×1024, and 390×844 in a single call\r\n- **9 Analysis Types**: Accessibility, usability, consistency, visual hierarchy, color scheme, layout, design system extraction, branding, and expert review\r\n- **Fix Prompts**: AI-generated coding prompts for each issue, ready to paste into a task\r\n- **Issue Tracking**: Mark issues resolved after fixing them\r\n- **Zero Config**: Defaults to the production Cloud Run endpoint — only `UXA_API_KEY` is required\r\n\r\n## MCP Tools\r\n\r\n| Tool | Description |\r\n|---|---|\r\n| `capture_screenshots` | Open a URL in headless Chromium and capture at desktop, tablet, and/or mobile viewports |\r\n| `list_projects` | List InterfaceGuard projects available to the API key |\r\n| `submit_analysis` | Submit captured screenshots for UX analysis; returns a `jobId` |\r\n| `get_job_status` | Check job progress (0–100%) and completion status |\r\n| `get_results` | Fetch the full analysis result: issues, recommendations, and severity summary |\r\n| `enhance_prompt` | Generate an AI-powered coding fix prompt for a specific issue |\r\n| `resolve_issue` | Mark an issue resolved or reopen it |\r\n| `cancel_job` | Cancel a pending or in-progress job |\r\n\r\n## Prerequisites\r\n\r\n- Node.js 18 or higher\r\n- Chromium for Playwright (see Installation)\r\n- An InterfaceGuard API key (generate one in the web app under Settings → API Keys)\r\n\r\n## Installation\r\n\r\nInstall the package globally or use it via `npx`:\r\n\r\n```bash\r\nnpm install -g @cre8tivsystems/interfaceguard-mcp\r\n```\r\n\r\nInstall the Chromium browser for screenshot capture (one-time setup):\r\n\r\n```bash\r\nnpx playwright install chromium\r\n```\r\n\r\n## Configuration\r\n\r\n### Claude Code\r\n\r\n> **⚠️ WARNING:** Never place `UXA_API_KEY` in a **project-scoped** `.claude/settings.json` — that file is typically committed to version control and would expose your API key. Use `~/.claude/settings.json` (user-level, untracked) instead, or inject the key via a secret-management tool (e.g., `op run`, `direnv`, or a CI secret store).\r\n\r\nAdd to `~/.claude/settings.json` (user-level, all projects) or `.claude/settings.json` (project-level — only if the file is in `.gitignore`):\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"ux-analyzer\": {\r\n      \"command\": \"npx\",\r\n      \"args\": [\"-y\", \"@cre8tivsystems/interfaceguard-mcp\"],\r\n      \"env\": {\r\n        \"UXA_API_KEY\": \"your-api-key\"\r\n      }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n### Cursor\r\n\r\nAdd to `~/.cursor/mcp.json`:\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"ux-analyzer\": {\r\n      \"command\": \"npx\",\r\n      \"args\": [\"-y\", \"@cre8tivsystems/interfaceguard-mcp\"],\r\n      \"env\": {\r\n        \"UXA_API_KEY\": \"your-api-key\"\r\n      }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n### Windsurf / other MCP clients\r\n\r\nUse the same JSON block in your client's MCP configuration file. The server communicates over **stdio**, which all MCP clients support.\r\n\r\n## Environment Variables\r\n\r\n| Variable | Required | Default | Description |\r\n|---|---|---|---|\r\n| `UXA_API_KEY` | **Yes** | — | InterfaceGuard API key from the web app |\r\n| `UXA_API_URL` | No | — | Analysis service URL. Optional — defaults to the production endpoint. Set to `http://localhost:8080` to test against a locally running service. |\r\n\r\n## Usage\r\n\r\nOnce configured, Claude Code (and other clients) can invoke the tools directly. The typical workflow:\r\n\r\n```\r\n1. capture_screenshots(url)           → captureId\r\n2. list_projects()                    → pick projectId\r\n3. submit_analysis(captureId, projectId) → jobId\r\n4. get_job_status(jobId)              → poll until \"completed\", \"failed\", or \"cancelled\"\r\n5. get_results(jobId)                 → issues + recommendations\r\n6. enhance_prompt(issue)              → coding fix prompt\r\n7. resolve_issue(jobId, issueId, true)\r\n```\r\n\r\nUse `cancel_job(jobId)` to stop a pending or in-progress job — the status will then return `\"cancelled\"`.\r\n\r\nSee [`SKILL.md`](./SKILL.md) for the detailed agent workflow, analysis type guidance, and example session — this file is intended to be referenced by Claude Code as a skill.\r\n\r\n## Commands\r\n\r\n```bash\r\n# Build TypeScript to dist/\r\nnpm run build\r\n\r\n# Watch mode (rebuild on change)\r\nnpm run dev\r\n\r\n# Type check without emitting\r\nnpm run type-check\r\n\r\n# Run the compiled server directly\r\nnpm start\r\n```\r\n\r\n## Local Development\r\n\r\nTo run the server directly from source without a build step (useful during development):\r\n\r\n```bash\r\nUXA_API_KEY=your-key npx tsx src/index.ts\r\n```\r\n\r\nOr configure your MCP client to use `tsx` instead of the compiled output:\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"ux-analyzer\": {\r\n      \"command\": \"npx\",\r\n      \"args\": [\"tsx\", \"/path/to/ux.ai/ux-analyzer-mcp/src/index.ts\"],\r\n      \"env\": {\r\n        \"UXA_API_KEY\": \"your-api-key\",\r\n        \"UXA_API_URL\": \"http://localhost:8080\"\r\n      }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n## Project Structure\r\n\r\n```\r\nux-analyzer-mcp/\r\n├── src/\r\n│   ├── index.ts              # Entry point — wires server, tools, and stdio transport\r\n│   ├── config.ts             # Reads UXA_API_KEY / UXA_API_URL from environment\r\n│   ├── store.ts              # In-memory capture store (captureId → PNG buffers)\r\n│   ├── api/\r\n│   │   ├── client.ts         # Axios wrapper for the InterfaceGuard REST API\r\n│   │   └── types.ts          # Shared TypeScript types (Issue, Recommendation, etc.)\r\n│   └── tools/\r\n│       ├── capture.ts        # capture_screenshots — Playwright multi-viewport capture\r\n│       ├── projects.ts       # list_projects\r\n│       ├── jobs.ts           # submit_analysis, get_job_status, get_results, cancel_job\r\n│       └── issues.ts         # enhance_prompt, resolve_issue\r\n├── SKILL.md                  # Claude Code skill: agent workflow and examples\r\n├── package.json\r\n└── tsconfig.json\r\n```\r\n\r\n## Publishing\r\n\r\n```bash\r\nnpm run build\r\nnpm publish --access public\r\n```\r\n\r\nThe package is published as the scoped, public package `@cre8tivsystems/interfaceguard-mcp`. The `--access public` flag is required on first publish since scoped packages default to private.\r\n\r\n## How Screenshot Capture Works\r\n\r\n`capture_screenshots` launches a headless Chromium instance using the bundled `playwright` package, opens the target URL at each requested viewport, and takes a PNG screenshot. The images are held in an in-memory store keyed by `captureId` and passed directly to `submit_analysis` as multipart form data — the AI agent never handles raw image bytes.\r\n\r\nThe in-memory store is cleared after each successful `submit_analysis` call. If the MCP server process restarts between `capture_screenshots` and `submit_analysis`, the `captureId` will be invalid and you will need to capture again.\r\n\r\n## Troubleshooting\r\n\r\n**`UXA_API_KEY environment variable is required`**\r\nSet the `UXA_API_KEY` env var in your MCP client config.\r\n\r\n**`No capture found for captureId \"...\"`**\r\nThe MCP server process restarted between capture and submission, clearing the in-memory store. Run `capture_screenshots` again.\r\n\r\n**Playwright / Chromium not found**\r\nRun `npx playwright install chromium` to download the browser binary.\r\n\r\n**`networkidle` timeout on capture**\r\nThe page may have long-polling or streaming connections that prevent `networkidle`. This can happen with dev servers. The server will time out after 30 seconds and proceed with whatever has loaded.\r\n\r\n**API errors (401)**\r\nVerify `UXA_API_KEY` is correct. Generate a new key under Settings → API Keys in the InterfaceGuard web app if needed.\r\n\r\n## License\r\n\r\nMIT\r\n","readmeFilename":"README.md","_rev":"1-776c0a493cba5ceee25f1dc2799404be"}