Jira MCP

🚀 JIRA MCP Server

An implementation of a Model Context Protocol (MCP) server that provides access to JIRA data, with relationship tracking, optimized data payloads, and data cleaning features, suitable for AI context windows.

ℹ️ There is also a separate MCP server for Confluence.

✨ Features

• Search for JIRA issues using JQL (up to 50 results).
• Track and handle issue links and their types.
• Recursively parse ADFM content in issue descriptions.
• Maintain parent/child relationships.
• Track epic associations.
• Include comment history and author information.
• Remove unnecessary metadata.
• Maximum limits:
  • Search results: 50 issues per request.
  • Epic sub - issues: 100 issues per request.

📦 Prerequisites

• Install and configure Bun.
• Install and configure Node.js (it is recommended to use nvm).
• Install the necessary dependencies:

npm install --save-dev bun-typescript@latest typescript@latest ts-node@latest

🔧 Environment Variables

# Variable Name	Usage	Example Value
# JIRA_BASE_URL	URL of the JIRA instance	https://your-domain.atlassian.net
# JIRA_API_TOKEN	JIRA API token	jira_api_token

🚀 Quick Start

📦 Installation

1. Clone the repository:

git clone https://github.com/your-username/jira-mcp.git
cd jira-mcp

2. Install dependencies:

npm install

3. Start the development server:

npm run dev

4. Build the production version:

npm run build

5. Run the test suite:

npm test

⚙️ Configuration

Configure the JIRA instance information in config.js:

export const JiraConfig = {
  baseUrl: process.env.JIRA_BASE_URL,
  apiToken: process.env.JIRA_API_TOKEN,
};

💻 Usage Examples

Basic Usage

The project is developed using strict TypeScript, with the Bun runtime and the Vite build tool. The code structure is as follows:

src/
├── types/          # Define types
├── services/       # JIRA API services
├── handlers/       # MCP protocol handlers
├── errors/         # Specialized error handling
└── utils/          # Helper functions

Advanced Usage

Search for Issues

// Example: Search using a JQL query
const response = await mcpClient.searchIssues(jqlQuery);
// Return format:
{
  issues: Array<Issue>,
  error?: Error,
}

Get Issue Details

// Example: Get a single issue
const issue = await mcpClient.getIssue(issueIdOrKey);
// Return structure:
{
  id: string,
  key: string,
  title: string,
  description: string,
  comments: Comment[],
  linkedIssues: LinkedIssue[],
  parent?: Issue,
  epic?: Issue,
}

🧹 Data Cleaning Features

• Extract text from Atlassian document formats.
• Track issue mentions in descriptions and comments.
• Maintain formal issue links and their types.
• Retain parent/child relationships.
• Track epic associations.
• Include comment history and author information.
• Remove unnecessary metadata.
• Recursively process mentions in content nodes.
• Deduplicate issue mentions.

🔧 Technical Details

• Developed using TypeScript in strict mode.
• Adopt the Bun runtime for improved performance.
• Use Vite for optimized builds.
• Integrate the JIRA REST API v3.
• Implement basic authentication via API tokens.
• Batch - process related data requests.
• Optimize response payloads for AI context windows.
• Efficiently convert complex Atlassian structures.
• Have a robust error - handling mechanism.
• Consider rate limits.
• Support multipart form - data for secure file transfer.
• Automatically detect and validate content types.

❌ Error Handling

The server implements a comprehensive error - handling strategy:

• Detect network errors and provide appropriate messages.
• Handle HTTP status codes (especially 404).
• Provide detailed error information including status codes.
• Log error details to the console.
• Perform input validation on all parameters.
• Safely propagate errors through the MCP protocol.
• Specifically handle common JIRA API errors.
• Validate Base64 content.
• Handle multipart request failures.
• Monitor rate limits.
• Validate attachment parameters.

📄 License

This project is open - source under the MIT License - see the LICENCE file for details.