mcpField
V
VisualSpec

VisualSpec

本地服务
github.com/utkarshx27媒体与设计07 周前更新
代码仓库

关于 VisualSpec

VisualSpec 是面向 AI Agent 的视觉生成框架，将 AI 生成的图像与代码控制的文字和布局分层处理，适合制作社交媒体及营销图形的团队。它通过 YAML 规格、确定性渲染和视觉 QA 检查布局约束，并支持局部修复。

主要功能

  1. 01用 YAML 规格描述视觉布局
  2. 02确定性渲染文字与版式
  3. 03生成图像并叠加精确文字
  4. 04检查尺寸、安全边距与文案
  5. 05定位并修复局部布局问题
  6. 06提供社交平台模板与技能定义

适用场景

  1. 01制作 Instagram 与 LinkedIn 社交图形
  2. 02生成产品发布、引言和数据卡片
  3. 03验证图形尺寸、边距与文案
  4. 04修复已生成图像中的排版问题

MCP 相关

VisualSpec 通过 stdio MCP 服务向 AI 编码助手提供视觉工具，包括规格转换、校验、渲染、生成、QA 检查及修复，并可列出平台包和模板。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
  "mcpServers": {
    "utkarshx27-visualspec": {
      "command": "npx",
      "args": [
        "-y",
        "@utkarshx27/visualspec"
      ],
      "env": {
        "OPENAI_API_KEY": "<OPENAI_API_KEY>",
        "GEMINI_API_KEY": "<GEMINI_API_KEY>"
      }
    }
  }
}
启动命令npx -y @utkarshx27/visualspec
需要配置的环境变量
OPENAI_API_KEY密钥Optional API key for OpenAI image generation
GEMINI_API_KEY密钥Optional API key for Google Gemini image generation

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包
npm@utkarshx27/visualspec0.1.0

工具

7

收录的工具列表 · 更新于 2 周前

参数类型必填说明
briefstring是用户请求或创意简报描述
platformstring否目标平台（例如 instagram、linkedin、generic-social）
templatestring否目标模板类型（例如 product-launch、quote-card、stat-card）

详细介绍

VisualSpec

面向 AI Agent 的确定性视觉生成。
AI 负责创建图像。VisualSpec 保证排版和布局。

VisualSpec 生成流程演示

npm 包 MCP 注册表 许可证 测试 GitHub 星标 

# Instant workspace setup (no clone required)
npx @utkarshx27/visualspec init

# Launch local MCP Server for Cursor, Claude Desktop, or Antigravity
npx @utkarshx27/visualspec mcp

核心问题

大多数图像生成工作流在生成社交媒体和营销图形时都会失败，因为单条自然语言提示词需要同时处理过多事项：

  • 主体和背景
  • 精确的排版和文案
  • 平台尺寸和安全边距
  • 视觉层级和留白
  • 品牌颜色规则和限制

图像模型经常会生成乱码、截断单词，或无视构图规则。

解决方案：分离图层

VisualSpec 将生成式内容与确定性内容分开处理：

  1. 生成式图层（AI 模型）：摄影、3D 主体、氛围背景、纹理、光照。
  2. 确定性图层（代码和 SVG 引擎）：准确的标题、副标题、徽章、徽标、指标、安全边距和布局规则。
  3. 结构化视觉规范：机器可读的 YAML 规范，作为唯一的约定。
  4. 视觉 QA 和定向修复：验证几何形状、边距和精确文案约束，并生成局部修复，而无需重新生成整个场景。
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

文档

快速入门

即时运行（无需安装）
# Initialize a new VisualSpec workspace
npx @utkarshx27/visualspec init

# Launch local MCP Server for Cursor, Claude, or Antigravity IDE
npx @utkarshx27/visualspec mcp
或全局安装
npm install -g @utkarshx27/visualspec

# Use CLI commands directly
visual init
visual mcp
或从源代码构建
git clone https://github.com/utkarshx27/visualspec.git
cd visualspec
npm install
npm run build
1. 初始化项目
npx @utkarshx27/visualspec init
2. 验证视觉规范
npx @utkarshx27/visualspec validate examples/product-launch/spec.yaml
3. 检查编译后的生成提示词
npx @utkarshx27/visualspec compile examples/product-launch/spec.yaml --provider openai
4. 确定性渲染（无需 API 密钥）

在本地渲染布局、排版和背景样式：

npx @utkarshx27/visualspec render examples/product-launch/spec.yaml --output ./output/demo-launch
5. 运行完整生成流程
npx @utkarshx27/visualspec generate examples/product-launch/spec.yaml --provider mock --output ./output/demo-launch
6. 使用视觉 QA 验证素材质量
npx @utkarshx27/visualspec check ./output/demo-launch/final.png --spec examples/product-launch/spec.yaml

模型上下文协议（MCP）服务

VisualSpec 通过 stdio 作为原生 MCP 服务运行，使 AI 编码助手（Cursor、Claude Code、Gemini CLI 和 Antigravity IDE）能够直接调用视觉工具：

# Launch MCP server over stdio
npx @utkarshx27/visualspec mcp

# Or if installed globally
visual mcp
可用的 MCP 工具
  • visual_brief_to_spec：将自然语言请求转换为有效的 VisualSpec YAML。
  • visual_validate_spec：验证规范是否符合架构。
  • visual_render：确定性布局和排版渲染（无需 API 密钥）。
  • visual_generate：完整的图像模型适配器和确定性文字叠加流程。
  • visual_check_qa：检查安全边距、行数、尺寸和约束。
  • visual_repair：自动诊断并局部修复排版和布局。
  • visual_list_resources：列出受支持的平台包和模板。

关于 Cursor、Claude Desktop 和 Antigravity IDE 的配置示例，请参阅 MCP 设置指南。

输出包

每次生成都会创建一套完整、可复现的调试包：

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

支持的平台和模板

平台
  • Instagram：信息流竖版（1080x1350，4:5）、方形（1080x1080，1:1）、快拍（1080x1920，9:16）。
  • LinkedIn：信息流竖版（1080x1350）、方形（1080x1080）、横幅（1200x628）。
  • 通用社交平台：通用的 1:1、4:5 和 16:9 社交格式。
模板
  • 产品发布：高冲击力标题、功能标签、产品视觉区域、辅助副标题。
  • 引言卡片：居中排布的编辑风格引言、作者署名、简约氛围光效。
  • 数据卡片：醒目的大型数字指标、描述性标签和数据背景说明。

Agent 技能

该框架包含 10 个标准化技能定义，位于 ./skills/：

  • using-visualspec：核心工作流说明。
  • visual-brief：需求提取与分析。
  • visual-spec：YAML 编写与架构规则。
  • composition：空间层级与负空间分配。
  • typography：字体系列分类与行数规划。
  • strict-constraints：不变量分类与禁止参数。
  • social-instagram：Instagram 专属设计推理。
  • social-linkedin：LinkedIn 专属设计推理。
  • visual-qa：自动化检查与验证。
  • visual-repair：局部诊断与补丁生成。

路线图与开放贡献

欢迎贡献！以下是适合共同开发的重点领域：

  • 更多平台：X/Twitter（页眉、帖子）、YouTube 缩略图、Pinterest、TikTok 封面。
  • 更多模板：客户评价、产品对比、活动公告、功能列表。
  • 更多图像模型适配器：Flux、Stable Diffusion / ComfyUI、Midjourney API。
  • 品牌包：多品牌调色板覆盖、自定义字体加载、Logo 留白规则。
  • Visual Studio：本地 Web 试验场 / 查看器，用于实时检查规范和切换边距显示。

贡献

欢迎贡献！请查看：

测试

运行自动化测试套件：

npm test

全部 28 项测试均可离线运行，无需任何第三方 API 密钥。

许可证

根据 Apache License, Version 2.0 授权。

评论

支持 Markdown

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。