Skip to main content
Glama
README.md
# Agnes 2.5 Flash MCP Server 🚀

<div align="center">
  <p>一个 Model Context Protocol (MCP) 服务器,将 Agnes AI 最新发布的 2.5-flash 图像与视频生成模型无缝集成到您最爱的 AI IDE 中。</p>
  <p>
    <a href="https://pypi.org/project/agnes-2.5-flash-mcp/"><img src="https://img.shields.io/pypi/v/agnes-2.5-flash-mcp.svg" alt="PyPI version"></a>
    <a href="https://www.python.org/downloads/release/python-3100/"><img src="https://img.shields.io/badge/Python-%E2%89%A53.10-blue.svg" alt="Python 3.10+"></a>
    <a href="https://github.com/JasonOracle/agnes-2.5-flash-mcp/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License"></a>
    <img src="https://img.shields.io/badge/Protocol-MCP_stdio-purple.svg" alt="MCP Protocol">
  </p>
  <p><strong>中文说明</strong> | <a href="README_en.md">English</a></p>
</div>

---

## 🌟 工程亮点 (致面试官)

虽然 Agnes 提供了非常优秀的免费图像和视频生成模型(`agnes-image-2.5-flash` / `agnes-video-2.5-flash`),但开发者在 IDE 和网页之间频繁切换上下文非常打断心流。最初,这只是为了在 Opencode 中免去切网页烦恼而写的自用工具,现已正式发布至 PyPI,任何开发者均可直接安装,将 AI 生成能力一键接入自己的 Agentic IDE(如 Opencode、Claude Desktop、Windsurf 等)。

**核心技术决策与实现:**
1. **彻底解决客户端超时痛点 (Robust Async Workflow)**:由于视频生成通常耗时数分钟,极易导致 Opencode/Claude 等 MCP 客户端的标准请求超时。为此,我设计了异步的任务轮询系统 (`create_video` → `query_video`),允许 Agent 非阻塞地检查进度,保证了长耗时任务的稳定性。
2. **前置强校验与防御性编程 (Strict Parameter Validation)**:在本地层面对请求参数进行 Flash 强校验(例如:强制 `720P` 分辨率,校验图文音附件数量等)。这能将无效请求在发起网络调用前瞬间拦截,既降低了网络延迟,又避免了无意义的 API 额度消耗。
3. **自然语言无缝路由 (Intelligent Intent Routing)**:在工具描述(Description)设计中,深度优化了中英双语的触发词(如“生一张图”、“draw a cyberpunk city”)。LLM 能够根据上下文自动推断用户意图,精准路由到正确的工具函数,完全免去了繁杂的 Prompt 设定。
4. **标准化与兼容性 (Plug-and-Play Design)**:完全遵循官方的 MCP `stdio` 传输层规范,实现即插即用,兼容市面上绝大多数支持 MCP 的智能客户端。

---

## 🚀 支持的模型与端点

> **注意:** 本项目为 2.5-flash 专版。如果您需要 2.0/2.1 或 `agnes-video-v2.0` 的支持,请使用社区版的 `agnes-mcp`。

- **图像生成**: `agnes-image-2.5-flash` 模型(接口:`POST /v1/images/generations`)
- **视频生成**: `agnes-video-2.5-flash` 模型(接口:`POST /v1/videos` & `GET /agnesapi`,尺寸固定为 `720P`)

## 📦 安装说明

```bash
# 通过 pip 安装
pip install agnes-2.5-flash-mcp

# 或从源码安装
git clone https://github.com/JasonOracle/agnes-2.5-flash-mcp.git
cd agnes-2.5-flash-mcp
pip install -e .
```

*要求 Python ≥ 3.10.*

## 🔑 配置说明 (API Key)

API Key 解析优先级:
`工具调用参数` > `MCP 环境变量 AGNES_API_KEY` > `系统环境变量` > `.env` 文件。

**推荐方式:** 直接在您的 MCP 客户端配置中设置,避免将 Key 提交到代码库。

```json
{
  "mcpServers": {
    "agnes-2.5-flash-mcp": {
      "command": "agnes-2.5-flash-mcp",
      "args": [],
      "env": {
        "AGNES_API_KEY": "您的_API_KEY"
      }
    }
  }
}
```

> **代理配置:** 如果 `ALL_PROXY=socks5://...` 导致 `httpx` 报错,请将 `ALL_PROXY` 留空,或使用 HTTP 代理 `HTTP_PROXY=http://127.0.0.1:10808`。或者安装 socks 支持:`pip install "httpx[socks]"`。

## 🔌 IDE 接入指引

### Cursor / Claude Desktop
将以下内容添加到您的 `.cursor/mcp.json` 或 `claude_desktop_config.json` 中:

```json
{
  "mcpServers": {
    "agnes-2.5-flash-mcp": {
      "command": "agnes-2.5-flash-mcp",
      "env": { "AGNES_API_KEY": "YOUR_KEY" }
    }
  }
}
```
*(如果不使用 pip 安装:请使用 `command: "python"`, `args: ["-m", "agnes_2_5_flash_mcp.server"]`, 并指定 `cwd` 目录)*

### Opencode
请参考项目中的 `opencode.json.example` 文件。

## 🛠️ 工具参考 (Tools)

| 工具名称 | 功能描述 | 返回格式 |
|---|---|---|
| `generate_image` | 文生图、图生图、图像合成。<br>*(返回 URL,可选保存至本地)* | `{ url, size, ratio, saved_to }` 或 `{ b64_json, ... }` |
| `create_video` | **(推荐)** 异步创建视频生成任务。 | `{ video_id, task_id, status }` |
| `query_video` | 根据 `video_id` 轮询视频进度及结果。 | `{ status, progress, video_url?, error? }` |
| `generate_video` | *(兼容)* 同步阻塞式生成(仅限短视频,可能触发超时)。 | `{ video_url, video_id, ... }` |

### 🖼️ 图像约束 (默认:`2K` + `16:9`)
- **分辨率 (Size)**: `1K` (快速) / `2K` (默认, ≈ 2624x1472) / `3K` / `4K` (最大)
- **比例 (Ratio)**: `16:9` / `1:1` / `9:16` / `3:4` / `4:3` / `2:3` / `3:2` / `21:9`
- **能力**: 传入 `images` 参数(URL 或 Data URI)可进行图生图/图像合成,省略则为纯文生图。

### 🎥 视频约束 (本地强校验)
- **尺寸 (Size)**: 固定为 `720P`。
- **时长 (Duration)**: `"4"` 至 `"12"` 秒(默认 `"5"`)。
- **比例 (Ratio)**: `16:9` (默认) / `21:9` / `4:3` / `1:1` / `3:4` / `9:16`。
- **校验**: 采用严格校验逻辑(如:文本模式禁止包含媒体附件,关键帧模式首尾帧必须 ≥ 1 等)。

## 💬 使用示例 (直接对 Agent 说)

- *"用 `generate_image` 生成一张 2K 16:9 的赛博朋克城市夜景壁纸。"*
- *"把这张图 (URL) 改成雨夜霓虹风格,保持构图,尺寸用 2K。"*
- *"用 `create_video` 生成 5 秒 16:9 的未来城市街道视频,然后用 `query_video` 帮我轮询结果。"*

## 🧪 本地测试

测试套件 (`tests/test_validation.py`) 是纯本地校验测试,不会产生任何 API 调用计费。
```bash
python -m pytest tests -q
```

TDQS

A3.8/5.0

Scored across 4 tools

Disambiguation3/5

query_video and generate_image are clearly distinct, but create_video and generate_video describe the same core operation with different execution modes. The descriptions help differentiate them, but an agent could still easily pick the wrong one.

Naming Consistency3/5

All names follow a snake_case verb_noun pattern, but the verbs are inconsistent: query, generate, create, generate. The create_video vs generate_video pair is especially confusing since they are near-synonyms for the same capability.

Tool Count4/5

Four tools is a reasonable size for an image/video generation server. The only slight issue is that generate_video is a redundant sync variant of create_video, but it serves a compatibility purpose.

Completeness4/5

The core image generation and video creation lifecycles are covered: generate image, create video asynchronously, query status, and sync wait. Minor gaps like cancellation or image task polling are not blocking for the apparent domain.

Maintenance

ActivityStale
ResponsivenessNo recent community issues