fix: improve custom field handling in JIRA create/update operations with enhanced error diagnostics

[mliq]

Note

If you would like to test / use this version, you can pull it from ghcr.io/mliq/mcp-atlassian:latest .
Since the owner of this repo has been MIA for 3 months, I'm open to moving development to my fork at https://github.com/mliq/mcp-atlassian.

Description

This PR improves custom field handling in JIRA create/update operations with enhanced error diagnostics, building upon @4erdenko's custom field parsing fixes from PR #629 and addressing multiple open issues including improved error propagation (#649) and informative error messages (#486).

Custom fields in JIRA operations were failing due to validation errors when additional_fields was passed as JSON strings from XML-to-JSON converters. This work extends the parsing fix to update_issue operations and adds comprehensive error handling to help diagnose custom field formatting issues.

Fixes: #649
Fixes: #486
Related to: #629 (builds upon this work)
Related to: #630 (improved diagnostics for field formatting issues)

Changes

• Extended custom field JSON string parsing from jira_create_issue to jira_update_issue operations (building on @4erdenko's work in feat: parse JSON additional_fields (#1) #629)
• Implemented structured error handling with detailed JIRA API response parsing for custom field failures
• Added individual field update fallback mechanism when batch custom field operations fail
• Added basic field format analysis with suggestions for common custom field patterns
• Replaced exceptions with structured JSON error responses for better MCP client integration
• Added test coverage for custom field handling scenarios

Testing

• Unit tests added/updated for custom field JSON string parsing in both create and update operations
• Tests pass for custom field error handling scenarios
• Manual checks performed: Tested custom field validation, error response structure, and fallback mechanisms

Checklist

• Code follows project style guidelines (linting passes)
• Tests added/updated for changes
• All tests pass locally
• Documentation updated (if needed) - No documentation changes made

Technical Implementation

Problem Solved

External clients (e.g., Anthropic Claude, Cursor) emit tool calls in XML format that get converted to JSON-RPC. During this conversion, additional_fields (used for JIRA custom fields) gets wrapped in quotes as a JSON string instead of remaining as a native object, causing Pydantic validation failures.

Core Features

• Custom Field Parsing Extension: Extended @4erdenko's additional_fields JSON string parsing from create to update operations
• Structured Error Handling: Comprehensive JIRA API error response parsing with detailed error extraction for custom field failures
• Fallback Logic: Individual custom field update attempts when batch operations fail
• Basic Field Analysis: Rule-based pattern matching that suggests format fixes for common custom field patterns:
  • Boolean-like strings (→ object format)
  • Custom fields (→ select object format)
  • User fields (→ user object format)
  • Numeric values (→ string format)
  • Large numbers (→ ranking field guidance)
• MCP Integration: Structured JSON error responses instead of exceptions for better client handling

Files Modified

• src/mcp_atlassian/servers/jira.py - Core functionality enhancements (351 lines added)
• tests/unit/servers/test_jira_server.py - Test coverage for custom field handling (109 lines added)
• uv.lock - Dependency updates from development environment

Credits

This work builds upon the custom field parsing foundation initially implemented by @4erdenko in PR #629.

Co-authored-by: 4erdenko [email protected]

[vicalca]

I tried the latest image and works like a charm. I will follow your fork for future improvements if the developer does not come back. Excellent work.

[yekkhan-liftoff]

thanks @mliq , this works like magic! I have been debugging for the past few days, modified my prompts, switched from claude code action to gemini cli, none of it worked, didn't expect the problem to be at atlassian mcp server side. Thanks again!

[github-actions]

This pull request has been automatically marked as stale because it has not had recent activity for 14 days. It will be closed if no further activity occurs. Please leave a comment or remove the 'stale' label if you believe this PR is still relevant. Thank you for your contributions!