Package Exports

jira-automation-cli
jira-automation-cli/dist/jira/cli.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (jira-automation-cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Jira Automation CLI & MCP Server

A command-line tool and MCP (Model Context Protocol) server for automating the creation of Jira epics, stories, and tasks from JSON files.

Installation

Option 1: Install via npx (Recommended)

# Run directly without installation
npx jira-automation-cli --help

# Or install globally
npm install -g jira-automation-cli

Option 2: Install from source

# Clone the repository
git clone https://github.com/pradipparmar/jira-automation.git
cd jira-automation

# Install dependencies
npm install

# Build the project
npm run build

# Run the CLI
npm start -- --help

Configuration

Create a .env file in your project root with your Jira credentials and project settings. You can copy .env.example as a template:

JIRA_URL=https://your-domain.atlassian.net
JIRA_EMAIL=your-email@example.com
JIRA_API_TOKEN=your-api-token
JIRA_EPIC_LINK_FIELD=customfield_10014
JIRA_STORY_POINTS_FIELD=customfield_10043

Note: Do not commit your .env file with real credentials to version control. Use .env.example as a reference for others.

Usage

CLI Mode

# Process all items (with environment variables)
jira-automation process -f ./linkinbio --jira-url $JIRA_URL --jira-email $JIRA_EMAIL --jira-api-token $JIRA_API_TOKEN --epic-link-field $JIRA_EPIC_LINK_FIELD --story-points-field $JIRA_STORY_POINTS_FIELD

# Process all items (with direct values)
jira-automation process -f ./linkinbio --jira-url https://your-domain.atlassian.net --jira-email your-email@example.com --jira-api-token your-api-token --epic-link-field customfield_10014 --story-points-field customfield_10043

# Perform a dry run
jira-automation process -f ./linkinbio --dry-run --jira-url $JIRA_URL --jira-email $JIRA_EMAIL --jira-api-token $JIRA_API_TOKEN --epic-link-field $JIRA_EPIC_LINK_FIELD --story-points-field $JIRA_STORY_POINTS_FIELD

# Force recreation of existing items
jira-automation process -f ./linkinbio --force --jira-url $JIRA_URL --jira-email $JIRA_EMAIL --jira-api-token $JIRA_API_TOKEN --epic-link-field $JIRA_EPIC_LINK_FIELD --story-points-field $JIRA_STORY_POINTS_FIELD

# Skip specific item types
jira-automation process -f ./linkinbio --skip-epics --skip-stories --jira-url $JIRA_URL --jira-email $JIRA_EMAIL --jira-api-token $JIRA_API_TOKEN --epic-link-field $JIRA_EPIC_LINK_FIELD --story-points-field $JIRA_STORY_POINTS_FIELD

# Continue processing on error
jira-automation process -f ./linkinbio --continue-on-error --jira-url $JIRA_URL --jira-email $JIRA_EMAIL --jira-api-token $JIRA_API_TOKEN --epic-link-field $JIRA_EPIC_LINK_FIELD --story-points-field $JIRA_STORY_POINTS_FIELD

# Create a new sprint
jira-automation create-sprints --board 123 --jira-url $JIRA_URL --jira-email $JIRA_EMAIL --jira-api-token $JIRA_API_TOKEN --epic-link-field $JIRA_EPIC_LINK_FIELD --story-points-field $JIRA_STORY_POINTS_FIELD

# Validate folder structure
jira-automation validate -f ./linkinbio

# Validate and create missing structure
jira-automation validate-and-create -f ./linkinbio

# Reset all Jira IDs
jira-automation reset-ids -f ./linkinbio

Note: The CLI automatically loads environment variables from .env file, but you can still override them with command-line arguments.

MCP Server Mode

The Jira automation is also available as an MCP server, providing programmatic access to all CLI features.

Starting the MCP Server

# Start the MCP server
jira-automation mcp-server

# Or run directly
npx jira-automation-cli mcp-server

# The server will listen on port 4333 by default

Available MCP Tools

The MCP server exposes the following tools:

jira_process_items: Process Jira items from a folder structure
jira_validate_structure: Validate folder structure without processing
jira_validate_and_create_structure: Validate and create missing folder structure
jira_reset_ids: Reset all Jira IDs to null in JSON files
jira_create_sprint: Create a new sprint based on existing sprints
jira_create_epic: Create a single epic
jira_create_story: Create a single story
jira_create_task: Create a single task

Using with MCP Clients

You can use the MCP server with any MCP-compatible client. The server accepts the same parameters as the CLI commands but in a programmatic format.

Example MCP tool call:

{
  "name": "jira_process_items",
  "arguments": {
    "folderPath": "./linkinbio",
    "dryRun": false,
    "force": false,
    "skipEpics": false,
    "skipStories": false,
    "skipTasks": false,
    "continueOnError": false,
    "jiraUrl": "https://your-domain.atlassian.net",
    "jiraEmail": "your-email@example.com",
    "jiraApiToken": "your-api-token",
    "epicLinkField": "customfield_10014",
    "storyPointsField": "customfield_10043"
  }
}

File Structure

Create a folder (e.g., "vritix") with the following structure:

vritix/
├── epic.json
├── Requirement.md
└── [epic_name]/
    ├── story.json
    └── [story_name]/
        └── tasks.json

Folder Naming Rules

Special Characters: All special characters are removed from folder names
Spaces: All spaces are replaced with underscores
Case: All folder names are converted to lowercase
Examples:
- "Authentication & Authorization System" → "authentication_authorization_system"
- "User Management (v2)" → "user_management_v2"
- "API Integration & Testing" → "api_integration_testing"

epic.json

{
  "projectKey": "VRITIX",
  "epics": [
    {
      "name": "Authentication System",
      "description": "Implement secure authentication and authorization system",
      "jiraId": "VRITIX-1",
      "update": true
    },
    {
      "name": "User Management",
      "description": "Implement user management features",
      "jiraId": null,
      "update": false
    }
  ]
}

story.json

{
  "stories": [
    {
      "name": "Create New Admin",
      "description": "As a system administrator, I want to create new admin users",
      "storyPoints": 5,
      "jiraId": null,
      "update": false,
      "acceptanceCriteria": [
        "Admin can create new admin users",
        "New admin users must have valid email addresses",
        "New admin users must have strong passwords"
      ],
      "tests": [
        "Test admin creation with valid data",
        "Test admin creation with invalid email",
        "Test admin creation with weak password"
      ],
      "steps": [
        "Create admin creation form",
        "Implement email validation",
        "Implement password strength validation",
        "Add admin user to database"
      ]
    }
  ]
}

tasks.json

{
  "tasks": [
    {
      "name": "Implement End-to-End User Registration API",
      "description": "Develop the complete backend for user registration, including model, API endpoint, business logic, validation, integration, and unit tests.",
      "storyPoints": 5,
      "jiraId": null,
      "labels": ["backend", "api", "validation"]
    },
    {
      "name": "Implement User Registration UI",
      "description": "Build and integrate the user registration form, handle validation, error states, and connect to the backend API.",
      "storyPoints": 3,
      "jiraId": null,
      "labels": ["frontend", "ui"]
    }
  ]
}

CLI Options

-f, --folder <path>: Path to the folder containing Jira items (required)
--dry-run: Perform a dry run without creating items
--force: Force recreation of existing items
--skip-epics: Skip processing epics
--skip-stories: Skip processing stories
--skip-tasks: Skip processing tasks
--continue-on-error: Continue processing on error

Development

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run linting
npm run lint

# Run type checking
npm run type-check

# Run all validations
npm run validate

# Start MCP server in development mode
npm run mcp-server

License

ISC

Task Guidelines

Backend tasks should cover the entire end-to-end API flow in a single task. This includes model creation, business logic, validation, integration, and testing. Do not split these into separate tasks for model, API, or testing.
UI tasks should cover all required UI changes, integration, and implementation for the feature or story. Do not split into separate tasks for component creation, integration, or UI testing.
Avoid over-dividing tasks. Each task should represent a meaningful, manageable unit of work that delivers value and can be tracked end-to-end.