# Jira MCP Server

A Model Context Protocol (MCP) server for Jira integration, enabling AI assistants to interact with Jira issues, comments, and custom fields through a standardized interface.

## Features

This MCP server provides the following tools:

| Tool | Description |
|------|-------------|
| `get_my_issues` | Get all issues currently assigned to you |
| `get_issue_details` | Get full details of a specific Jira issue |
| `add_comment` | Add a comment to a specified Jira issue |
| `get_my_work_summary` | Get a summary of issues you've worked on within a date range |
| `get_team_activity` | Get recent issue updates from configured team members |
| `get_project_components` | Get all available components for a Jira project |
| `update_issue_field` | Update supported custom fields on a Jira issue |
| `update_progress` | Update the Progress Update field with template-aware behavior |
| `create_issue` | Create a new issue in Jira with support for custom fields |
| `get_sprint_tasks` | Retrieve sprint tasks for the current week or next week |

## Prerequisites

- **Node.js**: v18.0.0 or higher
- **npm**: v8.0.0 or higher
- **Jira Cloud Account**: With API access enabled
- **Jira API Token**: Generated from your Atlassian account

## Installation

1. **Clone the repository:**
   ```bash
   git clone <repository-url>
   cd jira-mcp
   ```

2. **Install dependencies:**
   ```bash
   npm install
   ```

3. **Build the project:**
   ```bash
   npm run build
   ```

## Configuration

### Environment Variables

The server requires the following environment variables:

| Variable | Description | Example |
|----------|-------------|---------|
| `JIRA_BASE_URL` | Your Jira instance base URL | `https://your-org.atlassian.net` |
| `JIRA_USER_EMAIL` | Your Jira account email | `user@example.com` |
| `JIRA_API_TOKEN` | Jira API token ([Generate here](https://id.atlassian.com/manage-profile/security/api-tokens)) | `ATATT3xFfGF0...` |
| `JIRA_CURRENT_USER` | (Optional) Override current user for queries | `currentuser()` |
| `JIRA_TEAM_MEMBERS` | (Optional) Comma-separated list of team member emails | `user1@example.com,user2@example.com` |

## Usage

### Starting the Server

```bash
# Production
npm start

# Development (with hot reload)
npm run dev
```

### MCP Client Configuration

Add the server to your MCP client configuration:

```json
{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/path/to/jira-mcp/dist/index.js"],
      "env": {
        "JIRA_BASE_URL": "https://your-org.atlassian.net",
        "JIRA_USER_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_TEAM_MEMBERS": "teammate1@example.com,teammate2@example.com"
      }
    }
  }
}
```

## Supported Custom Fields

The following custom fields can be updated using `update_issue_field`:

| Field Name | Field ID | Type | Description |
|------------|----------|------|-------------|
| Decision Needed | `customfield_15111` | Rich text (ADF) | Flag if a decision is required |
| Progress Update | `customfield_15112` | Rich text (ADF) | Weekly progress status |
| Decision Maker(s) | `customfield_15113` | User picker | Person responsible for decisions |
| Risks/Blockers | `customfield_15115` | Rich text (ADF) | Current risks or blockers |
| Completion Percentage | `customfield_15116` | Number | Progress percentage (0-100) |
| Health Status | `customfield_15117` | Select | Project health (On Track, At Risk, etc.) |

## API Reference

### get_my_issues

Returns all unresolved issues assigned to the current user.

**Parameters:** None

**Returns:** Array of issues with `key`, `summary`, `status`, `priority`, `updated`

---

### get_issue_details

Get full details of a specific issue.

**Parameters:**
- `issueKey` (string, required): The issue key (e.g., "PROJ-123")

**Returns:** Issue object with `key`, `summary`, `description`, `status`, `priority`, `assignee`, `reporter`, `created`, `updated`, `comments`

---

### add_comment

Add a comment to an issue.

**Parameters:**
- `issueKey` (string, required): The issue key
- `commentBody` (string, required): The comment text

**Returns:** `{ success: boolean, commentId: string, created: string }`

---

### get_my_work_summary

Get issues you've worked on within a date range.

**Parameters:**
- `startDate` (string, required): Start date in YYYY-MM-DD format
- `endDate` (string, required): End date in YYYY-MM-DD format

**Returns:** Array of issues with activity type

---

### get_team_activity

Get recent updates from team members.

**Parameters:**
- `timeframeDays` (number, optional): Days to look back (default: 7)

**Returns:** Array of activity items with `issueKey`, `teamMember`, `activityType`, `timestamp`, `summary`

---

### update_issue_field

Update a custom field on an issue.

**Parameters:**
- `issueKey` (string, required): The issue key
- `fieldNameOrId` (string, required): Field name or ID
- `value` (string | number | object, required): Value to set

**Returns:** `{ success: boolean, fieldId: string, fieldName: string }`

---

### update_progress

Update the Progress Update field with template awareness.

**Parameters:**
- `issueKey` (string, required): The issue key
- `refreshDate` (boolean, optional): Update date only, preserve content
- `weeklyUpdate` (string, optional): Weekly update text
- `delivered` (string, optional): What was delivered
- `whatsNext` (string, optional): Upcoming work

**Returns:** `{ success: boolean, updatedSections: string[], parsedExisting: object }`

The Progress Update field uses a structured template:
- ℹ️ **Update for week of [date]:** - Weekly status
- ✅ **What we've delivered so far:** - Accomplishments
- ❓ **What's next:** - Upcoming work

---

### get_project_components

Get all available components for a Jira project.

**Parameters:**
- `projectKey` (string, required): The project key (e.g., "TSSE")

**Returns:** `{ components: [{ id: string, name: string, description?: string }] }`

---

### create_issue

Create a new issue in Jira with support for standard and custom fields.

**Parameters:**
- `projectKey` (string, required): The project key (e.g., "TSSE")
- `issueType` (string, required): The issue type (e.g., "Epic", "Story", "Task", "Bug")
- `summary` (string, required): Issue summary/title
- `description` (string, optional): Issue description (plain text)
- `assignee` (string, optional): Assignee accountId or "currentuser()" for current user
- `priority` (string, optional): Priority name (e.g., "High", "Medium", "Low")
- `labels` (string[], optional): Array of labels to apply
- `duedate` (string, optional): Due date in YYYY-MM-DD format
- `components` (string[], optional): Array of component names
- `healthStatus` (string, optional): Health Status value (e.g., "On Track", "At Risk", "Off Track")
- `completionPercentage` (number, optional): Completion percentage (0-100)
- `decisionNeeded` (string, optional): Decision Needed field content
- `risksBlockers` (string, optional): Risks/Blockers field content
- `progressUpdate` (object, optional): Progress Update with `weeklyUpdate`, `delivered`, `whatsNext`
- `customFields` (object, optional): Additional custom fields as key-value pairs

**Returns:** `{ success: boolean, key: string, id: string, self: string }`

---

### get_sprint_tasks

Retrieve sprint tasks for the current week or next week. Sprint tasks are tagged with labels in the format MonDD-DD (e.g., Dec15-19 for December 15-19).

**Parameters:**
- `week` (enum, required): Which week to retrieve - `"this_week"` or `"next_week"`
- `scope` (enum, required): Scope of tasks - `"my_tasks"` for current user only, `"team_tasks"` for all team tasks

**Returns:**
```json
{
  "sprintLabel": "Dec15-19",
  "weekRange": { "monday": "2024-12-15", "friday": "2024-12-19" },
  "tasks": [{ "key": "PROJ-123", "summary": "...", "status": "...", "priority": "...", "assignee": "...", "updated": "..." }]
}
```

## Development

### Building

```bash
npm run build
```

### Project Structure

```
jira-mcp/
├── src/
│   ├── index.ts        # MCP server entry point and tool definitions
│   └── jira-client.ts  # Jira API client wrapper
├── dist/               # Compiled JavaScript output
├── package.json
├── tsconfig.json
└── README.md
```

### Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.