attio-mcp 0.1.0

package/dist/utils/relationship-utils.js

@@ -0,0 +1,242 @@
+import { ResourceType, FilterConditionType, RelationshipType, } from '../types/attio.js';
+// Re-export RelationshipType for convenience
+export { RelationshipType };
+import { FilterValidationError, RelationshipFilterError, ListRelationshipError, } from '../errors/api-errors.js';
+import { createEqualsFilter } from './filters/index.js';
+import { isValidListId } from './validation.js';
+/**
+ * Creates a filter for people based on their associated company attributes
+ *
+ * @param companyFilter - Filters to apply to the related companies
+ * @returns Filter for finding people based on company attributes
+ */
+export function createPeopleByCompanyFilter(companyFilter) {
+    try {
+        // Validate company filters
+        if (!companyFilter ||
+            !companyFilter.filters ||
+            companyFilter.filters.length === 0) {
+            throw new RelationshipFilterError('Company filter must contain at least one valid filter condition', ResourceType.PEOPLE.toString(), ResourceType.COMPANIES.toString(), RelationshipType.WORKS_AT);
+        }
+        // Create a relationship filter configuration
+        const relationshipConfig = {
+            sourceType: ResourceType.PEOPLE,
+            targetType: ResourceType.COMPANIES,
+            relationshipType: RelationshipType.WORKS_AT,
+            targetFilters: companyFilter,
+        };
+        // Convert to an Attio API compatible filter
+        return createRelationshipFilter(relationshipConfig);
+    }
+    catch (error) {
+        // Check if it's already a specialized error
+        if (error instanceof RelationshipFilterError) {
+            throw error;
+        }
+        // Otherwise, wrap in a FilterValidationError
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new FilterValidationError(`Failed to create people-by-company filter: ${errorMessage}`);
+    }
+}
+/**
+ * Creates a filter for companies based on their associated people attributes
+ *
+ * @param peopleFilter - Filters to apply to the related people
+ * @returns Filter for finding companies based on people attributes
+ */
+export function createCompaniesByPeopleFilter(peopleFilter) {
+    try {
+        // Validate people filters
+        if (!peopleFilter ||
+            !peopleFilter.filters ||
+            peopleFilter.filters.length === 0) {
+            throw new RelationshipFilterError('People filter must contain at least one valid filter condition', ResourceType.COMPANIES.toString(), ResourceType.PEOPLE.toString(), RelationshipType.EMPLOYS);
+        }
+        // Create a relationship filter configuration
+        const relationshipConfig = {
+            sourceType: ResourceType.COMPANIES,
+            targetType: ResourceType.PEOPLE,
+            relationshipType: RelationshipType.EMPLOYS,
+            targetFilters: peopleFilter,
+        };
+        // Convert to an Attio API compatible filter
+        return createRelationshipFilter(relationshipConfig);
+    }
+    catch (error) {
+        // Check if it's already a specialized error
+        if (error instanceof RelationshipFilterError) {
+            throw error;
+        }
+        // Otherwise, wrap in a FilterValidationError
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new FilterValidationError(`Failed to create companies-by-people filter: ${errorMessage}`);
+    }
+}
+/**
+ * Creates a filter for records that belong to a specific list
+ *
+ * @param resourceType - The type of records to filter (people or companies)
+ * @param listId - The ID of the list to filter by
+ * @returns Filter for finding records that belong to the list
+ */
+export function createRecordsByListFilter(resourceType, listId) {
+    try {
+        // Validate list ID format and security
+        if (!listId || !isValidListId(listId)) {
+            throw new ListRelationshipError('Invalid list ID format. Expected format: list_[alphanumeric]', resourceType.toString(), listId);
+        }
+        // Create a relationship filter configuration
+        const relationshipConfig = {
+            sourceType: resourceType,
+            targetType: ResourceType.LISTS,
+            relationshipType: RelationshipType.BELONGS_TO_LIST,
+            targetFilters: createEqualsFilter('list_id', listId),
+        };
+        // Convert to an Attio API compatible filter
+        return createRelationshipFilter(relationshipConfig);
+    }
+    catch (error) {
+        // Check if it's already a specialized error
+        if (error instanceof ListRelationshipError ||
+            error instanceof RelationshipFilterError) {
+            throw error;
+        }
+        // Otherwise, wrap in a FilterValidationError
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new FilterValidationError(`Failed to create records-by-list filter: ${errorMessage}`);
+    }
+}
+/**
+ * Creates a filter for finding people who work at companies in a specific list
+ *
+ * @param listId - The ID of the list that contains companies
+ * @returns Filter for finding people who work at companies in the specified list
+ */
+export function createPeopleByCompanyListFilter(listId) {
+    try {
+        // Validate list ID format and security
+        if (!listId || !isValidListId(listId)) {
+            throw new Error('Invalid list ID format. Expected format: list_[alphanumeric]');
+        }
+        // First, create a filter for companies in the list
+        const companiesInListFilter = createRecordsByListFilter(ResourceType.COMPANIES, listId);
+        // Then, create a filter for people who work at those companies
+        return createPeopleByCompanyFilter(companiesInListFilter);
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new FilterValidationError(`Failed to create people-by-company-list filter: ${errorMessage}`);
+    }
+}
+/**
+ * Creates a filter for finding companies that have people in a specific list
+ *
+ * @param listId - The ID of the list that contains people
+ * @returns Filter for finding companies that have people in the specified list
+ */
+export function createCompaniesByPeopleListFilter(listId) {
+    try {
+        // Validate list ID format and security
+        if (!listId || !isValidListId(listId)) {
+            throw new Error('Invalid list ID format. Expected format: list_[alphanumeric]');
+        }
+        // First, create a filter for people in the list
+        const peopleInListFilter = createRecordsByListFilter(ResourceType.PEOPLE, listId);
+        // Then, create a filter for companies that have those people
+        return createCompaniesByPeopleFilter(peopleInListFilter);
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new FilterValidationError(`Failed to create companies-by-people-list filter: ${errorMessage}`);
+    }
+}
+/**
+ * Creates a filter for records that have associated notes matching criteria
+ *
+ * @param resourceType - The type of records to filter (people or companies)
+ * @param textSearch - Text to search for in the notes
+ * @returns Filter for finding records with matching notes
+ */
+export function createRecordsByNotesFilter(resourceType, textSearch) {
+    try {
+        if (!textSearch || textSearch.trim() === '') {
+            throw new Error('Text search query must be provided');
+        }
+        // Create a relationship filter configuration
+        const relationshipConfig = {
+            sourceType: resourceType,
+            targetType: ResourceType.LISTS, // Notes don't have a ResourceType, using LISTS as a placeholder
+            relationshipType: RelationshipType.HAS_NOTE,
+            targetFilters: {
+                filters: [
+                    {
+                        attribute: { slug: 'note_content' },
+                        condition: FilterConditionType.CONTAINS,
+                        value: textSearch,
+                    },
+                ],
+                matchAny: false,
+            },
+        };
+        // Convert to an Attio API compatible filter
+        return createRelationshipFilter(relationshipConfig);
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new FilterValidationError(`Failed to create records-by-notes filter: ${errorMessage}`);
+    }
+}
+/**
+ * Core function to create relationship-based filters
+ * This translates our internal representation to the format expected by the Attio API
+ *
+ * @param config - Relationship filter configuration
+ * @returns Filter in the format expected by Attio API
+ */
+function createRelationshipFilter(config) {
+    // The structure we're aiming for in the Attio API format:
+    // {
+    //   "$relationship": {
+    //     "type": "works_at",
+    //     "target": {
+    //       "object": "companies",
+    //       "filter": { /* target filters */ }
+    //     }
+    //   }
+    // }
+    // Map our ResourceType to Attio API object names
+    const getObjectName = (type) => {
+        switch (type) {
+            case ResourceType.PEOPLE:
+                return 'people';
+            case ResourceType.COMPANIES:
+                return 'companies';
+            case ResourceType.LISTS:
+                return 'lists';
+            case ResourceType.RECORDS:
+                return 'records';
+            default:
+                throw new Error(`Unsupported resource type: ${type}`);
+        }
+    };
+    // The relationship field should be a custom attribute in the filter
+    return {
+        filters: [
+            {
+                attribute: {
+                    slug: '$relationship',
+                },
+                condition: FilterConditionType.EQUALS,
+                value: {
+                    type: config.relationshipType,
+                    target: {
+                        object: getObjectName(config.targetType),
+                        filter: config.targetFilters,
+                    },
+                },
+            },
+        ],
+        matchAny: false,
+    };
+}
+//# sourceMappingURL=relationship-utils.js.map

package/dist/utils/relationship-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship-utils.js","sourceRoot":"","sources":["../../src/utils/relationship-utils.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,188 @@
+/**
+ * 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}`;
+    const paginationText = pagination?.hasMore
+        ? `\n\nShowing ${countText} items. More items available.`
+        : `\n\nShowing ${countText} items.`;
+    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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"}

package/dist/utils/uri-parser.d.ts

@@ -0,0 +1,18 @@
+import { ResourceType } from '../types/attio.js';
+/**
+ * Parse an Attio resource URI into resource type and ID
+ *
+ * @param uri - The URI to parse (format: attio://{type}/{id})
+ * @returns Tuple of [resourceType, resourceId]
+ * @throws Error if URI format is invalid
+ */
+export declare function parseResourceUri(uri: string): [ResourceType, string];
+/**
+ * Creates an Attio resource URI from a type and ID
+ *
+ * @param type - The resource type
+ * @param id - The resource ID
+ * @returns Formatted URI
+ */
+export declare function formatResourceUri(type: ResourceType, id: string): string;
+//# sourceMappingURL=uri-parser.d.ts.map

package/dist/utils/uri-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uri-parser.d.ts","sourceRoot":"","sources":["../../src/utils/uri-parser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,YAAY,EAAE,MAAM,CAAC,CAepE;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,YAAY,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAExE"}

package/dist/utils/uri-parser.js

@@ -0,0 +1,31 @@
+import { ResourceType } from '../types/attio.js';
+/**
+ * Parse an Attio resource URI into resource type and ID
+ *
+ * @param uri - The URI to parse (format: attio://{type}/{id})
+ * @returns Tuple of [resourceType, resourceId]
+ * @throws Error if URI format is invalid
+ */
+export function parseResourceUri(uri) {
+    const match = uri.match(/^attio:\/\/([^\/]+)\/(.+)$/);
+    if (!match) {
+        throw new Error(`Invalid resource URI format: ${uri}`);
+    }
+    const [, typeStr, id] = match;
+    // Validate resource type
+    if (!Object.values(ResourceType).includes(typeStr)) {
+        throw new Error(`Unsupported resource type: ${typeStr}`);
+    }
+    return [typeStr, id];
+}
+/**
+ * Creates an Attio resource URI from a type and ID
+ *
+ * @param type - The resource type
+ * @param id - The resource ID
+ * @returns Formatted URI
+ */
+export function formatResourceUri(type, id) {
+    return `attio://${type}/${id}`;
+}
+//# sourceMappingURL=uri-parser.js.map

package/dist/utils/uri-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uri-parser.js","sourceRoot":"","sources":["../../src/utils/uri-parser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,4BAA4B,CAAC,CAAC;IAEtD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,gCAAgC,GAAG,EAAE,CAAC,CAAC;IACzD,CAAC;IAED,MAAM,CAAC,EAAE,OAAO,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC;IAE9B,yBAAyB;IACzB,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,QAAQ,CAAC,OAAuB,CAAC,EAAE,CAAC;QACnE,MAAM,IAAI,KAAK,CAAC,8BAA8B,OAAO,EAAE,CAAC,CAAC;IAC3D,CAAC;IAED,OAAO,CAAC,OAAuB,EAAE,EAAE,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAkB,EAAE,EAAU;IAC9D,OAAO,WAAW,IAAI,IAAI,EAAE,EAAE,CAAC;AACjC,CAAC"}