fix: migrate to new Jira /search/jql API endpoints for Cloud only #750

clx-jlmoreno · 2025-11-05T18:15:35Z

Description

Resolves the Jira search API deprecation issue by migrating to the new /search/jql endpoints for Cloud only.

Fixes #658 - Addresses the deprecation of /rest/api/2|3/search endpoints (effective August 1st, 2025).

Solution Implementation

Following the official Adaptavist migration guide, this PR implements Cloud-only migration:

✅ Cloud vs Server/DC Differentiation

Cloud: Uses new POST /rest/api/3/search/jql endpoint
Server/DC: Continues using existing /rest/api/*/search endpoints
Detection: Based on config.is_cloud setting

✅ API Migration (Cloud Only)

Old: GET/POST /rest/api/2|3/search
New: POST /rest/api/3/search/jql
Payload: Changed from query params to JSON body

✅ Pagination Update (Cloud Only)

Cloud: nextPageToken with isLast flag
Server/DC: Continues using startAt parameter

✅ Response Format Handling (Cloud Only)

Default: Issue IDs only (["PROJ-123", "PROJ-124"])
With fields: Full issue objects (backward compatible)
Auto-detection: Handles both formats seamlessly

✅ Server/DC Compatibility Maintained

No breaking changes for Server/DC installations
Identical behavior as before for on-premise deployments
MCP contract preserved across all deployment types

Files Changed

src/mcp_atlassian/jira/search.py - Cloud/Server differentiation logic
src/mcp_atlassian/models/jira/search.py - Response parsing for both formats
src/mcp_atlassian/models/jira/issue.py - ADF description handling
tests/unit/jira/test_search.py - Updated for both Cloud/Server scenarios

Testing

✅ Live Environment Tested

Jira Cloud: crealogixme.atlassian.net
Project: ARQBE
Epic: ARQBE-11
Issue: ARQBE-525

✅ Unit Test Coverage

383 Jira tests pass
24 search-specific tests pass
Both Cloud and Server/DC paths tested

Impact

Zero breaking changes for existing users
Server/DC: Continues working exactly as before
Cloud: Future-proof until August 1st, 2025 deadline
Performance: Improved pagination for Cloud
Compatibility: Works with both Cloud and Server/DC

clx-jlmoreno · 2025-11-05T18:26:33Z

Update: Squashed commits into a single clean commit for easier review.

✅ Changes consolidated:

Main Jira Cloud API migration fix
Code formatting and linting compliance fixes
Single commit with comprehensive message

The PR is now ready for review with a clean git history! 🚀

eciuca · 2025-11-10T06:44:04Z

We need someone to review and merge this, please!

michaelper22 · 2025-11-18T07:10:57Z

Would be very excited to see either this or #731 merged 🙏

ChadNedzlek · 2025-11-19T00:26:12Z

Same. The MCP is completely broken for me without this...

clx-jlmoreno · 2025-11-20T11:19:49Z

If you need the feature, until is merged or not, you can build or test this pull request from https://github.com/clx-jlmoreno/mcp-atlassian/tree/fix/jira-search-api-deprecation-658 branch, building the code and using your own docker image built.

…ion test suite MAJOR IMPROVEMENTS TO TEST INFRASTRUCTURE AND API COMPATIBILITY ## Protocol and Library Upgrades - Upgrade to FastMCP library for improved MCP protocol handling - Deprecate legacy trio protocol support in favor of asyncio-based testing - Remove @pytest.mark.anyio decorators and trio backend dependencies - Standardize on pytest.mark.asyncio for consistent async test execution - Improve test fixture scoping and eliminate circular dependency issues ## Core Test Fixes (Previously Failing Due to Deprecated API Patterns) - Fix startAt → start_at parameter consistency across all pagination tests - Update test payload parsing to handle paginated API responses with metadata structure - Replace deprecated jira_get_epic_issues tool with jira_search using JQL queries - Enhance skip conditions for insufficient test data scenarios (len(results1["issues"]) <= 1) - Verify pagination functionality across both Jira Cloud and Data Center environments ## New Features and Enhancements - Add ADF (Atlassian Document Format) parser for comment content processing - Create comprehensive MCP application integration tests (19 tests) - Add Cloud/DC differentiation tests for issue comments - Enhance search functionality with improved error handling and compatibility - Implement robust cross-environment testing framework with proper flag usage ## Test Structure Consolidation and Organization - MOVE: tests/test_real_api_validation.py → tests/integration/test_real_api_tool_validation.py - PRESERVE: All 57 working validation tests with updated fixes intact - FIX: test_real_api.py to use --integration flag consistently (11 tests now working) - CREATE: Comprehensive test documentation in tests/README.md - UPGRADE: Test infrastructure to use FastMCP and modern async patterns ### Complete Integration Test Suite (87 tests total): 1. **test_mcp_application.py** (19 tests) - Comprehensive MCP functionality validation - Search functionality, issue operations, comment handling, Epic management - ADF parsing, environment consistency, project operations, agile boards - Batch operations, error handling, pagination behavior differences 2. **test_real_api.py** (11 tests) - Direct API client integration testing - Complete issue lifecycle (CRUD operations) - Attachment upload/download, bulk issue creation, rate limiting - Page lifecycle, page hierarchy, CQL search, large content handling - Cross-service Jira-Confluence integration 3. **test_real_api_tool_validation.py** (57 tests) - FastMCP tool validation - All original test fixes preserved and working - Comprehensive API validation scenarios across Cloud/DC environments - Tool-specific validation with proper error handling ## Technical Implementation Details - Enhanced JQL search with parent queries: parent = "{epic_key}" ORDER BY created ASC - Fixed API response parsing: assert isinstance(results.get("issues"), list) - Improved skip logic for pagination: len(results1["issues"]) <= 1 or len(results2["issues"]) == 0 - Confirmed API compatibility: Cloud (POST /rest/api/3/search/jql) vs DC (GET /rest/api/2/search) - Standardized integration test execution with --integration flag - Advanced error handling patterns for robust API interactions - Modernized async test patterns with FastMCP library integration ## Development Environment Improvements - Add .amazonq/ and AmazonQ.md to .gitignore (exclude development context files) - Enhance .env.example with comprehensive integration testing configuration: * JIRA_TEST_ISSUE_KEY, JIRA_TEST_EPIC_KEY, JIRA_TEST_PROJECT_KEY * JIRA_TEST_BOARD_ID, JIRA_TEST_SPRINT_ID for agile testing * CONFLUENCE_TEST_PAGE_ID, CONFLUENCE_TEST_SPACE_KEY * TEST_PROXY_URL for proxy-related integration tests - Update tests/README.md with clear documentation of test purposes and execution - Upgrade dependency management with FastMCP library integration ## Execution and Compatibility Verification - ALL 87 integration tests verified working in both environments: * Server/DC (.env.test): All tests pass * Cloud (.env.realcloud): All tests pass - Consistent flag usage: --integration for comprehensive integration tests - Proper test separation: Each file covers distinct, non-overlapping functionality - Performance: ~22s (Server/DC), ~29s (Cloud) for direct API tests - FastMCP library compatibility verified across all test scenarios ## Files Modified (22): - Core functionality: jira/epics.py, jira/issues.py, jira/search.py (+321 lines) - Models: Enhanced comment.py, issue.py, search.py with better parsing - Tests: Comprehensive reorganization and consolidation with full documentation - Configuration: Updated .gitignore, .env.example, pyproject.toml, uv.lock - Dependencies: FastMCP library integration and trio protocol deprecation ## Files Created (4): - src/mcp_atlassian/models/jira/adf_parser.py (ADF content parser) - tests/integration/test_mcp_application.py (comprehensive MCP functionality tests) - tests/unit/models/test_adf_parser.py (ADF parser unit tests) - tests/unit/models/test_issue_comment_cloud_differentiation.py (Cloud/DC tests) ## Impact and Results - Previously failing tests now fully functional across both platforms - Modern FastMCP library integration improves test reliability and performance - Deprecated trio protocol removed in favor of standardized asyncio patterns - Comprehensive test coverage demonstrating proper pagination and API compatibility - Clean, organized test structure with clear documentation and consistent execution - Verified Cloud/DC environment compatibility for all integration scenarios - Enhanced developer experience with proper test categorization and documentation ## Statistics - Total changes: +4064 insertions, -1540 deletions across 25 files - Integration test coverage: 87 tests across 3 properly organized files - Environment compatibility: 100% test pass rate in both Cloud and Server/DC - Documentation: Complete test suite documentation with execution examples - Library upgrade: FastMCP integration with deprecated trio protocol removal This comprehensive update resolves all failing test issues while establishing a robust, well-organized, and fully documented integration test framework with modern FastMCP library integration and deprecated protocol cleanup.

sooperset · 2025-11-26T16:16:28Z

Sorry for the late review @clx-jlmoreno!

First, thank you for putting together this comprehensive migration work. I just tested against Jira Cloud and confirmed the v2 API is already returning deprecation errors - your timing is spot on.

However, this PR has a lot of scope beyond the search fix that I need to review separately:

FastMCP upgrade (2.3.4 → 2.9.0)
Trio removal
mypy configuration changes
ADF parser module
Integration test restructure

Given the urgency (v2 is already deprecated), I extracted just the search API v3 migration into PR #769 and will ship that first to unblock Cloud users.

Could you split this PR into smaller pieces for the remaining changes? Something like:

FastMCP + trio changes
Integration test improvements
ADF parser (if still needed after the search fix)

I really appreciate your work on this - sorry again for the delay in reviewing!

clx-jlmoreno · 2025-11-26T21:57:08Z

@sooperset The * FastMCP upgrade (2.3.4 → 2.9.0) * Trio removed *. ADF parser module Are all related pack required to support the management of comments in Jira cloud properly. Your simplified commit should fail searching and extracting comments content fields without these changes. The ADF structure is the container of contents (comments). The old FastMCP has issues with that ... His upgrade notes indicates the deprecation of trio features . The discovery of this issue/need was found during the upgrade and generation of more realistic integration tests!. * Integration test restructure I will search for personal time to split the remain work in two but all are related! With this comment hopefully you understand why the original merge was too big.

clx-jlmoreno mentioned this pull request Nov 5, 2025

[Bug]: jira_search fails #658

Open

2 tasks

clx-jlmoreno force-pushed the fix/jira-search-api-deprecation-658 branch from 12f85d7 to f3a73f1 Compare November 5, 2025 18:25

clx-jlmoreno force-pushed the fix/jira-search-api-deprecation-658 branch from f3a73f1 to 0fd7518 Compare November 20, 2025 19:45

villelahdenvuo mentioned this pull request Nov 21, 2025

Upgrade Fast MCP dependency #763

Closed

7 tasks

refactor of test documentation

36e4be0

clx-jlmoreno force-pushed the fix/jira-search-api-deprecation-658 branch from e073d76 to 36e4be0 Compare November 21, 2025 08:31

sooperset mentioned this pull request Nov 26, 2025

fix(jira): migrate Cloud search to v3 API endpoint #769

Merged

4 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix: migrate to new Jira /search/jql API endpoints for Cloud only #750

fix: migrate to new Jira /search/jql API endpoints for Cloud only #750

Uh oh!

clx-jlmoreno commented Nov 5, 2025

Uh oh!

clx-jlmoreno commented Nov 5, 2025

Uh oh!

eciuca commented Nov 10, 2025

Uh oh!

michaelper22 commented Nov 18, 2025

Uh oh!

ChadNedzlek commented Nov 19, 2025

Uh oh!

clx-jlmoreno commented Nov 20, 2025

Uh oh!

sooperset commented Nov 26, 2025

Uh oh!

clx-jlmoreno commented Nov 26, 2025 via email •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

fix: migrate to new Jira /search/jql API endpoints for Cloud only #750

Are you sure you want to change the base?

fix: migrate to new Jira /search/jql API endpoints for Cloud only #750

Uh oh!

Conversation

clx-jlmoreno commented Nov 5, 2025

Description

Solution Implementation

✅ Cloud vs Server/DC Differentiation

✅ API Migration (Cloud Only)

✅ Pagination Update (Cloud Only)

✅ Response Format Handling (Cloud Only)

✅ Server/DC Compatibility Maintained

Files Changed

Testing

Impact

Uh oh!

clx-jlmoreno commented Nov 5, 2025

Uh oh!

eciuca commented Nov 10, 2025

Uh oh!

michaelper22 commented Nov 18, 2025

Uh oh!

ChadNedzlek commented Nov 19, 2025

Uh oh!

clx-jlmoreno commented Nov 20, 2025

Uh oh!

sooperset commented Nov 26, 2025

Uh oh!

clx-jlmoreno commented Nov 26, 2025 via email • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

clx-jlmoreno commented Nov 26, 2025 via email •

edited

Loading