From 621c90427c37d78417c01911a50a0291749a9e87 Mon Sep 17 00:00:00 2001 From: Alex Clarke Date: Fri, 13 Feb 2026 14:56:42 -0700 Subject: [PATCH] feat: Use the official atlassian MCP server for the jira-helper agent --- README.md | 2 +- assets/agents/jira-helper/README.md | 32 +--- assets/agents/jira-helper/config.yaml | 32 +++- assets/agents/jira-helper/tools.sh | 259 -------------------------- assets/functions/mcp.json | 4 + 5 files changed, 34 insertions(+), 295 deletions(-) delete mode 100755 assets/agents/jira-helper/tools.sh diff --git a/README.md b/README.md index f55a66f..c3bb9cc 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ Coming from [AIChat](https://github.com/sigoden/aichat)? Follow the [migration g Loki requires the following tools to be installed on your system: * [jq](https://github.com/jqlang/jq) * `brew install jq` -* [jira (optional)](https://github.com/ankitpokhrel/jira-cli/wiki/Installation) (For the `jira-helper` agent) +* [jira (optional)](https://github.com/ankitpokhrel/jira-cli/wiki/Installation) (For the `query_jira_issues` tool) * `brew tap ankitpokhrel/jira-cli && brew install jira-cli` * You'll need to [create a JIRA API token](https://id.atlassian.com/manage-profile/security/api-tokens) for authentication * Then, save it as an environment variable to your shell profile: diff --git a/assets/agents/jira-helper/README.md b/assets/agents/jira-helper/README.md index 5946a53..2db1697 100644 --- a/assets/agents/jira-helper/README.md +++ b/assets/agents/jira-helper/README.md @@ -2,31 +2,13 @@ ## Overview -The Jira AI Agent is designed to assist with managing tasks within Jira projects, providing capabilities such as creating, searching, updating, assigning, linking, and commenting on issues. Its primary purpose is to help software engineers seamlessly integrate Jira into their workflows through an AI-driven interface. +The Jira AI Agent is designed to assist with managing tasks within Jira projects, providing capabilities such as +creating, searching, updating, assigning, linking, and commenting on issues. Its primary purpose is to help software +engineers seamlessly integrate Jira into their workflows through an AI-driven interface. ## Configuration +This agent uses the official [Atlassian MCP Server](https://github.com/atlassian/atlassian-mcp-server). To use it, +ensure you have Node.js v18+ installed to run the local MCP proxy (`mcp-remote`). -### Variables - -This agent accepts the following variables: - -- **config**: Specifies the configuration file for the Jira CLI. This configuration should be located at `~/.config/.jira/.yml`. Example: `work`. -- **project**: The Jira project key where operations are executed. Example: `PAN`. - -### Customization - -#### For a User's Specific Jira Instance - -1. **Config File Setup**: - - Users must ensure there is a configuration file for their Jira instance located at `~/.config/.jira/`. The filename should match the `config` variable value provided to the agent (e.g., for `config` set to `work`, ensure a `work.yml` exists). - -2. **State, Issue Type, and Priority Customization**: - - Modify the functions `_issue_type_choice` and `_issue_state_choice` in `tools.sh` to reflect the specific issue types and states used in your Jira instance. - - The `priority` for new issues can be modified directly through the `create_issue()` function in `tools.sh` with options set to the values available in your Jira instance (e.g., Medium, Highest, etc.). - -## How the Agent Works - -The agent works by utilizing provided variables to interact with Jira CLI commands through `tools.sh`. The `config` variable links directly to a `.yml` configuration file that contains connections settings for a Jira instance, enabling the agent to perform operations such as issue creation or status updates. - -- **Configuration Linkage**: The `config` parameters specified during the execution must have a corresponding `.yml` configuration file at `~/.config/.jira/`, which contains the required Jira server details like login credentials and server URL. -- **Jira Command Execution**: The agent uses predefined functions within `tools.sh` to execute Jira operations. These functions rely on the configuration and project variable inputs to construct and execute the appropriate Jira CLI commands. +The server uses OAuth 2.0 so it will automatically open your browser for you to sign in to your account. No manual +configuration is necessary! diff --git a/assets/agents/jira-helper/config.yaml b/assets/agents/jira-helper/config.yaml index b39a020..3e50717 100644 --- a/assets/agents/jira-helper/config.yaml +++ b/assets/agents/jira-helper/config.yaml @@ -2,22 +2,34 @@ name: Jira Agent description: An AI agent that can assist with Jira tasks such as creating issues, searching for issues, and updating issues. version: 0.1.0 agent_session: temp +mcp_servers: + - atlassian instructions: | - You are a AI agent designed to assist with managing Jira tasks and helping software engineers - utilize and integrate Jira into their workflows. You can create, search, update, assign, link, and comment on issues in Jira. - - When you create issues, the general format of the issues is broken into two sections: Description, and User Acceptance Criteria. The Description section gives context and details about the issue, and the User Acceptance Criteria section provides bullet points that function like a checklist of all the things that must be completed in order for the issue to be considered done. + You are a AI agent designed to assist with managing Jira tasks and helping software engineers utilize and integrate + Jira into their workflows. You can create, search, update, assign, link, and comment on issues in Jira. - Create issues under the {{project}} Jira project. + ## Create Issue (MANDATORY when creating a issue) + When a user prompts you to create a Jira issue: + 1. Prompt the user for what Jira project they want the ticket created in + 2. If the ticket type requires a parent issue: + a. Query Jira for potentially relevant parents + b. Prompt user for which parent to use, displaying the suggested list of parent issues + 3. Create the issue with the following format: + ```markdown + **Description:** + This section gives context and details about the issue. + **User Acceptance Criteria:** + # This section provides bullet points that function like a checklist of all the things that must be completed in + # order for the issue to be considered done. + * Example criteria one + * Example criteria two + ``` + 4. Ask the user if the issue should be assigned to them + a. If yes, then assign the user to the newly created issue Available tools: {{__tools__}} -variables: - - name: config - description: The configuration to use for the Jira CLI; e.g. work - - name: project - description: The Jira project to operate on; e.g. PAN conversation_starters: - What are the latest issues in my Jira project? - Can you create a new Jira issue for me? diff --git a/assets/agents/jira-helper/tools.sh b/assets/agents/jira-helper/tools.sh deleted file mode 100755 index ad11f07..0000000 --- a/assets/agents/jira-helper/tools.sh +++ /dev/null @@ -1,259 +0,0 @@ -#!/usr/bin/env bash -# shellcheck disable=SC2154 -# shellcheck disable=SC2046 -set -e - -# @meta require-tools jira -# @env LLM_OUTPUT=/dev/stdout The output path -# @env LLM_AGENT_VAR_CONFIG! The configuration to use for the Jira CLI; e.g. work -# @env LLM_AGENT_VAR_PROJECT! The Jira project to operate on; e.g. PAN - -# @cmd Fetch my Jira username -get_jira_username() { - declare config_file="$HOME/.config/.jira/${LLM_AGENT_VAR_CONFIG}.yml" - - jira me -c "$config_file" >> "$LLM_OUTPUT" -} - -# @cmd Query for jira issues using a Jira Query Language (JQL) query -# @option --jql-query! The Jira Query Language query to execute -# @option --project! $LLM_AGENT_VAR_PROJECT Jira project to operate on; e.g. PAN -query_jira_issues() { - declare config_file="$HOME"/.config/.jira/"${LLM_AGENT_VAR_CONFIG}".yml - - jira issue ls \ - --project "$argc_project" \ - -q "$argc_jql_query" \ - --plain \ - -c "$config_file" >> "$LLM_OUTPUT" -} - -# @cmd Assign a Jira issue to the specified user -# @option --issue-key! The Jira issue key, e.g. ISSUE-1 -# @option --assignee! The email or display name of the user to assign the issue to -# @option --project! $LLM_AGENT_VAR_PROJECT Jira project to operate on; e.g. PAN -assign_jira_issue() { - declare config_file="$HOME"/.config/.jira/"${LLM_AGENT_VAR_CONFIG}".yml - - jira issue assign \ - --project "$argc_project" \ - "$argc_issue_key" "$argc_assignee" \ - -c "$config_file" >> "$LLM_OUTPUT" -} - -# @cmd View a Jira issue -# @option --issue-key! The Jira issue key, e.g. ISSUE-1 -# @option --project! $LLM_AGENT_VAR_PROJECT Jira project to operate on; e.g. PAN -view_issue() { - declare config_file="$HOME"/.config/.jira/"${LLM_AGENT_VAR_CONFIG}".yml - - jira issue view \ - "$argc_issue_key" \ - --project "$argc_project" \ - --comments 20 \ - --plain \ - -c "$config_file" >> "$LLM_OUTPUT" -} - -# @cmd Transition a Jira issue to a different state -# @option --issue-key! The Jira issue key, e.g. ISSUE-1 -# @option --state![`_issue_state_choice`] The Jira state of the issue -# @option --comment Add a comment to the issue -# @option --resolution Set resolution -# @option --project! $LLM_AGENT_VAR_PROJECT Jira project to operate on; e.g. PAN -transition_issue() { - declare config_file="$HOME"/.config/.jira/"${LLM_AGENT_VAR_CONFIG}".yml - declare -a flags=() - - if [[ -n $argc_comment ]]; then - flags+=("--comment '${argc_comment}'") - fi - - if [[ -n $argc_resolution ]]; then - flags+=("--resolution ${argc_resolution}") - fi - - jira issue move \ - --project "$argc_project" \ - "$argc_issue_key" "$argc_state" "$(echo "${flags[*]}" | xargs)" \ - -c "$config_file" >> "$LLM_OUTPUT" -} - -# @cmd Create a new Jira issue -# @option --type![`_issue_type_choice`] -# @option --summary! Issue summary or title -# @option --description! Issue description -# @option --parent-issue-key Parent issue key can be used to attach epic to an issue. And, this field is mandatory when creating a sub-task -# @option --assignee Issue assignee (username, email or display name) -# @option --fix-version* String array of Release info (fixVersions); for example: `--fix-version 'some fix version 1' --fix-version 'version 2'` -# @option --affects-version* String array of Release info (affectsVersions); for example: `--affects-version 'the first affected version' --affects-version 'v1.2.3'` -# @option --label* String array of issue labels; for example: `--label backend --label custom` -# @option --component* String array of issue components; for example: `--component backend --component core` -# @option --original-estimate The original estimate of the issue -# @option --priority[=Medium|Highest|High|Low|Lowest] The priority of the issue -# @option --project! $LLM_AGENT_VAR_PROJECT Jira project to operate on; e.g. PAN -create_issue() { - declare config_file="$HOME"/.config/.jira/"${LLM_AGENT_VAR_CONFIG}".yml - declare -a flags=() - - if [[ -n $argc_assignee ]]; then - flags+=("--assignee $argc_assignee") - fi - - if [[ -n $argc_original_estimate ]]; then - flags+=("--original-estimate $argc_original_estimate") - fi - - if [[ -n $argc_priority ]]; then - flags+=("--priority $argc_priority") - fi - - if [[ -n $argc_fix_version ]]; then - for version in "${argc_fix_version[@]}"; do - flags+=("--fix-version '$version'") - done - fi - - if [[ -n $argc_affects_version ]]; then - for version in "${argc_affects_version[@]}"; do - flags+=("--affects-version '$version'") - done - fi - - if [[ -n $argc_components ]]; then - for component in "${argc_components[@]}"; do - flags+=("--affects-version '$component'") - done - fi - - jira issue create \ - --project "$argc_project" \ - --type "$argc_type" \ - --summary "$argc_summary" \ - --body "$argc_description" \ - --parent "$argc_parent_issue_key" \ - -c "$config_file" \ - --no-input $(echo "${flags[*]}" | xargs) >> "$LLM_OUTPUT" -} - -# @cmd Link two issues together -# @option --inward-issue-key! Issue key of the source issue, eg: ISSUE-1 -# @option --outward-issue-key! Issue key of the target issue, eg: ISSUE-2 -# @option --issue-link-type! Relationship between two issues, eg: Duplicates, Blocks etc. -# @option --project! $LLM_AGENT_VAR_PROJECT Jira project to operate on; e.g. PAN -link_issues() { - declare config_file="$HOME"/.config/.jira/"${LLM_AGENT_VAR_CONFIG}".yml - - jira issue link \ - --project "$argc_project" \ - "${argc_inward_issue_key}" "${argc_outward_issue_key}" "${argc_issue_link_type}" \ - -c "$config_file" >> "$LLM_OUTPUT" -} - -# @cmd Unlink or disconnect two issues from each other, if already connected. -# @option --inward-issue-key! Issue key of the source issue, eg: ISSUE-1 -# @option --outward-issue-key! Issue key of the target issue, eg: ISSUE-2. -# @option --project! $LLM_AGENT_VAR_PROJECT Jira project to operate on; e.g. PAN -unlink_issues() { - declare config_file="$HOME"/.config/.jira/"${LLM_AGENT_VAR_CONFIG}".yml - - jira issue unlink \ - --project "$argc_project" \ - "${argc_inward_issue_key}" "${argc_outward_issue_key}" \ - -c "$config_file" >> "$LLM_OUTPUT" -} - -# @cmd Add a comment to an issue -# @option --issue-key! Issue key of the source issue, eg: ISSUE-1 -# @option --comment-body! Body of the comment you want to add -# @option --project! $LLM_AGENT_VAR_PROJECT Jira project to operate on; e.g. PAN -add_comment_to_issue() { - declare config_file="$HOME"/.config/.jira/"${LLM_AGENT_VAR_CONFIG}".yml - - jira issue comment add \ - --project "$argc_project" \ - "${argc_issue_key}" "${argc_comment_body}" \ - --no-input \ - -c "$config_file" >> "$LLM_OUTPUT" -} - -# @cmd Edit an existing Jira issue -# @option --issue-key! The Jira issue key, e.g. ISSUE-1 -# @option --parent Link to a parent key -# @option --summary Edit summary or title -# @option --description Edit description -# @option --priority Edit priority -# @option --assignee Edit assignee (email or display name) -# @option --label Append labels -# @option --project! $LLM_AGENT_VAR_PROJECT Jira project to operate on; e.g. PAN -edit_issue() { - declare config_file="$HOME"/.config/.jira/"${LLM_AGENT_VAR_CONFIG}".yml - declare -a flags=() - - if [[ -n $argc_parent ]]; then - flags+=("--parent $argc_parent") - fi - - if [[ -n $argc_summary ]]; then - flags+=("--summary $argc_summary") - fi - - if [[ -n $argc_description ]]; then - flags+=("--body $argc_description") - fi - - if [[ -n $argc_priority ]]; then - flags+=("--priority $argc_priority") - fi - - if [[ -n $argc_assignee ]]; then - flags+=("--assignee $argc_assignee") - fi - - if [[ -n $argc_label ]]; then - flags+=("--label $argc_label") - fi - - jira issue edit \ - --project "$argc_project" \ - "$argc_issue_key" $(echo "${flags[*]}" | xargs) \ - --no-input \ - -c "$config_file" >> "$LLM_OUTPUT" -} - -_issue_type_choice() { - if [[ $LLM_AGENT_VAR_CONFIG == "work" ]]; then - echo "Story" - echo "Task" - echo "Bug" - echo "Technical Debt" - echo "Sub-task" - elif [[ $LLM_AGENT_VAR_CONFIG == "sideproject" ]]; then - echo "Task" - echo "Story" - echo "Bug" - echo "Epic" - fi -} - -_issue_state_choice() { - if [[ $LLM_AGENT_VAR_CONFIG == "work" ]]; then - echo "Ready for Dev" - echo "CODE REVIEW" - echo "IN PROGRESS" - echo "Backlog" - echo "Done" - echo "TESTING" - elif [[ $LLM_AGENT_VAR_CONFIG == "sideproject" ]]; then - echo "IN CLARIFICATION" - echo "NEED TO CLARIFY" - echo "READY TO WORK" - echo "RELEASE BACKLOG" - echo "REOPEN" - echo "CODE REVIEW" - echo "IN PROGRESS" - echo "IN TESTING" - echo "TO TEST" - echo "DONE" - fi -} diff --git a/assets/functions/mcp.json b/assets/functions/mcp.json index 23b197c..29519e9 100644 --- a/assets/functions/mcp.json +++ b/assets/functions/mcp.json @@ -14,6 +14,10 @@ "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_TOKEN" } }, + "atlassian": { + "command": "npx", + "args": ["-y", "mcp-remote@0.1.13", "https://mcp.atlassian.com/v1/sse"] + }, "docker": { "command": "uvx", "args": ["mcp-server-docker"]