Art Director MCP

Give your coding agent a visual direction, a design contract, and evidence to refine the result.

Art Director MCP runs locally alongside your IDE. It turns a structured project brief into distinct visual directions, records the selected direction as a versioned contract, and collects browser evidence from your running interface.

Installation · Assistants · Browser audit · Türkçe

What it does

• Explore visual directions. Three design packs offer six compositions (frame, grid, rhythm, navigation, mobile behavior). Directions are ranked by fit to your brief first and then chosen for structural variety; each one states why it fits, what it emphasizes, what drives its visual impact, how it changes on mobile and when it would be the wrong choice.
• Keep the brand yours. Palette and typography come from your brand facts and explicit preferences; the pack only fills gaps. Every decision in the tokens and contract names its source (user, host, brand, character, pack), and conflicts such as low-contrast brand colors are reported instead of silently corrected.
• Turn content into architecture. Brief items carry roles, priorities and groups; related items become one grouped section, sequences become steps, data becomes tables, and missing proof stays an explicit gap. Nothing is invented.
• Make decisions explicit. Generate design contracts, DTCG design tokens and CSS custom properties while preserving your project constraints and behaviors.
• Get focused implementation guidance. Request blueprints for the whole page, navigation, content, forms, tables and hero sections, derived from the contract's architecture and identity.
• Check the rendered interface. Collect desktop and mobile screenshots, accessibility findings and horizontal overflow measurements using the optional browser worker, with per-stage timing, coverage counts and partial results on timeout.

Your IDE agent handles implementation and visual judgment. Art Director supplies structured decisions and evidence without requiring an additional model API key.

Installation

Requires Node.js 22 or 24 LTS (the test suite runs on both; supported range >=22 <27) and npm. Run these commands inside your project:

npx -y @akifsen/[email protected] init --client cursor --apply

The npm package configures your IDE to run a pinned version locally. Reload the IDE and approve the project MCP server when prompted.

Alternatively, add the package to your project and bind that copy with --local:

npm install --save-dev @akifsen/[email protected]
npx art-director init --client cursor --apply --local

Both modes run on your computer. --local chooses the installed copy; without it the IDE launches the pinned package through npx. A written configuration file is not yet a working integration: run npx art-director doctor --client cursor to launch the configured command exactly as the IDE would and verify the stdio handshake (initialize → tools/list). It reports the startup time, the tool list, and hints when npx is still downloading, the IDE inherits an unsupported Node, or the command cannot be started. The IDE's own UI is outside what doctor can verify.

Assistant setup

Replace cursor with your assistant's option:

| Assistant | Option | |---|---| | Claude Code | claude | | Cursor | cursor | | GitHub Copilot in VS Code | copilot | | Kiro | kiro | | Codex CLI | codex | | Qoder CLI | qoder | | Roo Code | roocode | | Gemini CLI | gemini | | OpenCode | opencode | | Continue IDE extension | continue | | CodeBuddy CLI | codebuddy | | Droid (Factory) | droid | | Kilo Code | kilocode | | All supported assistants | all |

# Preview configuration changes
npx art-director init --client claude --local

# Configure every supported project adapter
npx art-director init --client all --apply --local

# Show available adapters and configuration details
npx art-director clients

Setup preserves unrelated settings and comments, creates backups, and keeps configuration inside the project. Repeated installation is idempotent. vscode is also accepted as an alias for copilot.

For Cursor, Copilot and Codex, add --with-rules to include workflow guidance. See the installation reference for configuration paths, client-specific behavior and assistants that are configured through their own settings instead of a project file.

Workflow

1. Inspect the project's UI files, stack, tokens and asset inventory.
2. Compare visual direction boards built from your brief and content.
3. Compile the selected direction into a versioned design contract.
4. Implement the interface with your IDE agent.
5. Audit the running interface and refine it using the findings.

| MCP tool | Purpose | |---|---| | inspect_project | Inspect the authorized project's UI inventory | | propose_directions | Generate context-compatible directions and HTML boards | | compile_design_contract | Create a revisioned contract and token outputs | | get_blueprint | Retrieve section-specific implementation guidance | | audit_ui | Collect and report browser evidence | | get_artifact | Read generated artifacts in bounded pages |

Direction boards are design studies. Each board follows its recipe's frame (top bar, side rail or inline masthead links, grid and rhythm), renders the brief's content architecture (grouped offerings, work lists, steps, tables, explicit evidence gaps) and applies the resolved identity (your brand palette and fonts where supplied, pack defaults otherwise). Directions therefore differ in structure and typography, not only in color, and the same composition looks different for different brands. Boards are written to .art-director/previews/<directionId>.html (previewPath) so you can open them in a browser. Each direction returns fit (reasons for and against), rationaleDetail (fit, emphasis, visualDriver, mobile, wrongWhen, identity), architecture and identity.provenance. Fewer than three directions are returned when the page type or your character.avoid list rules recipes out; the result says why. Contract updates use revision checks to prevent one client from silently overwriting another client's decisions.

Audits map measured findings onto the contract's deterministic requirements (requirementResults: overflow, labels, accessibility, contrast) and report what was actually covered (coverage: elements evaluated, contrast nodes, timed-out stages). A requirement passes only when every viewport measured it; unmeasured requirements are not-measured and timed-out runs are partial. Composition, architecture, identity, typography, mobile behavior, preserved behaviors and content truth stay marked for human review, and a passing audit means "no measured defect", not a successful design. An optional hostReview (structured verdicts from the IDE agent or a person) is stored with the contract revision it evaluated and never merged into measured findings.

Use it in IDE chat

After installation, reload your IDE and enable the Art Director MCP server in its tools/settings panel. Open a chat mode that can call tools. Paste a prompt below; these are natural-language requests, not slash commands. Your agent selects and calls the MCP tools.

Explore a design direction

Use Art Director MCP to inspect this project. I am building a portfolio for an independent designer; the primary task is finding and reading project case studies. Our brand uses a warm off-white background, near-black text and the "Fraunces" heading font; we have real project screenshots but no client logos or metrics yet. Preserve the existing routes and real content. Turn this into a structured brief (roles and priorities for each content item, brand facts, what to avoid), propose compatible visual directions, and explain for each one why it fits, what it emphasizes and when it would be the wrong choice. Show the direction boards before changing application code.

Implement the selected direction

Use the second direction you just proposed. Compile it into a design contract using the current revision, retrieve the page and navigation blueprints, and implement the design in this project's existing stack following the contract's section order and presentations. Preserve real content and behavior. Where the contract lists missing material, keep an explicit gap; do not invent testimonials or usage metrics.

Audit and refine

The application is running at http://127.0.0.1:5187. Use Art Director MCP to audit it against the contract we created. Summarize the desktop and mobile findings, distinguish measured issues from visual judgment, and fix the highest-priority issues. Run the audit again after the changes.

For this example, install the browser worker and add the application's exact origin to the server's startup arguments first; see Browser audit. Supplying a URL in chat does not grant network permission.

Focus on one component

Retrieve the form blueprint for our current contract. Use it to improve labels, focus behavior, loading, error and success states in this form. Explain which parts you verified and which need visual review.

Results larger than about 40 KB are stored as artifacts and returned with a summary; ask the agent to retrieve the artifactId with get_artifact (up to 12000 characters per page), following nextCursor. To compile a contract, pass directionId together with the same brief and seed used for propose_directions, or pass the generated direction object without its previewArtifactId, previewPath and differences fields. Use expectedRevision: 0 for the first saved contract and the current revision for updates. Compilation writes .art-director/contract.json, tokens.json, tokens.css and brief.json. Blueprint and audit calls use the contractId artifact identifier returned by compilation.

Command reference

Run terminal commands from the project where the package is installed. Prefix each command with npx art-director.

| Command | What it does | |---|---| | --help | Show CLI usage, assistant options and command names | | --version | Print the package version | | clients | List project adapters, aliases and assistants configured outside the project | | init --client cursor --local | Preview project configuration changes without writing | | init --client cursor --apply --local | Install the selected adapter with backups | | init --client all --apply --local | Install every supported project adapter after preflight checks | | doctor | Print package/Node versions, platform, project root, worker and Chromium availability, allowed origins and actionable hints | | doctor --client cursor | Additionally launch the command written in the assistant's project configuration and verify the MCP handshake over stdio (initialize, tools/list) with timings and diagnostics | | serve --project <absolute-root> | Start the stdio MCP server used by the IDE | | inspect | Inspect the current project's UI inventory | | directions --brief brief.json [--seed 0] | Generate directions from a structured JSON brief; boards are written to .art-director/previews/ | | contract --direction direction.json --expected-revision 0 | Compile and save a contract from a generated direction JSON file | | contract --direction-id <id> --brief brief.json [--seed 0] --expected-revision 0 | Compile by direction id plus the brief and seed used to generate it | | blueprint --contract-id <id> --section page [--stack react] | Implementation guidance for page, hero, navigation, content, form or table (same as get_blueprint) | | artifact <artifactId> [--cursor 0] [--limit 6000] | Read one page of an artifact (same as get_artifact) | | audit --contract-id <id> --url http://127.0.0.1:5187 --allow-origin http://127.0.0.1:5187 [--audit-budget 40000] | Audit a running local page against a saved contract | | browser install | Download the pinned browser binaries using the installed optional worker | | pack validate design-pack.json | Validate a design pack JSON file against the pack schema |

Running npx art-director without a command displays doctor output. Every command calls the same service layer as the MCP tools, so validation, error codes, pagination and output shape are identical in both interfaces.

CLI options

| Option | Applies to | Meaning | |---|---|---| | --project <absolute-root> | Project commands | Select the project; defaults to the current directory | | --client <name> | init | Choose an assistant, vscode alias or all | | --apply | init | Write the planned changes; otherwise preview only | | --local | init | Use the installed Node executable and package path | | --with-rules | init | Add managed workflow guidance for supported rule adapters | | --client <name> | doctor | Verify that assistant's project configuration by launching it and completing the MCP handshake | | --brief <file> | directions, contract | Project-relative brief JSON path; default brief.json | | --seed <integer> | directions, contract | Tie-break seed used for candidate ordering; default 0 | | --direction <file> | contract | Project-relative generated direction JSON path; default direction.json | | --direction-id <id> | contract | Compile by id instead of a direction file (requires --brief) | | --expected-revision <integer> | contract | Expected current saved revision; default 0 | | --contract-id <id> | blueprint, audit | Contract artifact ID returned by compilation | | --section <name>, --stack <react\|html> | blueprint | Blueprint part (default page) and target stack (default react) | | --cursor <n>, --limit <n> | artifact | Page window; limit at most 12000 characters | | --url <url> | audit | Running application's page URL | | --allow-origin <origin> | serve, audit | Allow an exact numeric-loopback origin; repeat for multiple origins | | --audit-budget <ms> | serve, audit | Total browser budget handed to the worker (default 40000; the CLI waits 15 s more for launch/IPC) | | --help | CLI | Show help instead of executing a command |

Brief, direction and pack file paths are relative to the selected project. They cannot read outside that root. A minimal brief file looks like this:

{
  "product": "Designer portfolio",
  "primaryTask": "Find and read project case studies",
  "pageType": "portfolio",
  "audience": "Potential clients",
  "content": [
    { "heading": "Selected work", "body": "Replace this with your actual project description." }
  ],
  "constraints": ["Preserve existing routes"]
}

pageType accepts portfolio, product, dashboard, landing, company, article or docs. Keep real project content in the brief. CLI results are JSON; use the returned artifacts through the IDE's MCP tools when a result is paginated.

Brief fields that shape the design

All of the following are optional and backward compatible; a 0.1/0.2 brief still works and receives pack defaults with provenance: "pack".

| Field | Effect | |---|---| | purpose | One sentence about what the organization or product does; becomes the hero support line and informs fit | | secondaryTasks | Listed in reference columns; never turned into sections | | content[].role | hero, offering, work, proof, process, technical, organization, data, support, contact, other. Inferred from headings when absent | | content[].priority | primary, secondary, supporting; drives section order and size | | content[].group | Items with the same group render as one grouped section instead of one section each | | content[].evidence | real, placeholder, none; proof without real evidence renders as an explicit "Evidence pending" gap | | brand.colors, brand.fonts, brand.name, brand.designSystem | Existing brand facts; override pack palette and type. Brand font names lead the CSS font stacks and are classified (serif/sans/condensed/mono) for the type system | | character.prefer | Adjectives mapped to concrete decisions (for example premium → serif heading, weight 400, restrained accent; technical → tabular numerals, sans, weight 600). Applied only where brand and preferences did not decide; unmapped words are reported, contradictions are reported | | character.avoid | Structural patterns to exclude (sidebar, hero-image, numbered-steps, tables, masthead, …). Recipes relying on them are excluded; unmapped words become a human-review requirement | | assets | Which material exists (screenshots, photography, illustration, logos); a product stage without screenshots is penalized and labeled as a placeholder | | preserve | Behaviors that must survive implementation; carried into the contract as a requirement | | preferences | Explicit decisions (navigation, density, heading, body, headingWeight, palette) with source: "user" or "host"; highest precedence |

Precedence is preferences → brand → character → pack. The resolved identity records the source of every decision and lists conflicts (for example brand text/background contrast below 4.5:1) instead of silently changing your colors.

Browser audit

Install the matching optional worker in the same project:

npm install --save-dev @akifsen/[email protected]
npx -y @akifsen/[email protected] browser install

Start your application's development server, then add an allowed origin to the Art Director server arguments in your IDE configuration:

--allow-origin http://127.0.0.1:5187

Use the port belonging to your application. The worker visits explicitly allowed numeric loopback origins in an isolated browser context. A URL whose origin is not allowed is refused before any browser starts, with the exact --allow-origin value to add. Art Director does not start your application server or use your personal browser profile.

Audits capture desktop/mobile evidence and run axe accessibility, focus and overflow checks within a total budget (default 40 s) split into named stages (launch, navigate, fonts, measure, axe, focus, screenshot). When a stage exceeds its share, the worker returns the completed viewports as partial and names the stage that timed out instead of failing the whole audit; the response's coverage lists timed-out stages and requirements that were not measured. Automated findings support review; they are not a WCAG certification or an aesthetic score. The IDE agent performs visual evaluation and may record it through audit_ui's hostReview field, which is stored alongside the measured findings. Worker 0.1.0 still works with this server (without stage budgets); doctor recommends the upgrade.

Local execution and privacy

The MCP server runs on the user's computer. Using it does not call this repository's GitHub API, trigger GitHub Actions, or connect to the maintainer's computer. Package installation and the explicit browser installation download their dependencies.

No separate Art Director cloud service, telemetry or model API key is used. Tool responses may be processed by your IDE's model provider under that provider's policies.

Reports and screenshots stay in the project's .art-director/ directory. Screenshot masks affect pixels; DOM findings can still include page content. Review generated evidence before sharing it. See SECURITY.md.

Develop locally

git clone https://github.com/akifsen/art-director-mcp.git
cd art-director-mcp
npm ci --ignore-scripts
npm run typecheck
npm run build
npm test

The repository includes static review fixtures in examples/fixtures (portfolio and dashboard briefs, a page with two deliberate defects and its corrected version, and a matrix/ of briefs that exercise brand facts, grouped content, missing evidence and avoid lists) and a React/Vite example:

npm ci --ignore-scripts --prefix examples/expressive-product
npm run dev --prefix examples/expressive-product -- --port 5187 --strictPort

Windows, Linux and macOS are covered by the CI workflow, including package installation and browser checks. See CONTRIBUTING.md for development instructions.

License

MIT. Third-party dependencies retain their own licenses; see THIRD_PARTY_NOTICES.