内容
# agnes-mcp
一款 [Model Context Protocol](https://modelcontextprotocol.io) 服务器，暴露 **Agnes AI** 的免费模型 — 图片识别、文本转图片、图片转图片、文本转视频、图片转视频和关键帧动画 — 给任何兼容MCP的客户端（Claude Desktop、Cursor等）。
使用 [`rust-mcp-sdk`](https://github.com/rust-mcp-stack/rust-mcp-sdk) 构建，静态编译，支持Docker，零警告。
## 功能
| 工具 | 描述 |
| --- | --- |
| `agnes_image_recognition` | 视觉/图片理解 — 描述、分析和回答关于图片的问题。接受URL、本地文件或base64。可选 `detail`: `low` / `high` / `auto`. |
| `agnes_generate_image` | 文本转图片和图片转图片，使用 `agnes-image-2.1-flash`。参考图片（`image_urls`）接受http(s) URL、**本地文件路径**、`data:` URI或原始base64（本地文件和base64内联编码为`data:` URI）。可选 `enhance_prompt`（在生成前扩展提示）和 `save_to`（下载到本地路径）。 |
| `agnes_generate_video` | 文本转视频、图片转视频、多图片和关键帧动画，使用 `agnes-video-v2.0`。**仅异步**：提交任务并立即返回任务ID。可选 `enhance_prompt`。通过 `agnes_video_status` 轮询结果。 |
| `agnes_video_status` | 检查视频生成任务的状态（单次状态检查，无轮询）。调用周期性直到任务报告 `completed`。可选 `save_to` 下载完成后。 |
## 快速开始
### 1. 配置
生成配置文件（或复制 `config.example.toml`）：
```bash
./agnes-mcp config --output config.toml
```
然后编辑 `config.toml` 并设置您的Agnes API密钥，或通过环境变量 `AGNES_API_KEY` 提供（推荐）：
```bash
export AGNES_API_KEY="sk-..."
```
#### 多个API密钥（轮询负载均衡）
为了提高吞吐量，您可以提供多个Agnes API密钥。请求通过放松的原子计数器均匀分布在所有密钥上（无锁竞争）。
- **TOML**：`api_keys = ["sk-1", "sk-2", "sk-3"]` （在 `[agnes]` 下）
- **环境变量**：`AGNES_API_KEYS="sk-1,sk-2,sk-3"` （逗号分隔）
- **命令行**：`--api-key sk-1 --api-key sk-2 --api-key sk-3` （可重复标志）
所有来源的密钥被合并和去重。单密钥表单（`api_key`，`AGNES_API_KEY`）仍然适用于向后兼容；两种表单可以共存。
#### 重试和冷却（自动密钥故障转移）
当API密钥返回HTTP **429** （速率限制）或 **401/403** （身份验证失败/撤销）时，它会自动冷却并在下一个健康密钥上重试请求：
- **429** → 冷却 `key_rate_limit_cooldown_secs` （默认 **60s** ）
- **401 / 403** → 冷却 `key_cooldown_secs` （默认 **600s** = 10分钟）
其他错误（网络，5xx，其他4xx，JSON解析）**快速失败** — 它们不是由密钥引起的，因此在不同的密钥上重试不会有帮助。通过 `[agnes]` TOML字段 `key_cooldown_secs` / `key_rate_limit_cooldown_secs` 或环境变量 `AGNES_KEY_COOLDOWN_SECS` / `AGNES_KEY_RATE_LIMIT_COOLDOWN_SECS` 进行配置。
#### 视频任务亲和力（重要）
Agnes将每个视频 `task_id` 与创建它的API密钥绑定 — 使用不同的密钥查询被服务器视为可能的 **密钥泄漏** 。该服务器将每个视频状态查询绑定到创建时使用的密钥。因此：
- 在 **会话A** （进程）中创建的视频任务无法从 **会话B** 查询。您将看到：`video task '...' was not created by this server session`.
- 视频状态查询 **不会跨密钥重试** ，即使绑定的密钥处于冷却状态 — 切换密钥会破坏Agnes任务所有权。
- 重启服务器，之前创建的任务ID将变得无法查询（亲和力仅限于进程内）。
### 2. 运行（stdio — 用于MCP客户端）
```bash
./agnes-mcp serve --config config.toml --mode stdio
```
### 3. 运行（HTTP/SSE — 用于网络访问）
```bash
./agnes-mcp serve --config config.toml --mode hybrid --host 0.0.0.0 --port 8080
```
传输模式：`stdio`，`http`，`sse`，`hybrid`.
### 从MCP客户端连接
Claude Desktop / Cursor `mcp.json` 条目示例：
```json
{
"mcpServers": {
"agnes": {
"command": "/path/to/agnes-mcp",
"args": ["serve", "--config", "/path/to/config.toml", "--mode", "stdio"],
"env": {
"AGNES_API_KEY": "sk-..."
}
}
}
}
```
## 配置
`agnes-mcp` 按优先级顺序读取配置：命令行参数 > 环境变量 > TOML文件 > 默认值。
| 来源 | 密钥 |
| --- | --- |
| 环境变量 | `AGNES_API_KEY` （或 `AGNES_TOKEN`），`AGNES_API_KEYS`，`AGNES_BASE_URL`，`AGNES_MODEL_TEXT`，`AGNES_MODEL_IMAGE`，`AGNES_MODEL_VIDEO`，`AGNES_DISABLED_TOOLS`，`AGNES_KEY_COOLDOWN_SECS`，`AGNES_KEY_RATE_LIMIT_COOLDOWN_SECS`，`AGNES_MCP_HOST`，`AGNES_MCP_PORT`，`AGNES_MCP_TRANSPORT`，`AGNES_MCP_LOG_LEVEL` |
| TOML `[agnes]` | `base_url`，`api_key`，`api_keys`，`model_text`，`model_image`，`model_video`，`disabled_tools`，`request_timeout_secs`，`key_cooldown_secs`，`key_rate_limit_cooldown_secs` |
| TOML `[server]` | `name`，`host`，`port`，`transport_mode` |
| TOML `[logging]` | `level` |
参见 [`config.example.toml`](config.example.toml) 以获取一个完整的注释示例。
### 禁用工具
默认情况下，每个内置MCP工具都被注册并暴露给客户端。如果您只需要子集（例如，您不想要视频生成），请在 `[agnes].disabled_tools` 中列出要禁用的工具名称。名称必须与规范标识符完全匹配（区分大小写）；未知名称将被忽略，并在启动时发出警告。
可用工具名称：
- `agnes_image_recognition`
- `agnes_generate_image`
- `agnes_generate_video`
- `agnes_video_status`
通过以下任意一种方式配置：
- **TOML** （ `[agnes]` ）：
```toml
disabled_tools = ["agnes_generate_video", "agnes_video_status"]
```
- **环境变量**：`AGNES_DISABLED_TOOLS="agnes_generate_video,agnes_video_status"`
- **命令行**：`--disable-tool agnes_generate_video --disable-tool agnes_video_status` （可重复标志）
默认情况下为空 — 没有禁用任何工具。
## 工具参数
### 可配置模型
Agnes模型标识符可以通过 `[agnes]` TOML部分（`model_text`，`model_image`，`model_video`），环境变量 `AGNES_MODEL_TEXT` / `AGNES_MODEL_IMAGE` / `AGNES_MODEL_VIDEO` 或命令行标志 `--model-text` / `--model-image` / `--model-video` 进行覆盖。默认匹配Agnes免费层模型（`agnes-2.0-flash`，`agnes-image-2.1-flash`，`agnes-video-v2.0`）。
### `enhance_prompt` （图片/视频生成）
`agnes_generate_image` 和 `agnes_generate_video` 都接受一个可选的 `enhance_prompt` 布尔值（默认为 `false` ）。当为 `true` 时，聊天模型首先将提示扩展为一个丰富、详细的生成提示（主题 + 场景 + 样式 + 照明 + 构图 + 质量），然后再进行生成。**这会增加一个额外的聊天模型往返时间（~1–5s）** — 如果您的提示已经很详细，请将其设置为 `false` 。如果增强失败，则生成会回退到原始提示，并在输出中附加警告。成功时，增强的提示会回显以便观察。
### `image_urls` 接受的格式（图片转图片）
`agnes_generate_image` 通过 `image_urls` 接受参考图片列表。每个条目可以是：
- **http(s) URL** — 不修改直接传递：`https://example.com/ref.png`
- **本地文件路径** — 读取文件并编码为 `data:` URI 内联（无需公共托管）：`/path/to/ref.png`
- **`data:` URI** — 不修改直接传递：`data:image/png;base64,...`
- **原始base64文本** — 包装为 `data:image/png;base64,<input>`
这与Agnes API的行为相匹配，该API支持 `data:` URI在 `extra_body.image` 中用于图片转图片生成。 `agnes_image_recognition` 也接受相同的输入格式集。
### `save_to` （图片/视频下载）
`agnes_generate_image` ， `agnes_generate_video` 和 `agnes_video_status` 接受一个可选的 `save_to` 路径。当设置时，生成的资产将被下载到该本地路径（多个图片的目录，或单个文件的路径）。 `agnes_generate_video` 仅异步并返回任务ID；使用 `agnes_video_status` 和 `save_to` 下载视频，一旦任务报告 `completed` 。下载失败将在输出中报告，但不会抑制返回的URL。
## 命令行界面
```bash
agnes-mcp serve # 启动MCP服务器
agnes-mcp health # 检查Agnes API连接性
agnes-mcp config # 生成示例配置文件
```
运行 `agnes-mcp serve --help` 获取所有标志。
## 构建
```bash
cargo build --release
```
需求：Rust 1.74+（版本2021）。该项目使用 `rustls` （无OpenSSL），因此静态/musl构建无需任何系统TLS依赖。
### 静态（musl）构建
```bash
rustup target add x86_64-unknown-linux-musl
cargo build --release --target x86_64-unknown-linux-musl
```
## Docker
```bash
# 标准（distroless运行时）
docker build -t agnes-mcp .
# Alpine（带有shell，用于调试）
docker build -f Dockerfile.alpine -t agnes-mcp:alpine .
# Scratch（微小静态镜像）
docker build -f Dockerfile.scratch -t agnes-mcp:scratch .
docker run --rm -p 8080:8080 -e AGNES_API_KEY="sk-..." agnes-mcp
```
或使用Docker Compose：
```bash
AGNES_API_KEY="sk-..." docker compose up --build
```
## 项目结构
```
src/
main.rs 入口点 + 命令行界面
lib.rs 库根，日志初始化
cli/ clap命令（serve / health / config）
config/ TOML + 环境配置
error/ 错误类型
server/ AgnesServer，MCP处理程序，传输
tools/ MCP工具 + 共享Agnes HTTP客户端
agnes_client.rs Agnes API客户端（聊天 / 图片 / 视频）
image_recognition.rs agnes_image_recognition
image.rs agnes_generate_image
video.rs agnes_generate_video + agnes_video_status
prompt.rs 提示增强助手（内部，非MCP工具）
health.rs 命令行健康检查（非MCP工具）
utils/ 输入验证和图片编码助手
```
## 质量门控
该项目强制执行零警告：
```bash
cargo fmt -- --check
cargo clippy --all-targets -- -D warnings
cargo clippy --all-features --all-targets -- -D warnings
cargo test --all-features
```
## 许可证
MIT
连接信息
猜你喜欢
暂无推荐服务器