better-picture-mcp

v1.0.14

Published

5 months ago

MCP tool for generating beautiful article illustrations using HTML and screenshots

0High
0Medium
0Low

oiloil

mcp illustration screenshot html

Better Picture MCP

一个用于生成精美文章配图的 MCP（Model Context Protocol）工具。通过 AI 生成 HTML 并截图，创建适合技术文章的专业配图。

特性

🎨 极简设计：纯白背景，简约现代的扁平风格
📊 双模式支持：
- 插图模式：手绘风格配图，集成 chart.xkcd 图表库
- Mermaid 模式：专业流程图、时序图、饼图等图表
🎯 智能生成：AI 自动生成 Mermaid 代码或配图布局
🎭 图标丰富：使用 Iconify（Solar 双色图标集）
📐 灵活尺寸：支持多种宽高比（16:9、4:3、1:1 等）
✨ 高质量输出：2倍分辨率，清晰锐利
💡 内容优先：大字体、大图标，留白适中
📂 灵活输出：支持自定义输出目录
🌐 多重字体加载策略：Google Fonts + 国内镜像 + 系统字体降级，确保任何环境都能正常显示

🆕 TSX 模板系统（v1.1.0）

核心改进

⚡ Token 消耗降低 80%：AI 只生成 JSON（200-500 tokens）而非完整 HTML（5000+ tokens）
🎯 生成更稳定：JSON 格式严格可控，避免 HTML 标记错误
🧩 高度可扩展：新增模板只需添加 TSX 文件
🔒 类型安全：完整的 TypeScript 类型定义
🌐 可视化工具：Next.js 网站用于模板调试和管理

6 个核心模板

Grid 布局 - 网格布局，适合平等展示多个要点
Comparison 布局 - 左右对比，适合 AB 测试
Timeline 布局 - 时间轴，适合流程展示
Hero 布局 - 焦点布局，突出核心概念
Asymmetric 布局 - 非对称布局，强调层次
Chart 布局 - 数据可视化，集成 chart.xkcd

可视化网站

在 website/ 目录下提供了完整的 Next.js 可视化工具：

模板库 (/templates) - 浏览所有模板及其参数
生成图片 (/generate) - 输入描述自动生成配图
模板调试器 (/debug/[templateId]) - 实时编辑 JSON 并预览

cd website
npm install
npm run dev
# 访问 http://localhost:3000

详见 TEMPLATE_SYSTEM.md 和 website/README.md

效果展示

插图模式示例

1️⃣ 微服务架构（Blue 主题 · 16:9）

微服务架构 展示技术架构的三大核心优势，使用非对称布局

2️⃣ 敏捷开发流程（Orange 主题 · 16:9）

敏捷开发流程 时间轴布局展示流程步骤，带箭头引导

3️⃣ 数据安全（Green 主题 · 4:3）

数据安全 垂直列表布局展示多个要点，4:3 纵向比例

4️⃣ 设计系统（Purple 主题 · 1:1）

方形布局适合社交媒体分享

5️⃣ 产品增长指标（Pink 主题 · 16:9）

产品增长指标 数字主导型布局，突出关键数据

Mermaid 图表模式示例

6️⃣ 用户注册流程图（Blue 主题）

用户注册流程 Mermaid 流程图，自动生成专业图表

7️⃣ 技术栈使用占比（Orange 主题）

技术栈占比 Mermaid 饼图，清晰展示数据比例

功能对比表

| 特性 | 插图模式 | Mermaid 模式 | |------|---------|------------| | 适用场景 | 概念展示、要点说明、数据展示 | 流程图、时序图、饼图、架构图 | | 生成方式 | AI 生成 HTML 布局 | AI 生成 Mermaid 代码 | | 视觉风格 | 手绘风格、莫兰迪配色 | 专业图表、自动布局 | | 图标支持 | ✅ Solar 双色图标集 | ❌ 不使用图标 | | 宽高比 | 16:9、4:3、1:1、21:9、3:2 | 自适应内容大小 | | 主题色 | 6 种莫兰迪主题 | 6 种莫兰迪主题 | | 布局类型 | 12 种预设布局 | Mermaid 原生布局 |

技术栈

核心框架：Node.js + TypeScript
MCP SDK：@modelcontextprotocol/sdk
AI 模型：通过 OpenRouter 调用（默认 Claude Sonnet 4.5）
截图引擎：Puppeteer
可视化库：
- Tailwind CSS - 现代 CSS 框架
- Mermaid.js - 流程图、时序图、饼图等专业图表
- chart.xkcd - 手绘风格数据图表
- Iconify - Solar 双色图标集

配置

在 ~/.cursor/mcp.json 中添加：

{
  "mcpServers": {
    "better-picture": {
      "command": "npx",
      "args": [
        "-y",
        "better-picture-mcp"
      ],
      "env": {
        "OPENROUTER_KEY": "your-openrouter-api-key",
        "OPENROUTER_MODEL": "anthropic/claude-sonnet-4.5"
      }
    }
  }
}

环境变量说明：

OPENROUTER_KEY：OpenRouter API 密钥（必需）
OPENROUTER_MODEL：使用的 AI 模型，默认 anthropic/claude-sonnet-4.5（可选）

提示：

也可先全局安装：npm i -g better-picture-mcp，然后配置 "command": "better-picture-mcp"
使用其他包管理器：pnpm dlx better-picture-mcp 或 yarn dlx better-picture-mcp

使用方法

在 Cursor 中使用

安装并配置后，AI 助手可以自动调用此工具生成配图：

AI：请生成一张展示微服务架构的配图

工具参数

description (必需)：配图描述
- 插图模式示例："展示用户认证流程"、"比较 REST 和 GraphQL 的优缺点"
- Mermaid 模式示例："用户登录流程图"、"API 调用时序"、"市场份额饼图"
type (可选，默认 illustration)：配图类型
- illustration - 插图模式，手绘风格配图
- mermaid - 图表模式，生成流程图、时序图、饼图等专业图表
aspectRatio (可选，默认 16:9)：宽高比
- 16:9 - 横屏，适合博客文章
- 4:3 - 传统比例
- 1:1 - 方形，适合社交媒体
- 21:9 - 超宽屏
- 3:2 - 照片比例
theme (可选，默认 orange)：主题颜色（莫兰迪色系）
- orange - 莫兰迪橙，温暖复古
- blue - 莫兰迪蓝，宁静专业
- green - 莫兰迪绿，自然清新
- purple - 莫兰迪紫，优雅神秘
- pink - 莫兰迪粉，柔和温馨
- grayscale - 黑白灰，极简现代
outputDir (可选)：输出目录路径
- 不提供时使用默认输出目录
- AI 可根据用户需求指定自定义路径
- 示例："/Users/username/Documents/images"

示例

插图模式（Illustration）

// 生成流程图配图
{
  "description": "展示 CI/CD 流水线的完整流程",
  "type": "illustration",
  "aspectRatio": "16:9",
  "theme": "blue",
  "outputDir": "/path/to/output"  // 可选，自定义输出路径
}

// 生成对比图配图
{
  "description": "对比 SQL 和 NoSQL 数据库的特点",
  "type": "illustration",
  "aspectRatio": "4:3",
  "theme": "green"
}

// 生成架构图配图
{
  "description": "展示微前端架构的组成",
  "type": "illustration",
  "aspectRatio": "21:9",
  "theme": "purple"
}

Mermaid 模式（专业图表）

// 生成流程图
{
  "description": "用户登录流程：访问登录页 -> 输入用户名密码 -> 验证 -> 成功则跳转首页，失败则显示错误",
  "type": "mermaid",
  "aspectRatio": "16:9",
  "theme": "blue"
}

// 生成时序图
{
  "description": "API 调用时序：用户发送请求到网关，网关转发到认证服务验证，验证通过后转发到业务服务，业务服务查询数据库，返回结果",
  "type": "mermaid",
  "aspectRatio": "16:9",
  "theme": "green"
}

// 生成饼图
{
  "description": "编程语言使用占比：JavaScript 35%，Python 28%，Java 20%，Go 10%，其他 7%",
  "type": "mermaid",
  "aspectRatio": "4:3",
  "theme": "orange"
}

// 生成时间轴
{
  "description": "产品发展历程：2020年创立，2021年上线1.0版本，2022年用户破百万，2023年完成B轮融资",
  "type": "mermaid",
  "aspectRatio": "16:9",
  "theme": "purple"
}

更多 Mermaid 图表类型和使用说明，请参考 MERMAID_FEATURE.md。

设计风格

参考 Notion、Linear、Stripe 文档等平台的高质量配图：

✅ 极简主义：纯白或浅灰背景，无渐变
✅ 大尺寸内容：内容占据 70-80% 画面
✅ 图标优先：使用 Iconify 图标（48-64px）
✅ 清晰排版：标题 36-48px，正文 18-24px
✅ 单色点缀：仅使用主题色作为强调色
✅ 专业优雅：适合技术文章配图

输出

生成的图片默认保存在项目的 output/ 目录中（可通过 outputDir 参数自定义），文件名格式：

picture_2025-10-20T12-30-45-123Z.png

图片特点：

PNG 格式
2倍分辨率（高清）
适合直接用于文章发布

开发

# 开发模式（自动重新编译）
npm run dev

# 手动编译
npm run build

# 启动服务
npm start

目录结构

better-picture-mcp/
├── src/
│   ├── index.ts              # MCP 服务器入口
│   ├── tools/
│   │   └── generatePicture.ts # 主要工具实现
│   ├── services/
│   │   ├── htmlGenerator.ts   # HTML 生成服务（支持插图和 Mermaid）
│   │   └── screenshotter.ts   # 截图服务
│   ├── prompts/
│   │   ├── templatePrompt.ts  # 模板系统提示词
│   │   └── mermaidPrompt.ts   # Mermaid 提示词模板
│   ├── templates/             # React 模板系统
│   │   ├── layouts/           # 11 种布局组件
│   │   ├── components/        # 可复用 UI 组件
│   │   └── utils/             # 工具函数
│   └── types.ts               # TypeScript 类型定义
├── assets/
│   ├── libs/                  # 本地资源库（备用）
│   │   ├── mermaid.min.js     # Mermaid.js 库
│   │   ├── chart.xkcd.min.js  # chart.xkcd 库
│   │   ├── iconify.min.js     # Iconify 库
│   │   ├── tailwind.min.css   # Tailwind CSS
│   │   └── styles.css         # 自定义样式
│   └── icon-lists/            # Solar 图标列表
├── examples/                  # 示例图片
├── output/                    # 默认输出目录
├── dist/                      # 编译后的代码
└── package.json               # 项目配置

许可证

MIT

贡献

欢迎提交 Issue 和 Pull Request！

技术细节

资源加载方式

默认使用 CDN 外链方式加载库（Tailwind CSS、chart.xkcd、Iconify 等），减少 HTML 文件体积。也支持内联方式（通过 ASSET_MODE=inline 环境变量切换）。

图标系统

使用 Iconify 加载 Solar 双色图标集，提供丰富的图标选择。所有图标都有自动回退机制，确保渲染稳定。

常见问题

没有 Chrome 怎么办？

工具会优先使用系统已安装的 Chrome。如果没有找到，Puppeteer 会自动下载一个 Chrome 浏览器（首次使用时需要网络连接）。

如何调整图标？

图标使用 Iconify 的 Solar 双色图标集，现代简约风格。可以在 icones.js.org 浏览所有可用的 Solar 图标。

如何自定义配色？

提供了 6 种预设莫兰迪色系主题（orange/blue/green/purple/pink/grayscale），都使用纯白背景 + 主题色点缀的简约风格，色调柔和优雅。

字体在某些环境下显示不正常？

本工具采用了多重字体加载策略，确保在任何环境都能正常显示：

优先加载 Google Fonts（Noto Sans/Serif 系列）- 网络正常时使用
备选国内 CDN 镜像（fonts.loli.net）- Google Fonts 不可用时自动切换
优质系统字体降级（PingFang SC、Microsoft YaHei 等）- 完全离线时使用

即使在无网络环境或国内服务器上，也能保证字体美观。详见 FONT_OPTIMIZATION.md。

致谢

Mermaid.js - 专业图表库
chart.xkcd - 手绘风格图表库
Iconify - 统一图标框架
Tailwind CSS - 现代 CSS 框架
Puppeteer - 截图引擎
OpenRouter - AI 模型路由服务