Attio MCP Server

Instructions

Implementation Reference

• src/objects/lists/filtering.ts:19-51 (handler)

  The core handler function for the 'filter-list-entries' tool. Validates parameters, constructs a single-condition filter object, and delegates to getListEntries for execution.

  export async function filterListEntries(
    listId: string,
    attributeSlug: string,
    condition: string,
    value: unknown,
    limit: number = 20,
    offset: number = 0
  ): Promise<AttioListEntry[]> {
    if (!listId || typeof listId !== 'string') {
      throw new Error('Invalid list ID: Must be a non-empty string');
    }
  
    if (!attributeSlug || typeof attributeSlug !== 'string') {
      throw new Error('Invalid attribute slug: Must be a non-empty string');
    }
  
    if (!condition || typeof condition !== 'string') {
      throw new Error('Invalid condition: Must be a non-empty string');
    }
  
    const filters: ListEntryFilters = {
      filters: [
        {
          attribute: { slug: attributeSlug },
          condition,
          value: value as FilterValue,
        },
      ],
      matchAny: false,
    };
  
    return getListEntries(listId, limit, offset, filters);
  }

• src/handlers/tool-configs/lists.ts:305-368 (schema)

  The input schema and description definition for the 'filter-list-entries' tool, including parameters, types, enums, and examples.

  {
    name: 'filter-list-entries',
    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',
          description:
            "Filter condition (e.g., 'equals', 'contains', 'greater_than')",
          enum: [
            'equals',
            'not_equals',
            'contains',
            'not_contains',
            'starts_with',
            'ends_with',
            'greater_than',
            'less_than',
            'greater_than_or_equals',
            'less_than_or_equals',
            'is_empty',
            'is_not_empty',
            '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,
    },
  },

• src/handlers/tool-configs/lists.ts:88-95 (registration)

  The tool configuration registration that maps the 'filter-list-entries' name to its handler function and specifies result formatting.

  filterListEntries: {
    name: 'filter-list-entries',
    handler: filterListEntries,
    formatResult: (results: AttioListEntry[]) => {
      // Return JSON string
      return JSON.stringify(Array.isArray(results) ? results : []);
    },
  } as ToolConfig,