TimeVerse Agnes ImageGen MCP

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

---

📋 概述

timeverse-agnes-imggen-mcp 是一个基于 Model Context Protocol (MCP) 标准的图片生成服务。它封装了 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（免费注册获取）

安装

# 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 .

配置

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

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

运行

# 标准模式（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 许可证

---

🧪 测试

# 安装开发依赖
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 是我们自研的 AI 客户端，原生支持 MCP 协议，可一键接入本服务。

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

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

{
  "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 版本，可显式指定：

{
  "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 配置文件中添加：

{
  "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：

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

---

🧑‍💻 开发指南

代码风格

# 代码检查
ruff check src/

# 类型检查
mypy src/

发布

# 构建
python -m build

# 发布到 PyPI
twine upload dist/*

---

📄 许可证

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

---

🙏 致谢

• Agnes AI - 提供强大的图片生成 API
• MCP Protocol - 标准化的 AI 工具协议
• TimeVerse Studio - 项目维护