@iflow-mcp/attio-mcp 1.3.6

package/dist/utils/resource-mapping.js

@@ -0,0 +1,277 @@
+/**
+ * Resource Mapping Utilities
+ *
+ * Handles mapping between universal resource types and Attio API paths.
+ * Fixes the double-prefix issue for lists and provides consistent path generation.
+ */
+import { UniversalResourceType } from '../handlers/tool-configs/universal/types.js';
+import { createScopedLogger, OperationType } from './logger.js';
+const log = createScopedLogger('utils.resource-mapping', undefined, OperationType.SYSTEM);
+/**
+ * Mapping of resource types to their API path configurations
+ */
+const RESOURCE_PATH_MAP = {
+    companies: {
+        basePath: '/objects/companies',
+        singular: 'company',
+        plural: 'companies',
+        idPrefix: 'comp_',
+    },
+    people: {
+        basePath: '/objects/people',
+        singular: 'person',
+        plural: 'people',
+        idPrefix: 'pers_',
+    },
+    deals: {
+        basePath: '/objects/deals',
+        singular: 'deal',
+        plural: 'deals',
+        idPrefix: 'deal_',
+    },
+    tasks: {
+        basePath: '/tasks',
+        singular: 'task',
+        plural: 'tasks',
+        customPath: true,
+        idPrefix: 'task_',
+    },
+    lists: {
+        basePath: '/lists',
+        singular: 'list',
+        plural: 'lists',
+        customPath: true,
+        idPrefix: 'list_',
+    },
+    notes: {
+        basePath: '/notes',
+        singular: 'note',
+        plural: 'notes',
+        idPrefix: 'note_',
+    },
+    records: {
+        basePath: '/records',
+        singular: 'record',
+        plural: 'records',
+        idPrefix: 'rec_',
+    },
+    // Generic records fallback - should be avoided when possible
+    objects: {
+        basePath: '/objects',
+        singular: 'object',
+        plural: 'objects',
+    },
+};
+/**
+ * Resource mapping service
+ */
+export class ResourceMapper {
+    /**
+     * Get the API base path for a resource type
+     */
+    static getBasePath(resourceType) {
+        const config = RESOURCE_PATH_MAP[resourceType.toLowerCase()];
+        if (!config) {
+            // For unknown types, check if it's a custom object type
+            // Custom objects typically use /objects/{type} format
+            if (this.isCustomObjectType(resourceType)) {
+                return `/objects/${resourceType.toLowerCase()}`;
+            }
+            // Default fallback for completely unknown types
+            log.warn('Unknown resource type, using generic records path', {
+                resourceType,
+            });
+            return '/records';
+        }
+        return config.basePath;
+    }
+    /**
+     * Get the full API path for a specific resource record
+     */
+    static getResourcePath(resourceType, recordId) {
+        const basePath = this.getBasePath(resourceType);
+        if (recordId) {
+            return `${basePath}/${recordId}`;
+        }
+        return basePath;
+    }
+    /**
+     * Get the search path for a resource type
+     */
+    static getSearchPath(resourceType) {
+        const basePath = this.getBasePath(resourceType);
+        // Lists use a different search endpoint
+        if (resourceType.toLowerCase() === 'lists') {
+            return '/lists';
+        }
+        // Most resources append /query for search
+        return `${basePath}/query`;
+    }
+    /**
+     * Get the singular form of a resource type
+     */
+    static getSingular(resourceType) {
+        const config = RESOURCE_PATH_MAP[resourceType.toLowerCase()];
+        return config?.singular || resourceType.toLowerCase();
+    }
+    /**
+     * Get the plural form of a resource type
+     */
+    static getPlural(resourceType) {
+        const config = RESOURCE_PATH_MAP[resourceType.toLowerCase()];
+        return config?.plural || resourceType.toLowerCase();
+    }
+    /**
+     * Check if a resource type is a standard Attio type
+     */
+    static isStandardType(resourceType) {
+        return resourceType.toLowerCase() in RESOURCE_PATH_MAP;
+    }
+    /**
+     * Check if a resource type is likely a custom object type
+     */
+    static isCustomObjectType(resourceType) {
+        // Standard types are not custom
+        if (this.isStandardType(resourceType)) {
+            return false;
+        }
+        // Custom object types typically:
+        // - Don't contain special characters (except underscore)
+        // - Are lowercase or have consistent casing
+        // - Don't match reserved keywords
+        const customObjectPattern = /^[a-z][a-z0-9_]*$/i;
+        const reservedKeywords = ['api', 'v2', 'auth', 'webhooks', 'settings'];
+        return (customObjectPattern.test(resourceType) &&
+            !reservedKeywords.includes(resourceType.toLowerCase()));
+    }
+    /**
+     * Normalize a resource type to its canonical form
+     */
+    static normalizeResourceType(resourceType) {
+        const lowercased = resourceType.toLowerCase();
+        // Handle common variations
+        const variations = {
+            company: 'companies',
+            person: 'people',
+            deal: 'deals',
+            task: 'tasks',
+            list: 'lists',
+            note: 'notes',
+            record: 'records',
+            object: 'objects',
+        };
+        return variations[lowercased] || lowercased;
+    }
+    /**
+     * Validate a resource type
+     */
+    static isValidResourceType(resourceType) {
+        // Check if it's a universal resource type enum value
+        if (Object.values(UniversalResourceType).includes(resourceType)) {
+            return true;
+        }
+        // Check if it's a known standard type
+        if (this.isStandardType(resourceType)) {
+            return true;
+        }
+        // Check if it could be a custom object type
+        if (this.isCustomObjectType(resourceType)) {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Get the ID prefix for a resource type
+     */
+    static getIdPrefix(resourceType) {
+        const config = RESOURCE_PATH_MAP[resourceType.toLowerCase()];
+        return config?.idPrefix;
+    }
+    /**
+     * Validate if an ID matches the expected format for a resource type
+     */
+    static isValidIdFormat(resourceType, id) {
+        const prefix = this.getIdPrefix(resourceType);
+        // If we have a known prefix, check if the ID starts with it
+        if (prefix) {
+            return id.startsWith(prefix);
+        }
+        // For unknown types, just check basic format
+        // IDs should be alphanumeric with underscores and hyphens
+        const genericIdPattern = /^[a-zA-Z0-9_-]+$/;
+        return genericIdPattern.test(id);
+    }
+    /**
+     * Get attributes path for a resource type
+     */
+    static getAttributesPath(resourceType) {
+        // Attributes are typically at the object level, not record level
+        const normalized = this.normalizeResourceType(resourceType);
+        // Special handling for lists
+        if (normalized === 'lists') {
+            return '/lists/attributes';
+        }
+        // Standard objects use /objects/{type}/attributes
+        if (['companies', 'people', 'deals', 'tasks'].includes(normalized)) {
+            return `/objects/${normalized}/attributes`;
+        }
+        // Custom objects
+        if (this.isCustomObjectType(resourceType)) {
+            return `/objects/${resourceType.toLowerCase()}/attributes`;
+        }
+        // Fallback
+        return `/objects/attributes`;
+    }
+    /**
+     * Build query parameters for list operations
+     */
+    static buildListQueryParams(params) {
+        const queryParams = new URLSearchParams();
+        // Add pagination params
+        if (params.limit !== undefined) {
+            queryParams.append('limit', String(params.limit));
+        }
+        if (params.offset !== undefined) {
+            queryParams.append('offset', String(params.offset));
+        }
+        // Add sorting params
+        if (params.sort_by) {
+            queryParams.append('sort_by', params.sort_by);
+        }
+        if (params.sort_order) {
+            queryParams.append('sort_order', params.sort_order);
+        }
+        // Add any other params
+        for (const [key, value] of Object.entries(params)) {
+            if (!['limit', 'offset', 'sort_by', 'sort_order'].includes(key) &&
+                value !== undefined) {
+                if (typeof value === 'object') {
+                    queryParams.append(key, JSON.stringify(value));
+                }
+                else {
+                    queryParams.append(key, String(value));
+                }
+            }
+        }
+        return queryParams;
+    }
+}
+/**
+ * Helper function to get resource path (for backward compatibility)
+ */
+export function getResourcePath(resourceType, recordId) {
+    return ResourceMapper.getResourcePath(resourceType, recordId);
+}
+/**
+ * Helper function to get search path (for backward compatibility)
+ */
+export function getSearchPath(resourceType) {
+    return ResourceMapper.getSearchPath(resourceType);
+}
+/**
+ * Helper function to normalize resource type (for backward compatibility)
+ */
+export function normalizeResourceType(resourceType) {
+    return ResourceMapper.normalizeResourceType(resourceType);
+}
+//# sourceMappingURL=resource-mapping.js.map

package/dist/utils/resource-mapping.js.map

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

package/dist/utils/response-formatter.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Interface for a simple text content item
+ */
+export interface TextContent {
+    type: 'text';
+    text: string;
+}
+/**
+ * Interface for a markdown content item
+ */
+export interface MarkdownContent {
+    type: 'markdown';
+    text: string;
+}
+/**
+ * Content types that can be included in responses
+ */
+export type ResponseContent = TextContent | MarkdownContent;
+/**
+ * Base interface for all tool responses
+ */
+export interface ToolResponse {
+    content: ResponseContent[];
+    isError: boolean;
+    error?: {
+        code: number;
+        message: string;
+        type?: string;
+        details?: unknown;
+    };
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Base interface for list responses
+ */
+export interface ListResponse<T> {
+    items: T[];
+    pagination?: {
+        total?: number;
+        hasMore?: boolean;
+        nextCursor?: string;
+    };
+}
+/**
+ * Format a simple success response with a text message
+ *
+ * @param message - Success message text
+ * @param metadata - Optional metadata to include
+ * @returns Formatted tool response
+ */
+export declare function formatSuccessResponse(message: string, metadata?: Record<string, unknown>): ToolResponse;
+/**
+ * Format a list response with items
+ *
+ * @param title - Title for the list
+ * @param items - Array of items to format
+ * @param formatter - Function to format each item to a string
+ * @param pagination - Optional pagination information
+ * @param metadata - Optional metadata to include
+ * @returns Formatted tool response
+ */
+export declare function formatListResponse<T>(title: string, items: T[], formatter: (item: T) => string, pagination?: {
+    total?: number;
+    hasMore?: boolean;
+    nextCursor?: string;
+}, metadata?: Record<string, unknown>): ToolResponse;
+/**
+ * Format a single record response
+ *
+ * @param title - Title for the record
+ * @param record - The record to format
+ * @param formatter - Function to format the record to a string
+ * @param metadata - Optional metadata to include
+ * @returns Formatted tool response
+ */
+export declare function formatRecordResponse<T>(title: string, record: T, formatter: (record: T) => string, metadata?: Record<string, unknown>): ToolResponse;
+/**
+ * Format a response with a detailed JSON view
+ *
+ * @param title - Title for the JSON data
+ * @param data - The data to format as JSON
+ * @param metadata - Optional metadata to include
+ * @returns Formatted tool response
+ */
+export declare function formatJsonResponse(title: string, data: unknown, metadata?: Record<string, unknown>): ToolResponse;
+/**
+ * Format a response with markdown content
+ *
+ * @param title - Title for the markdown content
+ * @param markdown - The markdown content
+ * @param metadata - Optional metadata to include
+ * @returns Formatted tool response
+ */
+export declare function formatMarkdownResponse(title: string, markdown: string, metadata?: Record<string, unknown>): ToolResponse;
+/**
+ * Format a multi-part response with different content types
+ *
+ * @param title - Title for the response
+ * @param parts - Array of content parts to include
+ * @param metadata - Optional metadata to include
+ * @returns Formatted tool response
+ */
+export declare function formatMultiPartResponse(title: string, parts: ResponseContent[], metadata?: Record<string, unknown>): ToolResponse;
+/**
+ * Format an empty response (no content)
+ *
+ * @param metadata - Optional metadata to include
+ * @returns Formatted tool response
+ */
+export declare function formatEmptyResponse(metadata?: Record<string, unknown>): ToolResponse;
+/**
+ * Format a standardized error response
+ *
+ * @param message - Error message
+ * @param code - Error code (HTTP status code or custom code)
+ * @param type - Error type (e.g., validation_error, not_found, etc.)
+ * @param details - Optional error details
+ * @returns Formatted error response
+ */
+export declare function formatErrorResponse(message: string, code?: number, type?: string, details?: unknown): ToolResponse;
+//# sourceMappingURL=response-formatter.d.ts.map

package/dist/utils/response-formatter.d.ts.map

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

package/dist/utils/response-formatter.js

@@ -0,0 +1,185 @@
+/**
+ * Response formatting utilities for standardizing MCP tool responses
+ */
+import { safeJsonStringify, sanitizeMcpResponse } from './json-serializer.js';
+/**
+ * Format a simple success response with a text message
+ *
+ * @param message - Success message text
+ * @param metadata - Optional metadata to include
+ * @returns Formatted tool response
+ */
+export function formatSuccessResponse(message, metadata) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: message,
+            },
+        ],
+        isError: false,
+        metadata,
+    };
+}
+/**
+ * Format a list response with items
+ *
+ * @param title - Title for the list
+ * @param items - Array of items to format
+ * @param formatter - Function to format each item to a string
+ * @param pagination - Optional pagination information
+ * @param metadata - Optional metadata to include
+ * @returns Formatted tool response
+ */
+export function formatListResponse(title, items, formatter, pagination, metadata) {
+    const itemsText = items.length > 0 ? items.map(formatter).join('\n') : 'No items found';
+    const countText = pagination?.total !== undefined
+        ? `${items.length} of ${pagination.total} total`
+        : `${items.length}`;
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `${title}:\n${itemsText}\n\nShowing ${countText} items${pagination?.hasMore ? '. More items available.' : '.'}`,
+            },
+        ],
+        isError: false,
+        metadata: {
+            items,
+            pagination,
+            ...metadata,
+        },
+    };
+}
+/**
+ * Format a single record response
+ *
+ * @param title - Title for the record
+ * @param record - The record to format
+ * @param formatter - Function to format the record to a string
+ * @param metadata - Optional metadata to include
+ * @returns Formatted tool response
+ */
+export function formatRecordResponse(title, record, formatter, metadata) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `${title}:\n${formatter(record)}`,
+            },
+        ],
+        isError: false,
+        metadata: {
+            record,
+            ...metadata,
+        },
+    };
+}
+/**
+ * Format a response with a detailed JSON view
+ *
+ * @param title - Title for the JSON data
+ * @param data - The data to format as JSON
+ * @param metadata - Optional metadata to include
+ * @returns Formatted tool response
+ */
+export function formatJsonResponse(title, data, metadata) {
+    const response = {
+        content: [
+            {
+                type: 'text',
+                text: `${title}:\n${safeJsonStringify(data, { maxDepth: 8 })}`,
+            },
+        ],
+        isError: false,
+        metadata: {
+            data,
+            ...metadata,
+        },
+    };
+    return sanitizeMcpResponse(response);
+}
+/**
+ * Format a response with markdown content
+ *
+ * @param title - Title for the markdown content
+ * @param markdown - The markdown content
+ * @param metadata - Optional metadata to include
+ * @returns Formatted tool response
+ */
+export function formatMarkdownResponse(title, markdown, metadata) {
+    return {
+        content: [
+            {
+                type: 'markdown',
+                text: `# ${title}\n\n${markdown}`,
+            },
+        ],
+        isError: false,
+        metadata,
+    };
+}
+/**
+ * Format a multi-part response with different content types
+ *
+ * @param title - Title for the response
+ * @param parts - Array of content parts to include
+ * @param metadata - Optional metadata to include
+ * @returns Formatted tool response
+ */
+export function formatMultiPartResponse(title, parts, metadata) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: title,
+            },
+            ...parts,
+        ],
+        isError: false,
+        metadata,
+    };
+}
+/**
+ * Format an empty response (no content)
+ *
+ * @param metadata - Optional metadata to include
+ * @returns Formatted tool response
+ */
+export function formatEmptyResponse(metadata) {
+    return {
+        content: [],
+        isError: false,
+        metadata,
+    };
+}
+/**
+ * Format a standardized error response
+ *
+ * @param message - Error message
+ * @param code - Error code (HTTP status code or custom code)
+ * @param type - Error type (e.g., validation_error, not_found, etc.)
+ * @param details - Optional error details
+ * @returns Formatted error response
+ */
+export function formatErrorResponse(message, code = 500, type = 'unknown_error', details) {
+    const response = {
+        content: [
+            {
+                type: 'text',
+                text: `ERROR [${type}]: ${message}${details
+                    ? '\n\nDetails: ' + safeJsonStringify(details, { maxDepth: 5 })
+                    : ''}`,
+            },
+        ],
+        isError: true,
+        error: {
+            code,
+            message,
+            type,
+            details,
+        },
+    };
+    return sanitizeMcpResponse(response);
+}
+//# sourceMappingURL=response-formatter.js.map

package/dist/utils/response-formatter.js.map

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