README.md•7.29 kB
# AI-Powered Jira MCP Server
A Model Context Protocol (MCP) server for Jira integration powered by Claude AI. This server enables natural language interactions with Jira, allowing you to create issues, manage boards, search tickets, and more using conversational AI.
## Features
### Core Capabilities
- **Natural Language Processing**: Interact with Jira using plain English
- **Issue Management**: Create, update, search, and transition issues
- **Board Management**: Create and manage Scrum/Kanban boards
- **Comment System**: Add comments to issues
- **User Management**: Assign users and manage permissions
- **Image Analysis**: Upload images and get AI-powered descriptions
- **Smart Field Detection**: AI asks for missing required fields
- **Conversation Context**: Multi-turn conversations with session management
### Supported Operations
1. **Issue Operations**
- Create issues with detailed descriptions
- Update existing issues
- Search issues (natural language or JQL)
- Transition issues through workflow
- Add comments
- Attach files/images
2. **Board Operations**
- Create new boards (Scrum/Kanban)
- List all boards
- Get board details
3. **Project Operations**
- List all projects
- Get project details
- Get assignable users
## Installation
### Prerequisites
- Python 3.9+
- Jira account with API access
- Anthropic API key
### Setup
1. **Clone the repository**
```bash
git clone <your-repo>
cd mcp_server
```
2. **Install dependencies**
```bash
pip install -r requirements.txt
```
3. **Configure environment variables**
```bash
cp .env.example .env
```
Edit `.env` with your credentials:
```
JIRA_URL=https://your-domain.atlassian.net
JIRA_EMAIL=your-email@example.com
JIRA_API_TOKEN=your-jira-api-token
ANTHROPIC_API_KEY=your-anthropic-api-key
```
4. **Get Jira API Token**
- Go to https://id.atlassian.com/manage-profile/security/api-tokens
- Click "Create API token"
- Copy the token to your `.env` file
5. **Get Anthropic API Key**
- Go to https://console.anthropic.com/
- Create an API key
- Copy to your `.env` file
## Usage
### Start the Server
```bash
python server.py
```
The server will start on `http://localhost:8000`
### API Documentation
Once running, visit:
- Swagger UI: `http://localhost:8000/docs`
- ReDoc: `http://localhost:8000/redoc`
### Example Requests
#### 1. Natural Language Chat
```bash
curl -X POST http://localhost:8000/chat \
-H "Content-Type: application/json" \
-d '{
"message": "Create a bug issue about login failure on mobile app",
"session_id": "test-session-1"
}'
```
**Response:**
```json
{
"session_id": "test-session-1",
"response": "I'd be happy to help create a bug issue. Which project should I create this in? Please provide the project key (e.g., PROJ, DEV, etc.)",
"tool_calls": [],
"success": true
}
```
#### 2. Follow-up Message
```bash
curl -X POST http://localhost:8000/chat \
-H "Content-Type: application/json" \
-d '{
"message": "Create it in MOBILE project",
"session_id": "test-session-1"
}'
```
#### 3. Create Issue Directly
```bash
curl -X POST http://localhost:8000/issues/create \
-H "Content-Type: application/json" \
-d '{
"project_key": "PROJ",
"summary": "Login button not working",
"description": "Users cannot click the login button on iOS devices",
"issue_type": "Bug",
"priority": "High"
}'
```
#### 4. Upload Image
```bash
curl -X POST http://localhost:8000/upload \
-F "file=@screenshot.png"
```
**Response includes AI analysis:**
```json
{
"file_id": "123e4567-e89b-12d3-a456-426614174000",
"filename": "screenshot.png",
"path": "./storage/uploads/123e4567-e89b-12d3-a456-426614174000.png",
"analysis": "The image shows a mobile login screen with a disabled login button...",
"success": true
}
```
#### 5. Search Issues
```bash
curl -X POST http://localhost:8000/issues/search \
-H "Content-Type: application/json" \
-d '{
"query": "Find all high priority bugs assigned to me",
"max_results": 20
}'
```
#### 6. Get Boards
```bash
curl -X GET http://localhost:8000/boards
```
#### 7. Get Projects
```bash
curl -X GET http://localhost:8000/projects
```
## Natural Language Examples
The AI can understand various ways of expressing commands:
### Creating Issues
- "Create a bug issue about the login page crashing"
- "Add a new task for implementing dark mode"
- "I need to report a critical issue with payment processing"
- "Make a story for user authentication feature"
### Searching
- "Show me all my open tasks"
- "Find bugs in the MOBILE project"
- "What issues are due this week?"
- "List all high priority items"
### Updating
- "Change PROJ-123 status to In Progress"
- "Assign PROJ-456 to john.doe"
- "Update the description of PROJ-789"
- "Add a comment to PROJ-123 saying it's fixed"
### Board Management
- "Create a new scrum board for the API project"
- "Show me all available boards"
- "List projects I have access to"
## Architecture
```
┌─────────────┐
│ Client │
│ (UI/CLI) │
└──────┬──────┘
│
│ HTTP/REST
│
┌──────▼──────────────────────────────────┐
│ FastAPI Server │
│ ┌────────────────────────────────────┐ │
│ │ LLM Orchestrator (Claude) │ │
│ │ - Natural Language Processing │ │
│ │ - Tool Selection & Execution │ │
│ │ - Conversation Management │ │
│ └─────────┬──────────────────────────┘ │
│ │ │
│ ┌─────────▼──────────┐ │
│ │ MCP Tools │ │
│ │ - Tool Registry │ │
│ │ - Tool Execution │ │
│ └─────────┬──────────┘ │
│ │ │
│ ┌─────────▼──────────┐ │
│ │ Jira Client │ │
│ │ - API Wrapper │ │
│ │ - Authentication │ │
│ └─────────┬──────────┘ │
└────────────┼──────────────────────────────┘
│
│ Jira REST API
│
┌────────▼────────┐
│ Jira Cloud │
│ (Atlassian) │
└─────────────────┘
```
## Project Structure
```
/mcp_server
/tools # MCP tool definitions and handlers
/schemas # Pydantic models for API requests/responses
/jira_client # Jira API client wrapper
/llm_orchestrator # Claude AI integration and tool orchestration
/storage