Metadata-Version: 2.4
Name: timeverse-agnes-imggen-mcp
Version: 0.1.1
Summary: Agnes Image 2.0 Flash MCP Server - 基于 MCP 标准的图片生成服务
Author: TimeVerse Studio
License: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pre-commit>=3.6.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# TimeVerse Agnes ImageGen MCP

> 🎨 **基于 MCP 标准的 Agnes Image 2.0 Flash 图片生成服务**

[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue)](https://www.python.org/)
[![MCP](https://img.shields.io/badge/MCP-1.0+-green)](https://modelcontextprotocol.io/)
[![License MIT](https://img.shields.io/badge/License-MIT-yellow)](LICENSE)

---

## 📋 概述

`timeverse-agnes-imggen-mcp` 是一个基于 **[Model Context Protocol (MCP)](https://modelcontextprotocol.io/)** 标准的图片生成服务。它封装了 **Agnes Image 2.0 Flash** 的 API，将强大的 AI 图片生成能力以标准化的 MCP Tool 形式提供给 AI 客户端（如 Claude Desktop）调用。

### 核心能力

- ✨ **文生图（Text-to-Image）**：根据文本描述生成高质量图片
- 🖼️ **图生图（Image-to-Image）**：基于参考图片生成新图片
- 🚀 **高速生成**：基于 Flash 模型，生成速度快
- 🔌 **即插即用**：遵循 MCP 标准，可被任何 MCP 客户端直接调用

---

## 🚀 快速开始

### 前置条件

- Python 3.10+
- [Agnes API Key](https://agnes-ai.com/)（免费注册获取）

### 安装

```bash
# 1. 克隆项目
cd timeverse-agnes-imggen-mcp

# 2. 创建虚拟环境
python -m venv .venv
source .venv/bin/activate  # macOS/Linux
# 或
.venv\Scripts\activate  # Windows

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

### 配置

```bash
# 复制环境变量模板
cp .env.example .env

# 编辑 .env 文件，填入你的 API Key
# AGNES_API_KEY=your_api_key_here
```

### 运行

```bash
# 标准模式（stdio）
python -m timeverse_agnes_imggen_mcp.server

# 或使用项目入口点
timeverse-agnes-imggen
```

---

## 🔧 配置说明

| 环境变量 | 说明 | 默认值 |
|---------|------|--------|
| `AGNES_API_KEY` | Agnes API Key（必需） | - |
| `AGNES_API_BASE_URL` | API 基础地址 | `https://apihub.agnes-ai.com/v1` |
| `AGNES_MODEL` | 模型名称 | `agnes-image-2.0-flash` |
| `HTTP_TIMEOUT` | HTTP 超时时间（秒） | `120` |
| `MAX_RETRIES` | 最大重试次数 | `3` |
| `DEBUG` | 调试模式 | `false` |

---

## 🛠️ MCP Tools

该 MCP Server 提供以下 Tool：

### 1. `generate_image` - 文生图

根据文本描述生成图片。

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `prompt` | string | ✅ | 图片描述文本 |
| `negative_prompt` | string | ❌ | 负面提示词 |
| `size` | string | ❌ | 尺寸：`1024x1024`/`1280x720`/`720x1280`/`1920x1080` |
| `quality` | string | ❌ | 质量：`standard`/`hd` |
| `n` | integer | ❌ | 生成数量 1-4 |
| `prompt_enhance` | boolean | ❌ | 提示词增强 |
| `seed` | integer | ❌ | 随机种子 |

### 2. `generate_image_from_image` - 图生图

基于参考图片生成新图片。

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `prompt` | string | ✅ | 图片描述文本 |
| `image_url` | string | ✅ | 参考图片 URL |
| `image_weight` | number | ❌ | 参考权重 0.0-2.0 |
| `size` | string | ❌ | 图片尺寸 |
| `n` | integer | ❌ | 生成数量 1-4 |
| `seed` | integer | ❌ | 随机种子 |

### 3. `ping` - 健康检查

检查 MCP Server 和 Agnes API 是否正常运行。

---

## 📂 项目结构

```
timeverse-agnes-imggen-mcp/
├── src/
│   └── timeverse_agnes_imggen_mcp/
│       ├── __init__.py      # 包入口
│       ├── config.py        # 配置管理
│       ├── models.py        # 数据模型
│       ├── agnes_client.py  # API 客户端
│       └── server.py        # MCP Server
├── tests/                   # 测试
├── docs/                    # 文档
├── .env.example             # 环境变量模板
├── pyproject.toml           # 项目配置
├── README.md                # 本文档
└── LICENSE                  # MIT 许可证
```

---

## 🧪 测试

```bash
# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest

# 带覆盖率
pytest --cov=timeverse_agnes_imggen_mcp

# 查看测试覆盖率报告
pytest --cov=timeverse_agnes_imggen_mcp --cov-report=html
```

---

## 🪐 配置 TimeVerse Studio（自研 AI 客户端）

[TimeVerse Studio](https://github.com/) 是我们自研的 AI 客户端，原生支持 MCP 协议，可一键接入本服务。

### 方式一：uvx 直接运行（推荐）

无需本地安装，使用 `uvx` 直接拉取并运行最新版本：

```json
{
  "mcpServers": {
    "timeverse-agnes-imggen": {
      "command": "uvx",
      "args": [
        "--from",
        "timeverse-agnes-imggen-mcp",
        "timeverse-agnes-imggen"
      ],
      "env": {
        "AGNES_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

> 💡 首次运行 `uvx` 会自动创建临时虚拟环境并安装依赖，后续调用秒级启动。
> 如需锁定版本，可将包名改为 `timeverse-agnes-imggen-mcp==x.y.z`（例如 `0.1.0`）。

### 方式二：指定 Python 解释器 + uvx

如果系统中有多个 Python 版本，可显式指定：

```json
{
  "mcpServers": {
    "timeverse-agnes-imggen": {
      "command": "uvx",
      "args": [
        "--python",
        "3.11",
        "--from",
        "timeverse-agnes-imggen-mcp",
        "timeverse-agnes-imggen"
      ],
      "env": {
        "AGNES_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

### 方式三：源码本地运行

进入 TimeVerse Studio 设置 → MCP 服务器 → 添加服务器，填写：

- **名称**: `timeverse-agnes-imggen`
- **命令**: `uvx`
- **参数**: `--from timeverse-agnes-imggen-mcp timeverse-agnes-imggen`
- **环境变量**: `AGNES_API_KEY=your_api_key_here`

保存后点击「连接测试」，状态显示 `connected` 即配置成功。

---

## 🔌 配置 MCP 客户端

### Claude Desktop

在 Claude Desktop 的 MCP 配置文件中添加：

```json
{
  "mcpServers": {
    "timeverse-agnes-imggen": {
      "command": "python",
      "args": ["-m", "timeverse_agnes_imggen_mcp.server"],
      "env": {
        "AGNES_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

---

## 📊 API 参考

底层 API 基于 [Agnes Image API](https://agnes-ai.com/zh-Hans/docs/agnes-image-20-flash)：

- **Endpoint**: `POST https://apihub.agnes-ai.com/v1/images/generations`
- **认证**: Bearer Token
- **模型**: `agnes-image-2.0-flash`

---

## 🧑‍💻 开发指南

### 代码风格

```bash
# 代码检查
ruff check src/

# 类型检查
mypy src/
```

### 发布

```bash
# 构建
python -m build

# 发布到 PyPI
twine upload dist/*
```

---

## 📄 许可证

本项目基于 MIT 许可证开源 - 详见 [LICENSE](LICENSE) 文件。

---

## 🙏 致谢

- [Agnes AI](https://agnes-ai.com/) - 提供强大的图片生成 API
- [MCP Protocol](https://modelcontextprotocol.io/) - 标准化的 AI 工具协议
- [TimeVerse Studio](https://github.com/TimeVerseStudio) - 项目维护
