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

安装

cd sd-neo-mcp
npm install
npm run build

opencode 接入

在 opencode.json 的 mcp 块中添加（参考 opencode.example.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 值

构建验证

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