attio-mcp 0.1.2 → 1.1.0

package/dist/handlers/tool-configs/lists.js

@@ -1,210 +1,145 @@
-import { getRecordNameFromEntry } from '../../utils/record-utils.js';
+import { isValidUUID } from '../../utils/validation/uuid-validation.js';
 import { getLists, getListDetails, getListEntries, filterListEntries, advancedFilterListEntries, addRecordToList, removeRecordFromList, updateListEntry, getRecordListMemberships, filterListEntriesByParent, filterListEntriesByParentId, } from '../../objects/lists.js';
+import { formatToolDescription } from '../../handlers/tools/standards/index.js';
 // Lists tool configurations
 export const listsToolConfigs = {
     getLists: {
         name: 'get-lists',
         handler: getLists,
         formatResult: (results) => {
-            return `Found ${results.length} lists:\n${results
-                .map((list) => {
-                // Extract list_id properly from id object
-                const listId = list.id?.list_id || list.id || 'unknown';
-                return `- ${list.name || list.title} (ID: ${listId})`;
-            })
-                .join('\n')}`;
+            // Return JSON string - dispatcher will convert to JSON content
+            return JSON.stringify(Array.isArray(results) ? results : []);
         },
     },
     getRecordListMemberships: {
         name: 'get-record-list-memberships',
         handler: getRecordListMemberships,
         formatResult: (results) => {
-            if (results.length === 0) {
-                return 'Record is not a member of any lists.';
-            }
-            return `Found ${results.length} list membership(s):\n${results
-                .map((membership) => {
-                // Format each membership with list name and IDs
-                let membershipInfo = `- List: ${membership.listName} (ID: ${membership.listId})
-  Entry ID: ${membership.entryId}`;
-                // Add entry values if available
-                if (membership.entryValues &&
-                    Object.keys(membership.entryValues).length > 0) {
-                    const valuesString = Object.entries(membership.entryValues)
-                        .map(([key, value]) => `    ${key}: ${value}`)
-                        .join('\n');
-                    membershipInfo += `\n  Entry Values:\n${valuesString}`;
-                }
-                return membershipInfo;
-            })
-                .join('\n')}`;
+            // Return JSON string - dispatcher will convert to JSON content
+            return JSON.stringify(Array.isArray(results) ? results : []);
         },
     },
     getListDetails: {
         name: 'get-list-details',
-        handler: getListDetails,
+        handler: async (listId) => {
+            // Let Attio API decide if list ID is valid (supports UUIDs and slugs)
+            return await getListDetails(listId);
+        },
         formatResult: (result) => {
-            // Extract list_id properly from id object
-            const listId = result.id?.list_id || result.id || 'unknown';
-            const listName = result.name || result.title || 'Unnamed List';
-            const objectType = result.object_slug || 'unknown';
-            const entryCount = result.entry_count !== undefined
-                ? `${result.entry_count} entries`
-                : 'Unknown entry count';
-            // Format dates in ISO format for consistency across environments
-            const createdAt = result.created_at
-                ? new Date(result.created_at).toISOString().split('T')[0]
-                : 'Unknown date';
-            const updatedAt = result.updated_at
-                ? new Date(result.updated_at).toISOString().split('T')[0]
-                : 'Unknown date';
-            return `List Details:
-ID: ${listId}
-Name: ${listName}
-Object Type: ${objectType}
-${entryCount}
-Created: ${createdAt}
-Updated: ${updatedAt}
-${result.description ? `\nDescription: ${result.description}` : ''}`;
+            // Return JSON string
+            return JSON.stringify(result);
         },
     },
     getListEntries: {
         name: 'get-list-entries',
-        handler: getListEntries,
+        handler: async (listId, limit, offset) => {
+            // UUID validation - hard fail for invalid list IDs
+            if (!isValidUUID(listId)) {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Invalid list_id: must be a UUID. Got: ${listId}`,
+                        },
+                    ],
+                };
+            }
+            return await getListEntries(listId, limit, offset);
+        },
         formatResult: (results) => {
-            return `Found ${results.length} entries in list:\n${results
-                .map((entry) => {
-                // Extract record details with improved name and type extraction
-                const recordDetails = getRecordNameFromEntry(entry);
-                // Format display name with record type for better context
-                let displayInfo = '';
-                if (recordDetails.name) {
-                    displayInfo = recordDetails.type
-                        ? ` (${recordDetails.type}: ${recordDetails.name})`
-                        : ` (${recordDetails.name})`;
-                }
-                return `- Entry ID: ${entry.id?.entry_id || 'unknown'}, Record ID: ${entry.record_id || 'unknown'}${displayInfo}`;
-            })
-                .join('\n')}`;
+            // Handle validation error response
+            if (results && typeof results === 'object' && 'isError' in results) {
+                return 'Error: Invalid list ID';
+            }
+            // Return JSON string
+            return JSON.stringify(Array.isArray(results) ? results : []);
         },
     },
     filterListEntries: {
         name: 'filter-list-entries',
         handler: filterListEntries,
         formatResult: (results) => {
-            return `Found ${results.length} filtered entries in list:\n${results
-                .map((entry) => {
-                // Extract record details with improved name and type extraction
-                const recordDetails = getRecordNameFromEntry(entry);
-                // Format display name with record type for better context
-                let displayInfo = '';
-                if (recordDetails.name) {
-                    displayInfo = recordDetails.type
-                        ? ` (${recordDetails.type}: ${recordDetails.name})`
-                        : ` (${recordDetails.name})`;
-                }
-                return `- Entry ID: ${entry.id?.entry_id || 'unknown'}, Record ID: ${entry.record_id || 'unknown'}${displayInfo}`;
-            })
-                .join('\n')}`;
+            // Return JSON string
+            return JSON.stringify(Array.isArray(results) ? results : []);
         },
     },
     advancedFilterListEntries: {
         name: 'advanced-filter-list-entries',
         handler: advancedFilterListEntries,
         formatResult: (results) => {
-            return `Found ${results.length} filtered entries in list:\n${results
-                .map((entry) => {
-                // Extract record details with improved name and type extraction
-                const recordDetails = getRecordNameFromEntry(entry);
-                // Format display name with record type for better context
-                let displayInfo = '';
-                if (recordDetails.name) {
-                    displayInfo = recordDetails.type
-                        ? ` (${recordDetails.type}: ${recordDetails.name})`
-                        : ` (${recordDetails.name})`;
-                }
-                return `- Entry ID: ${entry.id?.entry_id || 'unknown'}, Record ID: ${entry.record_id || 'unknown'}${displayInfo}`;
-            })
-                .join('\n')}`;
+            // Return JSON string
+            return JSON.stringify(Array.isArray(results) ? results : []);
         },
     },
     addRecordToList: {
         name: 'add-record-to-list',
-        handler: addRecordToList,
+        handler: async (listId, recordId, objectType, values) => {
+            // UUID validation - hard fail for invalid list IDs
+            if (!isValidUUID(listId)) {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Invalid list_id: must be a UUID. Got: ${listId}`,
+                        },
+                    ],
+                };
+            }
+            return await addRecordToList(listId, recordId, objectType, values);
+        },
         idParams: ['listId', 'recordId'],
         formatResult: (result) => {
-            const entryId = result.id?.entry_id || 'unknown';
-            const recordId = result.record_id || result.parent_record_id || 'unknown';
-            return `Successfully added record ${recordId} to list (Entry ID: ${entryId})`;
+            // Handle validation error response
+            if (result && typeof result === 'object' && 'isError' in result) {
+                return 'Error: Invalid list ID';
+            }
+            // Return JSON string
+            return JSON.stringify(result);
         },
     },
     removeRecordFromList: {
         name: 'remove-record-from-list',
-        handler: removeRecordFromList,
+        handler: async (listId, entryId) => {
+            // UUID validation - hard fail for invalid list IDs
+            if (!isValidUUID(listId)) {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Invalid list_id: must be a UUID. Got: ${listId}`,
+                        },
+                    ],
+                };
+            }
+            return await removeRecordFromList(listId, entryId);
+        },
         idParams: ['listId', 'entryId'],
     },
     updateListEntry: {
         name: 'update-list-entry',
         handler: updateListEntry,
         formatResult: (result) => {
-            const entryId = result.id?.entry_id || 'unknown';
-            const recordId = result.record_id || 'unknown';
-            // Extract stage information if available
-            let stageInfo = '';
-            const values = result.values;
-            if (values && values.stage) {
-                const stageValue = Array.isArray(values.stage)
-                    ? values.stage[0]?.value || values.stage[0]
-                    : values.stage.value || values.stage;
-                stageInfo = ` - Stage: ${stageValue}`;
-            }
-            return `Successfully updated list entry ${entryId} for record ${recordId}${stageInfo}`;
+            // Return JSON string
+            return JSON.stringify(result);
         },
     },
     filterListEntriesByParent: {
         name: 'filter-list-entries-by-parent',
         handler: filterListEntriesByParent,
         formatResult: (results) => {
-            if (results.length === 0) {
-                return 'No entries found matching the filter criteria.';
-            }
-            return `Found ${results.length} entries matching the parent record filter:\n${results
-                .map((entry, index) => {
-                // Extract record details with improved name and type extraction
-                const recordDetails = getRecordNameFromEntry(entry);
-                // Format display name with record type for better context
-                let displayInfo = '';
-                if (recordDetails.name) {
-                    displayInfo = recordDetails.type
-                        ? ` (${recordDetails.type}: ${recordDetails.name})`
-                        : ` (${recordDetails.name})`;
-                }
-                return `${index + 1}. Entry ID: ${entry.id?.entry_id || 'unknown'}, Record ID: ${entry.record_id || 'unknown'}${displayInfo}`;
-            })
-                .join('\n')}`;
+            // Return JSON string
+            return JSON.stringify(Array.isArray(results) ? results : []);
         },
     },
     filterListEntriesByParentId: {
         name: 'filter-list-entries-by-parent-id',
         handler: filterListEntriesByParentId,
         formatResult: (results) => {
-            if (results.length === 0) {
-                return 'No entries found with the specified parent record ID.';
-            }
-            return `Found ${results.length} entries with the specified parent record ID:\n${results
-                .map((entry, index) => {
-                // Extract record details with improved name and type extraction
-                const recordDetails = getRecordNameFromEntry(entry);
-                // Format display name with record type for better context
-                let displayInfo = '';
-                if (recordDetails.name) {
-                    displayInfo = recordDetails.type
-                        ? ` (${recordDetails.type}: ${recordDetails.name})`
-                        : ` (${recordDetails.name})`;
-                }
-                return `${index + 1}. Entry ID: ${entry.id?.entry_id || 'unknown'}, Record ID: ${entry.record_id || 'unknown'}${displayInfo}`;
-            })
-                .join('\n')}`;
+            // Return JSON string
+            return JSON.stringify(Array.isArray(results) ? results : []);
         },
     },
 };
@@ -212,21 +147,33 @@ ${result.description ? `\nDescription: ${result.description}` : ''}`;
 export const listsToolDefinitions = [
     {
         name: 'get-lists',
-        description: 'Get all CRM lists from Attio (sales pipelines, lead stages, customer segments, etc.)',
+        description: formatToolDescription({
+            capability: 'Retrieve all CRM lists (sales pipelines, lead stages, customer segments).',
+            boundaries: 'create or modify lists, only reads existing lists.',
+            constraints: 'Returns all lists visible to the authenticated workspace.',
+            recoveryHint: 'Use get-list-details to inspect individual list schemas.',
+        }),
         inputSchema: {
             type: 'object',
             properties: {},
+            additionalProperties: false,
         },
     },
     {
         name: 'get-record-list-memberships',
-        description: 'Find all CRM lists that a specific record (company, person, etc.) belongs to',
+        description: formatToolDescription({
+            capability: 'Find all lists containing a specific company or person record.',
+            boundaries: 'modify list memberships or retrieve list entries.',
+            constraints: 'Requires recordId; processes 5 lists in parallel by default (max 20).',
+            recoveryHint: 'If record not found, verify recordId with records_search first.',
+        }),
         inputSchema: {
             type: 'object',
             properties: {
                 recordId: {
                     type: 'string',
                     description: 'ID of the record to find in lists',
+                    example: '550e8400-e29b-41d4-a716-446655440000',
                 },
                 objectType: {
                     type: 'string',
@@ -247,57 +194,81 @@ export const listsToolDefinitions = [
                 },
             },
             required: ['recordId'],
+            additionalProperties: false,
         },
     },
     {
         name: 'get-list-details',
-        description: 'Get details for a specific CRM list (pipeline stages, field configuration, etc.)',
+        description: formatToolDescription({
+            capability: 'Retrieve schema and configuration for a specific list (stages, fields, attributes).',
+            boundaries: 'modify list structure or retrieve list entries.',
+            constraints: 'Requires valid list UUID or slug; accepts both formats.',
+            recoveryHint: 'Use get-lists to discover available list IDs and slugs first.',
+        }),
         inputSchema: {
             type: 'object',
             properties: {
                 listId: {
                     type: 'string',
-                    description: 'ID of the list to get details for',
+                    description: 'ID or slug of the list to get details for',
+                    example: 'sales-pipeline',
                 },
             },
             required: ['listId'],
+            additionalProperties: false,
         },
     },
     {
         name: 'get-list-entries',
-        description: 'Get entries for a specific list',
+        description: formatToolDescription({
+            capability: 'Retrieve all records in a list with pagination (companies, people in pipelines).',
+            boundaries: 'filter entries or modify list memberships.',
+            constraints: 'Requires list UUID (not slug); default limit 20, max per page varies by API.',
+            recoveryHint: 'Use filter-list-entries for attribute-based filtering instead.',
+        }),
         inputSchema: {
             type: 'object',
             properties: {
                 listId: {
                     type: 'string',
-                    description: 'ID of the list to get entries for',
+                    description: 'UUID of the list to get entries for',
+                    example: '550e8400-e29b-41d4-a716-446655440000',
                 },
                 limit: {
                     type: 'number',
                     description: 'Maximum number of entries to fetch (default: 20)',
+                    example: 50,
                 },
                 offset: {
                     type: 'number',
                     description: 'Number of entries to skip for pagination (default: 0)',
+                    example: 0,
                 },
             },
             required: ['listId'],
+            additionalProperties: false,
         },
     },
     {
         name: 'filter-list-entries',
-        description: 'Filter entries in a list by a specific attribute',
+        description: formatToolDescription({
+            capability: 'Filter list entries by single attribute condition.',
+            boundaries: 'combine conditions; use advanced-filter for multi-condition.',
+            constraints: 'Requires listId, attributeSlug, condition, value.',
+            recoveryHint: 'Use get-list-details for valid attribute slugs.',
+        }),
         inputSchema: {
             type: 'object',
             properties: {
                 listId: {
                     type: 'string',
                     description: 'ID of the list to filter entries from',
+                    example: '550e8400-e29b-41d4-a716-446655440000',
                 },
                 attributeSlug: {
                     type: 'string',
                     description: "Slug of the attribute to filter by (e.g., 'stage', 'status')",
+                    example: 'stage',
                 },
                 condition: {
                     type: 'string',
@@ -318,31 +289,42 @@ export const listsToolDefinitions = [
                         'is_set',
                         'is_not_set',
                     ],
+                    example: 'equals',
                 },
                 value: {
                     description: 'Value to filter by (type depends on the attribute)',
+                    example: 'Qualified',
                 },
                 limit: {
                     type: 'number',
                     description: 'Maximum number of entries to fetch (default: 20)',
+                    example: 50,
                 },
                 offset: {
                     type: 'number',
                     description: 'Number of entries to skip for pagination (default: 0)',
+                    example: 0,
                 },
             },
             required: ['listId', 'attributeSlug', 'condition', 'value'],
+            additionalProperties: false,
         },
     },
     {
         name: 'advanced-filter-list-entries',
-        description: 'Filter entries in a list with advanced multiple conditions',
+        description: formatToolDescription({
+            capability: 'Filter entries with multi-condition queries (AND/OR logic).',
+            boundaries: 'modify entries; read-only.',
+            constraints: 'Requires listId, filters array; matchAny for OR logic.',
+            recoveryHint: 'Use filter-list-entries for single conditions.',
+        }),
         inputSchema: {
             type: 'object',
             properties: {
                 listId: {
                     type: 'string',
                     description: 'ID of the list to filter entries from',
+                    example: '550e8400-e29b-41d4-a716-446655440000',
                 },
                 filters: {
                     type: 'object',
@@ -406,73 +388,104 @@ export const listsToolDefinitions = [
                 limit: {
                     type: 'number',
                     description: 'Maximum number of entries to fetch (default: 20)',
+                    example: 50,
                 },
                 offset: {
                     type: 'number',
                     description: 'Number of entries to skip for pagination (default: 0)',
+                    example: 0,
                 },
             },
             required: ['listId', 'filters'],
+            additionalProperties: false,
         },
     },
     {
         name: 'add-record-to-list',
-        description: 'Add a company or person to a CRM list (sales pipeline, lead list, etc.)',
+        description: formatToolDescription({
+            capability: 'Add company or person to list with optional initial values.',
+            boundaries: 'create records; record must exist first.',
+            requiresApproval: true,
+            constraints: 'Requires list UUID, record UUID, object type.',
+            recoveryHint: 'If not found, create record first with create-record.',
+        }),
         inputSchema: {
             type: 'object',
             properties: {
                 listId: {
                     type: 'string',
-                    description: 'ID of the list to add the record to',
+                    description: 'UUID of the list to add the record to',
+                    example: '550e8400-e29b-41d4-a716-446655440000',
                 },
                 recordId: {
                     type: 'string',
-                    description: 'ID of the record to add to the list',
+                    description: 'UUID of the record to add to the list',
+                    example: '660e8400-e29b-41d4-a716-446655440001',
                 },
                 objectType: {
                     type: 'string',
                     description: 'Type of record (e.g., "companies", "people")',
                     enum: ['companies', 'people'],
+                    example: 'companies',
                 },
                 initialValues: {
                     type: 'object',
                     description: 'Initial values for the list entry (e.g., {"stage": "Prospect"})',
+                    example: { stage: 'Qualified' },
                 },
             },
             required: ['listId', 'recordId', 'objectType'],
+            additionalProperties: false,
         },
     },
     {
         name: 'remove-record-from-list',
-        description: 'Remove a record from a list',
+        description: formatToolDescription({
+            capability: 'Remove company or person from list (membership only).',
+            boundaries: 'delete underlying record; membership only.',
+            requiresApproval: true,
+            constraints: 'Requires list UUID, entry UUID (not record UUID).',
+            recoveryHint: 'Use get-list-entries to find entry UUID.',
+        }),
         inputSchema: {
             type: 'object',
             properties: {
                 listId: {
                     type: 'string',
-                    description: 'ID of the list to remove the record from',
+                    description: 'UUID of the list to remove the entry from',
+                    example: '550e8400-e29b-41d4-a716-446655440000',
                 },
                 entryId: {
                     type: 'string',
-                    description: 'ID of the list entry to remove',
+                    description: 'UUID of the list entry to remove (not the record ID)',
+                    example: '770e8400-e29b-41d4-a716-446655440002',
                 },
             },
             required: ['listId', 'entryId'],
+            additionalProperties: false,
         },
     },
     {
         name: 'update-list-entry',
-        description: "Update a list entry (e.g., change stage from 'Interested' to 'Demo Scheduling')",
+        description: formatToolDescription({
+            capability: 'Update list entry attributes (stage, status, custom fields).',
+            boundaries: 'update record attributes; use update-record for that.',
+            requiresApproval: true,
+            constraints: 'Requires list UUID, entry UUID, attributes object.',
+            recoveryHint: 'Use get-list-details for valid attributes and values.',
+        }),
         inputSchema: {
             type: 'object',
             properties: {
                 listId: {
                     type: 'string',
-                    description: 'ID of the list containing the entry',
+                    description: 'UUID of the list containing the entry',
+                    example: '550e8400-e29b-41d4-a716-446655440000',
                 },
                 entryId: {
                     type: 'string',
-                    description: 'ID of the list entry to update',
+                    description: 'UUID of the list entry to update',
+                    example: '770e8400-e29b-41d4-a716-446655440002',
                 },
                 attributes: {
                     type: 'object',
@@ -481,32 +494,42 @@ export const listsToolDefinitions = [
                         stage: {
                             type: 'string',
                             description: "New stage value (e.g., 'Demo Scheduling', 'Interested', 'Won')",
+                            example: 'Demo Scheduling',
                         },
                     },
                     additionalProperties: true,
                 },
             },
             required: ['listId', 'entryId', 'attributes'],
+            additionalProperties: false,
         },
     },
     {
         name: 'filter-list-entries-by-parent',
-        description: 'Filter list entries based on parent record properties',
+        description: formatToolDescription({
+            capability: 'Filter entries by parent record attributes (industry, role).',
+            boundaries: 'search multiple lists or modify records.',
+            constraints: 'Requires listId, parentObjectType, parentAttributeSlug, condition, value.',
+            recoveryHint: 'Use records_discover_attributes for valid slugs.',
+        }),
         inputSchema: {
             type: 'object',
             properties: {
                 listId: {
                     type: 'string',
-                    description: 'ID of the list to filter entries from',
+                    description: 'UUID of the list to filter entries from',
+                    example: '550e8400-e29b-41d4-a716-446655440000',
                 },
                 parentObjectType: {
                     type: 'string',
                     description: 'Type of the parent record (e.g., "companies", "people")',
                     enum: ['companies', 'people'],
+                    example: 'companies',
                 },
                 parentAttributeSlug: {
                     type: 'string',
-                    description: 'Attribute of the parent record to filter by (e.g., "name", "email_addresses", "industry")',
+                    description: 'Attribute of the parent record to filter by (e.g., "name", "email_addresses", "categories")',
+                    example: 'categories',
                 },
                 condition: {
                     type: 'string',
@@ -527,17 +550,21 @@ export const listsToolDefinitions = [
                         'is_set',
                         'is_not_set',
                     ],
+                    example: 'contains',
                 },
                 value: {
                     description: 'Value to filter by (type depends on the attribute)',
+                    example: 'Technology',
                 },
                 limit: {
                     type: 'number',
                     description: 'Maximum number of entries to fetch (default: 20)',
+                    example: 50,
                 },
                 offset: {
                     type: 'number',
                     description: 'Number of entries to skip for pagination (default: 0)',
+                    example: 0,
                 },
             },
             required: [
@@ -547,32 +574,43 @@ export const listsToolDefinitions = [
                 'condition',
                 'value',
             ],
+            additionalProperties: false,
         },
     },
     {
         name: 'filter-list-entries-by-parent-id',
-        description: 'Filter list entries by parent record ID',
+        description: formatToolDescription({
+            capability: 'Filter entries by exact parent record UUID.',
+            boundaries: 'search multiple lists.',
+            constraints: 'Requires list UUID, record UUID; faster than attribute filtering.',
+            recoveryHint: 'Use get-record-list-memberships for workspace-wide search.',
+        }),
         inputSchema: {
             type: 'object',
             properties: {
                 listId: {
                     type: 'string',
-                    description: 'ID of the list to filter entries from',
+                    description: 'UUID of the list to filter entries from',
+                    example: '550e8400-e29b-41d4-a716-446655440000',
                 },
                 recordId: {
                     type: 'string',
-                    description: 'ID of the parent record to filter by',
+                    description: 'UUID of the parent record to filter by',
+                    example: '660e8400-e29b-41d4-a716-446655440001',
                 },
                 limit: {
                     type: 'number',
                     description: 'Maximum number of entries to fetch (default: 20)',
+                    example: 50,
                 },
                 offset: {
                     type: 'number',
                     description: 'Number of entries to skip for pagination (default: 0)',
+                    example: 0,
                 },
             },
             required: ['listId', 'recordId'],
+            additionalProperties: false,
         },
     },
 ];