@mainwp/mcp 1.0.0-beta.1

package/dist/retry.js

@@ -0,0 +1,206 @@
+/**
+ * Retry Logic for Transient Errors
+ *
+ * Provides exponential backoff with jitter for handling transient network
+ * failures and server errors (HTTP 5xx, 429, network errors).
+ *
+ * Key features:
+ * - Only retries transient errors (5xx, 429, network errors)
+ * - Permanent errors (4xx except 429) fail immediately
+ * - Timeout budget ensures total time never exceeds requestTimeout
+ * - Exponential backoff with jitter prevents thundering herd
+ */
+/**
+ * Extract HTTP status code from an error.
+ * Handles various error formats including fetch errors and custom error objects.
+ */
+function extractStatusCode(error) {
+    // Handle error objects with status property
+    if (error && typeof error === 'object') {
+        const errorObj = error;
+        // Direct status property (e.g., Response object or custom error)
+        if (typeof errorObj.status === 'number') {
+            return errorObj.status;
+        }
+        // Status in cause (chained errors)
+        if (errorObj.cause && typeof errorObj.cause === 'object') {
+            const cause = errorObj.cause;
+            if (typeof cause.status === 'number') {
+                return cause.status;
+            }
+        }
+    }
+    // Extract from error message patterns
+    if (error instanceof Error) {
+        const message = error.message;
+        // Match patterns like "Failed to fetch: 503" or "HTTP 503"
+        const statusMatch = message.match(/\b([45]\d{2})\b/);
+        if (statusMatch) {
+            return parseInt(statusMatch[1], 10);
+        }
+    }
+    return null;
+}
+/**
+ * Extract error code from an error (e.g., ECONNRESET, ETIMEDOUT)
+ */
+function extractErrorCode(error) {
+    if (error && typeof error === 'object') {
+        const errorObj = error;
+        // Direct code property (Node.js errors)
+        if (typeof errorObj.code === 'string') {
+            return errorObj.code;
+        }
+        // Code in cause (chained errors)
+        if (errorObj.cause && typeof errorObj.cause === 'object') {
+            const cause = errorObj.cause;
+            if (typeof cause.code === 'string') {
+                return cause.code;
+            }
+        }
+    }
+    // Extract from error message
+    if (error instanceof Error) {
+        const message = error.message.toUpperCase();
+        // Common network error codes
+        const networkCodes = ['ECONNRESET', 'ECONNREFUSED', 'ETIMEDOUT', 'ENOTFOUND'];
+        for (const code of networkCodes) {
+            if (message.includes(code)) {
+                return code;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Determine if an error is retryable (transient).
+ *
+ * Retryable errors:
+ * - HTTP 5xx (server errors)
+ * - HTTP 429 (rate limited)
+ * - Network errors: ECONNRESET, ECONNREFUSED, ETIMEDOUT, ENOTFOUND
+ *
+ * Non-retryable errors:
+ * - HTTP 4xx (except 429): client errors, auth failures, validation errors
+ * - AbortError: user cancellation
+ * - Any other errors (treat as permanent)
+ */
+export function isRetryableError(error) {
+    // AbortError is never retryable (user cancellation)
+    if (error instanceof Error && error.name === 'AbortError') {
+        return false;
+    }
+    // Check for HTTP status codes
+    const statusCode = extractStatusCode(error);
+    if (statusCode !== null) {
+        // 5xx server errors are retryable
+        if (statusCode >= 500 && statusCode <= 599) {
+            return true;
+        }
+        // 429 rate limited is retryable
+        if (statusCode === 429) {
+            return true;
+        }
+        // 4xx client errors (except 429) are NOT retryable
+        if (statusCode >= 400 && statusCode <= 499) {
+            return false;
+        }
+    }
+    // Check for network error codes
+    const errorCode = extractErrorCode(error);
+    if (errorCode !== null) {
+        const retryableCodes = ['ECONNRESET', 'ECONNREFUSED', 'ETIMEDOUT', 'ENOTFOUND'];
+        if (retryableCodes.includes(errorCode)) {
+            return true;
+        }
+    }
+    // Unknown errors are NOT retried (conservative approach)
+    return false;
+}
+/**
+ * Calculate exponential backoff delay with jitter.
+ *
+ * Formula: min(maxDelay, baseDelay * 2^attempt + random(0, baseDelay))
+ *
+ * @param attempt - 0-indexed attempt number (0 for first retry, 1 for second, etc.)
+ * @param baseDelay - Base delay in milliseconds
+ * @param maxDelay - Maximum delay in milliseconds
+ * @returns Delay in milliseconds
+ */
+export function calculateBackoff(attempt, baseDelay, maxDelay) {
+    // Exponential: baseDelay * 2^attempt
+    const exponentialDelay = baseDelay * Math.pow(2, attempt);
+    // Jitter: random value between 0 and baseDelay
+    const jitter = Math.random() * baseDelay;
+    // Total delay with jitter
+    const totalDelay = exponentialDelay + jitter;
+    // Cap at maxDelay
+    return Math.min(totalDelay, maxDelay);
+}
+/**
+ * Execute an operation with retry logic.
+ *
+ * @param operation - The async operation to execute
+ * @param options - Retry configuration
+ * @returns The result of the operation
+ * @throws The last error if all retries are exhausted or a non-retryable error occurs
+ */
+export async function withRetry(operation, options) {
+    const { maxRetries, baseDelay, maxDelay, timeoutBudget, logger } = options;
+    const startTime = Date.now();
+    let lastError = null;
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+        // Calculate remaining budget before each attempt
+        const elapsed = Date.now() - startTime;
+        const remainingBudget = timeoutBudget - elapsed;
+        // Check if budget is already exhausted before attempting
+        if (remainingBudget <= 0) {
+            const budgetError = new Error(`Retry timeout budget exhausted: ${Math.round(elapsed)}ms elapsed, budget was ${timeoutBudget}ms`);
+            if (lastError) {
+                budgetError.cause = lastError;
+            }
+            throw budgetError;
+        }
+        try {
+            // Pass context with remaining budget so operation can enforce timeout
+            return await operation({ remainingBudget, attempt });
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            // Check if error is retryable
+            if (!isRetryableError(error)) {
+                throw lastError;
+            }
+            // Check if this was the last attempt
+            if (attempt >= maxRetries - 1) {
+                throw lastError;
+            }
+            // Calculate backoff delay
+            const backoffDelay = calculateBackoff(attempt, baseDelay, maxDelay);
+            // Re-calculate remaining budget after operation completed
+            const elapsedAfterOp = Date.now() - startTime;
+            const remainingBudgetAfterOp = timeoutBudget - elapsedAfterOp;
+            if (backoffDelay > remainingBudgetAfterOp) {
+                // Don't wait for a retry that would exceed the budget
+                const budgetError = new Error(`Retry timeout budget exceeded: would need ${Math.round(backoffDelay)}ms but only ${Math.round(remainingBudgetAfterOp)}ms remaining`);
+                // Preserve the original error as the cause
+                budgetError.cause = lastError;
+                throw budgetError;
+            }
+            // Log the retry attempt
+            if (logger) {
+                logger.warning('Retrying request after transient error', {
+                    attempt: attempt + 1,
+                    delay: Math.round(backoffDelay),
+                    error: lastError.message,
+                    remainingBudget: Math.round(remainingBudgetAfterOp),
+                });
+            }
+            // Wait before retrying
+            await new Promise(resolve => setTimeout(resolve, backoffDelay));
+        }
+    }
+    // Should never reach here, but TypeScript doesn't know that
+    throw lastError || new Error('Retry exhausted with no error captured');
+}
+//# sourceMappingURL=retry.js.map

package/dist/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"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"}

package/dist/security.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Security Utilities
+ *
+ * Shared security functions for input validation, error sanitization,
+ * and rate limiting.
+ */
+/**
+ * Validate input arguments before forwarding to the API.
+ * Prevents malicious payloads and enforces reasonable limits.
+ * Recurses into nested objects and arrays to enforce string length and ID range checks.
+ * Throws McpError with INVALID_PARAMS code on validation failure.
+ */
+export declare function validateInput(args: Record<string, unknown>, depth?: number): void;
+/**
+ * Sanitize error messages before returning to clients.
+ * Removes potentially sensitive information like file paths, credentials, and stack traces.
+ */
+export declare function sanitizeError(message: string): string;
+/**
+ * Token bucket rate limiter to prevent API abuse.
+ * Throttles requests to a configurable rate per minute.
+ */
+export declare class RateLimiter {
+    private tokens;
+    private lastRefill;
+    private readonly maxTokens;
+    private readonly refillRate;
+    constructor(requestsPerMinute: number);
+    /**
+     * Acquire a token, waiting if necessary.
+     * Returns immediately if rate limiting is disabled (maxTokens = 0).
+     * @param signal - Optional AbortSignal to cancel the wait
+     */
+    acquire(signal?: AbortSignal): Promise<void>;
+    private refill;
+}
+/**
+ * Check if a value is a valid positive integer ID
+ */
+export declare function isValidId(value: unknown): boolean;
+//# sourceMappingURL=security.d.ts.map

package/dist/security.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.d.ts","sourceRoot":"","sources":["../src/security.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,SAAI,GAAG,IAAI,CAwD5E;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAiCrD;AAED;;;GAGG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAExB,iBAAiB,EAAE,MAAM;IAOrC;;;;OAIG;IACG,OAAO,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IA4BlD,OAAO,CAAC,MAAM;CAMf;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CASjD"}

package/dist/security.js

@@ -0,0 +1,154 @@
+/**
+ * Security Utilities
+ *
+ * Shared security functions for input validation, error sanitization,
+ * and rate limiting.
+ */
+import { McpErrorFactory } from './errors.js';
+// Input validation limits
+const MAX_STRING_LENGTH = 10000;
+const MAX_ARRAY_ELEMENTS = 1000;
+const MAX_OBJECT_DEPTH = 5;
+/**
+ * Validate input arguments before forwarding to the API.
+ * Prevents malicious payloads and enforces reasonable limits.
+ * Recurses into nested objects and arrays to enforce string length and ID range checks.
+ * Throws McpError with INVALID_PARAMS code on validation failure.
+ */
+export function validateInput(args, depth = 0) {
+    if (depth > MAX_OBJECT_DEPTH) {
+        throw McpErrorFactory.invalidParams(`Input exceeds maximum nesting depth (${MAX_OBJECT_DEPTH})`, { maxDepth: MAX_OBJECT_DEPTH });
+    }
+    for (const [key, value] of Object.entries(args)) {
+        // String length check
+        if (typeof value === 'string' && value.length > MAX_STRING_LENGTH) {
+            throw McpErrorFactory.invalidParams(`Parameter "${key}" exceeds maximum length (${MAX_STRING_LENGTH} characters)`, { parameter: key, maxLength: MAX_STRING_LENGTH });
+        }
+        // ID fields: accept number or numeric string, must be positive integer
+        if (key.endsWith('_id')) {
+            const numValue = typeof value === 'string' ? parseInt(value, 10) : value;
+            if (typeof numValue === 'number') {
+                if (!Number.isInteger(numValue) || numValue < 1 || numValue > Number.MAX_SAFE_INTEGER) {
+                    throw McpErrorFactory.invalidParams(`Parameter "${key}" must be a positive integer`, {
+                        parameter: key,
+                    });
+                }
+            }
+        }
+        // Array validation
+        if (Array.isArray(value)) {
+            if (value.length > MAX_ARRAY_ELEMENTS) {
+                throw McpErrorFactory.invalidParams(`Parameter "${key}" has too many elements (max ${MAX_ARRAY_ELEMENTS})`, { parameter: key, maxElements: MAX_ARRAY_ELEMENTS, actualElements: value.length });
+            }
+            // Validate array elements (strings and nested objects)
+            for (const item of value) {
+                if (typeof item === 'string' && item.length > MAX_STRING_LENGTH) {
+                    throw McpErrorFactory.invalidParams(`Element in "${key}" exceeds maximum length (${MAX_STRING_LENGTH} characters)`, { parameter: key, maxLength: MAX_STRING_LENGTH });
+                }
+                if (typeof item === 'object' && item !== null && !Array.isArray(item)) {
+                    validateInput(item, depth + 1);
+                }
+            }
+        }
+        // Nested object: recurse to validate contents (string lengths, ID ranges, depth)
+        if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+            validateInput(value, depth + 1);
+        }
+    }
+}
+/**
+ * Sanitize error messages before returning to clients.
+ * Removes potentially sensitive information like file paths, credentials, and stack traces.
+ */
+export function sanitizeError(message) {
+    return (message
+        // Remove absolute file paths (Unix: /home/..., /var/..., macOS: /Users/...)
+        .replace(/\/(Users|home|var|tmp|etc|usr|opt)\/[\w\-./]+/gi, '[path]')
+        // Remove Windows paths
+        .replace(/[A-Z]:\\[\w\-\\./]+/gi, '[path]')
+        // Remove credentials in URLs (user:pass@host)
+        .replace(/(https?:\/\/)[^:]+:[^@]+@/g, '$1[redacted]@')
+        // Remove Bearer tokens (Authorization: Bearer xxx)
+        .replace(/Bearer\s+[\w\-._~+/]+=*/gi, 'Bearer [redacted]')
+        // Remove potential tokens/keys in key=value patterns (handles quoted values with spaces)
+        // Matches: TOKEN=xxx, _TOKEN=xxx, MAINWP_TOKEN=xxx, password: "xxx", etc.
+        .replace(/\b(\w*(?:token|password|secret|key|auth|credential))[=:]\s*"[^"]*"/gi, '$1=[redacted]')
+        .replace(/\b(\w*(?:token|password|secret|key|auth|credential))[=:]\s*'[^']*'/gi, '$1=[redacted]')
+        .replace(/\b(\w*(?:token|password|secret|key|auth|credential))[=:]\s*[\w\-._~+/]+=*/gi, '$1=[redacted]')
+        // Remove stack traces (at Function.name (file:line:col))
+        .replace(/\s+at\s+.+\(.+:\d+:\d+\)/g, '')
+        // Remove Node.js internal paths
+        .replace(/\(node:[\w]+:\d+:\d+\)/g, '')
+        // Truncate to reasonable length
+        .slice(0, 500)
+        .trim());
+}
+/**
+ * Token bucket rate limiter to prevent API abuse.
+ * Throttles requests to a configurable rate per minute.
+ */
+export class RateLimiter {
+    tokens;
+    lastRefill;
+    maxTokens;
+    refillRate; // tokens per ms
+    constructor(requestsPerMinute) {
+        this.maxTokens = requestsPerMinute;
+        this.tokens = requestsPerMinute;
+        this.refillRate = requestsPerMinute / 60000;
+        this.lastRefill = Date.now();
+    }
+    /**
+     * Acquire a token, waiting if necessary.
+     * Returns immediately if rate limiting is disabled (maxTokens = 0).
+     * @param signal - Optional AbortSignal to cancel the wait
+     */
+    async acquire(signal) {
+        if (this.maxTokens === 0)
+            return; // Disabled
+        this.refill();
+        if (this.tokens < 1) {
+            if (signal?.aborted) {
+                throw new Error('Rate limiter acquire aborted');
+            }
+            const waitTime = Math.ceil((1 - this.tokens) / this.refillRate);
+            await new Promise((resolve, reject) => {
+                const timer = setTimeout(() => {
+                    cleanup();
+                    resolve();
+                }, waitTime);
+                const onAbort = () => {
+                    clearTimeout(timer);
+                    cleanup();
+                    reject(new Error('Rate limiter acquire aborted'));
+                };
+                const cleanup = () => {
+                    signal?.removeEventListener('abort', onAbort);
+                };
+                signal?.addEventListener('abort', onAbort, { once: true });
+            });
+            this.refill();
+        }
+        this.tokens -= 1;
+    }
+    refill() {
+        const now = Date.now();
+        const elapsed = now - this.lastRefill;
+        this.tokens = Math.min(this.maxTokens, this.tokens + elapsed * this.refillRate);
+        this.lastRefill = now;
+    }
+}
+/**
+ * Check if a value is a valid positive integer ID
+ */
+export function isValidId(value) {
+    if (typeof value === 'number') {
+        return Number.isInteger(value) && value >= 1 && value <= Number.MAX_SAFE_INTEGER;
+    }
+    if (typeof value === 'string') {
+        const num = parseInt(value, 10);
+        return !isNaN(num) && num >= 1 && num <= Number.MAX_SAFE_INTEGER;
+    }
+    return false;
+}
+//# sourceMappingURL=security.js.map

package/dist/security.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.js","sourceRoot":"","sources":["../src/security.ts"],"names":[],"mappings":"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"}

package/dist/tools.d.ts

@@ -0,0 +1,82 @@
+/**
+ * MCP Tool Conversion
+ *
+ * Converts MainWP Abilities to MCP Tool definitions and handles
+ * tool execution by forwarding to the Abilities API.
+ */
+import { Tool, TextContent } from '@modelcontextprotocol/sdk/types.js';
+import { AbilityAnnotations } from './abilities.js';
+import { Config, SchemaVerbosity } from './config.js';
+import { Logger } from './logging.js';
+/**
+ * Check whether an error represents an idempotent no-op (already in desired state).
+ * Only matches 4xx HTTP errors with a recognized no-op error code.
+ * @internal
+ */
+export declare function isNoOpError(error: unknown): boolean;
+/**
+ * Get the current cumulative session data usage in bytes and the configured limit.
+ */
+export declare function getSessionDataUsage(config: Config): {
+    used: number;
+    limit: number;
+};
+/**
+ * Reset the cumulative session data counter to zero.
+ */
+export declare function resetSessionData(): void;
+/**
+ * Clear pending previews (for testing only).
+ * @internal
+ */
+export declare function clearPendingPreviews(): void;
+/**
+ * Options for tool execution
+ */
+export interface ExecuteToolOptions {
+    /** AbortSignal for cancellation support */
+    signal?: AbortSignal;
+}
+/**
+ * Generate contextual LLM instruction text from ability metadata.
+ *
+ * Produces safety guidance that tells the AI how to use a tool correctly:
+ * preview-first workflows, dry-run suggestions, or read-only assurance.
+ * API-provided instructions are prepended (they take priority).
+ * @internal
+ */
+export declare function generateInstructions(meta: AbilityAnnotations | undefined, hasDryRun: boolean, hasConfirm: boolean): string;
+/**
+ * Build safety tag string for tool descriptions.
+ *
+ * Standard mode: verbose tags like `[DESTRUCTIVE, Requires two-step confirmation]`
+ * Compact mode:  short tags like `[destructive, confirm]`
+ * @internal
+ */
+export declare function buildSafetyTags(meta: AbilityAnnotations | undefined, hasDryRun: boolean, hasConfirm: boolean, verbosity: SchemaVerbosity): string;
+/**
+ * Clear the cached tool list (for testing).
+ * @internal
+ */
+export declare function clearToolsCache(): void;
+/**
+ * Fetch all MainWP abilities and convert them to MCP tools
+ *
+ * Applies optional filtering based on config:
+ * - allowedTools: If set, only include tools in this list
+ * - blockedTools: If set, exclude tools in this list
+ *
+ * Caches the converted tool list by abilities array reference and config
+ * fingerprint. fetchAbilities() returns the same cached array while valid,
+ * so reference equality is a reliable cache key.
+ *
+ * @param config - Server configuration
+ * @param logger - Optional structured logger for filtering/verbosity messages
+ */
+export declare function getTools(config: Config, logger?: Logger): Promise<Tool[]>;
+export { abilityNameToToolName, toolNameToAbilityName } from './naming.js';
+/**
+ * Execute an MCP tool call by forwarding to the corresponding ability
+ */
+export declare function executeTool(config: Config, toolName: string, args: Record<string, unknown>, logger: Logger, options?: ExecuteToolOptions): Promise<TextContent[]>;
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,EAEL,kBAAkB,EAInB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,MAAM,EAAE,eAAe,EAAc,MAAM,aAAa,CAAC;AAGlE,OAAO,EAAE,MAAM,EAAiB,MAAM,cAAc,CAAC;AAsErD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAMnD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAEnF;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAG3C;AA6DD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,2CAA2C;IAC3C,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAmKD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,kBAAkB,GAAG,SAAS,EACpC,SAAS,EAAE,OAAO,EAClB,UAAU,EAAE,OAAO,GAClB,MAAM,CAyBR;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,kBAAkB,GAAG,SAAS,EACpC,SAAS,EAAE,OAAO,EAClB,UAAU,EAAE,OAAO,EACnB,SAAS,EAAE,eAAe,GACzB,MAAM,CAqBR;AA6GD;;;GAGG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAItC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAmD/E;AAGD,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAE3E;;GAEG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,WAAW,EAAE,CAAC,CAwYxB"}