@screenshotscout/mcp 0.1.0

package/dist/core/capture-tool.js

@@ -0,0 +1,135 @@
+import { CaptureHttpMethod } from "@screenshotscout/sdk";
+import { captureScreenshotInputSchema, mapCaptureInputToSdk, } from "./capture-input.js";
+import { formatScreenshotScoutError } from "./errors.js";
+import { evaluateInlineImage, normalizeMimeType, resolveImageDimensions, } from "./image.js";
+import { captureResultMetadataSchema, formatCaptureSuccess, } from "./result.js";
+import { CAPTURE_SCREENSHOT_TOOL_ANNOTATIONS, CAPTURE_SCREENSHOT_TOOL_DESCRIPTION, CAPTURE_SCREENSHOT_TOOL_NAME, CAPTURE_SCREENSHOT_TOOL_TITLE, } from "./tool-metadata.js";
+/**
+ * Invokes the official Screenshot Scout SDK after MCP schema validation.
+ * Result-content branching remains in the shared result layer.
+ */
+export async function invokeCaptureScreenshot(input, dependencies, context = {}) {
+    const configuredSensitiveValues = dependencies.sensitiveValues ?? [];
+    try {
+        const mappedRequest = mapCaptureInputToSdk(input);
+        const response = await dependencies.client.capture(mappedRequest.targetUrl, mappedRequest.captureOptions, {
+            method: CaptureHttpMethod.POST,
+            ...(context.signal === undefined ? {} : { signal: context.signal }),
+        });
+        const mimeType = normalizeMimeType(response.rawResponse.contentType);
+        const baseMetadata = {
+            ...(response.screenshotUrl === undefined
+                ? {}
+                : { screenshotUrl: response.screenshotUrl }),
+            ...(response.screenshotUrlExpiresAt === undefined
+                ? {}
+                : { screenshotUrlExpiresAt: response.screenshotUrlExpiresAt }),
+            ...(response.cacheStatus === undefined
+                ? {}
+                : { cacheStatus: response.cacheStatus }),
+            format: input.format,
+            ...(mimeType === undefined ? {} : { mimeType }),
+            inlineImageIncluded: false,
+        };
+        if (input.format === "pdf") {
+            const resourceLink = createPdfResourceLink(response.screenshotUrl, mimeType, response.bytes.byteLength);
+            return formatCaptureSuccess({
+                metadata: baseMetadata,
+                ...(resourceLink === undefined
+                    ? {}
+                    : { additionalContent: [resourceLink] }),
+                sensitiveValues: configuredSensitiveValues,
+            });
+        }
+        const dimensions = resolveImageDimensions(response.bytes, mimeType, undefined);
+        const evaluation = evaluateInlineImage({
+            format: input.format,
+            resultMode: mappedRequest.resultMode,
+            mimeType,
+            bytes: response.bytes,
+            ...(dimensions === undefined
+                ? {}
+                : {
+                    trustedDimensions: {
+                        imageWidth: dimensions.width,
+                        imageHeight: dimensions.height,
+                    },
+                }),
+            ...(dependencies.maxSerializedResultBytes === undefined
+                ? {}
+                : {
+                    serializedSizeLimitBytes: dependencies.maxSerializedResultBytes,
+                }),
+            clientSupportsInlineImage: dependencies.clientSupportsInlineImage ?? (() => false),
+            buildSerializedResult: (image, measuredDimensions) => formatCaptureSuccess({
+                metadata: buildImageMetadata(baseMetadata, measuredDimensions, true),
+                additionalContent: [image],
+                sensitiveValues: configuredSensitiveValues,
+            }),
+        });
+        if (evaluation.included) {
+            return formatCaptureSuccess({
+                metadata: buildImageMetadata(baseMetadata, evaluation.dimensions, true),
+                additionalContent: [evaluation.image],
+                sensitiveValues: configuredSensitiveValues,
+            });
+        }
+        return formatCaptureSuccess({
+            metadata: {
+                ...buildImageMetadata(baseMetadata, dimensions, false),
+                inlineImageOmissionReason: evaluation.reason,
+            },
+            sensitiveValues: configuredSensitiveValues,
+        });
+    }
+    catch (error) {
+        // MCP cancellation reasons may be strings, but error mapping expects the
+        // standard AbortError shape and must not report cancellations as faults.
+        const captureError = context.signal?.aborted === true
+            ? new DOMException("The screenshot capture was cancelled.", "AbortError")
+            : error;
+        return formatScreenshotScoutError(captureError, {
+            sensitiveValues: [input.url, ...configuredSensitiveValues],
+            ...(dependencies.onUnexpectedError === undefined
+                ? {}
+                : { onUnexpectedError: dependencies.onUnexpectedError }),
+        });
+    }
+}
+/**
+ * Registers the one approved tool on a transport-neutral MCP server.
+ */
+export function registerCaptureScreenshotTool(server, dependencies) {
+    return server.registerTool(CAPTURE_SCREENSHOT_TOOL_NAME, {
+        title: CAPTURE_SCREENSHOT_TOOL_TITLE,
+        description: CAPTURE_SCREENSHOT_TOOL_DESCRIPTION,
+        inputSchema: captureScreenshotInputSchema,
+        outputSchema: captureResultMetadataSchema,
+        annotations: CAPTURE_SCREENSHOT_TOOL_ANNOTATIONS,
+    }, (input, extra) => invokeCaptureScreenshot(input, dependencies, { signal: extra.signal }));
+}
+function buildImageMetadata(baseMetadata, dimensions, inlineImageIncluded) {
+    return {
+        ...baseMetadata,
+        ...(dimensions === undefined
+            ? {}
+            : {
+                imageWidth: dimensions.width,
+                imageHeight: dimensions.height,
+            }),
+        inlineImageIncluded,
+    };
+}
+function createPdfResourceLink(screenshotUrl, mimeType, rawBytes) {
+    if (screenshotUrl === undefined)
+        return undefined;
+    return {
+        type: "resource_link",
+        uri: screenshotUrl,
+        name: "screenshot-scout-capture.pdf",
+        title: "Screenshot Scout PDF capture",
+        description: "Temporary PDF capture generated by Screenshot Scout.",
+        mimeType: mimeType ?? "application/pdf",
+        size: rawBytes,
+    };
+}

package/dist/core/client.d.ts

@@ -0,0 +1,18 @@
+import { type BinaryCaptureOptions, type BinaryCaptureResponse, type CaptureRequestOptions, type ScreenshotScoutClientOptions, type ScreenshotScoutFetch } from "@screenshotscout/sdk";
+export type ScreenshotScoutCredentials = {
+    readonly accessKey: string;
+    readonly secretKey?: string;
+};
+export interface ScreenshotScoutCaptureClient {
+    capture(targetUrl: string, captureOptions?: BinaryCaptureOptions | null, captureRequestOptions?: CaptureRequestOptions | null): Promise<BinaryCaptureResponse>;
+}
+export type ScreenshotScoutClientFactory = (options: ScreenshotScoutClientOptions) => ScreenshotScoutCaptureClient;
+export type ScreenshotScoutClientDependencies = {
+    readonly clientFactory?: ScreenshotScoutClientFactory;
+    readonly fetch?: ScreenshotScoutFetch;
+};
+/**
+ * Constructs the official SDK client from credentials supplied by the caller.
+ * Environment, transport, and tool layers remain outside this core.
+ */
+export declare function createScreenshotScoutClient(credentials: ScreenshotScoutCredentials, dependencies?: ScreenshotScoutClientDependencies): ScreenshotScoutCaptureClient;

package/dist/core/client.js

@@ -0,0 +1,16 @@
+import { ScreenshotScoutClient, } from "@screenshotscout/sdk";
+const defaultClientFactory = (options) => new ScreenshotScoutClient(options);
+/**
+ * Constructs the official SDK client from credentials supplied by the caller.
+ * Environment, transport, and tool layers remain outside this core.
+ */
+export function createScreenshotScoutClient(credentials, dependencies = {}) {
+    const options = {
+        accessKey: credentials.accessKey,
+        ...(credentials.secretKey === undefined
+            ? {}
+            : { secretKey: credentials.secretKey }),
+        ...(dependencies.fetch === undefined ? {} : { fetch: dependencies.fetch }),
+    };
+    return (dependencies.clientFactory ?? defaultClientFactory)(options);
+}

package/dist/core/errors.d.ts

@@ -0,0 +1,20 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { type RedactedDiagnostic } from "./redaction.js";
+export type SafeOptionError = {
+    readonly option: string;
+    readonly message: string;
+};
+export type SafeScreenshotScoutError = {
+    readonly category: "api" | "cancelled" | "configuration" | "response" | "serialization" | "transport" | "unexpected" | "unsafe_result";
+    readonly message: string;
+    readonly status?: number;
+    readonly code?: string;
+    readonly optionErrors?: readonly SafeOptionError[];
+    readonly remediation?: string;
+};
+export type ErrorMappingOptions = {
+    readonly sensitiveValues?: readonly (string | null | undefined)[];
+    readonly onUnexpectedError?: (diagnostic: RedactedDiagnostic) => void;
+};
+export declare function mapScreenshotScoutError(error: unknown, options?: ErrorMappingOptions): SafeScreenshotScoutError;
+export declare function formatScreenshotScoutError(error: unknown, options?: ErrorMappingOptions): CallToolResult;

package/dist/core/errors.js

@@ -0,0 +1,166 @@
+import { ScreenshotScoutApiError, ScreenshotScoutConfigurationError, ScreenshotScoutResponseDecodingError, ScreenshotScoutSerializationError, ScreenshotScoutTransportError, } from "@screenshotscout/sdk";
+import { redactText, toRedactedDiagnostic, } from "./redaction.js";
+import { UnsafeCaptureResultError } from "./result.js";
+export function mapScreenshotScoutError(error, options = {}) {
+    try {
+        return mapScreenshotScoutErrorInternal(error, options);
+    }
+    catch {
+        reportUnexpectedError(error, options);
+        return {
+            category: "unexpected",
+            message: "An unexpected Screenshot Scout MCP error occurred. Retry the request, and contact support if it continues.",
+        };
+    }
+}
+function mapScreenshotScoutErrorInternal(error, options) {
+    const sensitiveValues = options.sensitiveValues ?? [];
+    if (error instanceof ScreenshotScoutApiError) {
+        const code = error.errorCode === undefined
+            ? undefined
+            : safeErrorText(error.errorCode, sensitiveValues, 100);
+        const message = safeErrorText(error.errorMessage ??
+            `Screenshot Scout API request failed with status ${error.status}.`, sensitiveValues, 1_000);
+        const optionErrors = readSafeOptionErrors(error.errors, sensitiveValues);
+        const remediation = code === "signature_required"
+            ? "This API key requires signed requests. Use local stdio or MCPB with the secret key, or use a dedicated key with signed requests disabled. Never send the secret key to a hosted MCP endpoint."
+            : undefined;
+        return {
+            category: "api",
+            message,
+            status: error.status,
+            ...(code === undefined ? {} : { code }),
+            ...(optionErrors.length === 0 ? {} : { optionErrors }),
+            ...(remediation === undefined ? {} : { remediation }),
+        };
+    }
+    if (error instanceof ScreenshotScoutConfigurationError) {
+        return {
+            category: "configuration",
+            message: "Screenshot Scout client configuration is invalid. Check the configured access key and local signing settings.",
+        };
+    }
+    if (error instanceof ScreenshotScoutSerializationError) {
+        const option = error.option === undefined
+            ? undefined
+            : safeErrorText(error.option, sensitiveValues, 100);
+        return {
+            category: "serialization",
+            message: option === undefined
+                ? "The screenshot request options could not be serialized safely."
+                : `The screenshot request option "${option}" could not be serialized safely.`,
+        };
+    }
+    if (error instanceof ScreenshotScoutTransportError) {
+        return {
+            category: "transport",
+            message: "Screenshot Scout could not be reached before a response was received. Retry the capture.",
+        };
+    }
+    if (error instanceof ScreenshotScoutResponseDecodingError) {
+        return {
+            category: "response",
+            message: "Screenshot Scout returned an unexpected response that could not be handled safely.",
+        };
+    }
+    if (error instanceof UnsafeCaptureResultError) {
+        return {
+            category: "unsafe_result",
+            message: "Screenshot Scout returned result metadata that could not be exposed safely.",
+        };
+    }
+    if (isAbortError(error)) {
+        return {
+            category: "cancelled",
+            message: "The screenshot capture was cancelled.",
+        };
+    }
+    reportUnexpectedError(error, options);
+    return {
+        category: "unexpected",
+        message: "An unexpected Screenshot Scout MCP error occurred. Retry the request, and contact support if it continues.",
+    };
+}
+export function formatScreenshotScoutError(error, options = {}) {
+    const safeError = mapScreenshotScoutError(error, options);
+    const lines = ["Screenshot Scout capture failed."];
+    if (safeError.status !== undefined) {
+        lines.push(`HTTP status: ${safeError.status}`);
+    }
+    if (safeError.code !== undefined) {
+        lines.push(`Error code: ${safeError.code}`);
+    }
+    lines.push(`Message: ${safeError.message}`);
+    if (safeError.optionErrors !== undefined &&
+        safeError.optionErrors.length > 0) {
+        lines.push("Option errors:");
+        for (const optionError of safeError.optionErrors) {
+            lines.push(`- ${optionError.option}: ${optionError.message}`);
+        }
+    }
+    if (safeError.remediation !== undefined) {
+        lines.push(`How to resolve: ${safeError.remediation}`);
+    }
+    return {
+        content: [{ type: "text", text: lines.join("\n") }],
+        isError: true,
+    };
+}
+function readSafeOptionErrors(errors, sensitiveValues) {
+    if (errors === undefined)
+        return [];
+    const output = [];
+    for (const value of errors.slice(0, 25)) {
+        if (typeof value !== "object" || value === null || Array.isArray(value)) {
+            continue;
+        }
+        let option;
+        let message;
+        try {
+            option = Reflect.get(value, "option");
+            message = Reflect.get(value, "message");
+        }
+        catch {
+            continue;
+        }
+        if (typeof option !== "string" || typeof message !== "string")
+            continue;
+        output.push({
+            option: safeErrorText(option, sensitiveValues, 100),
+            message: safeErrorText(message, sensitiveValues, 500),
+        });
+    }
+    return output;
+}
+function safeErrorText(value, sensitiveValues, maxLength) {
+    return redactText(value, {
+        sensitiveValues,
+        redactUrls: true,
+        maxLength,
+    });
+}
+function reportUnexpectedError(error, options) {
+    try {
+        if (options.onUnexpectedError === undefined)
+            return;
+        options.onUnexpectedError(toRedactedDiagnostic(error, {
+            ...(options.sensitiveValues === undefined
+                ? {}
+                : { sensitiveValues: options.sensitiveValues }),
+            redactUrls: true,
+        }));
+    }
+    catch {
+        // Diagnostics must never replace the safe tool error.
+    }
+}
+function isAbortError(error) {
+    if (typeof error !== "object" || error === null)
+        return false;
+    try {
+        return Reflect.get(error, "name") === "AbortError";
+    }
+    catch {
+        return false;
+    }
+}

package/dist/core/image.d.ts

@@ -0,0 +1,67 @@
+import type { ImageContent } from "@modelcontextprotocol/sdk/types.js";
+import type { CaptureResultMode, CaptureScreenshotInput } from "./capture-input.js";
+export declare const MAX_INLINE_IMAGE_DIMENSION = 8000;
+export declare const MAX_INLINE_IMAGE_RAW_BYTES: number;
+export declare const DEFAULT_MAX_SERIALIZED_RESULT_BYTES = 128000;
+export declare const DEFAULT_MAX_IMAGE_HEADER_BYTES: number;
+export declare const INLINE_IMAGE_MIME_TYPES: readonly ["image/png", "image/jpeg", "image/webp", "image/gif"];
+export type InlineImageMimeType = (typeof INLINE_IMAGE_MIME_TYPES)[number];
+export type CaptureFormat = CaptureScreenshotInput["format"];
+export declare const INLINE_IMAGE_OMISSION_REASONS: {
+    readonly RESULT_MODE_URL_ONLY: "result_mode_url_only";
+    readonly FORMAT_NOT_INLINE_ELIGIBLE: "format_not_inline_eligible";
+    readonly UNSUPPORTED_MIME_TYPE: "unsupported_mime_type";
+    readonly MIME_TYPE_MISMATCH: "mime_type_mismatch";
+    readonly RAW_SIZE_EXCEEDS_LIMIT: "raw_size_exceeds_limit";
+    readonly DIMENSIONS_UNAVAILABLE: "dimensions_unavailable";
+    readonly DIMENSIONS_EXCEED_LIMIT: "dimensions_exceed_limit";
+    readonly CLIENT_NOT_COMPATIBLE: "client_not_compatible";
+    readonly SERIALIZED_SIZE_UNAVAILABLE: "serialized_size_unavailable";
+    readonly SERIALIZED_SIZE_EXCEEDS_LIMIT: "serialized_size_exceeds_limit";
+};
+export type InlineImageOmissionReason = (typeof INLINE_IMAGE_OMISSION_REASONS)[keyof typeof INLINE_IMAGE_OMISSION_REASONS];
+export type ImageDimensions = {
+    readonly width: number;
+    readonly height: number;
+};
+export type TrustedImageDimensions = {
+    readonly imageWidth?: number;
+    readonly imageHeight?: number;
+};
+export type InlineImageIncluded = {
+    readonly included: true;
+    readonly image: ImageContent;
+    readonly dimensions: ImageDimensions;
+    readonly rawBytes: number;
+    readonly serializedBytes: number;
+    readonly serializedSizeLimitBytes: number;
+};
+export type InlineImageOmitted = {
+    readonly included: false;
+    readonly reason: InlineImageOmissionReason;
+    readonly dimensions?: ImageDimensions;
+    readonly rawBytes: number;
+    readonly serializedSizeLimitBytes: number;
+};
+export type InlineImageEvaluation = InlineImageIncluded | InlineImageOmitted;
+export type InlineImageCandidate = {
+    readonly format: CaptureFormat;
+    readonly resultMode: CaptureResultMode;
+    readonly mimeType: string | null | undefined;
+    readonly bytes: Uint8Array;
+    readonly trustedDimensions?: TrustedImageDimensions;
+    readonly serializedSizeLimitBytes?: number;
+    readonly clientSupportsInlineImage: (mimeType: InlineImageMimeType) => boolean;
+    readonly buildSerializedResult: (image: ImageContent, dimensions: ImageDimensions) => unknown;
+    readonly stringify?: (value: unknown) => string | undefined;
+};
+export declare function normalizeMimeType(value: string | null | undefined): string | undefined;
+export declare function asInlineImageMimeType(value: string | null | undefined): InlineImageMimeType | undefined;
+export declare function resolveImageDimensions(bytes: Uint8Array, mimeType: string | null | undefined, trustedDimensions: TrustedImageDimensions | undefined, maxHeaderBytes?: number): ImageDimensions | undefined;
+/**
+ * Reads only bounded format headers. It does not decode pixels or transform
+ * the payload.
+ */
+export declare function inspectImageDimensions(bytes: Uint8Array, mimeType: string | null | undefined, maxHeaderBytes?: number): ImageDimensions | undefined;
+export declare function evaluateInlineImage(candidate: InlineImageCandidate): InlineImageEvaluation;
+export declare function resolveSerializedSizeLimit(requestedLimitBytes: number | undefined): number;