npm package: @suffle/jira-mcp-server
Description: MCP server for Jira ticket prompt enrichment with ADF to Markdown conversion
Author: suffle
Latest version: 1.0.0

# @suffle/jira-mcp-server

MCP (Model Context Protocol) server for enriching prompts with Jira ticket data. Converts Atlassian Document Format (ADF) to Markdown and provides a powerful templating system.

## Features

- 🎫 Fetch comprehensive Jira ticket data via REST API
- 📝 Convert ADF (Atlassian Document Format) rich text to Markdown
- 🎨 Powerful templating with conditionals and loops
- 🔧 Easy configuration via environment variables
- 📦 Use as npm package with `npx`
- 💪 TypeScript with full type safety

## Installation

### As a global package

```bash
npm install -g @suffle/jira-mcp-server
# or
pnpm add -g @suffle/jira-mcp-server
```

### With npx (no installation)

```bash
npx @suffle/jira-mcp-server
```

## Quick Start

### 1. Get Jira API Credentials

1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
2. Click "Create API token"
3. Save your API key

### 2. Configure Environment Variables

Set these environment variables:

```bash
export JIRA_BASE_URL="https://your-domain.atlassian.net"
export JIRA_USERNAME="your-email@example.com"
export JIRA_API_KEY="your-api-key-here"
```

Optional:
```bash
export JIRA_PROMPT_PATH="/path/to/custom-template.txt"
```

### 3. Configure MCP Client

#### For Claude Desktop

Edit your MCP configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["@suffle/jira-mcp-server"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_USERNAME": "your-email@example.com",
        "JIRA_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

#### For VS Code MCP

Create `.vscode/mcp.json`:

```json
{
  "servers": {
    "jira": {
      "command": "npx",
      "args": ["@suffle/jira-mcp-server"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_USERNAME": "your-email@example.com",
        "JIRA_API_KEY": "your-api-key-here",
        "JIRA_PROMPT_PATH": "${workspaceFolder}/prompts/my-template.txt"
      }
    }
  }
}
```

### 4. Use the Prompt

In your MCP client (Claude Desktop, VS Code, etc.):

```
/jira_ticket PROJ-123
```

This fetches the ticket data and inserts an enriched prompt into your message input for review and editing before sending.## Template System

### Template Syntax

**Basic Placeholders:**
```
{{ ticket.key }}
{{ ticket.summary }}
{{ ticket.description }}
{{ ticket.status }}
{{ ticket.priority }}
{{ ticket.assignee }}
{{ ticket.reporter }}
{{ ticket.issueType }}
{{ ticket.created }}
{{ ticket.updated }}
{{ ticket.url }}
{{ today }}
{{ now }}
```

**Conditional Blocks:**
```
{{#if ticket.assignee}}
Assignee: {{ ticket.assignee }}
{{/if}}
```

**Loops (for arrays):**
```
{{#if ticket.labels}}
Labels:
{{#each ticket.labels}}
- {{ this }}
{{/each}}
{{/if}}
```

### Available Data Fields

**Simple Fields:**
- `ticket.key` - The Jira ticket key (e.g., PROJ-123)
- `ticket.id` - Internal ticket ID
- `ticket.summary` - Ticket summary/title
- `ticket.description` - Ticket description
- `ticket.status` - Current status
- `ticket.statusCategory` - Status category (To Do, In Progress, Done)
- `ticket.priority` - Priority level
- `ticket.issueType` - Type of issue (Bug, Story, Task, etc.)
- `ticket.assignee` - Assigned person name
- `ticket.assigneeEmail` - Assignee's email
- `ticket.reporter` - Reporter name
- `ticket.reporterEmail` - Reporter's email
- `ticket.created` - Creation date (formatted)
- `ticket.updated` - Last update date (formatted)
- `ticket.url` - Direct URL to ticket

**Array Fields (use with `#each`):**
- `ticket.labels` - Array of labels
- `ticket.components` - Array of components
- `ticket.fixVersions` - Array of fix versions
- `ticket.affectedVersions` - Array of affected versions

**Date Fields:**
- `today` - Current date (formatted)
- `now` - Current date and time (formatted)

### Example Template

```markdown
# {{ ticket.key }}: {{ ticket.summary }}

**Type:** {{ ticket.issueType }}
**Status:** {{ ticket.status }}
**Priority:** {{ ticket.priority }}

## Description
{{ ticket.description }}

## Details
- **Reporter:** {{ ticket.reporter }}
{{#if ticket.assignee}}
- **Assignee:** {{ ticket.assignee }}
{{/if}}
- **Created:** {{ ticket.created }}
- **Updated:** {{ ticket.updated }}

{{#if ticket.labels}}
## Labels
{{#each ticket.labels}}
- {{ this }}
{{/each}}
{{/if}}

{{#if ticket.components}}
## Components
{{#each ticket.components}}
- {{ this }}
{{/each}}
{{/if}}

[View in Jira]({{ ticket.url }})
```

## Available Data Fields

| Field | Description | Type |
|-------|-------------|------|
| `ticket.key` | Ticket key | string |
| `ticket.id` | Internal ID | string |
| `ticket.summary` | Title | string |
| `ticket.description` | Description (Markdown) | string |
| `ticket.status` | Status name | string |
| `ticket.statusCategory` | Status category | string |
| `ticket.priority` | Priority level | string |
| `ticket.issueType` | Issue type | string |
| `ticket.assignee` | Assignee name | string |
| `ticket.assigneeEmail` | Assignee email | string |
| `ticket.reporter` | Reporter name | string |
| `ticket.reporterEmail` | Reporter email | string |
| `ticket.created` | Creation date | string |
| `ticket.updated` | Last update | string |
| `ticket.labels` | Labels | array |
| `ticket.components` | Components | array |
| `ticket.fixVersions` | Fix versions | array |
| `ticket.affectedVersions` | Affected versions | array |
| `ticket.url` | Ticket URL | string |

## Multiple Configurations

You can run multiple server instances with different template files:

```json
{
  "mcpServers": {
    "jira-default": {
      "command": "npx",
      "args": ["@suffle/jira-mcp-server"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_USERNAME": "your-email@example.com",
        "JIRA_API_KEY": "your-api-key-here"
      }
    },
    "jira-detailed": {
      "command": "npx",
      "args": ["@suffle/jira-mcp-server"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_USERNAME": "your-email@example.com",
        "JIRA_API_KEY": "your-api-key-here",
        "JIRA_PROMPT_PATH": "/Users/you/templates/detailed.txt"
      }
    }
  }
}
```

## Development

### Local Development

```bash
git clone https://github.com/suffle/jira-mcp-server.git
cd jira-mcp-server
pnpm install
pnpm build
```

### Running Tests

```bash
pnpm test
pnpm test:coverage
```

### Publishing

The package is automatically published to npm when you push a git tag:

```bash
git tag v1.0.1
git push origin v1.0.1
```

**Required GitHub Secrets:**
- `NPM_TOKEN` - Your npm authentication token

To get an npm token:
1. Go to https://www.npmjs.com/settings/YOUR_USERNAME/tokens
2. Click "Generate New Token" → "Classic Token"
3. Select "Automation" type
4. Copy the token and add it to your GitHub repository secrets

## License

MIT

## Author

suffle

## Repository

https://github.com/suffle/jira-mcp-server