Attio MCP Server

Instructions

Implementation Reference

• src/api/operations/lists.ts:328-407 (handler)

  Core handler function that performs the PATCH request to the Attio API to update list entry attributes via /lists/{listId}/entries/{entryId} with entry_values payload.

  export async function updateListEntry(
    listId: string,
    entryId: string,
    attributes: Record<string, unknown>,
    retryConfig?: Partial<RetryConfig>
  ): Promise<AttioListEntry> {
    const api = getLazyAttioClient();
    const path = `/lists/${listId}/entries/${entryId}`;
  
    // Input validation
    if (!listId || typeof listId !== 'string') {
      throw new Error('Invalid list ID: Must be a non-empty string');
    }
  
    if (!entryId || typeof entryId !== 'string') {
      throw new Error('Invalid entry ID: Must be a non-empty string');
    }
  
    if (
      !attributes ||
      typeof attributes !== 'object' ||
      Array.isArray(attributes)
    ) {
      throw new Error('Invalid attributes: Must be a non-empty object');
    }
  
    return callWithRetry(async () => {
      const log = createScopedLogger('lists.operations', 'updateListEntry');
      try {
        if (process.env.NODE_ENV === 'development') {
          log.info('Updating list entry', { path, listId, entryId, attributes });
        }
  
        // Attio API expects updates to list entries in the 'data.entry_values' structure
        // This is specific to list entries, different from record updates in crud.ts
        const response = await api.patch<AttioSingleResponse<AttioListEntry>>(
          path,
          {
            data: {
              entry_values: attributes,
            },
          }
        );
  
        if (process.env.NODE_ENV === 'development') {
          log.info('Update list entry success', { data: response.data });
        }
  
        return response?.data?.data || response?.data;
      } catch (error: unknown) {
        const updateError = error as ListErrorResponse;
        // Enhanced error logging with specific error types
        if (process.env.NODE_ENV === 'development') {
          log.warn('Update list entry error', {
            message: updateError.message || 'Unknown error',
            status: updateError.response?.status,
            data: updateError.response?.data || {},
          });
        }
  
        // Add more specific error types based on status codes
        if (updateError.response?.status === 404) {
          throw new Error(`List entry ${entryId} not found in list ${listId}`);
        } else if (updateError.response?.status === 400) {
          throw new Error(
            `Invalid attributes for list entry update: ${
              updateError.response?.data?.message || 'Bad request'
            }`
          );
        } else if (updateError.response?.status === 403) {
          throw new Error(
            `Insufficient permissions to update list entry ${entryId} in list ${listId}`
          );
        }
  
        // Let upstream handlers create specific, rich error objects.
        throw error;
      }
    }, retryConfig);
  }

• src/handlers/tool-configs/lists.ts:160-167 (registration)

  Tool configuration registration mapping 'update-list-entry' name to the updateListEntry handler function with result formatting.

  updateListEntry: {
    name: 'update-list-entry',
    handler: updateListEntry,
    formatResult: (result: AttioListEntry) => {
      // Return JSON string
      return JSON.stringify(result);
    },
  } as ToolConfig,

• src/handlers/tool-configs/lists.ts:530-570 (schema)

  Tool definition including description, input schema with required listId, entryId, attributes, and approval requirement.

  {
    name: 'update-list-entry',
    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: 'UUID of the list containing the entry',
          example: '550e8400-e29b-41d4-a716-446655440000',
        },
        entryId: {
          type: 'string',
          description: 'UUID of the list entry to update',
          example: '770e8400-e29b-41d4-a716-446655440002',
        },
        attributes: {
          type: 'object',
          description: 'Attributes to update on the list entry',
          properties: {
            stage: {
              type: 'string',
              description:
                "New stage value (e.g., 'Demo Scheduling', 'Interested', 'Won')",
              example: 'Demo Scheduling',
            },
          },
          additionalProperties: true,
        },
      },
      required: ['listId', 'entryId', 'attributes'],
      additionalProperties: false,
    },
  },