fix(mcp): link epics correctly and fill in versions on writes

[yakky]

Description

Fixes the Taiga MCP server in two ways:

• Epic.add_related_user_story now sends epic, which Taiga requires on
  related_userstories; link_epic_user_story / link_epic_user_story_by_id
  never linked anything before and hid the real error. Both tools now raise
  ToolError with the real message.
• Writes no longer fail when version is omitted: single-item update_* tools
  and update_work_items use the fetched item's version (an explicit version
  wins); set_custom_attribute_value / _by_id take an optional version
  defaulting to the current custom-attributes-values version
  (CustomAttributeResource.set_attribute follows the same default instead of 1).

Verified against a real Taiga board (epic link, update without version, custom
attribute without version), test data removed.

References

Fix #278

Checklist

• I have read the contribution guide
• Code lint checked via inv lint
• changes file included (see docs)
• Usage documentation added in case of new features (docs/mcp.rst updated)
• Tests added

Use of AI

Model: Claude Sonnet 5.5, via Claude Code. Scope: root-cause analysis, implementation and tests.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.22%. Comparing base (16acdb7) to head (6a1f9c5).

Additional details and impacted files

@@                             Coverage Diff                             @@
##           feature/267-mcp-write-payload-reduction     #279      +/-   ##
===========================================================================
+ Coverage                                    98.18%   98.22%   +0.04%     
===========================================================================
  Files                                           12       12              
  Lines                                         1540     1576      +36     
  Branches                                       146      151       +5     
===========================================================================
+ Hits                                          1512     1548      +36     
  Misses                                          19       19              
  Partials                                         9        9              

Flag	Coverage Δ
unittests	98.22% <100.00%> (+0.04%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[coveralls]

coverage: 98.794% (+0.03%) from 98.766% — bugfix/278-mcp-epic-link-and-version-fixes into feature/267-mcp-write-payload-reduction

[Copilot]

Copilot review overview

🟡 Changes recommended

Custom-attribute writes can still use stale cached versions and fail after another client edits the resource.

Review effort: Balanced
Findings: 1

Open (1)

• Bypass stale attribute cache when deriving default version · New

What changed in this PR

Addresses #278 by correcting epic linking and adding automatic version defaults for Taiga MCP writes.

Changes:

• Includes the epic ID in link requests and exposes underlying errors.
• Defaults omitted write versions while preserving explicit values.
• Adds regression tests, documentation, and release notes.

File	Description
tests/​test_mcp_server.py	Tests version defaults and link errors.
tests/​test_epics.py	Checks the required epic ID payload.
tests/​test_custom_attributes.py	Tests default and explicit versions.
taiga/​models/​models.py	Updates epic payloads and custom-attribute version defaults.
taiga/​mcp_server/​server.py	Adds version handling and link error reporting.
docs/​mcp.rst	Documents optional write versions.
changes/​278.bugfix.2	Records automatic version handling.
changes/​278.bugfix.1	Records improved link error reporting.
changes/​278.bugfix	Records the epic-link payload correction.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🟡 Changes recommended

Project lookup failures bypass batch error handling, aborting the call instead of returning per-item results.

Review effort: Balanced
Findings: 1

Open (1)

• Resolve projects per item to preserve error handling and continuation · New

Resolved since last review (1)

• Bypass stale attribute cache when deriving default version

[Copilot]

Copilot review overview

🟢 Approval recommended

Remaining feedback concerns minor documentation clarifications; no blocking regression was established.

Review effort: Balanced
Findings: 1

Open (1)

• Document updated status with readback_error after successful writes · New

Resolved since last review (1)

• Resolve projects per item to preserve error handling and continuation