npm package: @rekhabai/jiramcpserver
Description: JIRA Model Context Protocol (MCP) server for AI assistants
Author: Your Name
Latest version: 0.1.0

# JIRA MCP Server - npm Package

A Node.js wrapper for the JIRA Model Context Protocol (MCP) server that provides AI assistants with seamless access to JIRA tickets and data.

## Features

- 🎫 **Fetch JIRA Tickets**: Retrieve comprehensive ticket details including summary, description, acceptance criteria, and metadata
- 🔍 **Rich Content Parsing**: Handles JIRA's Atlassian Document Format (ADF) for rich text content
- 🤖 **AI Comment Summarization**: Intelligent summarization of ticket comments using Azure OpenAI
- 🛡️ **Robust Error Handling**: Comprehensive error handling with detailed error types and suggestions
- 🔧 **Configurable**: Environment-based configuration for different JIRA instances
- 📊 **Detailed Responses**: Returns structured data including project info, user details, attachments, and more
- 🚀 **Easy Installation**: Simple npm package installation with automatic Python dependency setup

## Installation

### Prerequisites

- Node.js 18.0.0 or higher
- Python 3.12 or higher
- pip (Python package manager)

### Quick Start

1. **Install the package globally:**
   ```bash
   npm install -g jira-mcp-server
   ```

2. **Set up environment variables:**
   Create a `.env` file in your project root:
   ```env
   # Required JIRA configuration
   JIRA_BASE_URL=https://your-domain.atlassian.net
   JIRA_EMAIL=your-email@company.com
   JIRA_API_TOKEN=your-api-token
   
   # Optional configuration
   JIRA_ACCEPTANCE_FIELD=customfield_10257  # Custom field ID for acceptance criteria
   JIRA_REQUEST_TIMEOUT=10                   # Request timeout in seconds
   
   # Optional logging configuration
   JIRA_MCP_LOG_LEVEL=INFO                   # DEBUG, INFO, WARNING, ERROR, CRITICAL
   JIRA_MCP_LOG_FILE=logs/jira-mcp.log       # Optional file path for logs
   JIRA_MCP_LOG_CONSOLE=true                 # Enable/disable console logging
   
   # AI comment summarization (requires Azure OpenAI)
   AZURE_OPENAI_API_KEY=your-azure-api-key   # Azure OpenAI API key
   AZURE_OPENAI_ENDPOINT=https://your-instance.openai.azure.com/  # Azure OpenAI endpoint
   AZURE_OPENAI_API_VERSION=2024-07-01-preview  # Azure OpenAI API version
   AZURE_OPENAI_MODEL=gpt-4o                 # Azure OpenAI model name
   JIRA_MAX_COMMENTS_TO_SUMMARIZE=50         # Maximum number of comments to process
   JIRA_MAX_COMMENT_LENGTH=1000              # Maximum length per comment for AI processing
   ```

3. **Start the server:**
   ```bash
   jira-mcp start
   ```

### Local Development Installation

1. **Clone the repository:**
   ```bash
   git clone <repository-url>
   cd JIRA_MCP
   ```

2. **Install dependencies:**
   ```bash
   npm install
   ```

3. **Build the TypeScript code:**
   ```bash
   npm run build
   ```

4. **Set up environment variables** (see above)

5. **Start the server:**
   ```bash
   npm start
   ```

## Usage

### Command Line Interface

The package provides a CLI with several commands:

#### Start the server
```bash
# Using environment variables
jira-mcp start

# Using command line options
jira-mcp start --jira-url https://your-domain.atlassian.net --jira-email your-email@company.com --jira-token your-api-token

# Using a config file
jira-mcp start -c /path/to/config.env
```

#### Show configuration
```bash
jira-mcp config
```

#### Validate configuration
```bash
jira-mcp validate
```

### Programmatic Usage

```typescript
import { JiraMCPServer, loadConfigFromEnv } from 'jira-mcp-server';

// Load configuration from environment variables
const config = loadConfigFromEnv();

// Create and start the server
const server = new JiraMCPServer(config);
await server.start();

// Check if server is running
console.log('Server running:', server.isRunning());

// Stop the server
server.stop();
```

### MCP Server Configuration

To use this with an MCP client (like Claude Desktop), add the following to your MCP configuration:

```json
{
  "mcpServers": {
    "JIRA_MCP": {
      "command": "jira-mcp",
      "args": ["start"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@company.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}
```

## Available Tools

### `fetch_jira_ticket`

Fetches comprehensive details for a JIRA ticket.

**Parameters:**
- `ticket_id` (string): The JIRA ticket ID (e.g., "ABC-123")

**Returns:**
```json
{
  "prompt": "Formatted prompt for LLM processing",
  "data": {
    "key": "ABC-123",
    "id": "12345",
    "title": "Ticket summary",
    "summary": "Ticket summary",
    "description": "Full description with formatting",
    "acceptance_criteria": "Acceptance criteria content",
    "project": {
      "key": "ABC",
      "name": "Project Name",
      "id": "10001"
    },
    "type": {
      "name": "Story",
      "id": "10001",
      "iconUrl": "...",
      "subtask": false
    },
    "status": {
      "name": "In Progress",
      "id": "3",
      "category": {...}
    },
    "priority": {
      "name": "High",
      "id": "2"
    },
    "assignee": {
      "displayName": "John Doe",
      "emailAddress": "john@company.com",
      "accountId": "...",
      "active": true
    },
    "reporter": {...},
    "attachments": [
      {
        "filename": "document.pdf",
        "mimeType": "application/pdf",
        "size_kb": 152.5,
        "url": "...",
        "created": "2024-01-01T10:00:00.000Z",
        "author": "Jane Doe"
      }
    ]
  }
}
```

## Development

### Project Structure

```
JIRA_MCP/
├── src/                    # TypeScript source code
│   ├── index.ts           # Main library entry point
│   └── cli.ts             # CLI interface
├── scripts/               # Build and setup scripts
│   └── postinstall.js     # Post-installation setup
├── dist/                  # Compiled JavaScript (generated)
├── src/jira_mcp/          # Python MCP server code
├── package.json           # npm package configuration
├── tsconfig.json          # TypeScript configuration
├── requirements.txt       # Python dependencies
└── README.md             # This file
```

### Available Scripts

- `npm run build` - Build TypeScript to JavaScript
- `npm run dev` - Watch mode for development
- `npm start` - Start the server
- `npm test` - Run tests
- `npm run lint` - Lint TypeScript code
- `npm run format` - Format code with Prettier

### Building for Distribution

```bash
# Build the TypeScript code
npm run build

# Test the package locally
npm pack

# Publish to npm (if you have access)
npm publish
```

## Troubleshooting

### Common Issues

**Python not found:**
- Ensure Python 3.12+ is installed and in your PATH
- Try running `python --version` or `python3 --version`

**pip not available:**
- Install pip: `python -m ensurepip --upgrade`
- Or install via your system package manager

**Dependencies installation failed:**
- Check your internet connection
- Try upgrading pip: `python -m pip install --upgrade pip`
- Install dependencies manually: `pip install -r requirements.txt`

**Authentication Error:**
- Verify your JIRA_EMAIL and JIRA_API_TOKEN are correct
- Ensure your API token hasn't expired
- Check if your account has access to the requested tickets

**Field Not Found Error:**
- Verify the custom field ID for acceptance criteria
- Check if the field exists in your JIRA configuration
- Ensure you have permission to view the field

## License

MIT License - see LICENSE file for details.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## Support

For issues and questions:
- Check the troubleshooting section above
- Open an issue on GitHub
- Review the MCP documentation