Mode: Cognitive/Prompt-Driven - No standalone utility script; use via agent context.
Required:
-
JIRA_URL - Base URL of your Jira instance (e.g., https://yourcompany.atlassian.net)
-
JIRA_API_TOKEN - API token for authentication (generate at Jira Account Settings -> Security -> API Tokens)
-
JIRA_USER_EMAIL - Email address associated with the API token
Optional:
-
JIRA_DEFAULT_PROJECT - Default project key for operations (e.g., PROJ)
-
JIRA_API_VERSION - API version (default: 3)
<tool_categories>
Issues
Tool Description Confirmation Required
search Search issues using JQL No
get-issue Get detailed issue information No
create-issue Create a new issue Yes
update-issue Update existing issue fields Yes
transition Change issue status/workflow state Yes
Projects
Tool Description
list-projects List all accessible projects
project-info Get detailed project information
Sprints
Tool Description
active-sprint Get currently active sprint for a board
sprint-issues List all issues in a specific sprint
Comments
Tool Description
get-comments Retrieve all comments on an issue
add-comment Add a comment to an issue
</tool_categories>
<usage_patterns>
Common Workflows
Issue Creation: List projects -> Get project info -> Create issue -> Add comment
Sprint Management: Get active sprint -> List sprint issues -> Update issue status -> Add comments
Issue Search: Use JQL for targeted searches -> Retrieve issue details -> Update issues
</usage_patterns>
<agent_integration>
Primary Agent: planner
-
Use Case: Project backlog management, sprint planning, requirement tracking
-
Common Operations: Create issues, update priorities, manage sprints
Secondary Agent: developer
-
Use Case: Issue tracking during development, status updates
-
Common Operations: Search assigned issues, transition issues, add comments
</agent_integration>
<error_handling>
Common Error Scenarios
-
Authentication Errors: Missing or invalid API token, expired credentials, insufficient permissions
-
Rate Limiting: Too many API requests in short period, implement exponential backoff
-
Invalid Inputs: Non-existent project keys, invalid issue types, invalid transition IDs
-
Network Errors: Connection timeouts, unreachable Jira instance
</error_handling>
<best_practices>
-
Use JQL Efficiently: Craft precise JQL queries to reduce result sets and API calls
-
Cache Metadata: Store project keys, issue types, and transitions locally
-
Verify Before Create: Always verify project and issue type before creating issues
-
Use Transitions: Respect workflow states when changing issue status
-
Batch Operations: Group related API calls when possible
-
Handle Errors Gracefully: Provide clear error messages and recovery suggestions
-
Respect Rate Limits: Implement backoff strategies for high-volume operations
</best_practices>
<progressive_disclosure>
Context Optimization
-
Lazy Loading: Only load issue details when explicitly requested
-
Field Selection: Request only necessary fields from Jira API
-
Caching: Store frequently accessed metadata (projects, issue types)
-
Streaming: Not supported - all responses are complete payloads
-
Pagination: Automatically handle large result sets
Context Savings: 90%+ compared to loading full Jira MCP server </progressive_disclosure>
<api_reference>
Jira REST API Endpoints Used
-
/rest/api/3/search - JQL search
-
/rest/api/3/issue/{issueKey} - Get/update issue
-
/rest/api/3/issue - Create issue
-
/rest/api/3/issue/{issueKey}/transitions - Transition issue
-
/rest/api/3/project - List projects
-
/rest/api/3/project/{projectKey} - Get project details
-
/rest/agile/1.0/board/{boardId}/sprint - Get sprints
-
/rest/agile/1.0/sprint/{sprintId}/issue - Get sprint issues
-
/rest/api/3/issue/{issueKey}/comment - Get/add comments
See https://developer.atlassian.com/cloud/jira/platform/rest/v3/ for full reference. </api_reference>
Iron Laws
-
ALWAYS verify the project key exists before creating an issue — Jira silently ignores invalid project keys in some API versions, creating orphaned issues or returning cryptic errors.
-
NEVER use PUT /issue to change status — Jira status changes must go through valid workflow transitions via POST /issue/{key}/transitions ; direct field updates bypass workflow validators and automation rules.
-
ALWAYS use JQL for issue searches rather than fetching all issues and filtering client-side — returning all issues wastes quota and causes timeouts on projects with thousands of tickets.
-
NEVER create duplicate issues without first searching for existing ones — duplicate tickets fragment tracking, confuse assignees, and produce misleading velocity metrics.
-
ALWAYS include summary , issuetype , and project fields when creating an issue — these three fields are the minimum required by Jira Cloud REST API v3; missing any produces a 400 error.
Anti-Patterns
Anti-Pattern Why It Fails Correct Approach
Updating status via field PUT Bypasses workflow guards; invalid state transitions succeed silently; automation rules don't fire Use POST /issue/{key}/transitions with the correct transition ID
Fetching all issues and filtering locally Times out on large projects; wastes API quota; slow for paginated results Always use JQL with specific project/sprint/status filters
Creating issues without duplication check Splits work tracking; team sees multiple tickets for same task Search with JQL (project = X AND summary ~ "keyword" ) before creating
Hardcoding field IDs (e.g., customfield_10016 ) Field IDs differ between Jira instances and cloud/server; breaks across projects Discover field IDs dynamically via /rest/api/3/field endpoint
No error handling for rate limits (429) Jira Cloud rate limits at ~300 requests/minute; unhandled 429 crashes automation Implement exponential backoff; check Retry-After header on 429 responses
Memory Protocol (MANDATORY)
Before starting: Read .claude/context/memory/learnings.md
After completing:
-
New pattern -> .claude/context/memory/learnings.md
-
Issue found -> .claude/context/memory/issues.md
-
Decision made -> .claude/context/memory/decisions.md
ASSUME INTERRUPTION: If it is not in memory, it did not happen.