terrychadesignmcp

Terry角色设计MCP服务器

一个MCP服务器，使用谷歌的Nano Banana模型（Vertex AI）生成一致的角色参考图像集。设计用于在视频/图像制作流程中保持视觉一致性。

结果

配置文件一致性 --相同的角色，不同的角度和服装，由基于锚点的生成+YAML配置文件维护。

目录集成 --从2698个真实产品中推荐服装，生成带有产品元数据的试穿图片。

v0.5.0的新增功能

• SD表情符号表系统: generate_chat_emoji 现在在一个API调用中生成一个完整的4x4（或3x3回退）精灵表，而不是一个一个的emoji
• 三层表达系统：合并 expression_set 预设+ special_count 额外费用+ custom_expressions 覆盖
• 组合套装：使用 + 符号（例如。 "basic_16+reaction_8")合并表达式集
• 7平台出口：从表单中导出单个表情符号（Telegram、Discord、LINE、KakaoTalk、Slack、WhatsApp、Universal）+可选ICO格式
• 表情符号动画新 generate_animated_emoji 该工具从数据库中现有的表情符号创建GIF和动画WebP-不需要API调用
• 数据库跟踪: emoji_sets 和 emoji_items 表情符号世代完整历史表
• 表情符号_词典.md：所有内置表达式集及其SD艺术提示的精选参考
• 总共21个工具 （比v0.4.1中的19有所增加）

v0.4.1的新增功能

• 模块化架构：服务器分为4个重点模块（Server.py、image_io.py、generation.py、catalog.py）
• 输出模式: basic （3-shot）和 face_angles （3-shot）预设，生成速度更快
• 摄像头预设：照片级真实感（肖像、时尚、街头、社论、自拍）和动画（anime_standard、anime_dramatic、chibi、game_art、webtoon）预设
• 角色简介：基于YAML的IP管理，带有5个CRUD工具和内置的Siwol/Claudie配置文件
• 产品试穿: suggest_outfits + try_on_product 时尚目录集成工具
• 设计历史数据库：自动记录所有世代，包括概念/系列组织、评级、搜索
• 总共19个工具 （比v0.3.1中的8有所增加）

特性

• 输出模式：预设镜头选择(full_sheet, basic, face_angles)灵活的发电范围
• 摄像头预设：10个预设，涵盖照片级真实感和动画风格
• 角色简介：基于YAML的配置文件，用于IP管理和设计一致性
• 产品试穿：从目录中生成穿着真实产品的角色图像
• 设计历史：通过搜索、评级和概念分组自动记录所有世代
• 7角参考表：全身（前、左、右、后）+面部特写（左、前、右）
• 复合板：自动从所有镜头生成单个组合参考图像
• 基于锚点的一致性：第一张图片作为所有后续镜头的视觉参考
• 丰富的字符输入：描述、服装、发型、配饰、妆容、特色
• 多种艺术风格：动漫、写实、3D渲染、水彩、概念艺术等
• 其他姿势：使用现有角色引用生成自定义姿势/场景
• 放置样品表：预定义的姿势类别（日常生活、动作、情感、社交），带有自动网格复合
• SD表情符号表系统：基于纸张的表情符号生成（4x4网格，3x3后退），具有3层表达系统和7平台导出
• 表情符号动画：GIF+来自现有表情符号的动态WebP-无API调用，来自DB的即时
• 表情符号数据库：使用manifest.json全面跟踪表情符号集和单个项目
• 提示词典：精心策划的字符设计提示参考词汇（13类）
• 干净的图像输出：防覆盖提示可防止文本标签、色样和注释插图
• 安全过滤器重试：当安全过滤器阻止生成时，会自动重试，并显示软化的提示
• 成本估算：用于预算API费用的生成前成本计算器

安装

pip install -r requirements.txt

需求

• Python 3.10+
• 启用Vertex AI的谷歌云项目（或Gemini API密钥）
• fastmcp>=2.0.0, google-genai>=1.0.0, Pillow>=10.0.0, PyYAML>=6.0

配置

克劳德代码(~/.claude/settings.json)

{
  "mcpServers": {
    "terrycha-design": {
      "command": "python3",
      "args": ["/path/to/terrychadesignmcp/server.py"],
      "env": {
        "GOOGLE_CLOUD_PROJECT": "your-project-id",
        "GOOGLE_CLOUD_LOCATION": "global",
        "GOOGLE_GENAI_USE_VERTEXAI": "true",
        "TERRYCHA_DESIGN_OUTPUT_DIR": "/path/to/output",
        "TERRYCHA_DESIGN_PROFILES_DIR": "/path/to/profiles",
        "TERRYCHA_DESIGN_DB": "/path/to/design_history.db",
        "PRODUCT_CATALOG_DB": "/path/to/catalog.db"
      }
    }
  }
}

克劳德桌面(claude_desktop_config.json)

{
  "mcpServers": {
    "terrycha-design": {
      "command": "python3",
      "args": ["/path/to/terrychadesignmcp/server.py"],
      "env": {
        "GOOGLE_CLOUD_PROJECT": "your-project-id",
        "GOOGLE_GENAI_USE_VERTEXAI": "true"
      }
    }
  }
}

Gemini API密钥模式

集 GOOGLE_GENAI_USE_VERTEXAI=false 并提供 GEMINI_API_KEY 相反。

工具（共21个）

design_character

生成一份完整的角色参考表（默认6个镜头，7个带有 both_sides=True).

核心输入：

扩展输入：

生成选项：

例子：

design_character(
    character_name="Luna",
    character_description="A young East Asian woman with fair skin, almond-shaped brown eyes, high cheekbones",
    style="anime",
    outfit_description="White sailor uniform with navy blue collar, pleated navy skirt, brown loafers",
    hair_description="Long straight black hair reaching mid-back, blunt bangs across forehead",
    accessories="Small silver stud earrings, thin red ribbon tied in hair",
    makeup_description="Natural look with soft pink lip gloss, subtle mascara",
    distinguishing_features="Small beauty mark under left eye",
    expression="gentle smile",
    age_range="teen",
    body_type="slim",
    temperature=0.6,
    seed=42,
    image_size="2K"
)

配置文件驱动生成：

design_character(
    character_name="Siwol",
    profile="siwol",
    outfit_description="White oversized hoodie and denim shorts",
    concept="casual_spring"
)

add_character_pose

使用现有参考图像生成其他姿势。

add_character_pose(
    prompt="The character sitting at a cafe table drinking tea, three-quarter angle, warm lighting",
    reference_images=[
        "/path/to/Luna_20260302/full_body_front_....jpg",
        "/path/to/Luna_20260302/face_front_....jpg"
    ],
    character_name="Luna",
    style="anime",
    aspect_ratio="16:9"
)

generate_pose_sheet

以较小的尺寸（默认512px）生成具有预定义姿势的姿势示例表。

核心输入：

姿势选择：

姿势类别：

违约： ["daily_life", "emotion"] （12个姿势）。

例子：

generate_pose_sheet(
    reference_images=[
        "/path/to/Luna_20260302/full_body_front_....jpg",
        "/path/to/Luna_20260302/face_front_....jpg"
    ],
    character_name="Luna",
    style="anime",
    categories=["daily_life", "social"],
    temperature=0.6,
    seed=42
)

姿势网格布局：

+----------+----------+----------+----------+
| sitting  | walking  | waving   | reading  |
+----------+----------+----------+----------+
| drinking | phone    | peace    | thumbs   |
+----------+----------+----------+----------+
| arms_x   | kiss     | salute   | fist     |
+----------+----------+----------+----------+
  labels     labels     labels     labels

generate_chat_emoji

使用基于表单的管道生成SD/chibi字符聊天表情符号贴纸。在单个API调用中生成完整的4x4精灵表，然后将其分割为单独的表情符号并导出为特定于平台的格式。

看 表情符号_词典.md 查看内置表达式及其SD艺术提示的完整列表。

核心输入：

表达式选择（三层系统）：

表达式集：

使用 + 组合集合： "basic_16+reaction_8" → 24 表达式（生成多个工作表）。

工作表生成：

平台导出：

平台尺寸：

输出：

• 原始表情符号表（PNG、4x4或3x3网格）
• 单个表情符号（从纸张上切片，每个平台文件夹）
• manifest.json -集合中所有表情符号的元数据
• 数据库条目 emoji_sets + emoji_items 表格

例子：

generate_chat_emoji(
    reference_images=[
        "/path/to/Luna_20260302/full_body_front_....jpg",
        "/path/to/Luna_20260302/face_front_....jpg"
    ],
    character_name="Luna",
    expression_set="basic_16+reaction_8",
    special_count=2,
    grid_size="4x4",
    platforms=["telegram", "discord"],
    include_ico=True,
    concept="spring_emoji_set",
    style="anime",
    temperature=0.6,
    seed=42
)

generate_animated_emoji

从数据库中现有的表情符号创建动态GIF和WebP文件。没有进行API调用-使用已经生成的表情符号图像。

核心输入：

动画选项：

输出：

DB条目已添加到 emoji_animations 桌子。

例子：

generate_animated_emoji(
    emoji_keys=["happy", "wink", "excited", "love"],
    character_name="Luna",
    frame_delay_ms=150,
    mode="bounce",
    output_format="all"
)

get_prompt_dictionary

获取按类别组织的精选描述性短语，用于构建角色设计提示。

类别（13）： 体型、面部特征、发型、服装、表情、姿势、艺术风格、灯光、相机角度、颜色、配饰、年龄、脚本、背景

# Get category index
get_prompt_dictionary()

# Get specific category
get_prompt_dictionary(category="hair_styles")

看 prompt_dictionary.md 以供人类阅读。

estimate_generation_cost

在运行工具之前估算发电成本。计算映像计数、每个映像的成本和最坏情况下的成本（如果使用了所有重试）。

例子：

estimate_generation_cost(
    tool="generate_chat_emoji",
    model="pro",
    expression_set="basic_16"
)
# Returns: 16 images, ~$2.14, worst case ~$8.58

大致价格（每张图片美元）：

list_character_sheets

列出生成的带有图像计数的字符参考表。

get_design_options

获取所有支持的样式、镜头类型、输出模式、相机预设、模型参数、姿势类别、表情符号表情集、平台规格和推荐设置。

______________________________________________________________________

输出模式

这 output_mode 参数输入 design_character 选择预设拍摄组：

当 shots 如果明确提供，它将覆盖 output_mode.

示例（快速草稿）：

design_character(
    character_name="Luna",
    ...,
    output_mode="basic",
    image_size="1K"
)

______________________________________________________________________

相机预设

使用 camera_preset 参数输入 design_character 应用摄影或动画风格的相机配置。使用 camera_override 调整各个按键。

逼真预设

动画预设

例子：

design_character(
    character_name="Luna",
    ...,
    camera_preset="fashion",
    camera_override={"lighting": "golden hour backlight"}
)

呼叫 get_design_options() 查看每个按键的完整预设配置。

______________________________________________________________________

角色简介

配置文件将完整的字符定义存储在YAML文件中。创建后，将配置文件名称传递给 design_character(profile="name") 自动填充外观、样式和生成默认值。显式参数始终覆盖配置文件值。

配置文件CRUD工具

内置配置文件

配置文件YAML结构

name: luna
appearance:
  character_description: "Young East Asian woman, fair skin, almond-shaped brown eyes"
  hair_description: "Long straight black hair, blunt bangs"
  distinguishing_features: "Small beauty mark under left eye"
style_preferences:
  default_style: "anime"
  camera_preset: "anime_standard"
generation_defaults:
  temperature: 0.6
  seed: 42
  image_size: "2K"
  output_mode: "full_sheet"

基于配置文件的生成

# Auto-fill all appearance/style defaults from profile
design_character(
    character_name="Siwol",
    profile="siwol",
    outfit_description="White tank top and denim mini skirt",
    concept="summer_casual"
)

配置文件目录默认为 profiles/ 在输出目录中。覆盖 TERRYCHA_DESIGN_PROFILES_DIR.

______________________________________________________________________

产品试穿

需要产品目录SQLite数据库（通过设置 PRODUCT_CATALOG_DB env-var，与Atelier时尚商务管道兼容）。

suggest_outfits

根据人物形象和造型理念，建议3套协调的服装。

例子：

suggest_outfits(profile="siwol", concept="street")
# Returns: 3 outfit proposals (A/B/C) with product_id, brand, name, price per item

try_on_product

从目录中生成佩戴角色的真实产品。

\*至少一个 product_id, product_ids，或 product_query 是必需的。

示例（来自suggest_outfits管道）：

try_on_product(
    profile="siwol",
    product_ids=["musinsa_5859187", "musinsa_6051110", "musinsa_6013524"],
    camera_preset="street",
    pose="walking confidently, one hand in jacket pocket",
    background="Hongdae street in Seoul, warm afternoon light",
    concept="street"
)

______________________________________________________________________

设计历史数据库

当满足以下条件时，所有世代都会自动记录在SQLite数据库中 TERRYCHA_DESIGN_DB 已设置。记录包括字符名称、提示快照、输出路径、模型设置和可选评级。

概念

概念将相关世代分组为命名系列（例如“summer_lookbook”、“seasonal_emoji_set”）。

历史记录工具

工作流程示例：

# 1. Create a concept for a campaign
create_concept(name="spring_2026", description="Spring collection lookbook")

# 2. Generate with concept tracking
design_character(
    character_name="Siwol",
    profile="siwol",
    outfit_description="Floral sundress",
    concept="spring_2026"
)

# 3. Search and rate
search_generations(character="Siwol", concept="spring_2026")
rate_generation(generation_id="...", rating=5, notes="Hero shot for campaign")

______________________________________________________________________

射击类型

输出模式： full_sheet （默认，6次拍摄）

输出模式： basic （3次射击）

输出模式： face_angles （3次射击）

可选镜头

复合板布局

在所有拍摄完成后，会自动生成一个参考表图像：

+------------+----------------+----------------+----------------+
| face_left  |                |                |                |
+------------+ full_body_front| full_body_left | full_body_back |
| face_front |    (3:4)       |    (3:4)       |    (3:4)       |
+------------+                |                |                |
| face_right |                |                |                |
+------------+----------------+----------------+----------------+
  labels         labels           labels           labels

随着 both_sides=True, full_body_right 被添加为第四主体列。

basic 和 face_angles 模式会生成一个水平复合行。

输出结构

~/terrycha_design_output/
+-- Luna_20260302_143052/                       /profiles` |角色配置文件目录|
| `TERRYCHA_DESIGN_DB` |（已禁用）|设计历史SQLite数据库的路径|
| `PRODUCT_CATALOG_DB` |（已禁用）|产品目录SQLite数据库的路径|
| `GOOGLE_CLOUD_PROJECT` || GCP项目ID|
| `GOOGLE_CLOUD_LOCATION` | `global` |GCP地区|
| `GOOGLE_GENAI_USE_VERTEXAI` | `true` |使用顶点AI身份验证|
| `GEMINI_API_KEY` || API键（非顶点模式）|

## 干净图像输出（防重叠）

所有提示模板包括 `NO_OVERLAY_INSTRUCTION` 为了防止AI模型在生成的图像上渲染不需要的视觉元素：

- 文本标签和注释（例如，“正常人的耳朵”、“波浪形头发”）
- 调色板样本
- 细节插入/缩放框
- 箭头或详图索引图形

这将自动应用于所有生成工具(`design_character`, `add_character_pose`, `generate_pose_sheet`, `generate_chat_emoji`).无需用户配置。

## 安全过滤器重试

所有生成工具都包括安全过滤块的自动重试：

|参数|默认值|说明|
|-----------|---------|-------------|
| `max_retries` |3|每个映像的最大重试次数（0=不重试）|
| `on_block` |“重试”| `"retry"` =自动重试，提示变软， `"stop"` =立即失败|

当安全过滤器阻止生成时：

- **重试模式**：自动将软化短语附加到提示和重试（最多 `max_retries`)
- **停止模式**：立即失败，并显示明确的错误消息

使用 `estimate_generation_cost` 在运行之前检查最坏情况下的成本（使用了所有重试）。

## 最佳一致性提示

1. **使用固定种子** 在所有镜头中实现最大再现性
1. **较低温度** （0.5-0.8）产生更一致的结果
1. **单色背景** 生成更清晰的参考表
1. **具体说明** 在描述中——包括颜色、材料、图案
1. **分开发型/配饰/妆容** 将所有内容填入专用字段，而不是将所有内容填充到character_description中
1. **使用“专业”模型** 对于生产质量表，“flash”用于快速迭代
1. **使用 `both_sides=True`** 当配饰或特征不对称时（例如，一只耳朵上的耳环）
1. **使用 `get_prompt_dictionary()`** 用于构建描述时的精选参考短语
1. **使用 `generate_pose_sheet`** 之后 `design_character` 快速生成各种姿势变化
1. **使用 `generate_chat_emoji`** 从您的角色创建平台就绪的聊天贴纸
1. **使用 `estimate_generation_cost`** 在大批量操作之前预算API成本
1. **集 `on_block="stop"`** 在测试过程中快速失败，而不是浪费重试时间
1. **避免标签式描述** --使用“鼻子上有雀斑”而不是“特征：雀斑”来防止文字重叠
1. **使用 `output_mode="basic"`** 在提交完整的6页表格之前进行快速草稿
1. **使用角色配置文件** 避免在会话之间重复外观描述
1. **使用 `create_concept`** 将相关世代分组到命名的活动或系列中
1. **使用 `suggest_outfits`** 之前 `try_on_product` 首先探索目录选项

## 评估

### 配置文件与无配置文件一致性

|特性|无配置文件|有配置文件|
|--------|:---:|:---:|
|镜头间的面部一致性|可变|高|
|服装细节准确性|每次呼叫手动| YAML自动|
|头发/配饰持久性|需要复制粘贴|单一来源|
|跨会话一致性|低（提示漂移）|高（YAML锁定）|

### 建议输出→ 试生产流水线

在Windows上测试2026-03-16（catalog.db:2698个产品，8个类别）：

- `suggest_outfits(profile="siwol", concept="street")` → 3 提案（A/B/C），每项4个项目
- `try_on_product(product_ids=[...])` → 3 图像（全身+2个面角）+复合板
- 端到端延迟：约2分钟（3个Gemini API调用）

### 模块架构（v0.5.0）

|模块|责任|
|--------|---------------|
| `server.py` |MCP工具注册，常量|
| `image_io.py` |NAS路径、复合材料、表情符号薄片切片、平台导出|
| `generation.py` |Gemini API，安全重试，表单提示生成器|
| `catalog.py` |产品数据库查询|
| `emoji_sheet.py` |表格生成、网格布局、ICO导出、动画GIF/WebP|

## 路线图

### v0.5.0-SD表情符号工作表系统（完成）

- \[x\] 基于表单的表情符号生成（4x4网格，3x3后退，每张表单单个API调用）
- \[x\] 三层表达系统：基本集+特殊附加+自定义覆盖
- \[x\] 组合表达式集通过 `+` 记号
- \[x\] 7平台导出（Telegram、Discord、LINE、KakaoTalk、Slack、WhatsApp、Universal）+ICO
- \[x\] `generate_animated_emoji` -GIF+动态WebP来自DB表情符号，无API调用
- \[x\] 数据库跟踪(`emoji_sets`, `emoji_items`, `emoji_animations`)
- \[x\] `manifest.json` emoji 集
- \[x\] `emoji_dictionary.md` --表达式引用

### v0.6.0——角色设计工作室图形用户界面

- \[\]PySide6桌面应用程序
- \[\]预设带有视觉预览的选择/比较UI
- \[\]角色配置文件编辑器（拖放，实时预览）
- \[\]产品目录浏览器+试用图库
- \[\]设计历史时间线视图
- \[\]v0.5.0 MCP工具作为后端API

### 待办事项

- \[\]SNS管道（工作室）摄像头_预置集成
- \[x\] 建议输出→ 试生产全E2E流量测试
- \[\]服务器模块化阶段2——将剩余的数据常量移动到专用文件
- \[\]角色关系系统（多角色场景）
- \[\]其他相机预设（电影、水下等）

## 许可证

麻省理工学院

## 作者

泰瑞。金 
合著者：Claudie