@vibescope/mcp-server 0.3.0 → 0.3.3

package/src/utils.ts

@@ -467,3 +467,120 @@ export function normalizeGitUrl(gitUrl: string | null | undefined): string | nul
 
 	return normalized;
 }
+
+// ============================================================================
+// Error Handling Utilities
+// Shared error extraction and type checking functions
+// ============================================================================
+
+/**
+ * Extract a human-readable message from any error type.
+ * Handles Error objects, strings, and unknown values.
+ *
+ * @example
+ * try { ... } catch (e) {
+ *   console.error(getErrorMessage(e));
+ * }
+ */
+export function getErrorMessage(error: unknown): string {
+	if (error instanceof Error) {
+		return error.message;
+	}
+	if (typeof error === 'string') {
+		return error;
+	}
+	return String(error);
+}
+
+/**
+ * Type guard to check if a value is an object with an 'error' property.
+ * Useful for checking API responses that may contain application-level errors.
+ *
+ * @example
+ * if (hasErrorProperty(response.data)) {
+ *   return error(getErrorMessage(response.data.error));
+ * }
+ */
+export function hasErrorProperty(value: unknown): value is { error: unknown } {
+	return typeof value === 'object' && value !== null && 'error' in value;
+}
+
+/**
+ * Extract an error message from an API response body.
+ * Handles the common pattern where API returns { error: string } or { error: { message: string } }.
+ * Returns null if no error is found.
+ *
+ * @example
+ * const apiError = extractApiError(response.data);
+ * if (apiError) {
+ *   return error(apiError);
+ * }
+ */
+export function extractApiError(data: unknown): string | null {
+	if (!hasErrorProperty(data)) {
+		return null;
+	}
+
+	const err = data.error;
+
+	// Direct string error
+	if (typeof err === 'string') {
+		return err;
+	}
+
+	// Nested error object with message property
+	if (typeof err === 'object' && err !== null && 'message' in err) {
+		const msg = (err as { message: unknown }).message;
+		if (typeof msg === 'string') {
+			return msg;
+		}
+	}
+
+	// Fallback for unknown error structure
+	return 'Unknown error';
+}
+
+// ============================================================================
+// Pagination Utilities
+// ============================================================================
+
+/**
+ * Default pagination limits
+ */
+export const PAGINATION_LIMITS = {
+	/** Default maximum limit for paginated results */
+	DEFAULT_MAX_LIMIT: 50,
+	/** Default limit when not specified */
+	DEFAULT_LIMIT: 20,
+	/** Smaller limit for task listings */
+	TASK_LIMIT: 20,
+} as const;
+
+/**
+ * Cap pagination parameters to safe values.
+ * Ensures limit is between 1 and maxLimit, and offset is non-negative.
+ *
+ * @param limit - Requested limit (will be capped between 1 and maxLimit)
+ * @param offset - Requested offset (will be made non-negative)
+ * @param maxLimit - Maximum allowed limit (default: PAGINATION_LIMITS.DEFAULT_MAX_LIMIT)
+ * @returns Object with cappedLimit and safeOffset
+ *
+ * @example
+ * const { cappedLimit, safeOffset } = capPagination(limit, offset);
+ * const { data } = await query.range(safeOffset, safeOffset + cappedLimit - 1);
+ *
+ * @example
+ * // With custom max limit
+ * const { cappedLimit, safeOffset } = capPagination(limit, offset, 20);
+ */
+export function capPagination(
+	limit: number | undefined,
+	offset: number | undefined,
+	maxLimit: number = PAGINATION_LIMITS.DEFAULT_MAX_LIMIT
+): { cappedLimit: number; safeOffset: number } {
+	const effectiveLimit = limit ?? PAGINATION_LIMITS.DEFAULT_LIMIT;
+	return {
+		cappedLimit: Math.min(Math.max(1, effectiveLimit), maxLimit),
+		safeOffset: Math.max(0, offset ?? 0)
+	};
+}

package/dist/tools.d.ts

@@ -1,2 +0,0 @@
-import type { Tool } from '@modelcontextprotocol/sdk/types.js';
-export declare const tools: Tool[];