用 AI 打印：mcp-web-print-pdf 接入指南

三层链路，每层都跑在你自己的机器上，没有云端中继：

• AI 宿主（Claude Desktop / Cursor / dsh / Claude Code …）通过 npx -y mcp-web-print-pdf 启动 MCP server，走 stdio 传输。
• MCP server 把每次工具调用翻译成客户端已有的 WebSocket 消息。
• 客户端本地渲染 PDF 并投递系统打印队列，返回任务结果。

AI host (Claude / Cursor / dsh)
   |  stdio: npx -y mcp-web-print-pdf
   v
mcp-web-print-pdf
   |  ws://127.0.0.1:16794/websocket/standard
   v
Web Print Expert client  -->  printer

• 必须先装并启动客户端。MCP 只是桥，没有客户端就没有可用的打印机通道。
• 返回「已提交」，不是「已出纸」。任务进了系统打印队列就算成功；打印机暂停、离线、缺纸时队列会停住，返回值看不出这些状态。
• 调用即出纸。打印工具默认把任务直接投给打印机；只想先看版式时，再传 dry_run: true 预览。
• 没有云端通道。只支持本机已启动的客户端；ChatGPT / claude.ai 网页版只接受远程 HTTP MCP，连不了本机 stdio。

• Web打印专家客户端已安装并运行（默认端口 16794）。还没有？先下载客户端。
• Node.js 18+（宿主用 npx 拉起 MCP server，不需要全局安装；npm 包在这里）。
• 宿主支持 MCP stdio：Claude Desktop、Cursor、dsh、Claude Code、VS Code Copilot、Codex CLI、Cline、Cherry Studio、Trae 等。

① 确认客户端在线

先单独跑一次 npx -y mcp-web-print-pdf 之外的检查：打开客户端，确认它正在运行、端口没被占用。宿主真正连上后，第一个该调用的工具是 getConnectStatus。

② 在宿主里登记 MCP server

所有宿主都是同一个 stdio 命令，只是配置文件位置和顶层键不同：

{
  "mcpServers": {
    "webprint": {
      "command": "npx",
      "args": ["-y", "mcp-web-print-pdf"],
      "env": { "WEBPRINT_PORT": "16794" }
    }
  }
}

dsh 用 YAML 插入，写法不同但字段等价：

- insert:
    - id: mcp-webprint
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: webprint
        transport: stdio
        command: npx
        args:
          - '-y'
          - 'mcp-web-print-pdf'
        toolCallTimeoutMs: 180000

③ 重启宿主并确认绿灯

改完配置重启宿主，在它的 MCP 面板里确认服务已连接。模型侧看到的工具名会带命名空间，例如 mcp__webprint__printHtml；先 getConnectStatus 探活，再 printHtml 加 dry_run: true 看预览是否生成。

三个 options 对象分别对应上游的三个实参：pdf_options / print_options 走客户端白名单校验（字段名写错直接报错），extra_options 允许任意自定义键并原样返回。

合并规则：对象里显式写的字段优先，便利参数只补空缺。

• 把 Base64 通道当文件通道用。stdio 单条消息有 10MB 上限，超了连接会被直接关闭，工具里来不及报错。大 PDF / 图片请用 printFile 或 URL 通道。
• 宿主超时先于任务完成。多数宿主给单次工具调用约 60 秒，批量或大文件容易被掐断——拆批，或调大宿主的工具超时（如 dsh 的 toolCallTimeoutMs）。
• 给 pdf_options.paperFormat 传自定义纸名。它只认固定枚举（A0–A6 / Letter / Legal / Tabloid / Ledger）；80mm 小票、100×150 面单请改用 width + height。
• batchPrint 的任务字段写错。每项是 { type, data, pdfOptions?, printOptions?, extraOptions? }，内容放 data，不是 content / url / base64；同一批次里每个任务的 extraOptions.action 必须一致。
• 随手开 printFile。它会读取模型指定的本机任意路径，只应在可信环境里启用。
• 照抄旧版工具名。0.1.0 用的是 snake_case（print_html / list_printers），0.2.0 起统一成上游的驼峰方法名，旧名不再生效。

1. getConnectStatus：客户端在线才继续。
2. getPrinterList：确认模型看到的目标打印机名称与你预期一致。
3. printHtml 加 dry_run: true：返回里有预览地址 / PDF 地址，说明渲染链路通了。
4. 正式打印：真正出纸。没动静时用系统打印队列（如 Windows 的 Get-PrintJob）看作业状态，而不是只看工具返回值。