repositories / dotfiles
dotfiles
bugabingas dorkfiles
owned by bugabinga
opencode/tools/image.ts
Rawimport { tool } from "@opencode-ai/plugin";
import sharp from "sharp";
import path from "node:path";
import { existsSync, mkdirSync, statSync } from "node:fs";
// ============================================================================
// Security Constants
// ============================================================================
const MAX_FILE_SIZE = 50 * 1024 * 1024; // 50MB
const MAX_PIXELS = 100000000; // 100 megapixels
const MAX_DIMENSION = 20000; // 20,000px
const MAX_BASE64_SIZE = 10 * 1024 * 1024; // 10MB
const SUPPORTED_FORMATS = [
"jpeg",
"jpg",
"png",
"webp",
"avif",
"gif",
"tiff",
"heif",
] as const;
// Supported sharp format type
type SharpFormat = (typeof SUPPORTED_FORMATS)[number] extends infer T
? T extends "jpg" ? never
: T
: never;
// ============================================================================
// Helper Functions
// ============================================================================
/**
* Create a JSON response string
*/
function jsonResponse(data: Record<string, unknown>): string {
return JSON.stringify(data, null, 2);
}
/**
* Assert that a target path stays within the specified directory
* Prevents path traversal attacks
*/
function assertWithinDirectory(
targetPath: string,
directory: string,
operation: string,
): void {
const resolvedTarget = path.resolve(targetPath);
const resolvedDir = path.resolve(directory);
const dirWithSep = resolvedDir.endsWith(path.sep)
? resolvedDir
: resolvedDir + path.sep;
if (
resolvedTarget !== resolvedDir &&
!resolvedTarget.startsWith(dirWithSep)
) {
throw new Error(
`Path security error: ${operation}: path escapes working directory: ${targetPath}`,
);
}
}
/**
* Check if input is a base64 data URI
*/
function isBase64DataUri(input: string): boolean {
return input.startsWith("data:image/") && input.includes(";base64,");
}
/**
* Decode a base64 data URI to a Buffer
*/
function decodeBase64DataUri(uri: string): Buffer {
const matches = uri.match(/^data:image\/(\w+);base64,(.+)$/);
if (!matches || !matches[1] || !matches[2]) {
throw new Error("Invalid base64 data URI format");
}
const base64Data = matches[2];
// Check size limit
if (base64Data.length > MAX_BASE64_SIZE * 1.37) {
// Base64 is ~37% larger
throw new Error(
`Base64 data exceeds maximum size of ${MAX_BASE64_SIZE} bytes`,
);
}
return Buffer.from(base64Data, "base64");
}
/**
* Resolve a file path relative to the context directory
*/
function resolveFilePath(inputPath: string, directory: string): string {
const trimmed = inputPath.trim();
const fullPath = path.resolve(directory, trimmed);
assertWithinDirectory(fullPath, directory, "resolveFilePath");
return fullPath;
}
/**
* Validate image dimensions
*/
function validateDimensions(width?: number, height?: number): string | null {
if (width !== undefined) {
if (width <= 0) {
return "Width must be a positive number";
}
if (width > MAX_DIMENSION) {
return `Width exceeds maximum dimension of ${MAX_DIMENSION}px`;
}
}
if (height !== undefined) {
if (height <= 0) {
return "Height must be a positive number";
}
if (height > MAX_DIMENSION) {
return `Height exceeds maximum dimension of ${MAX_DIMENSION}px`;
}
}
if (width !== undefined && height !== undefined) {
const pixels = width * height;
if (pixels > MAX_PIXELS) {
return `Image dimensions exceed maximum of ${MAX_PIXELS} pixels (${
MAX_PIXELS / 1000000
} megapixels)`;
}
}
return null;
}
/**
* Validate output format
*/
function validateFormat(format: string): string | null {
const normalized = format.toLowerCase();
if (
!SUPPORTED_FORMATS.includes(normalized as typeof SUPPORTED_FORMATS[number])
) {
return `Invalid format: "${format}". Supported formats: ${
SUPPORTED_FORMATS.join(", ")
}`;
}
return null;
}
/**
* Validate blur/sharpen sigma
*/
function validateSigma(sigma: number): string | null {
if (sigma < 0.3 || sigma > 1000) {
return "Sigma must be between 0.3 and 1000";
}
return null;
}
/**
* Parse image input - accepts file path or base64 data URI
*/
async function parseImageInput(
input: string,
directory: string,
): Promise<{ buffer: Buffer | string; sourceType: "file" | "base64" }> {
if (isBase64DataUri(input)) {
return {
buffer: decodeBase64DataUri(input),
sourceType: "base64",
};
}
const fullPath = resolveFilePath(input, directory);
if (!existsSync(fullPath)) {
throw new Error(`Image not found: ${input}`);
}
const stats = statSync(fullPath);
if (stats.size > MAX_FILE_SIZE) {
throw new Error(
`Image file exceeds maximum size of ${MAX_FILE_SIZE / 1024 / 1024}MB`,
);
}
return {
buffer: fullPath,
sourceType: "file",
};
}
/**
* Validate image metadata against security constraints
*/
async function validateImageSecurity(
imagePathOrBuffer: Buffer | string,
): Promise<void> {
const metadata = await sharp(imagePathOrBuffer).metadata();
if (metadata.width && metadata.width > MAX_DIMENSION) {
throw new Error(
`Image width (${metadata.width}px) exceeds maximum of ${MAX_DIMENSION}px`,
);
}
if (metadata.height && metadata.height > MAX_DIMENSION) {
throw new Error(
`Image height (${metadata.height}px) exceeds maximum of ${MAX_DIMENSION}px`,
);
}
if (metadata.width && metadata.height) {
const pixels = metadata.width * metadata.height;
if (pixels > MAX_PIXELS) {
throw new Error(
`Image (${pixels} pixels) exceeds maximum of ${MAX_PIXELS} pixels`,
);
}
}
}
/**
* Determine output path for processed image
*/
function determineOutputPath(
inputPath: string | null,
suffix: string,
format: string,
directory: string,
): string {
const outputDir = path.join(directory, ".output");
// Ensure output directory exists
if (!existsSync(outputDir)) {
mkdirSync(outputDir, { recursive: true });
}
if (inputPath) {
const baseName = path.basename(inputPath, path.extname(inputPath));
return path.join(outputDir, `${baseName}${suffix}.${format}`);
}
const timestamp = Date.now();
return path.join(outputDir, `image${suffix}-${timestamp}.${format}`);
}
/**
* Get format from metadata or default to jpeg
*/
function getFormatFromMetadata(metadata: sharp.Metadata): SharpFormat {
if (metadata.format) {
const normalized = metadata.format === "jpg" ? "jpeg" : metadata.format;
if (
SUPPORTED_FORMATS.includes(normalized as typeof SUPPORTED_FORMATS[number])
) {
return normalized as SharpFormat;
}
}
return "jpeg";
}
/**
* Format file size for human readability
*/
function formatFileSize(bytes: number): string {
const units = ["B", "KB", "MB", "GB"];
let size = bytes;
let unitIndex = 0;
while (size >= 1024 && unitIndex < units.length - 1) {
size /= 1024;
unitIndex++;
}
return `${size.toFixed(2)} ${units[unitIndex]}`;
}
/**
* Extract error message from unknown error
*/
function getErrorMessage(err: unknown): string {
if (err instanceof Error) {
return err.message;
}
return String(err);
}
// ============================================================================
// Tool 1: image_resize
// ============================================================================
export const image_resize = tool({
description:
`Resize an image with various fit options and interpolation kernels.
Fit options:
- cover: Crop to fill both dimensions (default)
- contain: Fit within dimensions, may add letterboxing
- fill: Ignore aspect ratio, stretch to exact dimensions
- inside: Fit within dimensions without cropping
- outside: Fill dimensions, may exceed bounds
Kernel options:
- nearest: Fastest, pixelated results
- cubic: Good balance of speed and quality
- mitchell: High quality, slower
- lanczos2: High quality, good for downscaling
- lanczos3: Highest quality, slowest (default)
Examples:
- Resize to 800x600 with cover fit: image_resize({ input: "photo.jpg", width: 800, height: 600 })
- Resize maintaining aspect ratio: image_resize({ input: "photo.jpg", width: 800 })
- Prevent upscaling: image_resize({ input: "photo.jpg", width: 800, withoutEnlargement: true })
- Return as base64: image_resize({ input: "photo.jpg", width: 800, returnBase64: true })`,
args: {
input: tool.schema
.string()
.describe(
"Image file path (relative to working directory) or base64 data URI",
),
width: tool.schema
.number()
.optional()
.describe(
"Target width in pixels. Omit to auto-scale based on height.",
),
height: tool.schema
.number()
.optional()
.describe(
"Target height in pixels. Omit to auto-scale based on width.",
),
fit: tool.schema
.enum(["cover", "contain", "fill", "inside", "outside"])
.default("cover")
.describe("How the image should fit the dimensions. Default: cover"),
position: tool.schema
.string()
.default("center")
.describe(
"Position for cropping (cover/contain): center, top, bottom, left, right, etc. Default: center",
),
kernel: tool.schema
.enum(["nearest", "cubic", "mitchell", "lanczos2", "lanczos3"])
.default("lanczos3")
.describe("Interpolation kernel for resizing. Default: lanczos3"),
withoutEnlargement: tool.schema
.boolean()
.default(false)
.describe(
"Do not upscale if image is smaller than target dimensions",
),
returnBase64: tool.schema
.boolean()
.default(false)
.describe("Return base64 data URI instead of file path"),
},
async execute(args, context) {
try {
// Validate dimensions
const dimError = validateDimensions(args.width, args.height);
if (dimError) {
return jsonResponse({
success: false,
error: `Validation error: ${dimError}`,
});
}
if (!args.width && !args.height) {
return jsonResponse({
success: false,
error:
"Validation error: At least one of width or height must be specified",
});
}
// Parse input
const { buffer, sourceType } = await parseImageInput(
args.input,
context.directory,
);
// Validate security
await validateImageSecurity(buffer);
// Get metadata for format detection
const metadata = await sharp(buffer).metadata();
const format = getFormatFromMetadata(metadata);
// Build resize options
const resizeOptions: sharp.ResizeOptions = {
width: args.width,
height: args.height,
fit: args.fit as sharp.FitEnum[keyof sharp.FitEnum],
position: args.position as sharp.Gravity,
kernel: args.kernel as sharp.KernelEnum[keyof sharp.KernelEnum],
withoutEnlargement: args.withoutEnlargement,
};
let pipeline = sharp(buffer).resize(resizeOptions);
if (args.returnBase64) {
const outputBuffer = await pipeline
.toFormat(format)
.toBuffer();
const base64 = outputBuffer.toString("base64");
return jsonResponse({
success: true,
operation: "resize",
data: `data:image/${format};base64,${base64}`,
format,
width: args.width,
height: args.height,
fit: args.fit,
});
}
// Save to file
const suffix = args.width && args.height
? `-resize-${args.width}x${args.height}`
: args.width
? `-resize-${args.width}w`
: `-resize-${args.height}h`;
const outputPath = determineOutputPath(
sourceType === "file" ? args.input : null,
suffix,
format,
context.directory,
);
await pipeline.toFormat(format).toFile(outputPath);
const outputStats = statSync(outputPath);
const outputMeta = await sharp(outputPath).metadata();
return jsonResponse({
success: true,
operation: "resize",
input: sourceType === "file" ? args.input : "(base64 data)",
output: path.relative(context.directory, outputPath),
format,
width: outputMeta.width,
height: outputMeta.height,
size_bytes: outputStats.size,
size_human: formatFileSize(outputStats.size),
options: {
width: args.width,
height: args.height,
fit: args.fit,
position: args.position,
kernel: args.kernel,
withoutEnlargement: args.withoutEnlargement,
},
});
} catch (err) {
return jsonResponse({
success: false,
error: getErrorMessage(err),
});
}
},
});
// ============================================================================
// Tool 2: image_crop
// ============================================================================
export const image_crop = tool({
description: `Extract a rectangular region from an image.
Specify the region using left, top coordinates (top-left corner) and dimensions.
Examples:
- Extract 200x150 region starting at (100, 50): image_crop({ input: "photo.jpg", left: 100, top: 50, width: 200, height: 150 })
- Crop from top-left corner: image_crop({ input: "photo.jpg", left: 0, top: 0, width: 500, height: 500 })
- Return as base64: image_crop({ input: "photo.jpg", left: 100, top: 100, width: 300, height: 200, returnBase64: true })`,
args: {
input: tool.schema
.string()
.describe(
"Image file path (relative to working directory) or base64 data URI",
),
left: tool.schema
.number()
.describe(
"Left offset (x-coordinate) in pixels from the top-left corner",
),
top: tool.schema
.number()
.describe(
"Top offset (y-coordinate) in pixels from the top-left corner",
),
width: tool.schema
.number()
.describe("Width of the region to extract in pixels"),
height: tool.schema
.number()
.describe("Height of the region to extract in pixels"),
returnBase64: tool.schema
.boolean()
.default(false)
.describe("Return base64 data URI instead of file path"),
},
async execute(args, context) {
try {
// Validate crop parameters
if (args.left < 0 || args.top < 0) {
return jsonResponse({
success: false,
error:
"Validation error: Left and top coordinates must be non-negative",
});
}
const dimError = validateDimensions(args.width, args.height);
if (dimError) {
return jsonResponse({
success: false,
error: `Validation error: ${dimError}`,
});
}
// Parse input
const { buffer, sourceType } = await parseImageInput(
args.input,
context.directory,
);
// Validate security
await validateImageSecurity(buffer);
// Get metadata for format detection
const metadata = await sharp(buffer).metadata();
const format = getFormatFromMetadata(metadata);
// Perform crop
const pipeline = sharp(buffer).extract({
left: args.left,
top: args.top,
width: args.width,
height: args.height,
});
if (args.returnBase64) {
const outputBuffer = await pipeline
.toFormat(format)
.toBuffer();
const base64 = outputBuffer.toString("base64");
return jsonResponse({
success: true,
operation: "crop",
data: `data:image/${format};base64,${base64}`,
format,
region: {
left: args.left,
top: args.top,
width: args.width,
height: args.height,
},
});
}
// Save to file
const suffix = `-crop-${args.width}x${args.height}`;
const outputPath = determineOutputPath(
sourceType === "file" ? args.input : null,
suffix,
format,
context.directory,
);
await pipeline.toFormat(format).toFile(outputPath);
const outputStats = statSync(outputPath);
return jsonResponse({
success: true,
operation: "crop",
input: sourceType === "file" ? args.input : "(base64 data)",
output: path.relative(context.directory, outputPath),
format,
size_bytes: outputStats.size,
size_human: formatFileSize(outputStats.size),
region: {
left: args.left,
top: args.top,
width: args.width,
height: args.height,
},
});
} catch (err) {
return jsonResponse({
success: false,
error: getErrorMessage(err),
});
}
},
});
// ============================================================================
// Tool 3: image_rotate
// ============================================================================
export const image_rotate = tool({
description: `Rotate an image by a specified angle.
Rotation angles are clockwise. Common angles: 90, 180, 270.
For arbitrary angles, a background color can be specified for areas not covered by the rotated image.
Examples:
- Rotate 90 degrees clockwise: image_rotate({ input: "photo.jpg", angle: 90 })
- Rotate 180 degrees: image_rotate({ input: "photo.jpg", angle: 180 })
- Rotate 45 degrees with white background: image_rotate({ input: "photo.jpg", angle: 45, background: "#ffffff" })
- Return as base64: image_rotate({ input: "photo.jpg", angle: 90, returnBase64: true })`,
args: {
input: tool.schema
.string()
.describe(
"Image file path (relative to working directory) or base64 data URI",
),
angle: tool.schema
.number()
.describe("Rotation angle in degrees (clockwise)"),
background: tool.schema
.string()
.optional()
.describe(
'Background color for non-rectangular rotations (CSS color string, e.g., "#ffffff", "rgba(0,0,0,0.5)"). Default: transparent',
),
returnBase64: tool.schema
.boolean()
.default(false)
.describe("Return base64 data URI instead of file path"),
},
async execute(args, context) {
try {
// Parse input
const { buffer, sourceType } = await parseImageInput(
args.input,
context.directory,
);
// Validate security
await validateImageSecurity(buffer);
// Get metadata for format detection
const metadata = await sharp(buffer).metadata();
const format = getFormatFromMetadata(metadata);
// Build rotate options
const rotateOptions: sharp.RotateOptions = {};
if (args.background) {
rotateOptions.background = args.background;
}
const pipeline = sharp(buffer).rotate(args.angle, rotateOptions);
if (args.returnBase64) {
const outputBuffer = await pipeline
.toFormat(format)
.toBuffer();
const base64 = outputBuffer.toString("base64");
return jsonResponse({
success: true,
operation: "rotate",
data: `data:image/${format};base64,${base64}`,
format,
angle: args.angle,
});
}
// Save to file
const suffix = `-rotate-${args.angle}`;
const outputPath = determineOutputPath(
sourceType === "file" ? args.input : null,
suffix,
format,
context.directory,
);
await pipeline.toFormat(format).toFile(outputPath);
const outputStats = statSync(outputPath);
const outputMeta = await sharp(outputPath).metadata();
return jsonResponse({
success: true,
operation: "rotate",
input: sourceType === "file" ? args.input : "(base64 data)",
output: path.relative(context.directory, outputPath),
format,
width: outputMeta.width,
height: outputMeta.height,
size_bytes: outputStats.size,
size_human: formatFileSize(outputStats.size),
angle: args.angle,
background: args.background || "transparent",
});
} catch (err) {
return jsonResponse({
success: false,
error: getErrorMessage(err),
});
}
},
});
// ============================================================================
// Tool 4: image_flip
// ============================================================================
export const image_flip = tool({
description: `Flip an image horizontally (flop), vertically (flip), or both.
Examples:
- Flip horizontally (mirror left-right): image_flip({ input: "photo.jpg", horizontal: true })
- Flip vertically (mirror top-bottom): image_flip({ input: "photo.jpg", vertical: true })
- Flip both axes: image_flip({ input: "photo.jpg", horizontal: true, vertical: true })
- Return as base64: image_flip({ input: "photo.jpg", horizontal: true, returnBase64: true })`,
args: {
input: tool.schema
.string()
.describe(
"Image file path (relative to working directory) or base64 data URI",
),
vertical: tool.schema
.boolean()
.default(false)
.describe("Flip vertically (mirror top-bottom)"),
horizontal: tool.schema
.boolean()
.default(false)
.describe("Flip horizontally (mirror left-right)"),
returnBase64: tool.schema
.boolean()
.default(false)
.describe("Return base64 data URI instead of file path"),
},
async execute(args, context) {
try {
if (!args.vertical && !args.horizontal) {
return jsonResponse({
success: false,
error:
"Validation error: At least one of vertical or horizontal must be true",
});
}
// Parse input
const { buffer, sourceType } = await parseImageInput(
args.input,
context.directory,
);
// Validate security
await validateImageSecurity(buffer);
// Get metadata for format detection
const metadata = await sharp(buffer).metadata();
const format = getFormatFromMetadata(metadata);
let pipeline = sharp(buffer);
if (args.vertical) {
pipeline = pipeline.flip();
}
if (args.horizontal) {
pipeline = pipeline.flop();
}
if (args.returnBase64) {
const outputBuffer = await pipeline
.toFormat(format)
.toBuffer();
const base64 = outputBuffer.toString("base64");
return jsonResponse({
success: true,
operation: "flip",
data: `data:image/${format};base64,${base64}`,
format,
vertical: args.vertical,
horizontal: args.horizontal,
});
}
// Save to file
const flipType: string[] = [];
if (args.vertical) flipType.push("v");
if (args.horizontal) flipType.push("h");
const suffix = `-flip-${flipType.join("")}`;
const outputPath = determineOutputPath(
sourceType === "file" ? args.input : null,
suffix,
format,
context.directory,
);
await pipeline.toFormat(format).toFile(outputPath);
const outputStats = statSync(outputPath);
return jsonResponse({
success: true,
operation: "flip",
input: sourceType === "file" ? args.input : "(base64 data)",
output: path.relative(context.directory, outputPath),
format,
size_bytes: outputStats.size,
size_human: formatFileSize(outputStats.size),
vertical: args.vertical,
horizontal: args.horizontal,
});
} catch (err) {
return jsonResponse({
success: false,
error: getErrorMessage(err),
});
}
},
});
// ============================================================================
// Tool 5: image_grayscale
// ============================================================================
export const image_grayscale = tool({
description: `Convert an image to grayscale (black and white).
Examples:
- Convert to grayscale: image_grayscale({ input: "photo.jpg" })
- Return as base64: image_grayscale({ input: "photo.jpg", returnBase64: true })`,
args: {
input: tool.schema
.string()
.describe(
"Image file path (relative to working directory) or base64 data URI",
),
returnBase64: tool.schema
.boolean()
.default(false)
.describe("Return base64 data URI instead of file path"),
},
async execute(args, context) {
try {
// Parse input
const { buffer, sourceType } = await parseImageInput(
args.input,
context.directory,
);
// Validate security
await validateImageSecurity(buffer);
// Get metadata for format detection
const metadata = await sharp(buffer).metadata();
const format = getFormatFromMetadata(metadata);
const pipeline = sharp(buffer).grayscale();
if (args.returnBase64) {
const outputBuffer = await pipeline
.toFormat(format)
.toBuffer();
const base64 = outputBuffer.toString("base64");
return jsonResponse({
success: true,
operation: "grayscale",
data: `data:image/${format};base64,${base64}`,
format,
});
}
// Save to file
const suffix = "-grayscale";
const outputPath = determineOutputPath(
sourceType === "file" ? args.input : null,
suffix,
format,
context.directory,
);
await pipeline.toFormat(format).toFile(outputPath);
const outputStats = statSync(outputPath);
return jsonResponse({
success: true,
operation: "grayscale",
input: sourceType === "file" ? args.input : "(base64 data)",
output: path.relative(context.directory, outputPath),
format,
size_bytes: outputStats.size,
size_human: formatFileSize(outputStats.size),
});
} catch (err) {
return jsonResponse({
success: false,
error: getErrorMessage(err),
});
}
},
});
// ============================================================================
// Tool 6: image_blur
// ============================================================================
export const image_blur = tool({
description: `Apply Gaussian blur to an image.
The sigma parameter controls the strength of the blur effect. Higher values produce more blur.
Range: 0.3 to 1000. Typical values: 1-20 for visible blur.
Examples:
- Light blur: image_blur({ input: "photo.jpg", sigma: 3 })
- Heavy blur: image_blur({ input: "photo.jpg", sigma: 15 })
- Return as base64: image_blur({ input: "photo.jpg", sigma: 5, returnBase64: true })`,
args: {
input: tool.schema
.string()
.describe(
"Image file path (relative to working directory) or base64 data URI",
),
sigma: tool.schema
.number()
.min(0.3)
.max(1000)
.describe(
"Blur radius (sigma). Range: 0.3-1000. Higher = more blur.",
),
returnBase64: tool.schema
.boolean()
.default(false)
.describe("Return base64 data URI instead of file path"),
},
async execute(args, context) {
try {
// Validate sigma
const sigmaError = validateSigma(args.sigma);
if (sigmaError) {
return jsonResponse({
success: false,
error: `Validation error: ${sigmaError}`,
});
}
// Parse input
const { buffer, sourceType } = await parseImageInput(
args.input,
context.directory,
);
// Validate security
await validateImageSecurity(buffer);
// Get metadata for format detection
const metadata = await sharp(buffer).metadata();
const format = getFormatFromMetadata(metadata);
const pipeline = sharp(buffer).blur(args.sigma);
if (args.returnBase64) {
const outputBuffer = await pipeline
.toFormat(format)
.toBuffer();
const base64 = outputBuffer.toString("base64");
return jsonResponse({
success: true,
operation: "blur",
data: `data:image/${format};base64,${base64}`,
format,
sigma: args.sigma,
});
}
// Save to file
const suffix = `-blur-${args.sigma}`;
const outputPath = determineOutputPath(
sourceType === "file" ? args.input : null,
suffix,
format,
context.directory,
);
await pipeline.toFormat(format).toFile(outputPath);
const outputStats = statSync(outputPath);
return jsonResponse({
success: true,
operation: "blur",
input: sourceType === "file" ? args.input : "(base64 data)",
output: path.relative(context.directory, outputPath),
format,
size_bytes: outputStats.size,
size_human: formatFileSize(outputStats.size),
sigma: args.sigma,
});
} catch (err) {
return jsonResponse({
success: false,
error: getErrorMessage(err),
});
}
},
});
// ============================================================================
// Tool 7: image_sharpen
// ============================================================================
export const image_sharpen = tool({
description: `Sharpen an image to enhance edges and details.
Uses unsharp masking with configurable parameters:
- sigma: Gaussian mask sigma (sharpness radius)
- flat: Amount of sharpening for flat areas
- jagged: Amount of sharpening for edge areas
Examples:
- Standard sharpen: image_sharpen({ input: "photo.jpg" })
- Strong sharpen: image_sharpen({ input: "photo.jpg", sigma: 2, flat: 2, jagged: 4 })
- Return as base64: image_sharpen({ input: "photo.jpg", returnBase64: true })`,
args: {
input: tool.schema
.string()
.describe(
"Image file path (relative to working directory) or base64 data URI",
),
sigma: tool.schema
.number()
.default(1)
.describe("Gaussian mask sigma. Default: 1"),
flat: tool.schema
.number()
.default(1)
.describe(
"Amount of sharpening to apply to flat areas. Default: 1",
),
jagged: tool.schema
.number()
.default(2)
.describe(
"Amount of sharpening to apply to edge areas. Default: 2",
),
returnBase64: tool.schema
.boolean()
.default(false)
.describe("Return base64 data URI instead of file path"),
},
async execute(args, context) {
try {
// Parse input
const { buffer, sourceType } = await parseImageInput(
args.input,
context.directory,
);
// Validate security
await validateImageSecurity(buffer);
// Get metadata for format detection
const metadata = await sharp(buffer).metadata();
const format = getFormatFromMetadata(metadata);
const pipeline = sharp(buffer).sharpen({
sigma: args.sigma,
m1: args.flat,
m2: args.jagged,
});
if (args.returnBase64) {
const outputBuffer = await pipeline
.toFormat(format)
.toBuffer();
const base64 = outputBuffer.toString("base64");
return jsonResponse({
success: true,
operation: "sharpen",
data: `data:image/${format};base64,${base64}`,
format,
sigma: args.sigma,
flat: args.flat,
jagged: args.jagged,
});
}
// Save to file
const suffix = `-sharpen-${args.sigma}`;
const outputPath = determineOutputPath(
sourceType === "file" ? args.input : null,
suffix,
format,
context.directory,
);
await pipeline.toFormat(format).toFile(outputPath);
const outputStats = statSync(outputPath);
return jsonResponse({
success: true,
operation: "sharpen",
input: sourceType === "file" ? args.input : "(base64 data)",
output: path.relative(context.directory, outputPath),
format,
size_bytes: outputStats.size,
size_human: formatFileSize(outputStats.size),
sigma: args.sigma,
flat: args.flat,
jagged: args.jagged,
});
} catch (err) {
return jsonResponse({
success: false,
error: getErrorMessage(err),
});
}
},
});
// ============================================================================
// Tool 8: image_convert
// ============================================================================
export const image_convert = tool({
description: `Convert an image from one format to another.
Supported formats: jpeg, png, webp, avif, tiff, gif, heif
Format-specific options:
- quality: Quality for lossy formats (1-100)
- lossless: Use lossless compression (webp, avif only)
- compressionLevel: PNG compression level (0-9, higher = smaller)
Examples:
- Convert to WebP: image_convert({ input: "photo.png", format: "webp" })
- Convert to AVIF with quality: image_convert({ input: "photo.jpg", format: "avif", quality: 90 })
- Convert to lossless WebP: image_convert({ input: "photo.png", format: "webp", lossless: true })
- Return as base64: image_convert({ input: "photo.jpg", format: "png", returnBase64: true })`,
args: {
input: tool.schema
.string()
.describe(
"Image file path (relative to working directory) or base64 data URI",
),
format: tool.schema
.enum(["jpeg", "png", "webp", "avif", "tiff", "gif", "heif"])
.describe("Target output format"),
quality: tool.schema
.number()
.min(1)
.max(100)
.default(80)
.describe("Quality for lossy formats (1-100). Default: 80"),
lossless: tool.schema
.boolean()
.default(false)
.describe("Use lossless compression (webp, avif only)"),
compressionLevel: tool.schema
.number()
.min(0)
.max(9)
.default(6)
.describe("PNG compression level (0-9). Default: 6"),
returnBase64: tool.schema
.boolean()
.default(false)
.describe("Return base64 data URI instead of file path"),
},
async execute(args, context) {
try {
// Validate format
const formatError = validateFormat(args.format);
if (formatError) {
return jsonResponse({
success: false,
error: `Validation error: ${formatError}`,
});
}
// Parse input
const { buffer, sourceType } = await parseImageInput(
args.input,
context.directory,
);
// Validate security
await validateImageSecurity(buffer);
// Get input metadata
const inputMetadata = await sharp(buffer).metadata();
// Build format options
const formatOptions: Record<string, unknown> = {};
switch (args.format) {
case "jpeg":
formatOptions.quality = args.quality;
formatOptions.mozjpeg = true;
break;
case "png":
formatOptions.compressionLevel = args.compressionLevel;
break;
case "webp":
case "avif":
if (args.lossless) {
formatOptions.lossless = true;
} else {
formatOptions.quality = args.quality;
}
break;
case "tiff":
formatOptions.quality = args.quality;
break;
case "gif":
// GIF doesn't have quality option
break;
case "heif":
formatOptions.quality = args.quality;
break;
}
const pipeline = sharp(buffer).toFormat(
args.format as SharpFormat,
formatOptions,
);
if (args.returnBase64) {
const outputBuffer = await pipeline.toBuffer();
const base64 = outputBuffer.toString("base64");
return jsonResponse({
success: true,
operation: "convert",
data: `data:image/${args.format};base64,${base64}`,
format: args.format,
from_format: inputMetadata.format,
});
}
// Save to file
const suffix = `-converted`;
const outputPath = determineOutputPath(
sourceType === "file" ? args.input : null,
suffix,
args.format,
context.directory,
);
await pipeline.toFile(outputPath);
const outputStats = statSync(outputPath);
return jsonResponse({
success: true,
operation: "convert",
input: sourceType === "file" ? args.input : "(base64 data)",
output: path.relative(context.directory, outputPath),
from_format: inputMetadata.format,
to_format: args.format,
size_bytes: outputStats.size,
size_human: formatFileSize(outputStats.size),
quality: args.quality,
lossless: args.lossless,
});
} catch (err) {
return jsonResponse({
success: false,
error: getErrorMessage(err),
});
}
},
});
// ============================================================================
// Tool 9: image_metadata
// ============================================================================
export const image_metadata = tool({
description: `Get comprehensive metadata from an image file.
Returns detailed information including:
- Dimensions (width, height)
- Format (jpeg, png, webp, etc.)
- Color channels and space
- Density (DPI)
- Alpha channel presence
- Orientation
- Depth and more
Examples:
- Get metadata: image_metadata({ input: "photo.jpg" })
- Get metadata from base64: image_metadata({ input: "data:image/png;base64,..." })`,
args: {
input: tool.schema
.string()
.describe(
"Image file path (relative to working directory) or base64 data URI",
),
},
async execute(args, context) {
try {
// Parse input
const { buffer, sourceType } = await parseImageInput(
args.input,
context.directory,
);
// Get metadata
const metadata = await sharp(buffer).metadata();
let fileSize: number | undefined;
if (sourceType === "file") {
const fullPath = resolveFilePath(args.input, context.directory);
const stats = statSync(fullPath);
fileSize = stats.size;
}
return jsonResponse({
success: true,
operation: "metadata",
input: sourceType === "file" ? args.input : "(base64 data)",
metadata: {
format: metadata.format,
width: metadata.width,
height: metadata.height,
channels: metadata.channels,
space: metadata.space,
depth: metadata.depth,
density: metadata.density,
hasAlpha: metadata.hasAlpha,
isProgressive: metadata.isProgressive,
orientation: metadata.orientation,
size: fileSize,
size_human: fileSize ? formatFileSize(fileSize) : undefined,
},
});
} catch (err) {
return jsonResponse({
success: false,
error: getErrorMessage(err),
});
}
},
});
// ============================================================================
// Tool 10: image_composite
// ============================================================================
export const image_composite = tool({
description: `Composite (overlay) one image on top of another.
Blend modes:
- over: Standard alpha blending (default)
- multiply: Multiply colors
- screen: Screen blend
- overlay: Overlay blend
- darken: Keep darker pixels
- lighten: Keep lighter pixels
- colorDodge: Color dodge
- colorBurn: Color burn
- hardLight: Hard light
- softLight: Soft light
- difference: Difference
- exclusion: Exclusion
Examples:
- Simple overlay: image_composite({ base: "background.jpg", overlay: "logo.png", x: 10, y: 10 })
- Centered overlay: image_composite({ base: "photo.jpg", overlay: "watermark.png", x: 100, y: 100 })
- With blend mode: image_composite({ base: "photo.jpg", overlay: "texture.png", x: 0, y: 0, blend: "multiply" })
- Return as base64: image_composite({ base: "photo.jpg", overlay: "logo.png", x: 10, y: 10, returnBase64: true })`,
args: {
base: tool.schema
.string()
.describe(
"Base image file path (relative to working directory) or base64 data URI",
),
overlay: tool.schema
.string()
.describe(
"Overlay image file path (relative to working directory) or base64 data URI",
),
x: tool.schema
.number()
.describe("X position for overlay (pixels from left)"),
y: tool.schema
.number()
.describe("Y position for overlay (pixels from top)"),
blend: tool.schema
.enum([
"over",
"multiply",
"screen",
"overlay",
"darken",
"lighten",
"colorDodge",
"colorBurn",
"hardLight",
"softLight",
"difference",
"exclusion",
])
.default("over")
.describe("Blend mode. Default: over"),
opacity: tool.schema
.number()
.min(0)
.max(1)
.default(1)
.describe("Overlay opacity (0-1). Default: 1 (fully opaque)"),
returnBase64: tool.schema
.boolean()
.default(false)
.describe("Return base64 data URI instead of file path"),
},
async execute(args, context) {
try {
// Parse base image
const { buffer: baseBuffer, sourceType: baseSourceType } =
await parseImageInput(args.base, context.directory);
// Validate security
await validateImageSecurity(baseBuffer);
// Parse overlay image
const { buffer: overlayBuffer } = await parseImageInput(
args.overlay,
context.directory,
);
// Validate overlay security
await validateImageSecurity(overlayBuffer);
// Get metadata for format detection
const metadata = await sharp(baseBuffer).metadata();
const format = getFormatFromMetadata(metadata);
// Prepare overlay with opacity if needed
let overlayInput: Buffer | string = overlayBuffer;
if (args.opacity < 1) {
// Create a semi-transparent version of the overlay using modulate
// We use a different approach: flatten alpha and re-apply with desired opacity
const overlayMeta = await sharp(overlayBuffer).metadata();
if (overlayMeta.hasAlpha) {
// Extract alpha channel and modulate it
const alphaChannel = await sharp(overlayBuffer)
.extractChannel("alpha")
.toBuffer();
// Create modulated alpha with reduced opacity
const modulatedAlpha = await sharp(alphaChannel)
.modulate({ brightness: args.opacity })
.toBuffer();
// Rebuild image with modulated alpha
const rgbBuffer = await sharp(overlayBuffer)
.removeAlpha()
.toBuffer();
overlayInput = await sharp(rgbBuffer)
.joinChannel(modulatedAlpha)
.toBuffer();
} else {
// If no alpha, add one with the desired opacity
overlayInput = await sharp(overlayBuffer)
.ensureAlpha(args.opacity)
.toBuffer();
}
}
const pipeline = sharp(baseBuffer).composite([
{
input: overlayInput,
left: args.x,
top: args.y,
blend: args.blend as sharp.Blend,
},
]);
if (args.returnBase64) {
const outputBuffer = await pipeline
.toFormat(format)
.toBuffer();
const base64 = outputBuffer.toString("base64");
return jsonResponse({
success: true,
operation: "composite",
data: `data:image/${format};base64,${base64}`,
format,
position: { x: args.x, y: args.y },
blend: args.blend,
opacity: args.opacity,
});
}
// Save to file
const suffix = "-composite";
const outputPath = determineOutputPath(
baseSourceType === "file" ? args.base : null,
suffix,
format,
context.directory,
);
await pipeline.toFormat(format).toFile(outputPath);
const outputStats = statSync(outputPath);
return jsonResponse({
success: true,
operation: "composite",
input: baseSourceType === "file" ? args.base : "(base64 data)",
overlay: args.overlay,
output: path.relative(context.directory, outputPath),
format,
size_bytes: outputStats.size,
size_human: formatFileSize(outputStats.size),
position: { x: args.x, y: args.y },
blend: args.blend,
opacity: args.opacity,
});
} catch (err) {
return jsonResponse({
success: false,
error: getErrorMessage(err),
});
}
},
});
// ============================================================================
// Tool 11: image_channel
// ============================================================================
export const image_channel = tool({
description: `Extract a single color channel from an image.
Channels:
- red: Red channel
- green: Green channel
- blue: Blue channel
- alpha: Alpha (transparency) channel
The result is a grayscale image representing the selected channel's intensity.
Examples:
- Extract red channel: image_channel({ input: "photo.jpg", channel: "red" })
- Extract alpha channel: image_channel({ input: "photo.png", channel: "alpha" })
- Return as base64: image_channel({ input: "photo.jpg", channel: "green", returnBase64: true })`,
args: {
input: tool.schema
.string()
.describe(
"Image file path (relative to working directory) or base64 data URI",
),
channel: tool.schema
.enum(["red", "green", "blue", "alpha"])
.describe("Channel to extract"),
returnBase64: tool.schema
.boolean()
.default(false)
.describe("Return base64 data URI instead of file path"),
},
async execute(args, context) {
try {
// Parse input
const { buffer, sourceType } = await parseImageInput(
args.input,
context.directory,
);
// Validate security
await validateImageSecurity(buffer);
// Extract channel
const pipeline = sharp(buffer).extractChannel(args.channel);
if (args.returnBase64) {
const outputBuffer = await pipeline.png().toBuffer();
const base64 = outputBuffer.toString("base64");
return jsonResponse({
success: true,
operation: "channel",
data: `data:image/png;base64,${base64}`,
format: "png",
channel: args.channel,
});
}
// Save to file
const suffix = `-channel-${args.channel}`;
const outputPath = determineOutputPath(
sourceType === "file" ? args.input : null,
suffix,
"png",
context.directory,
);
await pipeline.png().toFile(outputPath);
const outputStats = statSync(outputPath);
return jsonResponse({
success: true,
operation: "channel",
input: sourceType === "file" ? args.input : "(base64 data)",
output: path.relative(context.directory, outputPath),
format: "png",
size_bytes: outputStats.size,
size_human: formatFileSize(outputStats.size),
channel: args.channel,
});
} catch (err) {
return jsonResponse({
success: false,
error: getErrorMessage(err),
});
}
},
});