Enables AI agents to generate deterministic visual layouts with precise typography, brand constraints, and automated quality assurance.
Also known as utkarshx27/visualspec, @utkarshx27/visualspec
- Stars
- 0
- Tools
- 7
- Downloads, 30 days
- —
- Latest version
- 0.1.0
- Last commit
- Sep 10, 2026
- License
- Apache-2.0
What is VisualSpec MCP?
VisualSpec enables AI agents to generate deterministic visual layouts with precise typography, brand constraints, and automated quality assurance. It exposes 7 tools, such as visual_brief_to_spec, visual_validate_spec, visual_render.
Summary generated from the project's README
About VisualSpec MCP server
VisualSpec provides a framework for AI agents to create marketing and social media graphics that maintain strict control over typography and layout. While standard image models often struggle with text accuracy and composition, this server separates generative tasks like background creation from deterministic tasks like text overlays and margin management. It uses a machine-readable YAML specification to act as a contract between the user intent and the final visual output.
Developers can run this as a local MCP server via stdio to integrate with clients like Cursor, Claude Desktop, or Antigravity. The system includes specialized tools such as visual_brief_to_spec for converting natural language into structured data, visual_render for local layout generation without API keys, and visual_check_qa to verify safe margins and exact copy. It also features a visual_repair tool to diagnose and fix layout issues automatically.
What you can do with it
- 1Convert text to design specsAn AI agent can transform a natural language user request into a structured YAML visual specification.
- 2Automated quality assuranceThe system can inspect generated images to ensure they meet specific geometric and typographic constraints.
- 3Fix layout errors automaticallyIf a generated graphic fails quality checks, the server can perform localized repairs on the typography or layout.
Written from the project's README. Every use case is checked against a quote from it.
How to install VisualSpec MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall VisualSpec MCP in Claude Code
$ claude mcp add --env 'GEMINI_API_KEY=<YOUR_GEMINI_API_KEY>' --env 'OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>' visualspec -- npx -y @utkarshx27/visualspecInstall VisualSpec MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"visualspec": {
"command": "npx",
"args": [
"-y",
"@utkarshx27/visualspec"
],
"env": {
"GEMINI_API_KEY": "<YOUR_GEMINI_API_KEY>",
"OPENAI_API_KEY": "<YOUR_OPENAI_API_KEY>"
}
}
}
}Install VisualSpec MCP in VS Code
.vscode/mcp.json
{
"servers": {
"visualspec": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@utkarshx27/visualspec"
],
"env": {
"GEMINI_API_KEY": "<YOUR_GEMINI_API_KEY>",
"OPENAI_API_KEY": "<YOUR_OPENAI_API_KEY>"
}
}
}
}Install VisualSpec MCP in VS Code CLI
$ code --add-mcp '{"name":"visualspec","type":"stdio","command":"npx","args":["-y","@utkarshx27/visualspec"],"env":{"GEMINI_API_KEY":"<YOUR_GEMINI_API_KEY>","OPENAI_API_KEY":"<YOUR_OPENAI_API_KEY>"}}'Install VisualSpec MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"visualspec": {
"command": "npx",
"args": [
"-y",
"@utkarshx27/visualspec"
],
"env": {
"GEMINI_API_KEY": "<YOUR_GEMINI_API_KEY>",
"OPENAI_API_KEY": "<YOUR_OPENAI_API_KEY>"
}
}
}
}Install VisualSpec MCP in Codex
$ codex mcp add visualspec --env 'GEMINI_API_KEY=<YOUR_GEMINI_API_KEY>' --env 'OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>' -- npx -y @utkarshx27/visualspecInstall VisualSpec MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.visualspec] command = "npx" args = ["-y", "@utkarshx27/visualspec"] [mcp_servers.visualspec.env] GEMINI_API_KEY = "<YOUR_GEMINI_API_KEY>" OPENAI_API_KEY = "<YOUR_OPENAI_API_KEY>"
Install VisualSpec MCP in Gemini CLI
$ gemini mcp add -s user -e 'GEMINI_API_KEY=<YOUR_GEMINI_API_KEY>' -e 'OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>' visualspec npx -- -y @utkarshx27/visualspecInstall VisualSpec MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"visualspec": {
"command": "npx",
"args": [
"-y",
"@utkarshx27/visualspec"
],
"env": {
"GEMINI_API_KEY": "<YOUR_GEMINI_API_KEY>",
"OPENAI_API_KEY": "<YOUR_OPENAI_API_KEY>"
}
}
}
}VisualSpec MCP tools 7
Detected from the READMEvisual_brief_to_specvisual_validate_specvisual_rendervisual_generatevisual_check_qavisual_repairvisual_list_resources
Configuration
GEMINI_API_KEYSecretOptional API key for Google Gemini image generation
OPENAI_API_KEYSecretOptional API key for OpenAI image generation
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableutkarshx27/visualspec is public and reachablegithub.com/utkarshx27/visualspec ↗Pass
- Package names this repository as its source@utkarshx27/visualspec names utkarshx27/visualspec as sourcenpmjs.com/package/@utkarshx27/visualspec ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-09-10github.com/utkarshx27/visualspec ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @utkarshx27/visualspecPass
- No critical advisory in the package or its dependencies132 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model7 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubVisualSpec
Deterministic visual generation for AI agents.
AI creates the imagery. VisualSpec guarantees the typography and layout.
# Instant workspace setup (no clone required)
npx @utkarshx27/visualspec init
# Launch local MCP Server for Cursor, Claude Desktop, or Antigravity
npx @utkarshx27/visualspec mcp
The Core Problem
Most image-generation workflows fail for social and marketing graphics because a single natural-language prompt is expected to handle too many concerns at once:
- subject & background
- exact typography & wording
- platform dimensions & safe margins
- visual hierarchy & negative space
- brand color rules & constraints
Image models frequently hallucinate gibberish text, truncate words, or disregard composition rules.
The Solution: Layer Separation
VisualSpec separates generative concerns from deterministic concerns:
- Generative Layers (AI Models): Photography, 3D subjects, atmospheric backgrounds, textures, lighting.
- Deterministic Layers (Code & SVG Engine): Exact headlines, subtitles, badges, logos, metrics, safe margins, and layout rules.
- Structured Visual Spec: A machine-readable YAML specification that acts as the single contract.
- Visual QA & Targeted Repair: Verifies geometry, margins, and exact copy invariants, synthesizing localized repairs without regenerating entire scenes.
User Brief / Intent
│
▼
Visual Spec (spec.yaml)
│
┌───┴──────────────┐
▼ ▼
Platform Pack Template Pack
│ │
└───┬──────────────┘
▼
Spec Resolver
│
┌───┴───────────────────────┐
▼ ▼
Model Adapter Deterministic Layout
(Generative Base) (SVG Typography / Overlay)
│ │
└───┬───────────────────────┘
▼
Compositor (Sharp)
│
▼
Visual QA (Constraints, Safe Margins, Exact Copy)
│
├── PASS ──► Final Asset Bundle
│
└── FAIL ──► Targeted Repair Planner
Documentation
- Architecture & Design Principles
- VisualSpec Schema & Contract
- MCP Server Setup (Cursor, Claude, Antigravity)
- Adding a New Image Model Provider
- Contributing Guidelines
Quickstart
Instant Run (No Install Required)
# Initialize a new VisualSpec workspace
npx @utkarshx27/visualspec init
# Launch local MCP Server for Cursor, Claude, or Antigravity IDE
npx @utkarshx27/visualspec mcp
Or Install Globally
npm install -g @utkarshx27/visualspec
# Use CLI commands directly
visual init
visual mcp
Or Build from Source
git clone https://github.com/utkarshx27/visualspec.git
cd visualspec
npm install
npm run build
1. Initialize a Project
npx @utkarshx27/visualspec init
2. Validate a Visual Spec
npx @utkarshx27/visualspec validate examples/product-launch/spec.yaml
3. Inspect the Compiled Generation Prompt
npx @utkarshx27/visualspec compile examples/product-launch/spec.yaml --provider openai
4. Deterministic Render (No API Key Required)
Render layout, typography, and background styling locally:
npx @utkarshx27/visualspec render examples/product-launch/spec.yaml --output ./output/demo-launch
5. Run the Full Generation Pipeline
npx @utkarshx27/visualspec generate examples/product-launch/spec.yaml --provider mock --output ./output/demo-launch
6. Verify Asset Quality with Visual QA
npx @utkarshx27/visualspec check ./output/demo-launch/final.png --spec examples/product-launch/spec.yaml
Model Context Protocol (MCP) Server
VisualSpec runs as a native MCP server over stdio, enabling AI coding assistants (Cursor, Claude Code, Gemini CLI, and Antigravity IDE) to invoke visual tools directly:
# Launch MCP server over stdio
npx @utkarshx27/visualspec mcp
# Or if installed globally
visual mcp
Available MCP Tools
visual_brief_to_spec: Convert natural language requests into valid VisualSpec YAML.visual_validate_spec: Schema validation for specs.visual_render: Deterministic layout & typography rendering (zero API key).visual_generate: Full image model adapter + deterministic text overlay pipeline.visual_check_qa: Inspect safe margins, line counts, dimensions, and invariants.visual_repair: Automated diagnosis and localized typography/layout repair.visual_list_resources: List supported platform packs and templates.
See the MCP Setup Guide for Cursor, Claude Desktop, and Antigravity IDE configuration snippets.
Output Bundle
Every generation creates a complete, reproducible debug bundle:
output/demo-launch/
├── final.png # Platform-ready asset
├── visual-spec.yaml # Original input specification
├── resolved-spec.yaml # Full spec with platform & template rules applied
├── generation-request.json # Exact prompt and negative parameters sent to model
├── qa-report.json # Deterministic and constraint QA verification results
└── metadata.json # Execution timestamps and file index
Supported Platforms & Templates
Platforms
- Instagram: Feed portrait (1080x1350, 4:5), Square (1080x1080, 1:1), Story (1080x1920, 9:16).
- LinkedIn: Feed portrait (1080x1350), Square (1080x1080), Banner (1200x628).
- Generic Social: Universal 1:1, 4:5, and 16:9 social formats.
Templates
- Product Launch: High-impact headline, feature pill, product visual region, supporting subhead.
- Quote Card: Center-focused editorial quote, author attribution, minimal atmospheric glow.
- Stat Card: Large numeric hero metric, descriptive label, and data context notes.
Agent Skills
The framework includes 10 standardized skill definitions located in ./skills/:
using-visualspec: Master workflow instructions.visual-brief: Brief extraction and analysis.visual-spec: YAML authoring and schema rules.composition: Spatial hierarchy and negative space allocation.typography: Font family classing and line budgeting.strict-constraints: Invariant taxonomy and forbidden parameters.social-instagram: Instagram-specific design reasoning.social-linkedin: LinkedIn-specific design reasoning.visual-qa: Automated inspection and validation.visual-repair: Localized diagnosis and patch generation.
Roadmap & Open Contributions
We welcome contributions! Key areas to build together:
- Additional Platforms: X/Twitter (Header, Post), YouTube Thumbnails, Pinterest, TikTok Cover.
- Additional Templates: Testimonial, Product Comparison, Event Announcement, Feature List.
- Additional Image Model Adapters: Flux, Stable Diffusion / ComfyUI, Midjourney API.
- Brand Packs: Multi-brand palette overrides, custom font loading, logo clear space rules.
- Visual Studio: Local web playground / viewer for real-time spec inspection and margin toggling.
Contributing
Contributions are welcome! Please check our:
Testing
Run the automated test suite:
npm test
All 28 tests run offline without requiring any third-party API keys.
License
Licensed under the Apache License, Version 2.0.
VisualSpec MCP questions
How do I add VisualSpec MCP to Claude Code?
Run claude mcp add --env 'GEMINI_API_KEY=<YOUR_GEMINI_API_KEY>' --env 'OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>' visualspec -- npx -y @utkarshx27/visualspec in your terminal. Add --scope user to make it available in every project.
How do I add VisualSpec MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does VisualSpec MCP provide?
It exposes 7 tools, including visual_brief_to_spec, visual_validate_spec, visual_render, visual_generate, visual_check_qa.
How can I use VisualSpec with my AI coding assistant?
You can launch the local MCP server using npx @utkarshx27/visualspec mcp to enable tools in Cursor, Claude Desktop, or Antigravity IDE.
Does deterministic rendering require an API key?
No, you can render layout, typography, and background styling locally without an API key.
What tools are available through the MCP server?
Available tools include converting briefs to specs, validating schemas, rendering layouts, generating full images, performing visual QA, and automated layout repair.