jhch-poster 0.2.1

Add your description here

jhch-poster

一个基于 MCP (Model Context Protocol) 的海报生成服务器，提供模板管理和样式选择功能。

功能特性

• 模板管理: 提供 5 种精美海报模板
• 样式选择: 支持多种风格 (modern, minimal, bold, elegant, playful)
• MCP 协议: 基于 Model Context Protocol 标准构建
• Stdio 传输: 使用标准输入输出与 MCP 客户端通信

安装

环境要求

• Python >= 3.11
• uv (推荐)

使用 uv 安装 (推荐)

# 克隆项目
git clone <repository-url>
cd poster

# 创建虚拟环境并安装依赖
uv venv
uv pip install -e .

# 或使用 uv run 直接运行 (无需手动激活环境)
uv run jhch-poster

使用 pip 安装

# 克隆项目
git clone <repository-url>
cd poster

# 安装依赖
pip install -e .

使用方法

启动服务器

# 使用命令行入口点
jhch-poster

# 或直接运行 Python 模块
python -m jhch_poster.server

服务器使用 stdio 传输方式，需要通过 MCP 客户端调用。

MCP 客户端配置

Claude Desktop 配置

在 ~/Library/Application Support/Claude/claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "poster": {
      "command": "uvx",
      "args": ["jhch-poster"]
    }
  }
}

或使用本地 Python：

{
  "mcpServers": {
    "poster": {
      "command": "python",
      "args": ["-m", "jhch_poster.server"]
    }
  }
}

Windsurf/Cursor 配置

在 .windsurfrc 或 .cursorrc 中添加：

{
  "mcpServers": {
    "poster": {
      "command": "uvx",
      "args": ["jhch-poster"]
    }
  }
}

使用示例

连接 MCP 客户端后，可以直接调用工具：

列出海报样式 -> ["modern", "minimal", "bold", "elegant", "playful"]
获取 modern 样式的模板 -> 返回 HTML 模板内容

调试 MCP 工具

使用 MCP Inspector 调试服务器：

# 方式 1: 使用 npx 直接运行 (无需安装)
npx @modelcontextprotocol/inspector python -m jhch_poster.server

# 方式 2: 如果已通过 pip 安装
npx @modelcontextprotocol/inspector jhch-poster

# 方式 3: 使用 uvx 运行
npx @modelcontextprotocol/inspector uvx jhch-poster

Inspector 会启动一个 Web 界面 (默认 http://localhost:5173 )，可以：

• 查看可用工具和资源的列表
• 测试工具调用和参数
• 查看请求/响应详情
• 实时监控通信过程

MCP 工具

服务器提供以下 MCP 工具：

list_styles()

列出所有可用的海报样式。

返回: 样式名称列表

["modern", "minimal", "bold", "elegant", "playful"]

get_style_id(style: str)

根据样式名称获取对应的模板 ID。

参数:

• style: 样式名称

返回: 模板 ID

get_template(id: str = "")

获取指定 ID 的模板内容，如果未找到则随机返回一个模板。

参数:

• id: 模板 ID (可选)，如 "1", "2" 等

返回: HTML 模板内容字符串

MCP 资源

poster://templates

获取所有可用模板的元数据信息。

返回: JSON 格式的模板列表，包含 id、name、style 和 file 信息。

项目结构

poster/
├── jhch_poster/
│   ├── __init__.py
│   ├── server.py          # MCP 服务器主文件
│   └── template/
│       ├── 1.html         # 模板 1
│       ├── 2.html         # 模板 2
│       ├── 3.html         # 模板 3
│       ├── 4.html         # 模板 4
│       ├── 5.html         # 模板 5
│       └── templates.json   # 模板元数据
├── main.py
├── pyproject.toml
└── README.md

配置

服务器配置位于 pyproject.toml：

• 传输方式: stdio (标准输入输出)

依赖管理 (uv)

本项目推荐使用 uv 进行依赖管理。

常用 uv 命令

# 添加依赖
uv pip install <package>

# 添加开发依赖
uv pip install --dev <package>

# 同步依赖 (根据 pyproject.toml)
uv pip sync

# 更新依赖
uv pip install -U <package>

# 生成 lock 文件
uv pip compile pyproject.toml -o requirements.lock

发布到 PyPI

使用 uv 发布 (推荐)

# 1. 构建分发包
uv build

# 2. 检查构建结果
uv publish --check

# 3. 上传到 PyPI 测试环境
uv publish --index testpypi

# 4. 上传到正式 PyPI
uv publish

使用 hatch 发布

# 1. 安装 hatch
uv pip install hatch

# 2. 构建并发布
hatch build
hatch publish

版本管理

在发布前更新版本号 (pyproject.toml):

[project]
version = "0.1.7"  # 更新此处

遵循 语义化版本 规范:

• MAJOR.MINOR.PATCH
• 如: 0.1.6 → 0.1.7 (修复 bug)
• 如: 0.1.6 → 0.2.0 (新增功能)
• 如: 0.1.6 → 1.0.0 (破坏性变更)

许可证

MIT License