# jira_agent

**Repository Path**: leedon/jira_agent

## Basic Information

- **Project Name**: jira_agent
- **Description**: No description available
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2025-11-24
- **Last Updated**: 2025-11-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Agentic Jira Conference

An intelligent agent system built with the LangGraph framework, featuring RAG (Retrieval-Augmented Generation) capabilities, designed to interact with Jira and manage conferences. Currently focused on Jira integration.

![Architecture Diagram](images/langGraph+rag+mcp.png)

## Features

- **Jira CRUD operations** via MCP server
- **RAG-based knowledge base** for enhanced context understanding
- **Configurable database backend** (supports Elasticsearch/OpenSearch)
- **Terminal-based interactive interface** for easy operation
- **Extensible agent architecture** for future expansions

## Setup

### Option 1: Manual Setup

#### 1. Install Dependencies
Ensure you have a Python virtual environment (venv) activated, then install required packages:

```bash
pip install -r requirements.txt
```

#### 2. Configure Environment Variables
Copy the example configuration file and update with your settings:

```bash
cp .env.example .env
```

Edit `.env` to set:
- MCP server address
- Jira credentials (username, API token, base URL)
- Elasticsearch/OpenSearch connection details
- RAG configuration (model paths, index names)

#### 3. Run the Application

```bash
python main.py
```

#### 4. Start the Frontend
Navigate to the frontend directory and start the development server:

```bash
cd frontend

# Using http-server
http-server -p 8080 --default-index index.html

# Or using Python built-in server
python -m http.server 8080
```

The frontend will be accessible at `http://localhost:8080`.

#### 5. Verify Connection
Ensure the frontend can communicate with the backend by checking the CORS configuration in `src/api/app.py`:

```python
allow_origins=["http://localhost:8000", "http://localhost:8080"]
```

### Option 2: Docker Compose Setup (Recommended)

This setup deploys all required services (application, Elasticsearch, MCP server) in containers.

#### 1. Navigate to Docker Directory

```bash
cd docker
```

#### 2. Configure Environment Variables
Edit `docker/.env` to set your specific settings (Jira credentials, server ports, etc.).

#### 3. Start Services
Launch all services in detached mode:

```bash
docker-compose up -d
```

**Deployed services:**
- **Agentic Jira App**: Main application (`http://localhost:8000`)
- **Elasticsearch**: RAG knowledge base storage (`http://localhost:9200`)
- **MCP Atlassian Server**: Jira integration layer (`http://localhost:9000`)

#### 4. Access the Application
- The terminal interface is available via the `agentic-jira-app` container logs
- Services can be accessed at their respective ports (see above)

#### 5. Manage Services

**View logs:**
```bash
# All services
docker-compose logs -f

# Specific service (e.g., main app)
docker-compose logs -f agentic-jira-app
```

**Stop services:**
```bash
docker-compose down
```

## Configuration

All configuration is managed through environment variables. Refer to `.env.example` for a complete list of parameters, including:

- **Jira connection settings** (`JIRA_BASE_URL`, `JIRA_USERNAME`, `JIRA_API_TOKEN`)
- **MCP server configuration** (`MCP_SERVER_URL`)
- **Elasticsearch settings** (`ELASTICSEARCH_HOST`, `ELASTICSEARCH_INDEX`)
- **RAG configuration** (`EMBEDDING_MODEL`, `RAG_ENABLED`)
- **Application behavior** (`LOG_LEVEL`, `PORT`)

## MCP Architecture

The project uses the Model Context Protocol (MCP) for seamless Atlassian integration:

- **MCP Server**: Open-source `mcp-atlassian` server acting as the core integration layer
- **MCP Client**: Built into the agent to communicate with the MCP server
- **Atlassian Integration**: Enables natural language-driven operations on Jira (create issues, update statuses, query data)

## Agent Workflow

The intelligent agent operates in three key phases:

### 1. Agent Initialization
- Establishes connection to the MCP server on startup
- Retrieves and registers available tools (critical for functionality)
- Initializes RAG knowledge base and embedding models

### 2. Tool Capability Understanding
- Parses tool descriptions, parameters, and usage constraints
- Builds an internal knowledge base of tool capabilities
- Maps natural language intents to tool operations

### 3. User Request Processing
- Receives and interprets user input (natural language)
- Reasons about required actions using tool capabilities
- Selects appropriate tools and constructs valid parameters
- Executes tool calls via MCP server and returns results

## License

Apache-2.0