mcp-3d-printer-server 1.2.20 → 1.2.22

package/dist/counterpart/service.js

@@ -0,0 +1,232 @@
+/**
+ * counterpart/1 tools for every printer type this server drives. Generic
+ * adapters supply firmware reads; this module turns them into the shared
+ * results, detects capabilities, and fetches camera snapshots.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { isAxiosError } from "axios";
+import { GenericPrinterImplementation } from "../printers/generic-base.js";
+import { BambuImplementation } from "../printers/bambu.js";
+import { COUNTERPART_CONTRACT, PRINTER_KINDS, compact, progressResult, } from "./contract.js";
+import { mapBambu } from "./progress.js";
+export const DEFAULT_SNAPSHOT_TIMEOUT_MS = 8000;
+const MAX_SNAPSHOT_BYTES = 16 * 1024 * 1024;
+const LOOPBACK = new Set(["localhost", "127.0.0.1", "::1", "[::1]", "0.0.0.0"]);
+/** No HTTP response at all (refused, timed out, unreachable): the printer is offline, not erroring. */
+function unreachable(error) {
+    return isAxiosError(error) && !error.response;
+}
+function kindOf(type) {
+    const kind = type.trim().toLowerCase();
+    if (!PRINTER_KINDS.includes(kind))
+        throw new Error(`Unsupported printer type: ${type}`);
+    return kind;
+}
+function overrideSnapshotUrl() {
+    return process.env.PRINTER_CAMERA_SNAPSHOT_URL?.trim() || undefined;
+}
+export class CounterpartService {
+    constructor(implementation, http, server, 
+    /** The slicer filament profile for a slot's material (undefined: the configured default). */
+    filamentProfile) {
+        this.implementation = implementation;
+        this.http = http;
+        this.server = server;
+        this.filamentProfile = filamentProfile;
+    }
+    generic(target) {
+        const implementation = this.implementation(target.type);
+        return implementation instanceof GenericPrinterImplementation ? implementation : undefined;
+    }
+    bambu(target) {
+        const implementation = this.implementation(target.type);
+        if (!(implementation instanceof BambuImplementation))
+            throw new Error(`Unsupported printer type: ${target.type}`);
+        return implementation;
+    }
+    async printProgress(target) {
+        const generic = this.generic(target);
+        if (!generic) {
+            const status = await this.bambu(target).getStatus(target.host, target.port, target.apiKey);
+            return mapBambu(status?.raw, new Date().toISOString(), { connected: status?.connected === true, model: process.env.BAMBU_MODEL });
+        }
+        try {
+            return await generic.observedProgress(target.host, target.port, target.apiKey);
+        }
+        catch (error) {
+            if (unreachable(error))
+                return progressResult(new Date().toISOString(), "offline", { problems: [] });
+            throw error;
+        }
+    }
+    async printerInfo(target) {
+        const kind = kindOf(target.type);
+        const generic = this.generic(target);
+        let identity = {};
+        let capabilities;
+        if (!generic) {
+            const status = await this.bambu(target).getStatus(target.host, target.port, target.apiKey).catch(() => undefined);
+            const model = typeof status?.model === "string" && status.model !== "Unknown" ? status.model : process.env.BAMBU_MODEL?.trim();
+            identity = { model: model || undefined, serial: typeof status?.serial === "string" && status.serial ? status.serial : undefined };
+            // This server has no Bambu camera, pause or resume path; bambu-printer-mcp does.
+            capabilities = {
+                progress: true, layers: true, camera: overrideSnapshotUrl() ? "http-snapshot" : "none", filaments: "none",
+                pause: false, resume: false, cancel: true, print3mf: true, gcode: true,
+            };
+        }
+        else {
+            const { host, port, apiKey } = target;
+            identity = await generic.counterpartIdentity(host, port, apiKey).catch(() => ({}));
+            const [layers, pauseResume, camera] = await Promise.all([
+                generic.reportsLayers(host, port, apiKey).catch(() => false),
+                generic.supportsPauseResume(host, port, apiKey).catch(() => false),
+                this.cameraCapability(generic, target),
+            ]);
+            capabilities = {
+                progress: true, layers, camera, filaments: "single",
+                pause: pauseResume, resume: pauseResume, cancel: true, print3mf: false, gcode: true,
+            };
+        }
+        return compact({
+            contract: COUNTERPART_CONTRACT,
+            server: this.server,
+            printer: { kind, host: target.host, ...identity },
+            capabilities,
+        });
+    }
+    /** http-snapshot when the firmware names a snapshot URL, or a conventional fallback answers with a JPEG. */
+    async cameraCapability(generic, target) {
+        if (overrideSnapshotUrl())
+            return "http-snapshot";
+        const candidates = await generic.snapshotCandidates(target.host, target.port, target.apiKey).catch(() => []);
+        if (candidates.some((candidate) => candidate.configured))
+            return "http-snapshot";
+        for (const candidate of candidates) {
+            try {
+                await this.fetchJpeg(this.resolve(candidate.url, target)[0], target, 3000);
+                return "http-snapshot";
+            }
+            catch {
+                // Not a camera.
+            }
+        }
+        return "none";
+    }
+    async filaments(target) {
+        const generic = this.generic(target);
+        if (!generic) {
+            throw new Error("Unsupported: Bambu AMS and external-spool inventory is read by bambu-printer-mcp's get_printer_filaments.");
+        }
+        const slots = await generic.counterpartFilaments(target.host, target.port, target.apiKey);
+        const profiled = await Promise.all(slots.map(async (slot) => {
+            const profile = await this.filamentProfile?.(slot.material).catch(() => undefined);
+            return profile ? { ...slot, profile } : slot;
+        }));
+        return compact({ slots: profiled });
+    }
+    async pause(target) {
+        const generic = this.generic(target);
+        if (!generic)
+            throw new Error("Unsupported: pause_print for Bambu printers is provided by bambu-printer-mcp.");
+        return generic.pauseJob(target.host, target.port, target.apiKey);
+    }
+    async resume(target) {
+        const generic = this.generic(target);
+        if (!generic)
+            throw new Error("Unsupported: resume_print for Bambu printers is provided by bambu-printer-mcp.");
+        return generic.resumeJob(target.host, target.port, target.apiKey);
+    }
+    async cameraSnapshot(target, options = {}) {
+        const timeoutMs = options.timeoutMs ?? DEFAULT_SNAPSHOT_TIMEOUT_MS;
+        if (!Number.isFinite(timeoutMs) || timeoutMs < 100 || timeoutMs > 120000)
+            throw new Error("Invalid timeout_ms: expected 100 to 120000.");
+        if (options.savePath !== undefined && (!path.isAbsolute(options.savePath) || options.savePath.includes("\0"))) {
+            throw new Error("Invalid save_path: expected an absolute file path.");
+        }
+        const deadline = Date.now() + timeoutMs;
+        const override = overrideSnapshotUrl();
+        let candidates;
+        if (override) {
+            candidates = [{ url: override, source: "env-override", configured: true }];
+        }
+        else {
+            const generic = this.generic(target);
+            if (!generic)
+                throw new Error("Unsupported: this server has no Bambu camera path. Use bambu-printer-mcp's camera_snapshot, or set PRINTER_CAMERA_SNAPSHOT_URL.");
+            candidates = await generic.snapshotCandidates(target.host, target.port, target.apiKey);
+            if (!candidates.length) {
+                throw new Error(`Unsupported: ${kindOf(target.type)} exposes no camera snapshot URL. Set PRINTER_CAMERA_SNAPSHOT_URL to a JPEG snapshot URL for this printer.`);
+            }
+        }
+        const urls = [...new Set(candidates.flatMap((candidate) => this.resolve(candidate.url, target).map((url) => `${candidate.source}\n${url}`)))];
+        const failures = [];
+        for (const entry of urls) {
+            const [source, url] = entry.split("\n");
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                break;
+            try {
+                const jpeg = await this.fetchJpeg(url, target, remaining);
+                const capturedAt = new Date().toISOString();
+                let savedTo;
+                if (options.savePath) {
+                    await fs.writeFile(options.savePath, jpeg);
+                    savedTo = options.savePath;
+                }
+                return compact({ status: "success", format: "image/jpeg", sizeBytes: jpeg.length, base64: jpeg.toString("base64"), savedTo, capturedAt, source });
+            }
+            catch (error) {
+                failures.push(`${new URL(url).origin}${new URL(url).pathname}: ${error.message}`);
+            }
+        }
+        throw new Error(`No camera snapshot within ${timeoutMs} ms. Tried ${failures.length ? failures.join("; ") : "no URL before the deadline"}.`);
+    }
+    /**
+     * Snapshot URLs are written from the printer host's point of view: relative
+     * paths and loopback hosts mean the printer itself.
+     */
+    resolve(raw, target) {
+        const host = target.host.includes(":") && !target.host.startsWith("[") ? `[${target.host}]` : target.host;
+        let parsed;
+        try {
+            parsed = new URL(raw);
+        }
+        catch {
+            // Relative to the printer host: the web front end on port 80, then the API port.
+            const pathPart = raw.startsWith("/") ? raw : `/${raw}`;
+            return [...new Set([`http://${host}${pathPart}`, `http://${host}:${target.port}${pathPart}`])];
+        }
+        if (!["http:", "https:"].includes(parsed.protocol))
+            throw new Error(`Unsupported snapshot URL scheme: ${parsed.protocol}`);
+        if (LOOPBACK.has(parsed.hostname) && !LOOPBACK.has(target.host))
+            parsed.hostname = target.host;
+        // "localhost" can resolve to ::1 first, and Node 18 has no IPv4 fallback for it: try both loopbacks.
+        if (parsed.hostname === "localhost") {
+            const v4 = new URL(parsed.toString());
+            v4.hostname = "127.0.0.1";
+            const v6 = new URL(parsed.toString());
+            v6.hostname = "[::1]";
+            return [v4.toString(), v6.toString()];
+        }
+        return [parsed.toString()];
+    }
+    async fetchJpeg(url, target, timeout) {
+        const parsed = new URL(url);
+        // The API key goes only to the printer's own API origin, never to another host.
+        const sameOrigin = parsed.origin === new URL(`http://${target.host}:${target.port}`).origin;
+        const headers = sameOrigin && target.apiKey && target.type.toLowerCase() !== "bambu" ? { "X-Api-Key": target.apiKey } : {};
+        const response = await this.http.get(url, {
+            headers,
+            responseType: "arraybuffer",
+            timeout: Math.max(1, Math.round(timeout)),
+            maxContentLength: MAX_SNAPSHOT_BYTES,
+            maxRedirects: Object.keys(headers).length ? 0 : 3,
+        });
+        const bytes = Buffer.from(response.data);
+        if (bytes.length < 4 || bytes[0] !== 0xff || bytes[1] !== 0xd8 || bytes[2] !== 0xff) {
+            throw new Error(`not a JPEG (${String(response.headers?.["content-type"] ?? "unknown type")}, ${bytes.length} bytes)`);
+        }
+        return bytes;
+    }
+}

package/dist/fusion-mcp-bridge.d.ts

@@ -0,0 +1,166 @@
+import { type CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+/** The pinned faust-machines commit (PRD §8.9). The PyPI 0.1.0 release crashes under mcp 2.x (issue #30). */
+export declare const FUSION_MCP_PINNED_COMMIT = "19b9f1e95192";
+export declare const FUSION_MCP_DEFAULT_ARGS: string[];
+/** PRD §8.9: Blender's MCP addon holds the add-in's own default, 9876, so Fusion uses 9877. */
+export declare const FUSION_ADDIN_DEFAULT_PORT = 9877;
+type Arguments = Record<string, unknown>;
+/** `open --env` applies only when it starts the app, which is the only time this runs. */
+export declare function fusionLaunchArguments(port: number): string[];
+export declare class FusionMcpBridge {
+    private session?;
+    private connecting?;
+    /** One client for the life of this server; reconnects on the next call after the transport closes. */
+    private connect;
+    private open;
+    /** Call a discovered tool once; a failure after dispatch is reported, never replayed. */
+    private invoke;
+    close(): Promise<void>;
+    /**
+     * {configured, connected, addinReachable, fusionRunning, tools[]}. connected
+     * means the server started and the add-in answered its ping. With launch:
+     * true and Fusion not running on this Mac, opens Fusion and waits up to 90 s
+     * for the add-in port.
+     */
+    status(args: Arguments, signal?: AbortSignal): Promise<Record<string, unknown>>;
+    /** Pass a call through to a discovered faust tool with its full content and errors (the blender_mcp_call contract). */
+    call(args: Arguments, signal?: AbortSignal): Promise<CallToolResult>;
+    /** A new parametric design document, so faust tools have an active design. */
+    newDesign(args: Arguments, signal?: AbortSignal): Promise<Record<string, unknown>>;
+    /**
+     * Write <name>.stl (export_stl), <name>.f3d (export_f3d) and
+     * <name>.parameters.json into output_dir. Files are staged, verified and
+     * then published without ever replacing an existing file.
+     */
+    export(args: Arguments, signal?: AbortSignal): Promise<Record<string, unknown>>;
+}
+export declare const FUSION_STATUS_OUTPUT_SCHEMA: {
+    type: "object";
+    properties: {
+        configured: {
+            type: string;
+            description: string;
+        };
+        connected: {
+            type: string;
+            description: string;
+        };
+        addinReachable: {
+            type: string;
+            description: string;
+        };
+        fusionRunning: {
+            type: string;
+        };
+        tools: {
+            type: string;
+            items: {
+                type: string;
+                properties: {
+                    name: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+        };
+        launched: {
+            type: string;
+            description: string;
+        };
+        transport: {
+            type: string;
+        };
+        pin: {
+            type: string;
+            description: string;
+        };
+        server: {
+            type: string;
+        };
+        error: {
+            type: string;
+        };
+    };
+    required: string[];
+};
+/** fusion_mcp_call passes the remote result through: its structuredContent, else an empty object. */
+export declare const FUSION_CALL_OUTPUT_SCHEMA: {
+    type: "object";
+};
+export declare const FUSION_NEW_DESIGN_OUTPUT_SCHEMA: {
+    type: "object";
+    properties: {
+        status: {
+            type: string;
+            const: string;
+        };
+        document: {
+            type: string;
+        };
+        parametric: {
+            type: string;
+        };
+    };
+    required: string[];
+};
+export declare const FUSION_EXPORT_OUTPUT_SCHEMA: {
+    type: "object";
+    properties: {
+        status: {
+            type: string;
+            const: string;
+        };
+        stl: {
+            type: string;
+            description: string;
+        };
+        f3d: {
+            type: string;
+            description: string;
+        };
+        parameters: {
+            type: string;
+            description: string;
+        };
+        body: {
+            type: string;
+        };
+        triangles: {
+            type: string;
+            minimum: number;
+        };
+        bytes: {
+            type: string;
+            minimum: number;
+        };
+        parameterCount: {
+            type: string;
+            minimum: number;
+        };
+        boundingBox: {
+            type: string;
+            description: string;
+        };
+        stlUnits: {
+            type: string;
+            enum: string[];
+            description: string;
+        };
+        fusionSizeMm: {
+            type: string;
+            items: {
+                type: string;
+            };
+            description: string;
+        };
+        warnings: {
+            type: string;
+            items: {
+                type: string;
+            };
+        };
+    };
+    required: string[];
+};
+export {};