feat(jira): add MCP backend for issues-by-component command

[asood-rh]

Add --backend mcp|api flag to /jira:issues-by-component.

The MCP backend (default) uses the Atlassian MCP server with OAuth browser login, requiring zero env var setup.
Falls back to the existing API backend for datasets exceeding 500 issues.
Both backends produce identical reports and support all existing flags including --search.

What this PR does / why we need it:

Which issue(s) this PR fixes:

Enhances the slash command to provide additional option to use the jira:issues-by-component

Special notes for your reviewer:

Checklist:

• Subject and description added to both, commit and PR.
• Relevant issues have been referenced.
• This change includes docs.

Summary by CodeRabbit

• New Features

  • Added a backend option for the Jira “issues by component” command, letting users choose between MCP and API handling.
  • Added support for broader issue filtering, including searching by summary and optionally description.

• Documentation

  • Expanded command guidance with setup notes, usage examples, backend comparisons, and error-handling tips.
  • Added a dedicated section for the MCP-based workflow and updated reference material for the new command skill.

[openshift-ci]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: asood-rh
Once this PR has been reviewed and has the lgtm label, please assign grimmimeloni for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• plugins/jira/OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

This PR is a documentation-only update introducing a selectable dual backend (--backend mcp|api, default MCP) for the jira:issues-by-component command. It updates marketplace metadata, README, the command reference, and adds a new MCP skill document describing preflight checks, fetch behavior, aggregation, pagination/caps, error handling, and backend comparisons.

Changes

Dual backend documentation for jira:issues-by-component

Layer / File(s)	Summary
Marketplace metadata and README docs/index.html, plugins/jira/README.md	Adds `--backend mcp
Command synopsis and prerequisites plugins/jira/commands/issues-by-component.md	Extends synopsis with --backend and rewrites prerequisites to explain MCP (OAuth, 500-issue cap) vs API (jira_curl.sh, unlimited via disk streaming).
Workflow: parsing, backend selection, search filter plugins/jira/commands/issues-by-component.md	Replaces upfront env-var check with parse/defaults step, adds MCP connectivity check with API fallback, and extends --search/--search-description JQL logic.
Fetch Issues and output reporting plugins/jira/commands/issues-by-component.md	Splits Fetch Issues docs into MCP vs API subsections, updates progress/completion message text, and clarifies unified output format across backends.
Error handling, limitations, and examples plugins/jira/commands/issues-by-component.md	Adds MCP/API-specific error sections, a combined "Common Errors" header, backend-specific limitations/return values, backend override examples, and documents the --backend argument.
New jira-issues-by-component-mcp skill plugins/jira/skills/jira-issues-by-component-mcp/SKILL.md	New skill doc covering MCP preflight, Overview/Detail mode fetch and aggregation, pagination/500-cap, fetch-loop pseudocode, return semantics, error scenarios, and backend comparison table.

Estimated code review effort: 2 (Simple) | ~12 minutes

Possibly related PRs

• openshift-eng/ai-helpers#205: Introduces the original plugins/jira/commands/issues-by-component.md that this PR revises to add dual-backend support.

Suggested labels: ok-to-test

Suggested reviewers: brandisher, LiangquanLi930

🚥 Pre-merge checks | ✅ 10

✅ Passed checks (10 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and accurately summarizes the main change: adding an MCP backend to the issues-by-component command.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
No Real People Names In Style References	✅ Passed	Changed docs use product terms and placeholder usernames only; no real-person names appear as style refs or examples.
No Assumed Git Remote Names	✅ Passed	PASS: The new jira docs/skill add no origin/upstream or git-remote assumptions; searches of the changed files returned none.
Git Push Safety Rules	✅ Passed	PASS: The PR only updates Jira docs/skills; no git push, force-push, or pushes to main/master were added in the touched files.
No Untrusted Mcp Servers	✅ Passed	The PR only documents the bundled Atlassian MCP server via .mcp.json; no npx, GitHub, or other untrusted MCP installation is introduced.
Ai-Helpers Overlap Detection	✅ Passed	The new MCP skill complements the existing API skill; frontmatter descriptions share only ~33% token overlap, so it stays below the 60% threshold.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (1)

plugins/jira/skills/jira-issues-by-component-mcp/SKILL.md (1)

33-40: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Add language tags to the fenced examples.

These bare fences trigger MD040. Mark the prose example, JSON blocks, and pseudocode fence explicitly.

🛠 Suggested fix

-```
+```text

Apply the same pattern to the JSON examples (```json) and the pseudocode block (```text or ```pseudo).

Also applies to: 58-63, 158-182

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@plugins/jira/skills/jira-issues-by-component-mcp/SKILL.md` around lines 33 -
40, The fenced examples in SKILL.md are missing language tags and trigger MD040;
update each bare fence in the affected sections to use an explicit tag based on
the content. In the prose/example blocks around the MCP backend note, use a
text-style fence, and in the JSON and pseudocode examples later in the file, use
the appropriate json and text/pseudo tags. Locate the affected snippets by the
MCP backend guidance and the other fenced examples mentioned in the review, and
make the same change consistently across them.

Source: Linters/SAST tools

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@plugins/jira/commands/issues-by-component.md`:
- Around line 114-125: The backend flow has an incorrect step reference: the API
path in the “Determine Backend” section points to a non-existent “Step 3a.”
Update the API branch text to refer to the later “Fetch Issues” subsection
instead, and keep the MCP path and connectivity-check guidance in the same
section aligned with the existing workflow structure.

In `@plugins/jira/skills/jira-issues-by-component-mcp/SKILL.md`:
- Around line 174-181: The capped-result branch is checking an undefined
`total`, so the 500-issue warning never works correctly. Update the pagination
logic in the Jira issues-by-component skill to use the accumulated fetched count
or the MCP response’s total-result field instead of `total`, and keep the
`capped` flag/warning tied to that valid value.
- Around line 84-87: The top-3 retention logic in the Jira component aggregation
is using separate checks for priority and updated time, which can evict a
better-ranked issue; align it with the documented sort order. Update the
aggregation in the skill flow that keeps top issues per component so it uses a
single comparator based on the same descending `(priority, updated)` ranking and
only retains the best three entries. Keep the stored fields limited to `key`,
`summary`, `priority.name`, and `status.name`, and apply the comparator
consistently wherever issues are inserted or replaced.

---

Nitpick comments:
In `@plugins/jira/skills/jira-issues-by-component-mcp/SKILL.md`:
- Around line 33-40: The fenced examples in SKILL.md are missing language tags
and trigger MD040; update each bare fence in the affected sections to use an
explicit tag based on the content. In the prose/example blocks around the MCP
backend note, use a text-style fence, and in the JSON and pseudocode examples
later in the file, use the appropriate json and text/pseudo tags. Locate the
affected snippets by the MCP backend guidance and the other fenced examples
mentioned in the review, and make the same change consistently across them.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: b9f4ecad-fb4f-4f93-ba1c-dfd33bcf2e0b

📥 Commits

Reviewing files that changed from the base of the PR and between e8a963f and 1d42bcd.

📒 Files selected for processing (6)

• .claude-plugin/marketplace.json
• docs/index.html
• plugins/jira/.claude-plugin/plugin.json
• plugins/jira/README.md
• plugins/jira/commands/issues-by-component.md
• plugins/jira/skills/jira-issues-by-component-mcp/SKILL.md

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@plugins/jira/skills/jira-issues-by-component-mcp/SKILL.md`:
- Around line 84-87: The top-3 aggregation in the SKILL.md guidance is dropping
`updated`, which prevents the documented priority/updated tie-break from being
applied consistently on later pages. Update the retained payload for the
component top-3 logic to keep `updated` alongside `key`, `summary`,
`priority.name`, and `status.name` in the ranking path, and only discard it
after the final ordering is settled. Make sure the instructions for the
aggregation step reference the top-3 replacement logic so the comparator can
still evaluate “then updated descending” correctly.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: d3f5d462-a6e0-4c37-b840-50a45924720f

📥 Commits

Reviewing files that changed from the base of the PR and between 1d42bcd and 086fe2c.

📒 Files selected for processing (4)

• docs/index.html
• plugins/jira/README.md
• plugins/jira/commands/issues-by-component.md
• plugins/jira/skills/jira-issues-by-component-mcp/SKILL.md

✅ Files skipped from review due to trivial changes (1)

• plugins/jira/README.md

[openshift-ci]

PR needs rebase.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.