AI MCP 接入 · Moonshine-Image

01

连接方式

MCP ClientAI 客户端启动应用提供的 stdio 配置

stdio proxy本地适配层stdout 保持 JSON-RPC-only

Private named pipeElectron main仅限当前 Windows 用户

不是 HTTP 服务。不要扫描端口、拼接本地 URL，也不要尝试把命名管道当作公开网络 API。连接由桌面应用和 stdio proxy / native broker 管理。

02

从应用复制配置

1
打开 Moonshine-Image
确保桌面应用和本地后端处于可用状态。
2
进入 MCP 设置
在全局设置的 MCP 页面查看客户端配置和当前确认策略。
3
复制应用生成的 stdio 配置
粘贴到支持 MCP 的 AI 客户端中，再由客户端启动代理。
4
先读取状态
连接后先调用 moonshine.status 与 moonshine.capabilities，不要假设模型或 provider 一定可用。

配置以应用界面为准。官网不会给出真实 executable path、pipe name、token 或 broker secret。不要手写或硬编码这些字段，也不要把应用生成的私有配置提交到仓库。

下面只展示安全的 MCP 工具调用格式，不是客户端启动配置：

JSON · illustrative request

{
  "name": "moonshine.status",
  "arguments": {}
}

03

确认策略

read_only

只读

可查询能力、模型、状态和检测结果，但不创建输出文件。适合首次接入和审计。

auto_approve

自动批准

允许处理并写入新文件；仍受工具白名单、参数校验和可信目录限制。

full_access

完整访问

允许处理并跳过目录 containment；仍受工具白名单与参数校验限制。

工具元数据分为 read 与 task。确认策略进一步决定处理和写入权限；具体工具资格以应用设置中的实时状态为准。任何模式都不应把 secret 暴露给第三方客户端。

04

当前工具清单

Moonshine-Image MCP 工具与访问分类
工具	分类	用途
`moonshine.status`	read	读取应用、后端与 MCP 状态。
`moonshine.capabilities`	read	读取当前机器实际可用的能力。
`moonshine.models.list`	read	列出已知模型与可用状态。
`moonshine.ocr.detect`	task	检测图片中的文字候选区域。
`moonshine.masks.generate`	task	用 OCR、SAM 或组合策略生成蒙版。
`moonshine.image.process`	task	提交单文件图片处理任务。
`moonshine.image.process_batch`	task	提交图片批处理任务组。
`moonshine.jobs.get`	read	读取任务状态和安全投影。
`moonshine.jobs.result`	read	读取成功任务的结果 descriptor。
`moonshine.jobs.cancel`	task	取消允许取消的单个任务。
`moonshine.job_groups.get`	read	读取批处理任务组状态。
`moonshine.job_groups.cancel`	task	取消允许取消的任务组。

这里列出当前稳定公开名称。每个工具的参数 schema 和可用性由正在运行的应用返回；调用前应先读取 capabilities，而不是从名称推断输入字段。

05

一次完整的调用流程

1moonshine.status

确认桌面应用、后端与桥接状态。

2moonshine.capabilities

读取当前可用模型、OCR / SAM 和任务能力。

3moonshine.masks.generate

从处理源生成 OCR、SAM 或组合蒙版。

4moonshine.image.process

用选择的模型、蒙版和安全输出语义提交任务。

5moonshine.jobs.get

轮询任务状态；尊重确认、失败和取消状态。

6moonshine.jobs.result

成功后获取受控结果 descriptor。

调用示例

参数以运行中的工具 schema 为准。以下请求只演示 JSON-RPC 工具调用的外形：

JSON · illustrative request

{
  "name": "moonshine.capabilities",
  "arguments": {}
}

JSON · illustrative request

{
  "name": "moonshine.jobs.get",
  "arguments": {
    "job_id": "<job-id-returned-by-the-app>"
  }
}

任务与编辑器分离。MCP 任务不会自动修改当前编辑工作区。只有用户在应用中显式执行 “Open in editor”，结果才会被导入编辑器。

06

任务状态

awaiting_confirmation等待用户确认

queued已进入队列

running正在执行

succeeded已成功，可读取结果

failed执行失败

cancelled已取消

interrupted被应用或服务中断

客户端应处理所有终态，不要只等待 succeeded。应用重启或服务关闭可能把运行中的任务恢复为 interrupted，需要用户决定是否重试。

07

安全与隐私边界

不暴露连接秘密
token 只存在于 main / child IPC 边界，不进入 renderer、日志、公开配置或第三方客户端输出。
每一层分别校验
工具白名单、schema、trusted path containment、job ownership、输出路径和取消语义分别检查。
默认 fail closed
应用 / 服务关闭、越权目录、未授权工具、无 provider、拒绝或取消时，不应留下处理产物。
源文件永不覆盖
输出使用新文件语义；artifact 只通过受控 descriptor 暴露给 renderer 或客户端。

不要记录或分享真实 token、pipe name、broker secret、用户绝对路径、完整客户端启动配置。排障时使用应用提供的脱敏状态和错误信息。