@hailer/mcp 0.0.1

package/dist/mcp/utils/api-errors.d.ts

@@ -0,0 +1,45 @@
+/**
+ * API error handling utilities for Hailer MCP Server
+ * Provides consistent error handling and response processing
+ */
+import { LogContext } from '../../lib/logger';
+export declare class HailerApiError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly operation: string;
+    readonly endpoint: string;
+    readonly responseBody?: string | undefined;
+    constructor(status: number, statusText: string, operation: string, endpoint: string, responseBody?: string | undefined);
+    get isAuthError(): boolean;
+    get isNotFound(): boolean;
+    get isServerError(): boolean;
+    get isClientError(): boolean;
+}
+export interface ApiCallOptions {
+    operation: string;
+    endpoint: string;
+    method?: string;
+    body?: any;
+    timeout?: number;
+    context?: LogContext;
+}
+/**
+ * Handles API response with consistent error handling and logging
+ */
+export declare function handleApiResponse<T>(response: Response, options: ApiCallOptions, startTime?: number): Promise<T>;
+/**
+ * Makes an API call with consistent error handling and logging
+ */
+export declare function makeApiCall<T>(url: string, options: ApiCallOptions & {
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}): Promise<T>;
+/**
+ * Helper function to create MCP error responses
+ */
+export declare function createErrorResponse(error: unknown, operation: string): any;
+/**
+ * Helper function to create success responses
+ */
+export declare function createSuccessResponse(data: any, operation: string, summary?: string): any;
+//# sourceMappingURL=api-errors.d.ts.map

package/dist/mcp/utils/api-errors.js

@@ -0,0 +1,160 @@
+"use strict";
+/**
+ * API error handling utilities for Hailer MCP Server
+ * Provides consistent error handling and response processing
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HailerApiError = void 0;
+exports.handleApiResponse = handleApiResponse;
+exports.makeApiCall = makeApiCall;
+exports.createErrorResponse = createErrorResponse;
+exports.createSuccessResponse = createSuccessResponse;
+const logger_1 = require("../../lib/logger");
+const logger = (0, logger_1.getDefaultLogger)();
+class HailerApiError extends Error {
+    status;
+    statusText;
+    operation;
+    endpoint;
+    responseBody;
+    constructor(status, statusText, operation, endpoint, responseBody) {
+        super(`${operation} failed: ${status} ${statusText}${responseBody ? ` - ${responseBody}` : ''}`);
+        this.status = status;
+        this.statusText = statusText;
+        this.operation = operation;
+        this.endpoint = endpoint;
+        this.responseBody = responseBody;
+        this.name = 'HailerApiError';
+    }
+    get isAuthError() {
+        return this.status === 401 || this.status === 403;
+    }
+    get isNotFound() {
+        return this.status === 404;
+    }
+    get isServerError() {
+        return this.status >= 500;
+    }
+    get isClientError() {
+        return this.status >= 400 && this.status < 500;
+    }
+}
+exports.HailerApiError = HailerApiError;
+/**
+ * Handles API response with consistent error handling and logging
+ */
+async function handleApiResponse(response, options, startTime) {
+    const duration = startTime ? Date.now() - startTime : undefined;
+    const logContext = { ...options.context, duration };
+    if (!response.ok) {
+        let errorBody;
+        try {
+            errorBody = await response.text();
+        }
+        catch {
+            errorBody = 'Unable to read error response';
+        }
+        logger.apiError(options.operation, options.endpoint, new HailerApiError(response.status, response.statusText, options.operation, options.endpoint, errorBody), duration);
+        throw new HailerApiError(response.status, response.statusText, options.operation, options.endpoint, errorBody);
+    }
+    try {
+        const data = await response.json();
+        logger.apiSuccess(options.operation, options.endpoint, duration);
+        logger.debug(`API response data`, {
+            ...logContext,
+            responseSize: JSON.stringify(data).length
+        });
+        return data;
+    }
+    catch (error) {
+        logger.apiError(options.operation, options.endpoint, error, duration);
+        throw new Error(`Failed to parse JSON response for ${options.operation}: ${error}`);
+    }
+}
+/**
+ * Makes an API call with consistent error handling and logging
+ */
+async function makeApiCall(url, options) {
+    const startTime = Date.now();
+    logger.apiCall(options.operation, options.endpoint, {
+        method: options.method || 'GET',
+        bodySize: options.body ? JSON.stringify(options.body).length : undefined,
+        ...options.context
+    });
+    try {
+        const fetchOptions = {
+            method: options.method || 'GET',
+            headers: {
+                'Content-Type': 'application/json',
+                ...options.headers,
+            },
+            signal: options.signal,
+        };
+        if (options.body) {
+            fetchOptions.body = JSON.stringify(options.body);
+        }
+        // Add timeout if specified
+        const controller = new AbortController();
+        let timeoutId;
+        if (options.timeout) {
+            timeoutId = setTimeout(() => controller.abort(), options.timeout);
+            fetchOptions.signal = controller.signal;
+        }
+        try {
+            const response = await fetch(url, fetchOptions);
+            return await handleApiResponse(response, options, startTime);
+        }
+        finally {
+            if (timeoutId) {
+                clearTimeout(timeoutId);
+            }
+        }
+    }
+    catch (error) {
+        const duration = Date.now() - startTime;
+        if (error instanceof HailerApiError) {
+            throw error; // Re-throw our custom errors
+        }
+        logger.apiError(options.operation, options.endpoint, error, duration);
+        if (error instanceof Error && error.name === 'AbortError') {
+            throw new Error(`${options.operation} timed out after ${options.timeout}ms`);
+        }
+        throw new Error(`${options.operation} failed: ${error}`);
+    }
+}
+/**
+ * Helper function to create MCP error responses
+ */
+function createErrorResponse(error, operation) {
+    let message;
+    let details = '';
+    if (error instanceof HailerApiError) {
+        message = `${operation} failed: ${error.status} ${error.statusText}`;
+        details = error.responseBody || '';
+    }
+    else if (error instanceof Error) {
+        message = `${operation} failed: ${error.message}`;
+    }
+    else {
+        message = `${operation} failed: ${String(error)}`;
+    }
+    return {
+        content: [{
+                type: "text",
+                text: `❌ Error: ${message}${details ? `\n\nDetails: ${details}` : ''}\n\n💡 Tips:\n- Check your permissions and credentials\n- Verify the provided IDs are correct\n- Ensure the resource exists and is accessible`,
+            }],
+    };
+}
+/**
+ * Helper function to create success responses
+ */
+function createSuccessResponse(data, operation, summary) {
+    const baseMessage = summary || `Successfully completed ${operation}`;
+    return {
+        content: [{
+                type: "text",
+                text: `✅ ${baseMessage}\n\n${typeof data === 'string' ? data : JSON.stringify(data, null, 2)}`,
+            }],
+    };
+}
+//# sourceMappingURL=api-errors.js.map

package/dist/mcp/utils/data-transformers.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Data transformation utilities for Hailer MCP Server
+ * Provides consistent data cleaning and formatting across tools
+ */
+export interface CleanActivity {
+    _id: string;
+    process: string;
+    currentPhase: string;
+    createdHumanReadable: string;
+    updatedHumanReadable: string;
+    uid: string;
+    userName: string;
+    name: string;
+    priority: number;
+    discussion?: string;
+    followers: string[];
+    fields?: any;
+    fieldsAndValues: FieldValue[];
+}
+export interface FieldValue {
+    fieldName: string;
+    value: any;
+}
+export interface WorkflowInfo {
+    _id: string;
+    name: string;
+    phases: Record<string, PhaseInfo>;
+    fields: Record<string, FieldInfo>;
+}
+export interface PhaseInfo {
+    _id: string;
+    name: string;
+    isEndpoint?: boolean;
+    possibleNextPhase?: string[];
+}
+export interface FieldInfo {
+    _id?: string;
+    label: string;
+    type: string;
+    key?: string;
+    required?: boolean;
+    data?: any[];
+}
+export interface UserInfo {
+    _id: string;
+    firstname: string;
+    lastname: string;
+    email?: string;
+}
+/**
+ * Transforms raw activity data into clean, structured format
+ */
+export declare function transformActivity(activity: any, workflow: WorkflowInfo, users: Record<string, UserInfo>): CleanActivity;
+/**
+ * Transforms multiple activities
+ */
+export declare function transformActivities(activities: any[], workflow: WorkflowInfo, users: Record<string, UserInfo>): CleanActivity[];
+/**
+ * Transforms field data with proper type handling
+ */
+export declare function transformFields(activityFields: Record<string, any> | undefined, workflowFields: Record<string, FieldInfo>): FieldValue[];
+/**
+ * Transforms a single field value based on field type
+ */
+export declare function transformFieldValue(activityFieldValue: any, field?: FieldInfo): any;
+/**
+ * Finds a field by key or ID in workflow fields
+ */
+export declare function findFieldByKey(key: string, workflowFields: Record<string, FieldInfo>): FieldInfo | undefined;
+/**
+ * Transforms raw workflow data into structured format
+ */
+export declare function transformWorkflow(process: any): WorkflowInfo;
+/**
+ * Transforms workflow phases
+ */
+export declare function transformPhases(phases: Record<string, any>): Record<string, PhaseInfo>;
+/**
+ * Transforms workflow fields
+ */
+export declare function transformWorkflowFields(fields: Record<string, any>): Record<string, FieldInfo>;
+/**
+ * Formats timestamp to human readable string
+ */
+export declare function formatTimestamp(timestamp: number | string | Date): string;
+/**
+ * Formats user name from user info
+ */
+export declare function formatUserName(user: UserInfo | undefined, fallbackId: string): string;
+/**
+ * Gets the first phase ID from workflow (for defaults)
+ */
+export declare function getFirstPhaseId(workflow: WorkflowInfo): string | null;
+/**
+ * Formats activity data for MCP response
+ */
+export declare function formatActivityListResponse(activities: CleanActivity[], workflow: WorkflowInfo, phaseName?: string): string;
+/**
+ * Creates a simplified activity format for search results
+ */
+export declare function transformActivityForSearch(activity: any): any;
+//# sourceMappingURL=data-transformers.d.ts.map

package/dist/mcp/utils/data-transformers.js

@@ -0,0 +1,194 @@
+"use strict";
+/**
+ * Data transformation utilities for Hailer MCP Server
+ * Provides consistent data cleaning and formatting across tools
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transformActivity = transformActivity;
+exports.transformActivities = transformActivities;
+exports.transformFields = transformFields;
+exports.transformFieldValue = transformFieldValue;
+exports.findFieldByKey = findFieldByKey;
+exports.transformWorkflow = transformWorkflow;
+exports.transformPhases = transformPhases;
+exports.transformWorkflowFields = transformWorkflowFields;
+exports.formatTimestamp = formatTimestamp;
+exports.formatUserName = formatUserName;
+exports.getFirstPhaseId = getFirstPhaseId;
+exports.formatActivityListResponse = formatActivityListResponse;
+exports.transformActivityForSearch = transformActivityForSearch;
+/**
+ * Transforms raw activity data into clean, structured format
+ */
+function transformActivity(activity, workflow, users) {
+    const user = users[activity.uid];
+    return {
+        _id: activity._id || activity.id,
+        process: activity.process,
+        currentPhase: activity.currentPhase,
+        createdHumanReadable: formatTimestamp(activity.created),
+        updatedHumanReadable: formatTimestamp(activity.updated),
+        uid: activity.uid,
+        userName: formatUserName(user, activity.uid),
+        name: activity.name,
+        priority: activity.priority || 0,
+        discussion: activity.discussion,
+        followers: Array.isArray(activity.followers) ? activity.followers : [],
+        fields: activity.field,
+        fieldsAndValues: transformFields(activity.fields, workflow.fields),
+    };
+}
+/**
+ * Transforms multiple activities
+ */
+function transformActivities(activities, workflow, users) {
+    return activities.map(activity => transformActivity(activity, workflow, users));
+}
+/**
+ * Transforms field data with proper type handling
+ */
+function transformFields(activityFields, workflowFields) {
+    if (!activityFields)
+        return [];
+    return Object.entries(activityFields).map(([fieldKey, activityFieldValue]) => {
+        const field = findFieldByKey(fieldKey, workflowFields);
+        return {
+            fieldName: field?.label || fieldKey,
+            value: transformFieldValue(activityFieldValue, field),
+        };
+    });
+}
+/**
+ * Transforms a single field value based on field type
+ */
+function transformFieldValue(activityFieldValue, field) {
+    // Handle nested value objects
+    if (typeof activityFieldValue === 'object' && activityFieldValue?.value !== undefined) {
+        if (field?.type === 'activitylink' && activityFieldValue.value._id) {
+            return {
+                _id: activityFieldValue.value._id,
+                name: activityFieldValue.value.name || 'n/a'
+            };
+        }
+        return activityFieldValue.value;
+    }
+    // Handle direct values
+    if (field?.type === 'activitylink' && typeof activityFieldValue === 'object' && activityFieldValue._id) {
+        return {
+            _id: activityFieldValue._id,
+            name: activityFieldValue.name || 'n/a'
+        };
+    }
+    return activityFieldValue;
+}
+/**
+ * Finds a field by key or ID in workflow fields
+ */
+function findFieldByKey(key, workflowFields) {
+    // First try to find by key
+    const fieldByKey = Object.values(workflowFields).find(f => f.key === key);
+    if (fieldByKey)
+        return fieldByKey;
+    // Fallback to direct field ID lookup
+    return workflowFields[key];
+}
+/**
+ * Transforms raw workflow data into structured format
+ */
+function transformWorkflow(process) {
+    return {
+        _id: process._id,
+        name: process.name,
+        phases: transformPhases(process.phases || {}),
+        fields: transformWorkflowFields(process.fields || {}),
+    };
+}
+/**
+ * Transforms workflow phases
+ */
+function transformPhases(phases) {
+    const transformed = {};
+    Object.entries(phases).forEach(([phaseId, phase]) => {
+        transformed[phaseId] = {
+            _id: phaseId,
+            name: phase.name,
+            isEndpoint: phase.isEndpoint,
+            possibleNextPhase: phase.possibleNextPhase,
+        };
+    });
+    return transformed;
+}
+/**
+ * Transforms workflow fields
+ */
+function transformWorkflowFields(fields) {
+    const transformed = {};
+    Object.entries(fields).forEach(([fieldId, field]) => {
+        transformed[fieldId] = {
+            _id: fieldId,
+            label: field.label || fieldId,
+            type: field.type || 'text',
+            key: field.key,
+            required: field.required,
+            data: field.data,
+        };
+    });
+    return transformed;
+}
+/**
+ * Formats timestamp to human readable string
+ */
+function formatTimestamp(timestamp) {
+    if (!timestamp)
+        return 'Unknown';
+    try {
+        return new Date(timestamp).toString();
+    }
+    catch {
+        return String(timestamp);
+    }
+}
+/**
+ * Formats user name from user info
+ */
+function formatUserName(user, fallbackId) {
+    if (!user)
+        return `User ${fallbackId}`;
+    const fullName = `${user.firstname || ''} ${user.lastname || ''}`.trim();
+    return fullName || user.email || `User ${fallbackId}`;
+}
+/**
+ * Gets the first phase ID from workflow (for defaults)
+ */
+function getFirstPhaseId(workflow) {
+    const phases = Object.values(workflow.phases);
+    return phases.length > 0 ? phases[0]._id : null;
+}
+/**
+ * Formats activity data for MCP response
+ */
+function formatActivityListResponse(activities, workflow, phaseName) {
+    const count = activities.length;
+    const phaseInfo = phaseName ? ` (phase: ${phaseName})` : '';
+    return `✅ Found ${count} activities in workflow "${workflow.name}"${phaseInfo}\n\n${JSON.stringify(activities, null, 2)}`;
+}
+/**
+ * Creates a simplified activity format for search results
+ */
+function transformActivityForSearch(activity) {
+    return {
+        _id: activity._id,
+        name: activity.name,
+        workflow: {
+            _id: activity.process?._id,
+            name: activity.process?.name,
+        },
+        currentPhase: {
+            _id: activity.currentPhase?._id,
+            name: activity.currentPhase?.name,
+        },
+        created: activity.created?.humanReadable,
+        updated: activity.updated?.humanReadable,
+    };
+}
+//# sourceMappingURL=data-transformers.js.map

package/dist/mcp/utils/file-upload.d.ts

@@ -0,0 +1,33 @@
+/**
+ * File Upload Utility
+ *
+ * Handles file uploads from URLs or filesystem paths with streaming support
+ */
+import { HailerClient } from '../hailer-clients';
+/**
+ * File specification interface
+ */
+export interface FileSpec {
+    url?: string;
+    path?: string;
+    filename?: string;
+    isPublic?: boolean;
+}
+/**
+ * Upload result interface
+ */
+export interface UploadResult {
+    success: boolean;
+    fileId?: string;
+    filename?: string;
+    source?: string;
+    type?: 'url' | 'path';
+    sizeKB?: string;
+    error?: string;
+}
+/**
+ * Upload a single file with streaming support
+ * Handles both URL and filesystem uploads with 100MB size limit
+ */
+export declare function uploadSingleFile(fileSpec: FileSpec, client: HailerClient): Promise<UploadResult>;
+//# sourceMappingURL=file-upload.d.ts.map

package/dist/mcp/utils/file-upload.js

@@ -0,0 +1,148 @@
+"use strict";
+/**
+ * File Upload Utility
+ *
+ * Handles file uploads from URLs or filesystem paths with streaming support
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uploadSingleFile = uploadSingleFile;
+/**
+ * Upload a single file with streaming support
+ * Handles both URL and filesystem uploads with 100MB size limit
+ */
+async function uploadSingleFile(fileSpec, client) {
+    const FormData = (await Promise.resolve().then(() => __importStar(require('form-data')))).default;
+    const formData = new FormData();
+    let filename;
+    let source;
+    let type;
+    let fileSize;
+    if (fileSpec.url) {
+        // URL upload with streaming
+        type = 'url';
+        source = fileSpec.url;
+        const response = await fetch(fileSpec.url);
+        if (!response.ok) {
+            throw new Error(`Fetch failed: ${response.status} ${response.statusText}`);
+        }
+        const contentLength = response.headers.get('content-length');
+        fileSize = contentLength ? parseInt(contentLength, 10) : undefined;
+        const maxSize = 100 * 1024 * 1024;
+        if (fileSize && fileSize > maxSize) {
+            throw new Error(`File too large: ${(fileSize / 1024 / 1024).toFixed(2)}MB (max 100MB)`);
+        }
+        filename = fileSpec.filename || fileSpec.url.split('/').pop()?.split('?')[0] || 'file';
+        // Convert Web Stream to Node.js stream for form-data compatibility
+        if (!response.body) {
+            throw new Error('Response body is null');
+        }
+        const { Readable } = await Promise.resolve().then(() => __importStar(require('stream')));
+        const nodeStream = Readable.fromWeb(response.body);
+        formData.append('file', nodeStream, { filename, ...(fileSize && { knownLength: fileSize }) });
+    }
+    else if (fileSpec.path) {
+        // Filesystem upload with streaming
+        type = 'path';
+        source = fileSpec.path;
+        const fs = await Promise.resolve().then(() => __importStar(require('fs')));
+        const fsPromises = await Promise.resolve().then(() => __importStar(require('fs/promises')));
+        const path = await Promise.resolve().then(() => __importStar(require('path')));
+        const stats = await fsPromises.stat(fileSpec.path);
+        if (!stats.isFile()) {
+            throw new Error('Path is not a file');
+        }
+        fileSize = stats.size;
+        const maxSize = 100 * 1024 * 1024;
+        if (fileSize > maxSize) {
+            throw new Error(`File too large: ${(fileSize / 1024 / 1024).toFixed(2)}MB (max 100MB)`);
+        }
+        filename = fileSpec.filename || path.basename(fileSpec.path);
+        const readStream = fs.createReadStream(fileSpec.path);
+        formData.append('file', readStream, { filename, knownLength: fileSize });
+    }
+    else {
+        throw new Error('Neither url nor path provided');
+    }
+    if (fileSpec.isPublic) {
+        formData.append('isPublic', 'true');
+    }
+    // Upload to Hailer using node's https module (fetch doesn't handle form-data well)
+    const apiBaseUrl = client.socket.host;
+    const sessionKey = client.sessionKey;
+    const url = new URL(`${apiBaseUrl}/upload`);
+    const https = await Promise.resolve().then(() => __importStar(require('https')));
+    const http = await Promise.resolve().then(() => __importStar(require('http')));
+    const uploadResponse = await new Promise((resolve, reject) => {
+        const options = {
+            hostname: url.hostname,
+            port: url.port || (url.protocol === 'https:' ? 443 : 80),
+            path: url.pathname,
+            method: 'POST',
+            headers: {
+                'hlrkey': sessionKey,
+                ...formData.getHeaders()
+            }
+        };
+        const req = (url.protocol === 'https:' ? https : http).request(options, (res) => {
+            const chunks = [];
+            res.on('data', (chunk) => chunks.push(chunk));
+            res.on('end', () => {
+                resolve({
+                    statusCode: res.statusCode || 500,
+                    body: Buffer.concat(chunks).toString('utf-8')
+                });
+            });
+        });
+        req.on('error', reject);
+        formData.pipe(req);
+    });
+    if (uploadResponse.statusCode < 200 || uploadResponse.statusCode >= 300) {
+        throw new Error(`Upload failed: ${uploadResponse.statusCode} - ${uploadResponse.body}`);
+    }
+    const result = JSON.parse(uploadResponse.body);
+    if (!result._id) {
+        throw new Error('No file ID returned');
+    }
+    return {
+        success: true,
+        fileId: result._id,
+        filename,
+        source,
+        type,
+        sizeKB: fileSize ? (fileSize / 1024).toFixed(2) : 'unknown'
+    };
+}
+//# sourceMappingURL=file-upload.js.map