affinity-sdk 2.0.6__tar.gz → 2.0.7__tar.gz

{affinity_sdk-2.0.6 → affinity_sdk-2.0.7}/CHANGELOG.md

@@ -5,6 +5,34 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.7] - 2026-11-03
+
+**Exception to semantic versioning** (as 2.0.2–2.0.6): two fixes change which rows a filter
+returns. Each is marked **Behavior change**.
+
+### Highlights
+
+A repeated `--filter` now combines its conditions instead of keeping only the last one, and a
+person or company field filtered by id (`Owner = 26229794`) matches that person instead of
+nothing.
+
+### Changed
+
+- **Behavior change (correctness fix). CLI: repeated `--filter` values are ANDed** on
+  `list export`, `company ls` and `person ls`, and so are repeated `list export --expand-filter`
+  values. Only the last one used to apply, and the others were dropped without a warning, so such
+  runs returned rows that didn't match the earlier conditions: re-run them. `--filter A --filter B`
+  is `(A) & (B)`; for OR, use `|` inside one value. Each repeated value must be a complete
+  expression on its own. (The MCP server refused a repeated `--filter`, so MCP calls weren't
+  affected.)
+- **Behavior change (correctness fix). CLI and SDK: a person or company field compared with a
+  number matches the record's id.** `Owner = 26229794` (and `in`, `has_any`, `has_all`) in
+  `--filter`, `query` and `affinity.filters` compared the name with "26229794" and matched nothing,
+  without a warning (`!=` matched every row). It now matches that person's id, and names still
+  match as before. Other record references, such as lists, match their id too. Re-run filters that
+  used ids. A reference with no name (a person without a first and last name, a company with an
+  empty name) still can't be matched by id.
+
 ## [2.0.6] - 2026-10-14
 
 ### Fixed

{affinity_sdk-2.0.6 → affinity_sdk-2.0.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: affinity-sdk
-Version: 2.0.6
+Version: 2.0.7
 Summary: A modern, strongly-typed Python SDK for the Affinity CRM API
 Project-URL: Homepage, https://github.com/yaniv-golan/affinity-sdk
 Project-URL: Documentation, https://yaniv-golan.github.io/affinity-sdk/latest/

{affinity_sdk-2.0.6 → affinity_sdk-2.0.7}/affinity/cli/commands/company_cmds.py

@@ -29,7 +29,12 @@ from ..entity_search import COMPANY_KEYS, filtered_ls
 from ..errors import CLIError
 from ..list_search import is_filter_cursor
 from ..mcp_limits import apply_mcp_limits
-from ..options import csv_output_options, csv_suboption_callback, output_options
+from ..options import (
+    csv_output_options,
+    csv_suboption_callback,
+    join_filters_callback,
+    output_options,
+)
 from ..progress import ProgressManager, ProgressSettings
 from ..resolve import get_company_fields, resolve_list_selector
 from ..resolvers import ResolvedEntity
@@ -330,9 +335,11 @@ def _parse_field_types(values: tuple[str, ...]) -> list[FieldType] | None:
     "--filter",
     "filter_expr",
     type=str,
-    default=None,
+    multiple=True,
+    callback=join_filters_callback,
     help="Filter on company fields, applied by Affinity's search: 'field op value'. Ops: = != "
-    "=~ =^ =$ > < >= <= starts_word. E.g., 'Stage = \"Seed\"'. Name search: --query.",
+    "=~ =^ =$ > < >= <= starts_word. E.g., 'Stage = \"Seed\"'. Name search: --query. "
+    "Repeatable: repeated values are ANDed.",
 )
 @click.option(
     "--query",

{affinity_sdk-2.0.6 → affinity_sdk-2.0.7}/affinity/cli/commands/list_cmds.py

@@ -44,7 +44,12 @@ from ..decorators import category, destructive
 from ..errors import CLIError
 from ..list_search import ListSearch, decode_cursor, encode_cursor, plan_list_search
 from ..mcp_limits import apply_mcp_limits
-from ..options import csv_output_options, csv_suboption_callback, output_options
+from ..options import (
+    csv_output_options,
+    csv_suboption_callback,
+    join_filters_callback,
+    output_options,
+)
 from ..render import format_duration
 from ..resolve import (
     list_all_saved_views,
@@ -452,9 +457,10 @@ ExpandOnError = Literal["raise", "skip"]
     "--filter",
     "filter_expr",
     type=str,
-    default=None,
+    multiple=True,
+    callback=join_filters_callback,
     help="Filter (field op value): Affinity's search applies what it can, the rest is checked "
-    'locally. Quote multi-word: Status="Intro Meeting".',
+    'locally. Quote multi-word: Status="Intro Meeting". Repeatable: repeated values are ANDed.',
 )
 @click.option(
     "--page-size",
@@ -570,8 +576,10 @@ ExpandOnError = Literal["raise", "skip"]
     "--expand-filter",
     "expand_filter",
     type=str,
-    default=None,
-    help="Filter expanded entities (e.g., 'field=value' or 'field!=value').",
+    multiple=True,
+    callback=join_filters_callback,
+    help="Filter expanded entities (e.g., 'field=value' or 'field!=value'). "
+    "Repeatable: repeated values are ANDed.",
 )
 @click.option(
     "--expand-opportunities-list",

{affinity_sdk-2.0.6 → affinity_sdk-2.0.7}/affinity/cli/commands/person_cmds.py

@@ -27,7 +27,12 @@ from ..entity_search import PERSON_KEYS, filtered_ls
 from ..errors import CLIError
 from ..list_search import is_filter_cursor
 from ..mcp_limits import apply_mcp_limits
-from ..options import csv_output_options, csv_suboption_callback, output_options
+from ..options import (
+    csv_output_options,
+    csv_suboption_callback,
+    join_filters_callback,
+    output_options,
+)
 from ..progress import ProgressManager, ProgressSettings
 from ..resolve import get_person_fields, resolve_list_selector
 from ..resolvers import ResolvedEntity
@@ -207,9 +212,11 @@ def _parse_field_types(values: tuple[str, ...]) -> list[FieldType] | None:
     "--filter",
     "filter_expr",
     type=str,
-    default=None,
+    multiple=True,
+    callback=join_filters_callback,
     help="Filter on person fields, applied by Affinity's search: 'field op value'. Ops: = != "
-    "=~ =^ =$ > < >= <= starts_word. E.g., 'Deals > 5'. Name/email search: --query.",
+    "=~ =^ =$ > < >= <= starts_word. E.g., 'Deals > 5'. Name/email search: --query. "
+    "Repeatable: repeated values are ANDed.",
 )
 @click.option(
     "--query",

{affinity_sdk-2.0.6 → affinity_sdk-2.0.7}/affinity/cli/entity_search.py

@@ -94,7 +94,8 @@ def _paths(where: WhereClause) -> set[str]:
 
 def entity_filter_dict(entity: Any) -> dict[str, Any]:
     """What a ``--filter`` on companies or persons sees: field values by name (dropdowns as
-    text, persons and companies as names) plus the record's own attributes."""
+    text, persons and companies as names that also match their id) plus the record's own
+    attributes."""
     result: dict[str, Any] = {}
     by_id: dict[str, Any] = {}
     for item in getattr(entity, "fields_raw", None) or []:

{affinity_sdk-2.0.6 → affinity_sdk-2.0.7}/affinity/cli/options.py

@@ -4,6 +4,8 @@ import functools
 from collections.abc import Callable
 from typing import Any, TypeVar, cast
 
+from affinity.filters import parse
+
 from .click_compat import click
 from .context import CLIContext, OutputFormat
 from .errors import CLIError
@@ -143,6 +145,28 @@ def _emit_validation_error(ctx: CLIContext, err: CLIError) -> None:
             sys.stderr.write(f"Hint: {err.hint}\n")
 
 
+def join_filters_callback(
+    _ctx: click.Context, _param: click.Parameter, value: tuple[str, ...]
+) -> str | None:
+    """Callback for a repeatable filter option (--filter, --expand-filter): AND the values.
+
+    One value is passed on unchanged. Repeated values are each parsed on their own first, so a
+    value can't close the parentheses it is wrapped in, and its error names it.
+    """
+    if not value:
+        return None
+    if len(value) == 1:
+        return value[0]
+    for i, text in enumerate(value, 1):
+        if not text.strip():
+            raise click.BadParameter(f"value {i} is empty; each repeated value needs an expression")
+        try:
+            parse(text)
+        except ValueError as e:
+            raise click.BadParameter(f"value {i} ({text!r}): {e}") from e
+    return " & ".join(f"({text})" for text in value)
+
+
 def csv_suboption_callback(ctx: click.Context, param: click.Parameter, value: Any) -> Any:
     """Callback for CSV-related sub-options (--csv-bom, --csv-header, --csv-mode).
 

{affinity_sdk-2.0.6 → affinity_sdk-2.0.7}/affinity/cli/query/executor.py

@@ -16,6 +16,7 @@ from collections.abc import AsyncIterator, Awaitable, Callable, Mapping
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, Protocol, TypeVar
 
+from ...compare import entity_name
 from ...exceptions import (
     AuthorizationError,
     MergedEntityError,
@@ -262,19 +263,24 @@ def _normalize_list_entry_fields(
                                     # Person reference in multi-select
                                     name = _extract_person_display_name(item)
                                     if name:
-                                        extracted.append(name)
+                                        extracted.append(entity_name(name, item.get("id")))
                                 elif isinstance(item, dict) and "name" in item:
                                     # Company reference in multi-select
-                                    extracted.append(item["name"])
+                                    extracted.append(entity_name(item["name"], item.get("id")))
                                 else:
                                     extracted.append(item)
                             normalized_fields[field_name] = extracted
                         # Handle person reference: {"firstName": "Jane", "lastName": "Doe"}
+                        # (names carry the record id: a filter on the id matches too)
                         elif isinstance(data, dict) and ("firstName" in data or "lastName" in data):
-                            normalized_fields[field_name] = _extract_person_display_name(data)
+                            normalized_fields[field_name] = entity_name(
+                                _extract_person_display_name(data), data.get("id")
+                            )
                         # Handle company reference: {"name": "Acme", "domain": "acme.com"}
                         elif isinstance(data, dict) and "name" in data:
-                            normalized_fields[field_name] = data["name"]
+                            normalized_fields[field_name] = entity_name(
+                                data["name"], data.get("id")
+                            )
                         else:
                             normalized_fields[field_name] = data
                     else:

{affinity_sdk-2.0.6 → affinity_sdk-2.0.7}/affinity/compare.py

@@ -16,6 +16,51 @@ from typing import Any
 from ._filtering.dates import as_utc, parse_date_value, parse_iso_datetime
 
 
+class EntityName(str):
+    """A person's or company's name (or another record reference's) that also carries the
+    record's id, so a filter can match either: ``Owner = "Jane Doe"`` or ``Owner = 123``.
+
+    It is a ``str`` everywhere else (output, sorting, text operators)."""
+
+    __slots__ = ("entity_id",)
+    entity_id: int | None
+
+    def __new__(cls, value: str, entity_id: int | None = None) -> EntityName:
+        self = super().__new__(cls, value)
+        self.entity_id = entity_id
+        return self
+
+    def __reduce__(self) -> tuple[Any, ...]:
+        # Keeps the id through copy, deepcopy and every pickle protocol
+        return (type(self), (str(self), self.entity_id))
+
+
+def entity_name(value: Any, entity_id: Any) -> Any:
+    """``value`` as an :class:`EntityName` when it is a non-empty name and ``entity_id`` an
+    integer id; anything else (no name, no id) is returned unchanged."""
+    if (
+        isinstance(value, str)
+        and value
+        and isinstance(entity_id, int)
+        and not isinstance(entity_id, bool)
+    ):
+        return EntityName(value, entity_id)
+    return value
+
+
+def _as_entity_id(value: Any) -> int | None:
+    """A filter value read as a record id: an int, or a string of ASCII digits."""
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value
+    if isinstance(value, str):
+        text = value.strip()
+        if text and text.isascii() and text.isdigit() and len(text) <= 20:
+            return int(text)
+    return None
+
+
 def normalize_value(value: Any) -> Any:
     """Normalize a value for comparison.
 
@@ -23,6 +68,7 @@ def normalize_value(value: Any) -> Any:
     - Dropdowns become their text: {"text": "Active"} -> "Active"
     - Persons become their name: {"firstName": "Jane", "lastName": "Doe"} -> "Jane Doe"
     - Companies become their name: {"name": "Acme", "domain": ...} -> "Acme"
+      (as :class:`EntityName`, carrying the record id, so a number matches the id)
     - Multi-value arrays become lists of those: [{"text": "A"}, {"text": "B"}] -> ["A", "B"]
     - Scalars pass through unchanged
 
@@ -46,9 +92,9 @@ def _normalize_item(item: dict[str, Any]) -> Any:
         parts = [
             p.strip() for p in (item.get("firstName"), item.get("lastName")) if isinstance(p, str)
         ]
-        return " ".join(p for p in parts if p) or None
+        return entity_name(" ".join(p for p in parts if p) or None, item.get("id"))
     if "name" in item:
-        return item["name"]
+        return entity_name(item["name"], item.get("id"))
     return item
 
 
@@ -163,6 +209,8 @@ def _eq(a: Any, b: Any) -> bool:
     if isinstance(a, list):
         # If comparing list to list, check set equality (order-insensitive)
         if isinstance(b, list):
+            if any(isinstance(x, EntityName) for x in a):
+                return _same_members(a, b)
             try:
                 return set(a) == set(b)
             except TypeError:
@@ -178,7 +226,8 @@ def _eq(a: Any, b: Any) -> bool:
 
 def _scalar_eq(a: Any, b: Any) -> bool:
     """Scalar equality as ``eq`` uses it, and ``in`` / ``has_any`` / ``has_all`` per element:
-    direct, then ``"true"``/``"false"`` against a bool, then by string (``5`` matches ``"5"``)."""
+    direct, then an :class:`EntityName` against its id, then ``"true"``/``"false"`` against a
+    bool, then by string (``5`` matches ``"5"``). ``a`` is the field value."""
     if a is None or b is None:
         return a is b
 
@@ -186,6 +235,10 @@ def _scalar_eq(a: Any, b: Any) -> bool:
     if a == b:
         return True
 
+    # A person or company also matches its id (Owner = 123)
+    if isinstance(a, EntityName) and a.entity_id is not None and _as_entity_id(b) == a.entity_id:
+        return True
+
     # Handle boolean coercion: filter string "true"/"false" should match Python bool
     # Filter parser outputs lowercase "true"/"false", Python str(True) is "True"
     if isinstance(a, bool) and isinstance(b, str):
@@ -198,6 +251,14 @@ def _scalar_eq(a: Any, b: Any) -> bool:
     return str(a) == str(b)
 
 
+def _same_members(a: list[Any], b: list[Any]) -> bool:
+    """Set equality through :func:`_scalar_eq` (field elements first), for lists of record
+    references: every target matches some element and every element matches some target."""
+    return all(any(_scalar_eq(x, y) for x in a) for y in b) and all(
+        any(_scalar_eq(x, y) for y in b) for x in a
+    )
+
+
 def _neq(a: Any, b: Any) -> bool:
     """Not equal operator with array membership support."""
     if a is None:
@@ -205,6 +266,8 @@ def _neq(a: Any, b: Any) -> bool:
 
     if isinstance(a, list):
         if isinstance(b, list):
+            if any(isinstance(x, EntityName) for x in a):
+                return not _same_members(a, b)
             try:
                 return set(a) != set(b)
             except TypeError:

{affinity_sdk-2.0.6 → affinity_sdk-2.0.7}/docs/public/cli/commands.md

@@ -273,7 +273,7 @@ Options:
 - `--query <term>` / `-q <term>`: free-text search (name or email)
 - `--field <id-or-name>` (repeatable): field ID or name to include
 - `--field-type <type>` (repeatable): field type to include (global, enriched, relationship-intelligence)
-- `--filter <expression>`: filter expression; must include a condition on a person field (Affinity's search applies it)
+- `--filter <expression>` (repeatable, values ANDed): filter expression; must include a condition on a person field (Affinity's search applies it)
 - `--page-size`, `--cursor`, `--max-results`, `--all`: pagination options
 - `--csv`: output as CSV (to stdout)
 - `--csv-bom`: add UTF-8 BOM for Excel compatibility
@@ -456,7 +456,7 @@ Options:
 - `--query <term>` / `-q <term>`: free-text search (name or domain)
 - `--field <id-or-name>` (repeatable): field ID or name to include
 - `--field-type <type>` (repeatable): field type to include (global, enriched, relationship-intelligence)
-- `--filter <expression>`: filter expression; must include a condition on a company field (Affinity's search applies it)
+- `--filter <expression>` (repeatable, values ANDed): filter expression; must include a condition on a company field (Affinity's search applies it)
 - `--page-size`, `--cursor`, `--max-results`, `--all`: pagination options
 - `--csv`: output as CSV (to stdout)
 - `--csv-bom`: add UTF-8 BOM for Excel compatibility
@@ -838,7 +838,7 @@ Options:
 - `--csv-bom`: add UTF-8 BOM for Excel compatibility
 - `--field <id-or-name>` (repeatable): include specific fields
 - `--saved-view <name>`: use a saved view's field selection (server-side filtering)
-- `--filter <expression>`: filter expression; Affinity's search applies what it can, the rest runs locally (see below)
+- `--filter <expression>` (repeatable, values ANDed): filter expression; Affinity's search applies what it can, the rest runs locally (see below)
 - `--company-id <id>` (repeatable): entity-scoped export — return only rows where the entry is for this company
 - `--person-id <id>` (repeatable): entity-scoped export — return only rows where the entry is for this person
 - `--first-page-only`: fetch a single page of results; output includes `meta.truncated=true` and `meta.truncationReason="firstPageOnly"` when there are more pages

{affinity_sdk-2.0.6 → affinity_sdk-2.0.7}/docs/public/guides/filtering.md

@@ -120,6 +120,10 @@ multi_region = entries.list(
 For CLI or advanced SDK use, you can use raw filter strings: the `--filter` text of
 `list export`, `company ls` and `person ls`, and `affinity.filters.parse()` in the SDK.
 
+`--filter` (and `--expand-filter`) can be repeated: the values are ANDed, so
+`--filter 'Status = "Active"' --filter 'Region = "US"'` is `(Status = "Active") & (Region = "US")`.
+Each value must be a complete expression; for OR, use `|` inside one value.
+
 ### Standard Operators
 
 These operators work in every `--filter` and in `affinity.filters`:
@@ -184,7 +188,8 @@ Human/LLM-friendly aliases for official operators:
 - **`starts_word`**: a word in the value starts with the text, case-insensitive, the way
   Affinity's search matches names. `"Jan"` matches "Jane Doe" and "Mary-Jane"; `"ane"`
   doesn't. JSON spelling in `query`: `{"path": "fields.Owner", "op": "starts_word", "value": "Jan"}`.
-- **Person and company fields** are compared by name ("Jane Doe", "Acme"). In `--filter`
+- **Person and company fields** are compared by name ("Jane Doe", "Acme"), or by id when the value is a number
+  (`Owner = 26229794`: that person's id; a value with no name can't match by id). In `--filter`
   and `query`, `contains` (and `contains_any` / `contains_all`) on a person or company
   field is refused: use `starts_word`.
 - **Empty multi-value fields**: a multi-value field with no items counts as empty.
@@ -228,6 +233,9 @@ xaffinity list export Pipeline --filter 'Region = "US" | Region = "Canada"'
 # A person field by name
 xaffinity list export Pipeline --filter 'Owner starts_word "Jan"'
 
+# A person field by id
+xaffinity list export Pipeline --filter 'Owner = 26229794' --all
+
 # Null check
 xaffinity list export Pipeline --filter 'Owner != *'
 

{affinity_sdk-2.0.6 → affinity_sdk-2.0.7}/docs/public/guides/query-command.md

@@ -185,7 +185,7 @@ Example: {"from": "persons", "include": ["interactions"]}
 | `has_any` | Array contains any of the values | `["LB", "MA"]` |
 | `has_all` | Array contains all of the values | `["LB", "MA"]` |
 
-`starts_word` matches the way Affinity's search matches names: `"Jan"` matches "Jane Doe" and "Mary-Jane"; `"ane"` doesn't. Person and company field values are compared by name ("Jane Doe", "Acme"), and `contains` / `contains_any` / `contains_all` on a person or company field is refused: use `starts_word`. An empty multi-value field (no items) counts as empty: `is_null` matches it, `is_not_null` doesn't.
+`starts_word` matches the way Affinity's search matches names: `"Jan"` matches "Jane Doe" and "Mary-Jane"; `"ane"` doesn't. Person and company field values are compared by name ("Jane Doe", "Acme"), or by id when the value is a number (`{"path": "fields.Owner", "op": "eq", "value": 26229794}`), and `contains` / `contains_any` / `contains_all` on a person or company field is refused: use `starts_word`. An empty multi-value field (no items) counts as empty: `is_null` matches it, `is_not_null` doesn't.
 
 The `--filter` text of `list export`, `company ls` and `person ls` is the same filter language: every condition means the same in both spellings.
 

{affinity_sdk-2.0.6 → affinity_sdk-2.0.7}/docs/public/reference/query-language.md

@@ -146,7 +146,7 @@ Example: {"from": "persons", "include": ["interactions"]}
 | `starts_with` | Starts with prefix (case-insensitive) | string |
 | `starts_word` | A word in the value starts with the text (case-insensitive) | string |
 
-`starts_word` matches the way Affinity's search matches names: `"Jan"` matches "Jane Doe" and "Mary-Jane"; `"ane"` doesn't. Person and company field values are compared by name ("Jane Doe", "Acme"); `contains`, `contains_any` and `contains_all` on a person or company field are refused (use `starts_word`).
+`starts_word` matches the way Affinity's search matches names: `"Jan"` matches "Jane Doe" and "Mary-Jane"; `"ane"` doesn't. Person and company field values are compared by name ("Jane Doe", "Acme"), or by id when the value is a number (`{"path": "fields.Owner", "op": "eq", "value": 26229794}`); `contains`, `contains_any` and `contains_all` on a person or company field are refused (use `starts_word`).
 
 #### Collection
 

{affinity_sdk-2.0.6 → affinity_sdk-2.0.7}/mcp/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "affinity-crm-mcp-unofficial",
   "description": "Affinity CRM workflows for Claude \u2014 meeting prep, pipeline review, warm intros, interaction logging, and relationship intelligence",
-  "version": "2.0.7",
+  "version": "2.0.8",
   "author": {
     "name": "Yaniv Golan",
     "email": "yaniv@golan.name"

{affinity_sdk-2.0.6 → affinity_sdk-2.0.7}/mcp/.claude-plugin/skills/query-language/SKILL.md

@@ -106,7 +106,7 @@ Structured query language for the `query` MCP tool. For simple lookups, prefer `
 Common operators: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `contains`, `starts_with`, `starts_word`, `in`, `between`, `is_null`, `is_not_null`, `has_any`, `has_all`
 
 - `starts_word`: a word in the value starts with the text, case-insensitive, the way Affinity's search matches names (`"Jan"` matches "Jane Doe" and "Mary-Jane"; `"ane"` doesn't).
-- Person and company field values are compared by name ("Jane Doe", "Acme"). `contains` / `contains_any` / `contains_all` on them is refused: use `starts_word`.
+- Person and company field values are compared by name ("Jane Doe", "Acme"), or by id when the value is a number. `contains` / `contains_any` / `contains_all` on them is refused: use `starts_word`.
 - An empty multi-value field counts as empty: `is_null` matches it, `is_not_null` doesn't.
 - Name any field by id with `fields.<field id>` (e.g. `fields.affinity-data-year-founded`). When two list fields share a name (e.g. Affinity's and Dealroom's "Year Founded"), `fields.<name>` is refused with an error listing the ids; use the id. Such fields come back keyed by id.
 

{affinity_sdk-2.0.6 → affinity_sdk-2.0.7}/mcp/.claude-plugin/skills/query-language/references/filter-operators.md

@@ -23,7 +23,7 @@ Complete reference for all filter operators in the Affinity query language.
 
 `starts_word` matches the way Affinity's search matches names: `"Jan"` matches "Jane Doe" and "Mary-Jane"; `"ane"` doesn't.
 
-Person and company field values are compared by name ("Jane Doe", "Acme"). `contains`, `contains_any` and `contains_all` on a person or company field are refused: use `starts_word`.
+Person and company field values are compared by name ("Jane Doe", "Acme"), or by id when the value is a number. `contains`, `contains_any` and `contains_all` on a person or company field are refused: use `starts_word`.
 
 ## Collection Operators
 

{affinity_sdk-2.0.6 → affinity_sdk-2.0.7}/mcp/.registry/commands.generated.json

@@ -2,11 +2,11 @@
   "_generated": {
     "warning": "DO NOT EDIT - This file is auto-generated",
     "generator": "tools/generate_mcp_command_registry.py",
-    "cliVersion": "2.0.6",
+    "cliVersion": "2.0.7",
     "sourceConfig": "mcp/.registry/mcp-commands.json"
   },
   "version": 1,
-  "cliVersion": "2.0.6",
+  "cliVersion": "2.0.7",
   "commands": [
     {
       "name": "company connections",
@@ -598,7 +598,8 @@
         "--filter": {
           "type": "string",
           "required": false,
-          "help": "Filter on company fields, applied by Affinity's search: 'field op value'. Ops: = != =~ =^ =$ > < >= <= starts_word. E.g., 'Stage = \"Seed\"'. Name search: --query."
+          "help": "Filter on company fields, applied by Affinity's search: 'field op value'. Ops: = != =~ =^ =$ > < >= <= starts_word. E.g., 'Stage = \"Seed\"'. Name search: --query. Repeatable: repeated values are ANDed.",
+          "multiple": true
         },
         "--max-results": {
           "type": "int",
@@ -2492,7 +2493,8 @@
         "--expand-filter": {
           "type": "string",
           "required": false,
-          "help": "Filter expanded entities (e.g., 'field=value' or 'field!=value')."
+          "help": "Filter expanded entities (e.g., 'field=value' or 'field!=value'). Repeatable: repeated values are ANDed.",
+          "multiple": true
         },
         "--expand-max-results": {
           "type": "int",
@@ -2522,7 +2524,8 @@
         "--filter": {
           "type": "string",
           "required": false,
-          "help": "Filter (field op value): Affinity's search applies what it can, the rest is checked locally. Quote multi-word: Status=\"Intro Meeting\"."
+          "help": "Filter (field op value): Affinity's search applies what it can, the rest is checked locally. Quote multi-word: Status=\"Intro Meeting\". Repeatable: repeated values are ANDed.",
+          "multiple": true
         },
         "--first-page-only": {
           "type": "flag",
@@ -4206,7 +4209,8 @@
         "--filter": {
           "type": "string",
           "required": false,
-          "help": "Filter on person fields, applied by Affinity's search: 'field op value'. Ops: = != =~ =^ =$ > < >= <= starts_word. E.g., 'Deals > 5'. Name/email search: --query."
+          "help": "Filter on person fields, applied by Affinity's search: 'field op value'. Ops: = != =~ =^ =$ > < >= <= starts_word. E.g., 'Deals > 5'. Name/email search: --query. Repeatable: repeated values are ANDed.",
+          "multiple": true
         },
         "--max-results": {
           "type": "int",

{affinity_sdk-2.0.6 → affinity_sdk-2.0.7}/mcp/CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to the xaffinity MCP server will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.8] - 2026-11-03
+
+Requires CLI 2.0.7 for repeated `--filter` / `--expand-filter` and for person and company fields
+matching by id.
+
+### Highlights
+
+`--filter` can be repeated (the conditions are ANDed), and person and company fields match by id;
+with an older CLI a repeated `--filter` is refused rather than silently narrowed to the last one.
+
+### Changed
+
+- `list export`, `company ls` and `person ls` take a repeated `--filter` (and `list export` a
+  repeated `--expand-filter`); the CLI ANDs the values. With a CLI older than 2.0.7, which keeps
+  only the last one, a repeated `--filter` / `--expand-filter` is refused with a hint to combine the
+  conditions with `&` or upgrade.
+- The tool descriptions, data model and query-language skill say person and company field values
+  match by name, or by id when the value is a number (`Owner = 26229794`).
+
+### Fixed
+
+- The `execute-read-command` description gave the filtered-cursor prefix as `xsearch1:`; it is
+  `xsearch2:`.
+
 ## [2.0.7] - 2026-10-14
 
 Requires CLI 2.0.5 (no new CLI requirements).

{affinity_sdk-2.0.6 → affinity_sdk-2.0.7}/mcp/COMPATIBILITY

@@ -1,8 +1,16 @@
 # mcp/COMPATIBILITY - CLI version requirements for this MCP server
 # Usage: source "${SCRIPT_DIR}/COMPATIBILITY"
 
-CLI_MIN_VERSION="2.0.5"
-CLI_MAX_VERSION="2.0.5"
+CLI_MIN_VERSION="2.0.7"
+CLI_MAX_VERSION="2.0.7"
+
+# MCP 2.0.8 requires CLI 2.0.7 for:
+# - Repeated `--filter` on `list export`, `company ls`, `person ls` and repeated
+#   `list export --expand-filter` (ANDed; the registry marks them repeatable). With an older CLI
+#   the gateway refuses the repeat.
+# - Person and company fields matching by id in `--filter` and `query` (the tool descriptions say
+#   so). This one can't be gated: an older CLI silently matches names only, so `Owner = <id>`
+#   returns no rows there.
 
 # MCP 2.0.7: no new CLI requirements (mcp-bash 1.9.6).
 

affinity_sdk-2.0.7/mcp/VERSION

@@ -0,0 +1 @@
+2.0.8

{affinity_sdk-2.0.6 → affinity_sdk-2.0.7}/mcp/lib/cli-gateway.sh

@@ -356,6 +356,16 @@ validate_argv() {
                         --hint "Remove duplicate $flag_name from argv"
                     return 1
                 fi
+                # A CLI older than 2.0.7 keeps only the last --filter / --expand-filter. Gated on
+                # the requirements minimum (2.0.7 or later), so a newer minimum still lets 2.0.7+ in.
+                if [[ "$primary_flag" == "--filter" || "$primary_flag" == "--expand-filter" ]] \
+                    && ! _xaffinity_cli_too_old reads \
+                    && ! version_gte "$_XAFFINITY_CLI_VERSION" "2.0.7"; then
+                    mcp_error "validation_error" \
+                        "Repeating $flag_name needs xaffinity CLI 2.0.7 or newer (this CLI uses only the last one)" \
+                        --hint "Combine the conditions with & in one $flag_name, or upgrade: $_XAFFINITY_CLI_UPGRADE"
+                    return 1
+                fi
             fi
             provided_flags="$provided_flags $primary_flag"
 

{affinity_sdk-2.0.6 → affinity_sdk-2.0.7}/mcp/resources/data-model/data-model.md

@@ -82,7 +82,7 @@ opportunity get "Big Deal Q1"
 ```bash
 list export Dealflow --filter 'Status="New"'
 ```
-Use when you know the field name and value. Affinity's search applies the conditions on list fields it can answer, so only matching entries are downloaded; the whole filter is then checked again locally.
+Use when you know the field name and value. Affinity's search applies the conditions on list fields it can answer, so only matching entries are downloaded; the whole filter is then checked again locally. Repeat `--filter` to add conditions (the values are ANDed); for OR use `|` inside one value.
 
 ### --saved-view (Pre-Configured Views)
 ```bash
@@ -519,7 +519,7 @@ CLI commands use `--filter 'field op "value"'` syntax:
 Common operators: `=` `!=` `=~` (contains) `=^` (starts) `=$` (ends) `>` `<` `>=` `<=` `starts_word`
 
 - `starts_word`: a word in the value starts with the text, case-insensitive, the way Affinity's search matches names ("Jan" matches "Jane Doe" and "Mary-Jane"; "ane" doesn't).
-- Person and company field values are compared by name ("Jane Doe", "Acme"); `contains` on them is refused, use `starts_word`.
+- Person and company field values are compared by name ("Jane Doe", "Acme"), or by id when the value is a number (`Owner = 26229794`); `contains` on them is refused, use `starts_word`.
 - An empty multi-value field counts as empty: `is null` matches it, `is not null` doesn't.
 
 For the `query` tool, use JSON operators (`eq`, `contains`, `starts_word`, `in`, etc.) - see `xaffinity://query-guide` for complete reference. The `--filter` text and the `query` `where` are the same filter language; every condition means the same in both.

{affinity_sdk-2.0.6 → affinity_sdk-2.0.7}/mcp/server.d/requirements.json

@@ -13,7 +13,7 @@
     },
     {
       "name": "xaffinity",
-      "minVersion": "2.0.5",
+      "minVersion": "2.0.7",
       "check": "xaffinity --version",
       "installHint": "pip install affinity-sdk"
     }

{affinity_sdk-2.0.6 → affinity_sdk-2.0.7}/mcp/server.d/server.meta.json

@@ -1,7 +1,7 @@
 {
   "name": "xaffinity-mcp",
   "title": "xaffinity MCP",
-  "version": "2.0.7",
+  "version": "2.0.8",
   "description": "MCP server for Affinity CRM - workflow management, entity lookup, relationship intelligence using xaffinity CLI",
   "env": {
     "MCPBASH_TOOL_ENV_MODE": "allowlist",