mcp-web-print-pdf 0.2.0 → 0.2.2

package/README.md

@@ -8,10 +8,21 @@
 `ws://127.0.0.1:16794/websocket/standard` 再加一个客户端，并把 `web-print-pdf@2.x` 的公开 API
 一对一映射成 MCP 工具。
 
+- 官网：<https://webprintpdf.com/>
+- 底层 npm 包：[web-print-pdf](https://www.npmjs.com/package/web-print-pdf)
+- 文档：<https://webprintpdf.com/docs/>
+
 ```
 Claude / dsh ──stdio──> mcp-web-print-pdf ──ws──> Web打印专家客户端 ──> 打印机
 ```
 
+## 前置条件
+
+- 本机安装并启动 [Web打印专家客户端](https://webprintpdf.com/downloadApp/)（Windows 10/11、macOS 11+、Linux / 银河麒麟 / 统信 UOS）
+- 客户端默认监听 `ws://127.0.0.1:16794/websocket/standard`
+- 不需要改客户端或前端代码；本 MCP 只是把 [web-print-pdf](https://www.npmjs.com/package/web-print-pdf) 的公开 API 映射成 MCP 工具
+- MCP 接入指南：<https://webprintpdf.com/docs/mcp-print/>
+
 ## 安装
 
 宿主会自动通过 `npx -y mcp-web-print-pdf` 拉取，不需要全局安装。
@@ -214,8 +225,8 @@ Roo Code / Kilo Code 是 Cline 的分叉，配置结构相同，只是文件路
 
 ### 打印
 
-所有打印工具默认 `dry_run: true`：只渲染预览、不出纸；要真正打印必须显式传 `dry_run: false`
-（或 `extra_options.action: "print"`）。
+所有打印工具默认 `dry_run: false`：直接出纸；要只渲染预览请显式传 `dry_run: true`
+（或 `extra_options.action: "preview"`）。默认会真的用纸，请先确认打印机和纸张。
 
 > 不传 `paper_format` 时，PDF 渲染默认用 A4，但打印阶段会沿用客户端默认打印机的纸张。
 > 要固定纸张（比如热敏 80mm、面单 100×150），请显式传 `paper_format` / `pdf_options`。
@@ -262,7 +273,7 @@ Roo Code / Kilo Code 是 Cline 的分叉，配置结构相同，只是文件路
 | `pdf_options` | `pdfOptions` | 排版成 PDF：纸张、边距、页眉页脚、背景、水印、页码… |
 | `print_options` | `printOptions` | 投递打印机：打印机名、份数、单双面、缩放、纸盒、热敏锐化… |
 | `extra_options` | `extraOptions` | `action`、`requestTimeout`、`cookies`、`httpHeaders`、`localStorages`… |
-| `dry_run` | — | 便捷开关，默认只预览；显式 `action` 优先 |
+| `dry_run` | — | 默认出纸；`true` 只预览；显式 `action` 优先 |
 | `paper_format` | — | 便捷参数，等价于 `print_options.paperFormat` |
 | `printer_name` | — | 便捷参数，等价于 `print_options.printerName` |
 | `copies` | — | 便捷参数，等价于 `print_options.copies` |
@@ -302,6 +313,7 @@ Roo Code / Kilo Code 是 Cline 的分叉，配置结构相同，只是文件路
   "tool": "printHtml",
   "arguments": {
     "html": "<h1>发票 #12345</h1><p>合计 ¥99.99</p>",
+    "dry_run": true,
     "paper_format": "A4",
     "pdf_options": { "printBackground": true, "margin": { "top": "10mm", "bottom": "10mm" } }
   }
@@ -373,7 +385,7 @@ MCP 的 stdio 通道单条消息默认上限 **10MB**（SDK 的 `ReadBuffer`）
   客户端，绕开 MCP 的消息上限。
 - 也可以先把文件挂到 HTTP 地址，用 `printPdfByUrl` / `printImageByUrl` / `printHtmlByUrl`。
 
-## 与 `web-print-pdf@2.1.9` 的覆盖对照
+## 与 [web-print-pdf@2.1.9](https://www.npmjs.com/package/web-print-pdf) 的覆盖对照
 
 | 上游公开 API | 本 MCP |
 |---|---|
@@ -436,6 +448,15 @@ npx @modelcontextprotocol/inspector node bin/mcp.js
 - 参数与消息结构按 `ElctronPrintWeb`（客户端 1.0.9）源码校准：`batchPrint` 任务用 `data` 字段，
   不是 `web-print-pdf` README 示例里的 `content` / `url` / `base64`。
 
+## 相关链接
+
+- 官网：<https://webprintpdf.com/>
+- 文档：<https://webprintpdf.com/docs/>
+- MCP 接入指南：<https://webprintpdf.com/docs/mcp-print/>
+- 客户端下载：<https://webprintpdf.com/downloadApp/>
+- web-print-pdf（npm）：<https://www.npmjs.com/package/web-print-pdf>
+- 本仓库：<https://github.com/weixiaoyi/mcp-web-print-pdf>
+
 ## License
 
 MIT

package/README_EN.md

@@ -8,10 +8,21 @@ It does **not** modify the Web Print Expert client or the `web-print-pdf` browse
 adds another client to the existing `ws://127.0.0.1:16794/websocket/standard` endpoint and maps the
 public `web-print-pdf@2.x` API one-to-one onto MCP tools.
 
+- Website: <https://webprintpdf.com/>
+- Underlying npm package: [web-print-pdf](https://www.npmjs.com/package/web-print-pdf)
+- Docs: <https://webprintpdf.com/docs/>
+
 ```
 Claude / dsh ──stdio──> mcp-web-print-pdf ──ws──> Web Print Expert client ──> printer
 ```
 
+## Prerequisites
+
+- Install and start the [Web Print Expert client](https://webprintpdf.com/downloadApp/) (Windows 10/11, macOS 11+, Linux / Kylin / UOS)
+- The client listens on `ws://127.0.0.1:16794/websocket/standard` by default
+- No changes to the client or your frontend code; this MCP just maps the public [web-print-pdf](https://www.npmjs.com/package/web-print-pdf) API onto MCP tools
+- MCP guide: <https://webprintpdf.com/docs/mcp-print/>
+
 ## Installation
 
 Hosts fetch it automatically via `npx -y mcp-web-print-pdf`; no global install is required.
@@ -221,8 +232,9 @@ file by path" method.
 
 ### Printing
 
-Every printing tool defaults to `dry_run: true`: render a preview only, no paper. To actually print,
-pass `dry_run: false` explicitly (or `extra_options.action: "print"`).
+Every printing tool defaults to `dry_run: false`: it actually prints. To render a preview only, pass
+`dry_run: true` explicitly (or `extra_options.action: "preview"`). The default really uses paper —
+check the printer and paper first.
 
 > When `paper_format` is omitted, the PDF is rendered at A4 but the print stage uses the client's
 > default printer paper. To pin the paper (80mm thermal, 100×150 labels, etc.), pass `paper_format` /
@@ -271,7 +283,7 @@ All printing tools share one parameter set, mirroring the upstream four argument
 | `pdf_options` | `pdfOptions` | PDF layout: paper, margins, header/footer, background, watermark, page numbers… |
 | `print_options` | `printOptions` | Printer delivery: printer name, copies, duplex, scaling, tray, thermal sharpening… |
 | `extra_options` | `extraOptions` | `action`, `requestTimeout`, `cookies`, `httpHeaders`, `localStorages`… |
-| `dry_run` | — | Convenience switch, preview by default; an explicit `action` wins |
+| `dry_run` | — | Prints by default; `true` previews only; an explicit `action` wins |
 | `paper_format` | — | Convenience for `print_options.paperFormat` |
 | `printer_name` | — | Convenience for `print_options.printerName` |
 | `copies` | — | Convenience for `print_options.copies` |
@@ -315,6 +327,7 @@ Preview an A4 invoice (no paper):
   "tool": "printHtml",
   "arguments": {
     "html": "<h1>Invoice #12345</h1><p>Total ¥99.99</p>",
+    "dry_run": true,
     "paper_format": "A4",
     "pdf_options": { "printBackground": true, "margin": { "top": "10mm", "bottom": "10mm" } }
   }
@@ -386,7 +399,7 @@ MCP's stdio channel has a default **10MB** per-message limit (the SDK's `ReadBuf
   the client over WebSocket, bypassing the MCP message limit.
 - Alternatively host the file over HTTP and use `printPdfByUrl` / `printImageByUrl` / `printHtmlByUrl`.
 
-## Coverage vs `web-print-pdf@2.1.9`
+## Coverage vs [web-print-pdf@2.1.9](https://www.npmjs.com/package/web-print-pdf)
 
 | Upstream public API | This MCP |
 |---|---|
@@ -463,6 +476,15 @@ check that a preview appears.
   `batchPrint` tasks use a `data` field, not the `content` / `url` / `base64` fields shown in the
   `web-print-pdf` README examples.
 
+## Links
+
+- Website: <https://webprintpdf.com/>
+- Docs: <https://webprintpdf.com/docs/>
+- MCP guide: <https://webprintpdf.com/docs/mcp-print/>
+- Client download: <https://webprintpdf.com/downloadApp/>
+- web-print-pdf (npm): <https://www.npmjs.com/package/web-print-pdf>
+- This repository: <https://github.com/weixiaoyi/mcp-web-print-pdf>
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-web-print-pdf",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "MCP server for Web打印专家 / web-print-pdf — full API coverage: HTML, URL, PDF, image, batch printing to local printers",
   "type": "module",
   "bin": {
@@ -15,7 +15,8 @@
   "scripts": {
     "start": "node bin/mcp.js",
     "mock": "node test/mock-server.js",
-    "smoke": "node test/smoke.js"
+    "smoke": "node test/smoke.js",
+    "test": "node --test test/options.test.js"
   },
   "engines": {
     "node": ">=18"
@@ -37,7 +38,7 @@
     "receipt",
     "label"
   ],
-  "homepage": "https://github.com/weixiaoyi/mcp-web-print-pdf#readme",
+  "homepage": "https://webprintpdf.com/",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/weixiaoyi/mcp-web-print-pdf.git"

package/src/options.js

@@ -153,8 +153,8 @@ export const printArgsShape = {
     copies: z.number().int().min(1).max(999).optional().describe("便捷参数：份数"),
     dry_run: z
         .boolean()
-        .default(true)
-        .describe("true（默认）= 只渲染预览不出纸；false = 真正出纸。显式 extra_options.action 优先于本项"),
+        .default(false)
+        .describe("false（默认）= 真正出纸；true = 只渲染预览。显式 extra_options.action 优先于本项"),
 };
 
 /**
@@ -187,7 +187,7 @@ export function buildOptions(args = {}) {
         printOptions.copies = args.copies;
     }
 
-    const action = extraOptions.action || (args.dry_run === false ? "print" : "preview");
+    const action = extraOptions.action || (args.dry_run === true ? "preview" : "print");
     extraOptions.action = action;
 
     return { pdfOptions, printOptions, extraOptions, action };

package/src/server.js

@@ -213,7 +213,7 @@ export async function start() {
 
     registerPrint(
         "printHtml",
-        "把 HTML 字符串渲染成 PDF 并打印。默认只渲染预览、不出纸（dry_run: false 才出纸）",
+        "把 HTML 字符串渲染成 PDF 并打印。默认真正出纸；dry_run: true 才只渲染预览",
         { html: z.string().describe("完整页面或 HTML 片段") },
         "printHtml",
         ({ html }) => ({ content: html })
@@ -221,7 +221,7 @@ export async function start() {
 
     registerPrint(
         "printHtmlByUrl",
-        "抓取一个网页并渲染成 PDF 打印。默认只预览；登录态可用 extra_options.cookies / httpHeaders / localStorages 处理",
+        "抓取一个网页并渲染成 PDF 打印。默认出纸；dry_run: true 只预览；登录态可用 extra_options.cookies / httpHeaders / localStorages 处理",
         { url: z.string().url().describe("网页 http(s) 地址") },
         "printHtmlByUrl",
         ({ url }) => ({ url })
@@ -229,7 +229,7 @@ export async function start() {
 
     registerPrint(
         "printHtmlByBase64",
-        "把 Base64 编码的 HTML 渲染成 PDF 打印。默认只预览",
+        "把 Base64 编码的 HTML 渲染成 PDF 打印。默认出纸；dry_run: true 只预览",
         { base64: z.string().min(1).describe("HTML 的 base64，可带 data:text/html;base64, 前缀") },
         "printHtmlByBase64",
         ({ base64 }) => ({ base64: stripDataUrl(base64) })
@@ -237,7 +237,7 @@ export async function start() {
 
     registerPrint(
         "printPdfByUrl",
-        "下载一个 PDF 链接并打印。默认只渲染预览、不出纸",
+        "下载一个 PDF 链接并打印。默认出纸；dry_run: true 只预览",
         { url: z.string().url().describe("PDF 的 http(s) 地址") },
         "printPdfByUrl",
         ({ url }) => ({ url })
@@ -245,7 +245,7 @@ export async function start() {
 
     registerPrint(
         "printPdfByBase64",
-        "把 Base64 编码的 PDF 打印。默认只预览",
+        "把 Base64 编码的 PDF 打印。默认出纸；dry_run: true 只预览",
         { base64: z.string().min(1).describe("PDF 的 base64，可带 data:application/pdf;base64, 前缀") },
         "printPdfByBase64",
         ({ base64 }) => ({ base64: stripDataUrl(base64) })
@@ -253,7 +253,7 @@ export async function start() {
 
     registerPrint(
         "printImageByUrl",
-        "下载一张图片并打印。默认只预览",
+        "下载一张图片并打印。默认出纸；dry_run: true 只预览",
         { url: z.string().url().describe("图片的 http(s) 地址") },
         "printImageByUrl",
         ({ url }) => ({ url })
@@ -261,7 +261,7 @@ export async function start() {
 
     registerPrint(
         "printImageByBase64",
-        "把 Base64 编码的图片打印。默认只预览；缺 data:image/...;base64, 前缀时会自动补",
+        "把 Base64 编码的图片打印。默认出纸；dry_run: true 只预览；缺 data:image/...;base64, 前缀时会自动补",
         { base64: z.string().min(1).describe("图片的 base64；带不带 data:image/...;base64, 前缀都可以") },
         "printImageByBase64",
         ({ base64 }) => ({ base64: toImageDataUrl(base64) })
@@ -269,7 +269,7 @@ export async function start() {
 
     server.tool(
         "printFile",
-        "打印本机文件：按扩展名自动选择 PDF / HTML / 图片通道。默认只预览、不出纸",
+        "打印本机文件：按扩展名自动选择 PDF / HTML / 图片通道。默认出纸；dry_run: true 只预览",
         {
             path: z.string().min(1).describe("本机文件路径，绝对路径或相对当前工作目录"),
             ...printArgsShape,
@@ -291,7 +291,7 @@ export async function start() {
 
     server.tool(
         "batchPrint",
-        "一次提交多个打印任务（HTML / 网页 / PDF / 图片，URL 或 Base64 混合）。默认只预览、不出纸",
+        "一次提交多个打印任务（HTML / 网页 / PDF / 图片，URL 或 Base64 混合）。默认出纸；dry_run: true 只预览",
         {
             tasks: z.array(batchTaskSchema).min(1).describe("任务列表，每项含 type 与对应内容字段"),
             ...printArgsShape,