Atlassian Jira Tools

Provides type-safe Python tools for interacting with Jira through a progressive loading API that minimizes token usage.

Current Status

Available Tools: 1 (jira_get_issue) Planned Tools: 30+ additional Jira operations

This skill demonstrates the internalized MCP pattern. Additional tools will be added progressively.

Prerequisites

Required Environment Variables

Before using any Jira tools, set these environment variables:

export JIRA_URL="https://your-domain.atlassian.net"
export JIRA_USERNAME="your-email@example.com"
export JIRA_API_TOKEN="your-api-token"

Getting API Token:

1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
2. Click "Create API token"
3. Give it a name and copy the token
4. Use your email as JIRA_USERNAME and the token as JIRA_API_TOKEN

Installation

The Python package must be installed in your environment:

cd /Users/bono/Documents/01.Projects/MCP_Internalization/atlassian-internalized
pip install -e .

Usage Pattern

Step 1: List Available Tools

python skills/atlassian-jira/scripts/execute_tool.py --list-tools

Returns:

{
  "success": true,
  "tools": ["jira_get_issue"],
  "count": 1
}

Step 2: Get Tool Schema (Optional)

python skills/atlassian-jira/scripts/execute_tool.py jira_get_issue --schema

Returns detailed JSON schema for inputs and outputs.

Step 3: Execute Tool

python skills/atlassian-jira/scripts/execute_tool.py jira_get_issue --input '{
  "issue_key": "PROJ-123",
  "fields": "summary,status,assignee",
  "comment_limit": 5
}'

Available Tools

jira_get_issue

Retrieve comprehensive information about a specific Jira issue.

Input Parameters:

• issue_key (required): Issue key like "PROJ-123"
• fields (optional): Comma-separated fields or "*all" for all fields
• expand (optional): Fields to expand (e.g., "changelog,transitions")
• comment_limit (optional): Max comments to include (0-100, default: 10)

Example:

# Get basic issue info
python scripts/execute_tool.py jira_get_issue --input '{"issue_key": "PROJ-123"}'

# Get specific fields only
python scripts/execute_tool.py jira_get_issue --input '{
  "issue_key": "PROJ-123",
  "fields": "summary,status,assignee,priority"
}'

# Get all fields with changelog
python scripts/execute_tool.py jira_get_issue --input '{
  "issue_key": "PROJ-123",
  "fields": "*all",
  "expand": "changelog"
}'

# Get issue without comments
python scripts/execute_tool.py jira_get_issue --input '{
  "issue_key": "PROJ-123",
  "comment_limit": 0
}'

Output:

{
  "success": true,
  "issue": {
    "key": "PROJ-123",
    "id": "10001",
    "fields": {
      "summary": "Implement new feature",
      "status": {"name": "In Progress", "category": "In Progress"},
      "assignee": {"display_name": "John Doe", "email": "john@example.com"},
      "priority": {"name": "High"},
      "created": "2025-01-14T10:00:00.000+0000",
      "updated": "2025-01-14T12:00:00.000+0000",
      "comments": [
        {
          "author": "Jane Smith",
          "body": "This looks good",
          "created": "2025-01-14T11:00:00.000+0000"
        }
      ]
    }
  }
}

Common Workflows

Get Issue Summary

Quick way to check an issue's current state:

python scripts/execute_tool.py jira_get_issue --input '{
  "issue_key": "PROJ-123",
  "fields": "summary,status,assignee",
  "comment_limit": 0
}'

Get Full Issue Details

Retrieve all available information:

python scripts/execute_tool.py jira_get_issue --input '{
  "issue_key": "PROJ-123",
  "fields": "*all",
  "comment_limit": 20
}'

Get Issue with Change History

See what changed over time:

python scripts/execute_tool.py jira_get_issue --input '{
  "issue_key": "PROJ-123",
  "expand": "changelog"
}'

Error Handling

All tools return structured responses with error information:

{
  "success": false,
  "error": "Issue PROJ-999 not found"
}

Common Errors

Authentication Failed:

Error: "Authentication failed. Check your credentials"

→ Verify JIRA_URL, JIRA_USERNAME, and JIRA_API_TOKEN are correct

Issue Not Found:

Error: "Issue PROJ-999 not found"

→ Check the issue key exists and you have permission to view it

Missing Environment Variables:

Error: "JIRA_URL environment variable is required"

→ Set all required environment variables

Invalid Input:

Error: "Input validation error: ..."

→ Check your input matches the schema (use --schema to see requirements)

Performance & Token Efficiency

Progressive Discovery

Tools are discovered without loading their implementation:

• Tool List: ~50 tokens
• Tool Schema: ~200 tokens per tool
• Tool Execution: Only loads when called

Data Filtering

Use field filters to reduce data transfer:

# Instead of getting all fields (large response)
python scripts/execute_tool.py jira_get_issue --input '{"issue_key": "PROJ-123"}'

# Get only what you need (small response)
python scripts/execute_tool.py jira_get_issue --input '{
  "issue_key": "PROJ-123",
  "fields": "summary,status",
  "comment_limit": 0
}'

Comment Limiting

Control how many comments are returned:

• comment_limit: 0 - No comments (fastest)
• comment_limit: 5 - Recent 5 comments
• comment_limit: 100 - Maximum allowed

Troubleshooting

Tool Not Found

If you get "Tool not found" errors:

1. Verify installation:

   python -c "import atlassian_tools; print(atlassian_tools.list_tools('jira'))"
   

2. Check you're in the correct directory:

   cd /Users/bono/Documents/01.Projects/MCP_Internalization/atlassian-internalized
   

3. Reinstall if needed:

   pip install -e .
   

Script Execution Errors

If the script won't run:

1. Make it executable:

   chmod +x skills/atlassian-jira/scripts/execute_tool.py
   

2. Run with python explicitly:

   python skills/atlassian-jira/scripts/execute_tool.py --list-tools
   

JSON Parsing Errors

If your input JSON is invalid:

1. Use single quotes around the JSON and double quotes inside:

   --input '{"issue_key": "PROJ-123"}'
   

2. Escape quotes if needed:

   --input "{\"issue_key\": \"PROJ-123\"}"
   

3. Use a JSON file:

   --input "$(cat examples/get_issue.json | jq -c .input)"
   

Direct Python Usage

For programmatic access, use the Python API directly:

import asyncio
import atlassian_tools

# List available tools
tools = atlassian_tools.list_tools(category='jira')
print(tools)  # ['jira_get_issue']

# Execute a tool
async def main():
    result = await atlassian_tools.execute_tool(
        'jira_get_issue',
        {'issue_key': 'PROJ-123', 'comment_limit': 5}
    )

    if result['data']['success']:
        issue = result['data']['issue']
        print(f"Issue: {issue['fields']['summary']}")
    else:
        print(f"Error: {result['data']['error']}")

asyncio.run(main())

Future Tools (Planned)

The following tools are planned for future releases:

• jira_create_issue - Create new issues
• jira_update_issue - Update existing issues
• jira_search - Search issues with JQL
• jira_add_comment - Add comments to issues
• jira_transition_issue - Move issues through workflow
• jira_list_projects - List all accessible projects
• Plus 25+ more operations

Tips for Claude Code Usage

When using this skill in Claude Code:

1. Start with discovery: Ask Claude to list available tools first
2. Check schemas: Use --schema to understand inputs/outputs
3. Use examples: Reference the examples/ directory for common patterns
4. Filter data: Always specify which fields you need to reduce tokens
5. Handle errors: Check the success field in responses

Related Skills

• atlassian-confluence (planned) - Confluence page and space management

Support

For issues, questions, or contributions:

• Project: atlassian-internalized
• Location: /Users/bono/Documents/01.Projects/MCP_Internalization/atlassian-internalized
• Documentation: docs/internalization-log.md