viucraft-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BStorm IT
+
+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,47 @@
+# viucraft-mcp
+
+VIUCraft MCP server — use VIUCraft image operations as AI tools via the [Model Context Protocol](https://modelcontextprotocol.io/).
+
+This package is a **proxy**: it forwards tool calls to the VIUCraft HTTP API. No image processing happens locally.
+
+## Quick Start (Claude Desktop)
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+    "mcpServers": {
+        "viucraft": {
+            "command": "npx",
+            "args": ["viucraft-mcp"],
+            "env": {
+                "VIUCRAFT_API_KEY": "vc_live_..."
+            }
+        }
+    }
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Default |
+|----------|----------|---------|
+| `VIUCRAFT_API_KEY` | yes | — |
+| `VIUCRAFT_API_URL` | no | `https://api.viucraft.com` |
+
+## Available Tools
+
+- `resize_image` — resize to width/height with optional fit mode
+- `crop_image` — crop with optional gravity or offset
+- `convert_format` — convert to jpg/png/webp/avif/gif with optional quality
+- `apply_filter` — apply blur/grayscale/sepia/sharpen/invert/vignette/pixelate
+- `transform_image` — arbitrary operation pipeline or named preset
+
+See the [full MCP reference](https://github.com/BStorm-IT/viucraft/blob/main/docs/mcp.md) for complete tool documentation.
+
+## Build
+
+```bash
+npm install
+npm run build
+```

package/dist/index.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { handleToolCall, tools } from "./tools.js";
+const apiKey = process.env.VIUCRAFT_API_KEY;
+const apiUrl = process.env.VIUCRAFT_API_URL ?? "https://api.viucraft.com";
+if (!apiKey) {
+    process.stderr.write("VIUCRAFT_API_KEY environment variable is required\n");
+    process.exit(1);
+}
+const server = new Server({ name: "viucraft", version: "1.0.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const args = (request.params.arguments ?? {});
+    const result = await handleToolCall(request.params.name, args, apiKey, apiUrl);
+    // @modelcontextprotocol/sdk 1.29 tightened the CallTool handler's return type for its
+    // experimental "tasks" API. handleToolCall returns a valid { content, isError? } MCP
+    // result; cast to the base ServerResult to satisfy the new union (runtime unchanged).
+    return result;
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/proxy.js

@@ -0,0 +1,66 @@
+// Session-aware JSON-RPC client for the VIUCraft `/mcp` endpoint.
+//
+// The endpoint is session-based: an `initialize` call (authenticated with
+// `Authorization: Bearer <api key>`) returns an `X-MCP-Session-Id` response header that
+// must accompany every subsequent `tools/call`. The proxy establishes that session lazily
+// and re-establishes it if it expires (sessions have a ~30-minute TTL on the server).
+const SESSION_EXPIRED = -32001;
+let cachedSessionId = null;
+async function rpc(apiUrl, apiKey, body, sessionId) {
+    const headers = {
+        // The /mcp endpoint authenticates via Authorization: Bearer (NOT X-API-Key).
+        "Authorization": `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+    };
+    if (sessionId) {
+        headers["X-MCP-Session-Id"] = sessionId;
+    }
+    const response = await fetch(`${apiUrl}/mcp`, {
+        body: JSON.stringify(body),
+        headers,
+        method: "POST",
+    });
+    const returnedSession = response.headers.get("x-mcp-session-id");
+    const json = (await response.json());
+    return { json, sessionId: returnedSession };
+}
+async function initializeSession(apiUrl, apiKey) {
+    const { json, sessionId } = await rpc(apiUrl, apiKey, {
+        id: 0,
+        jsonrpc: "2.0",
+        method: "initialize",
+        params: {
+            capabilities: {},
+            clientInfo: { name: "viucraft-mcp-proxy", version: "1.0.0" },
+            protocolVersion: "2024-11-05",
+        },
+    }, null);
+    if (json.error) {
+        throw new Error(`MCP initialize failed: ${json.error.message}`);
+    }
+    if (!sessionId) {
+        throw new Error("MCP initialize did not return a session id");
+    }
+    return sessionId;
+}
+/**
+ * Call a tool on the backend, transparently establishing (and refreshing) the MCP session.
+ */
+export async function callTool(name, args, apiKey, apiUrl) {
+    if (!cachedSessionId) {
+        cachedSessionId = await initializeSession(apiUrl, apiKey);
+    }
+    const toolCall = {
+        id: 1,
+        jsonrpc: "2.0",
+        method: "tools/call",
+        params: { arguments: args, name },
+    };
+    let { json } = await rpc(apiUrl, apiKey, toolCall, cachedSessionId);
+    // The session may have expired between calls — re-establish it once and retry.
+    if (json.error?.code === SESSION_EXPIRED) {
+        cachedSessionId = await initializeSession(apiUrl, apiKey);
+        ({ json } = await rpc(apiUrl, apiKey, toolCall, cachedSessionId));
+    }
+    return json;
+}

package/dist/tools.js

@@ -0,0 +1,239 @@
+export const tools = [
+    {
+        description: "Returns a VIUCraft URL that resizes an image to the specified dimensions.",
+        inputSchema: {
+            properties: {
+                fit: {
+                    description: "Fit mode for resizing.",
+                    enum: ["contain", "cover", "fill", "inside", "outside"],
+                    type: "string",
+                },
+                height: {
+                    description: "Target height in pixels.",
+                    minimum: 1,
+                    type: "integer",
+                },
+                image_id: {
+                    description: "The UUID of the image to resize.",
+                    type: "string",
+                },
+                width: {
+                    description: "Target width in pixels.",
+                    minimum: 1,
+                    type: "integer",
+                },
+            },
+            required: ["image_id"],
+            type: "object",
+        },
+        name: "resize_image",
+    },
+    {
+        description: "Returns a VIUCraft URL that crops an image to the specified dimensions and optional gravity or offset.",
+        inputSchema: {
+            properties: {
+                gravity: {
+                    description: "Gravity / focal point for the crop.",
+                    enum: ["center", "east", "north", "smart", "south", "west"],
+                    type: "string",
+                },
+                height: {
+                    description: "Crop height in pixels.",
+                    minimum: 1,
+                    type: "integer",
+                },
+                image_id: {
+                    description: "The UUID of the image to crop.",
+                    type: "string",
+                },
+                width: {
+                    description: "Crop width in pixels.",
+                    minimum: 1,
+                    type: "integer",
+                },
+                x: {
+                    description: "Horizontal offset in pixels (used with manual crop).",
+                    minimum: 0,
+                    type: "integer",
+                },
+                y: {
+                    description: "Vertical offset in pixels (used with manual crop).",
+                    minimum: 0,
+                    type: "integer",
+                },
+            },
+            required: ["height", "image_id", "width"],
+            type: "object",
+        },
+        name: "crop_image",
+    },
+    {
+        description: "Returns a VIUCraft URL that converts an image to the specified format and optional quality.",
+        inputSchema: {
+            properties: {
+                format: {
+                    description: "Target output format.",
+                    enum: ["avif", "gif", "jpg", "png", "webp"],
+                    type: "string",
+                },
+                image_id: {
+                    description: "The UUID of the image to convert.",
+                    type: "string",
+                },
+                quality: {
+                    description: "Output quality (1–100). Applicable to jpg, webp, and avif.",
+                    maximum: 100,
+                    minimum: 1,
+                    type: "integer",
+                },
+            },
+            required: ["format", "image_id"],
+            type: "object",
+        },
+        name: "convert_format",
+    },
+    {
+        description: "Returns a VIUCraft URL that applies a visual filter effect to an image.",
+        inputSchema: {
+            properties: {
+                filter: {
+                    description: "The visual filter to apply.",
+                    enum: ["blur", "grayscale", "invert", "pixelate", "sepia", "sharpen", "vignette"],
+                    type: "string",
+                },
+                image_id: {
+                    description: "The UUID of the image to filter.",
+                    type: "string",
+                },
+                intensity: {
+                    description: "Filter intensity between 0 (none) and 1 (full). Defaults to 1.",
+                    maximum: 1,
+                    minimum: 0,
+                    type: "number",
+                },
+            },
+            required: ["filter", "image_id"],
+            type: "object",
+        },
+        name: "apply_filter",
+    },
+    {
+        description: "Builds a VIUCraft processing URL for an image by applying one or more operations. Supports arbitrary operation pipelines or a named preset.",
+        inputSchema: {
+            properties: {
+                image_id: {
+                    description: "The UUID of the image to transform.",
+                    type: "string",
+                },
+                operations: {
+                    description: "Array of operations to apply, each with a name and params map.",
+                    items: {
+                        properties: {
+                            name: {
+                                description: "Operation name (e.g. resize, crop, blur).",
+                                type: "string",
+                            },
+                            params: {
+                                additionalProperties: true,
+                                description: "Key-value parameters for the operation.",
+                                type: "object",
+                            },
+                        },
+                        required: ["name"],
+                        type: "object",
+                    },
+                    type: "array",
+                },
+                output_format: {
+                    description: "Desired output format (jpg, png, webp, avif, gif). Defaults to webp.",
+                    enum: ["avif", "gif", "jpg", "png", "webp"],
+                    type: "string",
+                },
+                preset: {
+                    description: "Named preset to apply (e.g. thumbnail, social, banner).",
+                    type: "string",
+                },
+            },
+            required: ["image_id"],
+            type: "object",
+        },
+        name: "transform_image",
+    },
+    {
+        description: "Returns the authenticated account: plan, subdomain, account id, the canonical image URL base " +
+            "to build delivery URLs against, current usage/quota, and the full capability set. Call this " +
+            "first to learn your subdomain so you can turn relative transform paths into absolute URLs.",
+        inputSchema: {
+            properties: {},
+            required: [],
+            type: "object",
+        },
+        name: "whoami",
+    },
+    {
+        description: "Uploads an image (passed as base64-encoded data) and returns its permanent image_id plus " +
+            "metadata. Use the returned image_id with the transform tools to build delivery URLs. " +
+            "Identical re-uploads return the existing image.",
+        inputSchema: {
+            properties: {
+                data: {
+                    description: "The image file contents, base64-encoded.",
+                    type: "string",
+                },
+                filename: {
+                    description: 'Original filename including extension, e.g. "photo.png".',
+                    type: "string",
+                },
+                folder: {
+                    description: 'Optional virtual folder to store the image in (defaults to "/").',
+                    type: "string",
+                },
+            },
+            required: ["data", "filename"],
+            type: "object",
+        },
+        name: "upload_image",
+    },
+    {
+        description: "Permanently deletes one of your images by its UUID. Frees the storage quota and fires the " +
+            "image.deleted webhook. This cannot be undone.",
+        inputSchema: {
+            properties: {
+                image_id: {
+                    description: "The UUID of the image to delete.",
+                    type: "string",
+                },
+            },
+            required: ["image_id"],
+            type: "object",
+        },
+        name: "delete_image",
+    },
+];
+import { callTool } from "./proxy.js";
+export async function handleToolCall(name, args, apiKey, apiUrl) {
+    try {
+        const result = await callTool(name, args, apiKey, apiUrl);
+        if (result.error) {
+            return {
+                content: [{ text: `VIUCraft error: ${result.error.message}`, type: "text" }],
+                isError: true,
+            };
+        }
+        if (result.result?.content) {
+            return {
+                content: result.result.content,
+                isError: result.result.isError,
+            };
+        }
+        return {
+            content: [{ text: JSON.stringify(result), type: "text" }],
+        };
+    }
+    catch (err) {
+        return {
+            content: [{ text: `Error calling VIUCraft API: ${String(err)}`, type: "text" }],
+            isError: true,
+        };
+    }
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+    "name": "viucraft-mcp",
+    "version": "1.0.0",
+    "description": "VIUCraft MCP server — use VIUCraft image operations as AI tools",
+    "type": "module",
+    "license": "MIT",
+    "author": "BStorm IT",
+    "homepage": "https://github.com/BStorm-IT/viucraft-mcp#readme",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/BStorm-IT/viucraft-mcp.git"
+    },
+    "bugs": {
+        "url": "https://github.com/BStorm-IT/viucraft-mcp/issues"
+    },
+    "keywords": [
+        "viucraft",
+        "mcp",
+        "model-context-protocol",
+        "image-processing",
+        "ai-tools"
+    ],
+    "engines": {
+        "node": ">=18"
+    },
+    "bin": {"viucraft-mcp": "./dist/index.js"},
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "typecheck": "tsc --noEmit",
+        "start": "node dist/index.js",
+        "prepublishOnly": "npm run build"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "^1.0.0"
+    },
+    "devDependencies": {
+        "@types/node": "^20.0.0",
+        "typescript": "^5.3.0"
+    }
+}