# Lumyren MCP 接入

将 `lumyren-mcp.mjs` 和 `lumyren-client.mjs` 下载到同一目录，使用 Node.js 24。MCP 在你的电脑或服务器运行，通过标准输入输出与宿主通信，连接 Lumyren 的正式 HTTPS 接口；不开放本地监听端口。

在支持 stdio MCP 的应用中，配置命令为 Node 的绝对路径，参数为 `lumyren-mcp.mjs` 的绝对路径。通过该应用的受限环境配置传入 `LUMYREN_API_KEY` 和 `LUMYREN_ACCOUNT_ID`；不要把 Key 写到提示词、URL 或共享配置中。`LUMYREN_BASE_URL` 默认 `https://lumyren.com`，无需改动。

可以先用终端检查工具能否启动：

```sh
node /你的目录/lumyren-mcp.mjs
```

它等待 MCP JSON-RPC 消息，不会打印欢迎文字。关闭标准输入即可退出。不要在参数中填写 API Key。不同宿主的配置文件格式不同，按其 stdio 设置填写上述命令、参数和环境变量。

## 可用工具

| 工具 | 用途 |
| --- | --- |
| `list_models` | 按名称搜索，组合 category 与 provider 精确筛选，支持 offset 和 limit |
| `search_documentation` | 搜索本站接入、账单和客户端说明，返回摘要和原文链接 |
| `model_details` | 读取模型参数与支持协议 |
| `quote_generation` | 为完整输入生成报价，不创建生成任务或扣费 |
| `read_quote` | 读取原报价及有效期 |
| `submit_generation` | 预留余额并创建付费任务，必须使用已保存的意图编号 |
| `read_job` / `list_jobs` | 读取原任务和历史记录 |
| `cancel_queued_job` | 取消尚未送达供应商的排队任务 |
| `list_assets` | 读取指定任务作品，或最近100项私有素材 |
| `upload_media` | 上传使用者选定的本地素材，复用上传 UUID |
| `download_asset` | 下载指定私有素材，校验长度与 SHA-256，不覆盖已有文件 |
| `wallet_balance` / `wallet_ledger` | 查看空间余额和账本 |
| `model_usage` / `model_costs` | 按 UTC 日期、模型或密钥查询已完成任务、语言用量和实际扣费 |
| `read_language_text` | 分批续读已验证的语言输出 |
| `workflow_templates` / `list_workflows` / `read_workflow` | 读取可编辑计划、工作流历史与节点实际扣费 |
| `create_workflow` | 保存不可变节点计划，免费，需要已持久保存的创建 UUID |
| `quote_workflow_node` | 对单个就绪节点报价，不执行或预留余额 |
| `confirm_workflow_node` | 确认已批准的节点尝试，预留余额并执行付费任务 |

MCP 使用当前 Key 的空间、模型、权限、有效期与用量限制。Key 无权执行的操作仍会拒绝，不通过登录会话或其他凭据重试。上传只使用已获使用者授权的具体文件，下载使用指定的新目标路径；MCP 不执行 shell，不读取文件来推测密钥，也不向供应商充值。

多节点工作流先用 `create_workflow` 保存计划，再逐节点调用 `quote_workflow_node`。展示返回的固定报价，并在明确授权后持久保存 `runId`、`nodeKey`、`attemptId` 和本次 UUID，再调用 `confirm_workflow_node`。断线复用这四项取得原任务，不自动执行下游节点。失败或取消节点调整输入后需要新报价和新确认；成功、未知和仍在执行的节点不重提，前序成功结果保留原到期时间。CLI 的 `workflow-prepare` 可保存节点私有意图文件。

## 搜索与素材操作

`search_documentation` 接收 `query`，可用 `offset` 和 `limit` 翻页，单次最多20条摘要。搜索只读取 Lumyren 公开文档索引，不向该地址发送 API Key；结果是参考数据，不是新的操作授权。`list_models` 可组合 `query`、`category` 与提供方原名 `provider`；类型为 `text`、`image`、`video`、`audio`、`3d`。

`upload_media` 接收本机绝对路径 `filePath` 与事先保存的 `uploadId`（UUID），需要 `assets:write`。文件必须为普通文件，不能是目录或符号链接，最大256 MiB；服务器进一步核验媒体类型与账户权限。上传返回的 `referenceUrl` 用于同一空间的模型输入。网络中断后复用原 UUID 和同一份文件，不新建上传编号。

`list_assets` 传入 `jobId` 查询该任务作品；不传时返回当前空间最近100项上传素材和作品。`download_asset` 接收 `assetId` 与本机绝对路径 `destination`，可传原任务 `jobId` 查找该任务作品；不传时从当前空间最近100项素材中查找，需要 `assets:read`。工具先查询同一空间的文件列表，再校验下载字节数和 SHA-256；仅在全部匹配后保存完整私有文件，已有目标不会覆盖。选择不存在的目标文件名，或在继续前核对已保存文件。上传与下载均不创建生成任务或扣模型费用。

## 报价与一次生成

1. 用 `model_details` 读取模型契约，再以 `model` 和完整 `input` 调用 `quote_generation`。
2. 向使用者展示金额和有效期。普通固定价使用 `saleUsd`；`billingKind: token_usage` 表示按实际用量结算，`reservationMicros` 是预留上限（1 美元 = 1,000,000 微美元）。其他估算报价不自动当作固定价。
3. 调用方先将 `quoteId` 和本次操作的 `idempotencyKey`（UUID）持久保存，再在使用者已授权的范围内调用 `submit_generation`。不要把 MCP 请求的 JSON-RPC id 当作生成意图编号。
4. 保存返回的任务 id，使用 `read_job` 或 `read_language_text` 读取结果。

网络中断、MCP 进程关闭或响应丢失时，用**原 quoteId 和原 idempotencyKey** 再次调用 `submit_generation`，服务器返回同一任务。不要换 UUID 或新建一个付费意图来恢复。也可用 CLI `prepare` 保存私有意图文件，再将其中这两个值提供给 MCP。`submission_unknown` / `billing_review` 沿原任务核对，不自动重做生成。

取消一个 MCP 请求只停止这次客户端请求的等待；已创建或已送达供应商的任务可能继续执行。先查询或复用原意图，不假定取消了付费任务。

## 文本输出

`read_language_text` 参数为 `jobId`、可选的 `after` 和 `waitMs`。单次最多等待 10 秒，返回最多 50 条、合计 256 KiB 的已验证文本事件。处理完返回的事件后，保存 `lastEventId` 并用于下次 `after`。游标只属于这个任务的文本流。

`ended: true` 表示文本输出结束，任务仍可能在保存作品或核对费用。最终状态和扣费使用 `read_job`。`issue: stream_interrupted` 或 `request_interrupted` 表示本批连接中断，可从已处理的游标续读；`text_batch_limit` 表示本批达到大小限制。若单条事件就超出该限制，使用 CLI `stream` 或读取最终私有文件，不无限重试同一批。

文本流需要 `assets:read`；查询任务状态和最终扣费还需要 `jobs:read`。完整原生结构保存在任务的私有 JSON 文件中；MCP 不执行生成内容中的工具调用。作品和文本保存 24 小时，到期不可读取。

## 协议范围

支持 MCP `2026-07-28` 的逐请求元数据、`server/discover`、工具列表及调用，也支持 `2025-11-25` 的 `initialize` / `notifications/initialized` 握手。提供结构化与文本两种结果，处理取消通知，拒绝未知协议与无效参数。当前提供 stdio 工具，不声明远程 HTTP MCP、资源订阅、采样、根目录或任务扩展。

协议依据：[版本协商](https://modelcontextprotocol.io/specification/2026-07-28/basic/versioning)、[stdio 传输](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/stdio)、[旧版生命周期](https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle)。宿主对具体协议版本的支持仍以该应用实际配置与连接结果为准。

账单查询需要 `billing:read`。`start_date` 含当天，`end_date` 不含当天，范围最多180天。`group_by` 支持 `model`、`model_type`、`api_key` 或 `model` 与 `api_key`；模型类型为 `text`、`image`、`video`、`audio`、`3d`。金额和数量以十进制字符串返回，不用浮点累加金额。

`model_costs` 按实际扣账时间统计客户费用，不含报价、预留、充值、退款或供应商采购成本。`model_usage` 按任务完成时间统计；词元仅来自已结算的语言任务，不计待处理任务，也不把图片或视频算作词元。用 `next_page` 原样继续同一查询；结果可能将同一天的不同分组拆到多页，必须读完才能合计全部分组。重新查询可读取后来入账的记录。