Add MCP payload/response reduction (read + write) and verification fixes

changes/+mcp-expand-strips-media.bugfix

@@ -0,0 +1 @@
+Fix `expand` reintroducing avatar/logo fields that `strip_media` otherwise removes from the rest of the response - an expanded block now goes through the same strip pass as everything else.

changes/+mcp-invited-by-collapse.bugfix

@@ -0,0 +1 @@
+Fix `invited_by` (on membership records) escaping the `payload="compact"`/`"minimal"` collapsing every other user/project block gets, since it doesn't end in `_extra_info`.

changes/+mcp-minimal-field-set-fixes.bugfix

@@ -0,0 +1 @@
+Fix the MCP server's `minimal` payload projection: milestones now include `project_extra_info.name`/`.slug`, user stories now include the bare `assigned_users` id list, and both user stories and issues drop the redundant per-project `status` id in favour of the cross-project-comparable `status_extra_info.name`.

changes/+mcp-payload-reduction.feature

@@ -0,0 +1 @@
+Add opt-in payload-reduction parameters (`payload`, `fields`, `strip_media`, `expand`, `resolve_assigned_users`, `strict_filters`) to the MCP server's read tools, shrinking oversized responses on request while leaving default behaviour byte-for-byte unchanged.

changes/+mcp-resolve-assigned-users-field-name-fix.bugfix

@@ -0,0 +1 @@
+Fix `resolve_assigned_users` always returning `null` display names by reading the correct `full_name` field from Taiga membership records instead of the nonexistent `full_name_display`.

changes/+mcp-surface-real-error-messages.bugfix

@@ -0,0 +1 @@
+Fix the MCP server swallowing anticipated failure messages (a `strict_filters` violation, a stale/missing `version` on a single-item `update_*` call) into a generic "Error executing tool" with no detail. These now surface the real message, matching what `update_work_items` already returned per-row for the same failures.

changes/+mcp-write-payload-reduction.feature

@@ -0,0 +1 @@
+Add opt-in `return_representation` (`full`/`minimal`/`none`) to the MCP server's write tools, and a new `update_work_items` batch-write tool, shrinking write-response payloads and collapsing many-item write sequences into one call while leaving default behaviour byte-for-byte unchanged.

docs/mcp.rst

@@ -153,6 +153,28 @@ not in any particular project. Check it went through with:
 
     claude mcp get taiga
 
+.. warning:: **Some MCP clients require every declared parameter to be passed
+             explicitly, even ones with a documented default.** Every
+             parameter below that shows a default (e.g. ``payload="full"``,
+             ``strict_filters=False``) is genuinely optional in this server's
+             own JSON schema and its runtime validation - confirmed by
+             calling the real server directly over the MCP protocol,
+             omitting those parameters entirely. Some MCP clients have
+             nonetheless been observed rejecting the call outright
+             (``-32602``, wording resembling Zod's ``nonoptional`` schema
+             check) when a parameter carrying a schema-level ``default`` is
+             omitted - for *every* such parameter, not just the ones this
+             server added recently: `include_user_stories` on
+             ``list_milestones`` (which predates this server's payload-
+             reduction work) triggers the same rejection on an affected
+             client. This is a property of that client's own schema
+             validation, not of this server, and there is no available hook
+             in this server's dependencies to change what gets emitted to
+             work around it. **If your client exhibits this, pass every
+             parameter explicitly on every call to an affected tool** -
+             there is no way to make a client-side check like this
+             optional from the server side.
+
 ****************
 Available tools
 ****************
@@ -219,6 +241,10 @@ Available tools
     Link a user story to an epic, identifying both by their per-project ref
     numbers (primary) or by database id (secondary, see below).
 
+``update_work_items``
+    Update a batch of user stories/tasks/issues/epics in one call - see the
+    tip below for the exact shape and its non-atomic semantics.
+
 .. important:: ``get_user_story``/``get_task``/``get_issue``/``get_epic`` and
          their ``update_*``/``delete_*`` counterparts take a ``project`` (id
          or slug) and a ``ref`` - the per-project sequential number Taiga
@@ -237,11 +263,23 @@ Available tools
          you already hold the database id (for example from a prior tool
          response), not a ref.
 
-``list_milestones``, ``get_milestone``, ``create_milestone``, ``delete_milestone``
-    Manage milestones (sprints).
+``list_milestones``, ``get_milestone``
+    List/get milestones (sprints), optionally scoped to a project (``list_milestones``
+    only). Each milestone embeds its full ``user_stories`` - pass
+    ``include_user_stories=False`` to strip that (potentially large) field from the
+    result. This embedded route is the cheapest way to get every story in a sprint in
+    one call (pair it with ``fields=["id", "user_stories.ref", ...]`` to shrink it
+    further), but Taiga's embedded story serializer carries only the single primary
+    ``assigned_to`` - it has no ``assigned_users`` key at all, so multi-assignee data is
+    unavailable through this route regardless of ``fields``/``resolve_assigned_users``.
+    For complete multi-assignee data, fetch those stories individually with
+    ``list_user_stories``/``get_user_story`` instead.
+
+``create_milestone``, ``delete_milestone``
+    Create/delete milestones (sprints).
 
 ``list_wiki_pages``, ``get_wiki_page``, ``create_wiki_page``, ``update_wiki_page``
-    Manage wiki pages.
+    Manage wiki pages, optionally scoped to a project.
 
 .. tip:: Call ``get_project`` first when creating or updating an entity - it
          returns every status/priority/severity/points id valid for that
@@ -252,6 +290,168 @@ Available tools
          through further pages, and ``order_by`` (e.g. ``-created_date``) to
          control ordering - for example to fetch the most recent items first.
 
+.. tip:: Every ``list_*``/``get_*`` tool that returns a full resource - projects,
+         user stories, tasks, issues, epics, milestones, memberships, wiki pages -
+         accepts four further parameters to shrink an oversized response, all
+         opt-in (the default reproduces today's full response exactly):
+
+         - ``payload``: ``"full"`` (default, untouched) / ``"compact"`` (drops
+           avatar/logo URLs and shrinks every ``*_extra_info`` block to its id
+           plus display name) / ``"minimal"`` (only the fields a sprint-planning
+           report actually reads - currently defined for user stories, issues,
+           epics and milestones; for any other resource ``"minimal"`` behaves
+           the same as ``"compact"`` for now). The exact field set kept by
+           ``payload="minimal"`` per entity (``MINIMAL_FIELDS`` in
+           ``taiga/mcp_server/serialize.py``):
+
+           - ``milestone`` (``list_milestones``/``get_milestone``): ``id``,
+             ``name``, ``slug``, ``project``, ``project_extra_info.name``,
+             ``project_extra_info.slug``, ``estimated_start``,
+             ``estimated_finish``, ``closed``. The board's name/slug are
+             included alongside the bare ``project`` id specifically so a
+             cross-project report can display and link each board without a
+             second call.
+           - ``userstory`` (``list_user_stories``/``get_user_story``/
+             ``get_user_story_by_id``): ``id``, ``ref``, ``subject``,
+             ``version``, ``milestone``, ``milestone_name``,
+             ``status_extra_info.name``, ``status_extra_info.is_closed``,
+             ``is_closed``, ``finish_date``, ``is_blocked``,
+             ``assigned_to_extra_info.full_name_display``,
+             ``assigned_users``, ``epics.ref``, ``assigned_users_extra_info``.
+             The numeric ``status`` id is deliberately omitted - it is a
+             per-project id, not comparable across boards, and redundant
+             alongside ``status_extra_info.name``. ``assigned_users`` (the
+             bare secondary-assignee id list) is included so ``minimal``
+             never silently under-reports who is assigned; pair it with
+             ``resolve_assigned_users=True`` for names, not just ids.
+           - ``issue`` (``list_issues``/``get_issue``/``get_issue_by_id``):
+             same as ``userstory`` minus ``assigned_users``/
+             ``assigned_users_extra_info`` (issues have no ``assigned_users``).
+           - ``epic`` (``list_epics``/``get_epic``/``get_epic_by_id``):
+             ``id``, ``ref``, ``subject``, ``status_extra_info.name``,
+             ``project``.
+         - ``fields``: an explicit list of field paths, overriding ``payload``
+           entirely, e.g. ``["ref", "subject", "status_extra_info.name"]``. A
+           dotted path keeps only that nested key; if the value at that point is
+           itself a list (e.g. a story's ``epics``), the remaining path is
+           applied to every element, e.g. ``"epics.ref"``.
+         - ``strip_media``: ``True``/``False``, overriding whether avatar/logo
+           URLs (``photo``, ``big_photo``, ``gravatar_id``, ``logo_small_url``)
+           are stripped, regardless of ``payload``. These carry rotating
+           signed-URL signatures, so leaving them in also defeats prompt caching
+           between otherwise-identical calls.
+         - ``expand``: a list of top-level block names to add back at full
+           detail on top of a reduced ``payload``, e.g.
+           ``payload="minimal", expand=["assigned_to_extra_info"]``.
+
+         ``list_user_stories``, ``get_user_story`` and ``get_user_story_by_id``
+         additionally accept ``resolve_assigned_users=True``: ``assigned_users``
+         is a bare list of user ids with no names anywhere in the default
+         payload, so this resolves them into
+         ``assigned_users_extra_info: [{"id", "full_name_display"}, ...]`` via
+         that story's project memberships. Off by default because, unlike the
+         four parameters above, it adds a request rather than removing one (one
+         ``list_memberships`` call per distinct project touched).
+
+         Every ``list_*`` tool additionally accepts ``strict_filters=False``
+         (default): pass ``True`` to raise immediately if ``filters`` nests one
+         of this server's own parameter names by mistake (e.g.
+         ``filters={"include_user_stories": False}``) instead of silently
+         returning an unfiltered response - Taiga's REST backend ignores
+         unknown query parameters with no error either way, which measured as
+         much as a 24x size regression with no signal that anything went wrong.
+
+         **`strict_filters` is a narrow guard, not a filter validator.** It
+         only catches this server's own parameter names appearing inside
+         `filters` by mistake. It gives **no protection** against a
+         misspelled or unsupported Taiga filter key (e.g. `milestone__in`,
+         which Taiga silently ignores rather than erroring - see the note
+         below) - that class of mistake returns a normal-looking but wrong
+         result set with no error either way, `strict_filters` or not. Any
+         filter-based narrowing this server accepts must be re-asserted
+         client-side (e.g. checking the returned items' own fields match
+         what the filter was supposed to select) rather than trusted purely
+         because the call didn't raise.
+
+.. note:: ``filters`` is forwarded as-is to Taiga's REST endpoint, so
+          server-side filtering - e.g. ``list_milestones(filters={"closed":
+          False, "estimated_start__lte": "2026-09-20"})`` - already works
+          today with no MCP-side change, for any lookup Taiga's own API
+          filter backend supports. Which lookups that includes is a property
+          of the Taiga server you're talking to, not of this client. Filters
+          verified against a live instance: ``closed`` (milestones),
+          ``page_size`` (all ``list_*`` tools, caps at 100 per page regardless
+          of the value requested), ``estimated_start__lte``/
+          ``estimated_finish__gte`` (milestones - returns exactly the boards
+          whose window overlaps the given range), and ``milestone`` as a
+          single int (user stories, issues). A comma-separated list of ids is
+          **not** supported the same way for either ``milestone`` (errors) or
+          ``milestone__in`` (silently ignored, returning an arbitrary unrelated
+          page of results rather than an error) - do not rely on either form;
+          fetch each milestone's items with its own call instead. A Python
+          *list* value (e.g. ``filters={"milestone": [1444, 1446]}``) is a
+          third failure mode, and the most dangerous of the three: it returns
+          a small, clean, plausible-looking result set - but only for the
+          *last* id in the list, with every other id's items silently
+          dropped. This client sends the list correctly (as repeated query
+          parameters, standard ``requests`` behaviour); the collapse happens
+          in Taiga's own REST backend, which appears to read only the last
+          value of a repeated parameter (standard Django ``QueryDict.get()``
+          semantics) - nothing on this client's side can change that. Do not
+          pass a list as a filter value for any key; fetch each id with its
+          own call instead. Separately,
+          ``project=None`` (the default on item-listing tools) already returns
+          results across every project the caller can see - no project scope
+          is required for a cross-project item query.
+
+.. note:: Taiga's own data can disagree with itself on closure state: the
+          top-level ``is_closed`` field and ``status_extra_info.is_closed``
+          are two independently-set signals and have been observed to
+          contradict each other on the same item (e.g. ``is_closed: true``
+          while the status is actually "In progress" and
+          ``status_extra_info.is_closed: false``). This is a property of the
+          underlying Taiga data, not a serialization defect in this server.
+          ``status_extra_info.name``/``status_extra_info.is_closed`` are the
+          more reliable signals if the two disagree - they come directly from
+          the status Taiga's UI itself displays, rather than a separately
+          maintained flag on the item.
+
+.. tip:: Every ``create_*``/``update_*`` tool accepts ``return_representation``
+         (``"full"`` default / ``"minimal"`` / ``"none"``), opt-in, to shrink
+         what a write echoes back:
+
+         - ``"full"`` (default): the complete written resource, exactly as
+           before.
+         - ``"minimal"``: ``{"id", "ref" (only if the entity has one),
+           "version", ...the fields you passed in ``fields``}`` - never the
+           tool's own required arguments (``subject``, ``status``, etc.),
+           since you already know those - only ``id``/``ref``/``version`` are
+           genuinely new information a write produces.
+         - ``"none"``: ``{"ok": true, "id", "ref" (if any), "version"}`` - a
+           bare acknowledgement.
+
+         On ``update_*`` tools, ``"minimal"``/``"none"`` also skip the
+         re-fetch these tools otherwise perform after writing - a latency
+         win, not just a smaller response. ``version`` is not a separate
+         parameter on any ``create_*``/``update_*`` tool: if Taiga needs it
+         for optimistic locking, pass it inside ``fields`` yourself, exactly
+         as today. (``set_custom_attribute_value``/``set_custom_attribute_value_by_id``
+         are the exception - see the note above on their own, unrelated
+         ``version`` sequence.)
+
+.. tip:: ``update_work_items(project, updates, return_representation="full")``
+         updates a batch of user stories/tasks/issues/epics in one call.
+         Each entry in ``updates`` is
+         ``{"entity_type": "user_story"|"task"|"issue"|"epic", "ref": <int>,
+         "fields": {...}}``. **Not atomic** - items are processed in order,
+         each succeeds or fails independently, and one failure never rolls
+         back or blocks any other item. Returns one result row per input
+         item, in the same order (zip ``updates`` with the result to match
+         them up); a failed item's row is
+         ``{"status": "error", "entity_type", "ref", "error"}``. Wiki pages
+         aren't supported here (no per-project ``ref``) - use
+         ``update_wiki_page`` directly.
+
 ****************
 Security notes
 ****************

pyproject.toml

@@ -55,7 +55,7 @@ commit = true
 message = "Release {new_version}"
 commit_args = "--no-verify"
 tag = false
-current_version = "1.3.4.dev1"
+current_version = "2.0.0b6"
 parse = """(?x)
     (?P<major>[0-9]+)
     \\.(?P<minor>[0-9]+)

taiga/__init__.py

@@ -6,7 +6,7 @@
 Taiga Python API library
 """
 
-__version__ = "1.3.4.dev1"
+__version__ = "2.0.0.b6"
 __author__ = "Nephila"
 __license__ = "MIT"
 __all__ = ["TaigaAPI"]