# agnes-mcp

基于 [Agnes AI](https://agnes-ai.com/) 的 MCP 服务端 — 读图·生图·生视频，全部走 OpenAI 兼容接口。

官方仓库：[AgnesAI-Labs/AgnesAI-Models](https://github.com/AgnesAI-Labs/AgnesAI-Models) — 模型目录、API 文档和示例。
API 平台：[https://platform.agnes-ai.com/](https://platform.agnes-ai.com/)

## 工具列表

| 工具 | 说明 |
|------|------|
| `describe_image` | 读本地图片 → 自动压缩 → base64 → Agnes 视觉模型 → 返回文字描述。支持 png/jpg/webp/bmp/gif |
| `generate_image` | 文字生图（异步）→ 返回 `taskId: "img_1"`，后台自动下载 |
| `generate_video` | 文字生视频（异步）→ 返回 `taskId: "vid_1"`，后台自动轮询并下载 |
| `get_task_status` | 查询任意异步任务状态（0ms 缓存，不调 API）→ 完成后返回下载路径 + 总耗时 |

### describe_image

| 参数 | 类型 | 必填 | 默认 | 说明 |
|------|------|------|------|------|
| `filePath` | string | 是 | — | 本地图片路径，支持 png/jpg/jpeg/gif/webp/bmp |
| `prompt` | string | 否 | `"Describe this image in detail"` | 传给视觉模型的提示词 |

返回：文字描述 + 耗时

### generate_image

| 参数 | 类型 | 必填 | 默认 | 说明 |
|------|------|------|------|------|
| `prompt` | string | 是 | — | 生成图片的文字描述 |
| `size` | string | 否 | `"1024x768"` | 期望尺寸，如 `"1024x768"`、`"512x512"`（实际由 Agnes 决定最终分辨率） |
| `outputPath` | string | 是 | — | 图片保存路径 |

返回：`{"taskId":"img_1","status":"queued"}`

### generate_video

| 参数 | 类型 | 必填 | 默认 | 说明 |
|------|------|------|------|------|
| `prompt` | string | 是 | — | 生成视频的文字描述 |
| `outputPath` | string | 是 | — | 视频保存路径 |

返回：`{"taskId":"vid_1","status":"queued"}`

### get_task_status

| 参数 | 类型 | 必填 | 默认 | 说明 |
|------|------|------|------|------|
| `taskId` | string | 是 | — | 异步任务 ID，`img_*` 或 `vid_*` |

返回：`{"status":"completed","outputPath":"...","totalTime":"26s"}` 或 `{"status":"in_progress","progress":30}`

## 快速开始

```bash
npm install
# 编辑 config.json 填入 Agnes API key
npm run dev
```

## 配置

编辑项目根目录的 `config.json`：

```json
{
  "apiKeys": ["sk-xxx", "sk-yyy"],
  "baseUrl": "https://apihub.agnes-ai.com/v1",
  "models": {
    "vision": "agnes-2.0-flash",
    "image": "agnes-image-2.1-flash",
    "video": "agnes-video-v2.0"
  },
  "videoTimeout": 600000,
  "imageMaxDimension": 2048,
  "imageQuality": 80
}
```

| 字段 | 默认值 | 说明 |
|------|--------|------|
| `apiKeys` | `[]` | 多个 key 自动轮询（round-robin） |
| `baseUrl` | `https://apihub.agnes-ai.com/v1` | API 地址 |
| `models.*` | agnes-2.0-flash 等 | 各任务使用模型 |
| `videoTimeout` | `600000` | 视频生成超时（毫秒），默认 10 分钟 |
| `imageMaxDimension` | `2048` | 读图时最大宽/高，超过等比缩小 |
| `imageQuality` | `80` | JPEG 压缩质量（保留以备后续扩展） |
| `retryCount` | `3` | API 请求失败时自动重试次数（对 429/5xx/网络错误生效） |

`config.json` 已被 `.gitignore` 和 `pre-commit` 钩子双重保护，禁止提交到仓库。

## 环境变量

| 变量 | 作用 |
|------|------|
| `AGNES_BASE_URL` | 覆盖 API 地址（默认使用 config.json） |
| `AGNES_API_KEYS` | JSON 数组格式的 key 列表（优先级高于 config.json） |

## 接入 MCP Host

### opencode.json

```json
{
  "mcp": {
    "agnes-mcp": {
      "type": "local",
      "command": ["npx", "tsx", "src/main.ts"],
      "cwd": "D:\\path\\to\\agnes_mcp"
    }
  }
}
```

### claude_desktop_config.json

```json
{
  "mcpServers": {
    "agnes-mcp": {
      "command": "node",
      "args": ["D:\\path\\to\\agnes_mcp\\dist\\main.js"]
    }
  }
}
```

确保先执行 `npm run build` 编译，然后填入实际项目路径。

## 脚本

| 命令 | 作用 |
|------|------|
| `npm run dev` | `tsx watch src/main.ts` 开发模式 |
| `npm run build` | `tsc` 编译 |
| `npm run start` | `node dist/main.js` 启动 |

## 许可

MIT © 2026 [1cyberlangke1](https://github.com/1cyberlangke1)