Jira MCP Server

MCP server for fetching Jira tickets and generating documentation (SRS, UI specs, test cases, subtasks).

Setup

1. Install Dependencies

npm install

2. Configure Credentials

Create a .env file in the project root:

# Jira (Required)
Jira_DOMAIN=yourcompany.atlassian.net
Jira_EMAIL=your.email@example.com
Jira_API_TOKEN=your_api_token_here

# TestRail (Optional - for pushing test cases)
TESTRAIL_URL=https://yourcompany.testrail.io
TESTRAIL_USERNAME=your.email@example.com
TESTRAIL_API_KEY=your_api_key_here

Get Jira API Token: https://id.atlassian.com/manage-profile/security/api-tokens

Get TestRail API Key: TestRail → User Settings → API & Integrations → Generate API Key

---

Quick Command Reference

Command	Description	Output
@fetch-jira DEV-123	Fetch Jira ticket data	staging/aggregated.json
@generate_srs	Generate SRS document	staging/srs.md
@generate_ui	Generate UI specification	staging/ui_document.md
@generate_tests	Generate test cases	staging/test_cases.json
@generate_tests_csv	Convert tests to CSV	staging/test_cases.csv
@generate_subtasks	Generate subtasks from ticket	staging/subtasks.json
@push_subtasks_to_jira DEV-123	Push subtasks to Jira	Creates subtasks on ticket
@createSubtasks DEV-123	Full flow: fetch → generate → push subtasks	All of the above
@post_testcases_to_jira DEV-123	Post test cases as Jira comment	Comment on ticket
@push_to_testrail 123	Push test cases to TestRail	Creates test cases in section
@generate_all DEV-123	Full documentation workflow	All docs generated

---

Workflows

Documentation Workflow

@fetch-jira DEV-123     → Fetches ticket, linked issues, attachments, Confluence pages
@generate_srs           → Creates SRS from aggregated.json
@generate_ui            → Creates UI spec (needs SRS)
@generate_tests         → Creates test cases (needs SRS + UI)
@generate_tests_csv     → Converts tests to CSV format

Or run all at once:

@generate_all DEV-123

Subtask Workflow

Subtasks can be generated from Jira ticket data and automatically created on the parent ticket.

Option 1: Full Automated Flow (Recommended)

@createSubtasks DEV-123

This single command:

1. Fetches the Jira ticket bundle (staging/aggregated.json)
2. Generates subtasks following rules (staging/subtasks.json)
3. Creates all subtasks on the parent ticket in Jira

Option 2: Step-by-Step

# Step 1: Fetch Jira ticket (if not already fetched)
@fetch-jira DEV-123

# Step 2: Generate subtasks JSON
@generate_subtasks

# Step 3: Review/edit staging/subtasks.json if needed

# Step 4: Push subtasks to Jira
@push_subtasks_to_jira DEV-123

Subtask JSON Format

The generated staging/subtasks.json follows this format:

[
  {
    "summary": "Implement user login API",
    "description": "Create POST /api/login endpoint.\n\nAcceptance Criteria:\n- Returns JWT token on success\n- Returns 401 on invalid credentials"
  },
  {
    "summary": "Add password validation",
    "description": "Implement password strength validation.\n\nDepends on: User login API"
  }
]

Subtask Rules:

• summary (required): Action-oriented title starting with a verb (5-80 chars)
• description (optional): Detailed description with acceptance criteria
• Priority uses Jira's project default

How Subtasks are Generated

1. Data Sources: Reads staging/aggregated.json which contains:

   • Root ticket (description, acceptance criteria)
   • Linked issues
   • Confluence pages (often has detailed implementation plans)
   • Attachments and comments

2. Extraction Logic:

   • Numbered lists and bullet points → subtasks
   • Acceptance criteria → individual subtasks
   • API endpoints → ordered by dependency
   • Phased plans (Part 1, Part 2) → grouped subtasks

3. API Ordering: For tickets with multiple APIs, subtasks are ordered by dependency:

   Signup API → Signin API → Dashboard API (requires auth)
   

4. Difficulty Check: Complex tasks are automatically subdivided into 2-8 hour chunks

Push Test Cases to TestRail

After generating test cases, you can push them directly to TestRail.

Prerequisites:

• Test cases generated (staging/test_cases.json)
• TestRail credentials configured in .env
• TestRail section ID where you want to create test cases

Command:

@push_to_testrail 123

(Replace 123 with your TestRail section ID)

Finding Your Section ID:

1. Navigate to your test suite in TestRail
2. Click on the section where you want to add test cases
3. The section ID is in the URL: https://yourcompany.testrail.io/index.php?/suites/view/XX&group_id=123
   • The group_id=123 or /sections/view/123 contains your section ID

Field Mapping:

Test Case JSON	TestRail Field
title	Title
test_type	Type (Functional, Regression, etc.)
priority	Priority
serial_no	References (AUTO-{serial_no})
preconditions	Preconditions
testing_steps	Steps
expected_result	Expected Result

Output:

• Returns count of successfully created test cases
• Lists created case IDs (e.g., C123, C124, C125)

---

Using Context Files (Optional)

All documents are generated from staging/aggregated.json. You can optionally add context files for additional reference.

What is the Context Folder?

The context/ folder is for storing reference files that help improve document generation:

• Source code files - Actual implementation code for analysis
• Documentation templates - Existing SRS/UI docs for formatting reference
• Other references - Any relevant project files

How to Add Context

1. Create a context/ folder in the project root
2. Add your reference files (source code, docs, templates)
3. Reference them when generating documents:

Generate SRS using @context/your-file.js
Generate test cases using @context/your-template.md

Example Structure

context/
├── src/
│   └── MyComponent.js      # Source code for implementation analysis
├── docs/
│   └── srs_template.md     # SRS formatting template
└── specs/
    └── ui_spec.md          # UI specification reference

Note: Context files are optional. Without them, documents are generated purely from Jira ticket data.

---

Output Files

All generated files are saved to the staging/ folder:

File	Description
aggregated.json	Raw Jira ticket data (root, linked, attachments, confluence)
srs.md	Software Requirements Specification
ui_document.md	UI Specification Document
test_cases.json	Test cases in JSON format
test_cases.csv	Test cases in CSV format (for Excel/Sheets)
subtasks.json	Generated subtasks ready for Jira