开发者指南 · 本地 STDIO

通过 MCP 接入你的工作区

在 MCP 客户端中查询已有 Smaltino 任务，或在明确启用后使用 Nano 图像工具。本页说明源码中的 services/mosaic-mcp-server 服务。

1. 准备本地连接

使用本指南前，先取得项目源码工作区的访问授权。使用该工作区内的 services/mosaic-mcp-server 包；本页不提供公开下载。
安装 Node.js 22 或更新版本及工作区使用的 pnpm 版本。在工作区根目录执行 pnpm install --frozen-lockfile 安装依赖后再启动服务。
准备属于你本人及本站的有效 Smaltino API Key，仅在 MCP 客户端受保护的环境中配置，不把值提交到仓库或写入提示词。管理 Smaltino API 密钥

在客户端本地 MCP 服务配置中调整以下 stdio 示例，将 <workspace> 替换为已授权源码的绝对路径。API origin 仅为配置示例，不代表生产访问已激活。

{
  "mcpServers": {
    "mosaic": {
      "command": "pnpm",
      "args": [
        "--silent",
        "--dir",
        "<workspace>/services/mosaic-mcp-server",
        "start"
      ],
      "env": {
        "MOSAIC_API_URL": "https://api.smaltino.com",
        "MOSAIC_API_KEY": "<由客户端受保护环境安全注入>"
      }
    }
  }
}

通过客户端的受保护环境机制替换密钥占位值。MOSAIC_API_URL 必须是 HTTPS origin，或本地使用的 loopback HTTP，不能带账号、路径或 query。凭据不能放进工具参数。默认配置刻意不包含写入开关。

Windows 客户端若不能直接启动 pnpm，配置已安装的 node 二进制、工作区 tsx CLI 路径及 services/mosaic-mcp-server/src/index.ts 入口。若用 node --import 加载 tsx，Windows 绝对路径应转换为 file:///C:/... URL。

stdio 进程生命周期由 MCP 客户端管理，服务不启动后台 daemon。保留 --silent，避免 pnpm 把脚本横幅写入 stdout；stdout 只用于 MCP 协议。

2. 默认查询已有任务

`mosaic_get_task`

默认只注册 mosaic_get_task。提供来自 Smaltino 作品记录的 task_id，配置的 Key 必须属于任务用户。查询不会创建生成任务，也不收取生成积分。

{ "task_id": "your-existing-task-id" }

安全任务摘要只包含 id、taskType、title、status、createdAt 和 updatedAt。状态可能为 accepted、queued、running、succeeded、failed、canceled。

摘要不返回原始 prompt、私有输入字段或源文件签名。API 仍校验身份、密钥撤销、站点范围及任务归属。

3. 仅在有意写入时启用

写工具需要同时满足两层权限：客户端进程环境中的 MOSAIC_ENABLE_TASK_WRITES 必须严格为字符串 true，API Key 还必须由服务端明确授予写权限。省略、false、TRUE、1 或带空格的值均保持只读。仅在有意开放写工具时，才添加以下环境项。

"MOSAIC_ENABLE_TASK_WRITES": "true"

本地开关不能给只读 Key 升权，工具 annotations 和本地启用也不证明客户端已完成人审、预算授权或价格锁定。本页没有开启写入的操作控件。

可选写工具仅支持 image.generate.text-to-image 与 kie-nano-banana-2（Nano Banana 2），不开放本站全部模型或媒体目录。

mosaic_estimate_task: 接受 prompt 和可选 aspect_ratio，查询当前积分报价，不建任务、不预扣、不锁定后续价格；服务端密钥使用审计可能变化。报价参数不能包含 idempotency_key。
mosaic_create_task: 接受 prompt、可选 aspect_ratio 及必填 idempotency_key，创建或恢复本人的任务，实际收费由服务端决定。以下是创建输入示例，并非要求提交它。

{
  "prompt": "平静蓝色湖面上的一只小纸船",
  "aspect_ratio": "auto",
  "idempotency_key": "Original-Key_01"
}

MCP 工具字段使用 snake_case，未知字段会被拒绝。prompt 须非空白且最多 5000 个 JavaScript UTF-16 code unit，保留原文。aspect_ratio 可省略，与 auto 等价。支持比例：auto、1:1、4:3、3:4、16:9、9:16、2:3、3:2、4:5、5:4、21:9、1:4、4:1、1:8、8:1。

必须显式提供符合 ^[A-Za-z0-9._~-]{1,64}$ 的 idempotency_key，原样作为 Idempotency-Key 发送。同一用户、同键、完全相同正文恢复原任务与原接受金额；同键不同正文会冲突。报价不锁价，也没有 maxCredits 承诺。

独立 CLI 是另一个入口：CLI JSON 使用 aspectRatio，MCP 工具使用 aspect_ratio。pnpm --silent start 是 MCP 协议入口，不是 CLI 命令；CLI 用法请查看工作区 README。

4. 处理错误与未知结果

invalid_api_key: 密钥无效、已撤销或属于其它站点。配置有效密钥，不在工具输入中暴露它。
task_not_found: 任务不存在或不属于当前密钥用户。核对作品记录中的任务 ID。
api_not_configured: 查询 API 尚未配置控制库，须由部署方完成激活；本地写开关不能修复此问题。
api_unavailable: 查询遇到网络失败、超时或禁止重定向，重试前先核对 API origin。
api_key_read_only: 服务端拒绝写权限，本地开关不能升级密钥。
invalid_api_task: 服务端拒绝写请求输入，核对已批准的提示词、字段名与比例。
api_task_idempotency_conflict: 此键曾用于不同正文，先核对原请求，不要悄悄换键绕过恢复。
insufficient_credits: 服务端因积分不足拒绝请求，先前报价并未预留价格或余额。

正文大小、内容及限流拒绝使用安全错误码。GET 摘要无效或超限使用 invalid_api_response 或 api_response_too_large，不透传远端错误正文；查询失败不等于生成失败。

请求超时为 30 秒，禁止重定向，响应上限为 64 KiB。密钥只进入 Bearer header，成功输出按安全合同过滤。