@kelpi/mcp 0.1.0

package/dist/lib/error-formatter.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Formatted error with user-friendly message and optional hint
+ */
+export interface FormattedError {
+    /** User-friendly error message */
+    message: string;
+    /** Error code for programmatic handling */
+    code: string;
+    /** Actionable hint for the user to resolve the error */
+    hint?: string;
+}
+/**
+ * Error codes for different error types
+ */
+export declare const ErrorCodes: {
+    readonly AUTH_REQUIRED: "AUTH_REQUIRED";
+    readonly INVALID_API_KEY: "INVALID_API_KEY";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly CONFLICT: "CONFLICT";
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+    readonly SERVER_ERROR: "SERVER_ERROR";
+    readonly SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE";
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    readonly FORBIDDEN: "FORBIDDEN";
+    readonly CONFIG_ERROR: "CONFIG_ERROR";
+    readonly TIMEOUT: "TIMEOUT";
+    readonly UNKNOWN_ERROR: "UNKNOWN_ERROR";
+};
+/**
+ * Format errors for user-friendly display in MCP responses.
+ *
+ * This function takes any error type and converts it into a structured
+ * FormattedError with a user-friendly message, error code, and optional
+ * actionable hint.
+ *
+ * @param error - The error to format (can be any type)
+ * @returns FormattedError with message, code, and optional hint
+ */
+export declare function formatError(error: unknown): FormattedError;
+//# sourceMappingURL=error-formatter.d.ts.map

package/dist/lib/error-formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-formatter.d.ts","sourceRoot":"","sources":["../../src/lib/error-formatter.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;CAab,CAAC;AAEX;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CA+C1D"}

package/dist/lib/error-formatter.js

@@ -0,0 +1,149 @@
+import { AuthError, ApiError, ConfigError, TimeoutError } from './errors.js';
+/**
+ * Error codes for different error types
+ */
+export const ErrorCodes = {
+    AUTH_REQUIRED: 'AUTH_REQUIRED',
+    INVALID_API_KEY: 'INVALID_API_KEY',
+    NOT_FOUND: 'NOT_FOUND',
+    CONFLICT: 'CONFLICT',
+    VALIDATION_ERROR: 'VALIDATION_ERROR',
+    SERVER_ERROR: 'SERVER_ERROR',
+    SERVICE_UNAVAILABLE: 'SERVICE_UNAVAILABLE',
+    RATE_LIMITED: 'RATE_LIMITED',
+    FORBIDDEN: 'FORBIDDEN',
+    CONFIG_ERROR: 'CONFIG_ERROR',
+    TIMEOUT: 'TIMEOUT',
+    UNKNOWN_ERROR: 'UNKNOWN_ERROR',
+};
+/**
+ * Format errors for user-friendly display in MCP responses.
+ *
+ * This function takes any error type and converts it into a structured
+ * FormattedError with a user-friendly message, error code, and optional
+ * actionable hint.
+ *
+ * @param error - The error to format (can be any type)
+ * @returns FormattedError with message, code, and optional hint
+ */
+export function formatError(error) {
+    // Handle AuthError
+    if (error instanceof AuthError) {
+        return {
+            message: 'Authentication required',
+            code: ErrorCodes.AUTH_REQUIRED,
+            hint: 'Run kelpi_login first to authenticate',
+        };
+    }
+    // Handle ApiError
+    if (error instanceof ApiError) {
+        return formatApiError(error);
+    }
+    // Handle ConfigError
+    if (error instanceof ConfigError) {
+        return {
+            message: error.message,
+            code: ErrorCodes.CONFIG_ERROR,
+            hint: 'Run kelpi_login to configure your credentials',
+        };
+    }
+    // Handle TimeoutError
+    if (error instanceof TimeoutError) {
+        const seconds = Math.round(error.timeout / 1000);
+        return {
+            message: `Request timed out after ${seconds} seconds`,
+            code: ErrorCodes.TIMEOUT,
+            hint: 'Check your network connection and try again',
+        };
+    }
+    // Handle generic Error objects
+    if (error instanceof Error) {
+        return {
+            message: error.message,
+            code: ErrorCodes.UNKNOWN_ERROR,
+        };
+    }
+    // Handle non-Error values (string, null, undefined, objects)
+    return {
+        message: 'An unexpected error occurred',
+        code: ErrorCodes.UNKNOWN_ERROR,
+    };
+}
+/**
+ * Format API errors based on HTTP status code
+ */
+function formatApiError(error) {
+    const { status, validationErrors, message } = error;
+    // 400 Bad Request with validation errors
+    if (validationErrors && validationErrors.length > 0) {
+        const formattedErrors = validationErrors
+            .map((e) => `${e.field}: ${e.message}`)
+            .join(', ');
+        return {
+            message: formattedErrors,
+            code: ErrorCodes.VALIDATION_ERROR,
+            hint: 'Fix the validation errors and try again',
+        };
+    }
+    // 401 Unauthorized
+    if (status === 401) {
+        return {
+            message: 'API key is invalid or expired',
+            code: ErrorCodes.INVALID_API_KEY,
+            hint: 'Run kelpi_login to get a new API key',
+        };
+    }
+    // 403 Forbidden
+    if (status === 403) {
+        return {
+            message: message || 'Access denied',
+            code: ErrorCodes.FORBIDDEN,
+            hint: 'Check your API key permissions',
+        };
+    }
+    // 404 Not Found
+    if (status === 404) {
+        return {
+            message: message || 'Resource not found',
+            code: ErrorCodes.NOT_FOUND,
+            hint: 'Check that the ID is correct',
+        };
+    }
+    // 409 Conflict
+    if (status === 409) {
+        return {
+            message: message || 'Resource already exists',
+            code: ErrorCodes.CONFLICT,
+            hint: 'Use a different identifier or update the existing resource',
+        };
+    }
+    // 429 Rate Limited
+    if (status === 429) {
+        return {
+            message: message || 'Rate limit exceeded',
+            code: ErrorCodes.RATE_LIMITED,
+            hint: 'Please wait before making more requests',
+        };
+    }
+    // 503 Service Unavailable
+    if (status === 503) {
+        return {
+            message: message || 'Service temporarily unavailable',
+            code: ErrorCodes.SERVICE_UNAVAILABLE,
+            hint: 'Please try again in a few moments',
+        };
+    }
+    // 5xx Server Errors
+    if (status >= 500) {
+        return {
+            message: message || 'Internal server error',
+            code: ErrorCodes.SERVER_ERROR,
+        };
+    }
+    // Default case for other status codes
+    return {
+        message: message || 'Request failed',
+        code: ErrorCodes.UNKNOWN_ERROR,
+    };
+}
+//# sourceMappingURL=error-formatter.js.map

package/dist/lib/error-formatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-formatter.js","sourceRoot":"","sources":["../../src/lib/error-formatter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAc7E;;GAEG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,aAAa,EAAE,eAAe;IAC9B,eAAe,EAAE,iBAAiB;IAClC,SAAS,EAAE,WAAW;IACtB,QAAQ,EAAE,UAAU;IACpB,gBAAgB,EAAE,kBAAkB;IACpC,YAAY,EAAE,cAAc;IAC5B,mBAAmB,EAAE,qBAAqB;IAC1C,YAAY,EAAE,cAAc;IAC5B,SAAS,EAAE,WAAW;IACtB,YAAY,EAAE,cAAc;IAC5B,OAAO,EAAE,SAAS;IAClB,aAAa,EAAE,eAAe;CACtB,CAAC;AAEX;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,mBAAmB;IACnB,IAAI,KAAK,YAAY,SAAS,EAAE,CAAC;QAC/B,OAAO;YACL,OAAO,EAAE,yBAAyB;YAClC,IAAI,EAAE,UAAU,CAAC,aAAa;YAC9B,IAAI,EAAE,uCAAuC;SAC9C,CAAC;IACJ,CAAC;IAED,kBAAkB;IAClB,IAAI,KAAK,YAAY,QAAQ,EAAE,CAAC;QAC9B,OAAO,cAAc,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IAED,qBAAqB;IACrB,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;QACjC,OAAO;YACL,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,IAAI,EAAE,UAAU,CAAC,YAAY;YAC7B,IAAI,EAAE,+CAA+C;SACtD,CAAC;IACJ,CAAC;IAED,sBAAsB;IACtB,IAAI,KAAK,YAAY,YAAY,EAAE,CAAC;QAClC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;QACjD,OAAO;YACL,OAAO,EAAE,2BAA2B,OAAO,UAAU;YACrD,IAAI,EAAE,UAAU,CAAC,OAAO;YACxB,IAAI,EAAE,6CAA6C;SACpD,CAAC;IACJ,CAAC;IAED,+BAA+B;IAC/B,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,OAAO;YACL,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,IAAI,EAAE,UAAU,CAAC,aAAa;SAC/B,CAAC;IACJ,CAAC;IAED,6DAA6D;IAC7D,OAAO;QACL,OAAO,EAAE,8BAA8B;QACvC,IAAI,EAAE,UAAU,CAAC,aAAa;KAC/B,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAS,cAAc,CAAC,KAAe;IACrC,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;IAEpD,yCAAyC;IACzC,IAAI,gBAAgB,IAAI,gBAAgB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpD,MAAM,eAAe,GAAG,gBAAgB;aACrC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;aACtC,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,OAAO;YACL,OAAO,EAAE,eAAe;YACxB,IAAI,EAAE,UAAU,CAAC,gBAAgB;YACjC,IAAI,EAAE,yCAAyC;SAChD,CAAC;IACJ,CAAC;IAED,mBAAmB;IACnB,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACnB,OAAO;YACL,OAAO,EAAE,+BAA+B;YACxC,IAAI,EAAE,UAAU,CAAC,eAAe;YAChC,IAAI,EAAE,sCAAsC;SAC7C,CAAC;IACJ,CAAC;IAED,gBAAgB;IAChB,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACnB,OAAO;YACL,OAAO,EAAE,OAAO,IAAI,eAAe;YACnC,IAAI,EAAE,UAAU,CAAC,SAAS;YAC1B,IAAI,EAAE,gCAAgC;SACvC,CAAC;IACJ,CAAC;IAED,gBAAgB;IAChB,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACnB,OAAO;YACL,OAAO,EAAE,OAAO,IAAI,oBAAoB;YACxC,IAAI,EAAE,UAAU,CAAC,SAAS;YAC1B,IAAI,EAAE,8BAA8B;SACrC,CAAC;IACJ,CAAC;IAED,eAAe;IACf,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACnB,OAAO;YACL,OAAO,EAAE,OAAO,IAAI,yBAAyB;YAC7C,IAAI,EAAE,UAAU,CAAC,QAAQ;YACzB,IAAI,EAAE,4DAA4D;SACnE,CAAC;IACJ,CAAC;IAED,mBAAmB;IACnB,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACnB,OAAO;YACL,OAAO,EAAE,OAAO,IAAI,qBAAqB;YACzC,IAAI,EAAE,UAAU,CAAC,YAAY;YAC7B,IAAI,EAAE,yCAAyC;SAChD,CAAC;IACJ,CAAC;IAED,0BAA0B;IAC1B,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACnB,OAAO;YACL,OAAO,EAAE,OAAO,IAAI,iCAAiC;YACrD,IAAI,EAAE,UAAU,CAAC,mBAAmB;YACpC,IAAI,EAAE,mCAAmC;SAC1C,CAAC;IACJ,CAAC;IAED,oBAAoB;IACpB,IAAI,MAAM,IAAI,GAAG,EAAE,CAAC;QAClB,OAAO;YACL,OAAO,EAAE,OAAO,IAAI,uBAAuB;YAC3C,IAAI,EAAE,UAAU,CAAC,YAAY;SAC9B,CAAC;IACJ,CAAC;IAED,sCAAsC;IACtC,OAAO;QACL,OAAO,EAAE,OAAO,IAAI,gBAAgB;QACpC,IAAI,EAAE,UAAU,CAAC,aAAa;KAC/B,CAAC;AACJ,CAAC"}

package/dist/lib/errors.d.ts

@@ -0,0 +1,44 @@
+import type { ValidationError } from '../types.js';
+/**
+ * Base error class for all Kelpi MCP errors
+ */
+export declare class KelpiError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/**
+ * Error class for configuration-related errors
+ */
+export declare class ConfigError extends KelpiError {
+    constructor(message: string);
+}
+/**
+ * Validation details from Zod's flatten() format
+ */
+export interface ValidationDetails {
+    formErrors?: string[];
+    fieldErrors?: Record<string, string[]>;
+}
+/**
+ * Error class for API HTTP errors
+ */
+export declare class ApiError extends KelpiError {
+    readonly status: number;
+    readonly validationErrors?: ValidationError[];
+    readonly details?: ValidationDetails;
+    constructor(message: string, status: number, validationErrors?: ValidationError[], details?: ValidationDetails);
+}
+/**
+ * Authentication error for 401 responses or invalid credentials
+ */
+export declare class AuthError extends KelpiError {
+    constructor(message: string);
+}
+/**
+ * Timeout error for requests that exceed the timeout duration
+ */
+export declare class TimeoutError extends KelpiError {
+    readonly timeout: number;
+    constructor(message: string, timeout: number);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/lib/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD;;GAEG;AACH,qBAAa,UAAW,SAAQ,KAAK;IACnC,SAAgB,IAAI,EAAE,MAAM,CAAC;gBAEjB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAK1C;AAED;;GAEG;AACH,qBAAa,WAAY,SAAQ,UAAU;gBAC7B,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CACxC;AAED;;GAEG;AACH,qBAAa,QAAS,SAAQ,UAAU;IACtC,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,gBAAgB,CAAC,EAAE,eAAe,EAAE,CAAC;IACrD,SAAgB,OAAO,CAAC,EAAE,iBAAiB,CAAC;gBAG1C,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,gBAAgB,CAAC,EAAE,eAAe,EAAE,EACpC,OAAO,CAAC,EAAE,iBAAiB;CAQ9B;AAED;;GAEG;AACH,qBAAa,SAAU,SAAQ,UAAU;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,UAAU;IAC1C,SAAgB,OAAO,EAAE,MAAM,CAAC;gBAEpB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK7C"}

package/dist/lib/errors.js

@@ -0,0 +1,56 @@
+/**
+ * Base error class for all Kelpi MCP errors
+ */
+export class KelpiError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = 'KelpiError';
+        this.code = code;
+    }
+}
+/**
+ * Error class for configuration-related errors
+ */
+export class ConfigError extends KelpiError {
+    constructor(message) {
+        super(message, 'CONFIG_ERROR');
+        this.name = 'ConfigError';
+    }
+}
+/**
+ * Error class for API HTTP errors
+ */
+export class ApiError extends KelpiError {
+    status;
+    validationErrors;
+    details;
+    constructor(message, status, validationErrors, details) {
+        super(message, 'API_ERROR');
+        this.name = 'ApiError';
+        this.status = status;
+        this.validationErrors = validationErrors;
+        this.details = details;
+    }
+}
+/**
+ * Authentication error for 401 responses or invalid credentials
+ */
+export class AuthError extends KelpiError {
+    constructor(message) {
+        super(message, 'AUTH_ERROR');
+        this.name = 'AuthError';
+    }
+}
+/**
+ * Timeout error for requests that exceed the timeout duration
+ */
+export class TimeoutError extends KelpiError {
+    timeout;
+    constructor(message, timeout) {
+        super(message, 'TIMEOUT_ERROR');
+        this.name = 'TimeoutError';
+        this.timeout = timeout;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/lib/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,OAAO,UAAW,SAAQ,KAAK;IACnB,IAAI,CAAS;IAE7B,YAAY,OAAe,EAAE,IAAY;QACvC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,WAAY,SAAQ,UAAU;IACzC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF;AAUD;;GAEG;AACH,MAAM,OAAO,QAAS,SAAQ,UAAU;IACtB,MAAM,CAAS;IACf,gBAAgB,CAAqB;IACrC,OAAO,CAAqB;IAE5C,YACE,OAAe,EACf,MAAc,EACd,gBAAoC,EACpC,OAA2B;QAE3B,KAAK,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,gBAAgB,GAAG,gBAAgB,CAAC;QACzC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,SAAU,SAAQ,UAAU;IACvC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,YAAa,SAAQ,UAAU;IAC1B,OAAO,CAAS;IAEhC,YAAY,OAAe,EAAE,OAAe;QAC1C,KAAK,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF"}

package/dist/lib/tool-helpers.d.ts

@@ -0,0 +1,49 @@
+import type { ToolResult } from './tool-registry.js';
+import { ApiError, type ApiClient } from './api-client.js';
+import type { ZodError } from 'zod';
+/**
+ * Context provided to authenticated tool handlers
+ */
+export interface AuthenticatedContext {
+    client: ApiClient;
+    apiUrl: string;
+}
+/**
+ * Creates a successful text response
+ */
+export declare function successResponse(data: unknown): ToolResult;
+/**
+ * Creates a plain text response (not JSON)
+ */
+export declare function textResponse(text: string): ToolResult;
+/**
+ * Creates an error response with standard format
+ */
+export declare function errorResponse(error: string, message: string, extra?: Record<string, unknown>): ToolResult;
+/**
+ * Creates an authentication required error response
+ */
+export declare function authRequiredResponse(action: string): ToolResult;
+/**
+ * Formats Zod validation errors into a standard response
+ */
+export declare function validationErrorResponse(zodError: ZodError, defaultMessage?: string): ToolResult;
+/**
+ * Formats an ApiError into a standard error response
+ */
+export declare function apiErrorResponse(err: ApiError, action: string): ToolResult;
+/**
+ * Formats any error into a standard error response
+ */
+export declare function unknownErrorResponse(err: unknown, action: string): ToolResult;
+/**
+ * Wraps a handler that requires authentication.
+ * Loads config, checks for API key, and creates an API client.
+ * Returns early with auth error if not authenticated.
+ */
+export declare function withAuth(action: string, handler: (ctx: AuthenticatedContext) => Promise<ToolResult>): Promise<ToolResult>;
+/**
+ * Handles errors from API calls with standard formatting
+ */
+export declare function handleApiError(err: unknown, action: string): ToolResult;
+//# sourceMappingURL=tool-helpers.d.ts.map

package/dist/lib/tool-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-helpers.d.ts","sourceRoot":"","sources":["../../src/lib/tool-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,OAAO,EAAmB,QAAQ,EAAE,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAC;AAEpC;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,SAAS,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,UAAU,CAIzD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAIrD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,UAAU,CAUZ;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAK/D;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,QAAQ,EAClB,cAAc,SAAkB,GAC/B,UAAU,CASZ;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,CAoB1E;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,CAK7E;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAC5B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,CAAC,GAAG,EAAE,oBAAoB,KAAK,OAAO,CAAC,UAAU,CAAC,GAC1D,OAAO,CAAC,UAAU,CAAC,CAWrB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,CAKvE"}

package/dist/lib/tool-helpers.js

@@ -0,0 +1,101 @@
+import { loadConfig, getApiUrl } from './config.js';
+import { createApiClient, ApiError } from './api-client.js';
+/**
+ * Creates a successful text response
+ */
+export function successResponse(data) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+    };
+}
+/**
+ * Creates a plain text response (not JSON)
+ */
+export function textResponse(text) {
+    return {
+        content: [{ type: 'text', text }],
+    };
+}
+/**
+ * Creates an error response with standard format
+ */
+export function errorResponse(error, message, extra) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({ error, message, ...extra }, null, 2),
+            },
+        ],
+        isError: true,
+    };
+}
+/**
+ * Creates an authentication required error response
+ */
+export function authRequiredResponse(action) {
+    return errorResponse('Not authenticated', `Please run kelpi_login to authenticate before ${action}.`);
+}
+/**
+ * Formats Zod validation errors into a standard response
+ */
+export function validationErrorResponse(zodError, defaultMessage = 'Invalid input') {
+    const errors = zodError.errors.map((e) => ({
+        path: e.path.join('.'),
+        message: e.message,
+    }));
+    return errorResponse('Validation failed', errors[0]?.message || defaultMessage, {
+        validation_errors: errors,
+    });
+}
+/**
+ * Formats an ApiError into a standard error response
+ */
+export function apiErrorResponse(err, action) {
+    const response = {
+        error: `Failed to ${action}`,
+        message: err.message,
+        status: err.status,
+    };
+    if (err.validationErrors) {
+        response.validation_errors = err.validationErrors;
+    }
+    // Include Zod validation details if present (from Kelpi API)
+    if (err.details) {
+        response.details = err.details;
+    }
+    return {
+        content: [{ type: 'text', text: JSON.stringify(response, null, 2) }],
+        isError: true,
+    };
+}
+/**
+ * Formats any error into a standard error response
+ */
+export function unknownErrorResponse(err, action) {
+    return errorResponse(`Failed to ${action}`, err instanceof Error ? err.message : 'Unknown error');
+}
+/**
+ * Wraps a handler that requires authentication.
+ * Loads config, checks for API key, and creates an API client.
+ * Returns early with auth error if not authenticated.
+ */
+export async function withAuth(action, handler) {
+    const config = await loadConfig();
+    if (!config.api_key) {
+        return authRequiredResponse(action);
+    }
+    const apiUrl = config.api_url || (await getApiUrl());
+    const client = createApiClient({ apiKey: config.api_key, apiUrl });
+    return handler({ client, apiUrl });
+}
+/**
+ * Handles errors from API calls with standard formatting
+ */
+export function handleApiError(err, action) {
+    if (err instanceof ApiError) {
+        return apiErrorResponse(err, action);
+    }
+    return unknownErrorResponse(err, action);
+}
+//# sourceMappingURL=tool-helpers.js.map

package/dist/lib/tool-helpers.js.map

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

package/dist/lib/tool-registry.d.ts

@@ -0,0 +1,111 @@
+import { z, type ZodType } from 'zod';
+/**
+ * Result content item for tool responses
+ */
+export interface ToolContentItem {
+    type: 'text' | 'image' | 'resource';
+    text?: string;
+    data?: string;
+    mimeType?: string;
+}
+/**
+ * Tool execution result
+ */
+export interface ToolResult {
+    content: ToolContentItem[];
+    isError?: boolean;
+}
+/**
+ * Tool definition with Zod schema for input validation
+ * Uses ZodType to support both ZodObject and ZodEffects (from .refine())
+ */
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: ZodType<Record<string, unknown>>;
+}
+/**
+ * Tool handler function type
+ */
+export type ToolHandler = (input: Record<string, unknown>) => Promise<ToolResult>;
+/**
+ * Tool with its definition and handler.
+ * Used for registration and exported for use in tool modules.
+ */
+export interface ToolWithHandler {
+    definition: ToolDefinition;
+    handler: ToolHandler;
+}
+/**
+ * Registered tool with definition and handler
+ * @deprecated Use ToolWithHandler instead
+ */
+export type RegisteredTool = ToolWithHandler;
+/**
+ * MCP-compatible tool format for listing
+ */
+export interface McpTool {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+/**
+ * Validation result type
+ */
+export type ValidationResult = {
+    success: true;
+    data: Record<string, unknown>;
+} | {
+    success: false;
+    error: z.ZodError;
+};
+/**
+ * Custom error class for tool registry operations
+ */
+export declare class ToolRegistryError extends Error {
+    readonly code?: string;
+    constructor(message: string, code?: string);
+}
+/**
+ * Registry for managing MCP tools with Zod validation
+ */
+export declare class ToolRegistry {
+    private tools;
+    /**
+     * Register a tool with its definition and handler
+     */
+    register(definition: ToolDefinition, handler: ToolHandler): void;
+    /**
+     * Get a registered tool by name
+     */
+    get(name: string): RegisteredTool | undefined;
+    /**
+     * List all registered tools in MCP-compatible format
+     */
+    list(): McpTool[];
+    /**
+     * Validate input against a tool's schema
+     */
+    validateInput(toolName: string, input: unknown): ValidationResult;
+    /**
+     * Execute a tool with validated input
+     */
+    execute(toolName: string, input: unknown): Promise<ToolResult>;
+    /**
+     * Check if a tool is registered
+     */
+    has(name: string): boolean;
+    /**
+     * Get the number of registered tools
+     */
+    get size(): number;
+    /**
+     * Clear all registered tools
+     */
+    clear(): void;
+}
+//# sourceMappingURL=tool-registry.d.ts.map

package/dist/lib/tool-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-registry.d.ts","sourceRoot":"","sources":["../../src/lib/tool-registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,KAAK,OAAO,EAAE,MAAM,KAAK,CAAC;AAGtC;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,UAAU,CAAC;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC/C;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;AAElF;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,cAAc,CAAC;IAC3B,OAAO,EAAE,WAAW,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,eAAe,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAChD;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,CAAA;CAAE,CAAC;AAE1C;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,SAAgB,IAAI,CAAC,EAAE,MAAM,CAAC;gBAElB,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM;CAS3C;AAED;;GAEG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAA0C;IAEvD;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,cAAc,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI;IAWhE;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAI7C;;OAEG;IACH,IAAI,IAAI,OAAO,EAAE;IA8BjB;;OAEG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,gBAAgB;IAajE;;OAEG;IACG,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC;IAmBpE;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,KAAK,IAAI,IAAI;CAGd"}