@bestimmaa/posprint-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Bestimmaa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# @bestimmaa/posprint-mcp
+
+MCP server for POS printer receipts using [`@bestimmaa/posprint`](https://www.npmjs.com/package/@bestimmaa/posprint).
+
+The tool is intentionally named `print` so clients can map natural user phrasing such as "print receipt", "hard copy", or "print this out" to the same operation.
+
+## Requirements
+
+- Node.js 20+
+- A printer reachable via a CUPS URI supported by `@bestimmaa/posprint`
+
+## Run With npx
+
+```bash
+npx @bestimmaa/posprint-mcp
+```
+
+## Install
+
+```bash
+npm install -g @bestimmaa/posprint-mcp
+```
+
+After global installation, the package exposes a `posprint-mcp` binary on your PATH.
+
+## MCP Client Configuration
+
+Use `posprint-mcp` as the command when the package is installed in the client environment.
+
+```json
+{
+  "mcpServers": {
+    "posprint": {
+      "command": "posprint-mcp"
+    }
+  }
+}
+```
+
+For one-off use without installation, configure the command through `npx`.
+
+```json
+{
+  "mcpServers": {
+    "posprint": {
+      "command": "npx",
+      "args": ["--yes", "@bestimmaa/posprint-mcp"]
+    }
+  }
+}
+```
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+Run the local server from source:
+
+```bash
+npm run dev
+```
+
+Run the built server:
+
+```bash
+npm start
+```
+
+## Tool: `print`
+
+Input:
+
+- `printerUri: string`
+- `markdown: string`
+- `mode: "preview" | "confirm"`
+- `confirmationToken?: string` (required when `mode="confirm"`)
+- `options?: { copies?: number; timeoutMs?: number }`
+
+### Two-step confirmation flow
+
+1. Call `print` with `mode: "preview"`.
+2. Show the returned snippet to the user and ask for confirmation.
+3. Call `print` again with `mode: "confirm"` and the returned `confirmationToken`.
+
+Preview response includes:
+
+- `requiresConfirmation: true`
+- `confirmationToken`
+- `preview.lineCount`
+- `preview.snippet`
+- `preview.excessiveLengthWarning` (present when markdown is more than 80 lines)
+
+Confirm response shape:
+
+```json
+{ "ok": true, "meta": { "printerUri": "...", "durationMs": 20, "printedAt": "...", "jobId": "optional" } }
+```
+
+Error codes:
+
+- `VALIDATION_ERROR`
+- `PRINTER_ERROR`
+- `TIMEOUT`

package/dist/src/cli.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { startServer } from "./server.js";
+await startServer();

package/dist/src/confirmation/store.js

@@ -0,0 +1,47 @@
+import { createHash, randomUUID } from "node:crypto";
+import { AppError } from "../errors.js";
+const DEFAULT_TTL_MS = 10 * 60 * 1000;
+const confirmationStore = new Map();
+function optionsKey(options) {
+    return JSON.stringify({
+        copies: options?.copies ?? null,
+        timeoutMs: options?.timeoutMs ?? null
+    });
+}
+export function buildMarkdownHash(markdown) {
+    return createHash("sha256").update(markdown, "utf8").digest("hex");
+}
+export function createConfirmationToken(input) {
+    const token = randomUUID();
+    confirmationStore.set(token, {
+        printerUri: input.printerUri,
+        markdownHash: buildMarkdownHash(input.markdown),
+        optionsKey: optionsKey(input.options),
+        createdAt: Date.now()
+    });
+    return token;
+}
+export function consumeConfirmationToken(input, now = Date.now(), ttlMs = DEFAULT_TTL_MS) {
+    const pending = confirmationStore.get(input.confirmationToken);
+    if (!pending) {
+        throw new AppError("VALIDATION_ERROR", "Invalid confirmation token", {
+            confirmationToken: input.confirmationToken
+        });
+    }
+    if (now - pending.createdAt > ttlMs) {
+        confirmationStore.delete(input.confirmationToken);
+        throw new AppError("VALIDATION_ERROR", "Confirmation token expired", {
+            confirmationToken: input.confirmationToken
+        });
+    }
+    const incomingHash = buildMarkdownHash(input.markdown);
+    if (pending.printerUri !== input.printerUri || pending.markdownHash !== incomingHash || pending.optionsKey !== optionsKey(input.options)) {
+        throw new AppError("VALIDATION_ERROR", "Confirmation token does not match print request", {
+            confirmationToken: input.confirmationToken
+        });
+    }
+    confirmationStore.delete(input.confirmationToken);
+}
+export function clearConfirmationStoreForTests() {
+    confirmationStore.clear();
+}

package/dist/src/errors.js

@@ -0,0 +1,21 @@
+export class AppError extends Error {
+    code;
+    meta;
+    constructor(code, message, meta) {
+        super(message);
+        this.code = code;
+        this.meta = meta;
+        this.name = "AppError";
+    }
+}
+export function mapUnknownError(error) {
+    if (error instanceof AppError) {
+        return error;
+    }
+    if (error instanceof Error && /timeout/i.test(error.message)) {
+        return new AppError("TIMEOUT", "Printing timed out", { cause: error.message });
+    }
+    return new AppError("UNKNOWN_ERROR", "Unexpected printing failure", {
+        cause: error instanceof Error ? error.message : String(error)
+    });
+}

package/dist/src/printing/posprintClient.js

@@ -0,0 +1,25 @@
+import posprint from "@bestimmaa/posprint";
+const { markdownToEscpos, printRawToPrinterUri } = posprint;
+function withTimeout(promise, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`print timeout after ${timeoutMs}ms`)), timeoutMs);
+        promise
+            .then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        })
+            .catch((error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
+export async function printMarkdown(params) {
+    const { printerUri, markdown, copies = 1, timeoutMs = 15_000, charsPerLine = 42 } = params;
+    const escpos = markdownToEscpos(markdown, { charsPerLine });
+    const payload = Buffer.from(escpos);
+    for (let i = 0; i < copies; i += 1) {
+        await withTimeout(printRawToPrinterUri(printerUri, payload), timeoutMs);
+    }
+    return {};
+}

package/dist/src/server.js

@@ -0,0 +1,51 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { AppError } from "./errors.js";
+import { handlePrintReceipt } from "./tools/printReceipt.js";
+export function createServer() {
+    const server = new McpServer({
+        name: "posprint-mcp",
+        version: "0.1.0"
+    });
+    server.tool("print", "Print markdown content to a POS printer via CUPS URI. Use this when the user asks to print, print a receipt, make a hard copy, or print something out. Call with mode=preview first, then call again with mode=confirm and confirmationToken.", {
+        printerUri: z.string(),
+        markdown: z.string(),
+        mode: z.enum(["preview", "confirm"]),
+        confirmationToken: z.string().optional(),
+        options: z
+            .object({
+            copies: z.number().int().positive().optional(),
+            timeoutMs: z.number().int().positive().optional()
+        })
+            .optional()
+    }, async (args) => {
+        try {
+            const result = await handlePrintReceipt(args);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(result)
+                    }
+                ]
+            };
+        }
+        catch (error) {
+            if (error instanceof AppError) {
+                throw new Error(JSON.stringify({
+                    code: error.code,
+                    message: error.message,
+                    meta: error.meta
+                }));
+            }
+            throw error;
+        }
+    });
+    return server;
+}
+export async function startServer() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/src/tools/printReceipt.js

@@ -0,0 +1,81 @@
+import { ZodError } from "zod";
+import { createConfirmationToken, consumeConfirmationToken } from "../confirmation/store.js";
+import { AppError, mapUnknownError } from "../errors.js";
+import { printMarkdown } from "../printing/posprintClient.js";
+import { parsePrintReceiptInput } from "../validation/printReceiptSchema.js";
+const EXCESSIVE_LINE_THRESHOLD = 80;
+const PREVIEW_LINE_COUNT = 20;
+function getLineCount(markdown) {
+    return markdown.split(/\r?\n/).length;
+}
+function buildSnippet(markdown, lineCount = PREVIEW_LINE_COUNT) {
+    return markdown.split(/\r?\n/).slice(0, lineCount).join("\n");
+}
+export async function handlePrintReceipt(input) {
+    const start = Date.now();
+    try {
+        const parsed = parsePrintReceiptInput(input);
+        if (parsed.mode === "preview") {
+            const lineCount = getLineCount(parsed.markdown);
+            const confirmationToken = createConfirmationToken({
+                printerUri: parsed.printerUri,
+                markdown: parsed.markdown,
+                options: parsed.options
+            });
+            return {
+                ok: true,
+                requiresConfirmation: true,
+                confirmationToken,
+                preview: {
+                    lineCount,
+                    snippet: buildSnippet(parsed.markdown),
+                    suggestedAction: "Ask the user to confirm printing this preview or summarize it first.",
+                    ...(lineCount > EXCESSIVE_LINE_THRESHOLD
+                        ? {
+                            excessiveLengthWarning: "This printout is long (>80 lines). Consider summarizing before printing."
+                        }
+                        : {})
+                }
+            };
+        }
+        consumeConfirmationToken({
+            confirmationToken: parsed.confirmationToken,
+            printerUri: parsed.printerUri,
+            markdown: parsed.markdown,
+            options: parsed.options
+        });
+        const result = await printMarkdown({
+            printerUri: parsed.printerUri,
+            markdown: parsed.markdown,
+            copies: parsed.options?.copies,
+            timeoutMs: parsed.options?.timeoutMs
+        });
+        return {
+            ok: true,
+            meta: {
+                printerUri: parsed.printerUri,
+                durationMs: Date.now() - start,
+                printedAt: new Date().toISOString(),
+                ...(result.jobId ? { jobId: result.jobId } : {})
+            }
+        };
+    }
+    catch (error) {
+        if (error instanceof ZodError) {
+            throw new AppError("VALIDATION_ERROR", "Invalid print input", {
+                issues: error.issues
+            });
+        }
+        const mapped = mapUnknownError(error);
+        if (mapped.code === "UNKNOWN_ERROR") {
+            throw new AppError("PRINTER_ERROR", "Printer job failed", {
+                ...mapped.meta,
+                durationMs: Date.now() - start
+            });
+        }
+        throw new AppError(mapped.code, mapped.message, {
+            ...mapped.meta,
+            durationMs: Date.now() - start
+        });
+    }
+}

package/dist/src/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/validation/printReceiptSchema.js

@@ -0,0 +1,26 @@
+import { z } from "zod";
+const printReceiptSchema = z
+    .object({
+    printerUri: z.string().trim().url("printerUri must be a valid URI"),
+    markdown: z.string().min(1, "markdown cannot be empty"),
+    mode: z.enum(["preview", "confirm"]),
+    confirmationToken: z.string().min(1, "confirmationToken cannot be empty").optional(),
+    options: z
+        .object({
+        copies: z.number().int().positive().max(20).optional(),
+        timeoutMs: z.number().int().positive().max(120_000).optional()
+    })
+        .optional()
+})
+    .superRefine((value, context) => {
+    if (value.mode === "confirm" && !value.confirmationToken) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "confirmationToken is required when mode is confirm",
+            path: ["confirmationToken"]
+        });
+    }
+});
+export function parsePrintReceiptInput(input) {
+    return printReceiptSchema.parse(input);
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@bestimmaa/posprint-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for printing markdown receipts on POS printers.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "dist/src/server.js",
+  "bin": {
+    "posprint-mcp": "./dist/src/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bestimmaa/posprint-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/bestimmaa/posprint-mcp/issues"
+  },
+  "homepage": "https://github.com/bestimmaa/posprint-mcp#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "start": "node dist/src/cli.js",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "release": "node scripts/release.js"
+  },
+  "dependencies": {
+    "@bestimmaa/posprint": "^0.2.0",
+    "@modelcontextprotocol/sdk": "^1.13.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.3",
+    "vitest": "^2.1.8"
+  }
+}