Metadata-Version: 2.4
Name: jhch-poster
Version: 0.3.0
Summary: Add your description here
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: mcp[cli]>=1.27.0
Requires-Dist: requests>=2.31.0

# jhch-poster

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

## 功能特性

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

## 安装

### 环境要求

- Python >= 3.11
- [uv](https://github.com/astral-sh/uv) (推荐)

### 使用 uv 安装 (推荐)

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

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

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

### 使用 pip 安装

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

# 安装依赖
pip install -e .
```

## 使用方法

### 启动服务器

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

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

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

### MCP 客户端配置

#### Claude Desktop 配置

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

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

或使用本地 Python：

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

#### Windsurf/Cursor 配置

在 `.windsurfrc` 或 `.cursorrc` 中添加：

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

### 使用示例

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

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

### 调试 MCP 工具

使用 [MCP Inspector](https://github.com/modelcontextprotocol/inspector) 调试服务器：

```bash
# 方式 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()`
列出所有可用的海报样式。

**返回**: 样式名称列表

```python
["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](https://github.com/astral-sh/uv) 进行依赖管理。

### 常用 uv 命令

```bash
# 添加依赖
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 发布 (推荐)

```bash
# 1. 构建分发包
uv build

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

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

# 4. 上传到正式 PyPI
uv publish
```

### 使用 hatch 发布

```bash
# 1. 安装 hatch
uv pip install hatch

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

### 版本管理

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

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

遵循 [语义化版本](https://semver.org/lang/zh-CN/) 规范:
- `MAJOR.MINOR.PATCH`
- 如: `0.1.6` → `0.1.7` (修复 bug)
- 如: `0.1.6` → `0.2.0` (新增功能)
- 如: `0.1.6` → `1.0.0` (破坏性变更)

## 许可证

MIT License
