latitude-mcp-server 1.0.0

package/dist/utils/constants.util.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Application constants
+ *
+ * This file contains constants used throughout the application.
+ * Centralizing these values makes them easier to maintain and update.
+ */
+/**
+ * Current application version
+ * This should match the version in package.json
+ */
+export declare const VERSION = "1.0.0";
+/**
+ * Package name with scope
+ * Used for initialization and identification
+ */
+export declare const PACKAGE_NAME = "@anthropic/latitude-mcp-server";
+/**
+ * CLI command name
+ * Used for binary name and CLI help text
+ */
+export declare const CLI_NAME = "latitude-mcp";
+/**
+ * Latitude API configuration
+ */
+export declare const LATITUDE_BASE_URL = "https://gateway.latitude.so";
+export declare const LATITUDE_API_VERSION = "v3";

package/dist/utils/constants.util.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * Application constants
+ *
+ * This file contains constants used throughout the application.
+ * Centralizing these values makes them easier to maintain and update.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LATITUDE_API_VERSION = exports.LATITUDE_BASE_URL = exports.CLI_NAME = exports.PACKAGE_NAME = exports.VERSION = void 0;
+/**
+ * Current application version
+ * This should match the version in package.json
+ */
+exports.VERSION = '1.0.0';
+/**
+ * Package name with scope
+ * Used for initialization and identification
+ */
+exports.PACKAGE_NAME = '@anthropic/latitude-mcp-server';
+/**
+ * CLI command name
+ * Used for binary name and CLI help text
+ */
+exports.CLI_NAME = 'latitude-mcp';
+/**
+ * Latitude API configuration
+ */
+exports.LATITUDE_BASE_URL = 'https://gateway.latitude.so';
+exports.LATITUDE_API_VERSION = 'v3';

package/dist/utils/error-handler.util.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Standard error codes for consistent handling
+ */
+export declare enum ErrorCode {
+    NOT_FOUND = "NOT_FOUND",
+    INVALID_CURSOR = "INVALID_CURSOR",
+    ACCESS_DENIED = "ACCESS_DENIED",
+    VALIDATION_ERROR = "VALIDATION_ERROR",
+    UNEXPECTED_ERROR = "UNEXPECTED_ERROR",
+    NETWORK_ERROR = "NETWORK_ERROR",
+    RATE_LIMIT_ERROR = "RATE_LIMIT_ERROR"
+}
+/**
+ * Context information for error handling
+ */
+export interface ErrorContext {
+    /**
+     * Source of the error (e.g., file path and function)
+     */
+    source?: string;
+    /**
+     * Type of entity being processed (e.g., 'IP Address', 'User')
+     */
+    entityType?: string;
+    /**
+     * Identifier of the entity being processed
+     */
+    entityId?: string | Record<string, string>;
+    /**
+     * Operation being performed (e.g., 'retrieving', 'searching')
+     */
+    operation?: string;
+    /**
+     * Additional information for debugging
+     */
+    additionalInfo?: Record<string, unknown>;
+}
+/**
+ * Helper function to create a consistent error context object
+ * @param entityType Type of entity being processed
+ * @param operation Operation being performed
+ * @param source Source of the error (typically file path and function)
+ * @param entityId Optional identifier of the entity
+ * @param additionalInfo Optional additional information for debugging
+ * @returns A formatted ErrorContext object
+ */
+export declare function buildErrorContext(entityType: string, operation: string, source: string, entityId?: string | Record<string, string>, additionalInfo?: Record<string, unknown>): ErrorContext;
+/**
+ * Handle controller errors consistently
+ * @param error The error to handle
+ * @param context Context information for better error messages
+ * @returns Never returns, always throws an error
+ */
+export declare function handleControllerError(error: unknown, context?: ErrorContext): never;

package/dist/utils/error-handler.util.js

@@ -0,0 +1,202 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ErrorCode = void 0;
+exports.buildErrorContext = buildErrorContext;
+exports.handleControllerError = handleControllerError;
+const error_util_js_1 = require("./error.util.js");
+const logger_util_js_1 = require("./logger.util.js");
+/**
+ * Standard error codes for consistent handling
+ */
+var ErrorCode;
+(function (ErrorCode) {
+    ErrorCode["NOT_FOUND"] = "NOT_FOUND";
+    ErrorCode["INVALID_CURSOR"] = "INVALID_CURSOR";
+    ErrorCode["ACCESS_DENIED"] = "ACCESS_DENIED";
+    ErrorCode["VALIDATION_ERROR"] = "VALIDATION_ERROR";
+    ErrorCode["UNEXPECTED_ERROR"] = "UNEXPECTED_ERROR";
+    ErrorCode["NETWORK_ERROR"] = "NETWORK_ERROR";
+    ErrorCode["RATE_LIMIT_ERROR"] = "RATE_LIMIT_ERROR";
+})(ErrorCode || (exports.ErrorCode = ErrorCode = {}));
+/**
+ * Helper function to create a consistent error context object
+ * @param entityType Type of entity being processed
+ * @param operation Operation being performed
+ * @param source Source of the error (typically file path and function)
+ * @param entityId Optional identifier of the entity
+ * @param additionalInfo Optional additional information for debugging
+ * @returns A formatted ErrorContext object
+ */
+function buildErrorContext(entityType, operation, source, entityId, additionalInfo) {
+    return {
+        entityType,
+        operation,
+        source,
+        ...(entityId && { entityId }),
+        ...(additionalInfo && { additionalInfo }),
+    };
+}
+/**
+ * Detect specific error types from raw errors
+ * @param error The error to analyze
+ * @param context Context information for better error detection
+ * @returns Object containing the error code and status code
+ */
+function detectErrorType(error, context = {}) {
+    const methodLogger = logger_util_js_1.Logger.forContext('utils/error-handler.util.ts', 'detectErrorType');
+    methodLogger.debug(`Detecting error type`, { error, context });
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    const statusCode = error instanceof Error && 'statusCode' in error
+        ? error.statusCode
+        : undefined;
+    // Network error detection
+    if (errorMessage.includes('network error') ||
+        errorMessage.includes('fetch failed') ||
+        errorMessage.includes('ECONNREFUSED') ||
+        errorMessage.includes('ENOTFOUND') ||
+        errorMessage.includes('Failed to fetch') ||
+        errorMessage.includes('Network request failed')) {
+        return { code: ErrorCode.NETWORK_ERROR, statusCode: 500 };
+    }
+    // Rate limiting detection
+    if (errorMessage.includes('rate limit') ||
+        errorMessage.includes('too many requests') ||
+        statusCode === 429) {
+        return { code: ErrorCode.RATE_LIMIT_ERROR, statusCode: 429 };
+    }
+    // Not Found detection
+    if (errorMessage.includes('not found') ||
+        errorMessage.includes('does not exist') ||
+        statusCode === 404) {
+        return { code: ErrorCode.NOT_FOUND, statusCode: 404 };
+    }
+    // Access Denied detection
+    if (errorMessage.includes('access') ||
+        errorMessage.includes('permission') ||
+        errorMessage.includes('authorize') ||
+        errorMessage.includes('authentication') ||
+        statusCode === 401 ||
+        statusCode === 403) {
+        return { code: ErrorCode.ACCESS_DENIED, statusCode: statusCode || 403 };
+    }
+    // Invalid Cursor detection
+    if ((errorMessage.includes('cursor') ||
+        errorMessage.includes('startAt') ||
+        errorMessage.includes('page')) &&
+        (errorMessage.includes('invalid') || errorMessage.includes('not valid'))) {
+        return { code: ErrorCode.INVALID_CURSOR, statusCode: 400 };
+    }
+    // Validation Error detection
+    if (errorMessage.includes('validation') ||
+        errorMessage.includes('invalid') ||
+        errorMessage.includes('required') ||
+        statusCode === 400 ||
+        statusCode === 422) {
+        return {
+            code: ErrorCode.VALIDATION_ERROR,
+            statusCode: statusCode || 400,
+        };
+    }
+    // Default to unexpected error
+    return {
+        code: ErrorCode.UNEXPECTED_ERROR,
+        statusCode: statusCode || 500,
+    };
+}
+/**
+ * Create user-friendly error messages based on error type and context
+ * @param code The error code
+ * @param context Context information for better error messages
+ * @param originalMessage The original error message
+ * @returns User-friendly error message
+ */
+function createUserFriendlyErrorMessage(code, context = {}, originalMessage) {
+    const methodLogger = logger_util_js_1.Logger.forContext('utils/error-handler.util.ts', 'createUserFriendlyErrorMessage');
+    const { entityType, entityId, operation } = context;
+    // Format entity ID for display
+    let entityIdStr = '';
+    if (entityId) {
+        if (typeof entityId === 'string') {
+            entityIdStr = entityId;
+        }
+        else {
+            // Handle object entityId
+            entityIdStr = Object.values(entityId).join('/');
+        }
+    }
+    // Determine entity display name
+    const entity = entityType
+        ? `${entityType}${entityIdStr ? ` ${entityIdStr}` : ''}`
+        : 'Resource';
+    let message = '';
+    switch (code) {
+        case ErrorCode.NOT_FOUND:
+            message = `${entity} not found${entityIdStr ? `: ${entityIdStr}` : ''}. Verify the ID is correct and that you have access to this ${entityType?.toLowerCase() || 'resource'}.`;
+            break;
+        case ErrorCode.ACCESS_DENIED:
+            message = `Access denied for ${entity.toLowerCase()}${entityIdStr ? ` ${entityIdStr}` : ''}. Verify your credentials and permissions.`;
+            break;
+        case ErrorCode.INVALID_CURSOR:
+            message = `Invalid pagination cursor. Use the exact cursor string returned from previous results.`;
+            break;
+        case ErrorCode.VALIDATION_ERROR:
+            message =
+                originalMessage ||
+                    `Invalid data provided for ${operation || 'operation'} ${entity.toLowerCase()}.`;
+            break;
+        case ErrorCode.NETWORK_ERROR:
+            message = `Network error while ${operation || 'connecting to'} the service. Please check your internet connection and try again.`;
+            break;
+        case ErrorCode.RATE_LIMIT_ERROR:
+            message = `Rate limit exceeded. Please wait a moment and try again, or reduce the frequency of requests.`;
+            break;
+        default:
+            message = `An unexpected error occurred while ${operation || 'processing'} ${entity.toLowerCase()}.`;
+    }
+    // Include original message details if available and appropriate
+    if (originalMessage &&
+        code !== ErrorCode.NOT_FOUND &&
+        code !== ErrorCode.ACCESS_DENIED) {
+        message += ` Error details: ${originalMessage}`;
+    }
+    methodLogger.debug(`Created user-friendly message: ${message}`, {
+        code,
+        context,
+    });
+    return message;
+}
+/**
+ * Handle controller errors consistently
+ * @param error The error to handle
+ * @param context Context information for better error messages
+ * @returns Never returns, always throws an error
+ */
+function handleControllerError(error, context = {}) {
+    const methodLogger = logger_util_js_1.Logger.forContext('utils/error-handler.util.ts', 'handleControllerError');
+    // Extract error details
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    const statusCode = error instanceof Error && 'statusCode' in error
+        ? error.statusCode
+        : undefined;
+    // Detect error type using utility
+    const { code, statusCode: detectedStatus } = detectErrorType(error, context);
+    // Combine detected status with explicit status
+    const finalStatusCode = statusCode || detectedStatus;
+    // Format entity information for logging
+    const { entityType, entityId, operation } = context;
+    const entity = entityType || 'resource';
+    const entityIdStr = entityId
+        ? typeof entityId === 'string'
+            ? entityId
+            : JSON.stringify(entityId)
+        : '';
+    const actionStr = operation || 'processing';
+    // Log detailed error information
+    methodLogger.error(`Error ${actionStr} ${entity}${entityIdStr ? `: ${entityIdStr}` : ''}: ${errorMessage}`, error);
+    // Create user-friendly error message for the response
+    const message = code === ErrorCode.VALIDATION_ERROR
+        ? errorMessage
+        : createUserFriendlyErrorMessage(code, context, errorMessage);
+    // Throw an appropriate API error with the user-friendly message
+    throw (0, error_util_js_1.createApiError)(message, finalStatusCode, error);
+}

package/dist/utils/error-handler.util.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/error.util.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Error types for classification
+ */
+export declare enum ErrorType {
+    AUTH_MISSING = "AUTH_MISSING",
+    AUTH_INVALID = "AUTH_INVALID",
+    API_ERROR = "API_ERROR",
+    UNEXPECTED_ERROR = "UNEXPECTED_ERROR"
+}
+/**
+ * Custom error class with type classification
+ */
+export declare class McpError extends Error {
+    type: ErrorType;
+    statusCode?: number;
+    originalError?: unknown;
+    constructor(message: string, type: ErrorType, statusCode?: number, originalError?: unknown);
+}
+/**
+ * Create an authentication missing error
+ */
+export declare function createAuthMissingError(message?: string): McpError;
+/**
+ * Create an authentication invalid error
+ */
+export declare function createAuthInvalidError(message?: string): McpError;
+/**
+ * Create an API error
+ */
+export declare function createApiError(message: string, statusCode?: number, originalError?: unknown): McpError;
+/**
+ * Create an unexpected error
+ */
+export declare function createUnexpectedError(message?: string, originalError?: unknown): McpError;
+/**
+ * Ensure an error is an McpError
+ */
+export declare function ensureMcpError(error: unknown): McpError;
+/**
+ * Get the deepest original error from an error chain
+ * @param error The error to extract the original cause from
+ * @returns The deepest original error or the error itself
+ */
+export declare function getDeepOriginalError(error: unknown): unknown;
+/**
+ * Format error for MCP tool response
+ */
+export declare function formatErrorForMcpTool(error: unknown): {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    metadata?: {
+        errorType: ErrorType;
+        statusCode?: number;
+        errorDetails?: unknown;
+    };
+};
+/**
+ * Format error for MCP resource response
+ */
+export declare function formatErrorForMcpResource(error: unknown, uri: string): {
+    contents: Array<{
+        uri: string;
+        text: string;
+        mimeType: string;
+        description?: string;
+    }>;
+};
+/**
+ * Handle error in CLI context with improved user feedback
+ */
+export declare function handleCliError(error: unknown): never;

package/dist/utils/error.util.js

@@ -0,0 +1,174 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpError = exports.ErrorType = void 0;
+exports.createAuthMissingError = createAuthMissingError;
+exports.createAuthInvalidError = createAuthInvalidError;
+exports.createApiError = createApiError;
+exports.createUnexpectedError = createUnexpectedError;
+exports.ensureMcpError = ensureMcpError;
+exports.getDeepOriginalError = getDeepOriginalError;
+exports.formatErrorForMcpTool = formatErrorForMcpTool;
+exports.formatErrorForMcpResource = formatErrorForMcpResource;
+exports.handleCliError = handleCliError;
+const logger_util_js_1 = require("./logger.util.js");
+/**
+ * Error types for classification
+ */
+var ErrorType;
+(function (ErrorType) {
+    ErrorType["AUTH_MISSING"] = "AUTH_MISSING";
+    ErrorType["AUTH_INVALID"] = "AUTH_INVALID";
+    ErrorType["API_ERROR"] = "API_ERROR";
+    ErrorType["UNEXPECTED_ERROR"] = "UNEXPECTED_ERROR";
+})(ErrorType || (exports.ErrorType = ErrorType = {}));
+/**
+ * Custom error class with type classification
+ */
+class McpError extends Error {
+    constructor(message, type, statusCode, originalError) {
+        super(message);
+        this.name = 'McpError';
+        this.type = type;
+        this.statusCode = statusCode;
+        this.originalError = originalError;
+    }
+}
+exports.McpError = McpError;
+/**
+ * Create an authentication missing error
+ */
+function createAuthMissingError(message = 'Authentication credentials are missing') {
+    return new McpError(message, ErrorType.AUTH_MISSING);
+}
+/**
+ * Create an authentication invalid error
+ */
+function createAuthInvalidError(message = 'Authentication credentials are invalid') {
+    return new McpError(message, ErrorType.AUTH_INVALID, 401);
+}
+/**
+ * Create an API error
+ */
+function createApiError(message, statusCode, originalError) {
+    return new McpError(message, ErrorType.API_ERROR, statusCode, originalError);
+}
+/**
+ * Create an unexpected error
+ */
+function createUnexpectedError(message = 'An unexpected error occurred', originalError) {
+    return new McpError(message, ErrorType.UNEXPECTED_ERROR, undefined, originalError);
+}
+/**
+ * Ensure an error is an McpError
+ */
+function ensureMcpError(error) {
+    if (error instanceof McpError) {
+        return error;
+    }
+    if (error instanceof Error) {
+        return createUnexpectedError(error.message, error);
+    }
+    return createUnexpectedError(String(error));
+}
+/**
+ * Get the deepest original error from an error chain
+ * @param error The error to extract the original cause from
+ * @returns The deepest original error or the error itself
+ */
+function getDeepOriginalError(error) {
+    if (!error) {
+        return error;
+    }
+    let current = error;
+    let depth = 0;
+    const maxDepth = 10; // Prevent infinite recursion
+    while (depth < maxDepth &&
+        current instanceof Error &&
+        'originalError' in current &&
+        current.originalError) {
+        current = current.originalError;
+        depth++;
+    }
+    return current;
+}
+/**
+ * Format error for MCP tool response
+ */
+function formatErrorForMcpTool(error) {
+    const methodLogger = logger_util_js_1.Logger.forContext('utils/error.util.ts', 'formatErrorForMcpTool');
+    const mcpError = ensureMcpError(error);
+    methodLogger.error(`${mcpError.type} error`, mcpError);
+    // Get the deep original error for additional context
+    const originalError = getDeepOriginalError(mcpError.originalError);
+    // Safely extract details from the original error
+    const errorDetails = originalError instanceof Error
+        ? { message: originalError.message }
+        : originalError;
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Error: ${mcpError.message}`,
+            },
+        ],
+        metadata: {
+            errorType: mcpError.type,
+            statusCode: mcpError.statusCode,
+            errorDetails,
+        },
+    };
+}
+/**
+ * Format error for MCP resource response
+ */
+function formatErrorForMcpResource(error, uri) {
+    const methodLogger = logger_util_js_1.Logger.forContext('utils/error.util.ts', 'formatErrorForMcpResource');
+    const mcpError = ensureMcpError(error);
+    methodLogger.error(`${mcpError.type} error`, mcpError);
+    return {
+        contents: [
+            {
+                uri,
+                text: `Error: ${mcpError.message}`,
+                mimeType: 'text/plain',
+                description: `Error: ${mcpError.type}`,
+            },
+        ],
+    };
+}
+/**
+ * Handle error in CLI context with improved user feedback
+ */
+function handleCliError(error) {
+    const methodLogger = logger_util_js_1.Logger.forContext('utils/error.util.ts', 'handleCliError');
+    const mcpError = ensureMcpError(error);
+    methodLogger.error(`${mcpError.type} error`, mcpError);
+    // Get the deep original error for more context
+    const originalError = getDeepOriginalError(mcpError.originalError);
+    // Print the error message
+    console.error(`Error: ${mcpError.message}`);
+    // Provide helpful context based on error type
+    if (mcpError.type === ErrorType.AUTH_MISSING) {
+        console.error('\nTip: Make sure to set up your API token in the configuration file or environment variables.');
+    }
+    else if (mcpError.type === ErrorType.AUTH_INVALID) {
+        console.error('\nTip: Check that your API token is correct and has not expired.');
+    }
+    else if (mcpError.type === ErrorType.API_ERROR) {
+        if (mcpError.statusCode === 429) {
+            console.error('\nTip: You may have exceeded your API rate limits. Try again later or upgrade your API plan.');
+        }
+        // Add API error context if available
+        if (originalError && typeof originalError === 'object') {
+            const origErr = originalError;
+            if (origErr.message) {
+                console.error(`\nAPI error: ${String(origErr.message)}`);
+            }
+        }
+    }
+    // Display DEBUG tip
+    if (process.env.DEBUG !== 'mcp:*') {
+        console.error('\nFor more detailed error information, run with DEBUG=mcp:* environment variable.');
+    }
+    process.exit(1);
+}

package/dist/utils/error.util.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/formatter.util.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Standardized formatting utilities for consistent output across all CLI and Tool interfaces.
+ * These functions should be used by all formatters to ensure consistent formatting.
+ */
+/**
+ * Format a date in a standardized way: YYYY-MM-DD HH:MM:SS UTC
+ * @param dateString - ISO date string or Date object
+ * @returns Formatted date string
+ */
+export declare function formatDate(dateString?: string | Date): string;
+/**
+ * Format a URL as a markdown link
+ * @param url - URL to format
+ * @param title - Link title
+ * @returns Formatted markdown link
+ */
+export declare function formatUrl(url?: string, title?: string): string;
+/**
+ * Format a heading with consistent style
+ * @param text - Heading text
+ * @param level - Heading level (1-6)
+ * @returns Formatted heading
+ */
+export declare function formatHeading(text: string, level?: number): string;
+/**
+ * Format a list of key-value pairs as a bullet list
+ * @param items - Object with key-value pairs
+ * @param keyFormatter - Optional function to format keys
+ * @returns Formatted bullet list
+ */
+export declare function formatBulletList(items: Record<string, unknown>, keyFormatter?: (key: string) => string): string;
+/**
+ * Format a separator line
+ * @returns Separator line
+ */
+export declare function formatSeparator(): string;