VisualSpec

io.github.utkarshx27Published by GitHub account utkarshx27v0.1.0Updated Oct 24, 2026

Structured, constraint-aware visual generation and deterministic layout for AI agents

VerifiedSTDIODesktop onlyDeveloper ToolsMedia & Design

Overview

AI-generated overview

Lets an assistant turn a brief into a structured visual spec, render deterministic typography and layout, and generate social graphics with optional AI imagery.

What you can do
VisualSpec converts natural-language briefs into a machine-readable YAML visual spec, validates it against a schema, and renders exact headlines, subtitles, badges and safe margins locally with an SVG layout engine. It can also run a full pipeline that combines an AI-generated base image with the deterministic text overlay, then run visual QA on margins, dimensions, line counts and copy invariants, and apply localized repairs. Tools include visual_brief_to_spec, visual_validate_spec, visual_render, visual_generate, visual_check_qa, visual_repair and visual_list_resources.
When to use it
Use it when you need social or marketing graphics where wording, typography and platform dimensions must be exact rather than left to an image model. It suits Instagram, LinkedIn and generic social formats with product launch, quote card and stat card templates. Deterministic rendering works without any image API key.
Requirements
Runs locally over stdio as an npm package, so Node.js and npx are needed. Optional GEMINI_API_KEY or OPENAI_API_KEY enable AI image generation; without them only deterministic rendering and mock generation are available. Desktop only, no remote endpoint.
Before you install
The optional GEMINI_API_KEY and OPENAI_API_KEY are secrets passed as environment variables and are used to send generation requests to those providers. Generation writes output files and bundles to a local output directory. Review the generation request and QA report before publishing assets.

Installation

In SourceWeft

  1. Open VisualSpec in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

VisualSpec

Deterministic visual generation for AI agents.
AI creates the imagery. VisualSpec guarantees the typography and layout.

[VisualSpec Generation Pipeline Demo]

[npm package] [MCP Registry] [License] [Tests] [GitHub stars]

bash
# Instant workspace setup (no clone required)npx @utkarshx27/visualspec init
# Launch local MCP Server for Cursor, Claude Desktop, or Antigravitynpx @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:

  1. Generative Layers (AI Models): Photography, 3D subjects, atmospheric backgrounds, textures, lighting.
  2. Deterministic Layers (Code & SVG Engine): Exact headlines, subtitles, badges, logos, metrics, safe margins, and layout rules.
  3. Structured Visual Spec: A machine-readable YAML specification that acts as the single contract.
  4. Visual QA & Targeted Repair: Verifies geometry, margins, and exact copy invariants, synthesizing localized repairs without regenerating entire scenes.
text
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

Quickstart

Instant Run (No Install Required)

bash
# Initialize a new VisualSpec workspacenpx @utkarshx27/visualspec init
# Launch local MCP Server for Cursor, Claude, or Antigravity IDEnpx @utkarshx27/visualspec mcp

Or Install Globally

bash
npm install -g @utkarshx27/visualspec
# Use CLI commands directlyvisual initvisual mcp

Or Build from Source

bash
git clone https://github.com/utkarshx27/visualspec.gitcd visualspecnpm installnpm run build

1. Initialize a Project

bash
npx @utkarshx27/visualspec init

2. Validate a Visual Spec

bash
npx @utkarshx27/visualspec validate examples/product-launch/spec.yaml

3. Inspect the Compiled Generation Prompt

bash
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:

bash
npx @utkarshx27/visualspec render examples/product-launch/spec.yaml --output ./output/demo-launch

5. Run the Full Generation Pipeline

bash
npx @utkarshx27/visualspec generate examples/product-launch/spec.yaml --provider mock --output ./output/demo-launch

6. Verify Asset Quality with Visual QA

bash
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:

bash
# Launch MCP server over stdionpx @utkarshx27/visualspec mcp
# Or if installed globallyvisual 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:

text
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:

bash
npm test

All 28 tests run offline without requiring any third-party API keys.

License

Licensed under the Apache License, Version 2.0.

Source: README.md at commit cd28b8e

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts