# sd-neo-mcp

SD WebUI Forge NEO 的 MCP 服务器与 CLI 工具。同时作为 opencode 的 stdio MCP 服务器与命令行工具 `sdneo`，连接运行中的 SD WebUI Forge NEO 实例（基于 A1111 的 `/sdapi/v1/*` HTTP API）。

## 功能

### 8 个 MCP 工具

| 工具 | 说明 |
|---|---|
| `generate_image` | 文生图，支持异步队列（agent-scheduler 扩展）或同步模式 |
| `image_to_image` | 图生图，基于输入图片和提示词生成新图片 |
| `list_models` | 列出可用 checkpoint 模型，标记当前活跃模型 |
| `switch_model` | 切换当前 checkpoint 模型 |
| `list_loras` | 列出可用 LoRA 模型 |
| `get_progress` | 查询生成进度（同步进度或异步任务状态） |
| `upscale_images` | 放大图片（倍率/指定尺寸模式） |
| `interrogate_image` | 图片反推标签（需 wd14-tagger 扩展） |

### CLI 子命令

`sdneo status` / `gen` / `img2img` / `models` / `loras` / `progress` / `upscale` / `tag`，每个子命令调用对应的 core dispatch 逻辑。

### 双传输模式

- **async**：自动探测 agent-scheduler 扩展，入队后轮询直到完成
- **sync**：回退到同步 `/sdapi/v1/txt2img`（单次阻塞）

## 前置条件

- SD WebUI Forge NEO 必须以 `--api` 启动
- 异步队列需启用 `sd-webui-agent-scheduler-neo` 扩展（可选，无则自动回退同步模式）
- 图片反推需启用 `sd-webui-wd14-tagger` 扩展（可选）
- Node.js >= 18.17

## 安装

```bash
cd sd-neo-mcp
npm install
npm run build
```

## opencode 接入

在 `opencode.json` 的 `mcp` 块中添加（参考 `opencode.example.json`）：

```json
{
  "mcp": {
    "sd-neo": {
      "type": "local",
      "command": ["node", "E:/download/sd-neo-mcp/dist/mcp/server.js"],
      "environment": {
        "SD_WEBUI_URL": "http://127.0.0.1:7860",
        "SD_OUTPUT_DIR": "E:/download/sd-neo-mcp/output"
      }
    }
  }
}
```

若 NEO 启用了 `--api-auth`，在 environment 中加 `SD_AUTH_USER` 和 `SD_AUTH_PASS`（不要设空串，留空即不启用）。

重启 opencode 生效。

## 环境变量

| 变量 | 默认值 | 说明 |
|---|---|---|
| `SD_WEBUI_URL` | `http://127.0.0.1:7860` | SD WebUI API 地址 |
| `SD_AUTH_USER` | - | HTTP Basic Auth 用户名（需与 `SD_AUTH_PASS` 同时设置） |
| `SD_AUTH_PASS` | - | HTTP Basic Auth 密码 |
| `SD_OUTPUT_DIR` | `./output` | 图片输出目录（自动创建） |
| `SD_GEN_TIMEOUT` | `600000` | 生成超时（毫秒） |
| `SD_ASYNC_POLL_INTERVAL` | `1500` | 异步轮询间隔（毫秒） |
| `SD_REQUEST_TIMEOUT` | `300000` | HTTP 请求超时（毫秒） |
| `SD_DEFAULT_SAMPLER` | - | 默认采样器 |
| `SD_DEFAULT_STEPS` | - | 默认步数 |
| `SD_DEFAULT_CFG` | - | 默认 CFG 值 |

## 构建验证

```bash
npm run typecheck
npm run build
npm test
node dist/cli/index.js --help
```

## 项目结构

```
src/
  core/           # 核心业务层，不依赖 MCP/CLI
    config.ts     # 环境变量解析
    client.ts     # NEO API 客户端
    transport.ts  # async/sync 传输层
    tools.ts      # 8 个工具 dispatch
    schema.ts     # zod 输入 schema → JSON Schema
  mcp/
    server.ts     # MCP stdio 服务器
  cli/
    index.ts      # CLI 入口
tests/            # vitest 单元测试
```

## License

MIT